substratum-cli 0.1.0__py3-none-any.whl

substratum_cli/result.py

@@ -0,0 +1,185 @@
+"""SubstratumResult -- the ONE object model every command produces and every surface renders.
+
+Stdlib-only frozen dataclasses (never pydantic; the core must import with zero web deps so
+the CLI stays a static-binary candidate). `to_json_dict()` is the ONLY serializer: its output
+is `--json`, is written to the run store, and is what the VS Code extension consumes. There is
+no second serializer anywhere -- one object, many renderers, no forks.
+
+VERIFIED and REFUSED are equally first-class shapes: a refusal carries as much structured
+value (verified-before-refusing, named code, executable flip) as a verified fix carries
+(diff, provenance, gate transcript), because at thin coverage the refusal is the common case.
+"""
+from __future__ import annotations
+
+import dataclasses
+import json
+from dataclasses import dataclass, field
+from typing import Optional, Tuple
+
+from . import codes
+
+SCHEMA_VERSION = "1"
+
+
+@dataclass(frozen=True)
+class NextCommand:
+    """An executable next step. `command` is copy-pasteable; renderers may offer a "Run" button."""
+    action: str            # closed verbs: scaffold_test | rerun_fix | provide_test_command | repro | show
+    target: str
+    command: str
+
+
+@dataclass(frozen=True)
+class FlipCondition:
+    """How a refusal converts to a verified result, and WHO owns the next move.
+    owner=YOUR-TESTS  -> the developer's actionable debt (add a test pinning X).
+    owner=SUBSTRATUM-COVERAGE -> our gap; never billed as their debt."""
+    owner: str                          # "YOUR-TESTS" | "SUBSTRATUM-COVERAGE"
+    steps: Tuple[NextCommand, ...] = ()
+
+
+@dataclass(frozen=True)
+class Refusal:
+    """The five mandatory elements. A refusal missing any of these is a product bug (CI enforces)."""
+    code: str                           # a codes.REFUSAL_CODES member
+    engine_code: str                    # the raw engine/gate code, preserved for audit
+    why: str
+    verified_before_refusing: Tuple[str, ...]   # e.g. ("reproduced: test FAILS at base", "composed: 6 candidates, all gated out")
+    flip: FlipCondition
+    permanence: str = "Retrying without changing inputs returns this exact refusal."
+
+    def is_complete(self) -> bool:
+        return bool(self.code and self.why and self.flip.owner
+                    and self.flip.steps and self.permanence)
+
+
+@dataclass(frozen=True)
+class GateTranscript:
+    kind: str                           # "client_differential" | "docker" | "scaffold_check"
+    test_ids: Tuple[str, ...] = ()
+    runner_command: Tuple[str, ...] = ()
+    base_status: str = ""               # "FAIL" (required for differential) | "PASS" | "ERROR" | ...
+    patched_status: str = ""
+    base_excerpt: str = ""
+    patched_excerpt: str = ""
+    worktree_isolated: bool = True
+    impacted: Optional[dict] = None      # {"tests_run": N, "regressions": 0} or None until run
+
+
+@dataclass(frozen=True)
+class Provenance:
+    entries: Tuple[str, ...] = ()        # SubstrateCandidate.provenance verbatim
+    pattern_id: Optional[str] = None
+    corpus_support: Optional[int] = None
+
+
+@dataclass(frozen=True)
+class HunkVerdict:
+    path: str
+    hunk_index: int
+    header: str
+    verdict: str
+    code: Optional[str] = None
+    next_command: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class EngineInfo:
+    engine_version: str = ""
+    library_versions: Tuple[str, ...] = ()
+    egress: str = "none"                 # checked, not claimed (doctor verifies)
+
+
+@dataclass(frozen=True)
+class SubstratumResult:
+    verdict: str                         # a codes.VERDICTS member
+    run_id: str
+    operation: str                       # fix | verify | init | scaffold_test | coverage_map | explain | replay | show | apply | doctor
+    code: Optional[str] = None
+    summary: str = ""                    # the first line, "<VERDICT>  run=<id>  [code=<CODE>]"
+    diff: str = ""
+    files: Tuple[str, ...] = ()
+    provenance: Optional[Provenance] = None
+    gate: Optional[GateTranscript] = None
+    refusal: Optional[Refusal] = None
+    hunks: Tuple[HunkVerdict, ...] = ()
+    engine: EngineInfo = field(default_factory=EngineInfo)
+    data: Optional[dict] = None          # command-specific payload (coverage_map/explain/replay)
+    schema_version: str = SCHEMA_VERSION
+
+    @property
+    def exit_code(self) -> int:
+        return codes.exit_code_for(self.verdict, self.code)
+
+    def to_json_dict(self) -> dict:
+        """The ONE serializer. Tuples -> lists; exit_code emitted in-band (so a non-process
+        consumer -- VS Code -- branches without re-deriving it). Stable key order via asdict."""
+        d = dataclasses.asdict(self)
+        d["exit_code"] = self.exit_code
+        return d
+
+
+# ---------------------------------------------------------------------------
+# constructors + the first-line grammar (shared by every surface)
+# ---------------------------------------------------------------------------
+
+def verdict_line(verdict: str, run_id: str, code: Optional[str] = None) -> str:
+    """The machine-parseable first line, identical everywhere:
+        <VERDICT>  run=<id>  [code=<CODE>]
+    Two spaces between fields (the grammar UX_SCOPE pins)."""
+    line = f"{verdict}  run={run_id}"
+    if code:
+        line += f"  code={code}"
+    return line
+
+
+def make(verdict: str, run_id: str, operation: str, **kw) -> SubstratumResult:
+    """Build a result with its summary line filled in from verdict/run_id/code."""
+    code = kw.get("code")
+    summary = verdict_line(verdict, run_id, code)
+    return SubstratumResult(verdict=verdict, run_id=run_id, operation=operation,
+                            summary=summary, **kw)
+
+
+def from_json_dict(d: dict) -> SubstratumResult:
+    """Rehydrate a stored/received result. Tolerant of the extra in-band exit_code key."""
+    d = dict(d)
+    d.pop("exit_code", None)
+    prov = d.get("provenance")
+    gate = d.get("gate")
+    refusal = d.get("refusal")
+    eng = d.get("engine") or {}
+    hunks = d.get("hunks") or ()
+    kw = dict(
+        verdict=d["verdict"], run_id=d["run_id"], operation=d["operation"],
+        code=d.get("code"), summary=d.get("summary", ""), diff=d.get("diff", ""),
+        files=tuple(d.get("files", ())),
+        provenance=(Provenance(entries=tuple(prov.get("entries", ())),
+                               pattern_id=prov.get("pattern_id"),
+                               corpus_support=prov.get("corpus_support")) if prov else None),
+        gate=(GateTranscript(**{**gate, "test_ids": tuple(gate.get("test_ids", ())),
+                                "runner_command": tuple(gate.get("runner_command", ()))})
+              if gate else None),
+        refusal=(_refusal_from(refusal) if refusal else None),
+        hunks=tuple(HunkVerdict(**h) for h in hunks),
+        engine=EngineInfo(engine_version=eng.get("engine_version", ""),
+                          library_versions=tuple(eng.get("library_versions", ())),
+                          egress=eng.get("egress", "none")),
+        data=d.get("data"), schema_version=d.get("schema_version", SCHEMA_VERSION),
+    )
+    return SubstratumResult(**kw)
+
+
+def _refusal_from(r: dict) -> Refusal:
+    flip = r.get("flip") or {}
+    steps = tuple(NextCommand(**s) for s in flip.get("steps", ()))
+    return Refusal(
+        code=r["code"], engine_code=r.get("engine_code", ""), why=r.get("why", ""),
+        verified_before_refusing=tuple(r.get("verified_before_refusing", ())),
+        flip=FlipCondition(owner=flip.get("owner", ""), steps=steps),
+        permanence=r.get("permanence", ""),
+    )
+
+
+def dumps(r: SubstratumResult) -> str:
+    return json.dumps(r.to_json_dict(), indent=2, sort_keys=False)

