substratum-cli 0.1.0__py3-none-any.whl

substratum_cli/README.md

@@ -0,0 +1,51 @@
+# Substratum
+
+**Verified-or-refused code, with provenance.** Substratum is a deterministic comprehension engine
+for code. It never streams tokens and hopes — it produces a change only when that change passes a
+gate, and otherwise returns an honest, actionable refusal. Every result carries a run id you can
+replay byte-for-byte.
+
+```
+pip install substratum-cli
+```
+
+Then, in any repository:
+
+```
+substratum                      # open the interactive session (warms, then drives)
+```
+
+## What it does
+
+- **`summarize`** — describe the codebase in plain English, grounded in its real symbols (not a guess).
+- **`failing`** — run the suite and list the failing tests; each becomes a ready fix target.
+- **`verify`** — gate a diff (stdin, `--staged`, `--commit`): PASS / FAIL / per-hunk. The wedge — point
+  it at any tool's diff and it tells you, deterministically, whether the change is real.
+- **`fix`** — produce a verified fix for a failing test, or a named refusal.
+- **`write`** — greenfield code from plain intent (derive-or-refuse; no test required).
+- **`runs` / `show` / `replay` / `undo` / `apply` / `commit`** — a proof-carrying memory of every run.
+
+`summarize`, `failing`, and `verify` run **entirely on your machine** — no account, no network, no code
+leaves your repo. They work air-gapped.
+
+## The hosted engine (optional)
+
+`fix` and `write` draw on a large mined library. During the demo that library is hosted:
+
+```
+substratum login                # GitHub device flow; connects to the hosted engine
+```
+
+When logged in, `write` sends only your intent + signature, and `fix` receives a *candidate* that your
+machine then gates locally — so your code and your tests never leave your machine. `substratum logout`
+returns to fully-local operation.
+
+## The law
+
+Never render unproven code. A refusal is a deliverable, not an error. Determinism is a button you
+press to catch us: run the same request twice and get the same run id, or `replay` any run and get a
+byte-identical result.
+
+Coverage grows with data. Today the engine refuses more than it resolves, by design — the surface is
+built to feel complete at thin coverage, and the same commands silently resolve more as the library
+scales, with zero change on your end.

substratum_cli/__init__.py

@@ -0,0 +1,6 @@
+"""substratum_cli -- the product surface (CLI + shared object model) over the Substratum engine.
+
+Import budget: this package is stdlib-only; the ONLY module reaching into backend.* is
+`engine.py`, lazily. Importing substratum_cli (or any light command) opens nothing heavy.
+"""
+__version__ = "0.1.0"

substratum_cli/__main__.py

@@ -0,0 +1,7 @@
+"""python -m substratum_cli -> the CLI."""
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

substratum_cli/_vendor/_pro_test_derive.py

