@andresmassello/uscha 1.83.0 → 1.85.0

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

@@ -4007,6 +4007,86 @@ def _extract_static_py(repo_path, tracked):
     return obs, unsupported
 
 
+# Node one-liner (ADR-028): `require`s the impl and reports ITS OWN module.exports --
+# the target's own runtime reporting its own public surface, never a regex-narrated AST. A
+# module that guards its entry point with `require.main === module` (the SPEC contract) will
+# not auto-run under `require()`, since `require.main` here is this -e script, not the module.
+_NODE_EXPORTS_PROBE = (
+    "const p=process.argv[1]; const m=require(require('path').resolve(p)); "
+    "const ks=Object.keys(m).filter(k=>typeof m[k]==='function'||typeof m[k]==='object'); "
+    "process.stdout.write(JSON.stringify(ks.sort()))"
+)
+_STATIC_JS_TIMEOUT = 15
+
+
+def _extract_static_js(repo_path, tracked):
+    """v0 static extractor for JS (ADR-028): the target's OWN runtime reports its own public
+    surface via `node -e` + `Object.keys(module.exports)` -- measured, not parsed by a
+    heuristic. Function-vs-object and the observation's line number are best-effort source
+    regexes (Node reports WHICH names are exported; it does not report where they are
+    defined). If node is absent, or a file fails to load/print a clean JSON array, that file's
+    surface is UNMEASURED -- named in `unsupported`, never silently empty-as-measured.
+    Returns (observations, unsupported) where unsupported is a list of "<file>: <reason>"."""
+    obs, unsupported = [], []
+    js_files = sorted(rel for rel in tracked if rel.lower().endswith(".js"))
+    if not js_files:
+        return obs, unsupported
+    node = shutil.which("node")
+    if not node:
+        return obs, ["%s: node not on PATH" % rel for rel in js_files]
+    for rel in js_files:
+        full = os.path.join(repo_path, rel.replace("/", os.sep))
+        abs_path = os.path.abspath(full)
+        try:
+            r = subprocess.run([node, "-e", _NODE_EXPORTS_PROBE, "--", abs_path],
+                               capture_output=True, text=True, encoding="utf-8",
+                               errors="replace", timeout=_STATIC_JS_TIMEOUT,
+                               cwd=os.path.dirname(full))
+        except subprocess.TimeoutExpired:
+            unsupported.append("%s: node timed out extracting exports" % rel)
+            continue
+        except OSError as exc:
+            unsupported.append("%s: could not run node: %s" % (rel, exc))
+            continue
+        if r.returncode != 0:
+            unsupported.append("%s: node exited %d extracting exports (%s)"
+                               % (rel, r.returncode, (r.stderr or "").strip()[:200]))
+            continue
+        try:
+            names = json.loads(r.stdout)
+            if not isinstance(names, list):
+                raise ValueError("exports output was not a JSON list")
+        except ValueError as exc:
+            unsupported.append("%s: could not parse exports output: %s" % (rel, exc))
+            continue
+        try:
+            with open(full, encoding="utf-8", errors="replace") as fh:
+                src = fh.read()
+        except OSError:
+            src = ""
+        src_lines = src.splitlines()
+        for name in sorted(names):
+            is_function = bool(re.search(r"\bfunction\s+%s\s*\(" % re.escape(name), src))
+            lineno = 0
+            patterns = (r"\bfunction\s+%s\b" % re.escape(name),
+                        r"\b%s\s*=" % re.escape(name),
+                        r"exports\.%s\b" % re.escape(name),
+                        r"module\.exports\b")
+            for i, ln in enumerate(src_lines, 1):
+                if any(re.search(p, ln) for p in patterns):
+                    lineno = i
+                    break
+            stmt = ("%s exports function %s" % (rel, name) if is_function
+                    else "%s exports object %s" % (rel, name))
+            prov = "%s:%d" % (rel, lineno)
+            obs.append({"id": _obs_id("contract", stmt, prov), "type": "contract",
+                        "statement": stmt, "evidence_class": "static",
+                        "provenance": {"files": [prov],
+                                       "derivation": "node -e Object.keys(module.exports)",
+                                       "tool": "qa_ledger-static-js"}})
+    return obs, unsupported
+
+
 def _under_bound(rel, bound):
     return bound is None or rel == bound or rel.startswith(bound + "/")
 
@@ -5307,26 +5387,69 @@ def cmd_compile_ingest(args):
 _BOOTSTRAP_CASE_TIMEOUT = 15                        # a compiled hook must decide fast
 
 
