substratum-cli 0.1.0__py3-none-any.whl

substratum_cli/commands/verify.py

@@ -0,0 +1,193 @@
+"""`substratum verify` -- gate ANY diff (Cursor/Copilot output, a paste, a commit). The wedge.
+
+Reads a unified diff from stdin/-/--diff/--staged/--commit, materializes it against the base,
+runs the differential client gate (fail-at-base -> pass-with-patch), and for a multi-file diff
+attributes a per-hunk verdict. The gate proves BEHAVIOR, never authorship -- the `note:` line
+keeps that honest. This command leaf-loads client_gate; it never pays the numpy chain.
+"""
+from __future__ import annotations
+
+import os
+import sys
+from typing import Optional
+
+from .. import codes
+from .. import diffs
+from .. import engine
+from .. import gitio
+from .. import refusals
+from .. import result as _result
+from .. import run_store
+from .. import runid
+
+
+def _read_diff(args) -> str:
+    if args.staged:
+        return gitio.staged_diff(os.path.abspath(args.repo))
+    if args.commit:
+        return gitio.commit_diff(os.path.abspath(args.repo), args.commit)
+    src = getattr(args, "target", "-") or "-"
+    if args.diff or (src != "-" and os.path.isfile(src)):
+        path = src if src != "-" else None
+        if path:
+            return open(path, encoding="utf-8", errors="replace").read()
+    return sys.stdin.read()
+
+
+def _base_content(repo: str, base: str, path: str) -> str:
+    return gitio.show(repo, base, path) or ""
+
+
+def cmd_verify(args) -> "_result.SubstratumResult":
+    repo = os.path.abspath(args.repo)
+    if not gitio.is_git_repo(repo):
+        rid, _ = runid.compute(repo, "verify", {"err": "not_git"})
+        return _result.make(codes.REFUSED, rid, "verify", code=codes.GATE_PRECONDITION,
+                            refusal=refusals.build(codes.GATE_PRECONDITION,
+                                                   ctx={"target": repo, "run_id": rid}))
+    base = args.commit + "~1" if args.commit else gitio.head_sha(repo)
+    diff_text = _read_diff(args)
+    return run_verify(repo, diff_text, tuple(args.test or ()), base=base,
+                      test_command=args.test_command)
+
+
+def run_verify(repo, diff_text, tests, base=None, test_command=None):
+    """The verify core, callable directly (the session gates the working diff with this)."""
+    repo = os.path.abspath(repo)
+    tests = tuple(tests or ())
+    if base is None:
+        base = gitio.head_sha(repo)
+    rid, key = runid.compute(repo, "verify",
+                             {"diff_sha": _sha(diff_text), "tests": sorted(tests),
+                              "base": base, "test_cmd": test_command})
+
+    files = diffs.parse(diff_text)
+    if not files:
+        return _store(repo, _result.make(codes.REFUSED, rid, "verify",
+                      code=codes.NO_WARRANT_TESTS,
+                      refusal=refusals.build(codes.NO_WARRANT_TESTS,
+                                             ctx={"target": "the diff", "run_id": rid})), key)
+    if not tests:
+        return _store(repo, _result.make(codes.UNVERIFIABLE, rid, "verify",
+                      code=codes.NO_WARRANT_TESTS,
+                      refusal=refusals.build(codes.NO_WARRANT_TESTS,
+                                             ctx={"target": files[0].path, "run_id": rid})), key)
+
+    base_by_path = {f.path: _base_content(repo, base, f.path) for f in files}
+    edits, stale = diffs.materialize(base_by_path, files)
+    if not edits:
+        return _store(repo, _result.make(codes.UNVERIFIABLE, rid, "verify",
+                      code=codes.HUNK_CONTEXT_STALE,
+                      refusal=refusals.build(codes.HUNK_CONTEXT_STALE,
+                                             ctx={"target": ", ".join(stale), "run_id": rid})), key)
+
+    # ---- headline gate: the whole diff, differential ----
+    sink: dict = {}
+    cg = engine.client_gate.run_client_gate(repo, base, edits, test_paths=list(tests),
+                                            test_cmd=test_command, differential=True,
+                                            transcript_sink=sink)
+    gate = _gate_transcript(sink, tests, cg)
+
+    if cg.code == "GATE_TESTS_PASS_AT_BASE":
+        return _store(repo, _result.make(codes.REFUSED, rid, "verify",
+                      code=codes.FLAKY_OR_VACUOUS_WARRANT, gate=gate,
+                      refusal=refusals.build(codes.FLAKY_OR_VACUOUS_WARRANT,
+                                             ctx={"target": ", ".join(tests), "run_id": rid},
+                                             verified_before=(f"base run: {gate.base_status}",))), key)
+    if not cg.passed and cg.code != "TEST_FAILED":
+        ref = refusals.from_engine(cg.code, ctx={"target": ", ".join(tests), "run_id": rid})
+        return _store(repo, _result.make(codes.UNVERIFIABLE, rid, "verify",
+                      code=ref.code, gate=gate, refusal=ref), key)
+
+    # ---- per-hunk attribution (multi-file / multi-hunk) ----
+    hunks_verdicts = _attribute(repo, base, base_by_path, files, edits, tests,
+                                test_command, whole_passed=cg.passed)
+    note = "this verdict gates the DIFF, not its provenance (external code)."
+    if cg.passed:
+        verdict, code = codes.PASS, None
+    else:
+        verdict, code = codes.FAIL, None  # TEST_FAILED -> diff proven wrong
+    res = _result.make(verdict, rid, "verify", code=code, gate=gate,
+                       files=tuple(sorted(edits)), hunks=tuple(hunks_verdicts),
+                       data={"note": note, "stale": stale})
+    return _store(repo, res, key)
+
+
+def _attribute(repo, base, base_by_path, files, edits, tests, test_cmd, whole_passed):
+    """Per-file leave-one-out (whole passed) or singleton (whole failed) attribution, budgeted."""
+    out = []
+    multi = sum(len(f.hunks) for f in files) > 1
+    if not multi:
+        f = files[0]
+        out.append(_result.HunkVerdict(f.path, 0, f.hunks[0].header,
+                                       codes.PASS if whole_passed else codes.FAIL))
+        return out
+    budget = 8
+    runs = 0
+    for f in files:
+        if f.path not in edits:
+            out.append(_result.HunkVerdict(f.path, 0, "stale", codes.UNVERIFIABLE,
+                                           code=codes.HUNK_CONTEXT_STALE,
+                                           next_command=f"substratum scaffold-test {f.path}"))
+            continue
+        if runs >= budget:
+            out.append(_result.HunkVerdict(f.path, 0, f.hunks[0].header,
+                                           codes.PASS if whole_passed else codes.UNVERIFIABLE,
+                                           code=None if whole_passed else codes.UNDERDETERMINED_INTENT))
+            continue
+        if whole_passed:
+            minus = {p: c for p, c in edits.items() if p != f.path}
+            runs += 1
+            cg = engine.client_gate.run_client_gate(repo, base, minus, test_paths=list(tests),
+                                                    test_cmd=test_cmd, differential=True)
+            # ablation FAILS tests -> this file is load-bearing -> PASS
+            load_bearing = (not cg.passed and cg.code == "TEST_FAILED")
+            out.append(_result.HunkVerdict(
+                f.path, 0, f.hunks[0].header,
+                codes.PASS if load_bearing else codes.UNVERIFIABLE,
+                code=None if load_bearing else codes.UNDERDETERMINED_INTENT,
+                next_command=None if load_bearing else f"substratum scaffold-test {f.path}"))
+        else:
+            only = {f.path: edits[f.path]}
+            runs += 1
+            cg = engine.client_gate.run_client_gate(repo, base, only, test_paths=list(tests),
+                                                    test_cmd=test_cmd, differential=True)
+            if cg.passed:
+                out.append(_result.HunkVerdict(f.path, 0, f.hunks[0].header, codes.PASS))
+            elif cg.code == "TEST_FAILED":
+                out.append(_result.HunkVerdict(f.path, 0, f.hunks[0].header, codes.FAIL))
+            else:
+                out.append(_result.HunkVerdict(f.path, 0, f.hunks[0].header, codes.UNVERIFIABLE,
+                                               code=codes.map_engine_code(cg.code)))
+    return out
+
+
+def _gate_transcript(sink: dict, tests, cg) -> "_result.GateTranscript":
+    base_rc = sink.get("base_rc")
+    patched_rc = sink.get("patched_rc")
+    return _result.GateTranscript(
+        kind="client_differential", test_ids=tuple(tests),
+        runner_command=tuple(sink.get("runner_command", ())),
+        base_status=_status(base_rc, at_base=True),
+        patched_status=_status(patched_rc, at_base=False),
+        base_excerpt=(sink.get("base_out", "") or "")[-800:],
+        patched_excerpt=(sink.get("patched_out", "") or "")[-800:],
+    )
+
+
+def _status(rc: Optional[int], at_base: bool) -> str:
+    if rc is None:
+        return ""
+    if at_base:
+        return "FAIL" if rc != 0 else "PASS"
+    return "PASS" if rc == 0 else "FAIL"
+
+
+def _store(repo, res, key):
+    run_store.store_run(repo, res, run_key=key)
+    return res
+
+
+def _sha(text: str) -> str:
+    import hashlib
+    return hashlib.sha256(text.encode("utf-8", "replace")).hexdigest()[:16]

