candor-ts 0.23.0 → 0.24.0

package/policy.mjs

@@ -13,20 +13,138 @@ export const EFFECTS = ["Net", "Fs", "Db", "Exec", "Env", "Clock", "Ipc", "Log",
 // candor-rust's — the mapping below mirrors java's prefix-based ReasonClass.classify(String).
 export const REASON_CLASSES = ["reflect", "dispatch", "indirect", "native", "unresolved", "setup"];
 // `dynamic` = every GENUINE blind-spot class (excludes `setup`), incl. `unresolved` so it never under-gates.
-const DYNAMIC_CLASSES = ["reflect", "dispatch", "indirect", "native", "unresolved"];
+// Exported so the `--class` flag (query-core) resolves the alias from THIS list rather than a second copy:
+// 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"];
 /** 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();
-  if (w.startsWith("reflect") || w === "dynamicmemberlookup") return "reflect";
+  // `startsWith`, NOT `===`. candor-swift emits this token in the normative `kind:detail` form —
+  // `dynamicMemberLookup:<root>.<prop>` (CallCollector.swift) — and never bare, so an equality test can
+  // never match a real one and the token falls through to the `unresolved` catch-all below. Both classes
+  // are in DYNAMIC_CLASSES, so a bare `deny Unknown` is unaffected; what silently weakens is the
+  // class-targeted `deny Unknown[reflect]`, which is the form the reason ratchet is adopted in. Found by
+  // the swift sweep (the same equality test made `Unknown[reflect]` unsatisfiable there even in one tree)
+  // and fixed in candor-java as `d9b07b0`. Widening to a prefix is monotone: only ever MORE tokens reach
+  // `reflect`, never fewer.
+  if (w.startsWith("reflect") || w.startsWith("dynamicmemberlookup")) return "reflect";
   if (w.startsWith("native")) return "native";
   if (w.startsWith("callback") || w.startsWith("closure") || w.startsWith("task-handoff")) return "indirect";
   if (w.startsWith("dispatch") || w.startsWith("indy") || w.startsWith("ambiguous")) return "dispatch";
   if (w.startsWith("missing-config") || w.startsWith("no-tsconfig") || w.startsWith("no-node_modules")) return "setup";
   return "unresolved"; // conservative catch-all
 }
+
+// ⟨0.24⟩ THE reason-class resolution — ONE copy, for the GATE (evaluatePolicy, over the scan's in-memory
+// graph) and for the DISCLOSURE (`unverified --class`, over a loaded report). SPEC §6.2: "THE GATE AND THE
+// DISCLOSURE MUST APPLY THE SAME RULE, AND SHOULD SHARE THE SAME CODE." They did not: the gate resolved
+// transitively and the query open-coded a second, direct-only match — two implementations of one rule
+// inside one engine, drifting because nothing compared them, and the consumer-side one under-reported the
+// very holes the verb exists to name. Measured before the repair, `--class dynamic` (an alias for every
+// genuine class, so it must exclude NOTHING) against unfiltered `unverified`: 207→173 on this engine's own
+// sources, 268→158 on execa, 64→21 on got. So: no second fixpoint, no second match rule.
+//
+// `unknownWhy` is DIRECT-ONLY by design (§4: a reason names a site in the function's OWN body), so a
+// 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 = {}) {
+  const acc = new Map();
+  // ⟨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
+  // THAT field. candor-ts read `<prefix>.callgraph.json` and nothing else, so a report whose sidecar was
+  // deleted / never written / left behind in another workspace silently degraded to a DIRECT-ONLY
+  // resolution — every inherited hole's class set came back empty, and the empty set then matched every
+  // filter (see reasonClassesMatch). Two independent faults compounding into one wrong answer: `--class
+  // unresolved` selected `b_reasoned_only`, whose Unknown its callee classified `dispatch`, which is the
+  // literal outcome §6.2 requirement 3 forbids. Seeding from `calls` also makes the answer BYTE-IDENTICAL
+  // with and without the sidecar, which is the property the other three engines have and this one lacked.
+  // UNION rather than either-or: the sidecar can carry edges an older report's entries don't, and more
+  // edges only ever ADD classes — the fail-closed direction for the gate that shares this resolution.
+  const edges = new Map();
+  const addEdge = (caller, callee) => {
+    let s = edges.get(caller);
+    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);
+  for (const [caller, callees] of Object.entries(callgraph ?? {})) {
+    for (const c of Array.isArray(callees) ? callees : []) addEdge(caller, c);
+  }
+  for (const f of functions ?? []) {
+    const cs = new Set((f.unknownWhy ?? []).map(reasonClass));
+    // ⟨0.24⟩ CONTRIBUTES, not "is treated as". A DIRECT Unknown the function did not name ADDS
+    // `unresolved` HERE, at the node that owns the hole — never as a fallback on the JOINED set being
+    // empty. Emptiness is not upward-closed, so the old absence-keyed default was REMOVED by acquiring a
+    // second, classifiable reason: a caller of one reasonless dep was rejected by `Unknown[unresolved]`,
+    // a caller of one reasoned dep was not, and a caller of BOTH — strictly worse-known than the first —
+    // passed. Adding a call turned a red verdict green (the monotone-denial corollary).
+    // Gated on a DIRECT Unknown (§6.2 req 3), never on the reason set merely being absent: absence is
+    // also exactly what an INHERITED Unknown looks like, and tagging one of those `unresolved` when its
+    // callee classified it perfectly well is the mirror fabrication.
+    // candor-ts's own reports cannot reach this branch — its emitter already writes `["unresolved"]` on a
+    // 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);
+  }
+  // …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).
+  for (let changed = true; changed; ) {
+    changed = false;
+    for (const [caller, callees] of edges) {
+      for (const callee of callees) {
+        const cc = acc.get(callee);
+        if (!cc) continue;
+        let set = acc.get(caller);
+        if (!set) { set = new Set(); acc.set(caller, set); }
+        for (const c of cc) if (!set.has(c)) { set.add(c); changed = true; }
+      }
+    }
+  }
+  return acc;
+}
+
+/** ⟨0.24⟩ The class MATCH, shared by the gate and `unverified --class`. `classes` = a fn's resolved class
+ *  set (resolveReasonClasses); `filter` = the rule's / the flag's class tokens (an array or a Set). A null
+ *  filter means no narrowing.
+ *
+ *  THE UNCLASSIFIABLE CASE PROJECTS TO `{unresolved}` — it is not "kept by every filter". §6.2: a hole
+ *  nothing classified CONTRIBUTES `unresolved`, and `unresolved` is one class among six, so the hole is
+ *  kept by `unresolved` and by `dynamic` (which names every genuine class) and dropped by `native`,
+ *  `reflect`, `dispatch`, `indirect` and `setup` — the spec's own discrimination control says post-repair
+ *  `--class native` selects 0. Byte-aligns with rust `reason_class_matches` (its None/empty arms both read
+ *  `want.contains(Unresolved)`) and java `reasonClassesOf` (`Set.of(UNRESOLVED)`).
+ *
+ *  A blanket `return true` here was the mirror of the fail-open it replaced, and worse on two counts.
+ *  (1) `setup`: `dynamic` deliberately EXCLUDES `setup` as non-genuine, so an entry matching `--class
+ *  setup` because nothing classified it is doubly wrong. (2) It re-opened requirement 3 through the MATCH
+ *  arm rather than the contribution: an inherited `Unknown` its callee classified `dispatch` was selected
+ *  by `--class unresolved` whenever the reach could not be walked, which is the literal outcome §6.2
+ *  forbids — and the requirement-3 gating in resolveReasonClasses, which is correct, cannot prevent it
+ *  because the empty set never reaches that code. Measured cross-engine on identical bytes before the
+ *  repair: `--class native` on an orphan-callee report gave rust/java/swift `[]` and ts `['app.orphan']`.
+ *
+ *  This is still the fail-CLOSED direction for the case that made a blanket keep tempting: a hole no
+ *  filter would name is kept by the two filters an adopter narrows THROUGH (`unresolved`, `dynamic`),
+ *  never dropped by all six. What it refuses is asserting a class the engine does not have evidence for. */
+export function reasonClassesMatch(classes, filter) {
+  if (!filter) return true;
+  const has = filter instanceof Set ? (c) => filter.has(c) : (c) => filter.includes(c);
+  if (!classes || classes.size === 0) return has("unresolved");
+  for (const c of classes) if (has(c)) return true;
+  return false;
+}
 // The literal surfaces `allow` can restrict. `Llm` ⟨0.13⟩ rides Net's host literal (SPEC §1) —
 // `allow Llm <host…>` restricts which MODEL hosts a scope may reach, matched by hostname like Net.
 const ALLOW_EFFECTS = new Set(["Net", "Exec", "Fs", "Db", "Llm"]);
+// The two effect-position vocabularies, as sorted arrays. `deny`'s is every effect plus the §4 trust
+// marker; `allow`'s is the CLOSED set of effects that carry a literal surface a value list can restrict.
+const EFFECT_VOCAB = [...EFFECTS, "Unknown"].sort();
+const ALLOW_VOCAB = [...ALLOW_EFFECTS].sort();
+const ALLOW_FORM = ["allow <Effect> [in <scope>] <value…>"];
 
 // The §6.2 token separator: ASCII whitespace ONLY (space/tab/LF/VT/FF/CR). JS `\s`/`String.trim` strip
 // Unicode spaces (NBSP, ideographic, …) that Java drops — a gateless-green cross-engine divergence
@@ -36,8 +154,79 @@ const ASCII_WS_TRIM = /^[ \t\n\v\f\r]+|[ \t\n\v\f\r]+$/g;
 // ⟨0.19⟩ `aliases` (a Map name→class-token[], from `.candor/config` `unknown-alias`) lets an `Unknown[<name>]`
 // filter resolve a user-defined name (SPEC §6.2). A config alias never changes what bare `deny E Unknown`
 // means (always `Unknown[*]`), so a rule's denied set stays legible from the policy alone.
+//
+// ⟨0.24⟩ RETURNS `errors` AND `aliasesUsed` BESIDE THE RULES (SPEC §6.2 `382a7e0`/`be0b9a9`, §3.1 `99eb4e9`).
+// The rule objects are UNCHANGED — a token this parser cannot honour is still recorded in the rule exactly
+// as before, so `parsepolicy` can still show what was written — but an UNRECOGNISED VALUE TOKEN now lands
+// in `errors`, and every verdict-bearing call site refuses (exit 2) instead of running a policy it silently
+// rewrote. Measured on this engine before the change, over a report whose only `Unknown` is reflect-caused:
+//
+//   deny Unknown[dispatch,nativ] app         -> exit 0, rule kept as `Unknown[dispatch]`      NARROWS
+//   deny Net[known-partner,unkown-host] app  -> exit 0, rule kept as `Net[known-partner]`     NARROWS
+//   deny Unknown[corp] app                   -> exit 1, rule kept as bare `deny Unknown`      WIDENS
+//
+// The NARROWING half is the fail-open and it is the common case — a typo lands beside correct tokens far
+// more often than alone — and the rule stops gating what the operator spelled while the gate still looks
+// armed. The WIDENING half is loud but announces "ignoring policy rule" and then KEEPS a DIFFERENT rule,
+// which is a false disclosure. Neither is a policy the operator wrote.
+//
+// ⟨0.24⟩ AND `errors` COVERS EVERY LINE THIS PARSER DID NOT HONOUR, NOT ONLY UNRECOGNISED TOKENS (SPEC §3.1
+// `195d45a`). Measured against the reference engine on the conformance battery: java reported 12, candor-ts
+// 5 — the seven missing were LINES DROPPED WHOLE (an unknown effect name, an `allow` on an effect that
+// takes no operand, two malformed `forbid`s, two `allow`s naming no values, an unknown rule kind), each
+// warned on stderr and invisible to the machine output. **A dropped rule is the LIMIT CASE of "silently
+// rewritten into a different policy": the rewritten policy is the one without that line**, which is a
+// BIGGER rewrite than a narrowed filter, not a smaller one. The witness was disclosing the two cases that
+// prompted the clause and silent on the ones that did not.
+export const POLICY_ERROR_KINDS = ["reason-class/alias", "Net destination-class", "effect-name", "rule-kind"];
+// ⟨0.24⟩ FATAL vs DISCLOSED-ONLY. `errors` is ONE list because §3.1 pins one list, but it carries two
+// populations and only the verdict-bearing call sites need the distinction, so it is derived from `kind`
+// rather than stored.
+//
+// ⟨0.24⟩ `effect-name` IS FATAL (SPEC §6.2 `1e1748a`) — a typo'd EFFECT NAME deleted the rule, silently,
+// four-way green. Measured on all four engines:
+//
+//     deny Nett app             ->  rust 0  ts 0  java 0  swift 0    the rule is DELETED, the gate is green
+//     allow Nett host.example   ->  rust 0  ts 0  java 0  swift 0    the certification silently vanishes
+//
+// The operator reads an armed `deny Net`; there is no gate at all. This engine already called a dropped
+// rule the LIMIT CASE of silently rewriting the policy — a BIGGER rewrite than a narrowed filter — and the
+// bigger one was warning-only while the smaller one was exit 2. The grammar defence for leaving it open is
+// real but narrower than it was taken to be, and the two conditions that escape it are exactly the ones
+// that raise this kind:
+//   · `allow`'s effect position is a FIXED, CLOSED set with no scope reading available, so a token outside
+//     it is unambiguously a typo (and `allow Clock …` is the same shape: an effect carrying no literal
+//     surface a value list could restrict);
+//   · a `deny` whose effect list ends up EMPTY after scope-splitting is malformed under either reading —
+//     there is no legitimate policy it could be — so refusing loses nothing.
+// What stays open, deliberately, is the genuinely ambiguous middle: a `deny` with at least one valid effect
+// and an unrecognised trailing token that MIGHT be a scope (`deny Net Exex app`). `parsepolicy` reports it
+// either way, so the operator can always see it.
+//
+// `rule-kind` stays DISCLOSED-ONLY: `195d45a` is explicit that reporting a dropped line is "additive to the
+// witness and silent about the gate", and a malformed `forbid` or an unknown rule kind has no closed
+// vocabulary to be measured against — that would be a grammar change, not a token change.
+const FATAL_ERROR_KINDS = new Set(["reason-class/alias", "Net destination-class", "effect-name"]);
+export const fatalPolicyErrors = (errors) => (errors ?? []).filter((e) => FATAL_ERROR_KINDS.has(e.kind));
+// The accepted sets, as ARRAYS (SPEC §3.1 `901f14d`: `accepted` is an array of tokens, not prose — a prose
+// string is unparseable by the consumer the field exists for).
+const REASON_VOCAB = [...REASON_CLASSES, "dynamic", "*"];
+const RULE_KIND_VOCAB = ["deny", "pure", "forbid", "allow"];
+const DROPPED = (why) => `policy line NOT HONOURED — DROPPED (${why}); it is absent from the parse, so the `
+                       + `policy that ran is the one without it`;
+
 export function parsePolicy(text, aliases = null) {
   const deny = [], allow = [], forbid = [];
+  // ⟨0.24⟩ every line this parser could not honour AS WRITTEN, and every alias a rule RESOLVED THROUGH.
+  // `aliasesUsed` is recorded at the point of USE, never from the alias map: a config defining ten aliases
+  // the policy never mentions moved nothing, and naming it would train the reader to skip the field.
+  //
+  // THE ENTRY SHAPE IS PINNED (SPEC §3.1 `195d45a` + `901f14d`): `{kind, token, accepted, rule, message}`,
+  // `kind` drawn from the closed POLICY_ERROR_KINDS, `accepted` an ARRAY, `rule` the source line verbatim.
+  // This engine emitted `vocabulary` for `kind`, `where` for `rule`, prose for `accepted`, and no `message`
+  // at all — three renamed/reshaped fields on the one output whose whole job is to be diffed.
+  const errors = [], aliasesUsed = new Map();
+  const err = (kind, token, accepted, rule, message) => errors.push({ kind, token, accepted, rule, message });
   // Split LINES on \n / \r\n / bare \r — the three forms Java's Files.readAllLines (the reference parser)
   // breaks on. Splitting on \n ONLY let a classic-Mac (bare-\r) file collapse to one line: \r is also an
   // in-line ASCII-ws token separator (below), so every rule after the first was glued into the first rule's
@@ -67,7 +256,8 @@ export function parsePolicy(text, aliases = null) {
             if (!cn) continue;
             if (cn === "*") netStar = true;
             else if (NET_DEST_CLASSES.includes(cn)) netClasses.add(cn);
-            else warn(`unknown Net destination-class \`${cn}\` (known: ${NET_DEST_CLASSES.join(",")}, or *)`);
+            else err("Net destination-class", cn, [...NET_DEST_CLASSES, "*"], line,
+                     `unknown Net destination-class \`${cn}\` (known: ${NET_DEST_CLASSES.join(", ")}, or *)`);
           }
           continue;
         }
@@ -80,8 +270,10 @@ export function parsePolicy(text, aliases = null) {
             if (cn === "*") unknownStar = true;
             else if (cn === "dynamic") DYNAMIC_CLASSES.forEach((c) => unknownClasses.add(c));
             else if (REASON_CLASSES.includes(cn)) unknownClasses.add(cn);
-            else if (aliases && aliases.has(cn)) aliases.get(cn).forEach((c) => unknownClasses.add(c)); // ⟨0.19⟩ config unknown-alias
-            else warn(`unknown reason-class/alias \`${cn}\` (known: ${REASON_CLASSES.join(",")}; aliases: dynamic,*, or a config \`unknown-alias\`)`);
+            else if (aliases && aliases.has(cn)) { aliasesUsed.set(cn, [...aliases.get(cn)].sort()); aliases.get(cn).forEach((c) => unknownClasses.add(c)); } // ⟨0.19⟩ config unknown-alias
+            else err("reason-class/alias", cn, REASON_VOCAB, line,
+                     `unknown reason-class/alias \`${cn}\` (known: ${REASON_CLASSES.join(", ")}; aliases: `
+                     + "dynamic, *, or a config `unknown-alias`)");
           }
           continue;
         }
