candor-ts 0.32.1 → 0.33.1

package/AGENTS.md

@@ -21,7 +21,7 @@ the TypeScript-specific production + query surface.
 > **Already installed? Report the version and ask before upgrading — before you scan.** If this
 > project already has candor (a `.candor/` report directory, or `candor-ts` reachable via `npx`/a
 > global install), do this *first*: run `npx -y candor-ts --version` (offline) and **tell the user
-> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.32)."*
+> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.33)."*
 > On a build too old for the flag, read `candor.version` / `candor.spec` from an existing
 > `.candor/report*.json`, or `npm ls -g candor-ts`.
 >

package/README.md

@@ -198,7 +198,7 @@ pure-vs-Unknown ruling (PART 16) — the engines must answer identically, on eve
 | A call resolving to a *type* (function-typed field/param) → `Unknown`, never silent-pure | SPEC §4 |
 | Unmatched external calls contribute nothing (curated-classifier caveat) | SEMANTICS §8 C1 |
 | The literal surfaces `hosts`/`cmds`/`paths`/`tables`, literal-read only | SPEC §2 |
-| `{ candor: { version, toolchain, spec: "0.32" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
+| `{ candor: { version, toolchain, spec: "0.33" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
 | Call-graph sidecar with **every** analyzed function a key | SPEC §2.2 |
 | The gate: AS-EFF-006 / 008 / 009, loud on an unreadable policy | SPEC §6.2 |
 
@@ -216,7 +216,7 @@ read the Rust source".
 
 ## Status
 
-0.30.0, speaking candor-spec 0.32: the analysis core, the gate (`--policy` / `--gate-json` /
+0.30.0, speaking candor-spec 0.33: the analysis core, the gate (`--policy` / `--gate-json` /
 `.candor/config`), the full §3.1 query surface (including `containment`, `blindspots`, the
 `--include-unknown` dispatch frontier, and ⟨0.24⟩ `gate --report` — the gate applied to an EXISTING
 report, byte-equivalent to `scan --policy`'s verdict), the MCP server, the LSP server, and the watch loop are

package/lsp.mjs

@@ -402,11 +402,19 @@ const zeroRulePolicyWarn = (what) =>
  * same reason ("there is no line to pin it to"); the activity overlay's line-0 diagnostic is not a
  * counter-example, because its record NAMES the edited file and this one names no file in the workspace.
  */
-function discloseIncompleteness(unanalyzed, outOfScope, unread) {
+// `certainViolation`: SPEC §3.1's precedence (`query.mjs`'s `gate --report`: violation (1) > refusal (2) >
+// incomplete (2)) means a policy violation ELSEWHERE in this same report makes the real exit 1, not the 2
+// this function used to assert unconditionally. Measured: a report with an unread file AND a certain `Fs`
+// violation exits 1 over `gate --report` — the incompleteness is still real and still unjudged, but "exits
+// 2 (INCOMPLETE)" / "CI exits 2 over these bytes" is a wrong, checkable claim in exactly that case. Two
+// fixtures with the identical unread-file cause differ only in whether a violation coexists, and only the
+// violation-free one made this text true.
+function discloseIncompleteness(unanalyzed, outOfScope, unread, unaskedRules, certainViolation) {
   const causes = [];
-  // The CLI's order (`unanalyzed` → `outOfScope` → `unread`), so a report tripping two of them reads the
-  // same way here as it does in CI. The repairs genuinely differ — a parse to fix, a selector that
-  // REACHES the code, a scan that was ASKED the question — so each cause carries its own.
+  // The CLI's order (`unanalyzed` → `outOfScope` → `unread` → `unaskedRules`), so a report tripping two
+  // of them reads the same way here as it does in CI. The repairs genuinely differ — a parse to fix, a
+  // selector that REACHES the code, a scan that was ASKED the question, a scan asked the SAME question —
+  // so each cause carries its own.
   if (unanalyzed.length)
     causes.push(`the report DECLARES ${unanalyzed.length} unit(s) candor could not analyze, and a gate `
       + `cannot be green over unanalyzed code:\n`
@@ -421,16 +429,39 @@ function discloseIncompleteness(unanalyzed, outOfScope, unread) {
       + `report because nothing looked, not because there are none, so nothing in them can be squiggled `
       + `here — re-scan the sources WITH this policy (candor-ts <dir> --policy <file>); a scan that was `
       + `never asked cannot certify what it never opened.`);
+  // ⟨0.33⟩ SPEC §2 ⟨0.33⟩ — a class the peek DID read, but under a deny set that does not cover this
+  // policy's own. Distinct from `unread` above: that is "nothing looked", this is "something looked, for
+  // a narrower question than the one this editor is asking now" — the peek is bounded to the PRODUCER's
+  // denied effects (⟨0.29⟩), so an empty finding there answers nothing about a rule it was never put.
+  if (unaskedRules?.length)
+    causes.push(`this report's peek was bounded by the deny set its producing scan held, and that set `
+      + `does not cover ${unaskedRules.length} rule(s) of this policy: ${unaskedRules.join(", ")}. The `
+      + `excluded files it reports as read were searched for OTHER effects, so nothing in them can be `
+      + `squiggled here — re-run the producing scan under THE SAME policy this editor is applying `
+      + `(candor-ts <dir> --policy <file>), not merely under a policy.`);
   if (!causes.length) return;
+  // ⟨lsp-precedence⟩ the exit-code claim is conditional on whether a certain violation ALSO fires: if one
+  // does, Lemma 2 makes it dominate (exit 1), and the incompleteness below is true but not what CI is red
+  // over. See `certainViolation`'s definition above.
+  const exitClaim = certainViolation
+    ? `a certain policy violation ELSEWHERE in this report makes \`gate --report\` over the same bytes exit `
+      + `1 — SPEC §3.1's precedence has a firing rule dominate a refusal, so CI is red on THAT, not on this. `
+      + `The incompleteness below is still real and still unjudged; it is just not what the exit code names`
+    : `\`gate --report\` over the same bytes exits 2 (INCOMPLETE), so the squiggles in this editor are NOT `
+      + `the whole verdict`;
+  const briefClaim = certainViolation
+    ? `candor gate: a certain violation elsewhere in this report already makes CI exit 1 over these bytes — `
+      + `but this report ALSO has unjudged code (see the candor log); fixing the violation alone will not `
+      + `make it complete.`
+    : `candor gate: INCOMPLETE — this report cannot support a green verdict (CI exits 2 over these bytes). `
+      + `See the candor log for what went unjudged and how to fix it.`;
   warnLoudOnce(
-    `candor-lsp: this report cannot support a GREEN gate — \`gate --report\` over the same bytes exits 2 `
-    + `(INCOMPLETE), so the squiggles in this editor are NOT the whole verdict:\n`
+    `candor-lsp: this report cannot support a GREEN gate — ${exitClaim}:\n`
     + causes.map((c) => `    · ${c}`).join("\n")
     + `\n  NO diagnostic can be drawn for any of the above: the code it names is not in the report, so it `
     + `has no line in this editor to sit on. Its ABSENCE from the squiggles is the incompleteness itself, `
     + `not an all-clear.`,
-    `candor gate: INCOMPLETE — this report cannot support a green verdict (CI exits 2 over these bytes). `
-    + `See the candor log for what went unjudged and how to fix it.`);
+    briefClaim);
 }
 
 function diagnosticsFor(docPath) {
@@ -470,15 +501,29 @@ function diagnosticsFor(docPath) {
     warnOnce(`candor-lsp: ${dpol.ignored.length} line(s) of the configured policy were DROPPED by the `
       + `parse, so the gate you are seeing is SMALLER than the gate that was written (SPEC §6.2 ⟨0.28⟩):\n`
       + dpol.ignored.map((g) => `    line ${g.line}: ${g.text}`).join("\n"));
-  // ⟨0.21⟩/⟨0.30⟩/⟨0.32⟩ …AND THE CAUSES THAT MAKE THE GATE ITSELF INCOMPLETE — see
+  // ⟨0.21⟩/⟨0.30⟩/⟨0.32⟩/⟨0.33⟩ …AND THE CAUSES THAT MAKE THE GATE ITSELF INCOMPLETE — see
   // `discloseIncompleteness` for the mechanism and the channel argument. Read through the SAME
   // `reportCompleteness` the CLI gate, `fix-gate`, `unverified` and the MCP tools read, so the editor
-  // cannot come to a different view of one report from the CI job that judges the same commit. The
-  // `unread` condition is applied HERE, to the value, for the reason the CLI states at its own call
-  // site: one list, one condition, so two consumers of it cannot disagree about a run.
-  const dcomp = Q.reportCompleteness(reportPrefix);
+  // cannot come to a different view of one report from the CI job that judges the same commit. `dpol.deny`
+  // rides along so `reportUnaskedRules` can compare THIS policy's own rules against the report's
+  // `scannedUnder` — the identical value the CLI reads for the same bytes (SPEC §2 ⟨0.33⟩). The `unread`
+  // condition is applied HERE, to the value, for the reason the CLI states at its own call site: one
+  // list, one condition, so two consumers of it cannot disagree about a run.
+  const dcomp = Q.reportCompleteness(reportPrefix, dpol.deny);
+  // Cheap, side-effect-free pre-check for `discloseIncompleteness`'s exit-code wording (see its own
+  // comment): does THIS report already carry a certain violation, over the WHOLE report the way
+  // `gate --report` reads it, not just this one document? A redundant pass over an already-loaded report
+  // — the real one runs again below, where its `dunevaluated`/`violations` are also needed for the
+  // diagnostics themselves and for OTHER `warnOnce` lines whose relative order this must not disturb.
+  const dwp0 = wholePolicyUnanswerable(dpol, "the editor's report route");
+  const dunits0 = reportUnits(fns);
+  const dnet0 = reportNetClasses(fns, { authoritative: true, units: dunits0 });
+  const { withhold: dwithhold0 } = unanswerableScoped(dpol, fns,
+    resolveReasonClasses(fns, Q.loadCallgraph(reportPrefix), dunits0), dnet0, dunits0);
+  const certainViolation = evaluatePolicy(dwp0.answerable, fns, Q.loadCallgraph(reportPrefix),
+    new Map(), new Set(), dnet0, dwithhold0, dunits0).length > 0;
   discloseIncompleteness(dcomp.unanalyzed ?? [], dcomp.outOfScope ?? [],
-                         dpol.deny.length ? (dcomp.unread ?? []) : []);
+                         dpol.deny.length ? (dcomp.unread ?? []) : [], dcomp.unaskedRules ?? [], certainViolation);
   // ⟨0.24⟩ THE ANSWERABILITY WITHHOLD, which this surface ran WITHOUT — `evaluatePolicy` was called with no
   // `withhold` predicate and the DEFAULT netClass mode, so both directions of the §3.1 harm were live in the
   // editor. Measured against the CLI on one report and one policy: `deny Unknown[reflect]` drew NO squiggle
@@ -651,6 +696,18 @@ function runWhatif(a) {
       + `${zcallers.length} caller(s) would inherit ${a.effect})`);
     return { unevaluated: policyZeroRules(activePolicyPath ?? "(policy)").unevaluated };
   }
+  // PART 70 — this command returned the RAW `r` unconditionally, so the shipped editor experience
+  // (VS Code + JetBrains both bundle this server) certified `ok` over bytes `gate --report` refuses on:
+  // the ⟨0.30⟩/⟨0.32⟩/⟨0.33⟩ scope causes never reached this route at all. Read off the SAME
+  // `reportCompleteness` the CLI whatif and `candor_whatif`/`diagnosticsFor` use, `unread` gated on this
+  // call's OWN `deny`/`pure` rules exactly as those two gate it — so the three channels cannot disagree
+  // about one report. `discloseIncompleteness` is the SAME log+showMessage channel `diagnosticsFor`
+  // already uses for the standing gate squiggles (dedup on the message text), so a report already
+  // disclosed there says nothing new here, and one not yet seen surfaces on the FIRST channel that asks.
+  const wcomp = Q.reportCompleteness(reportPrefix, wpol?.deny ?? []);
+  const wUnread = wpol?.deny?.length ? (wcomp.unread ?? []) : [];
+  const wUnasked = wcomp.unaskedRules ?? [];
+  discloseIncompleteness(wcomp.unanalyzed ?? [], wcomp.outOfScope ?? [], wUnread, wUnasked);
   const callers = r.affected.filter((f) => !r.of.includes(f));   // affected minus the target(s) themselves
   const rules = [...new Set(r.violations.map((v) => v.rule))];
   // ⟨0.24⟩ THE EDITOR IS A CHANNEL THIS VERB ANSWERS ON, so the `conditional` has to reach it or this
@@ -685,7 +742,13 @@ function runWhatif(a) {
     }]);
     publishDiagnostics(a.uri);
   }
-  return r;   // the raw whatif result rides back as the executeCommand result (a thick client can render it)
+  // PART 70 — the executeCommand RESULT is the document a thick client renders, so it takes the SAME
+  // `ok`-withdrawal the CLI and `candor_whatif` apply: `incomplete: true` in its place, `affected`/
+  // `violations` (and the one-liner/diagnostic above, built off the raw `r`) unchanged. A no-op on a
+  // complete report — byte-identical to the pre-fix `return r` — so every fixture without a scope cause
+  // is untouched.
+  return Q.advisoryAnswer(r, wcomp.unanalyzed, wcomp.judgedNothing, wcomp.unreadable, wcomp.noManifest,
+                          wcomp.outOfScope ?? [], wUnread, wUnasked);
 }
 
 // The candor.fix command: the SAME query-core `fix` the CLI (`query.mjs fix`) and MCP (`candor_fix`) run —

package/mcp.mjs

@@ -345,7 +345,7 @@ const TOOLS = {
     run: (_a, p) => nestWithCaveat(p, "modules", () => Q.map(loadReportLoud(p))),
   },
   candor_whatif: {
-    description: "Hypothetically add `effect` to `fn` and report the blast radius; with `policy`, also the deny-rule violations it would cause. Pre-edit gate check.",
+    description: "Hypothetically add `effect` to `fn` and report the blast radius; with `policy`, also the deny-rule violations it would cause. Pre-edit gate check. ALWAYS CHECK for the presence of `ok`, never just its value: over a report this route cannot fully evaluate, `ok` is ABSENT and `{incomplete:true, ...}` takes its place — `affected`/`violations` still ship (a partial answer beats a refusal; this tool is consulted BEFORE an edit), but neither `true` nor `false` is a claim the input licenses. The causes are the same ones `candor_gate`/`candor_unverified` disclose: `unanalyzed` (candor could not read a file of the target's own code), `outOfScope` (the peek found a denied effect outside the scan's reach), `unread` (a class the scan never opened — gated on this call's OWN `deny`/`pure` rules, since only those depend on code outside the scan's scope), and `unaskedRules` (a class something DID open, but under a narrower deny set than this policy's own).",
     schema: { type: "object", properties: { fn: { type: "string" }, effect: { type: "string" }, policy: { type: "string", description: "path to a CANDOR_POLICY file (optional)" }, ...reportArg }, required: ["fn", "effect"] },
     run: (a, p) => {
       // A GIVEN policy path is always read (confined, fail-closed) — the old `existsSync` guard made a
@@ -359,7 +359,17 @@ const TOOLS = {
       // blast radius it qualifies are withheld for the caveat document (see `zeroRuleCaveat`). A policy
       // that is NOT configured stays untouched: that is the honest way to say "I am not gating".
       if (policyAskedNothing(pol)) return zeroRuleCaveat(a.policy, p);
-      return r;
+      // PART 70 — this tool returned the RAW `r` unconditionally, so the agent-facing surface certified
+      // `ok` over bytes `candor_gate`/`gate --report` refuse on: the ⟨0.30⟩/⟨0.32⟩/⟨0.33⟩ scope causes
+      // never reached it at all (measured RED four ways: outOfScope, unread class, cross-policy, and the
+      // pre-existing `unanalyzed` path this tool DID carry via `r` alone — none of them withdrew `ok`).
+      // Same `Q.advisoryAnswer` the CLI and `candor_unverified` apply, off the SAME `reportCompleteness`
+      // reader, so this channel cannot drift from the other two.
+      const wcomp = Q.reportCompleteness(p, pol?.deny ?? []);
+      const wUnread = pol?.deny?.length ? (wcomp.unread ?? []) : [];
+      const wUnasked = wcomp.unaskedRules ?? [];
+      return Q.advisoryAnswer(r, wcomp.unanalyzed, wcomp.judgedNothing, wcomp.unreadable, wcomp.noManifest,
+                              wcomp.outOfScope ?? [], wUnread, wUnasked);
     },
   },
   candor_fix: {
@@ -391,7 +401,7 @@ const TOOLS = {
     },
   },
   candor_gate: {
-    description: "The policy verdict over this report: { ok, violations:[{rule, fn, effects, detail}] } — 'would this repo pass its architecture gate?'. Uses `policy` if given, else the repo's checked-in .candor/config policy (spec §3.4). ALWAYS CHECK `ok`, never the length of `violations`: a rule whose narrowing evidence the report does not carry is NOT EVALUATED, and then the result is `{ ok:false, refused:true, reason, unevaluated:[{rule, why}] }` WITH NO `violations` KEY — an absent key, not an empty list, because the gate is making no claim there. `unevaluated` also rides a firing verdict (a certain violation dominates a refusal). `incomplete:true` means the gate CANNOT be green, and the key beside it says which of the three causes fired: `unanalyzed` (the report declares code candor could not analyze), `outOfScope` (the producer's peek NAMED a function outside the scan's scope performing an effect this policy denies), or `unread` (a class the producing scan never OPENED — its effects are absent because nothing looked, not because there are none; re-scan those sources WITH this policy). Computed from the report — the engine's own --gate-json run is the authoritative CI form: it additionally fails an allow rule whose literal surface is INCOMPLETE (a masked/invisible endpoint), which is not a report field, so a green here can still be red in CI.",
+    description: "The policy verdict over this report: { ok, violations:[{rule, fn, effects, detail}] } — 'would this repo pass its architecture gate?'. Uses `policy` if given, else the repo's checked-in .candor/config policy (spec §3.4). ALWAYS CHECK `ok`, never the length of `violations`: a rule whose narrowing evidence the report does not carry is NOT EVALUATED, and then the result is `{ ok:false, refused:true, reason, unevaluated:[{rule, why}] }` WITH NO `violations` KEY — an absent key, not an empty list, because the gate is making no claim there. `unevaluated` also rides a firing verdict (a certain violation dominates a refusal). `incomplete:true` means the gate CANNOT be green, and the key beside it says which of the four causes fired: `unanalyzed` (the report declares code candor could not analyze), `outOfScope` (the producer's peek NAMED a function outside the scan's scope performing an effect this policy denies), `unread` (a class the producing scan never OPENED — its effects are absent because nothing looked, not because there are none; re-scan those sources WITH this policy), or `unaskedRules` (a class the producing scan's peek DID read, but under a deny set that does not cover this one — re-scan under THE SAME policy this tool is applying, not merely under a policy). Computed from the report — the engine's own --gate-json run is the authoritative CI form: it additionally fails an allow rule whose literal surface is INCOMPLETE (a masked/invisible endpoint), which is not a report field, so a green here can still be red in CI.",
     schema: { type: "object", properties: { policy: { type: "string", description: "path to a §6.2 policy file (optional; defaults to the repo's .candor/config `policy`)" }, ...reportArg }, required: [] },
     run: (a, p) => {
       let text, polPath = a.policy ?? null;
@@ -428,7 +438,10 @@ const TOOLS = {
       // judged-nothing, and — newly — `unanalyzed`) could disagree with each other on a file another
       // process rewrites between them.
       const pol = policyOrThrow(text, polPath);
-      const g = Q.loadGateReport(p);
+      // ⟨0.33⟩ this tool's OWN rules ride along so `loadGateReport` can compare them against the gated
+      // report's `scannedUnder` (SPEC §2 ⟨0.33⟩) — the identical computation `gate --report` makes, off
+      // the same reader, so this agent-facing route cannot certify what the CLI would refuse.
+      const g = Q.loadGateReport(p, pol.deny);
       if (g.hardFail)
         throw new Error((g.corrupt.length
             ? `the report at prefix \`${clip(p)}\` has ${g.corrupt.length} present-but-unparseable §2 key(s) — a key that is THERE but of the wrong shape is corrupt input, not an empty one (SPEC §2 ⟨0.24⟩); coercing it to its empty value would turn corruption into a purity claim: ${g.corrupt.join("; ")}. `
@@ -472,9 +485,15 @@ const TOOLS = {
       //     effects are absent from `functions` because nothing looked. Decided by the policy applied NOW
       //     (only a `deny`/`pure` rule's answer depends on code outside the scan's scope), which is the
       //     same condition both CLI routes apply, from the same value, once.
+      //   · `unaskedRules` (⟨0.33⟩) — a class the producer's peek DID read, but under a deny set that
+      //     does not cover this policy's own. Read straight off `g` (computed by `loadGateReport` from
+      //     the `pol.deny` handed to it above), never re-derived: the identical value the CLI's
+      //     `gate --report` reads for the same bytes.
       const gscope = g.outOfScope ?? [];
       const gunread = pol.deny.length ? g.unread : [];
-      const incomplete = g.unanalyzed.length > 0 || gscope.length > 0 || gunread.length > 0;
+      const gunasked = g.unaskedRules ?? [];
+      const incomplete = g.unanalyzed.length > 0 || gscope.length > 0 || gunread.length > 0
+                        || gunasked.length > 0;
       // ⟨0.24⟩ …and a report that JUDGED NOTHING is not an all-clear (SPEC §2's three-row table, bound to
       // every report-reading route by §3.1: "the obligation is on the reading, not on the route by which
       // the report arrived"). This tool is exactly such a route — it gates whatever `report` points at,
@@ -531,7 +550,8 @@ const TOOLS = {
         ? { incomplete: true,
             ...(g.unanalyzed.length ? { unanalyzed: g.unanalyzed } : {}),
             ...(gscope.length ? { outOfScope: gscope } : {}),
-            ...(gunread.length ? { unread: gunread } : {}) }
+            ...(gunread.length ? { unread: gunread } : {}),
+            ...(gunasked.length ? { unaskedRules: gunasked } : {}) }
         : {};
       // ⟨0.24⟩ PRECEDENCE (SPEC §3.1 `7271c69`/`4c79958`): violation (1) > refusal (2) > incomplete (2), and
       // the REFUSAL SHAPE is the one the CLI writes — `ok:false`, `refused:true`, and NO `violations` KEY AT
@@ -560,10 +580,12 @@ const TOOLS = {
                  + "over a report declaring code candor could NOT analyze, `ok` IS ABSENT and `{incomplete:true, "
                  + "unanalyzed}` takes its place — a function in an unanalyzed file is missing from the report "
                  + "entirely, so it cannot be enumerated as an unverified pass, and an empty array there is not "
-                 + "an all-clear (spec §3.2). `incomplete:true` also rides the two SCOPE causes, on the same "
+                 + "an all-clear (spec §3.2). `incomplete:true` also rides the three SCOPE causes, on the same "
                  + "terms as candor_gate: `outOfScope` (the producer's peek named a function outside the scan's "
-                 + "scope performing a denied effect) and `unread` (a class the producing scan never OPENED — "
-                 + "re-scan those sources WITH this policy). `ok` is ABSENT for a further reason too, and the entries that come "
+                 + "scope performing a denied effect), `unread` (a class the producing scan never OPENED — "
+                 + "re-scan those sources WITH this policy), and `unaskedRules` (a class the producing scan's "
+                 + "peek DID read, but under a deny set that does not cover this one — re-scan under THE SAME "
+                 + "policy this tool is applying, not merely under a policy). `ok` is ABSENT for a further reason too, and the entries that come "
                  + "with it are the sharpest ones: where the policy narrows on evidence this report does not carry, "
                  + "candor_gate REFUSES — and this verb then NAMES each function the gate could not judge, as "
                  + "`{fn, rule, why}` where `why` is THE MISSING EVIDENCE and never a derived class, plus the gate's "
@@ -588,8 +610,11 @@ const TOOLS = {
       // ⟨0.28⟩ …and the `analyzed.count: 0` cause on the same terms (SPEC §2), read through the SAME
       // `reportCompleteness` the CLI and the descriptive tools use — one reader, so the two channels
       // cannot disagree about which reports judged nothing.
-      const ucomp = Q.reportCompleteness(p);
       const upol = policyOrThrow(text, polPath);
+      // ⟨0.33⟩ this tool's OWN deny/pure rules ride along, computed before this call so
+      // `reportCompleteness` can compare them against the report's `scannedUnder` — the same reader
+      // `unverified --strict` and `fix-gate --strict` use on the CLI.
+      const ucomp = Q.reportCompleteness(p, upol.deny);
       // ⟨0.28⟩ the sharpest of the three: the verb whose job is "your green gate is not provably green"
       // answered `{ok: true, unverified: []}` over a policy that asked nothing. The empty list is withheld
       // for ⟨0.27⟩'s reason — a document that made no evaluation must not carry the finding key.
@@ -606,9 +631,12 @@ const TOOLS = {
       // only a `deny`/`pure` rule's answer depends on code outside the scan's scope, and `pure` rides
       // the `deny` vector, so this is `deny.length` rather than a search for the token.
       const uUnread = upol.deny.length ? (ucomp.unread ?? []) : [];
+      // ⟨0.33⟩ …and the FOURTH cause — computed by `reportCompleteness` above (structurally `[]` when
+      // `upol.deny` is empty), never re-derived here.
+      const uUnasked = ucomp.unaskedRules ?? [];
       return Q.advisoryAnswer(Q.unverified(loadReportLoud(p), upol, scopeMatches),
                               ucomp.unanalyzed, ucomp.judgedNothing, ucomp.unreadable, ucomp.noManifest,
-                              ucomp.outOfScope ?? [], uUnread);
+                              ucomp.outOfScope ?? [], uUnread, uUnasked);
     },
   },
   candor_containment: {
@@ -629,8 +657,14 @@ const TOOLS = {
       // authoritative empty {changes:[]}; the CLI exits 2 on the same miss) — but NOT --root-confined:
       // see resolveBaseline for the out-of-tree-baseline trust argument.
       const b = resolveBaseline(a.baseline);
+      // ⟨0.33⟩ …and the ⟨0.28⟩ manifest on the same terms, BOTH SIDES separately — the SAME
+      // `Q.gainsCompleteness` the sibling `candor_gains` tool below spreads, because `diff` rests on the
+      // identical two-report shape and fails the identical two ways (a short CURRENT `changes`, a soft
+      // BASELINE floor). MEASURED: this tool answered a real 3-function gain over a CURRENT report naming
+      // an unread exclusion class with no caveat at all — the CLI carried the same gap (query.mjs `diff`
+      // case) and is fixed alongside this. No human sees this channel, so the JSON key is the whole fix.
       return { baseline_version: Q.reportVersion(b) ?? "", engine_version: Q.reportVersion(p) ?? "",
-               ...Q.diff(loadReportLoud(p), loadReportLoud(b)) };
+               ...Q.diff(loadReportLoud(p), loadReportLoud(b)), ...Q.gainsCompleteness(p, b) };
     },
   },
   candor_gains: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "candor-ts",
-  "version": "0.32.1",
-  "description": "candor for TypeScript \u2014 per-function side effects, transitively, with a policy gate (candor-spec 0.32)",
+  "version": "0.33.1",
+  "description": "candor for TypeScript \u2014 per-function side effects, transitively, with a policy gate (candor-spec 0.33)",
   "type": "module",
   "dependencies": {
     "@types/node": "^25.9.2",

package/query-core.mjs

@@ -553,7 +553,7 @@ export function reportUnanalyzed(prefix) {
  * every run trains the reader to ignore it, the same reason ⟨0.15⟩ omits `coverage` when nothing is
  * uncovered.
  */
-export function reportCompleteness(prefix) {
+export function reportCompleteness(prefix, denyRules = []) {
   // `judgedNothing` is the PER-FILE list, not the ANDed boolean the gate asks: the disclosure names
   // WHICH report judged nothing, so a locator with one silent member among several still hedges — the
   // semantics rust and java pin, and a repair the reader can aim (that file, not "somewhere here").
@@ -574,6 +574,13 @@ export function reportCompleteness(prefix) {
            // this field directly for their EXIT code and apply the gate's own condition to it: only a
            // `deny`/`pure` rule's answer depends on code outside the scan's scope.
            unread: reportUnread(prefix),
+           // ⟨0.33⟩ …and the rules THIS CALLER'S policy holds that a peeked class's producer was never
+           // asked about (`reportUnaskedRules`) — the SAME arm shape as `unread` one line up, and bound
+           // by the identical ⟨0.24⟩ pessimism MUST. `denyRules` defaults to `[]`, which is the
+           // STRUCTURAL carve-out for every caller of this function that carries no policy at all (the
+           // majority — `show`/`where`/`callers`/`map`/`tour`/… never pass one), so this key is a silent
+           // no-op for them rather than a sixth call site to remember the condition at.
+           unaskedRules: reportUnaskedRules(prefix, denyRules),
            ...(() => {
              const o = reportOutOfScope(prefix);
              // A corrupt key rides `unreadable`, which is ALREADY an arm of the strict exit — so the
@@ -634,7 +641,12 @@ export function reportCompleteness(prefix) {
  */
 export const mustHedge = (c) => !!(c && (c.unanalyzed?.length || c.judgedNothing?.length
                                          || c.noManifest?.length || c.unreadable?.length
-                                         || c.outOfScope?.length || c.unread?.length));
+                                         || c.outOfScope?.length || c.unread?.length
+                                         // ⟨0.33⟩ a peek bounded by a deny set narrower than this
+                                         // caller's own — see `reportUnaskedRules`. Structurally `[]`
+                                         // for every caller (the majority) that never passes `denyRules`
+                                         // to `reportCompleteness`, so this arm is a no-op for them.
+                                         || c.unaskedRules?.length));
 
 /** ⟨0.30⟩ The peek's findings across the reports under a locator. Read leniently HERE (a malformed key is
  *  the gate's refusal to make, and this feeds a disclosure) but non-emptiness raises the same hedge the
@@ -689,6 +701,57 @@ export function reportUnread(prefix) {
   return [...out];
 }
 
+/**
+ * ⟨0.33⟩ THE ADVISORY TWIN of `loadGateReport`'s `scannedUnder` subset test — SPEC §2 ⟨0.33⟩'s "AND THE
+ * ADVISORY VERBS FOLLOW IT": the rules THIS caller's policy holds that a report's producer, under the
+ * SAME peek-was-bounded reasoning, was never asked about. One helper for the gate route and this one,
+ * deliberately, so the ⟨0.24⟩ pessimism relation (an advisory verb must never be LESS sensitive to
+ * incompleteness than the gate over the same bytes) cannot drift the way it already has three times in
+ * this family — `unanalyzed`, `outOfScope`, `excluded[].peeked` each reached `gate --report` before they
+ * reached `unverified`/`fix-gate`, and each time it was a NEW cause landing at one site and not its
+ * siblings.
+ *
+ * STRUCTURAL CARVE-OUT FIRST: `denyRules` empty means this caller's policy holds no `deny`/`pure` rule at
+ * all (an `allow`/`forbid`/`only`-only policy, or none) — an EMPTY canonical set, which is a subset of
+ * everything — so the per-report loop below is skipped rather than run to compute nothing. This is the
+ * same carve-out `loadGateReport` takes, and it is what keeps a policy-less verb like `tour` inert here:
+ * `reportCompleteness`'s default `denyRules = []` makes this function a no-op for every caller that never
+ * passes one.
+ *
+ * LENIENT, like `reportOutOfScope`/`reportUnread` beside it and for the same reason: a malformed
+ * `scannedUnder` is the GATE's refusal to make (`loadGateReport` reads the same bytes STRICTLY and NAMES
+ * the key in a refusal), and this feeds a disclosure rather than an exit code. A garbled or absent
+ * `scannedUnder` reads here as the EMPTY SET — the same fail-closed reading `loadGateReport` takes, just
+ * reached without a refusal document to carry it: this function may only ever be MORE cautious than
+ * silence, never less.
+ *
+ * PER REPORT, never over the union of a report set: `scannedUnder` and `peeked` are facts about ONE
+ * producing scan, so a locator naming a policy-scanned report beside a no-policy sibling must not let the
+ * first one's deny set answer for the second one's peeked classes. The per-file `theirs` set is built
+ * fresh for every file and never merged across them; only the resulting MISSING RULE STRINGS are unioned
+ * (deduplicated, code-point sorted) across a multi-report prefix, exactly as `loadGateReport` does.
+ */
+export function reportUnaskedRules(prefix, denyRules) {
+  const mine = denyRules?.length ? canonicalDenySet(denyRules) : [];
+  if (!mine.length) return [];
+  const files = (prefix.endsWith(".json") && fs.existsSync(prefix)) ? [prefix] : reportFilesAt(prefix);
+  const out = new Set();
+  for (const f of files) {
+    try {
+      const d = JSON.parse(fs.readFileSync(f, "utf8"));
+      const exc = Array.isArray(d?.excluded) ? d.excluded : [];
+      const peeked = exc.some((e) => e && typeof e === "object" && e.peeked === true
+                                     && e.judgedElsewhere !== true);
+      if (!peeked) continue;
+      const su = d?.scannedUnder;
+      const theirs = (su && typeof su === "object" && !Array.isArray(su) && Array.isArray(su.deny))
+        ? new Set(su.deny.filter((x) => typeof x === "string")) : new Set();
+      for (const r of mine) if (!theirs.has(r)) out.add(r);
+    } catch { /* unparseable TEXT is `unreadable`'s business, not this key's */ }
+  }
+  return [...out].sort(byCodePoint);
+}
+
 /**
  * ⟨0.28⟩ The disclosure KEYS, defined ONCE, for spreading into a verb's answer document — `{}` when there
  * is nothing to disclose, so `{ ...data, ...completenessFields(c) }` is byte-identical to `data` on a
@@ -795,10 +858,10 @@ export const absorbCompleteness = (a, b) => ({
  * that has no exit code for it to matter to.)
  */
 export function advisoryAnswer(body, unanalyzed, judgedNothing = [], unreadable = [], noManifest = [],
-                               outOfScope = [], unread = []) {
+                               outOfScope = [], unread = [], unaskedRules = []) {
   const unevaluated = body?.unevaluated;
   if (!unanalyzed?.length && !unevaluated?.length && !judgedNothing?.length && !unreadable?.length
-      && !noManifest?.length && !outOfScope?.length && !unread?.length)
+      && !noManifest?.length && !outOfScope?.length && !unread?.length && !unaskedRules?.length)
     return body;  // COMPLETE: unchanged, byte for byte, `ok` and all.
   const { ok, ...rest } = body;                          // eslint-disable-line no-unused-vars -- omitted BY DESIGN
   // The array of report paths, same key and same shape as `completenessFields` — ONE wire spelling for
@@ -809,18 +872,21 @@ export function advisoryAnswer(body, unanalyzed, judgedNothing = [], unreadable
   // never emitted a manifest cannot support it (row 3: *no manifest, no claim*).
   const judged = { ...(judgedNothing?.length ? { judgedNothing } : {}),
                    ...(noManifest?.length ? { noManifest } : {}) };
-  // ⟨0.30⟩/⟨0.32⟩ THE TWO SCOPE CAUSES — the ones the `--strict` exit has consulted since ⟨0.30⟩ while this
-  // document did not, which is the document/exit split in its worse direction. MEASURED 2026-08-24 on
-  // `fix-gate --strict` and `unverified --strict` over a report carrying `outOfScope`: BOTH printed
-  // `{"ok": true, …: []}` **at exit 2** — the exit was right and the document certified. A CI wrapper reads
-  // the exit; an agent reads the document, and the agent channel is the one that cannot ask a follow-up
-  // question. Same keys and same order as the gate's verdict document, so one consumer parses both.
+  // ⟨0.30⟩/⟨0.32⟩/⟨0.33⟩ THE THREE SCOPE CAUSES — the ones the `--strict` exit has consulted since ⟨0.30⟩
+  // while this document did not, which is the document/exit split in its worse direction. MEASURED
+  // 2026-08-24 on `fix-gate --strict` and `unverified --strict` over a report carrying `outOfScope`: BOTH
+  // printed `{"ok": true, …: []}` **at exit 2** — the exit was right and the document certified. A CI
+  // wrapper reads the exit; an agent reads the document, and the agent channel is the one that cannot ask
+  // a follow-up question. Same keys and same order as the gate's verdict document, so one consumer parses
+  // both. `unaskedRules` is the ⟨0.33⟩ fourth cause — a peeked class read under a deny set narrower than
+  // this caller's own — riding beside its two siblings for the identical reason.
   const scope = { ...(outOfScope?.length ? { outOfScope } : {}),
-                  ...(unread?.length ? { unread } : {}) };
+                  ...(unread?.length ? { unread } : {}),
+                  ...(unaskedRules?.length ? { unaskedRules } : {}) };
   // Key order matches the gate's verdict document: the finding, then `unevaluated`, then the manifest.
   if (unanalyzed?.length) return { ...rest, incomplete: true, unanalyzed, ...scope, ...judged };
   return (judgedNothing?.length || noManifest?.length || unreadable?.length
-          || outOfScope?.length || unread?.length)
+          || outOfScope?.length || unread?.length || unaskedRules?.length)
     ? { ...rest, incomplete: true, ...scope, ...judged } : rest;
 }
 
@@ -868,10 +934,20 @@ export function loadReport(prefix) {
  * refusal to name the key), entry-level and envelope-level; non-empty implies `hardFail`.
  * `judgedNothing` is the ⟨0.24⟩ reading of `analyzed.count` (see `claimsToHaveJudgedNothing`).
  */
-export function loadGateReport(prefix) {
+export function loadGateReport(prefix, denyRules = []) {
   const files = reportFilesAt(prefix);
   const functions = [], unanalyzed = [], cov = new Map(), corrupt = [], outOfScope = [], netPartners = [],
         unread = [];
+  // ⟨0.33⟩ THIS GATE'S OWN canonical deny/pure rules, computed ONCE rather than per report — a subset
+  // test against ten sibling reports must ask the identical question ten times, not re-derive it. Empty
+  // when this route carries no `deny`/`pure` rule at all (an `allow`/`forbid`/`only`-only policy, or no
+  // policy), which is the STRUCTURAL carve-out SPEC §2 ⟨0.33⟩ requires: an empty rule set is a subset of
+  // everything, so the per-file loop below contributes nothing to `unasked` however the report reads.
+  const mine = denyRules?.length ? canonicalDenySet(denyRules) : [];
+  // ⟨0.33⟩ the rules NO gated report's producer was asked about — a SET, because a multi-report prefix
+  // otherwise repeats one missing rule once per sibling. Deduplicated and code-point sorted at the return
+  // below, the same collation `unread`'s dedup and the verdict's `zeroMatch` use.
+  const unasked = new Set();
   let hardFail = false, analyzed = 0;
   // ⟨0.24⟩ did the report handed to the gate judge ANYTHING? Per FILE, then ANDed across the multi-report
   // siblings, because the union of several reports has judged something as soon as ONE of them has — the
@@ -882,6 +958,12 @@ export function loadGateReport(prefix) {
   let judgedNothing = true;
   for (const f of files) {
     let parsed;
+    // ⟨0.33⟩ did THIS FILE's peek read a class it does not carry `judgedElsewhere: true` for? The
+    // precondition of the cross-policy refusal, reset per file because `scannedUnder` and `peeked` are
+    // facts about ONE producing scan (SPEC §2 ⟨0.33⟩: "the condition is PER REPORT, never over the union
+    // of a report set") — a policy-scanned sibling's deny set must never answer for a no-policy sibling's
+    // peeked classes.
+    let filePeeked = false;
     try { parsed = JSON.parse(fs.readFileSync(f, "utf8")); }
     catch { console.error(`candor-ts: report ${f} failed to parse — its functions are OMITTED from this gate (corrupt or mid-write); re-run the scan`); hardFail = true; continue; }
     const { entries, corrupt: entryCorrupt } = normFns(parsed, f);
@@ -990,7 +1072,31 @@ export function loadGateReport(prefix) {
         // `#[serde(default)]` does on the same field: a producer that does not say it read the class has
         // not said it read the class.
         else if (e.peeked !== true && e.judgedElsewhere !== true) unread.push(e.class);
+        // ⟨0.33⟩ …and the mirror case: a class the peek DID read (and that is not a `judgedElsewhere`
+        // copy of already-judged code) is exactly the class whose clean answer was bounded by THIS
+        // report's `scannedUnder` — the precondition below.
+        else if (e.peeked === true && e.judgedElsewhere !== true) filePeeked = true;
       }
+    // ⟨0.33⟩ THE QUESTION THIS REPORT'S PEEK WAS PUT — read STRICTLY, like every other verdict-bearing §2
+    // key on this route (`excluded`/`outOfScope` immediately above). A non-object, or a `deny` that is
+    // not an array of strings, IMPEACHES THE DOCUMENT: the safe-LOOKING coercion here is the FAIL-OPEN
+    // direction — "the producer held these rules" — the mirror of `peeked`'s own fail-open, where the
+    // safe-looking coercion was "no exclusions". ABSENT is untouched: a pre-⟨0.33⟩ producer never carried
+    // this key, and the subset test below reads that as the EMPTY SET (refuses), never as a licence.
+    let fileScannedUnder = null;
+    if ("scannedUnder" in parsed) {
+      const su = parsed.scannedUnder;
+      if (!su || typeof su !== "object" || Array.isArray(su) || !Array.isArray(su.deny)
+          || su.deny.some((x) => typeof x !== "string"))
+        corrupt.push(`${f}: \`scannedUnder\` (expected an object \`{deny: [string, …]}\`)`);
+      else fileScannedUnder = new Set(su.deny);
+    }
+    // ⟨0.33⟩ …and, when this file's peek read something, which of THIS gate's own rules that report's
+    // producer was never asked about. An absent `fileScannedUnder` reads as the empty set — never a
+    // licence — so a pre-⟨0.33⟩ producer's `peeked: true` fails closed here exactly as SPEC §2 ⟨0.33⟩
+    // requires. A class the peek never opened at all is `unread`'s gap, not this one's.
+    if (mine.length && filePeeked)
+      for (const r of mine) if (!(fileScannedUnder ?? new Set()).has(r)) unasked.add(r);
     // ⟨0.31⟩ the producer's PARTNER PROVENANCE, carried through verbatim and never recomputed — this
     // route has no target to anchor `net-partner` at, and re-classifying through the consumer's own
     // config is the re-derivation §3.1 forbids. A prefix can match several reports (a workspace writes
@@ -1021,7 +1127,12 @@ export function loadGateReport(prefix) {
   // same class once per member in a message whose job is to name what to re-scan. The verdict is unmoved
   // either way; only the sentence is.
   return { functions, analyzed, unanalyzed, coverage, judgedNothing, outOfScope, netPartners,
-           unread: [...new Set(unread)], hardFail: hardFail || corrupt.length > 0, corrupt };
+           unread: [...new Set(unread)],
+           // ⟨0.33⟩ SPEC §2 — the gate's own rules that some gated report's producer was never asked
+           // about; `[]` when `mine` is empty (no deny/pure rule at all) or every peeked class's producer
+           // covered them.
+           unaskedRules: [...unasked].sort(byCodePoint),
+           hardFail: hardFail || corrupt.length > 0, corrupt };
 }
 // The returned graph carries a non-enumerable `partial` flag (the loadReport `hardFail` precedent):
 // true iff a sidecar file was MATCHED but failed to read/parse — its edges were DROPPED (disclosed on
@@ -2062,6 +2173,33 @@ export function ruleUpgrade(r) {
   return [`deny ${effs}${suffix}`, `deny ${effs} Unknown${suffix}`];
 }
 
+/**
+ * ⟨0.33⟩ A deny/pure rule LIST as a canonical SET — the §6.2 spelling of every rule THE MATCHER USED,
+ * deduplicated and CODE-POINT sorted (`byCodePoint`, the same collation the `zeroMatch` verdict list
+ * already uses), so one policy produces one document however its lines were ordered, and a consumer's
+ * subset test is a plain membership test rather than an order-sensitive comparison.
+ *
+ * RENDERED THROUGH `ruleUpgrade`'s own SOURCE spelling — the first element of the pair it already quotes
+ * back to an operator for the provable-purity upgrade — rather than a second renderer. That is the same
+ * move candor-java made (`Policy.canonicalDenyRule`, shared with `ruleUpgrade`): the string an operator is
+ * quoted and the string a gate compares cannot become two spellings of one rule.
+ *
+ * NOT effect NAMES: `pure` is a rule with an EMPTY effect list meaning "every effect except Unknown", so
+ * flattening to names loses it entirely and the STRICTEST policy would compare equal to an empty one — the
+ * four-way false all-clear ⟨0.30⟩ closed on the peek itself, arriving one layer out. NOT the raw policy
+ * line either: §3.1 already notes alias expansion breaks byte-equality, so two configs defining
+ * `unknown-alias corp` differently would give the identical raw line `deny Unknown[corp]` two meanings.
+ * `ruleUpgrade`'s rendering is the EXPANDED form — post-alias, post-`.candor/config` — because that is
+ * what the peek actually asked (SPEC §2 ⟨0.33⟩, `scannedUnder.deny`).
+ *
+ * One element per RULE — a rule denying several effects is ONE element, not one per effect.
+ */
+export function canonicalDenySet(rules) {
+  const out = new Set();
+  for (const r of rules ?? []) out.add(ruleUpgrade(r)[0]);
+  return [...out].sort(byCodePoint);
+}
+
 /** The single predicate for a provable-purity hole (eval/fixloop/DISPATCH-NOTE.md): a function that is
  *  Unknown, sits in a pure/deny scope, and PASSES that rule (carries none of its forbidden real effects) —
  *  so its compliance is asserted but not verified (the Unknown could hide the very effect the rule forbids;