substratum_cli/run_store.py

@@ -0,0 +1,162 @@
+"""The local proof store: `.substratum/` at the repo root. Every run -- VERIFIED or REFUSED --
+is persisted so it is `substratum show`-able, replayable, and attestable, and so refusals feed
+the conversion ledger. Atomic writes (tmp + rename). No network, no object-DB writes."""
+from __future__ import annotations
+
+import json
+import os
+import time
+from typing import Optional
+
+from . import result as R
+
+
+def store_dir(repo: str) -> str:
+    return os.path.join(repo, ".substratum")
+
+
+def runs_dir(repo: str) -> str:
+    return os.path.join(store_dir(repo), "runs")
+
+
+def run_dir(repo: str, run_id: str) -> str:
+    return os.path.join(runs_dir(repo), run_id)
+
+
+def _atomic_write(path: str, text: str) -> None:
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    tmp = f"{path}.tmp{os.getpid()}"
+    with open(tmp, "w", encoding="utf-8") as fh:
+        fh.write(text)
+    os.replace(tmp, path)
+
+
+def store_run(repo: str, res: "R.SubstratumResult", run_key: Optional[dict] = None,
+              inputs: Optional[dict] = None) -> str:
+    """Write record.json (canonical) + diff.patch + inputs.json (for replay). Returns the dir."""
+    d = run_dir(repo, res.run_id)
+    _atomic_write(os.path.join(d, "record.json"), R.dumps(res))
+    if res.diff:
+        _atomic_write(os.path.join(d, "diff.patch"), res.diff)
+    if run_key is not None or inputs is not None:
+        _atomic_write(os.path.join(d, "inputs.json"),
+                      json.dumps({"run_key": run_key, "inputs": inputs or {}}, indent=2))
+    if res.gate:
+        if res.gate.base_excerpt:
+            _atomic_write(os.path.join(d, "gate", "base.log"), res.gate.base_excerpt)
+        if res.gate.patched_excerpt:
+            _atomic_write(os.path.join(d, "gate", "patched.log"), res.gate.patched_excerpt)
+    if res.verdict in ("REFUSED", "UNVERIFIABLE") and res.refusal:
+        _append_refusal(repo, res)
+    elif res.verdict in ("VERIFIED", "PASS"):
+        _mark_converted(repo, res)
+    return d
+
+
+def _target_of_record(j: dict) -> str:
+    data = j.get("data") or {}
+    if data.get("target"):
+        return str(data["target"])
+    gate = j.get("gate") or {}
+    if gate.get("test_ids"):
+        return ", ".join(gate["test_ids"][:2])
+    if j.get("files"):
+        return ", ".join(j["files"][:2])
+    return j.get("operation", "")
+
+
+def list_runs(repo: str, limit: int = 20) -> list:
+    """Newest-first run history: [{run_id, verdict, operation, code, target, ts}]. The proof store,
+    made visible -- every VERIFIED and every REFUSED, so the developer sees the whole trail."""
+    d = runs_dir(repo)
+    if not os.path.isdir(d):
+        return []
+    out = []
+    for rid in os.listdir(d):
+        rec = os.path.join(d, rid, "record.json")
+        if not os.path.isfile(rec):
+            continue
+        try:
+            j = json.load(open(rec))
+        except Exception:
+            continue
+        out.append({"run_id": j.get("run_id", rid), "verdict": j.get("verdict", ""),
+                    "operation": j.get("operation", ""), "code": j.get("code"),
+                    "target": _target_of_record(j), "ts": os.path.getmtime(rec)})
+    out.sort(key=lambda e: e["ts"], reverse=True)
+    return out[:limit]
+
+
+def run_ids(repo: str) -> list:
+    """All stored run ids (for tab-completion)."""
+    d = runs_dir(repo)
+    if not os.path.isdir(d):
+        return []
+    return [r for r in os.listdir(d) if os.path.isfile(os.path.join(d, r, "record.json"))]
+
+
+def load_run(repo: str, run_id: str) -> Optional[tuple["R.SubstratumResult", dict]]:
+    d = run_dir(repo, run_id)
+    rec = os.path.join(d, "record.json")
+    if not os.path.exists(rec):
+        return None
+    res = R.from_json_dict(json.load(open(rec)))
+    inp = {}
+    ip = os.path.join(d, "inputs.json")
+    if os.path.exists(ip):
+        inp = json.load(open(ip))
+    return res, inp
+
+
+def _refusals_path(repo: str) -> str:
+    return os.path.join(store_dir(repo), "refusals.jsonl")
+
+
+def _target_of(res: "R.SubstratumResult") -> str:
+    """A stable target key so a later VERIFIED can convert an earlier REFUSED: the sorted
+    failing-test ids or the touched files."""
+    q = (res.data or {}).get("target") if res.data else None
+    if q:
+        return str(q)
+    if res.gate and res.gate.test_ids:
+        return "|".join(sorted(res.gate.test_ids))
+    if res.files:
+        return "|".join(sorted(res.files))
+    return res.operation
+
+
+def _append_refusal(repo: str, res: "R.SubstratumResult") -> None:
+    path = _refusals_path(repo)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    rec = {"run_id": res.run_id, "code": res.code, "target": _target_of(res),
+           "flip_owner": res.refusal.flip.owner if res.refusal else "",
+           "converted_to": None, "_ts": int(time.time())}
+    with open(path, "a", encoding="utf-8") as fh:
+        fh.write(json.dumps(rec) + "\n")
+
+
+def _mark_converted(repo: str, res: "R.SubstratumResult") -> None:
+    """A VERIFIED on a target back-fills any unconverted refusal on the same target."""
+    path = _refusals_path(repo)
+    if not os.path.exists(path):
+        return
+    target = _target_of(res)
+    lines = [json.loads(l) for l in open(path) if l.strip()]
+    changed = False
+    for rec in lines:
+        if rec.get("target") == target and rec.get("converted_to") is None:
+            rec["converted_to"] = res.run_id
+            changed = True
+    if changed:
+        _atomic_write(path, "".join(json.dumps(r) + "\n" for r in lines))
+
+
+def refusal_stats(repo: str, window_days: int = 7) -> tuple[int, int]:
+    """(refusals in window, of which converted). The go/no-go health metric."""
+    path = _refusals_path(repo)
+    if not os.path.exists(path):
+        return (0, 0)
+    cutoff = int(time.time()) - window_days * 86400
+    recs = [json.loads(l) for l in open(path) if l.strip()]
+    recent = [r for r in recs if r.get("_ts", 0) >= cutoff]
+    return (len(recent), sum(1 for r in recent if r.get("converted_to")))