@@ -91,7 +283,11 @@ export function parsePolicy(text, aliases = null) {
           if (tok === "Net") netStar = true;         // bare Net ⇒ all destinations
         } else { scope = tok; break; }
       }
-      if (effects.length === 0) { warn("deny names no known effect"); continue; }
+      if (effects.length === 0) {
+        warn("deny names no known effect");
+        err("effect-name", t[1] ?? "", EFFECT_VOCAB, line, DROPPED("names no known effect"));
+        continue;
+      }
       // `*` (or bare Unknown) means all classes ⇒ empty filter (matches any Unknown).
       let uc = unknownStar ? [] : [...unknownClasses].sort();
       // `*` (or bare Net) means all destinations ⇒ empty filter (matches any Net).
@@ -104,25 +300,145 @@ export function parsePolicy(text, aliases = null) {
     } else if (t[0] === "pure") {
       deny.push({ effects: [], scope: t[1] ?? "", unknownClasses: [], netClasses: [], raw: line });
     } else if (t[0] === "allow") {
-      if (t.length < 3) { warn("allow names no values"); continue; }
-      if (!ALLOW_EFFECTS.has(t[1])) { warn("allow supports only Net hosts / Llm hosts / Exec commands / Fs paths / Db tables"); continue; }
+      if (t.length < 3) {
+        warn("allow names no values");
+        // `token` is EMPTY, not the line's remainder: nothing here was UNRECOGNISED — the line is
+        // truncated, so there is no offending token to name and inventing one would misdirect the reader.
+        err("rule-kind", "", ALLOW_FORM, line, DROPPED("allow names no values"));
+        continue;
+      }
+      if (!ALLOW_EFFECTS.has(t[1])) {
+        warn("allow supports only Net hosts / Llm hosts / Exec commands / Fs paths / Db tables");
+        err("effect-name", t[1], ALLOW_VOCAB, line,
+            DROPPED("allow supports only Net hosts / Llm hosts / Exec commands / Fs paths / Db tables"));
+        continue;
+      }
       let scope = "", vi = 2;
       if (t[2] === "in") { scope = t[3] ?? ""; vi = 4; }
       const values = t.slice(vi);
-      if (values.length === 0) { warn("allow names no values"); continue; }
+      if (values.length === 0) {
+        warn("allow names no values");
+        err("rule-kind", "", ALLOW_FORM, line, DROPPED("allow names no values"));
+        continue;
+      }
       allow.push({ effect: t[1], scope, values: [...new Set(values)].sort(), raw: line }); // dedup (set)
     } else if (t[0] === "forbid") {
       // Token-wise like the Rust/JVM parsers: the arrow must be its own whitespace-separated token
       // (`a->b` glued is malformed), and tokens past `b` are ignored. A regex here once accepted and
       // rejected DIFFERENT lines than the other engines — the one thing a shared gate must not do.
       const [a, arrow, b] = [t[1] ?? "", t[2] ?? "", t[3] ?? ""];
-      if (!a || arrow !== "->" || !b) { warn("malformed forbid (want `forbid <scope> -> <scope>`)"); continue; }
+      if (!a || arrow !== "->" || !b) {
+        warn("malformed forbid (want `forbid <scope> -> <scope>`)");
+        err("rule-kind", t.slice(1).join(" "), ["forbid <scope> -> <scope>"], line,
+            DROPPED("want `forbid <scope> -> <scope>`"));
+        continue;
+      }
       forbid.push({ from: a, to: b, raw: line });
     } else {
       warn("unknown rule kind");
+      err("rule-kind", t[0], RULE_KIND_VOCAB, line, DROPPED(`unknown rule kind \`${t[0]}\``));
     }
   }
