substratum-cli 0.1.0__py3-none-any.whl

substratum_cli/commands/auth.py

@@ -0,0 +1,37 @@
+"""`login` / `logout` / `whoami` -- connect the thin client to the hosted engine via GitHub."""
+from __future__ import annotations
+
+import sys
+
+from .. import account, remote
+
+
+def cmd_login() -> int:
+    if account.is_logged_in():
+        sys.stdout.write(f"  already logged in as {account.github_login() or 'a user'} "
+                         f"({account.server()})\n")
+        return 0
+    sys.stdout.write(f"  connecting to {account.server()} ...\n")
+    try:
+        who = remote.login()
+    except remote.RemoteError as e:
+        sys.stderr.write(f"  login failed: {e}\n")
+        return 1
+    sys.stdout.write(f"\n  logged in as {who.get('github_login') or 'a user'}. "
+                     f"fix/write/clarify now use the hosted engine.\n")
+    return 0
+
+
+def cmd_logout() -> int:
+    account.clear()
+    sys.stdout.write("  logged out (local commands still work offline).\n")
+    return 0
+
+
+def cmd_whoami() -> int:
+    if account.is_logged_in():
+        sys.stdout.write(f"  {account.github_login() or 'logged in'}  ·  {account.server()}\n")
+    else:
+        sys.stdout.write("  not logged in — run  substratum login  to use the hosted engine "
+                         "(local commands work offline)\n")
+    return 0

substratum_cli/commands/commit.py

@@ -0,0 +1,40 @@
+"""`commit [<run>]` -- a proof-carrying git commit of a verified, applied run: stages exactly the
+run's files and commits them with a message that cites the verified run + its provenance. Uses the
+repo's own git author config, never Substratum's."""
+from __future__ import annotations
+
+from typing import Optional
+
+from .. import codes, gitio, refusals, run_store
+from .. import result as _result
+
+
+def _proof_message(target: str, run_id: str, prov: list) -> str:
+    body = f"substratum: {target}\n\nVerified run {run_id}."
+    if prov:
+        body += "\nProvenance: " + ", ".join(prov[:4])
+    return body
+
+
+def cmd_commit(repo: str, run_id: str, message: Optional[str] = None) -> "_result.SubstratumResult":
+    loaded = run_store.load_run(repo, run_id)
+    if not loaded:
+        ref = refusals.build(codes.RUN_NOT_FOUND, ctx={"target": run_id, "run_id": run_id})
+        return _result.make(codes.REFUSED, run_id, "commit", code=codes.RUN_NOT_FOUND, refusal=ref)
+    res, _inp = loaded
+    files = list(res.files or [])
+    if res.verdict not in (codes.VERIFIED, codes.PASS) or not files:
+        ref = refusals.build(codes.GATE_PRECONDITION,
+                             engine_code="only a verified, applied run can be committed",
+                             ctx={"target": run_id, "run_id": run_id})
+        return _result.make(codes.REFUSED, run_id, "commit", code=codes.GATE_PRECONDITION, refusal=ref)
+    target = (res.data or {}).get("target") or run_id
+    prov = list(res.provenance.entries) if res.provenance else []
+    msg = message or _proof_message(target, run_id, prov)
+    ok, sha = gitio.commit_files(repo, files, msg)
+    if not ok:
+        ref = refusals.build(codes.GATE_PRECONDITION, engine_code=sha,
+                             ctx={"target": run_id, "run_id": run_id})
+        return _result.make(codes.REFUSED, run_id, "commit", code=codes.GATE_PRECONDITION, refusal=ref)
+    return _result.make(codes.PASS, run_id, "commit", files=tuple(files),
+                        data={"sha": sha, "files": files, "subject": msg.splitlines()[0]})

substratum_cli/commands/explain.py

