substratum-cli 0.1.0__py3-none-any.whl

substratum_cli/product_ops.py

@@ -0,0 +1,639 @@
+"""product_ops -- the verbs. Each returns a SubstratumResult. This is the ONLY module that
+imports engine logic, and it does so lazily (heavy imports inside op_fix, after the first
+progress event). Extracted from scripts/ci/substratum_fix_cli.py; the script becomes a shim.
+
+Route 1: test-derived synthesis through the v0-synth gated door.
+Route 2: the substrate registry (run_substrate_query), the one door.
+Both arbitrated by the differential client gate. Nothing ships unverified.
+"""
+from __future__ import annotations
+
+import ast
+import os
+import re
+from typing import Optional
+
+from . import codes
+from . import engine
+from . import gitio
+from . import refusals
+from . import result as _result
+from . import run_store
+from . import runid
+
+
+def op_fix_from_failing_test(repo: str, failing_tests: list[str], intent: str = "",
+                             test_command: Optional[str] = None,
+                             emit=None) -> "_result.SubstratumResult":
+    """emit(stage, text): optional progress callback (GROUND/COMPOSE/GATE)."""
+    repo = os.path.abspath(repo)
+    def stage(s, t):
+        if emit:
+            emit(s, t)
+    base = gitio.head_sha(repo)
+    rid, key = runid.compute(repo, "fix",
+                             {"failing_tests": sorted(failing_tests),
+                              "intent_sha": _sha(intent), "test_cmd": test_command})
+    target = ", ".join(failing_tests)
+    inputs = {"failing_tests": list(failing_tests), "intent": intent,
+              "test_command": test_command}
+
+    stage("GROUND", f"reading {len(failing_tests)} failing test(s)")
+
+    if not engine.available():        # client-only install: fix needs the engine (local or hosted)
+        ref = refusals.build(codes.NO_ENGINE, engine_code="NO_ENGINE",
+                             ctx={"target": target or "the failing test", "run_id": rid})
+        return _store(repo, _result.make(codes.REFUSED, rid, "fix", code=codes.NO_ENGINE, refusal=ref),
+                      key, inputs)
+
+    # ---- ROUTE 1: test-derived synthesis ----
+    r1 = _route_test_derived(repo, base, failing_tests, intent, test_command, stage)
+    if r1 is not None:
+        patches, provenance, sink = r1
+        diff = "".join(_diff_for(repo, base, p, c) for p, c in sorted(patches.items()))
+        gate = _gate_from_sink(sink, failing_tests)
+        res = _result.make(codes.VERIFIED, rid, "fix", diff=diff, files=tuple(sorted(patches)),
+                           provenance=_result.Provenance(entries=tuple(provenance)),
+                           gate=gate, engine=_engine_info(),
+                           data={"target": target})
+        return _store(repo, res, key, inputs)
+
+    # ---- ROUTE 2: substrate registry (the one door) ----
+    stage("COMPOSE", "querying the substrate registry")
+    h = engine.heavy()
+    from pathlib import Path
+    trace: list = []
+    req = h["FixRequest"](buggy_source="", repo_provenance=os.path.basename(repo),
+                          problem_statement=intent or "", clone_dir=Path(repo),
+                          base_commit=base, fail_to_pass=tuple(failing_tests))
+    cand = h["run_substrate_query"](req, trace_out=trace)
+    if cand is None:
+        vbr = _verified_before_from_trace(trace)
+        ref = _refusal_from_trace(trace, target, rid, vbr)
+        res = _result.make(codes.REFUSED, rid, "fix", code=ref.code, refusal=ref,
+                           engine=_engine_info(), data={"target": target})
+        return _store(repo, res, key, inputs)
+
+    patches = {}
+    if getattr(cand, "file_patches", None):
+        for fp in cand.file_patches:
+            patches[fp.path] = fp.patched_content
+    diff = "".join(_diff_for(repo, base, p, c) for p, c in sorted(patches.items()))
+    res = _result.make(codes.VERIFIED, rid, "fix", diff=diff, files=tuple(sorted(patches)),
+                       provenance=_result.Provenance(entries=tuple(cand.provenance)[:10]),
+                       engine=_engine_info(), data={"target": target})
+    return _store(repo, res, key)
+
+
+# ---------------------------------------------------------------------------
+# route 1 (ported verbatim from the CI script; emits progress; uses the sink)
+# ---------------------------------------------------------------------------
+
+def _route_test_derived(repo, base_commit, failing_tests, intent, test_command, stage):
+    lib_root = engine.lib_roots.py_library_root()
+    if not lib_root:
+        return None
+    test_files = sorted({t.split("::")[0] for t in failing_tests if "::" in t or t.endswith(".py")})
+    leaf_names = {t.split("::")[-1].split("[")[0] for t in failing_tests if "::" in t}
+    for tf in test_files:
+        tf_abs = os.path.join(repo, tf)
+        if not os.path.isfile(tf_abs):
+            continue
+        tsrc = open(tf_abs, encoding="utf-8", errors="replace").read()
+        try:
+            tree = ast.parse(tsrc)
+        except SyntaxError:
+            continue
+        targets = []
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ImportFrom) and node.module and node.level == 0:
+                mod_rel = node.module.replace(".", "/") + ".py"
+                if os.path.isfile(os.path.join(repo, mod_rel)):
+                    for a in node.names:
+                        if re.search(rf"\b{re.escape(a.name)}\s*\(", tsrc):
+                            targets.append((a.name, mod_rel))
+        for name, mod_rel in targets:
+            arities = [len(n.args) + len(n.keywords) for n in ast.walk(tree)
+                       if isinstance(n, ast.Call) and isinstance(n.func, ast.Name)
+                       and n.func.id == name]
+            if not arities:
+                continue
+            arity = max(arities)
+            kw_names = [k.arg for n in ast.walk(tree) if isinstance(n, ast.Call)
+                        and isinstance(n.func, ast.Name) and n.func.id == name
+                        for k in n.keywords if k.arg]
+            pos = arity - len(set(kw_names))
+            params = [f"p{i}" for i in range(pos)] + list(dict.fromkeys(kw_names))
+            signature = f"def {name}({', '.join(params)}):"
+            from ._vendor._pro_test_derive import derive_gated_test as _dgt
+            gated = _dgt(_as_patch(tf, tsrc), name, sorted(leaf_names))
+            if not gated:
+                continue
+            stage("GROUND", f"test exercises {name} (from {mod_rel})")
+            h = engine.heavy()
+            lib = engine.load_library_cached(lib_root)   # warm: loaded once per session
+            scn = {"id": f"cli:{name}", "intent": intent or "", "signature": signature,
+                   "imports": [], "acceptance_test": gated}
+            stage("COMPOSE", f"synthesizing {name} from the library")
+            out = h["synthesize"](scn, lib, "gated")
+            if getattr(out, "outcome", "") != "EMIT" or not out.source:
+                continue
+            mod_abs = os.path.join(repo, mod_rel)
+            base_mod = open(mod_abs, encoding="utf-8", errors="replace").read()
+            new_mod = _splice(base_mod, name, out.source)
+            stage("GATE", f"differential gate on {', '.join(failing_tests)}")
+            sink: dict = {}
+            cg = engine.client_gate.run_client_gate(
+                repo, base_commit, {mod_rel: new_mod}, test_paths=list(failing_tests),
+                test_cmd=test_command, differential=True, transcript_sink=sink)
+            if cg.passed:
+                prov = [f"v0_synth:EMIT:{name}", "execution_gate:client:PASS"]
+                sel = getattr(out.provenance, "selected_pattern", None)
+                if sel is not None:
+                    prov.insert(1, f"pattern:{getattr(sel, 'pattern_id', '?')}")
+                return {mod_rel: new_mod}, prov, sink
+    return None
+
+
+def op_write_from_intent(repo: str, intent: str, signature: str,
+                         into: Optional[str] = None, emit=None,
+                         prefer_purpose: Optional[str] = None) -> "_result.SubstratumResult":
+    """Greenfield from intent. Derivation, not generation: comprehend the intent, derive the
+    construction from the granular productions + grounding, verify intrinsically (construct-then-
+    verify, no external test needed), and EMIT or REFUSE. Same contract as everything else --
+    it resolves iff the intent is fully understood AND the construction is derivable; otherwise
+    it refuses by name. No LLM guess."""
+    repo = os.path.abspath(repo)
+    def stage(s, t):
+        if emit:
+            emit(s, t)
+    # hosted engine: when logged in, greenfield synthesis runs server-side (intent+sig only leave the
+    # machine) and returns the SAME SubstratumResult we render locally. Falls back to a clean refusal.
+    from . import remote
+    if remote.enabled():
+        stage("REMOTE", "hosted engine")
+        rid, key = runid.compute(repo, "write",
+                                 {"intent_sha": _sha(intent), "sig": signature, "into": into})
+        try:
+            return _result.from_json_dict(remote.write(intent, signature, into, prefer_purpose))
+        except remote.RemoteError as e:
+            ref = refusals.build(codes.GATE_PRECONDITION, engine_code=str(e),
+                                 ctx={"target": _name_from_sig(signature) or "the function",
+                                      "run_id": rid})
+            return _store(repo, _result.make(codes.REFUSED, rid, "write",
+                                             code=codes.GATE_PRECONDITION, refusal=ref), key,
+                          {"intent": intent, "signature": signature})
+    if not engine.available():
+        rid, key = runid.compute(repo, "write",
+                                 {"intent_sha": _sha(intent), "sig": signature, "into": into})
+        ref = refusals.build(codes.NO_ENGINE, engine_code="NO_ENGINE",
+                             ctx={"target": _name_from_sig(signature) or "the function", "run_id": rid})
+        return _store(repo, _result.make(codes.REFUSED, rid, "write", code=codes.NO_ENGINE, refusal=ref),
+                      key, {"intent": intent, "signature": signature})
+    base = gitio.head_sha(repo)
+    name = _name_from_sig(signature)
+    sig = signature if signature.strip().startswith("def ") else f"def {signature.strip().rstrip(':')}:"
+    rid, key = runid.compute(repo, "write",
+                             {"intent_sha": _sha(intent), "sig": sig, "into": into})
+    inputs = {"intent": intent, "signature": sig, "into": into}
+    target = name or "the requested function"
+
+    lib_root = engine.lib_roots.py_library_root()
+    if not lib_root:
+        ref = refusals.build(codes.NO_GROUNDED_CANDIDATE, engine_code="no_library",
+                             ctx={"target": target, "run_id": rid})
+        return _store(repo, _result.make(codes.REFUSED, rid, "write", code=ref.code,
+                                         refusal=ref, data={"target": target}), key, inputs)
+
+    stage("GROUND", "comprehending intent")
+    h = engine.heavy()
+    lib = engine.load_library_cached(lib_root)
+    stage("COMPOSE", f"deriving {name or 'code'} from intent + productions")
+    if prefer_purpose:   # accept a purpose_key OR the plain-English option text (--mean "...")
+        pp = prefer_purpose.strip().lower()
+        for o in _clarify_options(intent, sig, lib):
+            if o["purpose"].lower() == pp or o["text"].lower() == pp or pp in o["text"].lower():
+                prefer_purpose = o["purpose"]
+                break
+    _set_preferred_purpose(prefer_purpose)   # a clarification pick forces that operation identity
+    try:
+        res = h["synthesize_from_intent"](intent, sig, library=lib)
+    finally:
+        _set_preferred_purpose(None)
+
+    if res.get("status") == "emit" and res.get("source"):
+        stage("VERIFY", "construct-then-verify (intrinsic, intent-derived)")
+        into_file = into or (f"{name}.py" if name else "substratum_new.py")
+        mod_abs = os.path.join(repo, into_file)
+        base_mod = open(mod_abs, encoding="utf-8", errors="replace").read() \
+            if os.path.isfile(mod_abs) else ""
+        new_mod = _splice(base_mod, name, res["source"])
+        diff = _diff_for(repo, base, into_file, new_mod)
+        prov = _prov_from_intent(res.get("provenance"), name)
+        note = "derived from intent and intrinsically verified (construct-then-verify); no external test."
+        out = _result.make(codes.VERIFIED, rid, "write", diff=diff, files=(into_file,),
+                           provenance=_result.Provenance(entries=tuple(prov)),
+                           engine=_engine_info(), data={"target": target, "note": note})
+        return _store(repo, out, key, inputs)
+
+    # ASK before refusing: if the intent maps to >=2 DISTINCT operations, surface a plain-English
+    # clarification (the inverse-gloss of each candidate) instead of a bare refusal. The user's pick
+    # forces that operation and the SAME pipeline re-resolves. Never an emission -> zero-wrong intact.
+    reason = (res.get("refuse_reason") or "no_candidate")
+    if prefer_purpose is None and _is_intent_ambiguous(reason):
+        opts = _clarify_options(intent, sig, lib)
+        if len(opts) >= 2:
+            ref = refusals.build(codes.UNDERDETERMINED_INTENT, engine_code=reason,
+                                 ctx={"target": target, "run_id": rid})
+            clarify = {"question": f"\"{intent}\" could mean a few things. Which did you mean?",
+                       "options": opts, "intent": intent, "sig": sig, "into": into}
+            return _store(repo, _result.make(codes.UNVERIFIABLE, rid, "write",
+                                             code=codes.UNDERDETERMINED_INTENT, refusal=ref,
+                                             engine=_engine_info(),
+                                             data={"target": target, "clarify": clarify}), key, inputs)
+
+    # refuse: intent not fully understood, or no derivable construction (coverage)
+    code = codes.UNDERDETERMINED_INTENT if _is_intent_ambiguous(reason) else codes.NO_GROUNDED_CANDIDATE
+    vbr = (f"comprehended: intent parsed",) if code == codes.NO_GROUNDED_CANDIDATE else ()
+    ref = refusals.build(code, engine_code=reason, ctx={"target": target, "run_id": rid},
+                         verified_before=vbr)
+    return _store(repo, _result.make(codes.REFUSED, rid, "write", code=code, refusal=ref,
+                                     engine=_engine_info(), data={"target": target}), key, inputs)
+
+
+def _readme_synopsis(repo: str) -> Optional[dict]:
+    """Lift the project's self-description VERBATIM from its README (grounded, not generated): the
+    first H1 title + the first real prose paragraph, skipping badges / TOC / HTML / code. Returns
+    {title, blurb, source} or None. These are the AUTHORS' words, quoted and cited -- never a
+    Substratum paraphrase, so it cannot lie."""
+    import re
+    path = None
+    for name in ("README.md", "README.rst", "README.txt", "README", "readme.md",
+                 "Readme.md", "README.markdown", os.path.join("docs", "README.md")):
+        p = os.path.join(repo, name)
+        if os.path.isfile(p):
+            path = p
+            break
+    if not path:
+        return None
+    try:
+        lines = open(path, encoding="utf-8", errors="replace").read().splitlines()
+    except Exception:
+        return None
+
+    def clean(s):
+        s = re.sub(r"<[^>]+>", "", s)                 # strip HTML tags
+        s = re.sub(r"!?\[([^\]]*)\]\([^)]*\)", r"\1", s)  # [text](url) -> text
+        return re.sub(r"\s+", " ", s.strip().lstrip("#").strip().strip("*_` ").strip())
+
+    def is_noise(line):
+        s = line.strip()
+        if not s:
+            return False
+        core = re.sub(r"!?\[[^\]]*\]\([^)]*\)|<[^>]+>|[\s|>*_=#`~-]", "", s)
+        return len(core) < 3                          # only badges / rules / html / links
+
+    title = None
+    for l in lines:
+        m = re.match(r"^\s*#\s+(.+)$", l)
+        if m:
+            title = clean(m.group(1))
+            break
+    blurb, in_code, started = [], False, False
+    for l in lines:
+        s = l.strip()
+        if s.startswith("```") or s.startswith("~~~"):
+            in_code = not in_code
+            continue
+        if in_code:
+            continue
+        if re.match(r"^\s*#", l):                     # a heading ends the first paragraph
+            if started:
+                break
+            continue
+        if not s:
+            if started:
+                break
+            continue
+        if is_noise(l) or re.match(r"^\s*[-*]\s*\[", l):   # badge row / TOC link
+            continue
+        c = clean(l)
+        if len(c) < 3:
+            continue
+        blurb.append(c)
+        started = True
+    text = re.sub(r"\s+", " ", " ".join(blurb)).strip()
+    if len(text) > 360:
+        text = text[:360].rsplit(" ", 1)[0] + "…"
+    if not title and not text:
+        return None
+    return {"title": title or "", "blurb": text, "source": os.path.relpath(path, repo)}
+
+
+def _project_synopsis(repo: str) -> Optional[dict]:
+    """Gather EVERY grounded description of the project -- curated package manifests (which are
+    usually more current than a README) + the README + (upstream) the real code structure. Each
+    field is quoted from a real file and CITED; nothing is paraphrased, so it cannot lie. READMEs
+    go stale, so the manifest tagline is preferred for the one-liner and both are shown when they
+    differ -- the developer sees all grounded context and reconciles against the code counts."""
+    import json as _json
+    name = tagline = None
+    sources: list = []
+
+    def _read(rel):
+        p = os.path.join(repo, rel)
+        try:
+            return open(p, encoding="utf-8", errors="replace").read() if os.path.isfile(p) else None
+        except Exception:
+            return None
+
+    pj = _read("package.json")
+    if pj:
+        try:
+            d = _json.loads(pj)
+            if d.get("name") or d.get("description"):
+                name = name or (d.get("name") or "").strip() or None
+                tagline = tagline or (d.get("description") or "").strip() or None
+                sources.append("package.json")
+        except Exception:
+            pass
+    for man in ("pyproject.toml", "Cargo.toml"):
+        raw = _read(man)
+        if not raw:
+            continue
+        try:
+            import tomllib
+            t = tomllib.loads(raw)
+        except Exception:
+            t = None
+        desc = nm = None
+        if isinstance(t, dict):
+            proj = t.get("project") or (t.get("tool", {}).get("poetry") if man == "pyproject.toml" else None) \
+                or t.get("package") or {}
+            if isinstance(proj, dict):
+                nm = (proj.get("name") or "").strip() or None
+                desc = (proj.get("description") or "").strip() or None
+        if desc or nm:
+            name = name or nm
+            tagline = tagline or desc
+            sources.append(man)
+    gomod = _read("go.mod")
+    if gomod:
+        m = _re_first(r"^module\s+(\S+)", gomod)
+        if m and not name:
+            name = m.rsplit("/", 1)[-1]
+            sources.append("go.mod")
+
+    rd = _readme_synopsis(repo)
+    blurb = None
+    if rd:
+        name = name or rd.get("title") or None
+        blurb = rd.get("blurb") or None
+        if rd.get("source"):
+            sources.append(rd["source"])
+        if not tagline:                      # no manifest one-liner -> the README blurb is the tagline
+            tagline, blurb = blurb, None
+
+    if not (name or tagline or blurb):
+        return None
+    # if the README blurb just restates the tagline, don't show it twice
+    if blurb and tagline and blurb[:40].lower() in tagline.lower():
+        blurb = None
+    return {"name": name or "", "tagline": tagline or "", "blurb": blurb or "",
+            "sources": sorted(set(sources))}
+
+
+def _re_first(pat: str, text: str):
+    import re
+    m = re.search(pat, text, re.M)
+    return m.group(1) if m else None
+
+
+def _humanize_token(name: str) -> str:
+    """Stdlib humanizer (camelCase/snake_case -> words) so summarize stays fully local."""
+    import re as _re
+    s = _re.sub(r"(?<=[a-z0-9])(?=[A-Z])", " ", str(name or ""))
+    return s.replace("_", " ").strip() or str(name or "")
+
+
+def _local_gloss_fns():
+    """Prefer the engine's rich inverse-gloss; fall back to the stdlib humanizer when the engine
+    is not installed, so `summarize` runs on a zero-dependency (client-only) install."""
+    try:
+        engine._ensure_repo_on_path()
+        from backend.substratum_v2.code_generation_v2.intent_gloss import gloss_name, humanize_name
+        return gloss_name, humanize_name
+    except Exception:
+        return _humanize_token, _humanize_token
+
+
+def op_summarize_repo(repo: str, emit=None) -> "_result.SubstratumResult":
+    """Describe a codebase in plain English across EVERY serviced language (Python/Go/TS/JS), using
+    the SAME inverse-gloss the clarifier uses. Stdlib-only (langscan: ast for Python, closed-class
+    declaration regexes for the rest), no library load. Grounded: every line names a real symbol at
+    a real path. Comprehension surface, not generation -- no gaps by language."""
+    from . import langscan
+    repo = os.path.abspath(repo)
+    rid, key = runid.compute(repo, "summarize", {})
+    if emit:
+        emit("READ", "scanning modules across languages")
+    gloss_name, humanize_name = _local_gloss_fns()
+
+    _TYPE_KINDS = ("class", "struct", "interface", "type", "enum")
+    _CAP = 24
+    funcs: list = []
+    types: list = []
+    by_lang: dict = {}          # lang -> {files, function, method, class, struct, interface, type, enum}
+    total_files = 0
+    for root, dirs, fs in os.walk(repo):
+        dirs[:] = [d for d in dirs if d not in
+                   (".git", "node_modules", ".venv", "venv", "__pycache__", ".substratum", "dist", "build")]
+        for f in sorted(fs):
+            ext = os.path.splitext(f)[1]
+            lang = langscan.LANGS.get(ext)
+            if not lang:
+                continue
+            total_files += 1
+            rel = os.path.relpath(os.path.join(root, f), repo)
+            try:
+                text = open(os.path.join(root, f), encoding="utf-8", errors="replace").read()
+            except Exception:
+                continue
+            lstat = by_lang.setdefault(lang, {"files": 0})
+            lstat["files"] += 1
+            ff = ft = 0     # per-file caps so the described lists stay DIVERSE across the codebase
+            for d in langscan.scan(text, ext):
+                k, nm = d["kind"], d["name"]
+                lstat[k] = lstat.get(k, 0) + 1
+                if nm.startswith("_") or nm.startswith("$"):
+                    continue
+                if k == "function" and len(funcs) < _CAP and ff < 4:
+                    funcs.append({"symbol": nm, "file": rel, "lang": lang,
+                                  "english": gloss_name(nm)}); ff += 1
+                elif k in _TYPE_KINDS and len(types) < _CAP and ft < 4:
+                    types.append({"symbol": nm, "file": rel, "lang": lang, "kind": k,
+                                  "english": humanize_name(nm)}); ft += 1
+        if total_files >= 4000:      # backstop for pathological monorepos; disclosed if hit
+            break
+
+    n_func = sum(l.get("function", 0) for l in by_lang.values())
+    n_meth = sum(l.get("method", 0) for l in by_lang.values())
+    n_type = sum(l.get(k, 0) for l in by_lang.values() for k in _TYPE_KINDS)
+    summary = {
+        "about": _project_synopsis(repo),     # all grounded sources: manifests + README, cited
+        "total_code_files": total_files,
+        "languages": {lang: l["files"] for lang, l in by_lang.items()},
+        "functions": n_func, "methods": n_meth, "types": n_type,
+        "functions_shown": len(funcs), "functions_truncated": max(0, n_func - len(funcs)),
+        "described": funcs, "types_described": types,
+        "multi_lang": len([l for l in by_lang if by_lang[l]["files"]]) > 1,
+        "truncated_files": total_files >= 4000,
+    }
+    res = _result.make(codes.PASS, rid, "summarize", data={"summary": summary}, engine=_engine_info())
+    return _store(repo, res, key, {"repo": repo})
+
+
+def _set_preferred_purpose(purpose: Optional[str]) -> None:
+    """Channel a clarification pick to SELECT: the user's chosen operation is the disambiguation,
+    so intent_alone forces the survivor whose purpose matches it. Cleared after the call."""
+    try:
+        engine._ensure_repo_on_path()
+        from backend.substratum_v2.code_generation_v2 import v0_select as _vs
+        _vs._PREFERRED_PURPOSE = (purpose or "").strip() or None
+    except Exception:
+        pass
+
+
+def _clarify_options(intent: str, signature: str, lib) -> list:
+    """The candidate operations for an ambiguous intent, each glossed to plain English (the inverse
+    of the parse) and deduped by that English so noise collapses. Reuses the engine helpers."""
+    try:
+        engine._ensure_repo_on_path()
+        from backend.substratum_v2.code_generation_v2.v0_intent_parser import parse_intent
+        from backend.substratum_v2.code_generation_v2.v0_select import _identity_survivors
+        from backend.substratum_v2.code_generation_v2.intent_gloss import gloss
+    except Exception:
+        return []
+    scn = {"id": "cli", "intent": intent, "signature": signature, "acceptance_test": ""}
+    try:
+        q, _ref = parse_intent(scn, "intent_alone")
+    except Exception:
+        return []
+    if q is None:
+        return []
+    seen: dict = {}
+    for v in _identity_survivors(q, lib):
+        pk = (getattr(v, "purpose_key", "") or "").split()
+        verb = pk[0] if pk else ""
+        obj = pk[1] if len(pk) > 1 else ""
+        eng = gloss(verb, obj, getattr(v, "category", ""))
+        if eng and eng not in seen:
+            seen[eng] = {"text": eng, "refine": eng.lower(),
+                         "purpose": getattr(v, "purpose_key", "")}
+    return list(seen.values())[:5]
+
+
+def _name_from_sig(signature: str) -> str:
+    import re as _re
+    m = _re.search(r"(?:def\s+)?([A-Za-z_]\w*)\s*\(", signature or "")
+    return m.group(1) if m else ""
+
+
+def _is_intent_ambiguous(reason: str) -> bool:
+    r = (reason or "").upper()
+    return any(k in r for k in ("AMBIG", "UNDERDETERMIN", "MULTIPLE", "SELECT_AMBIGUOUS"))
+
+
+def _prov_from_intent(prov, name: str) -> list:
+    entries = [f"v0_synth:intent_alone:EMIT{':' + name if name else ''}"]
+    try:
+        if isinstance(prov, dict):
+            pid = (prov.get("selected_pattern") or {}).get("pattern_id") if isinstance(
+                prov.get("selected_pattern"), dict) else prov.get("pattern_id")
+            if pid:
+                entries.append(f"pattern:{pid}")
+    except Exception:
+        pass
+    entries.append("verify:intrinsic:PASS")
+    return entries
+
+
+def _as_patch(path: str, content: str) -> str:
+    lines = "\n".join("+" + l for l in content.splitlines())
+    return f"+++ b/{path}\n{lines}\n"
+
+
+def _splice(module_src: str, fn_name: str, emitted: str) -> str:
+    try:
+        tree = ast.parse(module_src)
+    except SyntaxError:
+        return module_src + "\n\n" + emitted + "\n"
+    for node in tree.body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.name == fn_name:
+            lines = module_src.splitlines()
+            start = node.lineno - 1
+            if node.decorator_list:
+                start = node.decorator_list[0].lineno - 1
+            end = node.end_lineno
+            return "\n".join(lines[:start] + emitted.splitlines() + lines[end:]) + "\n"
+    return module_src.rstrip("\n") + "\n\n\n" + emitted.rstrip("\n") + "\n"
+
+
+def _diff_for(repo: str, base_commit: str, path: str, new_content: str) -> str:
+    base = gitio.show(repo, base_commit, path) or ""
+    return engine.canonical_diff()(path, base, new_content)
+
+
+# ---------------------------------------------------------------------------
+# refusal derivation from the substrate trace
+# ---------------------------------------------------------------------------
+
+def _verified_before_from_trace(trace) -> tuple:
+    composed = sum(1 for t in trace if getattr(t, "status", "") in
+                   ("candidate_failed_verify", "candidate_failed_execution_gate"))
+    lines = []
+    if composed:
+        lines.append(f"composed: {composed} candidate(s), all failed the gate")
+    no_cand = sum(1 for t in trace if getattr(t, "status", "") == "no_candidate")
+    if no_cand and not composed:
+        lines.append("grounded: no candidate matched (coverage absent)")
+    return tuple(lines)
+
+
+def _refusal_from_trace(trace, target, rid, vbr):
+    statuses = [getattr(t, "status", "") for t in trace]
+    if any(s in ("candidate_failed_verify", "candidate_failed_execution_gate") for s in statuses):
+        eng = "candidate_failed_verify"
+    else:
+        eng = "no_candidate"
+    return refusals.from_engine(eng, ctx={"target": target, "run_id": rid},
+                                verified_before=vbr)
+
+
+def _gate_from_sink(sink: dict, tests) -> "_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="FAIL" if (base_rc not in (None, 0)) else ("PASS" if base_rc == 0 else ""),
+        patched_status="PASS" if patched_rc == 0 else ("FAIL" if patched_rc is not None else ""),
+        base_excerpt=(sink.get("base_out", "") or "")[-800:],
+        patched_excerpt=(sink.get("patched_out", "") or "")[-800:],
+    )
+
+
+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()))
+
+
+def _store(repo, res, key, inputs=None):
+    run_store.store_run(repo, res, run_key=key, inputs=inputs)
+    return res
+
+
+def _sha(text: str) -> str:
+    import hashlib
+    return hashlib.sha256((text or "").encode("utf-8", "replace")).hexdigest()[:16]