substratum_cli/runid.py

@@ -0,0 +1,69 @@
+"""Content-hash run IDs. The determinism story made shared: same repo state + same query +
+same engine/library versions -> the same `sub_...` id, for two engineers or an agent and its
+human. Computed here and ONLY here, so no surface forks the id.
+
+Nothing in the RunKey is volatile (no timestamps, no worktree paths), so a re-run of the same
+inputs re-derives the same id -- which is exactly what `replay` asserts.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Optional
+
+from . import gitio
+
+
+def canonical(obj: dict) -> str:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+def library_versions(repo_root: str = "/home/thepadrevictor/Substratum") -> dict:
+    """{lang: '<library-root-basename>@<manifest-hash>'} for each active root, or 'absent'.
+    Loaded via the leaf bridge (lib_roots is import-clean) so no numpy chain is paid."""
+    import os
+    out = {}
+    try:
+        from .engine import lib_roots
+        getters = {"py": lib_roots.py_library_root, "go": lib_roots.go_library_root,
+                   "ts": lib_roots.ts_library_root}
+        for lang, get in getters.items():
+            root = get()
+            if not root or not os.path.isdir(root):
+                out[lang] = "absent"
+                continue
+            man = os.path.join(root, "manifest.json")
+            h = ""
+            if os.path.exists(man):
+                h = hashlib.sha256(open(man, "rb").read()).hexdigest()[:12]
+            out[lang] = f"{os.path.basename(root)}@{h}"
+    except Exception:
+        out = {"py": "unknown", "go": "unknown", "ts": "unknown"}
+    return out
+
+
+def engine_version(repo_root: str = "/home/thepadrevictor/Substratum") -> str:
+    """The engine's git sha (dev fallback). A stamped build overrides via SUBSTRATUM_ENGINE_SHA."""
+    import os
+    env = os.environ.get("SUBSTRATUM_ENGINE_SHA")
+    if env:
+        return env
+    return gitio.head_sha(repo_root) or "dev"
+
+
+def compute(repo: str, operation: str, query: dict,
+            engine_sha: Optional[str] = None,
+            libs: Optional[dict] = None,
+            pkg_version: str = "0.1.0") -> tuple[str, dict]:
+    """Return (run_id, run_key). run_key is stored verbatim so `replay` can prove state identity."""
+    key = {
+        "head_sha": gitio.head_sha(repo) if gitio.is_git_repo(repo) else "",
+        "dirty_hash": gitio.dirty_hash(repo) if gitio.is_git_repo(repo) else "",
+        "operation": operation,
+        "query": query,
+        "engine_sha": engine_sha if engine_sha is not None else engine_version(),
+        "pkg_version": pkg_version,
+        "library_versions": libs if libs is not None else library_versions(),
+    }
+    digest = hashlib.sha256(canonical(key).encode()).hexdigest()[:12]
+    return f"sub_{digest}", key