@@ -0,0 +1,63 @@
+"""`substratum explain <run-id> [--line file:N]` -- render the provenance manifest for a run.
+`substratum attest <run-id>` -- emit an evidence bundle (transcripts + manifest + versions).
+Both are run-store readers; light (no engine import)."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import zipfile
+
+from .. import codes
+from .. import refusals
+from .. import result as _result
+from .. import run_store
+
+
+def cmd_explain(repo: str, run_id: str, line: str | None = None) -> "_result.SubstratumResult":
+    repo = os.path.abspath(repo)
+    loaded = run_store.load_run(repo, run_id)
+    if loaded is None:
+        return _result.make(codes.REFUSED, run_id, "explain", code=codes.RUN_NOT_FOUND,
+                            refusal=refusals.build(codes.RUN_NOT_FOUND,
+                                                   ctx={"target": run_id, "run_id": run_id}))
+    res, _inputs = loaded
+    manifest = {
+        "run_id": run_id, "verdict": res.verdict,
+        "provenance": list(res.provenance.entries) if res.provenance else [],
+        "pattern_id": res.provenance.pattern_id if res.provenance else None,
+        "corpus_support": res.provenance.corpus_support if res.provenance else None,
+        "grain": "function",  # honest: current provenance grain is function-level, not per-line
+        "files": list(res.files),
+    }
+    if line:
+        manifest["note"] = ("per-line provenance is not yet recorded; grain is function-level. "
+                            f"The provenance below covers the whole emission for {line}.")
+    return _result.make(codes.PASS, run_id, "explain", data={"manifest": manifest})
+
+
+def cmd_attest(repo: str, run_id: str) -> "_result.SubstratumResult":
+    repo = os.path.abspath(repo)
+    d = run_store.run_dir(repo, run_id)
+    if not os.path.isdir(d):
+        return _result.make(codes.REFUSED, run_id, "attest", code=codes.RUN_NOT_FOUND,
+                            refusal=refusals.build(codes.RUN_NOT_FOUND,
+                                                   ctx={"target": run_id, "run_id": run_id}))
+    # per-file sha256 manifest + egress attestation
+    file_hashes = {}
+    for root, _dirs, files in os.walk(d):
+        for f in files:
+            p = os.path.join(root, f)
+            rel = os.path.relpath(p, d)
+            file_hashes[rel] = hashlib.sha256(open(p, "rb").read()).hexdigest()
+    att_dir = os.path.join(run_store.store_dir(repo), "attestations")
+    os.makedirs(att_dir, exist_ok=True)
+    manifest = {"run_id": run_id, "files": file_hashes, "egress": "none",
+                "signature": "unsigned (v1; signing hook stubbed)"}
+    bundle = os.path.join(att_dir, f"{run_id}.zip")
+    with zipfile.ZipFile(bundle, "w", zipfile.ZIP_DEFLATED) as z:
+        for rel in file_hashes:
+            z.write(os.path.join(d, rel), rel)
+        z.writestr("manifest.json", json.dumps(manifest, indent=2))
+    return _result.make(codes.PASS, run_id, "attest",
+                        data={"bundle": bundle, "manifest": manifest})

substratum_cli/commands/failing.py

@@ -0,0 +1,80 @@
+"""`failing` / `tests` -- discover failing tests in the repo by RUNNING its own suite and collecting
+the failed node-ids. This is an OBSERVATION (read-only; runs the user's existing test command), not a
+guess -- the failing tests are facts from the runner, and each becomes a ready `fix <id>` target."""
+from __future__ import annotations
+
+import os
+import re
+import shlex
+import subprocess
+import sys as _sys
+from typing import Optional
+
+from .. import codes, refusals, runid
+from .. import result as _result
+
+# pytest -q prints "FAILED path::test - reason" and "ERROR path::test" lines
+_FAIL_RE = re.compile(r"^(?:FAILED|ERROR)\s+(\S+)", re.M)
+
+
+def _detect_command(repo: str) -> Optional[list]:
+    for marker in ("pytest.ini", "conftest.py", "tox.ini"):
+        if os.path.exists(os.path.join(repo, marker)):
+            return [_sys.executable, "-m", "pytest"]
+    for cfg in ("pyproject.toml", "setup.cfg"):
+        p = os.path.join(repo, cfg)
+        if os.path.isfile(p):
+            try:
+                if "pytest" in open(p, encoding="utf-8", errors="replace").read().lower():
+                    return [_sys.executable, "-m", "pytest"]
+            except Exception:
+                pass
+    if os.path.isdir(os.path.join(repo, "tests")):
+        return [_sys.executable, "-m", "pytest"]
+    try:
+        if any(f.startswith("test_") and f.endswith(".py") for f in os.listdir(repo)):
+            return [_sys.executable, "-m", "pytest"]
+    except Exception:
+        pass
+    return None
+
+
+def cmd_failing(repo: str, path: Optional[str] = None, test_command: Optional[str] = None,
+                timeout: int = 300) -> "_result.SubstratumResult":
+    repo = os.path.abspath(repo)
+    rid, _key = runid.compute(repo, "failing", {"path": path or ""})
+    argv = shlex.split(test_command) if test_command else _detect_command(repo)
+    if not argv:
+        ref = refusals.build(codes.NO_DRIVER,
+                             engine_code="no recognized test harness (looked for pytest)",
+                             ctx={"target": repo, "run_id": rid})
+        return _result.make(codes.REFUSED, rid, "failing", code=codes.NO_DRIVER, refusal=ref)
+    is_pytest = "pytest" in " ".join(argv)
+    run_argv = list(argv) + (["-q", "-p", "no:cacheprovider"] if is_pytest else [])
+    if path:
+        run_argv.append(path)
+    try:
+        r = subprocess.run(run_argv, cwd=repo, capture_output=True, text=True, timeout=timeout,
+                           env={**os.environ, "TMPDIR": "/tmp"})
+    except subprocess.TimeoutExpired:
+        ref = refusals.build(codes.GATE_PRECONDITION,
+                             engine_code=f"the test suite did not finish within {timeout}s",
+                             ctx={"target": repo, "run_id": rid})
+        return _result.make(codes.REFUSED, rid, "failing", code=codes.GATE_PRECONDITION, refusal=ref)
+    except (FileNotFoundError, PermissionError) as e:
+        ref = refusals.build(codes.NO_DRIVER, engine_code=f"could not run the test command ({e})",
+                             ctx={"target": repo, "run_id": rid})
+        return _result.make(codes.REFUSED, rid, "failing", code=codes.NO_DRIVER, refusal=ref)
+    out = (r.stdout or "") + "\n" + (r.stderr or "")
+    failing = []
+    for m in _FAIL_RE.finditer(out):
+        nid = m.group(1)
+        if nid not in failing:
+            failing.append(nid)
+    all_pass = (not failing) and r.returncode == 0
+    excerpt = ""
+    if not failing and not all_pass:                 # suite could not run cleanly -> surface why
+        excerpt = "\n".join(out.strip().splitlines()[-8:])
+    return _result.make(codes.PASS, rid, "failing",
+                        data={"failing": failing, "command": " ".join(run_argv),
+                              "all_pass": all_pass, "excerpt": excerpt, "rc": r.returncode})

substratum_cli/commands/fix.py

@@ -0,0 +1,48 @@
+"""`substratum fix <test>` -- produce a verified fix for a failing test, or a named refusal.
+Thin over product_ops.op_fix_from_failing_test; streams stage events when --events is set."""
+from __future__ import annotations
+
+import os
+import sys
+
+from .. import codes
+from .. import gitio
+from .. import refusals
+from .. import result as _result
+
+
+def cmd_fix(args) -> "_result.SubstratumResult":
+    from .. import product_ops
+    repo = os.path.abspath(args.repo)
+    if not gitio.is_git_repo(repo):
+        return _result.make(codes.REFUSED, "sub_000000000000", "fix",
+                            code=codes.GATE_PRECONDITION,
+                            refusal=refusals.build(codes.GATE_PRECONDITION,
+                                                   ctx={"target": repo, "run_id": "sub_000000000000"}))
+    tests = list(getattr(args, "failing_test", []) or [])
+    if getattr(args, "target", None):
+        tests.append(args.target)
+    if not tests:
+        return _result.make(codes.REFUSED, "sub_000000000000", "fix",
+                            code=codes.NO_WARRANT_TESTS,
+                            refusal=refusals.build(codes.NO_WARRANT_TESTS,
+                                                   ctx={"target": "no test given", "run_id": "sub_000000000000"}))
+    intent = getattr(args, "intent", "") or ""
+    if intent and os.path.isfile(intent):
+        intent = open(intent, encoding="utf-8", errors="replace").read()
+
+    emit = None
+    if getattr(args, "events", False):
+        import json
+
+        def emit(stage, text):
+            sys.stdout.write(json.dumps({"stage": stage, "text": text}) + "\n")
+            sys.stdout.flush()
+    elif not getattr(args, "json", False):
+        def emit(stage, text):
+            sys.stderr.write(f"  {stage:7} {text}\n")
+            sys.stderr.flush()
+
+    return product_ops.op_fix_from_failing_test(
+        repo, tests, intent=intent,
+        test_command=getattr(args, "test_command", None), emit=emit)

substratum_cli/commands/history.py

@@ -0,0 +1,15 @@
+"""`runs` / `log` -- the proof store made visible: the newest runs (every VERIFIED and every
+REFUSED) plus the refusal->VERIFIED conversion ledger. This is the persistent, proof-carrying
+memory that no LLM tool has, surfaced in the terminal."""
+from __future__ import annotations
+
+from .. import codes, run_store, runid
+from .. import result as _result
+
+
+def cmd_runs(repo: str, limit: int = 15) -> "_result.SubstratumResult":
+    runs = run_store.list_runs(repo, limit)
+    refn, conv = run_store.refusal_stats(repo, window_days=36500)   # all-time ledger
+    rid, _key = runid.compute(repo, "runs", {"n": len(runs)})
+    return _result.make(codes.PASS, rid, "runs",
+                        data={"runs": runs, "ledger": {"refusals": refn, "converted": conv}})

substratum_cli/commands/init_cmd.py

@@ -0,0 +1,155 @@
+"""`substratum init` -- declare the contract before the first refusal.
+
+Three things, all light (no library load, no numpy):
+  1. Coverage Contract: bucket the repo's file extensions against the LIVE driver registries
+     so every later refusal reads as the contract being honored, not the tool failing.
+  2. Flake scan: run the detected suite K times at base in a worktree; quarantine any test
+     whose outcome is not stable (protects the determinism claim from the customer's own infra).
+  3. Air-gap attestation: count socket events during the scan -> "0 sockets opened, checked
+     not claimed."
+`doctor` re-runs the checks any time.
+"""
+from __future__ import annotations
+
+import os
+from collections import defaultdict
+from typing import Optional
+
+from .. import codes
+from .. import engine
+from .. import gitio
+from .. import result as _result
+from .. import run_store
+from .. import runid
+
+_SKIP_DIRS = {".git", "node_modules", ".venv", "venv", "__pycache__", ".substratum",
+              "dist", "build", ".tox", ".mypy_cache", ".pytest_cache"}
+
+
+def _walk_extensions(repo: str) -> dict:
+    counts = defaultdict(lambda: [0, 0])   # ext -> [files, lines]
+    for root, dirs, files in os.walk(repo):
+        dirs[:] = [d for d in dirs if d not in _SKIP_DIRS]
+        for f in files:
+            ext = os.path.splitext(f)[1].lower()
+            if not ext:
+                continue
+            p = os.path.join(root, f)
+            counts[ext][0] += 1
+            try:
+                with open(p, "rb") as fh:
+                    counts[ext][1] += sum(1 for _ in fh)
+            except OSError:
+                pass
+    return counts
+
+
+def build_coverage_contract(repo: str) -> dict:
+    reg = engine.coverage_registries()
+    counts = _walk_extensions(repo)
+    gated, undriven, unknown = [], [], []
+    for ext, (nfiles, nlines) in sorted(counts.items()):
+        row = {"ext": ext, "files": nfiles, "lines": nlines}
+        if ext in reg["code_langs"]:
+            row["lang"] = reg["code_langs"][ext]
+            gated.append(row)
+        elif ext in reg["driven_noncode"] or ext in reg["template_exts"]:
+            gated.append(row)
+        elif ext in reg["known_undriven"]:
+            row["refusal"] = f"NONCODE_NO_DRIVER({ext})"
+            undriven.append(row)
+        else:
+            unknown.append(row)
+    harness = engine.client_gate.resolve_test_command(repo, None, [])
+    return {"gated": gated, "no_driver": undriven, "unknown": unknown,
+            "harness": " ".join(harness) if harness else None}
+
+
+def flake_scan(repo: str, tests: Optional[list] = None, rounds: int = 3) -> dict:
+    """Run the detected suite `rounds` times at HEAD in isolated worktrees; a test whose
+    pass/fail outcome differs across rounds is quarantined. Counts socket events -> air-gap."""
+    import socket as _socket
+    sock_events = {"n": 0}
+    orig = _socket.socket.connect
+
+    def _counting_connect(self, *a, **k):
+        sock_events["n"] += 1
+        return orig(self, *a, **k)
+
+    _socket.socket.connect = _counting_connect
+    outcomes = []
+    try:
+        base = gitio.head_sha(repo)
+        for _ in range(rounds):
+            sink: dict = {}
+            # a no-op "patch" (empty edits) with differential=False just runs the suite once
+            cg = engine.client_gate.run_client_gate(repo, base, {}, test_paths=tests or [],
+                                                    differential=False, transcript_sink=sink)
+            outcomes.append(cg.code)
+    finally:
+        _socket.socket.connect = orig
+    stable = len(set(outcomes)) <= 1
+    return {"rounds": rounds, "outcomes": outcomes, "stable": stable,
+            "sockets_opened": sock_events["n"],
+            "quarantine": [] if stable else ["suite outcome not stable across rounds"]}
+
+
+def cmd_init(repo: str, run_flake: bool = True) -> "_result.SubstratumResult":
+    repo = os.path.abspath(repo)
+    rid, key = runid.compute(repo, "init", {"op": "init"})
+    if not gitio.is_git_repo(repo):
+        from .. import refusals
+        return _result.make(codes.REFUSED, rid, "init", code=codes.GATE_PRECONDITION,
+                            refusal=refusals.build(codes.GATE_PRECONDITION,
+                                                   ctx={"target": repo, "run_id": rid}))
+    contract = build_coverage_contract(repo)
+    payload = {"coverage_contract": contract}
+    if run_flake and contract["harness"]:
+        payload["flake"] = flake_scan(repo)
+        payload["air_gap"] = {"sockets_opened": payload["flake"]["sockets_opened"],
+                              "attestation": "checked, not claimed"}
+    # persist the contract for the VS Code status bar + doctor
+    os.makedirs(run_store.store_dir(repo), exist_ok=True)
+    import json
+    with open(os.path.join(run_store.store_dir(repo), "coverage_contract.json"), "w") as fh:
+        json.dump(contract, fh, indent=2)
+    res = _result.make(codes.PASS, rid, "init", data=payload, engine=_engine_info())
+    run_store.store_run(repo, res, run_key=key)
+    return res
+
+
+def cmd_doctor(repo: str) -> "_result.SubstratumResult":
+    repo = os.path.abspath(repo)
+    rid, _ = runid.compute(repo, "doctor", {"op": "doctor"})
+    checks = {}
+    checks["git_repo"] = gitio.is_git_repo(repo)
+    harness = None
+    if checks["git_repo"]:
+        harness = engine.client_gate.resolve_test_command(repo, None, [])
+    checks["harness"] = " ".join(harness) if harness else None
+    checks["tmpdir_realfs"] = _tmpdir_ok()
+    checks["libraries"] = {k: v for k, v in runid.library_versions().items()}
+    if checks["git_repo"] and harness:
+        fl = flake_scan(repo)
+        checks["air_gap_sockets"] = fl["sockets_opened"]
+        checks["suite_stable"] = fl["stable"]
+    verdict = codes.PASS if checks["git_repo"] else codes.FAIL
+    return _result.make(verdict, rid, "doctor", data={"checks": checks})
+
+
+def _tmpdir_ok() -> bool:
+    """The drvfs/9p lesson: pytest capture needs a real-fs TMPDIR for unlinked-open tempfiles."""
+    import tempfile
+    try:
+        with tempfile.TemporaryFile() as fh:
+            fh.write(b"x")
+            fh.truncate()
+        return True
+    except OSError:
+        return False
+
+
+def _engine_info() -> "_result.EngineInfo":
+    return _result.EngineInfo(engine_version=runid.engine_version(),
+                              library_versions=tuple(f"{k}:{v}" for k, v in
+                                                     runid.library_versions().items()))

substratum_cli/commands/replay.py

@@ -0,0 +1,68 @@
+"""`substratum replay <run-id>` -- determinism as a button. Recompute the run key from current
+state; if it matches the stored key, re-execute and byte-compare; report byte-identical yes/no.
+This is the invitation to catch us."""
+from __future__ import annotations
+
+import os
+
+from .. import codes
+from .. import refusals
+from .. import result as _result
+from .. import run_store
+from .. import runid
+
+
+def _canonical_core(res) -> str:
+    """The stable slice compared on replay: verdict, code, diff, files, provenance. Excludes
+    volatile fields (there are none by construction -- run_id is content-addressed)."""
+    import hashlib
+    import json
+    core = {"verdict": res.verdict, "code": res.code, "diff": res.diff,
+            "files": list(res.files),
+            "provenance": list(res.provenance.entries) if res.provenance else []}
+    blob = json.dumps(core, sort_keys=True)
+    return hashlib.sha256(blob.encode()).hexdigest()
+
+
+def cmd_replay(repo: str, run_id: str) -> "_result.SubstratumResult":
+    repo = os.path.abspath(repo)
+    loaded = run_store.load_run(repo, run_id)
+    if loaded is None:
+        return _result.make(codes.REFUSED, run_id, "replay", code=codes.RUN_NOT_FOUND,
+                            refusal=refusals.build(codes.RUN_NOT_FOUND,
+                                                   ctx={"target": run_id, "run_id": run_id}))
+    stored, inputs = loaded
+    stored_key = (inputs.get("run_key") or {})
+    op = stored.operation
+
+    # recompute the run id from CURRENT state + the stored query; if it differs, state drifted
+    query = (stored_key.get("query") or {})
+    fresh_rid, fresh_key = runid.compute(repo, op, query)
+    if stored_key and fresh_key.get("head_sha") != stored_key.get("head_sha"):
+        return _result.make(codes.REFUSED, run_id, "replay", code=codes.REPLAY_STATE_DRIFT,
+                            refusal=refusals.build(codes.REPLAY_STATE_DRIFT,
+                                                   ctx={"target": run_id, "run_id": run_id}))
+
+    # re-execute the operation and compare the canonical core
+    re_res = _reexecute(repo, op, stored, inputs)
+    if re_res is None:
+        # cannot re-execute (e.g. informational op) -> compare id determinism only
+        identical = (fresh_rid == run_id)
+        return _result.make(codes.PASS if identical else codes.FAIL, run_id, "replay",
+                            data={"byte_identical": identical, "recomputed_run_id": fresh_rid})
+    a, b = _canonical_core(stored), _canonical_core(re_res)
+    identical = (a == b) and (re_res.run_id == run_id)
+    return _result.make(codes.PASS if identical else codes.FAIL, run_id, "replay",
+                        data={"byte_identical": identical, "sha": b,
+                              "recomputed_run_id": re_res.run_id})
+
+
+def _reexecute(repo, op, stored, inputs):
+    inp = inputs.get("inputs") or {}
+    if op == "fix" and inp.get("failing_tests"):
+        from .. import product_ops
+        return product_ops.op_fix_from_failing_test(
+            repo, list(inp["failing_tests"]), intent=inp.get("intent", ""),
+            test_command=inp.get("test_command"))
+    # verify replay would need the original diff bytes; informational ops fall through
+    return None

substratum_cli/commands/scaffold.py

@@ -0,0 +1,71 @@
+"""`substratum scaffold-test <file::fn> [--case k=v]` -- the flip-condition engine. Emit a
+RUNNABLE, FAILING test that pins a target/case, so an UNDERDETERMINED/UNVERIFIABLE refusal has
+an executable next step. Expected values come ONLY from a `TODO` that raises (never invented);
+the file runs and fails immediately, which is exactly a warrant waiting to be satisfied."""
+from __future__ import annotations
+
+import os
+
+from .. import codes
+from .. import gitio
+from .. import refusals
+from .. import result as _result
+from .. import run_store
+from .. import runid
+
+
+def _parse_target(target: str) -> tuple[str, str] | None:
+    if "::" in target:
+        path, name = target.split("::", 1)
+        return path, name
+    return None
+
+
+def cmd_scaffold_test(repo: str, target: str, cases: list | None = None) -> "_result.SubstratumResult":
+    repo = os.path.abspath(repo)
+    rid, key = runid.compute(repo, "scaffold_test", {"target": target, "cases": cases or []})
+    parsed = _parse_target(target or "")
+    if parsed is None:
+        return _result.make(codes.REFUSED, rid, "scaffold_test", code=codes.UNDERDETERMINED_INTENT,
+                            refusal=refusals.build(codes.UNDERDETERMINED_INTENT,
+                                                   ctx={"target": target or "<none>", "run_id": rid}))
+    mod_path, fn = parsed
+    mod_import = mod_path.replace("/", ".").rsplit(".py", 1)[0]
+    scaffold_rel = os.path.join(
+        os.path.dirname(mod_path) or ".", f"test_substratum_scaffold_{fn}.py")
+    scaffold_rel = os.path.normpath(scaffold_rel)
+
+    body = _emit_scaffold(mod_import, fn, cases or [])
+    diff = _new_file_diff(scaffold_rel, body)
+    res = _result.make(codes.PASS, rid, "scaffold_test", diff=diff, files=(scaffold_rel,),
+                       data={"target": target, "scaffold": scaffold_rel,
+                             "next": f"substratum fix {scaffold_rel}::test_{fn}_scaffold"})
+    run_store.store_run(repo, res, run_key=key)
+    return res
+
+
+def _emit_scaffold(mod_import: str, fn: str, cases: list) -> str:
+    lines = [
+        f"from {mod_import} import {fn}",
+        "",
+        "",
+        "def _TODO(msg):",
+        "    raise NotImplementedError('pin the expected value: ' + msg)",
+        "",
+        "",
+        f"def test_{fn}_scaffold():",
+    ]
+    if cases:
+        for i, c in enumerate(cases):
+            lines.append(f"    # case: {c}")
+            lines.append(f"    result_{i} = {fn}(_TODO('inputs for case {c!r}'))")
+            lines.append(f"    assert result_{i} == _TODO('expected output for case {c!r}')")
+    else:
+        lines.append(f"    result = {fn}(_TODO('inputs'))")
+        lines.append("    assert result == _TODO('expected output')")
+    return "\n".join(lines) + "\n"
+
+
+def _new_file_diff(path: str, content: str) -> str:
+    from .. import engine
+    return engine.canonical_diff()(path, "", content)

substratum_cli/commands/show.py

@@ -0,0 +1,18 @@
+"""`substratum show <run-id>` -- render a stored run through the SAME renderer as the live
+path. Light command: imports NO backend module (proven by the import-budget test)."""
+from __future__ import annotations
+
+from .. import codes
+from .. import refusals
+from .. import result as _result
+from .. import run_store
+
+
+def cmd_show(repo: str, run_id: str) -> "_result.SubstratumResult":
+    loaded = run_store.load_run(repo, run_id)
+    if loaded is None:
+        return _result.make(codes.REFUSED, run_id, "show", code=codes.RUN_NOT_FOUND,
+                            refusal=refusals.build(codes.RUN_NOT_FOUND,
+                                                   ctx={"target": run_id, "run_id": run_id}))
+    res, _inputs = loaded
+    return res

substratum_cli/commands/undo.py

@@ -0,0 +1,28 @@
+"""`undo [<run>]` -- the inverse of `apply`: reverse-apply a run's verified diff, restoring the
+working tree. Refuses cleanly (never force) if the files changed since apply."""
+from __future__ import annotations
+
+from typing import Optional
+
+from .. import codes, gitio, refusals, run_store
+from .. import result as _result
+
+
+def cmd_undo(repo: str, run_id: str) -> "_result.SubstratumResult":
+    loaded = run_store.load_run(repo, run_id)
+    if not loaded:
+        ref = refusals.build(codes.RUN_NOT_FOUND, ctx={"target": run_id, "run_id": run_id})
+        return _result.make(codes.REFUSED, run_id, "undo", code=codes.RUN_NOT_FOUND, refusal=ref)
+    res, _inp = loaded
+    if not res.diff:
+        ref = refusals.build(codes.APPLY_STATE_DRIFT,
+                             engine_code="this run wrote no diff, so there is nothing to undo",
+                             ctx={"target": run_id, "run_id": run_id})
+        return _result.make(codes.REFUSED, run_id, "undo", code=codes.APPLY_STATE_DRIFT, refusal=ref)
+    ok, msg = gitio.apply_reverse(repo, res.diff)
+    if not ok:
+        ref = refusals.build(codes.APPLY_STATE_DRIFT, engine_code=msg,
+                             ctx={"target": run_id, "run_id": run_id})
+        return _result.make(codes.REFUSED, run_id, "undo", code=codes.APPLY_STATE_DRIFT, refusal=ref)
+    files = list(res.files or [])
+    return _result.make(codes.PASS, run_id, "undo", files=tuple(files), data={"reverted": files})