+def _entry_unit(source_list):
+    """The unit the oracle runs (ADR-029): the one whose basename starts with `cli.` if any,
+    else the first declared source unit. Single-unit compilations resolve to their only unit,
+    unchanged. Returns None when there is no usable unit."""
+    units = [u.get("unit") for u in (source_list or []) if isinstance(u, dict) and u.get("unit")]
+    if not units:
+        return None
+    for u in units:
+        if os.path.basename(u).lower().startswith("cli."):
+            return u
+    return units[0]
+
+
+def _static_surface_for(cd, unit):
+    """Route the reverse-discovery organ by the unit's extension (ADR-028/029)."""
+    if os.path.splitext(unit)[1].lower() == ".js":
+        return _extract_static_js(cd, [unit])
+    so, _n = _extract_static_py(cd, [unit])
+    return so, []
+
+
+def _impl_interpreter(impl_path):
+    """Resolve the interpreter argv prefix for one implementation file by extension (ADR-028):
+    `.py` runs under this same Python (unchanged); `.js` runs under `node`, resolved from PATH.
+    Returns None when the extension's interpreter cannot be resolved (today: node absent) --
+    the caller must treat that as UNMEASURED, never a fake red or green."""
+    if impl_path.lower().endswith(".js"):
+        node = shutil.which("node")
+        return [node] if node else None
+    return [sys.executable]
+
+
 def _run_oracle_case(impl_path, case):
     """Run ONE withheld oracle case against a compiled implementation: feed the case's stdin
-    (raw_stdin verbatim if present, else json.dumps(payload)) to `python <impl>`, and check its
-    result against whichever expectations the case declares. Deterministic execution -- the
-    oracle is a `measured` fact, never an LLM judgment. Returns a per-case result dict.
+    (raw_stdin verbatim if present, else json.dumps(payload)) to the impl's interpreter (ADR-028:
+    `python` for `.py`, `node` for `.js`), and check its result against whichever expectations
+    the case declares. Deterministic execution -- the oracle is a `measured` fact, never an LLM
+    judgment. Returns a per-case result dict.
 
     A case may assert any of: `expected_exit` (process exit code -- the M4 guard's contract),
     `expected_stdout` (the program's stdout, compared stripped -- for archetypes that COMPUTE an
     output, e.g. a parser or transformer), and `expected_json` (stdout parsed as JSON and
     compared structurally, so an output whose formatting is free but whose value is fixed is not
     penalised for whitespace or key order). The case passes iff EVERY declared expectation holds;
-    a case that declares none proves nothing and fails."""
+    a case that declares none proves nothing and fails.
+
+    If the impl's interpreter cannot be resolved (a `.js` impl and no `node` on PATH), the case
+    is UNMEASURED -- never a fake red or green (ADR-028)."""
     if "raw_stdin" in case:
         stdin = case["raw_stdin"]
     else:
         stdin = json.dumps(case.get("payload"))
+    interp = _impl_interpreter(impl_path)
+    if interp is None:
+        return {"name": case.get("name"), "expected": case.get("expected_exit"), "got": None,
+                "ok": False, "error": "node not on PATH", "unmeasured": True}
     try:
-        r = subprocess.run([sys.executable, impl_path], input=stdin, capture_output=True,
-                           text=True, encoding="utf-8", errors="replace",
-                           timeout=_BOOTSTRAP_CASE_TIMEOUT)
+        # cwd = the impl's own directory (ADR-029): a multi-unit compilation imports its
+        # sibling modules by bare name; single-unit impls are unaffected by their cwd
+        r = subprocess.run(interp + [os.path.abspath(impl_path)], input=stdin,
+                           capture_output=True, text=True, encoding="utf-8", errors="replace",
+                           timeout=_BOOTSTRAP_CASE_TIMEOUT,
+                           cwd=os.path.dirname(os.path.abspath(impl_path)) or None)
         got, out, err = r.returncode, r.stdout, None
     except subprocess.TimeoutExpired:
         got, out, err = None, "", "timeout"
@@ -5369,22 +5492,30 @@ def cmd_bootstrap_oracle(args):
               file=sys.stderr)
         sys.exit(2)
     results = [_run_oracle_case(args.impl, c) for c in cases]
+    unmeasured = bool(results) and all(r.get("unmeasured") for r in results)
     passed = sum(1 for r in results if r["ok"])
     failed = [r for r in results if not r["ok"]]
     report = {"impl": args.impl, "oracle": args.oracle, "total": len(results),
               "passed": passed, "failed": len(failed),
-              "oracle_green": not failed, "results": results}
+              "oracle_green": (None if unmeasured else not failed), "results": results}
+    if unmeasured:
+        report["unmeasured"] = results[0]["error"]
     if args.ledger and args.repo:
         ledger = _load(args.ledger)
         _repo_node(ledger, args.repo)
         rec = {"impl": os.path.basename(args.impl), "oracle": os.path.basename(args.oracle),
                "total": len(results), "passed": passed, "failed": len(failed),
-               "oracle_green": not failed,
+               "oracle_green": (None if unmeasured else not failed),
                "failing": [r["name"] for r in failed], "at": _now()}
+        if unmeasured:
+            rec["unmeasured"] = results[0]["error"]
         ledger.setdefault("bootstrap_oracle", []).append(rec)
         _save(args.ledger, ledger)
     if args.json:
         print(json.dumps(report, indent=2, ensure_ascii=False))
+    elif unmeasured:
+        print("BOOTSTRAP-ORACLE %s: UNMEASURED -- %s"
+              % (os.path.basename(args.impl), report["unmeasured"]))
     else:
         print("BOOTSTRAP-ORACLE %s: %d/%d cases pass -- %s"
               % (os.path.basename(args.impl), passed, len(results),
@@ -5394,17 +5525,60 @@ def cmd_bootstrap_oracle(args):
             print("  x %s: expected exit %s, got %s%s"
                   % (r["name"], r["expected"], r["got"],
                      " (%s)" % r["error"] if r["error"] else ""))
-    sys.exit(0 if not failed else 1)
+    sys.exit(2 if unmeasured else (0 if not failed else 1))
+
+
+_JS_IMPORT_RE = re.compile(
+    r"""require\(\s*['"]([^'"]+)['"]\s*\)"""
+    r"""|import\s+(?:.+?\s+from\s+)?['"]([^'"]+)['"]"""
+)
+
+
+def _impl_metrics_js(path, src):
+    """JS structural fingerprint (ADR-028), honestly NARROWER than Python's: `loc` (non-blank,
+    non-`//` lines, with `/*..*/` blocks toggled by a simple per-line state machine) and
+    `imports` (require()/import specifiers -- a lexical fact over string literals, not a
+    narrated structure) are measured; `ast_nodes`/`functions`/`classes` are UNMEASURED (None) --
+    no stdlib JS AST exists and the engine does not invent one."""
+    loc = 0
+    in_block = False
+    for ln in src.splitlines():
+        s = ln.strip()
+        if in_block:
+            if "*/" in s:
+                in_block = False
+            continue
+        if not s:
+            continue
+        if s.startswith("/*"):
+            if "*/" not in s[2:]:
+                in_block = True
+            continue
+        if s.startswith("//"):
+            continue
+        loc += 1
+    imports = set()
+    for m in _JS_IMPORT_RE.finditer(src):
+        spec = m.group(1) or m.group(2)
+        if spec:
+            imports.add(spec)
+    return {"path": path, "loc": loc, "ast_nodes": None, "functions": None,
+            "classes": None, "imports": sorted(imports),
+            "sha256": hashlib.sha256(src.encode("utf-8")).hexdigest()}
 
 
 def _impl_metrics(path):
     """Structural fingerprint of one implementation: physical LOC, AST node count, function
-    and class counts, and the set of imported top-level modules. Deterministic; no judgment."""
+    and class counts, and the set of imported top-level modules. Deterministic; no judgment.
+    Routed by extension (ADR-028): `.py` unchanged; `.js` delegates to `_impl_metrics_js`,
+    which returns the same keys with `ast_nodes`/`functions`/`classes` UNMEASURED (None)."""
     try:
         with open(path, encoding="utf-8", errors="replace") as fh:
             src = fh.read()
     except OSError as exc:
         return {"path": path, "error": "unreadable: %s" % exc}
+    if path.lower().endswith(".js"):
+        return _impl_metrics_js(path, src)
     loc = sum(1 for ln in src.splitlines() if ln.strip())
     try:
         tree = ast.parse(src)
@@ -5531,8 +5705,14 @@ def _bench_curation_map(records):
 def _bench_oracle_all(impl_path, cases):
     results = [_run_oracle_case(impl_path, c) for c in cases]
     passed = sum(1 for r in results if r["ok"])
-    return {"passed": passed, "total": len(results), "green": passed == len(results),
-            "failing": [r["name"] for r in results if not r["ok"]]}
+    out = {"passed": passed, "total": len(results), "green": passed == len(results),
+           "failing": [r["name"] for r in results if not r["ok"]]}
+    # every case UNMEASURED (ADR-028: a `.js` impl with no `node` on PATH) is NOT a fake red --
+    # name the reason and let the caller treat it as absent, never as a scored FAIL.
+    if results and all(r.get("unmeasured") for r in results):
+        out["unmeasured"] = results[0]["error"]
+        out["green"] = False
+    return out
 
 
 def _bench_entry(entry_dir, name, fidelity=False, curation=None):
@@ -5564,15 +5744,16 @@ def _bench_entry(entry_dir, name, fidelity=False, curation=None):
             with open(cj, encoding="utf-8-sig") as fh:
                 c = json.load(fh)
             src = c.get("source") or []
-            unit = src[0].get("unit") if src else None
+            unit = _entry_unit(src)
+            all_units = [u.get("unit") for u in src if isinstance(u, dict) and u.get("unit")]
             model = (c.get("compilation_report") or {}).get("model")
         except (OSError, ValueError, AttributeError, IndexError):
