diff --git a/scripts/m8_procedure_package.py b/scripts/m8_procedure_package.py new file mode 100644 index 00000000..0ff72ccf --- /dev/null +++ b/scripts/m8_procedure_package.py @@ -0,0 +1,342 @@ +"""Assemble a reviewed M8 operator procedure into exact step files; never run them. + +A procedure document declares its composition in one TOML block under a heading +named ``Composition``. Steps are built from named fenced blocks, never copied by +hand:: + + labels = {current = ["g11", "q12"], historical = ["g10", "q11"]} + + [sources.oc] # a frozen document, pinned by SHA-256 + path = "M8-N4-operator-commands.md" + sha256 = "..." + + [[steps]] + name = "c3-qualification" + stdout = ["lane-boundary-checked"] # the step's exact declared stdout lines + historical = false # may this step name historical labels? + parts = [ + {literal = "C=..."}, + {source = "oc", heading = "Setup: fixed controller and evidence checks", fences = [0, 1]}, + {source = "lane", heading = "L1: qualification boundary", fences = [0]}, + ] + +``self`` is the procedure document itself, pinned by ``docs/plans/MANIFEST.sha256``. +Usage, with isolated Python from the repository root:: + + python -I -S -B scripts/m8_procedure_package.py check DOC [--template] + python -I -S -B scripts/m8_procedure_package.py build DOC OUT [--template] + +``build`` writes ``.sh`` and ``.stdout`` (LF only) and ``MANIFEST.sha256`` +(``sha256sum --check`` format) into ``OUT``, which it claims with an exclusive +``mkdir``. The manifest is written last, so a package without one is incomplete. It +prints the manifest's own SHA-256 and refuses, +naming the step, and never guesses or repairs: + +- **schema:** unknown keys, wrong types, empty parts or selections, a part that + is not exactly a literal or exactly a fence selection; +- **sources:** a changed pin, a CRLF source, an absent or repeated heading, a + missing fence, a fence that is not ``bash``; +- **lane boundary (#210):** text naming the lane CLI array (``LANE``) unless it + comes from an allowlisted, reviewed lane-boundary block; literals never may; +- **labels:** an undeclared generation/session label, or a historical one in a + step not marked historical. This is a spelling check, not proof of fresh paths; +- **placeholders:** ``UNREVIEWED`` or ``UNPREPARED`` (other than the + ``UNPREPARED.bundle`` sentinel) in any shell spelling, unless ``--template``; +- **bytes:** any CR in a built file, a declared stdout over 65,536 bytes. +""" + +from __future__ import annotations + +import hashlib +import re +import sys +import tomllib +from dataclasses import dataclass +from pathlib import Path + +HEADING = re.compile(r"^(?P#{1,6}) (?P.+?)[ \t]*$") +OPEN_FENCE = re.compile(r"^(?P<indent> {0,3})(?P<ticks>`{3,})(?P<lang>[A-Za-z]*)[ \t]*$") +LABEL = re.compile(r"(?<![0-9A-Za-z])[gq][0-9]{1,3}(?![0-9A-Za-z])") +# Matched after removing quotes, backslashes and `$`, so ordinary shell +# concatenation and escaping ($'X', "UNRE""VIEWED", UNRE\VIEWED) cannot hide a +# placeholder or a label. The exact `UNPREPARED.bundle` refusal sentinel is a +# comparison target, not a value. These lints catch honest composition mistakes +# in reviewed documents; deliberate obfuscation (ANSI-C hex escapes, eval, +# indirection) is the review's job, not a shell interpreter's here. +PLACEHOLDER = re.compile(r"\bUNREVIEWED\b|\bUNPREPARED\b(?!\.bundle(?:$|[\s;)|&]))", + re.MULTILINE) +SHELL_QUOTING = re.compile(r"[\"'\\$]") +LANE_NAME = re.compile(r"\bLANE\b") +NAME = re.compile(r"[a-z0-9][a-z0-9-]{0,62}") +MAX_STDOUT = 65_536 +# The only reviewed blocks that may name the lane CLI. Startup boundaries are +# wrapped by lane_capture (#210 L1-L3); OC Setup defines the array, S1 prepare +# prints a declared record, and S6a discards its held lane's output then checks +# `wait` and its evidence. +LANE_BLOCKS = { + ("M8-maintenance-lane-output.md", "L1: qualification boundary"), + ("M8-maintenance-lane-output.md", "L2: H7 controls"), + ("M8-maintenance-lane-output.md", "L3: explicit refresh"), + ("M8-N4-operator-commands.md", "Setup: fixed controller and evidence checks"), + ("M8-N4-operator-commands.md", "S1. Prepare"), + ("M8-N4-operator-commands.md", "S6a. Maintenance-lock positive control"), +} +TOP_KEYS = {"labels", "sources", "steps"} +STEP_KEYS = {"name", "stdout", "historical", "parts"} + + +class Refused(ValueError): + """The composition is not exactly reviewable; nothing is written.""" + + +@dataclass(frozen=True) +class Fence: + lang: str + body: str + start: int + end: int + + +@dataclass(frozen=True) +class Step: + name: str + text: str + stdout: tuple[str, ...] + + +def fence_blocks(document: str) -> list[Fence]: + """CommonMark-style backtick fences: up to three spaces of indent, a closing + run at least as long as the opening and nothing after it.""" + lines = document.splitlines(keepends=True) + starts = [0] + for line in lines: + starts.append(starts[-1] + len(line)) + blocks, index = [], 0 + while index < len(lines): + opening = OPEN_FENCE.match(lines[index].rstrip("\n")) + if opening is None: + index += 1 + continue + indent, ticks = len(opening["indent"]), len(opening["ticks"]) + closer = re.compile(rf"^ {{0,3}}`{{{ticks},}}[ \t]*$") + body, cursor = [], index + 1 + while cursor < len(lines) and not closer.match(lines[cursor].rstrip("\n")): + line = lines[cursor] + body.append(line[min(indent, len(line) - len(line.lstrip(" "))):]) + cursor += 1 + if cursor == len(lines): + raise Refused("a fenced block is never closed") + blocks.append(Fence(opening["lang"], "".join(body), starts[index], starts[cursor + 1])) + index = cursor + 1 + return blocks + + +@dataclass(frozen=True) +class Heading: + start: int # the heading line's first character + end: int # just after the heading line + level: int + title: str + + +def headings(document: str) -> list[Heading]: + """Markdown headings, never a ``# comment`` line inside a fenced block.""" + spans = [(block.start, block.end) for block in fence_blocks(document)] + found, offset = [], 0 + for line in document.splitlines(keepends=True): + match = HEADING.match(line.rstrip("\n")) + if match and not any(start <= offset < end for start, end in spans): + found.append(Heading(offset, offset + len(line), len(match["level"]), + match["title"])) + offset += len(line) + return found + + +def section(document: str, title: str) -> str: + """The text under exactly one heading named ``title``, to the next heading at + the same or a higher level.""" + found = headings(document) + matches = [heading for heading in found if heading.title == title] + if len(matches) != 1: + raise Refused(f"heading {title!r} occurs {len(matches)} times") + chosen = matches[0] + following = (heading.start for heading in found + if heading.start > chosen.start and heading.level <= chosen.level) + return document[chosen.end:next(following, len(document))] + + +def fences(text: str) -> list[tuple[str, str]]: + return [(block.lang, block.body) for block in fence_blocks(text)] + + +def composition(document: str) -> dict: + blocks = [body for lang, body in fences(section(document, "Composition")) if lang == "toml"] + if len(blocks) != 1: + raise Refused("the Composition section needs exactly one toml block") + try: + spec = tomllib.loads(blocks[0]) + except tomllib.TOMLDecodeError as error: + raise Refused(f"composition is not valid TOML: {error}") from None + if not set(spec) <= TOP_KEYS: + raise Refused(f"unknown composition keys {sorted(set(spec) - TOP_KEYS)}") + return spec + + +def _strings(value: object, what: str) -> list[str]: + if not isinstance(value, list) or not all(isinstance(item, str) for item in value): + raise Refused(f"{what} must be a list of strings") + return value + + +def _part(name: str, part: object, sources: dict, paths: dict) -> tuple[str, str | None]: + """(text, allowlist key or None) for one part, after strict shape checks.""" + if not isinstance(part, dict): + raise Refused(f"step {name}: a part must be a table") + if set(part) == {"literal"} and isinstance(part["literal"], str): + literal = part["literal"] + if not literal.strip(): + raise Refused(f"step {name}: a literal part is empty") + # Exact bytes: only a missing final newline is supplied. + return literal if literal.endswith("\n") else literal + "\n", None + if set(part) != {"source", "heading", "fences"}: + raise Refused(f"step {name}: a part is exactly a literal or a fence selection") + source, heading, selected = part["source"], part["heading"], part["fences"] + if not isinstance(source, str) or source not in sources or not isinstance(heading, str): + raise Refused(f"step {name}: unknown source {source!r}") + if not isinstance(selected, list) or not selected or not all( + type(index) is int for index in selected): + raise Refused(f"step {name}: fences must be a non-empty list of integers") + found = fences(section(sources[source], heading)) + text = [] + for index in selected: + if not 0 <= index < len(found): + raise Refused(f"step {name}: {heading!r} has no fence {index}") + lang, body = found[index] + if lang != "bash": + raise Refused(f"step {name}: {heading!r} fence {index} is not bash") + if not body.strip(): + raise Refused(f"step {name}: {heading!r} fence {index} is empty") + text.append(body) + return "".join(text), (paths[source], heading) + + +def assemble(path: Path, template: bool = False) -> list[Step]: + # Raw bytes: text-mode reading would silently translate CRLF and hide it. + document = path.read_bytes().decode("utf-8") + if "\r" in document: + raise Refused("the procedure document is not LF-only") + spec = composition(document) + sources, paths = {"self": document}, {"self": path.name} + declared = spec.get("sources", {}) + if not isinstance(declared, dict): + raise Refused("sources must be a table") + for key, source in declared.items(): + if (not isinstance(source, dict) or set(source) != {"path", "sha256"} + or not all(isinstance(source[field], str) for field in ("path", "sha256")) + or key == "self"): + raise Refused(f"source {key} needs exactly a string path and sha256") + raw = (path.parent / source["path"]).read_bytes() + if hashlib.sha256(raw).hexdigest() != source["sha256"]: + raise Refused(f"source {key} does not match its pinned SHA-256") + if b"\r" in raw: + raise Refused(f"source {key} is not LF-only") + # Only a sibling of the procedure (a bare file name) can be an allowlisted + # reviewed source; a pinned copy elsewhere never matches the allowlist. + bare = Path(source["path"]).name == source["path"] + sources[key], paths[key] = raw.decode("utf-8"), source["path"] if bare else None + labels = spec.get("labels", {}) + if not isinstance(labels, dict) or not set(labels) <= {"current", "historical"}: + raise Refused("labels has only current and historical lists") + current = set(_strings(labels.get("current", []), "labels.current")) + historical_labels = set(_strings(labels.get("historical", []), "labels.historical")) + if current & historical_labels: + raise Refused(f"labels {sorted(current & historical_labels)} are both current " + "and historical") + steps, names = [], set() + declared_steps = spec.get("steps", []) + if not isinstance(declared_steps, list): + raise Refused("steps must be a list of tables") + for entry in declared_steps: + if not isinstance(entry, dict) or not set(entry) <= STEP_KEYS or not { + "name", "stdout", "parts"} <= set(entry): + raise Refused("a step has exactly name, stdout, parts and optional historical") + name = entry["name"] + if not isinstance(name, str) or not NAME.fullmatch(name) or name in names: + raise Refused(f"step name {name!r} is invalid or repeated") + names.add(name) + historical = entry.get("historical", False) + if type(historical) is not bool: + raise Refused(f"step {name}: historical must be a boolean") + parts = entry["parts"] + if not isinstance(parts, list) or not parts: + raise Refused(f"step {name}: parts must be a non-empty list") + pieces = [] + for part in parts: + text, origin = _part(name, part, sources, paths) + if LANE_NAME.search(text.replace("\\\n", "")) and origin not in LANE_BLOCKS: + raise Refused(f"step {name}: only a reviewed lane-boundary block may name " + "the lane CLI (#210 lane-output contract)") + pieces.append(text) + text = "".join(pieces) + allowed = current | (historical_labels if historical else set()) + # Bash joins continued lines and adjacent quoted fragments into one word. + joined = SHELL_QUOTING.sub("", text.replace("\\\n", "")) + stray = sorted({label for label in LABEL.findall(joined) if label not in allowed}) + if stray: + raise Refused(f"step {name}: undeclared or historical labels {stray}") + if not template and PLACEHOLDER.search(joined): + raise Refused(f"step {name}: an unreviewed placeholder remains") + stdout = tuple(_strings(entry["stdout"], f"step {name}: stdout")) + rendered = "".join(line + "\n" for line in stdout) + if any("\n" in line or "\r" in line for line in stdout) or "\r" in text: + raise Refused(f"step {name}: a built file would not be LF-only") + if len(rendered.encode("utf-8")) > MAX_STDOUT: + raise Refused(f"step {name}: declared stdout exceeds {MAX_STDOUT} bytes") + steps.append(Step(name, text, stdout)) + if not steps: + raise Refused("the composition declares no steps") + return steps + + +def build(path: Path, out: Path, template: bool = False) -> str: + steps = assemble(path, template) + try: + out.mkdir() # an exclusive claim: refuses an existing path, never replaces one + except FileExistsError: + raise Refused("the output directory already exists") from None + lines = [] + for step in steps: + for suffix, body in ((".sh", step.text), + (".stdout", "".join(line + "\n" for line in step.stdout))): + raw = body.encode("utf-8") + with open(out / (step.name + suffix), "xb") as stream: + stream.write(raw) + lines.append(f"{hashlib.sha256(raw).hexdigest()} {step.name}{suffix}\n") + manifest = "".join(lines).encode("utf-8") + # Written last: a package without its manifest is visibly incomplete. + with open(out / "MANIFEST.sha256", "xb") as stream: + stream.write(manifest) + return hashlib.sha256(manifest).hexdigest() + + +def main(argv: list[str]) -> int: + try: + arguments = argv[1:] + template = arguments[-1:] == ["--template"] + if template: + arguments = arguments[:-1] + if arguments[:1] == ["check"] and len(arguments) == 2: + steps = assemble(Path(arguments[1]), template) + print(f"composition-checked {len(steps)} steps") + elif arguments[:1] == ["build"] and len(arguments) == 3: + print(build(Path(arguments[1]), Path(arguments[2]), template)) + else: + raise Refused("usage: check DOC [--template] | build DOC OUT [--template]") + except (Refused, OSError, UnicodeDecodeError) as error: + print(f"composition refused: {error}", file=sys.stderr) + return 1 + return 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv)) diff --git a/tests/test_m8_procedure_package.py b/tests/test_m8_procedure_package.py new file mode 100644 index 00000000..1f6d0600 --- /dev/null +++ b/tests/test_m8_procedure_package.py @@ -0,0 +1,395 @@ +"""The procedure packager: exact assembly, pinned sources, and refusals that name the step.""" + +from __future__ import annotations + +import hashlib +import shutil +import subprocess +import sys +from pathlib import Path + +import pytest +from scripts import m8_procedure_package as package + +HANDOFFS = Path(__file__).parents[1] / "docs" / "plans" / "handoffs" +REAL_LANE_BLOCKS = package.LANE_BLOCKS +FROZEN = """# Frozen + +## Setup + +```bash +set -Eeuo pipefail +LANE=(python lane) +``` + +### S4. Qualification + +```bash +"${ROOT_STORE[@]}" maintain -- \\ + "${LANE[@]}" startup --evidence "$W/s4.json" < /dev/null +``` + +### S6a. Held + +```bash +"${ROOT_STORE[@]}" maintain -- \\ + "${LANE[@]}" startup --hold 90 \\ + < /dev/null > /dev/null 2> /dev/null & +wait "$H" +``` + +### Notes + +```text +not a command +``` +""" +SELF_BLOCKS = """## L1: qualification boundary + +```bash +lane_capture "$LANES/s4" "${ROOT_STORE[@]}" maintain -- \\ + "${LANE[@]}" startup --evidence "$W/s4.json" +``` + +## Unreviewed + +```bash +lane_capture "$OUT" true; "${LANE[@]}" startup +``` + +## Split + +```bash +"${LA\\ +NE[@]}" startup +``` +""" + + +@pytest.fixture(autouse=True) +def fixture_allowlist(monkeypatch): + monkeypatch.setattr(package, "LANE_BLOCKS", { + ("procedure.md", "L1: qualification boundary"), + ("frozen.md", "Setup"), ("frozen.md", "S6a. Held"), + }) + + +def procedure(tmp_path: Path, steps: str, frozen: str = FROZEN, extra: str = "") -> Path: + (tmp_path / "frozen.md").write_bytes(frozen.encode()) + digest = hashlib.sha256(frozen.encode()).hexdigest() + document = f"""# Procedure + +{SELF_BLOCKS} +## Composition + +```toml +labels = {{current = ["g11", "q12"], historical = ["g10", "q11"]}} +{extra} +[sources.oc] +path = "frozen.md" +sha256 = "{digest}" +{steps} +``` +""" + path = tmp_path / "procedure.md" + path.write_bytes(document.encode()) + return path + + +QUALIFICATION = """ +[[steps]] +name = "c3-qualification" +stdout = ["lane-boundary-checked"] +parts = [ + {literal = "W=/home/m8-service/m8-maint-q12"}, + {source = "oc", heading = "Setup", fences = [0]}, + {source = "self", heading = "L1: qualification boundary", fences = [0]}, + {source = "oc", heading = "S6a. Held", fences = [0]}, +] +""" + + +def test_build_writes_exact_step_bytes_and_a_manifest_atomically(tmp_path): + out = tmp_path / "package" + digest = package.build(procedure(tmp_path, QUALIFICATION), out) + script = (out / "c3-qualification.sh").read_bytes().decode() + assert script.startswith("W=/home/m8-service/m8-maint-q12\nset -Eeuo pipefail\n") + assert 'lane_capture "$LANES/s4"' in script and 'wait "$H"' in script + assert (out / "c3-qualification.stdout").read_bytes() == b"lane-boundary-checked\n" + manifest = (out / "MANIFEST.sha256").read_bytes() + assert hashlib.sha256(manifest).hexdigest() == digest + for line in manifest.decode().splitlines(): + expected, name = line.split(" ") + assert hashlib.sha256((out / name).read_bytes()).hexdigest() == expected + assert "\r" not in script + with pytest.raises(package.Refused, match="already exists"): + package.build(procedure(tmp_path, QUALIFICATION), out) + # An empty directory that appeared first is never replaced. + claimed = tmp_path / "claimed" + claimed.mkdir() + with pytest.raises(package.Refused, match="already exists"): + package.build(procedure(tmp_path, QUALIFICATION), claimed) + assert list(claimed.iterdir()) == [] + + +@pytest.mark.parametrize("change", [ + # The g11 S4 stop: the frozen, unwrapped lane call. + ('{source = "self", heading = "L1: qualification boundary", fences = [0]}', + '{source = "oc", heading = "S4. Qualification", fences = [0]}'), + # A capture on the line does not make another call on it captured. + ('{source = "self", heading = "L1: qualification boundary", fences = [0]}', + '{source = "self", heading = "Unreviewed", fences = [0]}'), + # Splitting the name with a line continuation does not hide it. + ('{source = "self", heading = "L1: qualification boundary", fences = [0]}', + '{source = "self", heading = "Split", fences = [0]}'), + # Literals never name the lane. + ('{literal = "W=/home/m8-service/m8-maint-q12"}', + "{literal = 'OTHER=(\"${LANE[@]}\")'}"), +]) +def test_only_reviewed_lane_boundary_blocks_may_name_the_lane(tmp_path, change): + with pytest.raises(package.Refused, match="only a reviewed lane-boundary block"): + package.assemble(procedure(tmp_path, QUALIFICATION.replace(*change))) + + +def test_stale_generation_paths_are_refused_like_the_h7_composition_gap(tmp_path): + stale = QUALIFICATION.replace('"W=/home/m8-service/m8-maint-q12"', + '"ACTIVE=$W/h7-q11-active.json"') + with pytest.raises(package.Refused, match=r"undeclared or historical labels \['q11'\]"): + package.assemble(procedure(tmp_path, stale)) + allowed = stale.replace('stdout = ["lane-boundary-checked"]', + 'stdout = ["lane-boundary-checked"]\nhistorical = true') + assert package.assemble(procedure(tmp_path, allowed))[0].name == "c3-qualification" + with pytest.raises(package.Refused, match=r"\['q13'\]"): + package.assemble(procedure(tmp_path, QUALIFICATION.replace("q12", "q13"))) + + +def test_a_changed_or_crlf_frozen_source_is_refused(tmp_path): + path = procedure(tmp_path, QUALIFICATION) + (tmp_path / "frozen.md").write_bytes(FROZEN.replace("90", "91").encode()) + with pytest.raises(package.Refused, match="source oc does not match its pinned SHA-256"): + package.assemble(path) + crlf = FROZEN.replace("\n", "\r\n") + with pytest.raises(package.Refused, match="source oc is not LF-only"): + package.assemble(procedure(tmp_path, QUALIFICATION, frozen=crlf)) + + +@pytest.mark.parametrize(("change", "message"), [ + (('heading = "Setup"', 'heading = "Absent"'), "heading 'Absent' occurs 0 times"), + (('"Setup", fences = [0]', '"Setup", fences = [9]'), "has no fence 9"), + (('"Setup", fences = [0]', '"Setup", fences = []'), "non-empty list of integers"), + (('"Setup", fences = [0]', '"Setup", fences = ["0"]'), "non-empty list of integers"), + (('heading = "Setup"', 'heading = "Notes"'), "is not bash"), + (('source = "oc", heading = "Setup"', 'source = "other", heading = "Setup"'), + "unknown source 'other'"), + (('name = "c3-qualification"', 'name = "C3 Bad"'), "step name 'C3 Bad' is invalid"), + (('stdout = ["lane-boundary-checked"]', 'stdout = "ok"'), "stdout must be a list"), + (('stdout = ["lane-boundary-checked"]', 'stdout = ["ok\\r"]'), "not be LF-only"), + (('stdout = ["lane-boundary-checked"]', 'stdout = ["two\\nlines"]'), "not be LF-only"), + (('stdout = ["lane-boundary-checked"]', 'stdout = ["x"]\nhistorical = "false"'), + "historical must be a boolean"), + (('stdout = ["lane-boundary-checked"]', 'stdout = ["x"]\nextra = 1'), "a step has exactly"), + (('{literal = "W=/home/m8-service/m8-maint-q12"}', + '{literal = "W=x", source = "oc", heading = "Setup", fences = [0]}'), + "exactly a literal or a fence selection"), + (('{literal = "W=/home/m8-service/m8-maint-q12"}', '{literal = "true\\r\\n"}'), + "not be LF-only"), + (('{literal = "W=/home/m8-service/m8-maint-q12"}', '{literal = " \\n"}'), + "a literal part is empty"), +]) +def test_unresolvable_or_ambiguous_compositions_refuse(tmp_path, change, message): + with pytest.raises(package.Refused, match=message): + package.assemble(procedure(tmp_path, QUALIFICATION.replace(*change, 1))) + + +def test_empty_parts_unknown_keys_and_oversized_stdout_refuse(tmp_path): + empty = QUALIFICATION.split("parts = [", 1)[0] + "parts = []\n" + with pytest.raises(package.Refused, match="parts must be a non-empty list"): + package.assemble(procedure(tmp_path, empty)) + with pytest.raises(package.Refused, match="unknown composition keys"): + package.assemble(procedure(tmp_path, QUALIFICATION, extra='procedure = "g12"')) + big = QUALIFICATION.replace('stdout = ["lane-boundary-checked"]', + f'stdout = ["{"x" * 65_536}"]') + with pytest.raises(package.Refused, match="exceeds 65536 bytes"): + package.assemble(procedure(tmp_path, big)) + + +def test_repeated_steps_and_assigned_placeholders_refuse_sentinels_do_not(tmp_path): + with pytest.raises(package.Refused, match="invalid or repeated"): + package.assemble(procedure(tmp_path, QUALIFICATION * 2)) + unreviewed = QUALIFICATION.replace("m8-maint-q12", "m8-maint-q12\\nRUN_ID=UNREVIEWED") + path = procedure(tmp_path, unreviewed) + with pytest.raises(package.Refused, match="unreviewed placeholder"): + package.assemble(path) + assert package.assemble(path, template=True)[0].text.count("=UNREVIEWED") == 1 + sentinel = QUALIFICATION.replace( + "m8-maint-q12", "m8-maint-q12\\ntest \\\"$B\\\" != /h/UNPREPARED.bundle") + assert "UNPREPARED.bundle" in package.assemble(procedure(tmp_path, sentinel))[0].text + for quoted in ('RUN_ID=\\\"UNREVIEWED\\\"', "RUN_ID='UNPREPARED'"): + assigned = QUALIFICATION.replace("m8-maint-q12", f"m8-maint-q12\\n{quoted}") + with pytest.raises(package.Refused, match="unreviewed placeholder"): + package.assemble(procedure(tmp_path, assigned)) + + +def test_an_allowlisted_name_outside_the_procedure_directory_is_not_reviewed(tmp_path): + """A pinned copy at fake/frozen.md shares the reviewed name, never its standing.""" + (tmp_path / "fake").mkdir() + (tmp_path / "fake" / "frozen.md").write_bytes(FROZEN.encode()) + path = procedure(tmp_path, QUALIFICATION) + path.write_bytes(path.read_bytes().replace(b'path = "frozen.md"', b'path = "fake/frozen.md"')) + with pytest.raises(package.Refused, match="only a reviewed lane-boundary block"): + package.assemble(path) + + +def test_wrong_container_and_selector_types_refuse_without_a_traceback(tmp_path): + scalar = tmp_path / "scalar.md" + scalar.write_bytes(b"# P\n\n## Composition\n\n```toml\nsteps = 1\n```\n") + with pytest.raises(package.Refused, match="steps must be a list"): + package.assemble(scalar) + listed = QUALIFICATION.replace('{source = "oc", heading = "Setup"', + '{source = ["oc"], heading = "Setup"') + with pytest.raises(package.Refused, match="unknown source"): + package.assemble(procedure(tmp_path, listed)) + + +@pytest.mark.parametrize("spelling", [ + "RUN_ID=$'UNREVIEWED'", "RUN_ID=UNRE\\\\VIEWED", 'RUN_ID=\\"UNRE\\"\\"VIEWED\\"', + "--run UNREVIEWED", "C=UNPREPARED", "RUN_ID=UNPREPARED.bundle.old", + "RUN_ID=UNPREPARED.bundlex", +]) +def test_every_shell_spelling_of_a_placeholder_refuses(tmp_path, spelling): + escaped = QUALIFICATION.replace("m8-maint-q12", f"m8-maint-q12\\n{spelling}") + with pytest.raises(package.Refused, match="unreviewed placeholder"): + package.assemble(procedure(tmp_path, escaped)) + + +def test_literals_keep_their_exact_trailing_newlines(tmp_path): + exact = QUALIFICATION.replace('{literal = "W=/home/m8-service/m8-maint-q12"}', + '{literal = "W=/home/m8-service/m8-maint-q12\\n\\n\\n"}') + text = package.assemble(procedure(tmp_path, exact))[0].text + assert text.startswith("W=/home/m8-service/m8-maint-q12\n\n\nset -Eeuo pipefail\n") + + +def test_split_placeholders_empty_fences_and_double_labels_refuse(tmp_path): + split = QUALIFICATION.replace("m8-maint-q12", "m8-maint-q12\\nRUN_ID=UNRE\\\\\\nVIEWED") + with pytest.raises(package.Refused, match="unreviewed placeholder"): + package.assemble(procedure(tmp_path, split)) + empty = FROZEN + "\n### Empty\n\n```bash\n\n```\n" + selected = QUALIFICATION.replace('heading = "Setup"', 'heading = "Empty"') + with pytest.raises(package.Refused, match="'Empty' fence 0 is empty"): + package.assemble(procedure(tmp_path, selected, frozen=empty)) + path = procedure(tmp_path, QUALIFICATION) + path.write_bytes(path.read_bytes().replace(b'historical = ["g10", "q11"]', + b'historical = ["g10", "q12"]')) + with pytest.raises(package.Refused, match=r"\['q12'\] are both current and historical"): + package.assemble(path) + + +def test_a_label_split_by_shell_quoting_is_still_seen(tmp_path): + quoted = QUALIFICATION.replace('"W=/home/m8-service/m8-maint-q12"', + "\"W=/home/m8-service/m8-maint-q'1'1\"") + with pytest.raises(package.Refused, match=r"\['q11'\]"): + package.assemble(procedure(tmp_path, quoted)) + + +def test_a_label_split_by_a_line_continuation_is_still_seen(tmp_path): + split = QUALIFICATION.replace('"W=/home/m8-service/m8-maint-q12"', + '"W=/home/m8-service/m8-maint-q\\\\\\n11"') + with pytest.raises(package.Refused, match=r"\['q11'\]"): + package.assemble(procedure(tmp_path, split)) + + +@pytest.mark.parametrize("sources", [ + "sources = []", + '[sources.oc]\npath = 7\nsha256 = "x"', + '[sources.self]\npath = "frozen.md"\nsha256 = "x"', +]) +def test_malformed_sources_refuse_without_a_traceback(tmp_path, sources): + document = (f"# P\n\n## Composition\n\n```toml\n{sources}\n" + '[[steps]]\nname = "s"\nstdout = []\nparts = [{literal = "true"}]\n```\n') + path = tmp_path / "procedure.md" + path.write_bytes(document.encode()) + with pytest.raises(package.Refused, match=r"sources must be a table|string path and sha256"): + package.assemble(path) + + +def test_crlf_document_and_missing_composition_refuse(tmp_path): + path = procedure(tmp_path, QUALIFICATION) + path.write_bytes(path.read_bytes().replace(b"\n", b"\r\n")) + with pytest.raises(package.Refused, match="not LF-only"): + package.assemble(path) + path.write_bytes(b"# Procedure\n\n## Other\n") + with pytest.raises(package.Refused, match="heading 'Composition' occurs 0 times"): + package.assemble(path) + + +def test_section_ends_at_the_next_heading_of_the_same_or_higher_level(): + document = "# A\n## B\nb\n### C\nc\n## D\nd\n" + assert package.section(document, "B") == "b\n### C\nc\n" + assert package.section(document, "C") == "c\n" + + +def test_fences_follow_commonmark_indent_length_and_exact_closers(): + document = ("## B\n\n```bash\n# D\nx=1\n## C\n```\n\n" + " ```bash\n indented\n ```\n\n" + "````text\n```bash\ninner example\n```\n````\n\n" + "```bash\nnot closed by\n```suffix\nstill inside\n```\n\n## C\nc\n") + assert package.fences(package.section(document, "B")) == [ + ("bash", "# D\nx=1\n## C\n"), ("bash", "indented\n"), + ("text", "```bash\ninner example\n```\n"), + ("bash", "not closed by\n```suffix\nstill inside\n"), + ] + assert package.section(document, "C") == "c\n" + with pytest.raises(package.Refused, match="'D' occurs 0 times"): + package.section(document, "D") + with pytest.raises(package.Refused, match="never closed"): + package.fences("```bash\nopen\n") + + +def test_cli_is_strict_unless_template_and_runs_isolated(tmp_path): + path = procedure(tmp_path, QUALIFICATION.replace( + "m8-maint-q12", "m8-maint-q12\\nRUN_ID=UNREVIEWED")) + script = str(Path(package.__file__)) + + def run(*args): + return subprocess.run([sys.executable, "-I", "-S", "-B", script, *args], + stdin=subprocess.DEVNULL, capture_output=True, text=True, + timeout=30, check=False) + + # The isolated CLI uses the real allowlist; this fixture's L1 is not on it. + refused = run("check", str(path), "--template") + assert refused.returncode == 1 and "lane-boundary block" in refused.stderr + assert run("bogus").returncode == 1 + + +def test_real_frozen_and_reviewed_blocks_are_classified(tmp_path, monkeypatch): + """The allowlist against actual repository bytes: L1-L3 and frozen S6a pass; + frozen OC S4 and ER R1, which print the lane summary unwrapped, refuse.""" + monkeypatch.setattr(package, "LANE_BLOCKS", REAL_LANE_BLOCKS) + names = ("M8-N4-operator-commands.md", "M8-N5-explicit-refresh.md", + "M8-maintenance-lane-output.md") + for name in names: + shutil.copyfile(HANDOFFS / name, tmp_path / name) + sources = "\n".join( + f'[sources.s{index}]\npath = "{name}"\nsha256 = "' + f'{hashlib.sha256((HANDOFFS / name).read_bytes()).hexdigest()}"' + for index, name in enumerate(names)) + + def step(source: str, heading: str) -> Path: + document = (f"# P\n\n## Composition\n\n```toml\nlabels = {{current = []}}\n{sources}\n" + f'[[steps]]\nname = "s"\nstdout = []\nparts = [{{source = "{source}", ' + f'heading = "{heading}", fences = [0]}}]\n```\n') + path = tmp_path / "procedure.md" + path.write_bytes(document.encode()) + return path + + for source, heading in (("s0", "S4. Qualification"), + ("s1", "R1: one explicit-refresh attempt")): + with pytest.raises(package.Refused, match="lane-boundary block"): + package.assemble(step(source, heading), template=True) + for source, heading in (("s2", "L1: qualification boundary"), ("s2", "L2: H7 controls"), + ("s2", "L3: explicit refresh"), + ("s0", "S6a. Maintenance-lock positive control")): + try: + package.assemble(step(source, heading), template=True) + except package.Refused as error: + assert "lane-boundary" not in str(error), heading