substratum_cli/commands/write.py

@@ -0,0 +1,42 @@
+"""`substratum write "<intent>" --sig "name(args)"` -- greenfield code from intent.
+
+Derivation, not generation: the intent is comprehended, the construction is derived from the
+granular productions + grounding, verified intrinsically, and emitted or refused. No test is
+required and none determines the answer -- resolve iff the intent is fully understood and the
+construction is derivable, else a named refusal. Thin over product_ops.op_write_from_intent."""
+from __future__ import annotations
+
+import os
+import sys
+
+from .. import codes
+from .. import gitio
+from .. import refusals
+from .. import result as _result
+
+
+def cmd_write(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", "write",
+                            code=codes.GATE_PRECONDITION,
+                            refusal=refusals.build(codes.GATE_PRECONDITION,
+                                                   ctx={"target": repo, "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_write_from_intent(
+        repo, intent, getattr(args, "sig", ""), into=getattr(args, "into", None), emit=emit,
+        prefer_purpose=getattr(args, "mean", None))

substratum_cli/config.py

@@ -0,0 +1,49 @@
+"""`.substratum.toml` reader. Autonomy ladder: L1 Suggest is the default (print, never write;
+apply is the only writer). L2/L3 are PARSED but LOCKED in v1 -- an L2/L3 action refuses
+AUTONOMY_LOCKED. Config keys: autonomy, output, drivers, limits. Stdlib tomllib only."""
+from __future__ import annotations
+
+import os
+
+try:
+    import tomllib  # py3.11+
+except ModuleNotFoundError:  # pragma: no cover
+    tomllib = None
+
+_DEFAULTS = {
+    "autonomy": {"level": "L1", "automerge_classes": []},
+    "output": {"refusal_verbosity": "always"},
+    "drivers": {},
+    "limits": {"attempts_per_target": 3, "runner_timeout": 600, "max_gate_runs": 8},
+}
+
+
+def load(repo: str) -> dict:
+    cfg = {k: dict(v) if isinstance(v, dict) else v for k, v in _DEFAULTS.items()}
+    path = os.path.join(repo, ".substratum.toml")
+    if tomllib and os.path.exists(path):
+        try:
+            with open(path, "rb") as fh:
+                user = tomllib.load(fh)
+            for section, vals in user.items():
+                if section in cfg and isinstance(cfg[section], dict) and isinstance(vals, dict):
+                    cfg[section].update(vals)
+                else:
+                    cfg[section] = vals
+        except Exception:
+            pass
+    return cfg
+
+
+def autonomy_level(repo: str) -> str:
+    return str(load(repo).get("autonomy", {}).get("level", "L1")).upper()
+
+
+def is_write_allowed(repo: str, action: str) -> bool:
+    """L1: only `apply` (an explicit user action) writes. L2/L3 are locked in v1."""
+    level = autonomy_level(repo)
+    if action == "apply":
+        return True                 # apply is always an explicit, user-invoked write
+    if level in ("L2", "L3"):
+        return False                # visible-but-locked: the config declares ambition, not power
+    return False

substratum_cli/diffs.py

@@ -0,0 +1,106 @@
+"""Unified-diff parsing into per-file hunks, and materialization of patched whole-file content
+(the gate takes {path: content}, not hunks). Stdlib only."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+
+_FILE_RE = re.compile(r"^\+\+\+ b/(.+)$")
+_HUNK_RE = re.compile(r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@")
+
+
+@dataclass
+class Hunk:
+    header: str
+    old_start: int
+    old_len: int
+    new_start: int
+    new_len: int
+    lines: List[str] = field(default_factory=list)   # with leading ' '/'+'/'-'
+
+
+@dataclass
+class FileDiff:
+    path: str
+    hunks: List[Hunk] = field(default_factory=list)
+
+
+def parse(diff_text: str) -> List[FileDiff]:
+    files: List[FileDiff] = []
+    cur: Optional[FileDiff] = None
+    cur_hunk: Optional[Hunk] = None
+    for line in diff_text.splitlines():
+        m = _FILE_RE.match(line)
+        if m:
+            cur = FileDiff(path=m.group(1))
+            files.append(cur)
+            cur_hunk = None
+            continue
+        if line.startswith("--- ") or line.startswith("diff --git") or line.startswith("index "):
+            continue
+        hm = _HUNK_RE.match(line)
+        if hm and cur is not None:
+            cur_hunk = Hunk(header=line,
+                            old_start=int(hm.group(1)), old_len=int(hm.group(2) or 1),
+                            new_start=int(hm.group(3)), new_len=int(hm.group(4) or 1))
+            cur.hunks.append(cur_hunk)
+            continue
+        if cur_hunk is not None and (not line or line[0] in " +-\\"):
+            cur_hunk.lines.append(line)
+    return [f for f in files if f.hunks]
+
+
+def apply_hunks(base_content: str, hunks: List[Hunk]) -> Optional[str]:
+    """Apply hunks to base with EXACT context matching. Returns new content, or None if any
+    hunk's context does not match (context stale -> the caller refuses, never fuzzes)."""
+    base_lines = base_content.splitlines(keepends=False)
+    out: List[str] = []
+    cursor = 0  # index into base_lines already consumed
+    for h in sorted(hunks, key=lambda x: x.old_start):
+        start = h.old_start - 1  # 0-indexed
+        if start < cursor or start > len(base_lines):
+            return None
+        out.extend(base_lines[cursor:start])
+        bi = start
+        for dl in h.lines:
+            if not dl:
+                # blank context line
+                if bi < len(base_lines) and base_lines[bi] == "":
+                    out.append("")
+                    bi += 1
+                continue
+            tag, text = dl[0], dl[1:]
+            if tag == " ":
+                if bi >= len(base_lines) or base_lines[bi] != text:
+                    return None
+                out.append(text)
+                bi += 1
+            elif tag == "-":
+                if bi >= len(base_lines) or base_lines[bi] != text:
+                    return None
+                bi += 1
+            elif tag == "+":
+                out.append(text)
+            elif tag == "\\":
+                pass  # ""
+        cursor = bi
+    out.extend(base_lines[cursor:])
+    trailing = "\n" if base_content.endswith("\n") else ""
+    return "\n".join(out) + trailing
+
+
+def materialize(base_by_path: Dict[str, str],
+                files: List[FileDiff]) -> Tuple[Dict[str, str], List[str]]:
+    """{path: patched content} for every file whose hunks apply cleanly; the second list is
+    paths with stale context (excluded, never fuzzed)."""
+    edits: Dict[str, str] = {}
+    stale: List[str] = []
+    for f in files:
+        base = base_by_path.get(f.path, "")
+        new = apply_hunks(base, f.hunks)
+        if new is None:
+            stale.append(f.path)
+        else:
+            edits[f.path] = new
+    return edits, stale

substratum_cli/engine.py

@@ -0,0 +1,154 @@
+"""The lazy engine bridge -- the ONLY module in substratum_cli that reaches into backend.*.
+
+The import bomb: `backend/substratum_v2/__init__.py` eagerly imports the numpy-heavy claim
+pipeline, so a normal `from backend...` costs that chain (and dies without numpy). Two
+strategies keep light commands fast and numpy-free:
+
+1. LEAF LOAD by file path (importlib.util.spec_from_file_location) for modules verified to be
+   stdlib-only with NO relative imports: `client_gate.py`, `lib_roots.py`. These are loaded
+   without ever executing any `backend` package __init__, so `verify` and run-id hashing pay
+   nothing.
+2. HEAVY IMPORT via the normal package path, done INSIDE the fix code path only, after the
+   first progress event has streamed (the user sees GROUND before the seconds-scale import).
+
+Every attribute here is a lazy accessor; importing this module opens nothing.
+"""
+from __future__ import annotations
+
+import importlib.util
+import os
+import sys
+from types import ModuleType
+
+REPO_ROOT = os.environ.get("SUBSTRATUM_ENGINE_ROOT", "/home/thepadrevictor/Substratum")
+_ENGINE_DIR = os.path.join(REPO_ROOT, "backend", "substratum_v2", "code_generation_v2")
+_LEAF_CACHE: dict[str, ModuleType] = {}
+
+
+def _leaf(name: str) -> ModuleType:
+    """Load `<engine>/<name>.py` in isolation (no backend __init__), cached."""
+    if name in _LEAF_CACHE:
+        return _LEAF_CACHE[name]
+    path = os.path.join(_ENGINE_DIR, f"{name}.py")
+    spec = importlib.util.spec_from_file_location(f"_substratum_leaf_{name}", path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"cannot leaf-load {path}")
+    mod = importlib.util.module_from_spec(spec)
+    # register so dataclasses/pickling inside the module resolve their own module name
+    sys.modules[spec.name] = mod
+    spec.loader.exec_module(mod)
+    _LEAF_CACHE[name] = mod
+    return mod
+
+
+class _LazyAttr:
+    """Access `.foo` -> leaf-load module `name` and return its `foo` (or the module if attr=None)."""
+    def __init__(self, name: str):
+        self._name = name
+
+    def __getattr__(self, attr: str):
+        return getattr(_leaf(self._name), attr)
+
+
+# ---- leaf modules (fast, numpy-free) ----
+client_gate = _LazyAttr("client_gate")     # run_client_gate, resolve_test_command, ClientGateResult
+lib_roots = _LazyAttr("lib_roots")         # py_/go_/ts_library_root, defaults
+
+
+def coverage_registries() -> dict:
+    """The LIVE driver registries for the Coverage Contract, read from the engine (not copied,
+    so no drift). All leaf-loaded -> zero numpy. Returns the extension buckets."""
+    nc = _leaf("noncode_drivers")
+    out = {"driven_noncode": set(getattr(nc, "_DRIVERS", {}).keys()),
+           "template_exts": set(), "known_undriven": set(getattr(nc, "_KNOWN_UNDRIVEN", ())),
+           "code_langs": {".py": "py", ".go": "go", ".ts": "ts", ".tsx": "ts",
+                          ".js": "ts", ".jsx": "ts"}}
+    try:
+        out["driven_noncode"] |= set(getattr(_leaf("struct_resolve"), "STRUCT_EXTS", ()))
+    except Exception:
+        pass
+    try:
+        out["template_exts"] = set(getattr(_leaf("template_resolve"), "TEMPLATE_EXTS", ()))
+    except Exception:
+        pass
+    return out
+
+
+def canonical_diff():
+    """canonical_diff_builder.build_file_diff -- audited for import-cleanliness at call time;
+    falls back to the heavy package path if it has relative imports."""
+    try:
+        return _leaf("canonical_diff_builder").build_file_diff
+    except Exception:
+        _ensure_repo_on_path()
+        from backend.substratum_v2.code_generation_v2.canonical_diff_builder import build_file_diff
+        return build_file_diff
+
+
+# ---- heavy path (numpy chain paid here, inside the fix op only) ----
+def _ensure_repo_on_path():
+    if REPO_ROOT not in sys.path:
+        sys.path.insert(0, REPO_ROOT)
+
+
+def available() -> bool:
+    """Is the heavy engine importable here? A client-only (`pip install substratum-cli`) install
+    has no numpy, so numpy is the cheap discriminator between the thin client and a full engine
+    checkout. When False, the fix/write local path refuses cleanly instead of crashing."""
+    try:
+        import numpy  # noqa: F401
+        return os.path.isdir(_ENGINE_DIR)
+    except Exception:
+        return False
+
+
+_HEAVY: dict | None = None
+_LIB_CACHE: dict[str, object] = {}
+
+
+def heavy():
+    """Return a namespace of the heavy fix-path symbols. Pays the numpy chain ONCE per
+    process (cached), so a persistent session reuses the imports across every command."""
+    global _HEAVY
+    if _HEAVY is None:
+        _ensure_repo_on_path()
+        from backend.substratum_v2.code_generation_v2 import substrates  # noqa: F401 (populates the registry)
+        from backend.substratum_v2.code_generation_v2.substrate_query import (
+            FixRequest, run_substrate_query)
+        from backend.substratum_v2.code_generation_v2.pattern_library_lazy import load_library_lazy
+        from backend.substratum_v2.code_generation_v2.v0_synth_entry import (
+            synthesize, synthesize_from_intent)
+        _HEAVY = {
+            "FixRequest": FixRequest,
+            "run_substrate_query": run_substrate_query,
+            "load_library_lazy": load_library_lazy,
+            "synthesize": synthesize,
+            "synthesize_from_intent": synthesize_from_intent,
+        }
+    return _HEAVY
+
+
+def load_library_cached(lib_root: str):
+    """Load the library resident index ONCE per (process, root). The lazy loader hydrates
+    patterns on demand and keeps its own LRU, so a warm session pays the resident load once
+    and reuses hydration across every fix. This is the warm-library win."""
+    if lib_root not in _LIB_CACHE:
+        _LIB_CACHE[lib_root] = heavy()["load_library_lazy"](lib_root)
+    return _LIB_CACHE[lib_root]
+
+
+def is_warm(lib_root: str | None = None) -> bool:
+    if lib_root is None:
+        lib_root = lib_roots.py_library_root()
+    return bool(_HEAVY is not None and lib_root and lib_root in _LIB_CACHE)
+
+
+def warm(lib_root: str | None = None) -> bool:
+    """Preload the heavy imports + the library so the first fix in a session is fast.
+    Safe to call from a background thread at session start."""
+    if lib_root is None:
+        lib_root = lib_roots.py_library_root()
+    if not lib_root:
+        return False
+    load_library_cached(lib_root)
+    return True

substratum_cli/gitio.py

@@ -0,0 +1,102 @@
+"""Read-only git helpers. Stdlib + the `git` binary only; never writes to the object DB
+except `git hash-object` WITHOUT -w (which computes a hash without storing)."""
+from __future__ import annotations
+
+import subprocess
+from typing import List, Optional
+
+
+def _git(repo: str, *args: str, timeout: int = 60) -> subprocess.CompletedProcess:
+    return subprocess.run(["git", "-C", repo, *args], capture_output=True, text=True,
+                          timeout=timeout)
+
+
+def is_git_repo(repo: str) -> bool:
+    import os
+    return os.path.isdir(os.path.join(repo, ".git")) or \
+        _git(repo, "rev-parse", "--git-dir").returncode == 0
+
+
+def apply_reverse(repo: str, diff_text: str) -> tuple[bool, str]:
+    """Reverse-apply a stored diff (the exact inverse of `substratum apply`). Returns (ok, message).
+    Uses --3way so it undoes even if surrounding lines moved; refuses cleanly if it can't."""
+    if not diff_text.strip():
+        return False, "empty diff"
+    r = subprocess.run(["git", "-C", repo, "apply", "--reverse", "--3way", "-"],
+                       input=diff_text, capture_output=True, text=True, timeout=60)
+    if r.returncode == 0:
+        return True, "reverted"
+    r2 = subprocess.run(["git", "-C", repo, "apply", "--reverse", "-"],
+                        input=diff_text, capture_output=True, text=True, timeout=60)
+    if r2.returncode == 0:
+        return True, "reverted"
+    err = (r.stderr or r2.stderr or "").strip().splitlines()
+    return False, (err[-1] if err else "could not reverse-apply (the files changed since apply)")
+
+
+def commit_files(repo: str, files, message: str) -> tuple[bool, str]:
+    """Stage the given files and commit them with `message`. Returns (ok, short_sha_or_error).
+    Uses the repo's own git author config (never Substratum's)."""
+    files = list(files or [])
+    if not files:
+        return False, "no files to commit"
+    add = _git(repo, "add", "--", *files)
+    if add.returncode != 0:
+        return False, (add.stderr or "git add failed").strip()
+    c = _git(repo, "commit", "-m", message, "--", *files)
+    if c.returncode != 0:
+        return False, (c.stderr or c.stdout or "git commit failed").strip().splitlines()[-1] \
+            if (c.stderr or c.stdout) else "git commit failed"
+    sha = _git(repo, "rev-parse", "--short", "HEAD")
+    return True, sha.stdout.strip() if sha.returncode == 0 else "committed"
+
+
+def head_sha(repo: str) -> str:
+    return _git(repo, "rev-parse", "HEAD").stdout.strip()
+
+
+def show(repo: str, commit: str, path: str) -> Optional[str]:
+    r = _git(repo, "show", f"{commit}:{path}")
+    return r.stdout if r.returncode == 0 else None
+
+
+def diff_head(repo: str) -> str:
+    """Tracked modifications (staged + unstaged) vs HEAD, as text bytes for hashing."""
+    return _git(repo, "diff", "HEAD", "--no-color").stdout
+
+
+def staged_diff(repo: str) -> str:
+    return _git(repo, "diff", "--cached", "--no-color").stdout
+
+
+def commit_diff(repo: str, sha: str) -> str:
+    return _git(repo, "show", sha, "--no-color", "--format=").stdout
+
+
+def untracked_files(repo: str) -> List[str]:
+    out = _git(repo, "status", "--porcelain", "-z").stdout
+    files = []
+    for entry in out.split("\0"):
+        if entry.startswith("?? "):
+            files.append(entry[3:])
+    return sorted(files)
+
+
+def hash_object(repo: str, path: str) -> str:
+    """Content hash of a file WITHOUT storing it (no -w). Empty on failure."""
+    r = _git(repo, "hash-object", path)
+    return r.stdout.strip() if r.returncode == 0 else ""
+
+
+def dirty_hash(repo: str) -> str:
+    """A deterministic digest of the working-tree delta vs HEAD: tracked diff + untracked
+    file hashes. 'clean' when there is nothing. No object-DB writes."""
+    import hashlib
+    tracked = diff_head(repo)
+    parts = [tracked]
+    for f in untracked_files(repo):
+        parts.append(f"{f}\0{hash_object(repo, f)}")
+    blob = "\n".join(parts)
+    if not blob.strip():
+        return "clean"
+    return hashlib.sha256(blob.encode("utf-8", "replace")).hexdigest()[:16]