@@ -0,0 +1,169 @@
+"""Derive a standalone GATED acceptance test for a single target function from a Pro test_patch.
+
+Recipe (from the mapping): take the test_patch added lines, extract the test functions that are in
+fail_to_pass AND call the target, keep only self-contained ones (no heavy fixtures / heavy objects),
+rewrite MOD.fn -> fn and inject `from solution import fn`. Returns the test string or None (-> intent-alone).
+"""
+import re
+
+_HEAVY_FIXTURES = {
+    "caplog", "capsys", "monkeypatch", "config_stub", "benchmark", "qtbot", "tmp_path", "tmpdir",
+    "mocker", "win_registry", "fake_web_tab", "responses", "qt_logger", "host_blocker_factory",
+    "mock_datetime", "tmpdir_factory", "request", "freezer",
+}
+_HEAVY_TOKENS = ("QUrl", "QtCore", "QtGui", "QtWidgets", "usertypes.", "objreg.", "asyncio.run",
+                 "await ", "PyQt", "qtbot", "QApplication", "mock.", "Mock(", "MagicMock")
+
+
+def _added_lines(test_patch: str):
+    out = []
+    for l in test_patch.split("\n"):
+        if l.startswith("+++") or l.startswith("---") or l.startswith("@@"):
+            continue
+        if l.startswith("+"):
+            out.append(l[1:])
+    return out
+
+
+def _ftp_names(fail_to_pass):
+    names = set()
+    for f in fail_to_pass or ():
+        leaf = f.split("::")[-1]
+        names.add(leaf.split("[")[0].strip())
+    return names
+
+
+def _extract_regions(added, name):
+    """[(fn, indent, [lines])] for each def test_* with its decorators + indented body."""
+    regions = []
+    i, n = 0, len(added)
+    while i < n:
+        m = re.match(r"(\s*)def (test_\w+)\s*\(", added[i])
+        if not m:
+            i += 1
+            continue
+        indent = len(m.group(1))
+        fn = m.group(2)
+        # decorators above: the contiguous non-blank block, from its first @-line down (captures a
+        # MULTI-LINE @pytest.mark.parametrize whose tuple list spans many lines before the def).
+        above = []
+        j = i - 1
+        while j >= 0 and added[j].strip() != "":
+            above.insert(0, added[j]); j -= 1
+        dec_start = next((idx for idx, l in enumerate(above) if l.lstrip().startswith("@")), None)
+        decs = above[dec_start:] if dec_start is not None else []
+        body = [added[i]]
+        k = i + 1
+        while k < n:
+            ln = added[k]
+            if ln.strip() == "" or (len(ln) - len(ln.lstrip())) > indent:
+                body.append(ln)
+                k += 1
+            else:
+                break
+        regions.append((fn, indent, decs + body))
+        i = k
+    return regions
+
+
+def _dedent(lines, indent):
+    out = []
+    for l in lines:
+        out.append(l[indent:] if len(l) >= indent and l[:indent].strip() == "" else l.lstrip())
+    return out
+
+
+def derive_gated_test(test_patch: str, name: str, fail_to_pass):
+    if not test_patch or not name:
+        return None
+    added = _added_lines(test_patch)
+    ftp = _ftp_names(fail_to_pass)
+    regions = _extract_regions(added, name)
+    call_re = re.compile(r"(\b\w+\.)?\b" + re.escape(name) + r"\s*\(")
+    kept = []
+    for fn, indent, lines in regions:
+        if ftp and fn not in ftp:
+            continue
+        region_text = "\n".join(lines)
+        if not call_re.search(region_text):
+            continue
+        # self-contained: def params carry no heavy fixture; body no heavy token
+        def_line = next((l for l in lines if l.lstrip().startswith("def ")), "")
+        params = def_line[def_line.find("(") + 1: def_line.rfind(")")] if "(" in def_line else ""
+        param_names = {p.strip().split(":")[0].split("=")[0].strip() for p in params.split(",")}
+        if param_names & _HEAVY_FIXTURES:
+            continue
+        if any(tok in region_text for tok in _HEAVY_TOKENS):
+            continue
+        # METHOD guard: if the target is invoked as QUAL.name( and QUAL is a LOCAL object constructed
+        # in the test body (QUAL = ...), it is a method needing instance state -> a free function the
+        # engine synthesizes cannot satisfy it. (utils.parse_duration: `utils` is a module top-import,
+        # never assigned -> kept. entity.get_statement_values: `entity = createWikidataEntity()` -> dropped.)
+        quals = set(re.findall(r"(\b\w+)\." + re.escape(name) + r"\s*\(", region_text))
+        if any(re.search(r"(?m)^\s*" + re.escape(q) + r"\s*=", region_text) for q in quals):
+            continue
+        kept.append((fn, indent, lines))
+    if not kept:
+        return None
+    # stdlib imports the kept regions may use (best-effort: keep added import lines that are not repo imports)
+    stdlib_imports = []
+    for l in added:
+        s = l.strip()
+        if s.startswith(("import ", "from ")) and " import " in (s + " "):
+            mod = s.split()[1].split(".")[0]
+            if mod in ("re", "math", "datetime", "logging", "dataclasses", "json", "itertools",
+                       "collections", "enum", "functools", "string", "decimal", "fractions"):
+                stdlib_imports.append(s)
+    body_blocks = []
+    for fn, indent, lines in kept:
+        ded = _dedent(lines, indent)
+        text = "\n".join(ded)
+        # strip a leading `self, ` / `self` from the def (class-method -> module-level)
+        text = re.sub(r"(def test_\w+\()self,\s*", r"\1", text)
+        text = re.sub(r"(def test_\w+\()self\)", r"\1)", text)
+        # rewrite MOD.name( -> name(
+        text = re.sub(r"\b\w+\." + re.escape(name) + r"\b", name, text)
+        body_blocks.append(text)
+    # NEED-DRIVEN stdlib imports: the added lines carry an import only when the PATCH adds it,
+    # but the original test file usually imported the module already (the patch only adds the
+    # test function). Scan the kept regions for `mod.` usages of the same stdlib allowlist and
+    # import every one the carried lines missed -- else the derived snippet NameErrors at
+    # collection and the gate can never evaluate ANY candidate.
+    _STDLIB = ("re", "math", "datetime", "logging", "dataclasses", "json", "itertools",
+               "collections", "enum", "functools", "string", "decimal", "fractions")
+    all_text = "\n".join(body_blocks)
+    carried = {l.split()[1].split(".")[0] for l in stdlib_imports}
+    for mod in _STDLIB:
+        if mod not in carried and re.search(rf"\b{mod}\.", all_text):
+            stdlib_imports.append(f"import {mod}")
+    header = "import pytest\n" + ("\n".join(dict.fromkeys(stdlib_imports)) + "\n" if stdlib_imports else "")
+    header += f"from solution import {name}\n"
+    return header + "\n\n" + "\n\n".join(body_blocks) + "\n"
+
+
+if __name__ == "__main__":
+    import json
+    D = "/mnt/f/luca-lm-data/swe_bench/pro_test.jsonl"
+    rows = [json.loads(l) for l in open(D) if l.strip()]
+    targets = {
+        "parse_duration": "instance_qutebrowser__qutebrowser-96b997802e94",
+        "widened_hostnames": "instance_qutebrowser__qutebrowser-c580ebf0801e",
+        "get_statement_values": "instance_internetarchive__openlibrary-4a5d2a7d",
+    }
+    by_id = {r["instance_id"]: r for r in rows}
+    for name, idpfx in targets.items():
+        inst = next((r for iid, r in by_id.items() if iid.startswith(idpfx)), None)
+        if inst is None:
+            print(f"\n=== {name}: instance not found ({idpfx}) ===")
+            continue
+        ftp = inst.get("fail_to_pass")
+        if isinstance(ftp, str):
+            try:
+                ftp = json.loads(ftp)
+            except Exception:
+                ftp = [x.strip().strip("'\"") for x in ftp.strip("[]").split(",")]
+        t = derive_gated_test(inst.get("test_patch", "") or "", name, ftp or [])
+        print(f"\n{'='*70}\n=== {name} ({inst['instance_id'][:40]}) ===")
+        print("DERIVED TEST:" if t else "NO SELF-CONTAINED TEST (-> intent-alone)")
+        if t:
+            print(t[:1200])