-            pass
+            all_units = []
         impl = os.path.join(cd, unit.replace("/", os.sep)) if unit else None
         ores = (_bench_oracle_all(impl, cases) if impl and os.path.isfile(impl)
                 else {"passed": 0, "total": len(cases), "green": False, "failing": ["<no impl>"]})
-        comp_rec = {"dir": d, "model": model, "impl": impl,
-                    "compile_valid": not errors, "oracle": ores}
+        comp_rec = {"dir": d, "model": model, "impl": impl, "entry_unit": unit,
+                    "units": len(all_units), "compile_valid": not errors, "oracle": ores}
         if fidelity and impl and os.path.isfile(impl) and unit:
             # the per-compiler fidelity descriptor (ADR-022): the M1 static extractor applied
             # to the compiled artifact -- reverse discovery per compiler. Advisory by
@@ -5597,20 +5778,36 @@ def _bench_entry(entry_dir, name, fidelity=False, curation=None):
                             units_f.add(u2["unit"])
             except AttributeError:
                 pass
-            sobs, _uns = _extract_static_py(cd, [unit])
+            # ADR-028: the static extractor is routed by the source unit's extension -- `.py`
+            # via the AST (unchanged), `.js` via the target's own `node` runtime. `uns_f` is a
+            # list of "<file>: <reason>" for JS (an int count for Python, discarded either way).
+            sobs, uns_f = [], []
+            for u_all in (all_units or [unit]):
+                so, un = _static_surface_for(cd, u_all)
+                sobs.extend(so)
+                uns_f.extend(un)
             fn_names, cls_names = [], []
             for o2 in sobs:
-                m2 = re.search(r"defines function (\w+)", o2.get("statement", ""))
+                m2 = re.search(r"defines function (\w+)|exports function (\w+)",
+                               o2.get("statement", ""))
                 if m2:
-                    fn_names.append(m2.group(1))
-                m2 = re.search(r"defines class (\w+)", o2.get("statement", ""))
+                    fn_names.append(m2.group(1) or m2.group(2))
+                m2 = re.search(r"defines class (\w+)|exports object (\w+)",
+                               o2.get("statement", ""))
                 if m2:
-                    cls_names.append(m2.group(1))
+                    cls_names.append(m2.group(1) or m2.group(2))
             unex = sorted(u for u in units_f if u not in traced_f)
