candor-ts 0.30.0 → 0.32.0

package/query.mjs

@@ -26,8 +26,8 @@ import { fileURLToPath } from "node:url";
 import { parsePolicy, scopeMatches, discoverConfigPolicy, parseUnknownAliases, discoverConfigText,
          evaluatePolicy, reportNetClasses, resolveReasonClasses, discoverConfigPath,
          policyVocabularyAnchor, policyErrorText, policyRefusalUnevaluated, policyUnreadable, policyZeroRules,
-         fatalPolicyErrors, refusalVerdict,
-         unanswerableScoped, wholePolicyUnanswerable } from "./policy.mjs";
+         fatalPolicyErrors, refusalVerdict, sortViolations,
+         unanswerableScoped, wholePolicyUnanswerable, reportUnits } from "./policy.mjs";
 import { hasReport } from "./query-core.mjs";
 import { printAgents, writeStdoutSync } from "./contract.mjs";
 import { bestFinds } from "./surface.mjs";
@@ -191,7 +191,18 @@ const put = (a, data, proseFn) => { if (!proseFn || wantJsonOut(a)) emit(data);
 // disclosure, not an exit code"), so the gate exits 0 there. A note that sends the reader to a CI job which
 // then passes teaches them the warning is noise — the disclosure discrediting itself. The count-0 sentence
 // is also the more urgent one and says so: nothing downstream fails closed on those bytes.
-const gateLine = (comp) => (comp.unanalyzed.length || comp.unreadable?.length
+//
+// ⟨0.32⟩ THE UNREAD-CLASS CAUSE GETS ITS OWN SENTENCE, because both of the others are FALSE of it in
+// opposite directions: "exits 2 over these bytes" is unqualified and these verbs hold no policy to say it
+// under, while "exits 0 over a judged-nothing report" names a cause that is not present and sends the
+// reader to a CI job that will pass. `gate --report` can only ever evaluate a deny-family rule — measured
+// 2026-08-24, all four engines refuse an `allow`-only policy as NO RULES and a `forbid` rule as
+// unevaluable on that route — so the exit is a certainty once a policy exists; the gap is that none does
+// here. Checked FIRST, because a report can carry an unread class and unanalyzed units together and this
+// is the sentence naming the cause the other two do not.
+const gateLine = (comp) => (comp.unread?.length && !comp.unanalyzed.length && !comp.unreadable?.length
+  ? "`gate --report` exits 2 over these bytes under any policy it can evaluate (they are all `deny`/`pure`), and this verb holds none — so NOTHING DOWNSTREAM IS FAILING CLOSED ON IT HERE and this note is the whole of the warning."
+  : comp.unanalyzed.length || comp.unreadable?.length
   ? "`gate --report` exits 2 over these bytes."
   : "NOTHING DOWNSTREAM WILL CATCH THIS FOR YOU — `gate --report` exits 0 over a judged-nothing report (⟨0.24⟩: a disclosure, not an exit code), so this note is the whole of the warning.");
 
@@ -225,6 +236,17 @@ const incompleteAnswerNote = (comp, soWhat, tail) => {
     causes.push(`include ${comp.noManifest.length} report(s) carrying NO \`analyzed\` manifest at all`);
   if (comp.unreadable?.length)
     causes.push(`include ${comp.unreadable.length} file(s) that could not be parsed at all`);
+  // ⟨0.30⟩/⟨0.32⟩ THE TWO SCOPE CAUSES, which `mustHedge` has counted since ⟨0.30⟩ and this sentence
+  // never named. Over a report whose ONLY cause is one of them the head came out as
+  // `⚠ INCOMPLETE — the report(s) under this locator , so …` — an EMPTY clause, because `causes` was
+  // built from the three manifest rows alone. A hedge whose sentence says nothing is the deleted
+  // disclosure arriving inside the disclosure; candor-rust and candor-java each measured the same line
+  // on the same rung. It was unreachable here while the unread cause was kept out of `mustHedge`, and
+  // reachable on nearly every no-policy report the moment it was not.
+  if (comp.outOfScope?.length)
+    causes.push(`name ${comp.outOfScope.length} function(s) OUTSIDE the scan's scope performing an effect the producing scan's policy DENIED`);
+  if (comp.unread?.length)
+    causes.push(`declare ${comp.unread.length} exclusion class(es) the scan did NOT READ (\`excluded[].peeked: false\`)`);
   console.log(`candor-ts: ⚠ INCOMPLETE — the report(s) under this locator ${causes.join(", and ")}, so ${soWhat}:`);
   for (const u of comp.unanalyzed) console.log(`    ${u.path}${u.reason ? `  (${u.reason})` : ""}`);
   if (comp.judgedNothing.length)
@@ -233,6 +255,10 @@ const incompleteAnswerNote = (comp, soWhat, tail) => {
     console.log(`    ${f} — no \`analyzed\` manifest (a pre-⟨0.21⟩ producer): it makes no claim about what was judged, so its silence licenses none either. Re-scan with a current engine.`);
   for (const f of comp.unreadable ?? [])
     console.log(`    ${f} — could not be parsed (corrupt or mid-write), so whatever it says is not in this answer`);
+  for (const o of comp.outOfScope ?? [])
+    console.log(`    ${o.fn ?? "(unnamed)"} — OUTSIDE the producing scan's scope: it performs ${(o.effects ?? []).join(", ")}, and the gate did not judge it`);
+  for (const c of comp.unread ?? [])
+    console.log(`    ${c} — this exclusion class went UNREAD (\`excluded[].peeked: false\`): its effects are absent because nothing looked, not because there are none. Re-run the producing scan WITH a \`deny\`/\`pure\` policy so the peek reads it (candor-ts <dir> --policy <file>)`);
   console.log(`    ${tail} ${gateLine(comp)}`);
 };
 
@@ -243,8 +269,8 @@ const incompleteAnswerNote = (comp, soWhat, tail) => {
 // construct it. `map` was the one caller whose top level is a USER NAMESPACE, and it answered by MERGING
 // the hedge over a module literally named `incomplete` and disclosing the loss on stderr — a lost row the
 // operator was told about, which was the best available answer while the caveat had to ride the result.
-// It no longer does: `map` takes `putCaveatInstead` below, where the caveat REPLACES the document and
-// nothing is displaced. Every remaining caller has a FIXED key set of its own (`where`
+// It no longer does: `map` takes `putNestedWithCaveat` below, where its namespace sits one level down
+// under `modules` and nothing is displaced. Every remaining caller has a FIXED key set of its own (`where`
 // {effect,directly,inherited}, `reachable` {entryPoints,effects}, `containment` {contained,ambient},
 // `blindspots` {sources,totalUnknown}), so a collision here is not constructible from any report.
 // Deleted rather than kept as a dormant guard: a check whose condition cannot arise reads as coverage.
@@ -261,10 +287,9 @@ const putAnswer = (a, data, proseFn, comp, soWhat, tail) => {
   return data;
 };
 
-// ---- ⟨0.28⟩ RUNG A — SPEC §2: "A VERB WHOSE PINNED SHAPE CANNOT CARRY THE CAVEAT MUST EMIT THE CAVEAT
-// DOCUMENT INSTEAD OF ITS RESULT DOCUMENT." Not a result document with the caveat omitted, and not an
-// empty result of the pinned shape. `putAnswer` above SPREADS the caveat into the answer, which works for
-// every verb with a fixed key set; two verbs have no such place:
+// ---- ⟨0.28⟩ RUNG A — SPEC §2: a verb whose pinned shape CANNOT CARRY the caveat changes SHAPE over a
+// hedging report. `putAnswer` above SPREADS the caveat into the answer, which works for every verb with a
+// fixed key set; two verbs have no such place at their root:
 //
 //   show   pinned to a TOP-LEVEL ARRAY — nowhere to put a key at all. MEASURED here 2026-08-12 over a
 //          report declaring one `unanalyzed` unit: `[]`, exit 0, no caveat on ANY channel. *Nothing
@@ -278,10 +303,35 @@ const putAnswer = (a, data, proseFn, comp, soWhat, tail) => {
 // airtight in one namespace and merely unlikely in another is not a convention; it is a deferred
 // collision."
 //
-// THE TYPE CHANGE IS THE POINT. A consumer doing `for (const x of doc)` over `show` gets a TypeError
-// rather than a silent zero-iteration loop — the one case where breaking a consumer is the CORRECT
-// outcome, because the consumer was being lied to. The exit does not move (⟨0.24⟩: a disclosure, not an
-// exit code), and HEALTHY OUTPUT IS BYTE-IDENTICAL: the shape changes only on the hedge path.
+// ⟨0.32⟩ **AND WHAT THE HEDGING DOCUMENT CONTAINS WAS RULED AGAIN ON 2026-08-25: THE RESULT *AND* THE
+// WARNING, NEVER THE WARNING INSTEAD OF THE RESULT.** Rung A's original answer was the CAVEAT DOCUMENT
+// INSTEAD of the result, written while the trigger was a manifest a scan had FAILED to produce — there
+// was little result to lose. ⟨0.32⟩'s unread-class cause then armed the same substitution on nearly every
+// no-policy report. MEASURED on a single-file scan with unparsed `.js`/`.mjs` siblings, and on a rust
+// crate with one `tests/` dir:
+//
+//     show <fn> --json   ->  {"incomplete": true}      the rows are GONE
+//     map       --json   ->  {"incomplete": true}      the map is GONE
+//
+// and through mcp.mjs the SAME document reached an AGENT (`candor_show`/`candor_map`), which is the
+// channel that cannot ask a follow-up question.
+//
+// **THE BOUNDARY, STATED: THESE TWO ARE DESCRIPTIVE — THEY CERTIFY NOTHING.** No `ok`, no verdict, no
+// exit-code obligation, so there is no claim for a pessimism rule to protect and withholding the rows
+// buys no soundness. The verbs on the OTHER side of the boundary are the ones that answer `ok` — `gate`,
+// and `unverified`/`fix-gate`/`whatif`/`fix` under `--strict` — and they MUST keep refusing over these
+// same bytes (⟨0.24⟩'s "never LESS sensitive than the gate"; conformance PARTs 62 and 67 pin it). Nothing
+// in this helper touches them. The same codebase already answers the descriptive question this way one
+// verb over: `gains --json` keeps its gained set and adds `incomplete: true` beside it.
+//
+// SO THE RESULT MOVES ONE LEVEL DOWN, under a key this helper is given, and the caveat sits at the root.
+// That placement is what lets both properties hold at once: no reserved-key convention is needed (`map`'s
+// module namespace is nested, so a module named `incomplete` cannot collide with the boolean), and no row
+// is displaced. THE TYPE CHANGE IS STILL THE POINT — a consumer doing `for (const x of doc)` over `show`
+// still gets a TypeError rather than a silent zero-iteration loop — and relative to the shape this
+// replaces the change is purely ADDITIVE: a consumer that already handles the hedge sees one more key.
+// The exit does not move (⟨0.24⟩: a disclosure, not an exit code), and HEALTHY OUTPUT IS BYTE-IDENTICAL:
+// the shape changes only on the hedge path.
 //
 // The PROSE arm is `putAnswer`'s, verbatim — prose has no shape problem, and the clause is about the
 // machine document. Sharing the note + renderer call keeps the two channels from drifting.
@@ -290,14 +340,37 @@ const putAnswer = (a, data, proseFn, comp, soWhat, tail) => {
 // it delegated to `putAnswer`, whose `{ ...data, ...{} }` turned `show`'s ARRAY into `{"0": {…}}` — the
 // pinned top-level array destroyed on the very path this rung promises to leave byte-identical. Caught by
 // the intact-input control before it left the machine. So the healthy arm emits `data` itself.
-const putCaveatInstead = (a, data, proseFn, comp, soWhat, tail) => {
-  if (!proseFn || wantJsonOut(a)) { emit(mustHedge(comp) ? completenessFields(comp) : data); return data; }
+const putNestedWithCaveat = (a, key, data, proseFn, comp, soWhat, tail) => {
+  if (!proseFn || wantJsonOut(a)) {
+    emit(mustHedge(comp) ? { [key]: data, ...completenessFields(comp) } : data);
+    return data;
+  }
   incompleteAnswerNote(comp, soWhat, tail);
   proseFn(data, mustHedge(comp));
   return data;
 };
 // The one sentence every hedged prose arm ends with, so the six cannot drift into six wordings.
 const NOT_A = (claim) => `— but see the INCOMPLETE note above; this is NOT "${claim}"`;
+
+// ---- ⟨0.32⟩ THE THREE GRAPH-TRAVERSAL VERBS THAT CARRIED NO COMPLETENESS READER AT ALL ----------------
+//
+// `callers`, `impact` and `path`. The ⟨0.28⟩ rung that widened SPEC §2's re-disclosure MUST to "any verb
+// whose output could be read as a NEGATIVE FINDING about the code — a verdict, an empty result set, or a
+// zero count" enumerated six verbs and skipped these three; the ⟨0.32⟩ unread-class cause then made the
+// gap fire on nearly every no-policy report. MEASURED at HEAD 2026-08-25, over a report whose `excluded`
+// names one class with `peeked: false`, all three answered FLAT at exit 0 with nothing on either channel —
+// and the same three tools answered flat on the MCP surface, which is the consumer that cannot ask a
+// follow-up question. Reproduced identically in candor-rust and candor-java.
+//
+// Each verb's own `soWhat`/`tail` pair, hoisted because `callers` has TWO answering sites (the complete
+// graph and the effect-only fallback) and `path` has THREE. A wording written at one site and forgotten at
+// the next is how this file's own comments say the last two fixes here went wrong.
+const CALLERS_SOWHAT = "the caller set below covers only the call graph candor could see";
+const CALLERS_TAIL = "A caller living in an unread unit is ABSENT from the graph, so it appears in neither `direct` nor `transitive` — and an EMPTY answer reads as *nothing calls this*, which is a claim this report cannot support. Re-scan before treating this as the blast radius.";
+const IMPACT_SOWHAT = "the blast radius below covers only the callers candor could see";
+const IMPACT_TAIL = "A caller living in an unread unit is ABSENT from the graph, so it is missing from this count and from the entry points — and `affectedCount: 0` reads as *safe to edit*, which is a claim this report cannot support. Re-scan before treating this as the blast radius.";
+const PATH_SOWHAT = "the chain below is traced over only the call graph candor could see";
+const PATH_TAIL = "A hop through an unread unit BREAKS the chain, so `path` can answer EMPTY for a function that really does reach the effect — and an empty `path` reads as *this function does not reach it*, which is a claim this report cannot support. Re-scan before treating an empty chain as an answer.";
 const csv = (xs) => (xs && xs.length ? xs.join(", ") : "none");
 const rows = (xs, pre = "    ") => { for (const x of xs) console.log(pre + x); };
 // Per-verb prose renderers. Read the SAME shapes query-core returns (so JSON and prose can't drift); kept
@@ -318,15 +391,27 @@ const P = {
     if (d.directly.length) { console.log(`  perform it directly (${d.directly.length}):`); rows(d.directly); }
     if (d.inherited.length) { console.log(`  reach it transitively (${d.inherited.length}):`); rows(d.inherited); }
   },
-  callers: (d) => {
+  callers: (d, hedge) => {
     // ⟨0.28⟩ UNREACHABLE FROM THE CLI since the callers verb split the empty-`of` case into its two real
     // causes below (no graph at all -> `unanswerable`, exit 2; a name absent from a real graph -> "no
     // function matching", exit 2). Kept as a renderer guard only; do NOT route a new caller through it —
     // this sentence is a determined negative and is the wrong answer when there is no call graph.
-    if (!d.of.length) { console.log("candor: no function in the call graph matches that name."); return; }
+    if (!d.of?.length) {
+      // ⟨0.32⟩ …and the effect-only-fallback arm routes `{}` through here, where `d.of` is undefined. The
+      // hedged spelling is the one that matters: over a report naming an unread class this sentence is
+      // itself a determined negative.
+      console.log(hedge
+        ? `candor: no function in the call graph candor COULD SEE matches that name ${NOT_A("there is no such function")}.`
+        : "candor: no function in the call graph matches that name.");
+      return;
+    }
     console.log(`candor callers — who reaches \`${d.of.join("`, `")}\`:`);
     console.log(`  direct callers (${d.direct.length}): ${csv(d.direct)}`);
     console.log(`  transitive callers (${d.transitive.length}): ${csv(d.transitive)}`);
+    // ⟨0.32⟩ "0 callers" IS the prose spelling of `direct: []`, so the note alone is not enough — a fix
+    // that leaves the calm reading standing MOVES the false all-clear rather than removing it. Same shape
+    // `show` and `blindspots` already take.
+    if (hedge && !d.transitive.length) console.log(`  ${NOT_A("nothing calls it")}.`);
   },
   show: (d, hedge) => {
     // ⟨0.28⟩ the empty sentence stops citing the ⟨0.21⟩ purity convention when the report cannot back it:
@@ -397,11 +482,14 @@ const P = {
     }
     for (const [e, v] of effs) console.log(`  ${e}: ${v.count} (via ${csv(v.via)})`);
   },
-  impact: (d) => {
+  impact: (d, hedge) => {
     console.log(`candor impact — the blast radius of \`${d.fn}\`:`);
     console.log(`  ${d.affectedCount} effectful function(s) transitively call it${d.affected.length ? ":" : "."}`);
     if (d.affected.length) rows(d.affected);
     if (d.entryPoints.length) { console.log(`  reachable from ${d.entryPoints.length} entry point(s):`); rows(d.entryPoints.map((ep) => `${ep.fn}  [${csv(ep.inferred)}]`)); }
+    // ⟨0.32⟩ `affectedCount: 0` is this verb's strongest claim — *nothing calls this, safe to change* — and
+    // the sentence above is its prose spelling. Under a hedge it is exactly what the note withdrew.
+    if (hedge && !d.affected.length) console.log(`  ${NOT_A("nothing calls it, safe to change")}.`);
   },
   blindspots: (d, hedge) => {
     if (!d.sources.length) {
@@ -462,7 +550,7 @@ const knownFnNames = (cg, fns) => [...new Set([...Object.keys(cg), ...fns.map((e
 // UNTOUCHED (conformance PART 5 pins `{effect, fn, path:[{fn,loc,source}]}` four-way): this path is
 // only taken when the caller did NOT pass --json, and it reads the SAME `path` array corePath computes.
 // Prints to stdout and returns nothing (matches the JSON-only verbs' fire-and-forget style).
-function renderPathHuman(fns, cg, fnQ, eff) {
+function renderPathHuman(fns, cg, fnQ, eff, hedge = false) {
   // Resolve the start over the REPORT entries (as Rust does) — that's where `inferred` lives, and the
   // no-effect wording quotes it. The RESOLVED name (not the raw query) is then handed to corePath,
   // which re-resolves over the CALLGRAPH keys — a DIFFERENT name set: a raw partial query could pick
@@ -483,14 +571,19 @@ function renderPathHuman(fns, cg, fnQ, eff) {
     // `inferred` is printed in Rust's `{:?}` debug shape: each name quoted, ", "-joined, in `[...]`,
     // in the report's original order (unsorted). An empty set prints `[]`.
     const dbg = `[${inferred.map((e) => `"${e}"`).join(", ")}]`;
-    console.log(`${start} does not perform ${eff}  (inferred: ${dbg})`);
+    // ⟨0.32⟩ "does not perform" is the prose spelling of `path: []`, and over a report naming a class the
+    // scan never opened it is a determined negative the report cannot support — the effect could enter
+    // through a callee in the unread unit, which contributes no `inferred` entry at all.
+    console.log(`${start} does not perform ${eff}  (inferred: ${dbg})`
+      + (hedge ? `  ${NOT_A(`${start} cannot reach ${eff}`)}` : ""));
     return;
   }
   const r = corePath(fns, cg, start, eff);
   if (r.path.length === 0) {
     // Inferred, but no LOCAL direct source on a `calls` path — reached cross-crate or via Unknown.
     console.log(`${start} performs ${eff} but its source is not a local function `
-      + `(cross-crate, or via Unknown) — not statically traceable.`);
+      + `(cross-crate, or via Unknown) — not statically traceable.`
+      + (hedge ? `  ${NOT_A("there is no traceable local source")}` : ""));
     return;
   }
   console.log(`candor path — how \`${start}\` comes to perform ${eff}:\n`);
@@ -509,7 +602,7 @@ function renderPathHuman(fns, cg, fnQ, eff) {
 // package.json; SPEC_VERSION is the spec contract this build speaks. Reused, never re-littered.
 const QUERY_DIR = path.dirname(fileURLToPath(import.meta.url));
 const PKG_VERSION = JSON.parse(fs.readFileSync(path.join(QUERY_DIR, "package.json"), "utf8")).version;
-const SPEC_VERSION = "0.30";
+const SPEC_VERSION = "0.32";
 
 // ---- the §3.3.1 canonical query grammar (⟨0.10⟩, additive over 0.9) --------------------------------
 // One shape for every verb: `<verb> <verb-args…> [--report <locator>] [--policy <file>] [--json]
@@ -552,7 +645,48 @@ function discoverReportPrefix() {
 // A null prefix (no --report AND nothing discovered) is a LOUD exit-2 failure — never a silent empty
 // answer. A resolved prefix that names NO report files is likewise loud (hasReport). One helper so every
 // verb's no-report path is identical to the Rust engine's (report_or_discover + the no-files check).
+// ⟨0.32⟩ SPEC §3.3.1 — did the most recent attempt over these reports REFUSE?
+//
+// A consumer cannot work this out for itself. The hazard is an EVENT — a refusal that happened AFTER
+// these bytes were written — witnessed only by the run that refused; no function of the report and the
+// tree recovers it. So the refusing run writes a marker beside the reports and this reads it.
+//
+// Resolved for all three §3.3.1 locator forms. The DIRECT-FILE case is why the marker carries its own
+// `prefix`: that form accepts any `.json` name whatever its dot-segments, so the prefix cannot come from
+// the filename — the marker is found by scanning the file's directory and asking which recorded prefix
+// covers it.
+function refusalMarkerFor(prefix) {
+  const read = (f) => {
+    try {
+      const d = JSON.parse(fs.readFileSync(f, "utf8"));
+      return d && d.refused === true && typeof d.prefix === "string" ? d : null;
+    } catch { return null; }
+  };
+  try {
+    if (prefix.endsWith(".json") && fs.existsSync(prefix) && fs.statSync(prefix).isFile()) {
+      const dir = path.dirname(path.resolve(prefix));
+      const me = path.resolve(prefix);
+      for (const n of fs.readdirSync(dir)) {
+        if (!n.endsWith(".refused.json")) continue;
+        const d = read(path.join(dir, n));
+        if (d && me.startsWith(path.resolve(d.prefix))) return d;
+      }
+      return null;
+    }
+  } catch { return null; }
+  return read(`${prefix}.refused.json`);
+}
+
 function requireReport(prefix) {
+  if (prefix !== null) {
+    const m = refusalMarkerFor(prefix);
+    if (m) {
+      console.error(`candor-ts: the most recent scan over '${m.prefix}' REFUSED — these reports are from `
+                  + `an earlier run and this verb will not certify them. Cause: ${m.reason}. `
+                  + `Re-scan ${m.target || "the target"}; a completing run clears the marker.`);
+      process.exit(2);
+    }
+  }
   if (prefix === null) {
     console.error("candor-ts: no report found (no --report and no .candor/ discovered) — scan the crate first.");
     process.exit(2);
@@ -1184,11 +1318,12 @@ switch (cmd) {
     // A missing/empty <query> is a LOUD usage error (exit 2, like candor-java) — never a silently-empty
     // `[]` at exit 0, which reads as an authoritative "no such function" over a question never asked.
     if (!q) { console.error("usage: candor-ts-query show <query> [--report <locator>] [--json]"); process.exit(2); }
-    // ⟨0.28⟩ RUNG A — `show`'s pinned shape is a TOP-LEVEL ARRAY, so over a hedging report it emits the
-    // CAVEAT DOCUMENT INSTEAD (see `putCaveatInstead`). Before this it took plain `put` and had no
-    // completeness reader at all: measured, `[]` at exit 0 over a report whose own manifest names a file
-    // candor could not read — the only verb of the six with no caveat on EITHER channel.
-    putCaveatInstead(args, coreShow(loadReportOrDie(prefix), q), P.show, reportCompleteness(prefix),
+    // ⟨0.28⟩ RUNG A — `show`'s pinned shape is a TOP-LEVEL ARRAY, so over a hedging report it changes
+    // shape (see `putNestedWithCaveat`). Before that rung it took plain `put` and had no completeness
+    // reader at all: measured, `[]` at exit 0 over a report whose own manifest names a file candor could
+    // not read — the only verb of the six with no caveat on EITHER channel. ⟨0.32⟩ the rows now travel
+    // under `functions` BESIDE the caveat rather than being replaced by it: `show` certifies nothing.
+    putNestedWithCaveat(args, "functions", coreShow(loadReportOrDie(prefix), q), P.show, reportCompleteness(prefix),
       `the function(s) shown below are only those candor could SEE match \`${q}\``,
       "A function in an unread unit is ABSENT from the report, so it cannot be shown here at all. Re-scan for a complete answer.");
     break;
@@ -1279,12 +1414,25 @@ switch (cmd) {
       // so the answer is empty at exit 0, never a fabricated "no such function" (rust corpus-audit #5,
       // byte-matching its two arms: `{}` on the machine channel, the re-scan pointer on the human one).
       if (!completeGraph) {
-        put(args, {}, () => console.log(`candor: no caller of \`${q}\` in the effect-relevant graph (the full call-graph sidecar is absent; re-scan with --out to see pure-only callers).`));
+        // ⟨0.32⟩ AND THIS ARM TAKES THE HEDGE TOO. `{}` is the STRONGEST determined negative the format
+        // has — every key a consumer reads defaults to empty, so `d.direct ?? []` cannot tell it from
+        // `{"direct": []}`. The sidecar-absence sentence is a DIFFERENT limitation (an effect-only graph)
+        // and does not cover a report whose own `excluded` names a class nothing opened.
+        putAnswer(args, {}, () => console.log(`candor: no caller of \`${q}\` in the effect-relevant graph (the full call-graph sidecar is absent; re-scan with --out to see pure-only callers).`),
+          reportCompleteness(prefix), CALLERS_SOWHAT, CALLERS_TAIL);
         break;
       }
       console.error(`candor-ts-query callers: no function matching '${q}' in the call graph`); process.exit(2);
     }
-    put(args, cres, P.callers);
+    // ⟨0.32⟩ `putAnswer`, not `put`: this verb carried NO completeness reader at all — measured at HEAD
+    // over a report whose `excluded` names one class with `peeked: false`, `callers` answered
+    // `{"of":[…],"direct":["a.top"],"transitive":["a.top"]}` at exit 0 with no caveat on EITHER channel,
+    // and an EMPTY `direct` over the same bytes reads as *nothing calls this*. Its key set is FIXED, so
+    // the caveat spreads in beside the answer exactly as it does for `where` — no nesting, no reserved-key
+    // collision, and the exit does not move. `show`/`map` OVER-hedged (`putNestedWithCaveat` above, and
+    // the descriptive/certifying boundary is stated there); these three UNDER-hedged, which is the
+    // direction this family calls the cardinal sin.
+    putAnswer(args, cres, P.callers, reportCompleteness(prefix), CALLERS_SOWHAT, CALLERS_TAIL);
     break;
   }
   case "map": {
@@ -1292,9 +1440,11 @@ switch (cmd) {
     const { prefix } = resolveReportVerb(args, 0);
     // ⟨0.28⟩ `map` answers `{}`, which SPEC §2 calls the STRONGEST determined negative there is: every key
     // a consumer reads defaults to empty, so `d["db"] ?? {}` cannot tell an empty map from an unexamined
-    // one. RUNG A: its top level is a USER NAMESPACE, so the caveat REPLACES the module map rather than
-    // merging into it — the merged shape displaced a real module row to make space for the hedge.
-    putCaveatInstead(args, coreMap(loadReportOrDie(prefix)), P.map, reportCompleteness(prefix),
+    // one. RUNG A: its top level is a USER NAMESPACE, so the caveat may not merge into it — the merged
+    // shape displaced a real module row to make space for the hedge. ⟨0.32⟩ the map now NESTS under
+    // `modules` with the caveat at the root, which removes the collision instead of deferring it AND
+    // keeps the answer: `map` certifies nothing, so there was never a claim to withhold.
+    putNestedWithCaveat(args, "modules", coreMap(loadReportOrDie(prefix)), P.map, reportCompleteness(prefix),
       "the module rows below cover only the source candor read",
       "A module living wholly in an unread unit is MISSING from this overview, and one that IS listed may be missing functions. Re-scan for a complete map.");
     break;
@@ -1453,7 +1603,11 @@ switch (cmd) {
     if (coreMatches(knownFnNames(impCg, impFns), q).length === 0) {
       console.error(`candor-ts-query impact: no function matching '${q}'`); process.exit(2);
     }
-    put(args, coreImpact(impFns, impCg, q), P.impact);
+    // ⟨0.32⟩ `putAnswer`, not `put` — this verb had NO completeness reader at all (see `CALLERS_SOWHAT`
+    // above for the measurement and the boundary). `affectedCount: 0` is the strongest claim in this
+    // verb's vocabulary, and over a report whose own `excluded` names a class nothing opened it rests on
+    // a graph missing whatever lives in that class. Fixed key set, so the caveat spreads in at the root.
+    putAnswer(args, coreImpact(impFns, impCg, q), P.impact, reportCompleteness(prefix), IMPACT_SOWHAT, IMPACT_TAIL);
     break;
   }
   case "blindspots": {
@@ -1655,6 +1809,18 @@ switch (cmd) {
     // "does not perform undefined" at exit 0 — a false all-clear over a question that was never posed.
     if (!fn || !eff) { console.error("usage: candor-ts-query path <fn> <Effect> [--report <locator>] [--json]"); process.exit(2); }
     const fns = loadReportOrDie(prefix);
+    // A TYPO'D EFFECT NAME IS A LOUD ERROR HERE TOO. `where` has refused an unknown effect since the
+    // corpus audit; `path` did not, and answered "<fn> does not perform Fsz" at exit 0 — a typo scored
+    // as a confident NEGATIVE, in the verb people reach for to check one specific claim.
+    //
+    // Same rule as `where`, deliberately: a KNOWN effect that is simply absent is a legitimate negative
+    // answer, and an unknown name PRESENT in the report (a spec extension effect from another engine) is
+    // allowed. The error is only for a name NEITHER known NOR present.
+    if (!KNOWN_EFFECTS.includes(eff) && eff !== "Unknown"
+        && !fns.some(f => (f.inferred || []).includes(eff))) {
+      console.error(`candor-ts-query path: unknown effect '${eff}' (known: ${KNOWN_EFFECTS.join(", ")})`);
+      process.exit(2);
+    }
     // ⟨0.28⟩ Sidecar first, then the report's embedded `calls` edges (rust's `path` runs on the report's
     // edges alone — see the callers verb). The unanswerable arm below keeps the genuinely-absent case.
     let cg = loadCallgraph(prefix);
@@ -1703,13 +1869,23 @@ switch (cmd) {
     if (coreMatches(knownFnNames(cg, fns), fn).length === 0) {
       console.error(`candor-ts-query path: no function matching '${fn}'`); process.exit(2);
     }
-    if (wantJson) emit(corePath(fns, cg, fn, eff));           // conformance PART 5 shape — UNCHANGED
+    // ⟨0.32⟩ THE COMPLETENESS READER THIS VERB DID NOT HAVE (see `PATH_SOWHAT` above). `path: []` is the
+    // determined negative here — *this function does not reach that effect* — and a hop through an unread
+    // unit BREAKS the chain, so a hedging report can produce that answer for a function that really does
+    // reach it. Read once and used on BOTH arms; the key set is fixed, so the caveat spreads at the root
+    // and the conformance PART 5 shape is unchanged on a complete report (`completenessFields` → `{}`).
+    const pcomp = reportCompleteness(prefix);
+    if (wantJson) emit(withCompleteness(corePath(fns, cg, fn, eff), pcomp));
     else {
       // The accepted 0.11 default change (the human chain replaced JSON as the no-flag output) gets a
       // ONE-line stderr breadcrumb, so a pre-0.11 pipeline that broke on the new default is pointed at
       // --json rather than left guessing. stderr only — stdout stays the human chain; --json untouched.
       console.error("candor-ts-query: tip — `--json` selects the machine-readable path shape (the default before 0.11)");
-      renderPathHuman(fns, cg, fn, eff);
+      // The note goes on STDOUT with the answer it qualifies, like every other verb here: a caveat on the
+      // other stream is one `2>/dev/null` from gone. `renderPathHuman` takes the hedge flag so its two
+      // determined-negative sentences ("does not perform", "not statically traceable") can withdraw.
+      incompleteAnswerNote(pcomp, PATH_SOWHAT, PATH_TAIL);
+      renderPathHuman(fns, cg, fn, eff, mustHedge(pcomp));
     }
     break;
   }
@@ -1847,7 +2023,16 @@ switch (cmd) {
       emitZeroRuleCaveat("fix-gate", policyFile, fgComp);
       process.exit(fgUnan.length || fgComp.unreadable.length ? (strict ? 2 : 0) : 0);
     }
-    emit(advisoryAnswer(fgr, fgUnan, fgComp.judgedNothing, fgComp.unreadable, fgComp.noManifest));
+    // ⟨0.32⟩ the classes the producer never opened, under the SAME condition the gate applies (only a
+    // `deny`/`pure` rule's answer depends on code outside the scan's scope), computed ONCE and handed to
+    // both the document and the exit below so the two cannot disagree about a run.
+    const fgUnread = fgpol.deny.length ? (fgComp.unread ?? []) : [];
+    // ⟨0.30⟩/⟨0.32⟩ THE TWO SCOPE CAUSES NOW REACH THE DOCUMENT, not just the exit. MEASURED before this
+    // argument existed: over a report carrying `outOfScope`, this verb printed `{"ok": true, "remedies":
+    // []}` AT EXIT 2 — the exit obeyed §3.2's "never MORE certain than the gate" while the document it
+    // printed certified. The exit expression below is unchanged for `outOfScope` and gains the ⟨0.32⟩ arm.
+    emit(advisoryAnswer(fgr, fgUnan, fgComp.judgedNothing, fgComp.unreadable, fgComp.noManifest,
+                        fgComp.outOfScope ?? [], fgUnread));
     // ⟨0.28⟩ `unreadable` joins the `--strict` exit-2 trigger (SPEC §3.2's pessimism relation): `gate
     // --report` REFUSES over a corrupt member — measured, exit 2 — so exiting 0/1 here claimed this verb
     // got FURTHER than the gate on identical bytes. The unreadable note above already SAID the exit was
@@ -1857,7 +2042,9 @@ switch (cmd) {
     // and "THE SAME RULE BINDS EVERY ADVISORY VERB THAT ANSWERS `ok` — `unverified`, `fix-gate`, and any
     // later sibling". ⟨0.30⟩ moved the gate to exit 2 on this cause and left these verbs certifying:
     // MEASURED, `gate --report` exited 2 while this printed a clean answer at exit 0 over the same bytes.
-    process.exit(fgUnan.length || fgComp.unreadable.length || fgComp.outOfScope?.length || fgr.unevaluated?.length ? (strict ? 2 : 0) : (strict && !fgr.ok ? 1 : 0));
+    // ⟨0.32⟩ …and the class nothing OPENED, for the same MUST: `gate --report` exits 2 over it, so a verb
+    // that answered 0 on the same bytes would have got FURTHER than the gate.
+    process.exit(fgUnan.length || fgComp.unreadable.length || fgComp.outOfScope?.length || fgUnread.length || fgr.unevaluated?.length ? (strict ? 2 : 0) : (strict && !fgr.ok ? 1 : 0));
     break; // unreachable
   }
   case "unverified": {
@@ -1918,12 +2105,17 @@ switch (cmd) {
       emitZeroRuleCaveat("unverified", policyFile, uComp);
       process.exit(uUnan.length || uComp.unreadable.length ? (strict ? 2 : 0) : 0);
     }
-    emit(advisoryAnswer(r, uUnan, uComp.judgedNothing, uComp.unreadable, uComp.noManifest));
+    // ⟨0.30⟩/⟨0.32⟩ the two scope causes, in the document as well as the exit — see the fix-gate site for
+    // the measurement (`{"ok": true, "unverified": []}` at exit 2 over a report carrying `outOfScope`).
+    const uUnread = upol.deny.length ? (uComp.unread ?? []) : [];
+    emit(advisoryAnswer(r, uUnan, uComp.judgedNothing, uComp.unreadable, uComp.noManifest,
+                        uComp.outOfScope ?? [], uUnread));
     // ⟨0.28⟩ `unreadable` joins the `--strict` exit-2 trigger — see fix-gate above. Measured on this verb
     // before the fix: over one good report plus one unparsable sibling, `gate --report` exited 2 and
     // `unverified --strict` exited 0 — and `--strict` is how CI consumes it.
     // ⟨0.30⟩ the peek's findings too — see the fix-gate exit above for the ⟨0.24⟩ MUST this satisfies.
-    process.exit(uUnan.length || uComp.unreadable.length || uComp.outOfScope?.length || r.unevaluated?.length ? (strict ? 2 : 0) : (strict && !r.ok ? 1 : 0));
+    // ⟨0.32⟩ …and the class nothing OPENED — see the fix-gate exit above.
+    process.exit(uUnan.length || uComp.unreadable.length || uComp.outOfScope?.length || uUnread.length || r.unevaluated?.length ? (strict ? 2 : 0) : (strict && !r.ok ? 1 : 0));
     break; // unreachable
   }
   case "gate": {
@@ -2044,6 +2236,18 @@ switch (cmd) {
     // human channel simply did not show it.
     for (const u of gunevaluated) console.error(`candor-ts: gate: ${u.why}`);
     const g = loadGateReport(prefix);
+    // ⟨0.32⟩ DOES THIS POLICY'S ANSWER DEPEND ON THE CODE THE PRODUCER LEFT UNREAD? — the ONE place that
+    // condition is applied on this route (the rule itself is stated at the reading site in
+    // query-core.mjs's `loadGateReport`). `deny` is the rule vector that carries `pure` too;
+    // `allow`/`forbid`/`only` live in their own, and none of them is answered from code OUTSIDE the scan's
+    // scope, so refusing them for want of a peek would be an over-charge — the same short-circuit
+    // scan.mjs's peek applies to the same question.
+    //
+    // APPLIED TO THE VALUE, not repeated at the exit arm, and that is deliberate: this list feeds BOTH
+    // `gincomplete` (hence `ok`/`incomplete` in the verdict document) and the exit code below, so a
+    // condition stated at only one of them lets the two disagree — a document reading `ok: false,
+    // incomplete: true` beside exit 0. candor-rust's copy of this rung had exactly that split.
+    const gunread = gpol.deny.length ? g.unread : [];
     // ANY report under the locator that did not load cleanly REFUSES THE WHOLE GATE — not just the case
     // where they ALL failed. The old guard was `functions.length === 0 && hardFail`, i.e. it fired only
     // when nothing survived anywhere, so a multi-report prefix with ONE clean sibling and one truncated
@@ -2115,12 +2319,16 @@ switch (cmd) {
     // THE REPORT ROUTE'S `(S, D)`: `S` = each entry's `inferred`, verbatim; `D` = the reason classes
     // resolved over the entries' OWN `calls` edges (the sidecar is NOT passed — that is the MUST NOT), by
     // the SAME resolution the scan gate and `unverified --class` use. `netClass` verbatim, likewise.
-    const gnet = reportNetClasses(g.functions, { authoritative: true });
-    const gacc = resolveReasonClasses(g.functions, {});
+    // ⟨0.32⟩ THE UNIT IDENTITY FOR A MULTI-REPORT PREFIX (SPEC §2.2). Built ONCE here and handed to every
+    // accumulator, so the gate, its refusal and its verdict all key the same way — a private copy is how
+    // the advisory verbs came to disagree with the gate before.
+    const gunits = reportUnits(g.functions);
+    const gnet = reportNetClasses(g.functions, { authoritative: true, units: gunits });
+    const gacc = resolveReasonClasses(g.functions, {}, gunits);
     // THE THIRD REFUSAL — the only one that depends on the REPORT rather than the policy alone, and the
     // only one whose GRANULARITY is per (rule, function). See unanswerableScoped for why it is minimal, and
     // why it no longer short-circuits.
-    const { unevaluated: gscoped, withhold: gwithhold } = unanswerableScoped(gpol, g.functions, gacc, gnet);
+    const { unevaluated: gscoped, withhold: gwithhold } = unanswerableScoped(gpol, g.functions, gacc, gnet, gunits);
     for (const u of gscoped) { console.error(`candor-ts: gate: ${u.why}`); gunevaluated.push(u); }
     // ONE matcher for both routes into the gate (SPEC §6.2: "THE GATE AND THE DISCLOSURE MUST APPLY THE
     // SAME RULE, AND SHOULD SHARE THE SAME CODE"). `scan --policy` and this verb both land in
@@ -2133,7 +2341,7 @@ switch (cmd) {
     // matcher would be the very evaluation-on-partial-evidence they are unanswerable FOR — `allow` would
     // fire AS-EFF-008 "no visible literal" on every report entry whose surface the wire does not carry.
     const gviol = evaluatePolicy(gwp.answerable,
-                                 g.functions, {}, new Map(), new Set(), gnet, gwithhold);
+                                 g.functions, {}, new Map(), new Set(), gnet, gwithhold, gunits);
     // Route the human output exactly as a scan does: to stderr whenever stdout carries the verdict
     // document, so `candor-ts-query gate … --json | jq` sees pure JSON.
     const gsay = (json || gateJsonPath === "-") ? (l) => console.error(l) : (l) => console.log(l);
@@ -2156,7 +2364,10 @@ switch (cmd) {
     // peek's findings, which is what makes §3.1 byte-equality hold here by construction rather than by two
     // authors agreeing. ABSENT is not empty: a report produced with no policy was never asked.
     const gscope = g.outOfScope ?? [];
-    const gincomplete = g.unanalyzed.length > 0 || gscope.length > 0;
+    // ⟨0.32⟩ the THIRD cause, read off `excluded[].peeked` — code the PRODUCER never opened. Distinct from
+    // the ⟨0.30⟩ one above: that is "the peek looked and found the effect you deny", this is "nothing
+    // looked at all", and the two want different repairs.
+    const gincomplete = g.unanalyzed.length > 0 || gscope.length > 0 || gunread.length > 0;
     // The verdict document — the SAME builder shape scan.mjs writes, field for field and in the same key
     // order, because §3.1 ⟨0.24⟩ makes byte-equality with `scan --policy`'s `--gate-json` the acceptance
     // test. `analyzed.count`, `incomplete`/`unanalyzed` and the ⟨0.15⟩ coverage advisory all come off the
@@ -2170,7 +2381,17 @@ switch (cmd) {
     const gverdictObj = { spec: SPEC_VERSION, ok: gviol.length === 0 && !gincomplete,
                           analyzed: { count: g.analyzed } };
     if (gvocab) gverdictObj.policyVocabulary = gvocab;
-    gverdictObj.violations = gviol;
+    // ⟨0.31⟩ the partner declaration that moved the producer's classification, READ OFF THE REPORT —
+    // never recomputed here. This route has no target to anchor `net-partner` at, and the note above
+    // says why recomputing would be wrong anyway: `netClass` is read verbatim off the wire, so
+    // re-classifying through THIS machine's config is the re-derivation §3.1 forbids and would make the
+    // verdict depend on the consumer's CWD. The producer recorded which of its declared partners
+    // actually participated; both routes copy that one record, and byte-equality holds by construction.
+    // Same position as the scan route puts it, for the same reason as `policyVocabulary` above.
+    if (g.netPartners?.length) gverdictObj.netPartners = g.netPartners;
+    // ⟨0.32⟩ SPEC §2 — the sort key includes the unit identity. See `sortViolations`; the SAME call
+    // is made on the scan route, because §3.1 makes the two documents byte-equal.
+    gverdictObj.violations = sortViolations(gviol);
     if (gunevaluated.length) gverdictObj.unevaluated = gunevaluated;
     // ⟨0.27⟩ SPEC §4 `zeroMatch` — the same list the stderr lines above carry, in the machine channel,
     // in the same position the scan route puts it (§3.1's byte-equality MUST binds the two documents).
@@ -2204,9 +2425,15 @@ switch (cmd) {
       // ⟨0.30⟩ NAME THE CAUSE THAT ACTUALLY FIRED. Two causes reach this exit now, and a message that
       // always says "could not analyze" would report the wrong repair for the scope one — the operator
       // would go looking for a parse failure that is not there.
+      // ⟨0.32⟩ …and a THIRD, last in the same order scan.mjs uses (`unanalyzed` → `outOfScope` → unread),
+      // so a report that trips two of them names the same cause on both routes. Its message differs from
+      // the `outOfScope` one because the repair does: that one wants a scan whose SELECTOR reaches the
+      // code, this one wants a scan that was ASKED the question at all.
       const why = g.unanalyzed.length
         ? `gate NOT certified — the report declares ${g.unanalyzed.length} unit(s) candor could not analyze; a gate cannot be green over unanalyzed code`
-        : `gate NOT certified — the report names ${gscope.length} function(s) OUTSIDE the scan's scope performing an effect this policy denies; the gate did not judge them, so the verdict is incomplete rather than a pass`;
+        : gscope.length
+        ? `gate NOT certified — the report names ${gscope.length} function(s) OUTSIDE the scan's scope performing an effect this policy denies; the gate did not judge them, so the verdict is incomplete rather than a pass`
+        : `gate NOT certified — the report says the scan did not READ ${gunread.join(", ")}. Their effects are absent because nothing looked, not because there are none, so the verdict is INCOMPLETE rather than a pass. Re-scan the sources with this policy (candor-ts <dir> --policy <file>) — a scan that was never asked cannot certify what it never opened`;
       console.error(`candor-ts: ${why}`);
       // The INCOMPLETE verdict is a JUDGEMENT, not a refusal: it names what was analyzed and what was not,
       // and §3.1 makes byte-equality with `scan --policy`'s document the acceptance test for exactly it.