substratum_cli/account.py

@@ -0,0 +1,62 @@
+"""Global per-user account state: `~/.substratum/config.json` -- the login token, the server URL,
+and the GitHub identity. Distinct from the per-repo `.substratum.toml` (config.py). Stdlib only."""
+from __future__ import annotations
+
+import json
+import os
+
+_DEFAULT_SERVER = os.environ.get("SUBSTRATUM_SERVER", "https://substratum-api.fly.dev")
+
+
+def _dir() -> str:
+    return os.path.join(os.path.expanduser("~"), ".substratum")
+
+
+def _path() -> str:
+    return os.path.join(_dir(), "config.json")
+
+
+def load() -> dict:
+    try:
+        with open(_path(), encoding="utf-8") as fh:
+            d = json.load(fh)
+        return d if isinstance(d, dict) else {}
+    except Exception:
+        return {}
+
+
+def save(**fields) -> None:
+    d = load()
+    d.update({k: v for k, v in fields.items() if v is not None})
+    os.makedirs(_dir(), exist_ok=True)
+    tmp = _path() + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as fh:
+        json.dump(d, fh, indent=2)
+    os.replace(tmp, _path())
+    try:
+        os.chmod(_path(), 0o600)                # the token is a credential
+    except Exception:
+        pass
+
+
+def clear() -> None:
+    try:
+        os.remove(_path())
+    except Exception:
+        pass
+
+
+def token() -> str:
+    return os.environ.get("SUBSTRATUM_TOKEN") or str(load().get("token") or "")
+
+
+def server() -> str:
+    return str(load().get("server") or _DEFAULT_SERVER).rstrip("/")
+
+
+def github_login() -> str:
+    return str(load().get("github_login") or "")
+
+
+def is_logged_in() -> bool:
+    return bool(token())

substratum_cli/cli.py

