candor-ts 0.30.0 → 0.32.0

package/policy.mjs

@@ -17,6 +17,121 @@ export const REASON_CLASSES = ["reflect", "dispatch", "indirect", "native", "unr
 // the flag and the policy filter name the same vocabulary, so `--class dynamic` and `Unknown[dynamic]`
 // cannot drift into meaning different sets.
 export const DYNAMIC_CLASSES = ["reflect", "dispatch", "indirect", "native", "unresolved"];
+
+// ⟨0.32⟩ THE UNIT IDENTITY, AS A PLUGGABLE POLICY — `units`, threaded through every function on this page
+// that keys an accumulator by a function.
+//
+// It exists because a MULTI-REPORT gate must join by `hash` and never by bare `fn` (SPEC §2.2: "names may
+// legitimately repeat across packages"), and this engine joined by `fn`. Measured on candor-ts at spec
+// 0.31: `gate --report` over member `a` REFUSED a scoped rule at exit 2, and gating that same member
+// beside an unrelated sibling exited 0 with `policy ✓` — a false green produced by ADDING a report. The
+// harm is not effects merging (union can only add violations); it is REASONS merging, because a reason
+// set is what makes an `Unknown` ANSWERABLE. `a`'s reasonless Unknown borrowed `b`'s `callback:` class,
+// the filter saw a class the rule does not deny, and tolerated: "I cannot say" became "I checked".
+//
+// AND THE KEY SWAP CANNOT BE MADE ALONE, which is why the identity is a PARAMETER rather than a hardcoded
+// `e.hash`. A policy SCOPE is written against the NAME (`deny Exec app::`) and the verdict ROW must print
+// the NAME (§3.3.1 byte-equality with `scan --policy`), so a key that is not a name has to travel BESIDE
+// the name, never instead of it. Keying by hash without that separation is a false green introduced while
+// fixing a false green — the shape where killing an over-charge introduces a silent under-report. Hence
+// the split landing: this identity is plumbed and verified a NO-OP first, and only then swapped.
+//
+// `identityUnits()` is the SCAN route's identity and the default everywhere: a scan gates ONE analysis
+// world, its keys are already names, so that route cannot change behaviour by construction.
+export const AMBIGUOUS = Symbol("candor:ambiguous-callee");
+
+export function identityUnits() {
+  return {
+    key: (e) => e?.fn,
+    /** A callee/caller NAME resolved to a unit key, `AMBIGUOUS`, or null. Under identity a name IS a key. */
+    resolveCall: (_callerKey, name) => name,
+    /** Every unit key declaring `name`. Under identity, the name itself. */
+    unitsNamed: (name) => [name],
+  };
+}
+
+/** `units.key` with the identity default applied, for the sites that take `units` as an option. */
+const unitKey = (units, e) => (units ? units.key(e) : e?.fn);
+
+/**
+ * ⟨0.32⟩ THE MULTI-REPORT UNIT IDENTITY (SPEC §2.2) — for `gate --report` and every verb that reads a
+ * report PREFIX, which may match several sibling files (a workspace writes one report per member).
+ *
+ * THE KEY IS `hash` REFINED BY `fn`, NOT `hash` ALONE, and that is an engine-MEASURED deviation from
+ * candor-rust rather than a hedge. A rust `hash` is a DefPathHash, unique per unit; THIS engine emits
+ * `<package>#<local tail>` (scan.mjs), which is not unique — measured on hono's own sources, 13 hashes are
+ * shared by two or more DISTINCT `fn`s, with five different `handle` functions all keying `src#handle`.
+ * Keying by bare `hash` would MERGE those five into one unit and let each borrow the others' reason
+ * classes: the very defect this closes, reopened inside a single report. `hash` refined by `fn` is
+ * strictly FINER than either bare key, so it never joins two entries that bare-`fn` kept apart, and it
+ * never joins across packages by name — which is what §2.2's MUST is about. No `hash`: the name is the key.
+ *
+ * The key is a JSON PAIR rather than a joined string, so there is no separator that could occur inside
+ * either field and no two distinct (hash, fn) pairs can collapse into one key. A SYNTHETIC key (a
+ * callgraph name no entry declares, see `unitsNamed`) is the bare name, which is never JSON-pair shaped.
+ */
+export function reportUnits(functions) {
+  const byName = new Map();
+  const pkgByKey = new Map();
+  const key = (e) => {
+    const h = typeof e?.hash === "string" ? e.hash : "";
+    return h ? JSON.stringify([h, String(e.fn)]) : String(e?.fn);
+  };
+  for (const f of functions ?? []) {
+    const k = key(f);
+    let s = byName.get(f.fn);
+    if (!s) { s = new Set(); byName.set(f.fn, s); }
+    s.add(k);
+    // The unit's PACKAGE, off the `hash` prefix and recorded here rather than parsed back out of the key
+    // — the key is an opaque identifier, and reading structure out of an identifier is how a rescue branch
+    // comes to depend on the shape a hash happens to have today.
+    const h = typeof f.hash === "string" ? f.hash : "";
+    const i = h.indexOf("#");
+    if (i > 0) pkgByKey.set(k, h.slice(0, i));
+  }
+  const pkgOf = (k) => pkgByKey.get(k) ?? "";
+  return {
+    key,
+    unitsNamed: (name) => {
+      const s = byName.get(name);
+      // A name NO entry declares is its own key. The §2.2 sidecar carries EVERY function while the report
+      // carries only the effectful ones, so an intermediate hop is routinely name-only — dropping it would
+      // break the chain that carries a callee's reason class up to its caller, and a LOST class is exactly
+      // how an unanswerable Unknown comes to look answerable.
+      return s ? [...s] : [name];
+    },
+    resolveCall: (callerKey, name) => {
+      const s = byName.get(name);
+      if (!s || s.size === 0) return name;      // not an entry: its own key, as above
+      if (s.size === 1) return [...s][0];
+      // SAME PACKAGE FIRST, and only where it settles the question on its own: a member calling a name its
+      // OWN package declares means that one, which is the common case and unambiguous.
+      const mine = pkgOf(callerKey);
+      if (mine) {
+        const same = [...s].filter((k) => pkgOf(k) === mine);
+        if (same.length === 1) return same[0];
+      }
+      // Otherwise two or more units declare it and nothing here can say which is meant. Picking is what
+      // the bare-`fn` join did implicitly, and it is wrong both ways — right by luck when the guess lands,
+      // inventing a reach when it does not. The CALLER carries the ambiguity instead; see
+      // `resolveReasonClasses`, where dropping it silently was measured reopening this very defect.
+      return AMBIGUOUS;
+    },
+  };
+}
+
+/**
+ * ⟨0.32⟩ The effect set the GATE reads for one entry: the report's `inferred`, plus `Unknown` when the
+ * merge could not resolve one of this entry's callee names (see `reportUnits`). An unresolvable callee
+ * means the transitive set on the wire cannot be completed here, and `Unknown` is what this family says
+ * about a reach it cannot follow. Never subtracts.
+ */
+export function effectiveInferred(f, reasonAcc, units = null) {
+  const inf = f?.inferred ?? [];
+  const amb = reasonAcc?.ambiguous;
+  if (!amb || amb.size === 0 || inf.includes("Unknown")) return inf;
+  return amb.has(unitKey(units, f)) ? [...inf, "Unknown"] : inf;
+}
 /** Map a raw `unknownWhy` token (e.g. `reflect:eval`, `callback:fetch`) to its normative reason class. */
 export function reasonClass(why) {
   const w = String(why).trim().toLowerCase();
@@ -49,8 +164,11 @@ export function reasonClass(why) {
 // function whose Unknown is purely INHERITED carries no reason of its own — 24% of Unknown-bearing entries
 // on this engine's sources and 57-58% on execa/got. Matching against the direct field reads a field that
 // answers a different question.
-export function resolveReasonClasses(functions, callgraph = {}) {
+export function resolveReasonClasses(functions, callgraph = {}, units = null) {
+  const U = units ?? identityUnits();
   const acc = new Map();
+  // ⟨0.32⟩ the units whose OWN callee name the merge could not resolve — see the contribution below.
+  const ambiguous = new Set();
   // ⟨0.24⟩ THE REACH IS THE REPORT'S OWN, not the sidecar's. §2 embeds the call edges per entry (`calls`)
   // precisely so a consumer without the sidecar can reconstruct the graph, and rust (`reason_class_acc`),
   // java (`gateInputFromReport`: `edges…addAll(e.calls())`) and swift all resolve the reason classes over
@@ -69,9 +187,37 @@ export function resolveReasonClasses(functions, callgraph = {}) {
     if (!s) { s = new Set(); edges.set(caller, s); }
     s.add(callee);
   };
-  for (const f of functions ?? []) for (const c of f.calls ?? []) addEdge(f.fn, c);
+  // ⟨0.32⟩ NODES AND EDGES. `calls` names a callee by BARE `fn`, so keying the accumulators by a unit key
+  // while joining the EDGES by name leaves the same defect one layer down — harder to see, because the
+  // node table looks right. Every edge endpoint therefore goes through `units.resolveCall`, which is
+  // identity on the scan route and the hash join on the report route.
+  const link = (callerKey, name) => {
+    const r = U.resolveCall(callerKey, name);
+    // AMBIGUOUS: two or more units declare this name and nothing here can say which is meant. Dropping
+    // the edge is right — picking would invent a reach — but dropping it SILENTLY is not, and that was
+    // measured on candor-rust: the caller lost the reason class it would have inherited, stayed
+    // ANSWERABLE through a reason of its own, and a RED verdict went GREEN by adding a report. So the
+    // ambiguity is CONTRIBUTED at the caller's entry instead (below), before the fixpoint.
+    if (r === AMBIGUOUS) { ambiguous.add(callerKey); return; }
+    if (r != null) addEdge(callerKey, r);
+  };
+  for (const f of functions ?? []) {
+    const ck = U.key(f);
+    for (const c of f.calls ?? []) link(ck, c);
+  }
   for (const [caller, callees] of Object.entries(callgraph ?? {})) {
-    for (const c of Array.isArray(callees) ? callees : []) addEdge(caller, c);
+    // The SIDECAR's caller is a NAME too, and it takes the SAME rule rather than a carve-out: one unit
+    // declaring it resolves, several means the edge cannot be attributed and each candidate carries the
+    // ambiguity. Attaching it to all of them would be the name join again, in the caller direction —
+    // and that direction is the harmful one, since a borrowed class is what makes an Unknown answerable.
+    // A name no entry declares keeps a key of its own (`unitsNamed` returns it), so an intermediate hop
+    // the report omits as effect-free still carries classes through, exactly as it did before.
+    const ckeys = U.unitsNamed(caller);
+    if (ckeys.length === 1) {
+      for (const c of Array.isArray(callees) ? callees : []) link(ckeys[0], c);
+    } else if (ckeys.length > 1) {
+      for (const k of ckeys) ambiguous.add(k);
+    }
   }
   for (const f of functions ?? []) {
     const cs = new Set((f.unknownWhy ?? []).map(reasonClass));
@@ -88,7 +234,17 @@ export function resolveReasonClasses(functions, callgraph = {}) {
     // direct Unknown it could not name (scan.mjs), which is the same rule one layer earlier, at the source.
     // It fires for a FOREIGN report (java/rust/swift/an older build), which every query verb also reads.
     if ((f.direct ?? []).includes("Unknown") && !(f.unknownWhy ?? []).length) cs.add("unresolved");
-    if (cs.size) acc.set(f.fn, cs);
+    if (cs.size) acc.set(U.key(f), cs);
+  }
+  // ⟨0.32⟩ …and the AMBIGUITY CONTRIBUTES, exactly as the reasonless Unknown above it does — at the
+  // caller's own entry, before the fixpoint. `dispatch` is the right class by the vocabulary's own
+  // definition ("unresolved virtual/dynamic dispatch, SAME-NAME AMBIGUITY"), and it is evidence THIS
+  // merge holds — it saw two declarers — never a class borrowed from another function's body, so it
+  // cannot make some other function's Unknown answerable, which is what the original defect did.
+  for (const k of ambiguous) {
+    let s = acc.get(k);
+    if (!s) { s = new Set(); acc.set(k, s); }
+    s.add("dispatch");
   }
   // …then propagate over the call graph to a fixpoint, so `Unknown[reflect]` at a caller inheriting
   // Unknown from a reflect-caused callee still fires (matches java/rust reasonClassAcc).
@@ -104,6 +260,10 @@ export function resolveReasonClasses(functions, callgraph = {}) {
       }
     }
   }
+  // ⟨0.32⟩ The unresolvable-callee set rides the accumulator NON-ENUMERABLY (the `zeroMatch` precedent
+  // below), so every existing caller keeps a plain `Map` and nothing that serializes one acquires a field
+  // the spec has not pinned. `effectiveInferred` is the only reader.
+  Object.defineProperty(acc, "ambiguous", { value: ambiguous, enumerable: false });
   return acc;
 }
 
@@ -495,6 +655,29 @@ export function refusalVerdict(spec, reason, unevaluated = null) {
   return o;
 }
 
+/** ⟨0.32⟩ **THE VERDICT'S ROW ORDER — SPEC §2: "the sort key MUST include that identity".**
+ *
+ * The other half of the ⟨0.32⟩ identity clause, stated separately in the spec because carrying `hash`
+ * in the ROW without carrying it in the KEY is half a fix. `(rule, detail)` TIES on two units that
+ * share a name — `detail` is built from the NAME — so the pair's order was whatever each route happened
+ * to accumulate in, and §3.3.1 makes the document's ORDER part of the byte-equality between
+ * `scan --policy` and `gate --report`. This engine had NO sort at all on either route: order was the
+ * `functions`-array order crossed with policy-rule order, which agrees between the two routes only for
+ * as long as the report is written in the order the scan discovered.
+ *
+ * ONE definition, called from both assembly sites — two copies of a rule is how this family ended up
+ * with two element rules for the manifest reader. Compared with `<`/`>` and never `localeCompare`:
+ * ⟨0.24⟩ §3.3.1 requires every ordering to be locale-INDEPENDENT. `Array.prototype.sort` has been
+ * stable since ES2019, so rows with an equal key keep their arrival order.
+ */
+export function sortViolations(violations) {
+  const c = (x, y) => (x < y ? -1 : x > y ? 1 : 0);
+  return violations.sort((a, b) =>
+    c(a?.rule ?? "", b?.rule ?? "")
+    || c(a?.detail ?? "", b?.detail ?? "")
+    || c(a?.hash ?? "", b?.hash ?? ""));
+}
+
 /** §6.2 scope match: by NAME SEGMENT, last segment a prefix.
  * Segments split on BOTH "." and "::" — Rust/Java qualify with "::" while TS uses ".", and a shared
  * policy must match across engines (a `Foo::bar` scope authored against Rust was inert in TS before). */
@@ -522,13 +705,26 @@ export function scopeMatchesPermitted(name, scope) {
 }
 
 export function scopeMatches(name, scope) {
+  // A TRAILING SEPARATOR MEANS EXACT SEGMENT — `app::` matches the segment `app` and nothing else,
+  // while bare `app` keeps the documented prefix behaviour and still matches `application_name`.
+  //
+  // REPORTED FROM THE FIELD (2026-08-23) and reproduced four-way: `forbid aws -> app` fired 14 times on
+  // honest AWS SDK calls, and writing `app::` did not help — the split drops empty parts, so `app::`
+  // became exactly ["app"] and the separator never survived to mean anything. The reporter deleted the
+  // rule, which is the real cost: the genuine violation it existed to catch will now never fire, and
+  // NOTHING in the policy file records that a boundary stopped being checked.
+  //
+  // ADDITIVE: bare `app` is unchanged, so no existing verdict moves. Only `app::` — which today
+  // silently behaves as `app` — starts meaning what everyone who writes it intends.
+  const exact = /(::|\.)\s*$/.test(scope);
   const segs = name.split(/[.:]+/).filter(Boolean);
   const parts = scope.split(/[.:]+/).filter(Boolean);
   if (parts.length === 0 || parts.length > segs.length) return false;
   const last = parts[parts.length - 1], init = parts.slice(0, -1);
   outer: for (let i = 0; i + parts.length <= segs.length; i++) {
     for (let k = 0; k < init.length; k++) if (segs[i + k] !== init[k]) continue outer;
-    if (segs[i + parts.length - 1].startsWith(last)) return true;
+    const tail = segs[i + parts.length - 1];
+    if (exact ? tail === last : tail.startsWith(last)) return true;
   }
   return false;
 }
@@ -593,15 +789,18 @@ export function literalAllowed(effect, reached, values) {
 //     entry (exit 2), so no gate DECISION rests on the empty set; what the mode additionally prevents is
 //     the class list a BARE `deny Net` violation REPORTS being re-derived from `hosts` — asserting a
 //     destination class the report never made, in a field a consumer reads as the producer's judgment.
-export function reportNetClasses(functions, { authoritative = false } = {}) {
+export function reportNetClasses(functions, { authoritative = false, units = null } = {}) {
   const m = new Map();
   for (const f of functions ?? []) {
     const carried = Array.isArray(f.netClass) ? f.netClass : [];
     if (carried.length === 0 && !(authoritative && (f.inferred ?? []).includes("Net"))) continue;
-    const prev = m.get(f.fn);
-    // A repeated `fn` is malformed input; UNION rather than overwrite — the direction that cannot turn a
-    // violation into a pass (java `gateInputFromReport` merges the same way).
-    m.set(f.fn, prev ? [...new Set([...prev, ...carried])].sort() : carried);
+    // ⟨0.32⟩ keyed by the UNIT, not by the bare name — two members of a workspace may legitimately share
+    // one (SPEC §2.2), and merging their destination classes is the same borrowing the reason-class merge
+    // was measured doing. A repeated KEY is one unit reported twice; UNION rather than overwrite — the
+    // direction that cannot turn a violation into a pass (java `gateInputFromReport` merges the same way).
+    const k = unitKey(units, f);
+    const prev = m.get(k);
+    m.set(k, prev ? [...new Set([...prev, ...carried])].sort() : carried);
   }
   return m;
 }
@@ -730,11 +929,16 @@ export function wholePolicyUnanswerable(pol, verb = "this route") {
   };
 }
 
-export function unanswerableScoped(pol, functions, reasonAcc, netMap) {
+// ⟨0.32⟩ THE WITHHOLD IS KEYED BY UNIT; THE DISCLOSURE NAMES THE FUNCTION. Keying the held set by name
+// would withhold the rule on EVERY same-named unit — and a withheld triple is a violation NOT reported,
+// so that is the fail-OPEN direction: one member's missing evidence deleting another member's certain
+// violation. `evaluatePolicy` and `narrowingContext` pass the unit key in turn. `why` still lists NAMES,
+// because a key is not something an operator can look up in their own source.
+export function unanswerableScoped(pol, functions, reasonAcc, netMap, units = null) {
   const held = new Set(), byRule = new Map();
-  const key = (raw, fn, eff) => `${raw}\u0000${fn}\u0000${eff}`;
-  const note = (r, fn, eff, why) => {
-    held.add(key(r.raw, fn, eff));
+  const key = (raw, uk, eff) => `${raw}\u0000${uk}\u0000${eff}`;
+  const note = (r, uk, fn, eff, why) => {
+    held.add(key(r.raw, uk, eff));
     let e = byRule.get(r.raw);
     if (!e) { e = { rule: r.raw, fns: [], why }; byRule.set(r.raw, e); }
     e.fns.push(fn);
@@ -742,15 +946,16 @@ export function unanswerableScoped(pol, functions, reasonAcc, netMap) {
   for (const r of pol.deny) {
     for (const f of functions) {
       if (r.scope && !scopeMatches(f.fn, r.scope)) continue;
-      const inf = f.inferred ?? [];
-      if (r.netClasses?.length && inf.includes("Net") && !(netMap.get(f.fn)?.length))
-        note(r, f.fn, "Net", "narrows on the Net DESTINATION CLASS, but %F carr%S Net with no "
+      const uk = unitKey(units, f);
+      const inf = effectiveInferred(f, reasonAcc, units);
+      if (r.netClasses?.length && inf.includes("Net") && !(netMap.get(uk)?.length))
+        note(r, uk, f.fn, "Net", "narrows on the Net DESTINATION CLASS, but %F carr%S Net with no "
           + "`netClass` in this report — the field the filter reads is absent, so the narrowing would "
           + "succeed for lack of evidence and drop a Net the bare `deny Net` catches. NOT EVALUATED for "
           + "those functions rather than passed: an absent optional field must not relax a fail-closed "
           + "gate. Use the bare `deny Net`, or gate at scan time (candor-ts <src> --policy <file>).");
-      if (r.unknownClasses?.length && inf.includes("Unknown") && !(reasonAcc.get(f.fn)?.size))
-        note(r, f.fn, "Unknown", "narrows on the Unknown REASON CLASS, but %F carr%S Unknown with no "
+      if (r.unknownClasses?.length && inf.includes("Unknown") && !(reasonAcc.get(uk)?.size))
+        note(r, uk, f.fn, "Unknown", "narrows on the Unknown REASON CLASS, but %F carr%S Unknown with no "
           + "reason reachable in this report — neither %P own `unknownWhy` nor a `calls` edge to one. "
           + "§6.2 resolves the class set TRANSITIVELY over the gate's reach; with the channel missing, "
           + "every narrowed filter silently tolerates while only the bare `deny Unknown` fires. NOT "
@@ -766,7 +971,7 @@ export function unanswerableScoped(pol, functions, reasonAcc, netMap) {
     return { rule, why: `\`${rule}\` ` + why.replace("%F", list).replace("%S", names.length === 1 ? "ies" : "y")
                                             .replace("%P", names.length === 1 ? "its" : "their") };
   });
-  return { unevaluated, withhold: held.size ? (r, fn, eff) => held.has(key(r.raw, fn, eff)) : null };
+  return { unevaluated, withhold: held.size ? (r, uk, eff) => held.has(key(r.raw, uk, eff)) : null };
 }
 
 /**
@@ -805,12 +1010,17 @@ export function unanswerableScoped(pol, functions, reasonAcc, netMap) {
 /** ⟨0.24⟩ ONE definition of a function's Net destination classes for a run: the report's own field when it
  *  carries one (reportNetClasses), else the derivation from the surfaces the caller supplied. Exported so
  *  the ADVISORY verbs resolve the class the same way the gate does — see `classFilterExcludes`. */
-export function netClassResolver(incomplete = new Map(), partners = new Set(), netClasses = null) {
+export function netClassResolver(incomplete = new Map(), partners = new Set(), netClasses = null, units = null) {
   // `has`, not `get(…) ?? derive`: an entry mapped to the EMPTY set is a report that carried no class, and
   // on the authoritative route that absence is the answer — deriving one there would re-classify.
-  return (f) => (netClasses && netClasses.has(f.fn))
-    ? netClasses.get(f.fn)
-    : netClassesOf(f.hosts ?? [], incomplete.get(f.fn)?.has("Net") ?? false, partners);
+  // ⟨0.32⟩ `netClasses` is keyed by UNIT (reportNetClasses); `incomplete` stays keyed by NAME, because it
+  // is the SCAN route's own live structure and that route's keys are names by construction.
+  return (f) => {
+    const k = unitKey(units, f);
+    return (netClasses && netClasses.has(k))
+      ? netClasses.get(k)
+      : netClassesOf(f.hosts ?? [], incomplete.get(f.fn)?.has("Net") ?? false, partners);
+  };
 }
 
 /**
@@ -842,35 +1052,88 @@ export function netClassResolver(incomplete = new Map(), partners = new Set(), n
  * An entry ABSENT from the report excludes NOTHING: a missing entry is missing evidence, and the direction
  * that cannot turn a boundary crossing into a silent pass is "the rule still applies".
  */
-export function classFilterExcludes(r, entry, eff, reasonAcc, netClassOf) {
+export function classFilterExcludes(r, entry, eff, reasonAcc, netClassOf, units = null) {
   if (!entry) return false;
+  // ⟨0.32⟩ the lookup key comes from the ENTRY, never from its name: a name-keyed lookup into a
+  // unit-keyed map does not error, it returns `undefined`, and `undefined` reads here as "no classes" —
+  // which `reasonClassesMatch` floors at `unresolved`. Silent, and in whichever direction the filter falls.
   if (eff === "Unknown" && r.unknownClasses?.length)
-    return !reasonClassesMatch(reasonAcc.get(entry.fn), r.unknownClasses);
+    return !reasonClassesMatch(reasonAcc.get(unitKey(units, entry)), r.unknownClasses);
   if (eff === "Net" && r.netClasses?.length)
     return !netClassOf(entry).some((c) => r.netClasses.includes(c));
   return false;
 }
 
-export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map(), partners = new Set(), netClasses = null, withhold = null) {
+export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map(), partners = new Set(), netClasses = null, withhold = null, units = null, hashByName = null) {
   const out = [];
   // `Llm` ⟨0.13⟩ reaches the SAME hosts surface as Net (an Llm host WAS captured as a Net host literal).
   const surfaces = { Net: "hosts", Llm: "hosts", Exec: "cmds", Fs: "paths", Db: "tables" };
   // §6.2 ⟨0.19⟩: `reasonClass` (all classes on the fn) rides an AS-EFF-006 Unknown violation; ⟨0.20⟩ `netClass`
   // (all destination classes on the fn) rides a Net violation. Both omitted when empty (byte-identical verdict).
-  const push = (rule, fn, effects, detail, reasonClass, netClass) => {
-    const rec = { rule, fn, effects, detail };
+  //
+  // ⟨0.32⟩ **AND `hash` — THE UNIT THIS ROW IS ABOUT (SPEC §2).** *"A verdict row MUST carry enough
+  // identity for a consumer to tell two units apart… the sort key MUST include that identity."* MEASURED
+  // on this engine 2026-08-24, `gate --report` over two reports whose members both define `go` and both
+  // violate `deny Exec`: two BYTE-IDENTICAL rows, `{rule, fn, effects, detail}`, with nothing
+  // attributing either to a package. A reader cannot tell two broken members from one listed twice, and
+  // a consumer that fingerprints on name alone — candor's own SARIF action did — hides one finding
+  // behind the other.
+  //
+  // `hash` AND NOT `package`/`loc`, because §2.2 already binds a consumer to join a verdict row back to
+  // its report entry BY HASH; a row that omits it forces exactly the name join that clause forbids.
+  // BESIDE `fn`, NEVER INSTEAD OF IT: the NAME is what a policy scope matches and what a human reads,
+  // and swapping in the qualified form would silently stop every scoped rule matching — a false green
+  // introduced by fixing a false green. Omitted when the producer has none to give (a hand-authored
+  // report with no `hash`, which §3.1 says this route serves): absent is ⟨0.26⟩'s *cannot answer*,
+  // never a fabricated id. Positioned directly after `fn`, so the row reads `{rule, fn, hash, …}` in
+  // every engine.
+  //
+  // **AND IN THIS ENGINE THE IDENTITY IS THE PAIR, NOT `hash` ALONE — which is not a weaker port, it is
+  // the same key `reportUnits` already uses.** A rust `hash` is a DefPathHash, unique per unit; THIS
+  // engine emits `<package>#<local tail>`, and that is measurably not unique — on hono's own sources 13
+  // hashes are shared by two or more distinct `fn`s, five `handle` functions all keying `src#handle`
+  // (see `reportUnits`, which keys by `hash` REFINED BY `fn` for exactly that reason). So a row here
+  // carries the module-qualified `fn` AND the package-qualified `hash`, and the pair is what tells two
+  // units apart. Emitting `hash` alone would be the identity §2.2 forbids joining on.
+  const push = (rule, fn, effects, detail, reasonClass, netClass, hash) => {
+    const rec = { rule, fn };
+    if (hash) rec.hash = hash;
+    rec.effects = effects;
+    rec.detail = detail;
     if (reasonClass && reasonClass.length) rec.reasonClass = reasonClass;
     if (netClass && netClass.length) rec.netClass = netClass;
     out.push(rec);
   };
+  // ⟨0.32⟩ NAME -> unit identity, for the two rule codes that iterate the CALL GRAPH rather than the
+  // entry list (AS-EFF-009/011) and so hold a name where the others hold the entry itself. Scan-route
+  // only in practice — `gate --report` passes an EMPTY callgraph, because a report's `calls` is
+  // effect-relevant while those rules match on NAME, so they are refused as unevaluable there — and a
+  // scan gates ONE analysis world, in which a name identifies a unit.
+  //
+  // THE CALLER'S MAP WINS, and that is not a convenience — `forbid`'s violator is TYPICALLY PURE (a
+  // `model.outer` that merely CALLS across a layer performs nothing), and a pure function has NO REPORT
+  // ENTRY, so the fallback below cannot see it. MEASURED 2026-08-24: the AS-EFF-009 row for exactly that
+  // shape came out with no `hash` here while candor-java and candor-swift both emitted one, because they
+  // build the identity from the scan's own name table rather than from the entry list. scan.mjs passes
+  // `unitHash` over `fns`, which holds every function including the pure ones. The fallback stays for the
+  // callers that have no such table (the MCP/LSP routes and the unit tests): FIRST writer wins rather
+  // than last, so its value is a function of the entry list and not of iteration order.
+  const hashOf = hashByName ?? new Map();
+  if (!hashByName)
+    for (const f of functions)
+      if (typeof f?.hash === "string" && f.hash && !hashOf.has(f.fn)) hashOf.set(f.fn, f.hash);
   // Reason-scoped Unknown: the Unknown reason CLASS travels the call graph the same way the Unknown
   // EFFECT does. ONE copy of that resolution, shared with the disclosure side — see resolveReasonClasses.
-  const reasonAcc = resolveReasonClasses(functions, callgraph);
+  const reasonAcc = resolveReasonClasses(functions, callgraph, units);
   // ⟨0.24⟩ ONE definition of a function's Net destination classes for this run (netClassResolver above):
   // the report's own field when it carries one, else the derivation from the surfaces the caller supplied.
   // The gate's TEST and the class list it REPORTS both read it, so the two can't disagree about one function.
-  const netClassOf = netClassResolver(incomplete, partners, netClasses);
+  const netClassOf = netClassResolver(incomplete, partners, netClasses, units);
   for (const f of functions) {
+    // ⟨0.32⟩ the KEY identifies the unit; `f.fn` is the NAME, and the name is what a policy SCOPE matches
+    // and what the verdict row prints (§3.3.1 byte-equality with `scan --policy` rests on it).
+    const uk = unitKey(units, f);
+    const inferredOf = effectiveInferred(f, reasonAcc, units);
     for (const r of pol.deny) {
       if (r.scope && !scopeMatches(f.fn, r.scope)) continue;
       // `pure` (empty forbidden set) forbids every EFFECT — not `Unknown`, which is the §4 trust
@@ -878,8 +1141,8 @@ export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()
       // The reference engine (candor-java) and the rust deep engine exclude it identically; candor-ts
       // wrongly counted an Unknown-only fn as a `pure` violation until 2026-07-09.
       const hits = r.effects.length === 0
-        ? f.inferred.filter((e) => e !== "Unknown")
-        : f.inferred.filter((e) => r.effects.includes(e));
+        ? inferredOf.filter((e) => e !== "Unknown")
+        : inferredOf.filter((e) => r.effects.includes(e));
       // Reason-scoped Unknown: a `deny E Unknown[classes]` keeps its Unknown hit only for a fn whose
       // TRANSITIVE reason classes include one of those; Net destination-class: a `deny Net[dest…]` keeps its
       // Net hit only for a fn reaching one of those destinations, else tolerates (only asserted-safe ones).
@@ -887,16 +1150,16 @@ export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()
       // travels the call graph via f.hosts + f.incomplete, propagated transitively before the gate (scan.mjs).
       // ⟨0.24⟩ BOTH now live in `classFilterExcludes`, so `fix-gate` and `unverified` apply the same filter
       // instead of computing from the effect set alone (see that function's measurement).
-      let kept = hits.filter((e) => !classFilterExcludes(r, f, e, reasonAcc, netClassOf));
+      let kept = hits.filter((e) => !classFilterExcludes(r, f, e, reasonAcc, netClassOf, units));
       // ⟨0.24⟩ …and LAST, because it overrides the matchers rather than joining them: an effect whose match
       // this report cannot evidence is neither a violation nor a pass. The caller lists it as `unevaluated`.
-      if (withhold && kept.length) kept = kept.filter((e) => !withhold(r, f.fn, e));
+      if (withhold && kept.length) kept = kept.filter((e) => !withhold(r, uk, e));
       if (kept.length) {
         // When Unknown is denied, report ALL reason classes on the fn (transitive) — every reason the gate bit.
-        const rc = kept.includes("Unknown") ? [...(reasonAcc.get(f.fn) ?? [])].sort() : undefined;
+        const rc = kept.includes("Unknown") ? [...(reasonAcc.get(uk) ?? [])].sort() : undefined;
         // ⟨0.20⟩ when Net is denied, report ALL of the fn's destination classes (transitive).
         const ncv = kept.includes("Net") ? netClassOf(f) : undefined;
-        push("AS-EFF-006", f.fn, kept, `\`${f.fn}\` performs { ${kept.join(", ")} }, forbidden by policy: \`${r.raw}\``, rc, ncv);
+        push("AS-EFF-006", f.fn, kept, `\`${f.fn}\` performs { ${kept.join(", ")} }, forbidden by policy: \`${r.raw}\``, rc, ncv, f.hash);
       }
     }
     for (const r of pol.allow) {
@@ -912,10 +1175,10 @@ export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()
       const surfaceIncomplete = incomplete.get(f.fn)?.has(r.effect)
         || (r.effect === "Llm" && incomplete.get(f.fn)?.has("Net"));
       if (reached.length === 0 || surfaceIncomplete) {
-        push("AS-EFF-008", f.fn, [r.effect], `\`${f.fn}\` performs ${r.effect} with no visible literal — the surface cannot be certified: \`${r.raw}\``);
+        push("AS-EFF-008", f.fn, [r.effect], `\`${f.fn}\` performs ${r.effect} with no visible literal — the surface cannot be certified: \`${r.raw}\``, undefined, undefined, f.hash);
       } else {
         const bad = reached.filter((v) => !literalAllowed(r.effect, v, r.values));
-        if (bad.length) push("AS-EFF-008", f.fn, [r.effect], `\`${f.fn}\` reaches { ${bad.join(", ")} } outside the allowlist: \`${r.raw}\``);
+        if (bad.length) push("AS-EFF-008", f.fn, [r.effect], `\`${f.fn}\` reaches { ${bad.join(", ")} } outside the allowlist: \`${r.raw}\``, undefined, undefined, f.hash);
       }
     }
   }
@@ -933,7 +1196,7 @@ export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()
           queue.push(c);
         }
       }
-      if (hit) push("AS-EFF-009", fn, [], `\`${fn}\` reaches into a forbidden layer (via \`${hit}\`), violating policy: \`${r.raw}\``);
+      if (hit) push("AS-EFF-009", fn, [], `\`${fn}\` reaches into a forbidden layer (via \`${hit}\`), violating policy: \`${r.raw}\``, undefined, undefined, hashOf.get(fn));
     }
   }
   // ⟨0.29⟩ AS-EFF-011 — `only A -> B …`: a fn in A may reach A and the listed scopes, NOTHING else. The
@@ -963,7 +1226,7 @@ export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()
       // ⟨0.29⟩ ITS OWN CODE, not `forbid`'s — a rule code is what a CI suppression keys on, and these two
       // are opposite constructs. Sharing 009 would make an existing `forbid` suppression silently mute
       // `only` violations its author never accepted.
-      if (hit) push("AS-EFF-011", fn, [], `\`${fn}\` reaches \`${hit}\`, which this permission rule does not permit: \`${r.raw}\``);
+      if (hit) push("AS-EFF-011", fn, [], `\`${fn}\` reaches \`${hit}\`, which this permission rule does not permit: \`${r.raw}\``, undefined, undefined, hashOf.get(fn));
     }
   }
   // ⟨0.27⟩ SPEC §4 — A RULE WHOSE SCOPE BOUND NO FUNCTION IS UNANSWERABLE, AND IS DISCLOSED RATHER THAN