-  return { deny, allow, forbid };
+  // ⟨0.24⟩ `aliasesUsed` is name -> THE CLASSES IT RESOLVED TO, not a bare name list (SPEC §3.1
+  // `b4e9155`): naming the source without the content leaves a reader knowing they were affected and not
+  // how. Key order is sorted so the disclosure is deterministic across runs and across the two routes.
+  //
+  // ⟨0.24⟩ THIS IS THE OBJECT FORM AND IT IS DELIBERATE — a measured three-to-one divergence, KEPT.
+  // candor-ts emits `policyVocabulary.aliases` as `{"corp": ["reflect"]}` where rust, java and swift emit
+  // the ARRAY `["corp"]`; conformance R9's shape walk was blind one level down and scored all four OK.
+  // The object stands, on `b4e9155`'s own argument rather than on preference:
+  //
+  //   · The clause's SHAPE is `{ "config": "<path>", "aliases": { … } }` — braces, i.e. an object. The
+  //     array is a departure from the written pin, not the pin.
+  //   · Its ARGUMENT is decisive and is about the array, one level down. It rejects swift's
+  //     `configSources: [path]` because that "names the file but drops the alias names, and the file is
+  //     the lesser half — an operator reading a verdict changed by an ambient definition needs to see WHAT
+  //     THE DEFINITION WAS, not merely that one existed. A disclosure that names the source but not the
+  //     content leaves the reader knowing they were affected and not how." `aliases: ["corp"]` fails that
+  //     sentence for exactly the same reason `configSources` does: it names the alias and drops the
+  //     definition. And the definition is the whole of what moved the verdict — `corp = reflect` and
+  //     `corp = reflect,native` gate differently under one unchanged policy line, so a reader who sees
+  //     only the NAME cannot tell which gate ran.
+  //   · The object is a strict superset: `Object.keys(aliases)` recovers the array exactly, so nothing a
+  //     consumer of the array form can do is lost.
+  //
+  // Being outnumbered is not the argument against it, and this family has twice found the outlier to be
+  // the correct one on `gate --report` questions. Recorded for the spec to adjudicate.
+  return { deny, allow, forbid, errors,
+           aliasesUsed: Object.fromEntries([...aliasesUsed.entries()].sort((x, y) => (x[0] < y[0] ? -1 : x[0] > y[0] ? 1 : 0))) };
+}
+
+// ⟨0.24⟩ The ONE rendering of the unreadable-policy posture (SPEC §6.2), so the wording cannot drift
+// between the scan gate, `gate --report`, `whatif`, `fix-gate`, `unverified` and `parsepolicy`. Returns the
+// human line; the caller prints it, writes the ⟨0.24⟩ refusal document and exits 2.
+export function policyErrorText(policyFile, errors) {
+  const head = `candor-ts: policy ${policyFile} cannot be honoured AS WRITTEN`;
+  const body = errors.map((e) =>
+    `  unknown ${e.kind} \`${e.token}\` (known: ${e.accepted.join(", ")})\n    in: ${e.rule}`).join("\n");
+  // ⟨0.24⟩ the tail is written for the population actually present. A VALUE-token typo rewrites a rule;
+  // an EFFECT-name typo DELETES it — different harms, and the alias remedy applies only to the first.
+  const dropped = errors.filter((e) => e.kind === "effect-name");
+  const tail = dropped.length === errors.length
+    ? "  Refusing (exit 2), policy NOT evaluated: the rule names no effect this engine knows, so honouring "
+      + "the policy as written would mean DROPPING the line — and the policy that then runs is the one "
+      + "without it, which is a bigger rewrite than a narrowed filter, not a smaller one.\n"
+      + "  Fix the spelling. (`allow` takes only Net/Llm hosts, Exec commands, Fs paths or Db tables.)"
+    : "  Refusing (exit 2), policy NOT evaluated: dropping the token would rewrite the policy into a "
+      + "DIFFERENT one. If it is the list's only token the rule WIDENS to the bare effect; if it sits beside "
+      + "valid tokens the rule NARROWS and stops gating what you spelled, while the gate still looks armed.\n"
+      + "  Fix the spelling, or define it in `.candor/config` as `unknown-alias <name> = <class,…>`.";
+  return `${head} — ${errors.length} line(s) it cannot honour:\n${body}\n` + tail;
+}
+
+// ⟨0.24⟩ THE `unevaluated` DISCLOSURE FOR A POLICY THIS ENGINE CANNOT HONOUR AS WRITTEN — one entry per
+// RAW POLICY LINE (SPEC §3.1: "the RAW policy line, verbatim"), grouped because one line can carry two bad
+// tokens. ONE builder, because BOTH gate routes emit it and §3.1 makes byte-equality between their
+// documents the acceptance test: the scan route gained it first (a certain baseline regression must ride
+// exit 1 with the refusal disclosed beside it) and `gate --report` has to say the same thing in the same
+// bytes or the equality MUST breaks on the very change that repaired the precedence.
+//
+// The wording is written FOR THE DOCUMENT rather than reusing `policyErrorText`, which ends "Refusing
+// (exit 2)" — true of a refusal document and FALSE beside a dominating violation, and a machine-consumer
+// channel is exactly where a stale sentence about the exit code does damage.
+export function policyErrorUnevaluated(errors) {
+  const byLine = new Map();
+  for (const e of errors) {
+    if (!byLine.has(e.rule)) byLine.set(e.rule, []);
+    byLine.get(e.rule).push(`\`${e.token}\` is not a recognised ${e.kind} (known: ${e.accepted.join(", ")})`);
+  }
+  return [...byLine.entries()].map(([rule, ts]) => ({ rule,
+    why: `NOT EVALUATED — this line cannot be honoured as written: ${ts.join("; ")}. Dropping the token `
+       + `would gate a DIFFERENT policy than the one spelled (alone the rule widens to the bare effect; `
+       + `beside valid tokens it narrows while the gate still looks armed).` }));
+}
+
+// ⟨0.24⟩ …and the same for a policy that could not be READ at all. ONE sentence and one `unevaluated`
+// entry for both gate routes: they had two different `reason` strings, so §3.1's byte-equality MUST was
+// already broken for this cause and no test could see it (the equality row only exercises the UNHONOURABLE
+// policy). `rule` names the WHOLE FILE, parenthesised so it cannot be mistaken for a policy line — an
+// unreadable policy has no lines to name, and a consumer of a verdict where a certain violation DOMINATED
+// this refusal must still be able to see from the DOCUMENT that the policy half of the gate never ran.
+export function policyUnreadable(policyFile) {
+  const shown = policyFile === "" ? "(configured empty)" : policyFile;
+  const why = `policy ${shown} could not be read — the gate was NOT enforced from it`;
+  return { why, unevaluated: [{ rule: `(entire policy ${shown} — unreadable, no rules parsed)`, why }] };
+}
+
+// ⟨0.24⟩ THE REFUSAL DOCUMENT (SPEC §3.1 `107755b`, carve-outs removed by `1503368`). A refusal used to
+// write NO `--gate-json` document at all, so a CI wrapper reading that path unconditionally re-read THE
+// PREVIOUS RUN'S document as current — a green file from yesterday's clean run, still on disk, is how a
+// refusal becomes an all-clear. Deleting the path is not the fix either: a consumer that treats a missing
+// file as "nothing to report" fails open by a different route.
+//
+// It MUST be fail-closed to a NAIVE reader: `ok: false` so a consumer keying only on `ok` lands on FAIL,
+// `refused: true` so one keying on that learns why, and **NO `violations` KEY AT ALL** — the gate is making
+// no claim about violations, and an empty array is precisely the claim it cannot make. ABSENT, not empty.
+// `1503368`: no cause is exempt, including an unreadable policy — a stale green does not care why this run
+// declined to overwrite it.
+export function refusalVerdict(spec, reason, unevaluated = null) {
+  const o = { spec, ok: false, refused: true, reason };
+  if (unevaluated && unevaluated.length) o.unevaluated = unevaluated;
+  return o;
 }
 
 /** §6.2 scope match: by NAME SEGMENT, last segment a prefix.
@@ -175,16 +491,227 @@ export function literalAllowed(effect, reached, values) {
   }
 }
 
+// ⟨0.24⟩ SPEC §3.1 — the REPORT route's Net destination classes, taken VERBATIM off the wire.
+//
+// `netClass` is already the TRANSITIVE set the producer derived (scan.mjs writes `netClassesOf([...rec
+// .hosts], rec.incomplete.has("Net"), netPartners)` into every Net-bearing entry), so re-deriving it in a
+// consumer is a §3.1 ⟨0.24⟩ re-classification with two live failure modes, in OPPOSITE directions:
+//   · the producer's `.candor/config` `net-partner` list is NOT on the wire, so a host the producer
+//     classified `known-partner` re-derives here as `unknown-host` — `deny Net[unknown-host]` fires on a
+//     function the producing project asserted safe (a FABRICATED violation, and one whose evidence the
+//     consumer cannot even see);
+//   · the AS-EFF-008 masked-surface flag is not on the wire either, so an entry whose `netClass` says
+//     `unknown-host` BECAUSE its host was runtime-computed re-derives from its one benign visible literal
+//     and loses the `unknown-host` member — the fail-OPEN mirror, on the exact filter a hardening team
+//     narrows through.
+// TWO MODES, because the two report routes differ in ONE way that matters — whether a refusal channel
+// exists downstream:
+//   · DEFAULT (MCP `candor_gate`, LSP diagnostics): map only the entries that actually CARRY the field.
+//     An entry without it falls back to the derivation, which is the fail-CLOSED reading (`netClassesOf`
+//     floors an empty/masked surface at `unknown-host`) and keeps a pre-⟨0.20⟩ or foreign report gated
+//     rather than silently un-narrowed. Neither surface can refuse a question, so a hedge beats a hole.
+//   · `authoritative` (`gate --report`): map EVERY `Net`-bearing entry, to its `netClass` or to the EMPTY
+//     set, so the derivation is unreachable and the report is the only source of the class — the §3.1
+//     ⟨0.24⟩ MUST NOT taken literally. That verb REFUSES a scoped `deny Net[…]` over a `netClass`-less
+//     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 } = {}) {
+  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);
+  }
+  return m;
+}
+
+// ⟨0.24⟩ MOVED HERE FROM query.mjs (SPEC §6.2: "THE GATE AND THE DISCLOSURE MUST APPLY THE SAME RULE, AND
+// SHOULD SHARE THE SAME CODE"). It lived beside `gate --report` because that is where it was written, and
+// the consequence was measured on the two surfaces that have no exit code: `mcp.mjs` and `lsp.mjs` called
+// `evaluatePolicy` with NO withhold predicate and no discloser, so BOTH directions of harm were live on the
+// surface an agent trusts and no human reads. Same report, same policy, against the CLI:
+//
+//   deny Unknown[reflect] app   -> CLI exit 2 (refused);  MCP {"ok":true,"violations":[]}   FALSE ALL-CLEAR
+//   deny Net[unknown-host] app  -> CLI exit 2 (refused);  MCP fires AND asserts
+//                                                         "netClass":["unknown-host"] the report never carried
+//
+// The control (`deny Unknown app`) fires on both, so the channel was not simply dead — it was answering a
+// narrowing question the report cannot answer, in whichever direction the missing evidence happened to fall.
+// A helper that only one of three call sites can reach is a rule only one of them implements.
+/**
+ * ⟨0.24⟩ THE THIRD ANSWERABILITY CASE (SPEC §3.1) — a class-scoped `deny` over a report that cannot answer
+ * the narrowing question. Returns the refusal message, or null when every scoped filter is answerable.
+ *
+ * A bare `deny Net` / `deny Unknown` asks a question the effect set alone answers. A SCOPED one —
+ * `deny Net[unknown-host]`, `deny Unknown[dispatch]` — asks a second question ("…and is the destination /
+ * the reason class one of THESE?") and NARROWS the gate on the answer. Where the report does not carry the
+ * evidence, the field is simply absent, the matcher sees an empty set, nothing intersects, and the effect
+ * is dropped from the violation: **the narrowing succeeds BECAUSE the evidence is missing**. Measured on
+ * the reference engine — `deny Net[unknown-host]` over a `Net`-bearing entry with no `netClass` returned
+ * exit 0 where bare `deny Net` returns 1, an absent optional field silently un-scoping a fail-closed gate.
+ *
+ * THE REFUSAL IS MINIMAL, and the minimality is the subtle half. §3.1 ⟨0.24⟩: a scoped `deny` is NOT
+ * unanswerable merely because some datum is missing. The class set only ever GROWS as evidence arrives
+ * (§6.2 CONTRIBUTES, never retracts) and `Reject` is upward-closed in it, so
+ *   · if the classes determinable from the entry ALONE already INTERSECT the filter, the rule FIRES and the
+ *     answer is certain — missing data could only have added more matches. That case never reaches here:
+ *     it is `evaluatePolicy`'s ordinary path.
+ *   · only where the determinable set is EMPTY does the rule fail to fire AND could the missing datum still
+ *     make it fire. That, and only that, is refused.
+ * A NON-empty set that does not intersect is answered (tolerated), because on the wire both fields are
+ * total by construction for the entries this can reach: `netClass` is emitted for EVERY `Net`-bearing entry
+ * and floored at `unknown-host`, and an in-scope `Unknown` always resolves — a DIRECT one CONTRIBUTES
+ * `unresolved` at its own entry (resolveReasonClasses, §6.2 requirement 3) and an INHERITED one has the
+ * callee that raised it in `calls`, because that callee carries `Unknown` and is therefore effectful and
+ * present. So a non-empty set means the channel is carried and the producer's set is the whole answer.
+ *
+ * That entry-level CONTRIBUTION is also why this engine does not repeat the over-broad refusal the spec
+ * records against candor-swift: a function whose direct `Unknown` names no reason is answerable here under
+ * `deny E Unknown[unresolved]` — the class comes from the entry itself, with no transitive step — so it
+ * FIRES rather than exiting 2.
+ *
+ * PER (RULE, FUNCTION), not per policy — §3.1's granularity ruling. A scoped rule whose own matches all
+ * carry their evidence evaluates normally; only the rule that would have been silently narrowed is refused.
+ *
+ * ⟨0.24⟩ IT NO LONGER SHORT-CIRCUITS THE GATE (SPEC §3.1 `7271c69` + `5a8cf48`), and that is the whole of
+ * this rung's precedence correction. It used to return the FIRST refusal message and the verb exited 2 on
+ * the spot — so a policy carrying a firing `deny Fs` BESIDE one unanswerable scoped rule exited 2 and wrote
+ * no `--gate-json` document at all, DELETING A CERTAIN VIOLATION from the machine-consumer channel. `Reject`
+ * is upward-closed (PAPER3 Lemma 2): if a rule fires on evidence the report carries, however the
+ * unanswerable rule would have resolved cannot un-reject it, so exit 1 is not merely fail-closed there, it
+ * is CERTAIN — and it names the violation where exit 2 names nothing.
+ *
+ * So it now returns EVERY unanswerable (rule, function, effect) triple, as a disclosure that travels
+ * ALONGSIDE a verdict rather than as the whole output, plus the `withhold` predicate `evaluatePolicy` needs
+ * to keep the unevidenced pairs from FIRING (see the note on that parameter — flooring an empty class set
+ * at `unresolved` is right for a matcher and wrong for a firing).
+ */
+export function unanswerableScoped(pol, functions, reasonAcc, netMap) {
+  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));
+    let e = byRule.get(r.raw);
+    if (!e) { e = { rule: r.raw, fns: [], why }; byRule.set(r.raw, e); }
+    e.fns.push(fn);
+  };
+  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 "
+          + "`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 "
+          + "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 "
+          + "EVALUATED for those functions rather than passed. Use the bare `deny Unknown`, or gate at "
+          + "scan time (candor-ts <src> --policy <file>).");
+    }
+  }
+  // EVERY withheld function is named, never one witness standing for the rest: the operator has to be able
+  // to see which part of the policy went unenforced, and a count cannot be acted on.
+  const unevaluated = [...byRule.values()].map(({ rule, fns, why }) => {
+    const names = [...new Set(fns)].sort();
+    const list = names.map((n) => `\`${n}\``).join(", ");
+    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 };
+}
+
 /**
  * The standing gate: evaluate a parsed policy over a report + callgraph (AS-EFF-006 deny/pure over
  * transitive inferred; AS-EFF-008 allowlists over the transitive literal surfaces, the no-visible-
  * literal case flagged as uncertifiable; AS-EFF-009 forbid by reachability). One line per violation.
+ *
+ * ⟨0.24⟩ THE ONLY MATCHING CODE IN THIS ENGINE. `scan --policy` lands here over the live graph;
+ * `gate --report` (SPEC §3.1) lands here over a WRITTEN report, with `callgraph`/`incomplete`/`partners`
+ * empty — none of the three rides the ⟨0.24⟩ wire, and the two rule kinds that would have needed them
+ * (`forbid`, `allow`) are REFUSED by that verb rather than evaluated on partial evidence. That shared
+ * landing is what makes "the same verdict from the same signature" a property of the code rather than of
+ * two consistent authors, and it is what §6.2 asks for: "THE GATE AND THE DISCLOSURE MUST APPLY THE SAME
+ * RULE, AND SHOULD SHARE THE SAME CODE."
  */
 // Each violation is a STRUCTURED record { rule, fn, effects, detail } (candor-spec §3.3 ⟨0.8⟩): `effects`
 // is the specific denied/allowed effect set the violation concerns ([] for the 009 layer-flow, which has
 // no single effect); `detail` is the message BODY (no `[AS-EFF-00x]` prefix — the rule carries the code).
 // The console gate renders `[${rule}] ${detail}`; --gate-json emits the records verbatim.