@@ -0,0 +1,185 @@
+"""The `substratum` CLI: argparse dispatch. Commands are pure (inputs -> SubstratumResult);
+`main` alone maps the result to the process exit code and picks the renderer. Heavy commands
+(fix/verify/init/...) are imported inside their branch so light commands (show/--help) never
+pay the engine import.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional
+
+from . import codes
+from . import render as _render
+from . import result as _result
+
+
+def _emit(res: "_result.SubstratumResult", args) -> int:
+    """Render + return the process exit code. One place maps verdict -> exit."""
+    if getattr(args, "json", False):
+        print(_result.dumps(res))
+    else:
+        sys.stdout.write(_render.render_human(res, color=getattr(args, "color", None)))
+    return res.exit_code
+
+
+def _add_common(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--json", action="store_true", help="emit the machine result (one object model)")
+    p.add_argument("--events", action="store_true", help="stream NDJSON stage events")
+    p.add_argument("--color", choices=["auto", "always", "never"], default="auto")
+    p.add_argument("-C", "--repo", default=".", help="repo checkout (default: cwd)")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(prog="substratum",
+                                 description="Substratum: verified-or-refused code, with provenance.")
+    # no subcommand -> the persistent session (cmd left None; handled in main)
+    sub = ap.add_subparsers(dest="cmd", required=False)
+    ps = sub.add_parser("session", help="interactive session: warm library, cd-in-and-drive")
+    _add_common(ps)
+
+    for name, help_ in [
+        ("fix", "produce a verified fix for a failing test, or a named refusal"),
+        ("write", "greenfield code from intent (derive-or-refuse; no test required)"),
+        ("verify", "gate a diff (stdin/--diff/--staged/--commit); PASS/FAIL/per-hunk"),
+        ("init", "mine the repo; print the Coverage Contract + flake scan + air-gap attestation"),
+        ("apply", "apply a stored run's verified diff"),
+        ("show", "render a stored run's transcript"),
+        ("replay", "re-execute a stored run; assert byte-identical"),
+        ("attest", "emit a signed evidence bundle for a run"),
+        ("explain", "render the provenance manifest for a run"),
+        ("doctor", "check harness, env, air-gap, effective config"),
+        ("scaffold-test", "emit a runnable failing test pinning a target (the flip engine)"),
+        ("summarize", "describe the codebase in plain English (grounded in real symbols)"),
+        ("runs", "run history + the refusal->verified conversion ledger (the proof store)"),
+        ("undo", "reverse-apply a run (the inverse of apply)"),
+        ("commit", "proof-carrying git commit of a verified, applied run"),
+        ("failing", "run the suite and list failing tests (each becomes a fix target)"),
+    ]:
+        p = sub.add_parser(name, help=help_)
+        _add_common(p)
+        if name in ("fix", "scaffold-test", "failing"):
+            p.add_argument("target", nargs="?", help="failing test id / file::fn / path to scope")
+        if name == "failing":
+            p.add_argument("--test-command", default=None)
+        if name == "fix":
+            p.add_argument("--failing-test", action="append", default=[])
+            p.add_argument("--intent", default="")
+            p.add_argument("--test-command", default=None)
+        if name == "write":
+            p.add_argument("intent", help="what the code should do, in plain language")
+            p.add_argument("--sig", required=True, help="target signature, e.g. \"clamp(x, lo, hi)\"")
+            p.add_argument("--into", default=None, help="file to write into (default: <name>.py)")
+            p.add_argument("--mean", default=None,
+                           help="disambiguate an ambiguous intent by the plain-English option text")
+        if name == "verify":
+            p.add_argument("target", nargs="?", default="-", help="'-' stdin, or a diff file")
+            p.add_argument("--diff", action="store_true")
+            p.add_argument("--staged", action="store_true")
+            p.add_argument("--commit", default=None)
+            p.add_argument("--test", action="append", default=[])
+            p.add_argument("--test-command", default=None)
+        if name in ("apply", "show", "replay", "attest", "explain", "undo", "commit"):
+            p.add_argument("run_id")
+        if name == "commit":
+            p.add_argument("--message", default=None)
+        if name == "explain":
+            p.add_argument("--line", default=None)
+    return ap
+
+
+def dispatch(args) -> "_result.SubstratumResult":
+    cmd = args.cmd
+    if cmd == "show":
+        from .commands.show import cmd_show
+        return cmd_show(args.repo, args.run_id)
+    # heavy commands land in later milestones; wire as built
+    if cmd == "verify":
+        from .commands.verify import cmd_verify
+        return cmd_verify(args)
+    if cmd == "fix":
+        from .commands.fix import cmd_fix
+        return cmd_fix(args)
+    if cmd == "write":
+        from .commands.write import cmd_write
+        return cmd_write(args)
+    if cmd == "apply":
+        from .commands.apply import cmd_apply
+        return cmd_apply(args.repo, args.run_id)
+    if cmd == "init":
+        from .commands.init_cmd import cmd_init
+        return cmd_init(args.repo)
+    if cmd == "doctor":
+        from .commands.init_cmd import cmd_doctor
+        return cmd_doctor(args.repo)
+    if cmd == "replay":
+        from .commands.replay import cmd_replay
+        return cmd_replay(args.repo, args.run_id)
+    if cmd == "explain":
+        from .commands.explain import cmd_explain
+        return cmd_explain(args.repo, args.run_id, getattr(args, "line", None))
+    if cmd == "attest":
+        from .commands.explain import cmd_attest
+        return cmd_attest(args.repo, args.run_id)
+    if cmd == "scaffold-test":
+        from .commands.scaffold import cmd_scaffold_test
+        return cmd_scaffold_test(args.repo, getattr(args, "target", None) or "")
+    if cmd == "summarize":
+        from . import product_ops
+        return product_ops.op_summarize_repo(args.repo)
+    if cmd == "runs":
+        from .commands.history import cmd_runs
+        return cmd_runs(args.repo)
+    if cmd == "undo":
+        from .commands.undo import cmd_undo
+        return cmd_undo(args.repo, args.run_id)
+    if cmd == "commit":
+        from .commands.commit import cmd_commit
+        return cmd_commit(args.repo, args.run_id, getattr(args, "message", None))
+    if cmd == "failing":
+        from .commands.failing import cmd_failing
+        return cmd_failing(args.repo, path=getattr(args, "target", None),
+                           test_command=getattr(args, "test_command", None))
+    # not-yet-built commands: a clean, honest not-implemented refusal (never a crash)
+    return _result.make(codes.UNVERIFIABLE, "sub_000000000000", cmd,
+                        code=codes.NO_DRIVER,
+                        refusal=_not_built(cmd))
+
+
+def _not_built(cmd: str):
+    from . import refusals
+    return refusals.build(codes.NO_DRIVER, engine_code="NOT_IMPLEMENTED",
+                          ctx={"target": cmd})
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    argv = list(argv if argv is not None else sys.argv[1:])
+    # no arguments, or `session` -> the persistent interactive session
+    if not argv or argv[0] == "session":
+        from .session import run_session
+        repo = "."
+        rest = argv[1:] if argv and argv[0] == "session" else argv
+        if "-C" in rest:
+            i = rest.index("-C")
+            repo = rest[i + 1] if i + 1 < len(rest) else "."
+        elif "--repo" in rest:
+            i = rest.index("--repo")
+            repo = rest[i + 1] if i + 1 < len(rest) else "."
+        color = "--color" not in rest or "never" not in rest
+        return run_session(repo, color=color)
+    # account verbs are global (no repo, print directly) -- handled before the repo-based parser
+    if argv[0] in ("login", "logout", "whoami"):
+        from .commands import auth
+        return {"login": auth.cmd_login, "logout": auth.cmd_logout,
+                "whoami": auth.cmd_whoami}[argv[0]]()
+    ap = build_parser()
+    try:
+        args = ap.parse_args(argv)
+    except SystemExit as e:
+        return int(e.code) if e.code is not None else codes.EXIT_USAGE
+    try:
+        res = dispatch(args)
+    except Exception as exc:  # internal fault -> exit 1, never a refusal code
+        sys.stderr.write(f"substratum: internal error: {exc}\n")
+        return codes.EXIT_INTERNAL
+    return _emit(res, args)

substratum_cli/codes.py

@@ -0,0 +1,114 @@
+"""Closed-class verdicts, refusal codes, the exit-code table, and the engine-code mapping.
+
+This is the single source of truth for the CLI contract. Nothing here imports the engine.
+
+The exit-code ranges ARE the machine API (a script or the VS Code layer branches on the
+process exit / the in-band `exit_code` field without parsing text):
+
+    0        VERIFIED | PASS        the gate proved it
+    10-19    refusal classes        a named, deliberate non-answer (never a crash)
+    20       FAIL                   a diff was proven WRONG by the gate
+    1        internal error         the tool itself broke
+    2        usage error            bad arguments
+
+A refusal is a deliverable, so it NEVER shares the exit code of a crash (1). Cyan, not red.
+"""
+from __future__ import annotations
+
+# ---- verdicts (closed) -------------------------------------------------------
+VERIFIED = "VERIFIED"
+PASS = "PASS"
+FAIL = "FAIL"
+REFUSED = "REFUSED"
+UNVERIFIABLE = "UNVERIFIABLE"
+VERDICTS = (VERIFIED, PASS, FAIL, REFUSED, UNVERIFIABLE)
+
+# ---- refusal codes (closed class; ~a dozen) ----------------------------------
+# Each maps to exactly one exit code in EXIT_CODES below. Grouped by exit class.
+NO_GROUNDED_CANDIDATE = "NO_GROUNDED_CANDIDATE"      # 10: coverage absent for this request
+GATE_PRECONDITION = "GATE_PRECONDITION"             # 11: the gate could not be run cleanly
+NO_WARRANT_TESTS = "NO_WARRANT_TESTS"               # 11: verify with no tests to gate against
+HUNK_CONTEXT_STALE = "HUNK_CONTEXT_STALE"           # 11: a diff hunk does not apply to base
+APPLY_STATE_DRIFT = "APPLY_STATE_DRIFT"             # 11: apply/replay: HEAD moved under the run
+REPLAY_STATE_DRIFT = "REPLAY_STATE_DRIFT"           # 11
+NO_DRIVER = "NO_DRIVER"                             # 12: no gate runner / no filetype driver
+AUTONOMY_LOCKED = "AUTONOMY_LOCKED"                 # 12: an L2/L3 action attempted at L1
+UNDERDETERMINED_INTENT = "UNDERDETERMINED_INTENT"   # 13: candidates composed, all failed the gate
+FLAKY_OR_VACUOUS_WARRANT = "FLAKY_OR_VACUOUS_WARRANT"  # 14: tests pass at base (nothing to fix / flaky)
+FLAKY_TEST = "FLAKY_TEST"                           # 14: quarantined nondeterministic test
+RUN_NOT_FOUND = "RUN_NOT_FOUND"                     # 11: show/explain/replay on an unknown id
+NO_ENGINE = "NO_ENGINE"                             # 12: synthesis needs the engine; login or [engine]
+
+REFUSAL_CODES = (
+    NO_GROUNDED_CANDIDATE, GATE_PRECONDITION, NO_WARRANT_TESTS, HUNK_CONTEXT_STALE,
+    APPLY_STATE_DRIFT, REPLAY_STATE_DRIFT, NO_DRIVER, AUTONOMY_LOCKED,
+    UNDERDETERMINED_INTENT, FLAKY_OR_VACUOUS_WARRANT, FLAKY_TEST, RUN_NOT_FOUND,
+    NO_ENGINE,
+)
+
+# ---- the exit-code table (closed; the machine contract) ----------------------
+EXIT_OK = 0
+EXIT_FAIL = 20
+EXIT_INTERNAL = 1
+EXIT_USAGE = 2
+
+_REFUSAL_EXIT = {
+    NO_GROUNDED_CANDIDATE: 10,
+    GATE_PRECONDITION: 11,
+    NO_WARRANT_TESTS: 11,
+    HUNK_CONTEXT_STALE: 11,
+    APPLY_STATE_DRIFT: 11,
+    REPLAY_STATE_DRIFT: 11,
+    RUN_NOT_FOUND: 11,
+    NO_DRIVER: 12,
+    AUTONOMY_LOCKED: 12,
+    NO_ENGINE: 12,
+    UNDERDETERMINED_INTENT: 13,
+    FLAKY_OR_VACUOUS_WARRANT: 14,
+    FLAKY_TEST: 14,
+}
+
+
+def exit_code_for(verdict: str, code: str | None) -> int:
+    """The one place verdict+code -> process exit. Total over the closed classes."""
+    if verdict in (VERIFIED, PASS):
+        return EXIT_OK
+    if verdict == FAIL:
+        return EXIT_FAIL
+    if verdict in (REFUSED, UNVERIFIABLE):
+        return _REFUSAL_EXIT.get(code or "", 10)   # unknown refusal -> the generic 10
+    return EXIT_INTERNAL
+
+
+# ---- engine-code -> CLI refusal code (the single mapping door) ----------------
+# Engine/gate codes (client_gate.ClientGateResult.code, resolve_files refusal_sink codes,
+# substrate_query trace statuses) are translated here and NOWHERE else. Unknown engine
+# codes map to GATE_PRECONDITION with the raw code preserved by the caller (refuse-on-unknown,
+# never invent a template).
+_ENGINE_TO_CLI = {
+    # client_gate closed set
+    "PASS": None,                                   # not a refusal
+    "TEST_FAILED": None,                            # -> FAIL verdict, handled by caller
+    "GATE_TESTS_PASS_AT_BASE": FLAKY_OR_VACUOUS_WARRANT,
+    "GATE_NO_RUNNER": NO_DRIVER,
+    "GATE_WORKTREE_FAILED": GATE_PRECONDITION,
+    "GATE_BASE_ERROR": GATE_PRECONDITION,
+    "GATE_ERROR": GATE_PRECONDITION,
+    "GATE_TIMEOUT": GATE_PRECONDITION,
+    # substrate_query / resolve_files trace + refusal_sink
+    "no_candidate": NO_GROUNDED_CANDIDATE,
+    "candidate_failed_verify": UNDERDETERMINED_INTENT,
+    "candidate_failed_execution_gate": UNDERDETERMINED_INTENT,
+    "no_op_candidate": NO_GROUNDED_CANDIDATE,
+}
+
+
+def map_engine_code(engine_code: str) -> str:
+    """Translate a raw engine/gate code to a CLI refusal code. NONCODE_NO_DRIVER(...) and
+    NONCODE_TOOLCHAIN_OWNED(...) are prefix-matched. Unknown -> GATE_PRECONDITION."""
+    if engine_code in _ENGINE_TO_CLI and _ENGINE_TO_CLI[engine_code] is not None:
+        return _ENGINE_TO_CLI[engine_code]
+    if engine_code.startswith(("NONCODE_NO_DRIVER", "NONCODE_TOOLCHAIN_OWNED",
+                               "NONCODE_UNKNOWN_FILETYPE")):
+        return NO_DRIVER
+    return GATE_PRECONDITION

substratum_cli/commands/apply.py

@@ -0,0 +1,49 @@
+"""`substratum apply <run-id>` -- apply a stored run's verified diff. L1 default: apply is
+the ONLY writer. Refuses APPLY_STATE_DRIFT if HEAD has moved since the run was produced."""
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+
+from .. import codes
+from .. import gitio
+from .. import refusals
+from .. import result as _result
+from .. import run_store
+
+
+def cmd_apply(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, "apply", code=codes.RUN_NOT_FOUND,
+                            refusal=refusals.build(codes.RUN_NOT_FOUND,
+                                                   ctx={"target": run_id, "run_id": run_id}))
+    res, inputs = loaded
+    recorded_head = (inputs.get("run_key") or {}).get("head_sha")
+    if recorded_head and gitio.head_sha(repo) != recorded_head:
+        return _result.make(codes.REFUSED, run_id, "apply", code=codes.APPLY_STATE_DRIFT,
+                            refusal=refusals.build(codes.APPLY_STATE_DRIFT,
+                                                   ctx={"target": run_id, "run_id": run_id}))
+    if not res.diff.strip():
+        return _result.make(codes.REFUSED, run_id, "apply", code=codes.NO_GROUNDED_CANDIDATE,
+                            refusal=refusals.build(codes.NO_GROUNDED_CANDIDATE,
+                                                   ctx={"target": run_id, "run_id": run_id}))
+    with tempfile.NamedTemporaryFile("w", suffix=".patch", delete=False) as fh:
+        fh.write(res.diff)
+        patch = fh.name
+    try:
+        r = subprocess.run(["git", "-C", repo, "apply", "--index", patch],
+                           capture_output=True, text=True)
+        if r.returncode != 0:
+            r2 = subprocess.run(["git", "-C", repo, "apply", "--3way", patch],
+                                capture_output=True, text=True)
+            if r2.returncode != 0:
+                return _result.make(codes.REFUSED, run_id, "apply", code=codes.APPLY_STATE_DRIFT,
+                                    refusal=refusals.build(codes.APPLY_STATE_DRIFT,
+                                                           ctx={"target": run_id, "run_id": run_id}))
+    finally:
+        os.unlink(patch)
+    return _result.make(codes.PASS, run_id, "apply", files=res.files,
+                        data={"applied": list(res.files)})