+            if not sobs and uns_f:
+                # node absent (or every JS file failed to load): the surface is UNMEASURED,
+                # never a silent "0 functions, 0 classes" that reads as a measured empty
+                # surface (ADR-028 -- absence named, same discipline as curation_closure below).
+                static_surface = "UNMEASURED: %s" % "; ".join(uns_f)
+            else:
+                static_surface = {"functions": len(fn_names), "classes": len(cls_names),
+                                  "names": sorted(fn_names + cls_names)}
             comp_rec["fidelity"] = {
                 "trace_coverage": round(len(covered_f) / max(len(node_ids_f), 1), 3),
-                "static_surface": {"functions": len(fn_names), "classes": len(cls_names),
-                                   "names": sorted(fn_names + cls_names)},
+                "static_surface": static_surface,
                 "oracle_passrate": (round(ores["passed"] / ores["total"], 3)
                                     if ores["total"] else None),
                 "unexplained_share": round(len(unex) / max(len(units_f), 1), 3),
@@ -5634,9 +5831,17 @@ def _bench_entry(entry_dir, name, fidelity=False, curation=None):
     stub_dir = os.path.join(entry_dir, "stub")
     stub_green = False
     if os.path.isdir(stub_dir):
-        stubs = sorted(f for f in os.listdir(stub_dir) if f.endswith(".py"))
-        if stubs:
-            sres = _bench_oracle_all(os.path.join(stub_dir, stubs[0]), cases)
+        stubs = sorted(f for f in os.listdir(stub_dir) if f.endswith((".py", ".js")))
+        stub_path = os.path.join(stub_dir, stubs[0]) if stubs else None
+        if stub_path is None and os.path.isdir(os.path.join(stub_dir, "source")):
+            # multi-unit entries (ADR-029): the stub is a directory shaped like a compilation;
+            # its entry unit is the cli.* under source/
+            cands = sorted(f for f in os.listdir(os.path.join(stub_dir, "source"))
+                           if f.lower().startswith("cli.") and f.endswith((".py", ".js")))
+            if cands:
+                stub_path = os.path.join(stub_dir, "source", cands[0])
+        if stub_path:
+            sres = _bench_oracle_all(stub_path, cases)
             stub_green = sres["green"]
             rec["discrimination"] = {"stub_passed": sres["passed"], "total": sres["total"],
                                      "stub_green": stub_green}
@@ -5651,7 +5856,14 @@ def _bench_entry(entry_dir, name, fidelity=False, curation=None):
     # distinct is None when variance could not be computed (fewer than 2 resolvable impl files),
     # which is NOT the same as a byte-identical convergence -- keep the two reasons apart.
     distinct = rec["variance"]["all_distinct"] if rec["variance"] else None
-    if stub_green:
+    # ADR-028: node absent for a `.js` entry means EVERY case of that compilation came back
+    # UNMEASURED -- never score that as a FAIL (nor a PASS); the entry stays PENDING with the
+    # reason named, ahead of every other verdict check.
+    unmeasured_js = next((i["oracle"]["unmeasured"] for i in impls
+                          if i["oracle"].get("unmeasured")), None)
+    if unmeasured_js:
+        rec["verdict"], rec["reason"] = "PENDING", "%s -- JS entry unmeasured" % unmeasured_js
+    elif stub_green:
         rec["verdict"], rec["reason"] = "FAIL", ("oracle satisfied by a degenerate stub -- not "
                                                  "discriminating; the entry proves nothing")
     elif not all_valid:
@@ -5720,15 +5932,23 @@ def _render_bench_md(table, anon, recs):
                 if isinstance(cur_v, float):
                     cur_v = "%.3f (judged %d/%d)" % (cur_v, fd["curation"]["judged"],
                                                      fd["curation"]["total"])
-                lines.append("- fidelity `%s` (%s): trace %.2f · surface %d fn / %d cls · "
+                ss = fd["static_surface"]
+                # ADR-028: `static_surface` is UNMEASURED (a named string) when a JS entry's
+                # extractor could not run (node absent) -- never a silent "0 fn / 0 cls".
+                surface_txt = ("%d fn / %d cls" % (ss["functions"], ss["classes"])
+                               if isinstance(ss, dict) else ss)
+                lines.append("- fidelity `%s` (%s): trace %.2f · surface %s · "
                              "oracle %s · unexplained %.2f · curation %s" % (
                                  i["dir"], anon.get(i["model"], i["model"] or "?"),
-                                 fd["trace_coverage"], fd["static_surface"]["functions"],
-                                 fd["static_surface"]["classes"],
+                                 fd["trace_coverage"], surface_txt,
                                  ("%.3f" % fd["oracle_passrate"])
                                  if fd["oracle_passrate"] is not None else "n/a",
                                  fd["unexplained_share"], cur_v))
         lines.append("")
+    if any((i.get("impl") or "").lower().endswith(".js")
+           for r in recs for i in r["compilations"]):
+        lines += ["*JS pairs use a 2-dimensional distance (LOC + import Jaccard; no stdlib JS "
+                  "AST).*", ""]
     return "\n".join(lines)
 
 
@@ -5786,6 +6006,444 @@ def cmd_bench(args):
     sys.exit(0)
 
 
+_R2_DIR = "r2"
+_R2_SIGNAL = 0.5          # intra/inter below this: inter-compiler variance is real signal
+_R2_NOISE = 1.0           # intra/inter at/above this: same-model reruns differ as much as models
+
+
+def _r2_class(ratio):
+    if ratio is None:
+        return None
+    if ratio < _R2_SIGNAL:
+        return "SIGNAL"
+    if ratio < _R2_NOISE:
+        return "NOISY"
+    return "NOISE"
+
+
+def _r2_entry(entry_dir, name):
+    """Intra-model variance for ONE bench entry (ADR-027): for each model with a run-1 (top-level
+    c-<model>) AND a run-2 (r2/c-<model>), the structural distance between the two runs via the
+    SAME _struct_distance the bench uses between compilers, each run's oracle pass-rate, and
+    whether the two runs agree on every oracle case. Entries without r2/ report absent, never 0."""
+    ir_graph, ir_errors = _load_ir_at(os.path.join(entry_dir, IR_FILE))
+    try:
+        with open(os.path.join(entry_dir, "oracle", "ORACLE.json"), encoding="utf-8-sig") as fh:
+            cases = (json.load(fh) or {}).get("cases") or []
+    except (OSError, ValueError):
+        cases = []
+    rec = {"archetype": name, "has_r2": False, "models": [], "intra_mean": None,
+           "inter": None, "intra_over_inter": None, "class": None, "reason": None}
+    r2 = os.path.join(entry_dir, _R2_DIR)
+    if not os.path.isdir(r2):
+        rec["reason"] = "no r2/ directory -- intra-model variance not measured"
+        return rec, False
+    rec["has_r2"] = True
+    if ir_graph is None or ir_errors or not cases:
+        rec["reason"] = "entry incomplete (missing/invalid IR or oracle)"
+        return rec, False
+
+    def load_run(cd):
+        cj = os.path.join(cd, "COMPILATION.json")
+        if not os.path.isfile(cj):
+            return None
+        errors, _adv = _validate_compilation(cj, ir_graph)
+        try:
+            with open(cj, encoding="utf-8-sig") as fh:
+                c = json.load(fh)
+            unit = _entry_unit(c.get("source") or [])
+            model = (c.get("compilation_report") or {}).get("model")
+        except (OSError, ValueError, AttributeError, IndexError):
+            return None
+        impl = os.path.join(cd, unit.replace("/", os.sep)) if unit else None
+        if not impl or not os.path.isfile(impl):
+            return None
+        ores = _bench_oracle_all(impl, cases)
+        m = _impl_metrics(impl)
+        return {"model": model, "compile_valid": not errors, "oracle": ores,
+                "metrics": m if "error" not in m else None,
+                "case_vector": tuple(sorted(ores.get("failing") or []))}
+
+    def rate(o):
+        return round(o["passed"] / o["total"], 3) if o["total"] else None
+
+    intra = []
+    run1_metrics = []
+    has_js = False                                  # footer disclosure only; not serialized
+    for d in sorted(os.listdir(entry_dir)):
+        if not d.startswith("c-") or not os.path.isdir(os.path.join(entry_dir, d)):
+            continue
+        r1 = load_run(os.path.join(entry_dir, d))
+        if r1 is None:
+            continue
+        if r1["metrics"]:
+            run1_metrics.append(r1["metrics"])
+            if r1["metrics"]["path"].lower().endswith(".js"):
+                has_js = True
+        r2run = load_run(os.path.join(r2, d))
+        if r2run is None:
+            rec["models"].append({"dir": d, "model": r1["model"], "r2": "absent"})
+            continue
+        if r2run["metrics"] and r2run["metrics"]["path"].lower().endswith(".js"):
+            has_js = True
+        dist = (_struct_distance(r1["metrics"], r2run["metrics"])
+                if r1["metrics"] and r2run["metrics"] else None)
+        stable = r1["case_vector"] == r2run["case_vector"]
+        rec["models"].append({"dir": d, "model": r1["model"],
+                              "intra_distance": round(dist, 4) if dist is not None else None,
+                              "run1_passrate": rate(r1["oracle"]),
+                              "run2_passrate": rate(r2run["oracle"]),
+                              "run2_compile_valid": r2run["compile_valid"],
+                              "behaviour_stable": stable})
+        if dist is not None:
+            intra.append(dist)
+    if intra:
+        rec["intra_mean"] = round(sum(intra) / len(intra), 4)
+    inter = []
+    for i in range(len(run1_metrics)):
+        for j in range(i + 1, len(run1_metrics)):
+            inter.append(_struct_distance(run1_metrics[i], run1_metrics[j]))
+    if inter:
+        rec["inter"] = round(sum(inter) / len(inter), 4)
+    if rec["intra_mean"] is not None and rec["inter"]:
+        # 2 dp on purpose: the ratio moves by up to ~0.26 between interpreters (ast.walk
+        # counts nodes differently on 3.8 vs 3.13 -- the 1.84.0 review measured it); more
+        # decimals would print precision the measurement does not have (ADR-027).
+        rec["intra_over_inter"] = round(rec["intra_mean"] / rec["inter"], 2)
+        rec["class"] = _r2_class(rec["intra_over_inter"])
+    elif rec["intra_mean"] is not None and rec["inter"] == 0.0:
+        rec["reason"] = "inter-compiler distance is 0 (converged run-1) -- ratio undefined"
+    elif rec["intra_mean"] is None:
+        # r2/ exists but no model pair yielded a computable distance (unparseable source,
+        # missing COMPILATION.json in every r2 model): absent, named -- never a silent None
+        rec["reason"] = ("r2/ present but no model pair measurable (no parseable run-1+run-2 "
+                         "source for any model) -- intra-model variance not measured")
+    return rec, has_js
+
+
+_R2_VERDICT_TEXT = {
+    "SIGNAL": "Across the measured entries, same-model reruns differ far less than different "
+              "models do: the inter-compiler variance the program reports is signal, not sampling "
+              "noise -- for these archetypes, at n=2 per model.",
+    "NOISY": "Same-model reruns differ by a sizeable fraction of the inter-compiler distance: "
+             "inter-compiler variance carries information, but a delta smaller than the noise "
+             "floor should not be read as an effect.",
+    "NOISE": "Same-model reruns differ as much as different models do: the inter-compiler "
+             "variance the program reports is dominated by sampling noise for these archetypes -- "
+             "variance-based claims must be re-read.",
+    "UNMEASURED": "No entry carries a second run; the noise floor is absent, not zero.",
+}
+
+
+def _render_r2_md(recs, agg, has_js=False):
+    lines = ["<!-- GENERATED by qa_ledger.py bench-r2 (ADR-027) -- measured run; do not hand-edit. -->",
+             "", "# DIAMOND-BENCH-R2 -- intra-model variance, the noise floor under the bench", "",
+             "For every archetype with a second blind run (`r2/`) of the SAME model on the SAME "
+             "canonical package: the structural distance between run 1 and run 2 (the same "
+             "function the bench uses BETWEEN compilers), each run's oracle pass-rate, and "
+             "whether both runs fail the same oracle cases. `intra/inter` below 0.5 reads SIGNAL "
+             "(inter-compiler variance is at least twice the noise floor), 0.5-1.0 NOISY, at or "
+             "above 1.0 NOISE (same-model reruns differ as much as different models). Advisory: "
+             "no bench verdict changes; this qualifies every variance claim the program makes.", "",
+             "| Archetype | intra (mean) | inter | intra/inter | class | per model (run1 -> run2 pass-rate, stable) |",
+             "|-----------|--------------|-------|-------------|-------|--------------------------------------------|"]
+    for r in recs:
+        if not r["has_r2"]:
+            lines.append("| %s | -- | -- | -- | (no r2) | %s |" % (r["archetype"], r["reason"] or ""))
+            continue
+        pm = "; ".join(("%s %s->%s %s" % (m["dir"], m.get("run1_passrate"), m.get("run2_passrate"),
+                                         "stable" if m.get("behaviour_stable") else "DIFFERS"))
+                       if m.get("r2") != "absent" else ("%s (r2 absent)" % m["dir"])
+                       for m in r["models"])
+        lines.append("| %s | %s | %s | %s | %s | %s |" % (
+            r["archetype"],
+            "%.4f" % r["intra_mean"] if r["intra_mean"] is not None else "--",
+            "%.4f" % r["inter"] if r["inter"] is not None else "--",
+            "%.2f" % r["intra_over_inter"] if r["intra_over_inter"] is not None else "--",
+            r["class"] or (r["reason"] or "--"), pm))
+    lines += ["", "**Aggregate:** %d entries measured -- SIGNAL %d · NOISY %d · NOISE %d · mean "
+              "intra/inter %s · behaviour-stable reruns %d/%d." % (
+                  agg["measured"], agg["signal"], agg["noisy"], agg["noise"],
+                  "%.3f" % agg["mean_ratio"] if agg["mean_ratio"] is not None else "n/a",
+                  agg["stable"], agg["reruns"]),
+              "", "## Verdict: %s" % agg["verdict"], "", _R2_VERDICT_TEXT[agg["verdict"]],
+              "", "*Structural distance = mean of normalized LOC delta, AST-node delta and "
+              "import-set Jaccard distance -- the one function shared by lang-compare, bench "
+              "and bench-r2. n=2 per model is the minimum that yields a floor at all; it is a "
+              "floor, not a distribution. The ratio is printed to 2 decimals on purpose: the "
+              "AST-node count differs between Python versions (ast.walk on 3.8 vs 3.13), so a "
+              "ratio can move by up to ~0.26 across interpreters without any code or model "
+              "changing -- classes are stable across 3.8/3.13 on this bench, ratios are not "
+              "point-precise, and an entry within ~0.25 of a threshold should be read as "
+              "borderline.*", ""]
+    if has_js:
+        lines += ["*JS pairs use a 2-dimensional distance (LOC + import Jaccard; no stdlib JS "
+                  "AST).*", ""]
+    return "\n".join(lines)
+
+
+def cmd_bench_r2(args):
+    if not os.path.isdir(args.dir):
+        print("[qa_ledger] bench-r2: no directory %s" % args.dir, file=sys.stderr)
+        sys.exit(2)
+    entries = sorted(d for d in os.listdir(args.dir)
+                     if os.path.isfile(os.path.join(args.dir, d, IR_FILE)))
+    if not entries:
+        print("[qa_ledger] bench-r2: no entries under %s" % args.dir, file=sys.stderr)
+        sys.exit(2)
+    pairs = [_r2_entry(os.path.join(args.dir, e), e) for e in entries]
+    recs = [p[0] for p in pairs]
+    has_js = any(p[1] for p in pairs)
+    measured = [r for r in recs if r["class"] is not None]
+    ratios = [r["intra_over_inter"] for r in measured]
+    reruns = [m for r in recs if r["has_r2"] for m in r["models"] if m.get("r2") != "absent"]
+    agg = {"entries": len(recs), "with_r2": sum(1 for r in recs if r["has_r2"]),
+           "measured": len(measured),
+           "signal": sum(1 for r in measured if r["class"] == "SIGNAL"),
+           "noisy": sum(1 for r in measured if r["class"] == "NOISY"),
+           "noise": sum(1 for r in measured if r["class"] == "NOISE"),
+           "mean_ratio": round(sum(ratios) / len(ratios), 3) if ratios else None,
+           "reruns": len(reruns),
+           "stable": sum(1 for m in reruns if m.get("behaviour_stable"))}
+    if not measured:
+        agg["verdict"] = "UNMEASURED"
+    else:
+        counts = [(agg["signal"], "SIGNAL"), (agg["noisy"], "NOISY"), (agg["noise"], "NOISE")]
+        top = max(c for c, _ in counts)
+        # ties resolve toward the more cautious reading (NOISE > NOISY > SIGNAL)
+        agg["verdict"] = [n for c, n in reversed(counts) if c == top][0]
+    md = _render_r2_md(recs, agg, has_js)
+    if args.out:
+        with open(args.out, "w", encoding="utf-8", newline="\n") as fh:
+            fh.write(md)
+    if args.json:
+        print(json.dumps({"aggregate": agg, "raw": recs}, indent=2, ensure_ascii=False))
+    else:
+        print("BENCH-R2: %d entries, %d with r2, %d measured -- SIGNAL %d / NOISY %d / NOISE %d"
+              % (agg["entries"], agg["with_r2"], agg["measured"], agg["signal"], agg["noisy"],
+                 agg["noise"]))
+        for r in recs:
+            if r["class"]:
+                print("  %-17s intra %.4f  inter %.4f  ratio %.2f  %s"
+                      % (r["archetype"], r["intra_mean"], r["inter"], r["intra_over_inter"],
+                         r["class"]))
+            elif r["has_r2"]:
+                print("  %-17s %s" % (r["archetype"], r["reason"]))
+        print("VERDICT: %s%s" % (agg["verdict"], ("  -> %s" % args.out) if args.out else ""))
+        print("  (ratios are not point-precise: AST-node counts differ across Python versions; "
+              "classes stable, ratios +/-0.25 -- read borderline entries as borderline)")
+    sys.exit(0)
+
+
+_RT_ID_RE = re.compile(r"(?i)\b(AC|INV|ADR)[-_][A-Z0-9-]*?\d+\b")
+
+
+def _rt_ids_in(text):
+    """Every canonical id (AC-*, INV-*, ADR-*) literally referenced in a text, upper-cased.
+    ID REFERENCE only (the ADR-013 rule) -- no fuzzy or semantic matching, ever."""
+    out = set()
+    for m in _RT_ID_RE.finditer(text or ""):
+        out.add(m.group(0).upper().replace("_", "-"))
+    return out
+
+
+def _rt_read_source(cd, unit):
+    try:
+        with open(os.path.join(cd, unit.replace("/", os.sep)), encoding="utf-8",
+                  errors="replace") as fh:
+            return fh.read()
+    except OSError:
+        return ""
+
+
+def _rt_compilation(entry_dir, cd, ir_graph, cases):
+    """Round-trip recoverability of ONE compilation against the pinned IR (ADR-030): for every
+    IR node, whether the mechanical reverse organs find footing for it in the artifact --
+    (a) static: a source unit's text or a static observation literally references the id;
+    (b) manifest: the compiler's validated trace manifest maps the node to a unit that exists;
+    (c) behaviour: for AC nodes, at least one withheld-oracle case tagged with the id passes
+    (UNMEASURED when no case carries any AC tag). It regenerates NOTHING: no IR', no spec --
+    a coverage over the human-authored IR, plus the list of nodes nothing anchors."""
+    cj = os.path.join(cd, "COMPILATION.json")
+    try:
+        with open(cj, encoding="utf-8-sig") as fh:
+            c = json.load(fh)
+    except (OSError, ValueError):
+        return None
+    units = [u.get("unit") for u in (c.get("source") or []) if isinstance(u, dict) and u.get("unit")]
+    units = [u for u in units if os.path.isfile(os.path.join(cd, u.replace("/", os.sep)))]
+    node_ids = [n["id"] for n in (ir_graph.get("nodes") or [])]
+    # (a) static footing: ids referenced in source text (comments/docstrings/names) or in
+    # the static observations' statements/provenance
+    static_ids = set()
+    for u in units:
+        static_ids |= _rt_ids_in(_rt_read_source(cd, u))
+        so, _un = _static_surface_for(cd, u)
+        for o in so:
+            static_ids |= _rt_ids_in(o.get("statement", ""))
+    # (b) manifest footing
+    manifest_ids = set()
+    for e in c.get("trace_manifest") or []:
+        if e.get("unit") in units:
+            for nid in e.get("implements") or []:
+                manifest_ids.add(str(nid).upper())
+    # (c) behaviour footing: oracle cases whose NAME carries an AC id (payload tags are not a
+    # convention the bench oracles use today -- absence named, not faked)
+    tagged = {}
+    for case in cases:
+        for cid in _rt_ids_in(case.get("name", "")):
+            tagged.setdefault(cid, []).append(case)
+    behaviour_measured = bool(tagged)
+    behaviour_ids = set()
+    entry_unit = _entry_unit(c.get("source") or [])
+    impl = os.path.join(cd, entry_unit.replace("/", os.sep)) if entry_unit else None
+    if behaviour_measured and impl and os.path.isfile(impl):
+        for cid, cs in tagged.items():
+            if any(_run_oracle_case(impl, case).get("ok") for case in cs):
+                behaviour_ids.add(cid)
+    per_node = []
+    anchored = 0
+    for nid in node_ids:
+        a_s = nid in static_ids
+        a_m = nid in manifest_ids
+        a_b = (nid in behaviour_ids) if (behaviour_measured and nid.startswith("AC-")) else None
+        anchored_any = a_s or a_m or bool(a_b)
+        # the MEASURED footing excludes the manifest: the manifest is what the compiler
+        # CLAIMED (and the prompt handed it the ids), so counting it as recovered would be
+        # tautological -- the 1.000 that means nothing (found on the first run of this tool)
+        anchored_meas = a_s or bool(a_b)
+        anchored += 1 if anchored_meas else 0
+        per_node.append({"id": nid, "static": a_s, "manifest": a_m,
+                         "behaviour": a_b, "anchored": anchored_meas,
+                         "claimed": anchored_any})
+    edges = ir_graph.get("edges") or []
+    anch_ids = {n["id"] for n in per_node if n["anchored"]}
+    edges_recovered = sum(1 for e in edges if e.get("from") in anch_ids and e.get("to") in anch_ids)
+    claimed = sum(1 for n in per_node if n["claimed"])
+    return {"dir": os.path.basename(cd), "units": len(units),
+            "ir_nodes": len(node_ids), "anchored": anchored, "claimed": claimed,
+            "recoverability": round(anchored / len(node_ids), 3) if node_ids else None,
+            "claimed_share": round(claimed / len(node_ids), 3) if node_ids else None,
+            "static_anchored": sum(1 for n in per_node if n["static"]),
+            "manifest_anchored": sum(1 for n in per_node if n["manifest"]),
+            "behaviour": ("UNMEASURED" if not behaviour_measured
+                          else sum(1 for n in per_node if n["behaviour"])),
+            "edges": len(edges), "edges_recovered": edges_recovered,
+            "unanchored": [n["id"] for n in per_node if not n["anchored"]],
+            "nodes": per_node}
+
+
+def _rt_entry(entry_dir, name):
+    ir_graph, ir_errors = _load_ir_at(os.path.join(entry_dir, IR_FILE))
+    try:
+        with open(os.path.join(entry_dir, "oracle", "ORACLE.json"), encoding="utf-8-sig") as fh:
+            cases = (json.load(fh) or {}).get("cases") or []
+    except (OSError, ValueError):
+        cases = []
+    rec = {"archetype": name, "compilations": [], "ir_nodes": None, "edges": None,
+           "recoverability_mean": None, "edges_recovered_mean": None, "reason": None}
+    if ir_graph is None or ir_errors:
+        rec["reason"] = "entry incomplete (missing/invalid IR)"
+        return rec
+    rec["ir_nodes"] = len(ir_graph.get("nodes") or [])
+    rec["edges"] = len(ir_graph.get("edges") or [])
+    for d in sorted(os.listdir(entry_dir)):
+        cd = os.path.join(entry_dir, d)
+        if d.startswith("c-") and os.path.isfile(os.path.join(cd, "COMPILATION.json")):
+            r = _rt_compilation(entry_dir, cd, ir_graph, cases)
+            if r:
+                rec["compilations"].append(r)
+    recs = [c["recoverability"] for c in rec["compilations"] if c["recoverability"] is not None]
+    if recs:
+        rec["recoverability_mean"] = round(sum(recs) / len(recs), 3)
+        rec["edges_recovered_mean"] = round(
+            sum(c["edges_recovered"] for c in rec["compilations"]) / len(rec["compilations"]), 2)
+    else:
+        rec["reason"] = "no compilations yet"
+    return rec
+
+
+def _render_rt_md(recs, agg):
+    lines = ["<!-- GENERATED by qa_ledger.py bench-roundtrip (ADR-030) -- measured run; do not hand-edit. -->",
+             "", "# DIAMOND-ROUNDTRIP -- how much of the pinned IR the reverse organs can anchor in each compiled artifact", "",
+             "**What this is NOT:** it does not regenerate an IR from code, it does not diff specs, "
+             "it does not infer requirements. Reverse discovery produces FACTS (ADR-013); the human "
+             "authors the spec. This instrument joins those facts against the human-authored IR "
+             "and reports, per compilation, which nodes have footing -- (a) static: the id is "
+             "literally referenced in a source unit or a static observation; (b) manifest: the "
+             "compiler's validated trace manifest maps the node to a unit that exists; (c) "
+             "behaviour: a withheld-oracle case tagged with the AC id passes (UNMEASURED where "
+             "the entry's oracle cases carry no AC tag -- absence named). **`recoverability` "
+             "counts ONLY static + behaviour footing** -- the manifest is what the compiler "
+             "CLAIMED (and the blind prompt handed it the node ids), so it is reported apart as "
+             "`claimed` and never counted as recovered: the first run of this instrument read "
+             "1.000 on every entry for exactly that reason. `edges recovered` = edges with both "
+             "endpoints MEASURED-anchored. Advisory: no bench verdict changes. The unanchored "
+             "list IS the honest gap, per compiler.", "",
+             "| Archetype | IR nodes | edges | recoverability (mean, measured) | edges recovered (mean) | per compilation (measured/nodes · static · behaviour · claimed-by-manifest · unanchored) |",
+             "|-----------|----------|-------|---------------------------------|------------------------|--------------------------------------------------------------------------------------------|"]
+    for r in recs:
+        if r["recoverability_mean"] is None:
+            lines.append("| %s | %s | %s | -- | -- | %s |" % (r["archetype"], r["ir_nodes"], r["edges"], r["reason"] or ""))
+            continue
+        pc = "; ".join("%s %d/%d · s%d · b%s · claimed %d · [%s]" % (
+            c["dir"], c["anchored"], c["ir_nodes"], c["static_anchored"],
+            c["behaviour"], c["manifest_anchored"], ",".join(c["unanchored"]) or "none")
+            for c in r["compilations"])
+        lines.append("| %s | %d | %d | %.3f | %.2f | %s |" % (
+            r["archetype"], r["ir_nodes"], r["edges"], r["recoverability_mean"],
+            r["edges_recovered_mean"], pc))
+    lines += ["", "**Aggregate:** %d entries measured · mean recoverability %s · entries with edges %d "
+              "· behaviour dimension measured in %d/%d entries." % (
+                  agg["measured"], "%.3f" % agg["mean_recoverability"] if agg["mean_recoverability"] is not None else "n/a",
+                  agg["with_edges"], agg["behaviour_measured"], agg["measured"]),
+              "", "*The manifest dimension is what the compiler CLAIMED (validated for shape, "
+              "not truth) and is excluded from recoverability; the static dimension is what the "
+              "artifact literally names; the behaviour dimension is what the withheld oracle can "
+              "attribute per AC -- and it is UNMEASURED wherever oracle cases are not tagged with "
+              "AC ids, which today is every entry: the honest state of reverse discovery is that "
+              "it anchors names, not semantics, until oracles carry per-AC tags. None of the three "
+              "is a spec.*", ""]
+    return "\n".join(lines)
+
+
+def cmd_bench_roundtrip(args):
+    if not os.path.isdir(args.dir):
+        print("[qa_ledger] bench-roundtrip: no directory %s" % args.dir, file=sys.stderr)
+        sys.exit(2)
+    entries = sorted(d for d in os.listdir(args.dir)
+                     if os.path.isfile(os.path.join(args.dir, d, IR_FILE)))
+    if not entries:
+        print("[qa_ledger] bench-roundtrip: no entries under %s" % args.dir, file=sys.stderr)
+        sys.exit(2)
+    recs = [_rt_entry(os.path.join(args.dir, e), e) for e in entries]
+    measured = [r for r in recs if r["recoverability_mean"] is not None]
+    agg = {"entries": len(recs), "measured": len(measured),
+           "mean_recoverability": (round(sum(r["recoverability_mean"] for r in measured) / len(measured), 3)
+                                   if measured else None),
+           "with_edges": sum(1 for r in measured if (r["edges"] or 0) > 0),
+           "behaviour_measured": sum(1 for r in measured
+                                     if any(c["behaviour"] != "UNMEASURED" for c in r["compilations"]))}
+    md = _render_rt_md(recs, agg)
+    if args.out:
+        with open(args.out, "w", encoding="utf-8", newline="\n") as fh:
+            fh.write(md)
+    if args.json:
+        print(json.dumps({"aggregate": agg, "raw": recs}, indent=2, ensure_ascii=False))
+    else:
+        print("BENCH-ROUNDTRIP: %d entries, %d measured -- mean recoverability %s, %d with edges, "
+              "behaviour measured in %d" % (agg["entries"], agg["measured"],
+                                            "%.3f" % agg["mean_recoverability"] if agg["mean_recoverability"] is not None else "n/a",
+                                            agg["with_edges"], agg["behaviour_measured"]))
+        for r in recs:
+            if r["recoverability_mean"] is not None:
+                print("  %-17s nodes %2d edges %d  recover %.3f  edges-rec %.2f" % (
+                    r["archetype"], r["ir_nodes"], r["edges"], r["recoverability_mean"], r["edges_recovered_mean"]))
+        if args.out:
+            print("  -> %s" % args.out)
+    sys.exit(0)
+
+
 def _bench_curable_obs(bench_dir, entry, cdir):
     """The curable set for one compilation: the SAME observations the M1 static extractor
     produces for the descriptor's static_surface, re-extracted at call time -- a verdict
@@ -5802,13 +6460,20 @@ def _bench_curable_obs(bench_dir, entry, cdir):
         with open(cj, encoding="utf-8-sig") as fh:
             c = json.load(fh)
         src = c.get("source") or []
-        unit = src[0].get("unit") if src else None
+        units = [u.get("unit") for u in src if isinstance(u, dict) and u.get("unit")]
     except (OSError, ValueError, AttributeError, IndexError):
-        unit = None
-    if not unit or not os.path.isfile(os.path.join(cd, unit.replace("/", os.sep))):
+        units = []
+    units = [u for u in units if os.path.isfile(os.path.join(cd, u.replace("/", os.sep)))]
+    if not units:
         return None, ("%s/%s: no resolvable source unit -- nothing to extract a surface "
                       "from" % (entry, cdir))
-    sobs, _uns = _extract_static_py(cd, [unit])
+    sobs, uns = [], []
+    for u in units:
+        so, un = _static_surface_for(cd, u)
+        sobs.extend(so)
+        uns.extend(un)
+    if not sobs and uns:
+        return None, ("%s/%s: static surface UNMEASURED -- %s" % (entry, cdir, "; ".join(uns)))
     return sobs, None
 
 
@@ -5895,7 +6560,9 @@ _LANG_PR_MARGIN = 0.02                              # mean oracle pass-rate drop
 
 def _lang_arm_metrics(arm_dir):
     """Measure ONE arm: per-compiler oracle green + unresolved_intent, and inter-compiler
-    variance over the arm's compilations. Reuses the M4/M5 organs unchanged."""
+    variance over the arm's compilations. Reuses the M4/M5 organs unchanged. Returns
+    (rec, errors, has_js) -- has_js is a footer-only signal for _render_lang_md (ADR-028);
+    it is never part of `rec`, so lang-compare's JSON output is untouched by it."""
     ir_graph, ir_errors = _load_ir_at(os.path.join(arm_dir, IR_FILE))
     try:
         with open(os.path.join(arm_dir, "oracle", "ORACLE.json"), encoding="utf-8-sig") as fh:
@@ -5907,7 +6574,7 @@ def _lang_arm_metrics(arm_dir):
            "mean_passrate": None, "ui_count": 0.0, "ui_distinct_regions": 0.0,
            "ui_rationale_len": 0.0}
     if ir_graph is None or ir_errors or not cases:
-        return rec, ["arm incomplete (missing/invalid IR or oracle)"]
+        return rec, ["arm incomplete (missing/invalid IR or oracle)"], False
     comp_dirs = sorted(d for d in os.listdir(arm_dir)
                        if d.startswith("c-") and
                        os.path.isfile(os.path.join(arm_dir, d, "COMPILATION.json")))
@@ -5921,7 +6588,7 @@ def _lang_arm_metrics(arm_dir):
             with open(cj, encoding="utf-8-sig") as fh:
                 c = json.load(fh)
             src = c.get("source") or []
-            unit = src[0].get("unit") if src else None
+            unit = _entry_unit(src)
             model = (c.get("compilation_report") or {}).get("model")
             uis = c.get("unresolved_intent") or []
         except (OSError, ValueError, AttributeError, IndexError):
@@ -5954,14 +6621,29 @@ def _lang_arm_metrics(arm_dir):
     dists = []
     for i in range(len(good)):
         for j in range(i + 1, len(good)):
-            a, b = good[i], good[j]
-            ia, ib = set(a["imports"]), set(b["imports"])
-            jac = (len(ia & ib) / len(ia | ib)) if (ia or ib) else 1.0
-            dloc = abs(a["loc"] - b["loc"]) / max(a["loc"], b["loc"], 1)
-            dast = abs(a["ast_nodes"] - b["ast_nodes"]) / max(a["ast_nodes"], b["ast_nodes"], 1)
-            dists.append((dloc + dast + (1.0 - jac)) / 3.0)
+            dists.append(_struct_distance(good[i], good[j]))
     rec["variance_score"] = round(sum(dists) / len(dists), 4) if dists else None
-    return rec, []
+    has_js = any(p.lower().endswith(".js") for p in impl_paths)
+    return rec, [], has_js
+
+
+def _struct_distance(a, b):
+    """The ONE structural distance the program uses between two implementations -- mean of
+    normalized LOC delta, AST-node delta and import-set Jaccard distance (0 = identical). Shared
+    by the inter-compiler variance (lang-compare, bench) and the intra-model variance (bench-r2,
+    ADR-027) so their ratio is commensurable: same function, both sides.
+
+    ADR-028: a `.js` metrics dict has `ast_nodes: None` (no stdlib JS AST) -- when either side
+    lacks it, the distance is the mean over the dimensions BOTH sides have (LOC + import
+    Jaccard only). A cross-language pair never occurs (one archetype, one language), so this
+    never mixes a Python 3-dimensional distance with a JS 2-dimensional one within a pair."""
+    ia, ib = set(a["imports"]), set(b["imports"])
+    jac = (len(ia & ib) / len(ia | ib)) if (ia or ib) else 1.0
+    dloc = abs(a["loc"] - b["loc"]) / max(a["loc"], b["loc"], 1)
+    if a.get("ast_nodes") is None or b.get("ast_nodes") is None:
+        return (dloc + (1.0 - jac)) / 2.0
+    dast = abs(a["ast_nodes"] - b["ast_nodes"]) / max(a["ast_nodes"], b["ast_nodes"], 1)
+    return (dloc + dast + (1.0 - jac)) / 3.0
 
 
 def _oracle_hash(arm_dir):
@@ -5987,8 +6669,9 @@ def cmd_lang_compare(args):
               "the comparison requires the SAME withheld oracle; behaviour must be held fixed "
               "while only the authoring changes." % (hf[:12], hc[:12]), file=sys.stderr)
         sys.exit(2)