-export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map(), partners = new Set()) {
+// ⟨0.24⟩ `withhold(rule, fn, effect) -> bool` (SPEC §3.1 `5a8cf48`) — THE OPERATIONAL FORM OF MINIMAL
+// REFUSAL, and the half of the precedence ruling that makes it safe. It is null on the scan route (full
+// evidence, nothing to withhold) and supplied by `gate --report`.
+//
+// WHY IT EXISTS, because the mechanism is not obvious from the signature. Until the precedence fix, an
+// unanswerable scoped rule SHORT-CIRCUITED the whole gate, so this function was never reached with one.
+// Removing the short-circuit made it reachable — and `reasonClassesMatch` floors an empty class set at
+// `unresolved`, which is the correct fail-closed default for a MATCHER ("could this rule apply?") and the
+// WRONG basis for a FIRING ("did it?"). Measured on this engine: a `deny Unknown[unresolved]` over an entry
+// whose Unknown is INHERITED and reasonless began emitting an actual violation RECORD, asserting a reason
+// nobody recorded. Same constant, same helper, opposite direction of harm — a fabrication reachable ONLY
+// through the soundness fix.
+//
+// It is per (rule, function, effect), never whole-policy and never whole-rule: `deny Fs Net[unknown-host]`
+// over a function carrying BOTH a certain `Fs` and a `netClass`-less `Net` must still report the `Fs`.
+// Withholding the pair would delete a certain violation — the very harm the precedence ruling is fixing.
+/** ⟨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) {
+  // `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.24⟩ THE CLASS FILTER, AS A PREDICATE ON ONE (rule, function, effect) — does `r`'s `Unknown[…]` /
+ * `Net[…]` narrowing EXCLUDE `eff` at `entry`? Factored out of `evaluatePolicy` because it was inlined
+ * there, and inlined there meant the two ADVISORY verbs that ask the same question computed from the
+ * effect set ALONE. Measured on this engine, `deny Unknown[reflect,unresolved] app` over a report whose
+ * only hole is `native:dlopen` — the class the policy EXCLUDES:
+ *
+ *     gate --report        exit 0, no violations           <- correct, the class is excluded
+ *     fix-gate --strict    exit 1 + a remedy naming it     <- OVER-CHARGE: a red CI check and a hoist
+ *                                                             instruction for a boundary nothing denies
+ *     unverified --strict  exit 0, ok:true, []             <- UNDER-REPORT, and the worse half: the layer
+ *                                                             PASSES while carrying an Unknown, so it is a
+ *                                                             pass-but-Unknown hole, and the verb whose whole
+ *                                                             job is "your green gate is not provably green"
+ *                                                             certified it clean
+ *
+ * Same shape on the `Net[…]` sibling (`deny Net[unknown-host]` over a `known-partner` entry). SPEC §6.2:
+ * "THE GATE AND THE DISCLOSURE MUST APPLY THE SAME RULE, AND SHOULD SHARE THE SAME CODE" — this is that
+ * code, and both halves existed because the disclosure side never reached it.
+ *
+ * THE MATCHER QUESTION, NOT THE FIRING ONE. `reasonClassesMatch` floors an empty class set at `unresolved`,
+ * which the note on `withhold` records as the correct fail-closed default for a MATCHER ("could this rule
+ * apply?") and the wrong basis for a FIRING ("did it?"). The advisory verbs ask the matcher question — they
+ * emit no violation record that could assert a reason nobody recorded — so they use this predicate WITHOUT
+ * `withhold`, whose paired `unevaluated` disclosure has no ruled shape on those verbs anyway.
+ *
+ * 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) {
+  if (!entry) return false;
+  if (eff === "Unknown" && r.unknownClasses?.length)
+    return !reasonClassesMatch(reasonAcc.get(entry.fn), 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) {
   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" };
@@ -196,27 +723,13 @@ export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()
     if (netClass && netClass.length) rec.netClass = netClass;
     out.push(rec);
   };
-  // Reason-scoped Unknown: the Unknown reason CLASS must travel the call graph the same way the Unknown
-  // EFFECT does (unknownWhy in the report is direct-only). Classify each fn's DIRECT reasons to class
-  // tokens, then propagate transitively over `callgraph` to a fixpoint — so `deny E Unknown[reflect]` at a
-  // caller inheriting Unknown from a reflect-caused callee still fires (matches java/rust reasonClassAcc).
-  const reasonAcc = new Map();
-  for (const f of functions) {
-    const cs = new Set((f.unknownWhy ?? []).map(reasonClass));
-    if (cs.size) reasonAcc.set(f.fn, cs);
-  }
-  for (let changed = true; changed; ) {
-    changed = false;
-    for (const [caller, callees] of Object.entries(callgraph)) {
-      for (const callee of callees) {
-        const cc = reasonAcc.get(callee);
-        if (!cc) continue;
-        let set = reasonAcc.get(caller);
-        if (!set) { set = new Set(); reasonAcc.set(caller, set); }
-        for (const c of cc) if (!set.has(c)) { set.add(c); changed = true; }
-      }
-    }
-  }
+  // 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);
+  // ⟨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);
   for (const f of functions) {
     for (const r of pol.deny) {
       if (r.scope && !scopeMatches(f.fn, r.scope)) continue;
@@ -228,28 +741,21 @@ export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()
         ? f.inferred.filter((e) => e !== "Unknown")
         : f.inferred.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; an Unknown with no recorded reason ⇒ `unresolved`.
-      let kept = hits;
-      if (hits.includes("Unknown") && (r.unknownClasses?.length)) {
-        const cs = reasonAcc.get(f.fn);
-        const fnClasses = cs && cs.size ? [...cs] : ["unresolved"];
-        if (!fnClasses.some((c) => r.unknownClasses.includes(c))) kept = hits.filter((e) => e !== "Unknown");
-      }
-      // Net destination-class: a `deny Net[dest…]` keeps its Net hit only for a fn reaching one of those
-      // destination classes; else tolerate (only asserted-safe destinations). Fail-closed: a masked surface /
-      // a Net with no visible host is unknown-host (netClassesOf). The class travels the call graph via
-      // f.hosts + f.incomplete, both propagated transitively before the gate (scan.mjs).
-      if (kept.includes("Net") && (r.netClasses?.length)) {
-        const fnNet = netClassesOf(f.hosts ?? [], incomplete.get(f.fn)?.has("Net") ?? false, partners);
-        if (!fnNet.some((c) => r.netClasses.includes(c))) kept = kept.filter((e) => e !== "Net");
-      }
+      // 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).
+      // Fail-closed: a masked surface / a Net with no visible host is unknown-host (netClassesOf); the class
+      // 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));
+      // ⟨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 (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;
         // ⟨0.20⟩ when Net is denied, report ALL of the fn's destination classes (transitive).
-        const ncv = kept.includes("Net")
-          ? netClassesOf(f.hosts ?? [], incomplete.get(f.fn)?.has("Net") ?? false, partners)
-          : undefined;
+        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);
       }
     }
@@ -334,10 +840,48 @@ export function discoverConfigText(fromDir) {
   }
 }
 
+// ⟨0.24⟩ The PATH the text above came from (SPEC §3.1 `99eb4e9`: "if a config file supplied vocabulary that
+// participated in the verdict, the `--gate-json` document MUST name that file"). Discovery WALKS PARENT
+// DIRECTORIES and `CANDOR_CONFIG` overrides it outright, so a file the operator never named — and cannot
+// see named anywhere in the output — can decide the verdict. That is the ambient-input failure this format
+// exists to refuse, and the remedy is the usual one: not to forbid the input, but to make it unable to act
+// unnamed. Same walk as `discoverConfigText`, deliberately, so the two cannot name different files.
+export function discoverConfigPath(fromDir) {
+  const env = process.env.CANDOR_CONFIG;
+  if (env) { try { fs.readFileSync(env, "utf8"); return nodePath.resolve(env); } catch { return null; } }
+  let dir = nodePath.resolve(fromDir);
+  for (;;) {
+    const cand = nodePath.join(dir, ".candor", "config");
+    if (fs.existsSync(cand)) return cand;
+    const parent = nodePath.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// ⟨0.24⟩ The ANCHOR for keys that supply POLICY VOCABULARY (SPEC §3.1 `99eb4e9`). All four gate verbs used
+// to anchor config discovery at the POLICY file's directory while all four scan routes anchored at the
+// TARGET, so with the policy filed outside the scan target `scan --policy P` and `gate --report R --policy
+// P` expanded the SAME rule differently — §3.1's byte-equality MUST broken by a file that is neither the
+// report nor the policy. Vocabulary travels with the policy that uses it. TARGET-scoped keys (`deps`,
+// `net-partner`, scan settings) keep anchoring at the target, because they describe the thing being scanned
+// rather than the language the rules are written in.
+export function policyVocabularyAnchor(policyFile, fallbackDir) {
+  return policyFile ? nodePath.dirname(nodePath.resolve(policyFile)) : fallbackDir;
+}
+
 // ⟨0.19⟩ Parse `unknown-alias <name> = <class,…>` lines (SPEC §6.2) into a Map name→class-token[]. A name
 // that shadows a built-in (`*`/`dynamic`/a class token) is warned-and-skipped, as is a no-valid-class def.
 // Byte-shape with the java `Config.addAlias` / rust `parse_unknown_aliases`.
-export function parseUnknownAliases(configText) {
+// ⟨0.24⟩ `errors`, when supplied, receives an unrecognised token in an alias DEFINITION under the same rule
+// as one in the policy itself (SPEC §6.2 `be0b9a9` — the rule binds EVERY policy value list). This is the
+// sharper of the two: the typo is in the VOCABULARY the policy is written against rather than in the policy,
+// and it fails open identically — `unknown-alias corp = dispatch,nativ` silently becomes `{dispatch}`, so
+// `deny Unknown[corp]` stops gating native-caused holes that `= dispatch,native` catches, and the operator
+// reads a policy that mentions no typo at all. A RESERVED or empty NAME stays a warn-and-skip: the name is
+// not a value token, the definition is dropped whole, and a rule referencing it then raises its own
+// unrecognised-token error at the policy — loud by the route the ruling already covers.
+export function parseUnknownAliases(configText, errors = null) {
   const out = new Map();
   if (!configText) return out;
   for (const raw of configText.split(/\r?\n/)) {
@@ -358,6 +902,10 @@ export function parseUnknownAliases(configText) {
       if (!cn) continue;
       if (cn === "dynamic") DYNAMIC_CLASSES.forEach((c) => classes.add(c));
       else if (REASON_CLASSES.includes(cn)) classes.add(cn);
+      else if (errors) errors.push({ kind: "reason-class/alias", token: cn,
+                                     accepted: [...REASON_CLASSES, "dynamic"], rule: line,
+                                     message: `unknown reason-class \`${cn}\` in an \`unknown-alias\` `
+                                            + `DEFINITION (known: ${REASON_CLASSES.join(", ")}, or dynamic)` });
       else console.error(`candor: \`unknown-alias ${name}\` names unknown reason-class \`${cn}\` — skipped`);
     }
     if (classes.size === 0) console.error(`candor: ignoring \`unknown-alias ${name}\` — no valid reason-class`);