@andresmassello/uscha 1.71.0 → 1.73.0

package/uscha-kit/.claude/skills/uscha-devloop/qa_ledger.py

@@ -4598,8 +4598,25 @@ def cmd_fidelity(args):
                                      % (_scope, okc, len(static_canon)))
     else:
         dims["contracts"] = _fid_dim(None, "UNMEASURED: no static-class canonical items")
-    # curation_closure: curated OBS / total OBS in the active delta
-    if obs:
+    # curation_closure: curated OBS / total OBS in the active delta. With --ir (ADR-015) it is
+    # answered as a path query over the graph -- OBS nodes reachable to a CURATION node via an
+    # OBS->CURATION edge / OBS nodes. It reproduces v0 when the graph's OBS set equals the
+    # delta's (the FIELD-RUN-001 case); a canonical carrying OBS beyond the active delta would
+    # widen the denominator, which is the graph's honest answer, not v0's.
+    if args.ir:
+        graph = _extract_ir(repo_path, ledger)
+        obs_nodes = [nd["id"] for nd in graph["nodes"] if nd["type"] == "OBS"]
+        cured = {e["from"] for e in graph["edges"] if e["type"] == "OBS->CURATION"}
+        if obs_nodes:
+            hit = sum(1 for oid in obs_nodes if oid in cured)
+            dims["curation_closure"] = _fid_dim(
+                round(hit / len(obs_nodes), 4),
+                "IR path query: %d/%d OBS node(s) reach a CURATION node (IR v%s)"
+                % (hit, len(obs_nodes), IR_SCHEMA))
+        else:
+            dims["curation_closure"] = _fid_dim(
+                None, "UNMEASURED: no OBS nodes in the IR graph")
+    elif obs:
         cur = sum(1 for o in obs if o["id"] in verdicts)
         dims["curation_closure"] = _fid_dim(round(cur / len(obs), 4),
                                             "%d/%d OBS in %s carry a ledger verdict"
@@ -4655,6 +4672,632 @@ def cmd_fidelity(args):
     sys.exit(0)
 
 
+# --------------------------------------------------------------------------- #
+# IR  (Diamond M2: the canonical package extracts into a typed graph. ADR-015.
+# Markdown stays canonical; the IR is a derived index. What cannot be typed
+# deterministically is UNTYPED -- visible, counted, never guessed.)
+# --------------------------------------------------------------------------- #
+
+IR_DIR = "ir"
+IR_FILE = "IR.json"
+IR_TWIN = "IR.md"
+IR_SCHEMA = "0.1"
+IR_NODE_TYPES = ("REQ", "INV", "AC", "CONTRACT", "DECISION", "NFR",
+                 "GOLDEN", "OBS", "CURATION", "EVIDENCE")
+IR_EDGE_TYPES = ("REQ->AC", "AC->EVIDENCE", "DECISION->INV", "OBS->CURATION",
+                 "CURATION->canonical", "supersedes", "derived_from")
+# broader than _AC_ID: the forward package uses sub-namespaced ids (AC-DD-07, AC-FV-06)
+_IR_AC_LINE = re.compile(r"^\s*[-*]\s*\[[ xX]\]\s*(AC-[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*)\b\s*[-—:]*\s*(.*)$")
+_IR_INV_LINE = re.compile(r"^\s*[-*]\s*\*\*(INV-[A-Za-z0-9-]+)\s*[—-]+\s*(.*?)\*\*")
+_IR_ADR_REF = re.compile(r"\bADR-0*(\d+)\b")
+_IR_INV_REF = re.compile(r"\bINV-[A-Za-z0-9-]+\b")
+_IR_SUPERSEDE = re.compile(r"(?i)supersed\w*\s+(ADR-0*\d+)")
+_IR_BANNER = ("GENERATED by qa_ledger.py ir-extract (ADR-015). Rendered view of "
+              + IR_FILE + " -- hand edits are overwritten on regeneration.")
+
+
+def _ir_node_id(ntype, text, source):
+    """Content-address the ID-less (ADR-015 option B): nodes with a native human id keep it;
+    only nodes with nothing human to anchor to get NODE-sha256(type+text+source)[:12]."""
+    norm = re.sub(r"\s+", " ", (text or "").strip().lower())
+    return "NODE-" + hashlib.sha256(
+        (ntype + "\n" + norm + "\n" + source).encode("utf-8")).hexdigest()[:12]
+
+
+def _ir_read_lines(path):
+    try:
+        with open(path, encoding="utf-8-sig", errors="replace") as fh:
+            return fh.read().splitlines()
+    except OSError:
+        return None
+
+
+def _extract_ir(repo_path, ledger):
+    """Deterministic extraction of the forward canonical package into a typed graph. Every
+    node/edge is derived from an EXISTING structural convention or reference -- nothing is
+    inferred. A line that fills a structural slot but cannot be typed lands in `untyped`."""
+    nodes, edges, untyped = [], [], []
+    seen_ids = set()
+
+    def add(node):
+        if node["id"] not in seen_ids:
+            seen_ids.add(node["id"])
+            nodes.append(node)
+
+    # AC nodes <- ACCEPTANCE.md checkboxes carrying an AC id; a checkbox WITHOUT an id is an
+    # acceptance slot the conventions do not type -> untyped (never a guessed id).
+    acc_lines = _ir_read_lines(os.path.join(repo_path, "ACCEPTANCE.md")) or []
+    for n, ln in enumerate(acc_lines, 1):
+        s = ln.strip()
+        if s[:5].lower() not in ("- [x]", "- [ ]", "* [x]", "* [ ]"):
+            continue
+        m = _IR_AC_LINE.match(ln)
+        src = {"file": "ACCEPTANCE.md", "line": n}
+        if m:
+            add({"id": m.group(1).upper(), "type": "AC",
+                 "statement": m.group(2).strip(), "source": src})
+        else:
+            untyped.append({"text": s[5:].strip(), "source": src,
+                            "reason": "acceptance checkbox without a traceable AC-id"})
+
+    # INV nodes <- CONSTITUTION.md `- **INV-XXX-NN — Title.**` headings
+    con_lines = _ir_read_lines(os.path.join(repo_path, "CONSTITUTION.md")) or []
+    inv_ids = set()
+    for n, ln in enumerate(con_lines, 1):
+        m = _IR_INV_LINE.match(ln)
+        if m:
+            add({"id": m.group(1).upper(), "type": "INV",
+                 "statement": m.group(2).strip().rstrip("."),
+                 "source": {"file": "CONSTITUTION.md", "line": n}})
+            inv_ids.add(m.group(1).upper())
+
+    # DECISION nodes <- docs/adr/*.md (native ADR-NNN id, title, file); edges to the INVs the
+    # ADR governs/states, and supersedes edges -- both from references already in the body.
+    adr_dir = os.path.join(repo_path, "docs", "adr")
+    ac_ids = {nd["id"] for nd in nodes if nd["type"] == "AC"}
+    for row in _mirador_adrs(adr_dir):
+        add({"id": row["id"], "type": "DECISION", "statement": row["t"],
+             "source": {"file": os.path.relpath(row["file"], repo_path).replace(os.sep, "/"),
+                        "line": 1}})
+        body = _ir_read_lines(row["file"]) or []
+        text = "\n".join(body)
+        for inv in set(_IR_INV_REF.findall(text)):
+            if inv.upper() in inv_ids:
+                edges.append({"from": row["id"], "to": inv.upper(), "type": "DECISION->INV"})
+        for sup in set(_IR_SUPERSEDE.findall(text)):
+            edges.append({"from": row["id"],
+                          "to": "ADR-%03d" % int(re.search(r"\d+", sup).group()),
+                          "type": "supersedes"})
+        # an ADR's Verification checklist references its ACs -> REQ->AC is absent here (no REQ
+        # layer yet), but AC nodes referenced by an ADR are real edges DECISION mentions AC:
+        for aid in {m.group(0)[1:-1].upper()
+                    for m in re.finditer(r"\(AC-[A-Za-z0-9-]+\)", text)}:
+            if aid in ac_ids:                       # set(): an AC cited twice is one edge
+                edges.append({"from": row["id"], "to": aid, "type": "REQ->AC"})
+
+    # GOLDEN nodes <- git-tracked approved fixtures (the path is a native, stable id)
+    tracked = _tracked_files(repo_path) or []
+    gold_marker = ".appro" + "ved."
+    for f in tracked:
+        if gold_marker in f:
+            add({"id": f, "type": "GOLDEN", "statement": "approved golden fixture",
+                 "source": {"file": f, "line": 1}})
+
+    # OBS / CURATION <- the active delta's observations (all of them, so curation_closure is
+    # a real path query over the graph) + the ledger's curation records. Absent in a repo
+    # that never ran a field run -> simply no such nodes.
+    delta, derrs = _load_delta(repo_path)
+    if delta and not derrs:
+        for o in delta.get("observations") or []:
+            prov = (o.get("provenance") or {}).get("files") or []
+            add({"id": o["id"], "type": "OBS", "statement": o.get("statement") or "",
+                 "source": {"file": prov[0].split(":")[0] if prov else "delta", "line": 1}})
+    canon_path = os.path.join(repo_path, CANDIDATE_DIR, CANONICAL_FILE)
+    canon_items = []
+    if os.path.isfile(canon_path):
+        try:
+            with open(canon_path, encoding="utf-8-sig") as fh:
+                canon_items = json.load(fh).get("items") or []
+        except (OSError, ValueError):
+            canon_items = []
+    for it in canon_items:
+        oid = it.get("derived_from")
+        if not oid:
+            continue
+        prov = (it.get("provenance") or {}).get("files") or []
+        add({"id": oid, "type": "OBS", "statement": it.get("statement") or "",
+             "source": {"file": prov[0].split(":")[0] if prov else "canonical", "line": 1}})
+    for rec in ledger.get("curation") or []:
+        oid = rec.get("obs_id")
+        if not oid:
+            continue
+        cid = "CUR-" + hashlib.sha256(
+            (oid + "\n" + (rec.get("at") or "")).encode("utf-8")).hexdigest()[:12]
+        add({"id": cid, "type": "CURATION",
+             "statement": "%s: %s" % (rec.get("verdict"), oid),
+             "source": {"file": "QA-LEDGER.json", "line": 0}})
+        if oid in seen_ids:
+            edges.append({"from": oid, "to": cid, "type": "OBS->CURATION"})
+
+    node_ids = {nd["id"] for nd in nodes}
+    kept, dropped = [], 0
+    for e in edges:
+        if e["from"] in node_ids and e["to"] in node_ids:
+            kept.append(e)
+        elif e["type"] == "supersedes" and e["from"] in node_ids:
+            kept.append(e)                          # a superseded ADR may be archived; keep it
+        else:
+            dropped += 1
+    nodes.sort(key=lambda nd: (nd["type"], nd["id"]))
+    kept.sort(key=lambda e: (e["type"], e["from"], e["to"]))
+    untyped.sort(key=lambda u: (u["source"]["file"], u["source"]["line"]))
+    counts = {t: sum(1 for nd in nodes if nd["type"] == t) for t in IR_NODE_TYPES}
+    stats = {"nodes": len(nodes), "edges": len(kept),
+             "edges_dropped": dropped, "untyped": len(untyped),
+             "by_type": {t: c for t, c in counts.items() if c},
+             "untyped_rate": round(len(untyped) / (len(nodes) + len(untyped)), 4)
+             if (nodes or untyped) else 0.0}
+    graph = {"schema_version": IR_SCHEMA,
+             "_generated_by": "qa_ledger.py ir-extract (ADR-015) -- derived index of the "
+                              "canonical package; never hand-edit",
+             "nodes": nodes, "edges": kept, "untyped": untyped, "stats": stats}
+    # the seal covers stats too (fresh-review MEDIUM): a doctored summary that ir-render
+    # would faithfully print must trip the strict loader, not slip past it -- the
+    # derived-but-unsealed lesson, applied a third time (path @1.70, evidence_class @1.69).
+    graph["_integrity"] = _ir_seal(graph)
+    return graph
+
+
+def _ir_seal(graph):
+    return _integrity_hash({k: graph.get(k) for k in
+                            ("schema_version", "nodes", "edges", "untyped", "stats")})
+
+
+def _load_ir(repo_path):
+    """Strict loader: an unknown schema_version or a broken graph is exit-2 class, never
+    mis-read (AC-IR-05). Returns (graph, errors); graph None when absent."""
+    path = os.path.join(repo_path, IR_DIR, IR_FILE)
+    if not os.path.isfile(path):
+        return None, []
+    try:
+        with open(path, encoding="utf-8-sig") as fh:
+            g = json.load(fh)
+    except (OSError, ValueError) as exc:
+        return {}, ["unreadable: %s" % exc]
+    errors = []
+    if g.get("schema_version") != IR_SCHEMA:
+        errors.append("schema_version %r != %r (a version this engine does not know is not "
+                      "read, it is refused)" % (g.get("schema_version"), IR_SCHEMA))
+        return g, errors
+    if not isinstance(g.get("nodes"), list) or not isinstance(g.get("edges"), list):
+        return g, ["nodes/edges missing or not lists"]
+    if g.get("_integrity") != _ir_seal(g):
+        errors.append("integrity seal does not match the graph -- nodes, edges, untyped or "
+                      "stats was hand-edited (regenerate via ir-extract)")
+    return g, errors
+
+
+def _render_ir_md(graph):
+    st = graph.get("stats") or {}
+    lines = ["<!-- %s -->" % _IR_BANNER, "", "# Uscha IR v%s (rendered view)" % IR_SCHEMA, "",
+             "%d nodes · %d edges · %d UNTYPED (rate %.2f)"
+             % (st.get("nodes", 0), st.get("edges", 0), st.get("untyped", 0),
+                st.get("untyped_rate", 0.0)), "",
+             "## Nodes", "", "| id | type | statement | source |",
+             "|----|------|-----------|--------|"]
+    for nd in graph.get("nodes") or []:
+        src = "%s:%s" % (nd["source"]["file"], nd["source"]["line"])
+        stmt = (nd.get("statement") or "").replace("|", "\\|")
+        lines.append("| %s | %s | %s | %s |" % (nd["id"], nd["type"], stmt, src))
+    lines += ["", "## Edges", "", "| from | type | to |", "|------|------|----|"]
+    for e in graph.get("edges") or []:
+        lines.append("| %s | %s | %s |" % (e["from"], e["type"], e["to"]))
+    if graph.get("untyped"):
+        lines += ["", "## UNTYPED (conventions the human layer is missing)", "",
+                  "| text | source | reason |", "|------|--------|--------|"]
+        for u in graph["untyped"]:
+            src = "%s:%s" % (u["source"]["file"], u["source"]["line"])
+            txt = (u.get("text") or "").replace("|", "\\|")[:80]
+            lines.append("| %s | %s | %s |" % (txt, src, u.get("reason", "")))
+    lines.append("")
+    return "\n".join(lines)
+
+
+def cmd_ir_extract(args):
+    ledger = _load(args.ledger)
+    _repo_node(ledger, args.repo)
+    repo_path = _scope_path(ledger, args.repo)
+    graph = _extract_ir(repo_path, ledger)
+    ir_dir = os.path.join(repo_path, IR_DIR)
+    os.makedirs(ir_dir, exist_ok=True)
+    with open(os.path.join(ir_dir, IR_FILE), "w", encoding="utf-8", newline="\n") as fh:
+        fh.write(json.dumps(graph, indent=2, ensure_ascii=False) + "\n")
+    twin_path = os.path.join(ir_dir, IR_TWIN)
+    twin = _render_ir_md(graph)
+    prev = None
+    if os.path.isfile(twin_path):
+        try:
+            with open(twin_path, encoding="utf-8-sig") as fh:
+                prev = fh.read()
+        except OSError:
+            prev = None
+    with open(twin_path, "w", encoding="utf-8", newline="\n") as fh:
+        fh.write(twin)
+    if prev is not None and prev != twin:
+        print("[qa_ledger] ir-extract: %s regenerated (rendered view, never a source)"
+              % IR_TWIN, file=sys.stderr)
+    st = graph["stats"]
+    if args.json:
+        print(json.dumps(st, indent=2, ensure_ascii=False))
+    else:
+        print("IR-EXTRACT %s: %d nodes, %d edges -> %s"
+              % (args.repo, st["nodes"], st["edges"],
+                 os.path.join(IR_DIR, IR_FILE)))
+        print("  by type: " + ", ".join("%s=%d" % (t, c)
+                                        for t, c in st["by_type"].items()))
+        print("  UNTYPED: %d (rate %.2f) -- the size of what the conventions cannot yet type"
+              % (st["untyped"], st["untyped_rate"]))
+        if st["edges_dropped"]:
+            print("  %d edge(s) dropped (endpoint not a node) -- counted, never dangling"
+                  % st["edges_dropped"])
+    sys.exit(0)
+
+
+def cmd_ir_render(args):
+    ledger = _load(args.ledger)
+    _repo_node(ledger, args.repo)
+    repo_path = _scope_path(ledger, args.repo)
+    graph, errors = _load_ir(repo_path)
+    if graph is None:
+        print("[qa_ledger] ir-render: no %s -- run ir-extract first."
+              % os.path.join(IR_DIR, IR_FILE), file=sys.stderr)
+        sys.exit(2)
+    if errors:
+        for e in errors:
+            print("[qa_ledger] ir-render: %s" % e, file=sys.stderr)
+        sys.exit(2)
+    twin = _render_ir_md(graph)
+    with open(os.path.join(repo_path, IR_DIR, IR_TWIN), "w", encoding="utf-8",
+              newline="\n") as fh:
+        fh.write(twin)
+    print("IR-RENDER %s: %s regenerated from the graph"
+          % (args.repo, os.path.join(IR_DIR, IR_TWIN)))
+    sys.exit(0)
+
+
+# --------------------------------------------------------------------------- #
+# compiler contract  (Diamond M3: the LLM is a compiler with a validated output
+# contract. The engine VALIDATES and INGESTS compilations; it NEVER compiles and
+# never calls a model. Only mechanical violations gate; every statistic is
+# advisory (INV-ADVISORY-01). ADR-016.)
+# --------------------------------------------------------------------------- #
+COMPILE_SCHEMA = "compile/0.1"
+COMPILE_REQUIRED = ("schema_version", "canonical_ir", "target_stack", "source",
+                    "tests", "trace_manifest", "unresolved_intent",
+                    "compilation_report")
+# The seal covers the load-bearing contract, NOT compilation_report: model, versions and
+# timestamps legitimately vary and never change WHAT was compiled. A hand edit of the
+# substance (source/tests/manifest/unresolved_intent) after production must trip the seal.
+COMPILE_SEALED = ("schema_version", "canonical_ir", "target_stack",
+                  "implementation_constraints", "source", "tests",
+                  "trace_manifest", "unresolved_intent")
+# Advisory degeneracy dial: a manifest of >=2 units where EVERY unit claims >= this share
+# of ALL IR nodes is "everything traces to everything" -- no unit discriminates. ADVISORY
+# ONLY: printed, never gates. The exact value is a reporting choice, not a contract,
+# precisely because it can never block (a threshold on a smell would be a judgment).
+_COMPILE_DEGENERATE_FANOUT = 0.8
+
+
+def _compile_seal(c):
+    return _integrity_hash({k: c.get(k) for k in COMPILE_SEALED})
+
+
+def _sha256_file(path):
+    try:
+        with open(path, "rb") as fh:
+            return hashlib.sha256(fh.read()).hexdigest()
+    except OSError:
+        return None
+
+
+def _contained_unit(base, unit):
+    """A compilation's units must be RELATIVE paths CONTAINED within the compilation
+    directory: the manifest references what was compiled, and what was compiled lives with
+    the compilation. An absolute path or a `..` escape lets a manifest name any file on the
+    filesystem as a "source" unit and pass on that file's hash -- exactly the "manifest
+    cannot lie about what was compiled" guarantee, defeated. Returns the resolved path, or
+    None if the unit is absolute or escapes `base`. Both sides are `realpath`-normalized
+    before comparison -- the Windows 8.3 short-path trap this repo already paid for once
+    (a file INSIDE a tree judged outside it) applies to any containment check."""
+    if os.path.isabs(unit):
+        return None
+    full = os.path.realpath(os.path.join(base, unit.replace("/", os.sep)))
+    root = os.path.realpath(base)
+    if full == root or full.startswith(root + os.sep):
+        return full
+    return None
+
+
+def _load_ir_at(path):
+    """Strict IR loader for an ARBITRARY IR.json. The repo's own ir/ is gitignored (a
+    regenerable index), so the M3 reference IR is a committed fixture loaded here with the
+    same posture as _load_ir: an unknown schema or a broken/hand-edited seal is refused,
+    never mis-read. Returns (graph, errors); graph None when the file is absent."""
+    if not os.path.isfile(path):
+        return None, ["no reference IR at %s" % path]
+    try:
+        with open(path, encoding="utf-8-sig") as fh:
+            g = json.load(fh)
+    except (OSError, ValueError) as exc:
+        return {}, ["unreadable: %s" % exc]
+    if g.get("schema_version") != IR_SCHEMA:
+        return g, ["schema_version %r != %r (an IR version this engine does not know is "
+                   "refused, not read)" % (g.get("schema_version"), IR_SCHEMA)]
+    if not isinstance(g.get("nodes"), list) or not isinstance(g.get("edges"), list):
+        return g, ["nodes/edges missing or not lists"]
+    if g.get("_integrity") != _ir_seal(g):
+        return g, ["reference IR integrity seal does not match -- it was hand-edited "
+                   "(regenerate via ir-extract)"]
+    return g, []
+
+
+def _validate_compilation(comp_path, ir_graph):
+    """The deterministic checker (ADR-016). Returns (blocking_errors, advisory).
+
+    BLOCKS only on FACTS: unknown schema, a missing/mistyped section, a broken seal, an
+    ir_hash that does not match the reference IR, a trace_manifest id that is not an IR
+    node, a unit whose file is absent or whose hash does not match the bytes on disk, a
+    malformed unresolved_intent entry. Every STATISTIC (fan-out degeneracy, empty/generic
+    unresolved_intent, coverage) is advisory and can NEVER change the outcome -- a
+    threshold on a smell is a judgment, and no judgment gates (INV-ADVISORY-01)."""
+    errors, advisory = [], {}
+    base = os.path.dirname(os.path.abspath(comp_path))
+    try:
+        with open(comp_path, encoding="utf-8-sig") as fh:
+            c = json.load(fh)
+    except (OSError, ValueError) as exc:
+        return ["unreadable compilation: %s" % exc], advisory
+    if c.get("schema_version") != COMPILE_SCHEMA:
+        return ["schema_version %r != %r (a contract version this engine does not know is "
+                "refused, not read)" % (c.get("schema_version"), COMPILE_SCHEMA)], advisory
+    for k in COMPILE_REQUIRED:
+        if k not in c:
+            errors.append("required section missing: %s" % k)
+    if errors:
+        return errors, advisory
+    for k, typ in (("source", list), ("tests", list), ("trace_manifest", list),
+                   ("unresolved_intent", list), ("canonical_ir", dict),
+                   ("compilation_report", dict)):
+        if not isinstance(c.get(k), typ):
+            errors.append("%s must be a %s" % (k, typ.__name__))
+    if errors:
+        return errors, advisory
+    # ELEMENT shapes, checked before any `.get` on them: an adversarial/buggy compiler that
+    # emits a list of strings (or a non-list `implements`) is a mechanical violation -> exit
+    # 2 with a named fault, NEVER an AttributeError traceback (exit 1). This is the trust
+    # boundary the contract exists to defend; the loops below assume dict elements.
+    for k in ("source", "tests"):
+        for i, u in enumerate(c.get(k)):
+            if not isinstance(u, dict):
+                errors.append("%s[%d] must be an object with unit/sha256" % (k, i))
+    for i, e in enumerate(c.get("trace_manifest")):
+        if not isinstance(e, dict):
+            errors.append("trace_manifest[%d] must be an object with unit/implements" % i)
+        elif not isinstance(e.get("implements"), list):
+            errors.append("trace_manifest[%d].implements must be a list of IR node ids" % i)
+    for i, ui in enumerate(c.get("unresolved_intent")):
+        if not isinstance(ui, dict):
+            errors.append("unresolved_intent[%d] must be an object with ir_region/decision"
+                          % i)
+    if errors:
+        return errors, advisory
+    if c.get("_integrity") != _compile_seal(c):
+        errors.append("compilation integrity seal does not match -- source/tests/manifest/"
+                      "unresolved_intent was hand-edited after production")
+    # the compilation NAMES which IR it compiled; a stale or foreign ir_hash is refused --
+    # a compilation cannot be measured against a graph this repo does not reproduce.
+    ir_seal = ir_graph.get("_integrity")
+    named = (c.get("canonical_ir") or {}).get("ir_hash")
+    if named != ir_seal:
+        errors.append("canonical_ir.ir_hash %s.. does not match the reference IR seal %s.. "
+                      "-- a stale or foreign IR is refused, never assumed"
+                      % (str(named)[:12], str(ir_seal)[:12]))
+    node_ids = {nd["id"] for nd in ir_graph.get("nodes") or []}
+    # units resolve on disk and their hashes match the bytes: the manifest cannot lie about
+    # what was compiled.
+    units = {}
+    for section in ("source", "tests"):
+        for u in c.get(section) or []:
+            unit, want = u.get("unit"), u.get("sha256")
+            if not unit:
+                errors.append("%s entry without a unit path" % section)
+                continue
+            # source classification is sticky: a unit listed in BOTH source and tests stays
+            # source, so the degeneracy detector (over source units) cannot be dodged by also
+            # listing a source file under tests. Advisory-only, but the detector stays honest.
+            if units.get(unit) != "source":
+                units[unit] = section
+            full = _contained_unit(base, unit)
+            if full is None:
+                errors.append("%s unit escapes the compilation directory -- a relative, "
+                              "contained path is required (the manifest references what was "
+                              "compiled): %s" % (section, unit))
+                continue
+            got = _sha256_file(full)
+            if got is None:
+                errors.append("%s unit missing on disk: %s" % (section, unit))
+            elif got != want:
+                errors.append("%s unit hash mismatch (manifest lies about the bytes): %s"
+                              % (section, unit))
+    # every manifest id is an IR node (THE named mechanical violation); every manifest unit
+    # is a real source/test unit.
+    for entry in c.get("trace_manifest") or []:
+        unit = entry.get("unit")
+        if unit not in units:
+            errors.append("trace_manifest unit is not a declared source/test unit: %s" % unit)
+        for nid in entry.get("implements") or []:
+            if nid not in node_ids:
+                errors.append("trace_manifest implements an id that is not an IR node: %s"
+                              % nid)
+    # unresolved_intent SHAPE blocks; its richness (count, specificity) is advisory only.
+    for ui in c.get("unresolved_intent") or []:
+        if not ui.get("ir_region") or not ui.get("decision"):
+            errors.append("unresolved_intent entry missing ir_region or decision")
+    # ---- ADVISORY (computed always, gates never) ----
+    manifest_units = {e.get("unit") for e in c.get("trace_manifest") or []}
+    per_unit = [len(e.get("implements") or []) for e in c.get("trace_manifest") or []]
+    total_nodes = len(node_ids) or 1
+    mean_fanout = (sum(per_unit) / len(per_unit)) if per_unit else 0.0
+    covered = {nid for e in c.get("trace_manifest") or []
+               for nid in (e.get("implements") or []) if nid in node_ids}
+    # Degeneracy is a property of the SOURCE units: >=2 source units that EACH claim >= the
+    # threshold share of all nodes -> the manifest cannot tell you which code implements
+    # which intent (everything traces to everything). Min-based, not mean-based, and over
+    # source only: one comprehensive source file legitimately implements a whole tiny
+    # package, and tests naturally exercise everything, so neither is a degeneracy signal.
+    source_units = {u for u, s in units.items() if s == "source"}
+    src_fanout = [len(e.get("implements") or []) for e in c.get("trace_manifest") or []
+                  if e.get("unit") in source_units]
+    advisory = {
+        "trace_units": len(manifest_units),
+        "mean_nodes_per_unit": round(mean_fanout, 3),
+        "node_coverage": round(len(covered) / total_nodes, 3),
+        "unexplained_units": sorted(u for u in units if u not in manifest_units),
+        "unresolved_intent_count": len(c.get("unresolved_intent") or []),
+        "degenerate": len(src_fanout) >= 2 and all(
+            (pu / total_nodes) >= _COMPILE_DEGENERATE_FANOUT for pu in src_fanout),
+        "empty_unresolved": len(c.get("unresolved_intent") or []) == 0,
+    }
+    return errors, advisory
+
+
+def _print_compile_advisory(advisory):
+    if not advisory:
+        return
+    print("  advisory (never gates): coverage %.2f, mean %.2f nodes/unit, %d unresolved_intent%s"
+          % (advisory.get("node_coverage", 0.0), advisory.get("mean_nodes_per_unit", 0.0),
+             advisory.get("unresolved_intent_count", 0),
+             ", DEGENERATE manifest" if advisory.get("degenerate") else ""))
+    if advisory.get("empty_unresolved"):
+        print("  advisory: unresolved_intent is EMPTY -- suspicious (a compiler that made no "
+              "choices is rare); reported, never blocked")
+    for u in advisory.get("unexplained_units") or []:
+        print("  advisory: %s has no trace_manifest entry -- unexplained by construction" % u)
+
+
+def cmd_compile_validate(args):
+    ir_graph, ir_errors = _load_ir_at(args.ir)
+    if ir_graph is None or ir_errors:
+        for e in ir_errors:
+            print("[qa_ledger] compile-validate: reference IR: %s" % e, file=sys.stderr)
+        sys.exit(2)
+    errors, advisory = _validate_compilation(args.compilation, ir_graph)
+    if args.json:
+        print(json.dumps({"compilation": args.compilation, "ir": args.ir,
+                          "valid": not errors, "errors": errors, "advisory": advisory},
+                         indent=2, ensure_ascii=False))
+    elif errors:
+        # diagnostics to stderr (Unix convention, and consistent with compile-ingest); the
+        # machine signal is the exit code. stdout stays clean for the VALID payload path.
+        print("COMPILE-VALIDATE %s: REFUSED (%d mechanical violation(s))"
+              % (args.compilation, len(errors)), file=sys.stderr)
+        for e in errors:
+            print("  x %s" % e, file=sys.stderr)
+    else:
+        print("COMPILE-VALIDATE %s: VALID (contract conformant)" % args.compilation)
+        _print_compile_advisory(advisory)
+    sys.exit(2 if errors else 0)
+
+
+def cmd_compile_ingest(args):
+    """Record a VALIDATED compilation into the ledger (ADR-016). Ingesting an invalid
+    compilation is a refusal. unresolved_intent becomes append-only, content-addressed
+    UINT objects + an ISSUES-DEFERRED.md mirror (the house convention `fix` uses); the
+    by-construction unexplained_code is the set of units with no trace_manifest entry."""
+    ledger = _load(args.ledger)
+    _repo_node(ledger, args.repo)
+    repo_path = _scope_path(ledger, args.repo)
+    ir_graph, ir_errors = _load_ir_at(args.ir)
+    if ir_graph is None or ir_errors:
+        for e in ir_errors:
+            print("[qa_ledger] compile-ingest: reference IR: %s" % e, file=sys.stderr)
+        sys.exit(2)
+    errors, advisory = _validate_compilation(args.compilation, ir_graph)
+    if errors:
+        print("[qa_ledger] compile-ingest: REFUSED -- ingesting an invalid compilation is a "
+              "refusal (%d mechanical violation(s)); run compile-validate." % len(errors),
+              file=sys.stderr)
+        for e in errors:
+            print("  x %s" % e, file=sys.stderr)
+        sys.exit(2)
+    with open(args.compilation, encoding="utf-8-sig") as fh:
+        c = json.load(fh)
+    comp_seal = c.get("_integrity")
+    uints, seen_uint = [], set()
+    for ui in c.get("unresolved_intent") or []:
+        uid = "UINT-" + hashlib.sha256(
+            (ui.get("ir_region", "") + "\n" + ui.get("decision", "")).encode("utf-8")
+        ).hexdigest()[:12]
+        # content-addressed: two entries that resolve to the same id ARE the same intent gap
+        # (same ir_region + decision), deduped within this ingest just as across ingests --
+        # otherwise ISSUES-DEFERRED and the ledger record carry the id twice.
+        if uid in seen_uint:
+            continue
+        seen_uint.add(uid)
+        uints.append({"id": uid, "ir_region": ui.get("ir_region"),
+                      "decision": ui.get("decision"), "rationale": ui.get("rationale", "")})
+    comp_rec = {"id": comp_seal[:12], "repo": args.repo,
+                "ir_hash": (c.get("canonical_ir") or {}).get("ir_hash"),
+                "model": (c.get("compilation_report") or {}).get("model"),
+                "target_stack": c.get("target_stack"), "seal": comp_seal,
+                "unexplained_units": advisory.get("unexplained_units") or [],
+                "node_coverage": advisory.get("node_coverage"),
+                "unresolved_intent": uints, "at": _now()}
+    comps = ledger.setdefault("compilations", [])
+    # re-ingest is idempotent PER REPO: the seal is the identity within a repo, and a
+    # byte-identical compilation has nothing to supersede. The compilations list is flat and
+    # cross-repo, so the supersede check MUST be scoped by repo -- otherwise two repos that
+    # legitimately produce the same compilation (a shared/small canonical package -- exactly
+    # this milestone's own fixtures) collide, and the second repo's first ingest is dropped
+    # as a false "superseded". A CHANGED compilation reseals -> a new record. Never a dup.
+    superseded = any(x.get("seal") == comp_seal and x.get("repo") == args.repo for x in comps)
+    if not superseded:
+        comps.append(comp_rec)
+        _save(args.ledger, ledger)
+    new_items = []
+    if uints:
+        dpath = os.path.join(repo_path, ISSUES_DEFERRED_FILE)
+        existing = ""
+        if os.path.isfile(dpath):
+            with open(dpath, encoding="utf-8-sig", errors="replace") as fh:
+                existing = fh.read()
+        add = [u for u in uints if u["id"] not in existing]
+        if add:
+            with open(dpath, "a", encoding="utf-8", newline="\n") as fh:
+                if existing and not existing.endswith("\n"):
+                    fh.write("\n")
+                for u in add:
+                    fh.write("- [ ] %s (unresolved_intent): %s -- the compiler decided "
+                             "'%s' on its own; a candidate canonical improvement (ADR-016)\n"
+                             % (u["id"], u["ir_region"], u["decision"]))
+            new_items = [u["id"] for u in add]
+    out = {"repo": args.repo, "compilation": comp_rec["id"], "superseded": superseded,
+           "unresolved_intent": [u["id"] for u in uints],
+           "issues_deferred_new": new_items,
+           "unexplained_units": comp_rec["unexplained_units"]}
+    if args.json:
+        print(json.dumps(out, indent=2, ensure_ascii=False))
+    else:
+        print("COMPILE-INGEST %s: compilation %s%s"
+              % (args.repo, comp_rec["id"],
+                 " (byte-identical to a prior ingest -- nothing superseded)"
+                 if superseded else ""))
+        print("  %d unresolved_intent -> %d new %s item(s); %d unexplained unit(s)"
+              % (len(uints), len(new_items), ISSUES_DEFERRED_FILE,
+                 len(comp_rec["unexplained_units"])))
+    sys.exit(0)
+
+
 # --------------------------------------------------------------------------- #
 # facts  (T0 / SYSTEM-FACTS: public claims become compiled artifacts of repo
 # facts -- Diamond applied to Diamond. ADR-012.)
@@ -8702,9 +9345,51 @@ def build_parser():
     pfv.add_argument("--repo", required=True)
     pfv.add_argument("--config", default="uscha.config.json",
                      help="checked for defaults.fidelity.gate -- advisory there is a refusal")
+    pfv.add_argument("--ir", action="store_true",
+                     help="answer curation_closure as a path query over the IR graph "
+                          "(ADR-015); reproduces v0 from the derived index")
     pfv.add_argument("--json", action="store_true")
     pfv.set_defaults(func=cmd_fidelity)
 
+    pie = sub.add_parser(
+        "ir-extract",
+        help="extract the canonical package into a typed graph (ir/IR.json); what cannot be "
+             "typed deterministically is UNTYPED, counted, never guessed (ADR-015)")
+    pie.add_argument("--ledger", default="QA-LEDGER.json")
+    pie.add_argument("--repo", required=True)
+    pie.add_argument("--json", action="store_true")
+    pie.set_defaults(func=cmd_ir_extract)
+
+    pir = sub.add_parser(
+        "ir-render",
+        help="regenerate the human view (ir/IR.md) from the graph; round-trip content-stable "
+             "for the structured parts (ADR-015)")
+    pir.add_argument("--ledger", default="QA-LEDGER.json")
+    pir.add_argument("--repo", required=True)
+    pir.set_defaults(func=cmd_ir_render)
+
+    pcmv = sub.add_parser(
+        "compile-validate",
+        help="validate a COMPILATION.json against a reference IR (ADR-016); only mechanical "
+             "violations gate, degeneracy stats are advisory and NEVER block")
+    pcmv.add_argument("--ir", required=True,
+                      help="the reference IR.json the compilation targets")
+    pcmv.add_argument("--compilation", required=True, help="path to COMPILATION.json")
+    pcmv.add_argument("--json", action="store_true")
+    pcmv.set_defaults(func=cmd_compile_validate)
+
+    pcmi = sub.add_parser(
+        "compile-ingest",
+        help="record a VALIDATED compilation into the ledger (ADR-016): by-construction "
+             "unexplained_code + unresolved_intent as append-only UINT objects + backlog")
+    pcmi.add_argument("--ledger", default="QA-LEDGER.json")
+    pcmi.add_argument("--repo", required=True)
+    pcmi.add_argument("--ir", required=True,
+                      help="the reference IR.json the compilation targets")
+    pcmi.add_argument("--compilation", required=True, help="path to COMPILATION.json")
+    pcmi.add_argument("--json", action="store_true")
+    pcmi.set_defaults(func=cmd_compile_ingest)
+
     pcr = sub.add_parser("cleanroom",
                          help="run a command against a CLEAN checkout of one commit in a throwaway worktree (ADR-008)")
     pcr.add_argument("--ledger", default="QA-LEDGER.json")