-    free, ef = _lang_arm_metrics(args.free)
-    ctrl, ec = _lang_arm_metrics(args.controlled)
+    free, ef, has_js_f = _lang_arm_metrics(args.free)
+    ctrl, ec, has_js_c = _lang_arm_metrics(args.controlled)
+    has_js = has_js_f or has_js_c
     if ef or ec:
         for e in ef + ec:
             print("[qa_ledger] lang-compare: %s" % e, file=sys.stderr)
@@ -6027,7 +6710,7 @@ def cmd_lang_compare(args):
               "margin": _LANG_MARGIN, "passrate_margin": _LANG_PR_MARGIN, "oracle_shared": True}
     if args.out:
         with open(args.out, "w", encoding="utf-8", newline="\n") as fh:
-            fh.write(_render_lang_md(report))
+            fh.write(_render_lang_md(report, has_js))
     if args.json:
         print(json.dumps(report, indent=2, ensure_ascii=False))
     else:
@@ -6051,7 +6734,7 @@ def cmd_lang_compare(args):
     sys.exit(0)
 
 
-def _render_lang_md(r):
+def _render_lang_md(r, has_js=False):
     d = r["delta"]
     lines = ["<!-- GENERATED by qa_ledger.py lang-compare (ADR-019) -- measured run; do not "
              "hand-edit. -->", "", "# CONTROLLED-LANGUAGE-REPORT", "",
@@ -6093,11 +6776,16 @@ def _render_lang_md(r):
                            "arm's low variance was convergence on a shared reading (right or "
                            "wrong): two compilers resolving the same ambiguity the same way read "
                            "as agreement, and a rewrite that separates them raises variance "
-                           "while moving behaviour."
+                           "while moving behaviour. Read any variance number here against the "
+                           "entry's intra-model noise floor (bench-r2, ADR-027): an inter-compiler "
+                           "distance below that floor is not evidence of convergence."
                            % r.get("passrate_margin", 0.02)}[r["verdict"]],
               "", "*The oracle is byte-identical across both arms, so behaviour is held fixed; "
               "the only variable is the authoring discipline. The judgement of \"same semantic "
               "content\" between the two canonical packages is human — a stated limitation.*", ""]
+    if has_js:
+        lines += ["*JS pairs use a 2-dimensional distance (LOC + import Jaccard; no stdlib JS "
+                  "AST).*", ""]
     return "\n".join(lines)
 
 
@@ -10246,6 +10934,28 @@ def build_parser():
                           "(read-only), including stale verdicts whose obs no longer exists")
     pbc.set_defaults(func=cmd_bench_curate)
 
+    pbr = sub.add_parser(
+        "bench-r2",
+        help="intra-model variance (ADR-027): for every bench entry with an r2/ second run of "
+             "the same models, the run1-vs-run2 structural distance via the SAME function the "
+             "bench uses between compilers, oracle stability, and a per-entry SIGNAL/NOISY/NOISE "
+             "class; the noise floor under every variance claim; advisory, deterministic, no LLM")
+    pbr.add_argument("--dir", required=True, help="the bench directory")
+    pbr.add_argument("--out", default=None, help="write DIAMOND-BENCH-R2.md here")
+    pbr.add_argument("--json", action="store_true")
+    pbr.set_defaults(func=cmd_bench_r2)
+
+    prt = sub.add_parser(
+        "bench-roundtrip",
+        help="round-trip recoverability (ADR-030): per compilation, which pinned-IR nodes the "
+             "mechanical reverse organs can anchor in the compiled artifact -- static id "
+             "reference, validated manifest claim, tagged withheld-oracle behaviour -- and the "
+             "unanchored gap list; regenerates NO IR, infers NO spec; advisory, deterministic")
+    prt.add_argument("--dir", required=True, help="the bench directory")
+    prt.add_argument("--out", default=None, help="write DIAMOND-ROUNDTRIP.md here")
+    prt.add_argument("--json", action="store_true")
+    prt.set_defaults(func=cmd_bench_roundtrip)
+
     plc = sub.add_parser(
         "lang-compare",
         help="controlled-language arm (ADR-019): compare a FREE-prose arm and an EARS+STE arm of "