candor-ts 0.31.0 → 0.32.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.31)."*
+> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.32)."*
 > 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`.
 >
@@ -210,7 +210,13 @@ refactor, as a showMessage and a transient diagnostic, cleared on the file's nex
 CAVEAT — the MCP/LSP gate verdicts are computed FROM THE REPORT: the engine's own `--policy` /
 `--gate-json` run additionally fails an allow rule whose literal surface is incomplete (a masked
 endpoint — internal state, not a report field), so treat a report-side green as advisory and the
-scan-time gate as the CI truth.
+scan-time gate as the CI truth. ⟨0.21⟩/⟨0.30⟩/⟨0.32⟩ — where the REPORT cannot support a green verdict
+at all (a declared `unanalyzed`, an out-of-scope denied effect the producer's peek named, or a class the
+producing scan never OPENED), every route says so: `gate --report` exits 2, `candor_gate` and
+`candor_unverified` withhold `ok` and name the cause, and the LSP — which has neither an exit code nor a
+verdict document — discloses on `window/logMessage` + `window/showMessage`. **An empty editor is not an
+all-clear**: code the scan never read has no line to squiggle, so its absence from the diagnostics IS
+the incompleteness. Re-scan those sources WITH the policy.
 
 Name queries resolve exact > segment-suffix (`db.save` matches `src.db.save`, never
 `src.db.save_all`) > substring — the same ladder as the other engines. The trailing `1` is the
@@ -232,10 +238,16 @@ want-JSON flag.
 - **The classifier is curated** — the node builtins plus a growing npm tier; the README's
   "classifier" paragraph is the ONE current list (this file deliberately doesn't duplicate it — a
   vendored copy here drifted a full generation once).
-  An unlisted package contributes nothing — an effect through it is invisible, not `Unknown`. The
+  An unlisted npm package contributes nothing — an effect through it is invisible, not `Unknown`. The
   scanner **names these per scan**: the receipt's coverage-ledger line (marker: `classifier doesn't
   cover`) lists every npm package the code demonstrably calls that candor's classifier neither
   classifies nor has reviewed-pure — read it before concluding "no effect" through anything it names.
+  ⟨0.32⟩ **NODE CORE is the exception, and it fails closed.** Node's builtins are a finite set, every
+  module's surface has been reviewed, and a core member that is neither classified nor reviewed
+  effect-free reads `Unknown[native:<module>.<member>]` rather than pure. `repl.start()`,
+  `process.dlopen()`, `process.chdir()`, `v8.setFlagsFromString()` and `new worker_threads.Worker(file)`
+  are holes you can see and `deny Unknown[native]` can select — and an API node adds next year is a hole
+  too, until someone reviews it.
 - **`process.env.X` reads are `Env`** (a property read, not a call); `Date.now()` is `Clock`.
 - **DI-style code reads `Unknown` a lot, by design**: a function-typed parameter or field being
   called is genuinely indeterminate (rimraf's injected-fs style yields many `Unknown`s — that's the

package/README.md

@@ -95,12 +95,18 @@ socket.io/nodemailer, gaxios + googleapis-common + google-auth-library, stripe,
 posthog-node, bull/bullmq), the database drivers (pg/mysql2/mongodb/redis/ioredis/sqlite3/
 better-sqlite3/knex) **and the ORM tier** (TypeORM — with `@Entity("…")` table extraction —
 Prisma, Mongoose, Sequelize, drizzle-orm), plus execa/cross-spawn/shelljs/open, fs-extra/
-graceful-fs/rimraf/glob/chokidar, dotenv, winston/pino/bunyan. An unlisted package contributes
+graceful-fs/rimraf/glob/chokidar, dotenv, winston/pino/bunyan. An unlisted npm package contributes
 nothing — candor never guesses an effect — but the scan **names it**: the receipt's coverage-ledger
 line (marker: `classifier doesn't cover`) lists every package the code demonstrably calls that
 candor's classifier neither classifies nor has reviewed-pure, and each function carries the
 `invisible` list it (transitively) reaches.
 
+⟨0.32⟩ **Node core is the one part of the classifier that is a denylist, not a curated list.** The
+builtins are a finite set, so every module's surface is reviewed and a core member that is neither
+classified nor reviewed effect-free reads `Unknown[native:<module>.<member>]` — never pure. That is
+why `v8.writeHeapSnapshot()` is `Fs`, `inspector.open()` is `Net`, and `repl.start()`,
+`process.dlopen()` and `new worker_threads.Worker(file)` are visible holes rather than silence.
+
 ## MCP server — candor as agent ground truth
 
 `candor-ts-mcp` exposes the read-only queries as an [MCP](https://modelcontextprotocol.io) server, so
@@ -192,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.31" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
+| `{ candor: { version, toolchain, spec: "0.32" }, 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 |
 
@@ -210,7 +216,7 @@ read the Rust source".
 
 ## Status
 
-0.30.0, speaking candor-spec 0.31: the analysis core, the gate (`--policy` / `--gate-json` /
+0.30.0, speaking candor-spec 0.32: 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

@@ -11,6 +11,11 @@
  *     gate also fails an allow rule whose literal surface is INCOMPLETE (a masked/invisible endpoint,
  *     kept internal per the java/rust engines — not a report field), so no-squiggle here can still be
  *     red in CI. The engine's --gate-json is the authoritative form (same caveat as MCP candor_gate).
+ *     ⟨0.21⟩/⟨0.30⟩/⟨0.32⟩ — and where the report itself cannot support a green verdict (a declared
+ *     `unanalyzed`, the producer's peek naming an out-of-scope denied effect, or a class the scan never
+ *     OPENED), the squiggles are not the whole verdict and the gap is DISCLOSED on window/logMessage +
+ *     window/showMessage. No diagnostic: code the scan never read has no line here to sit on. See
+ *     `discloseIncompleteness`.
  *   • Hover: effect PROVENANCE — for each inherited effect, the `path` hop chain to the function that
  *     performs it directly ("Net via mid → leaf (source)"), plus unknownWhy when the fn discloses opacity.
  *   • CodeAction (pre-edit whatif): inside a function the report knows, one action per BOUNDARY effect
@@ -45,7 +50,7 @@ import { createRequire } from "node:module";
 import nodePath from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import * as Q from "./query-core.mjs";
-import { discoverConfigPolicy, evaluatePolicy, parsePolicy, scopeMatches, reportNetClasses, parseUnknownAliases, discoverConfigText, policyVocabularyAnchor, policyErrorText, unanswerableScoped, wholePolicyUnanswerable, resolveReasonClasses, fatalPolicyErrors, policyZeroRules } from "./policy.mjs";
+import { discoverConfigPolicy, evaluatePolicy, parsePolicy, scopeMatches, reportNetClasses, parseUnknownAliases, discoverConfigText, policyVocabularyAnchor, policyErrorText, unanswerableScoped, wholePolicyUnanswerable, resolveReasonClasses, fatalPolicyErrors, policyZeroRules, reportUnits } from "./policy.mjs";
 
 // Version: from the sibling package.json when running inside the npm package; a single-file BUNDLE of
 // this server (the IDE-plugin embedding) has no sibling package.json — fall back rather than crash.
@@ -280,6 +285,26 @@ function hoverAt(docPath, line) {
 // ---- Diagnostics (the live gate) ---------------------------------------------------------------------
 const warned = new Set();
 function warnOnce(message) { if (!warned.has(message)) { warned.add(message); logMessage(message); } }
+/**
+ * ⟨0.32⟩ A LOUDER `warnOnce`, for the causes that are EXIT-BEARING on every other route.
+ *
+ * Everything `warnOnce` carries today is a disclosure the CLI makes AT EXIT 0 — ⟨0.24⟩ ruled count-0 "a
+ * disclosure, not an exit code", the unevaluated-rule rows ride alongside a verdict, and `ignored` does
+ * not move `ok`. The incompleteness causes below are the other kind: `gate --report` EXITS 2 over them,
+ * `candor_gate` withholds `ok`, and `fix-gate`/`unverified --strict` exit 2. This surface has no exit
+ * code and no verdict document, so the whole rung collapses onto messages — and putting the LOUDER cause
+ * on the QUIETER channel (an output pane the developer has to go and open) would invert an ordering the
+ * other four routes agree on. So: the log line carries the detail and the repair, and a `window/
+ * showMessage` says that CI is red over these bytes. Both are `warnOnce`-deduped on the LOG text, which
+ * is a function of the policy and the report rather than of the edit, so a save loop cannot turn either
+ * into the per-keystroke noise that gets an advisory switched off.
+ */
+function warnLoudOnce(message, brief) {
+  if (warned.has(message)) return;
+  warned.add(message);
+  logMessage(message);
+  showMessage(2, brief);          // Warning — the same severity the activity push uses for a red gate
+}
 // ⟨0.24⟩ the file `activePolicy()` last read, so the vocabulary anchor can be the POLICY FILE's dir.
 let activePolicyPath = null;
 function activePolicy() {
@@ -337,6 +362,77 @@ const zeroRulePolicyWarn = (what) =>
     + `here is NOT an all-clear: \`gate\` REFUSES over this policy outright (exit 2, SPEC §6.2). If you did `
     + `not mean to gate, remove the policy configuration rather than pointing it at a file with no rules.`);
 
+/**
+ * ⟨0.21⟩/⟨0.30⟩/⟨0.32⟩ THE INCOMPLETENESS CAUSES, ON THE ROUTE THAT CARRIED NONE OF THEM.
+ *
+ * MEASURED at `9f22581` — the commit titled "four routes, one rule", where there were FIVE. Over a
+ * report whose `excluded` records a `dist/shipped.js` running `curl … | sh` that the scan never opened,
+ * under a discovered `deny Exec`: `gate --report` exits 2 naming the class, the MCP `candor_gate` tool
+ * withholds `ok`, and this server published `[]` — no diagnostic, no log line, no message. `lsp.mjs` had
+ * zero occurrences of `excluded`, `peeked` or `unread`, and it is silent on the ⟨0.21⟩ and ⟨0.30⟩ causes
+ * for the same reason: `diagnosticsFor` read NO completeness key at all. This is the SHIPPED EDITOR
+ * EXPERIENCE — `integrations/vscode` and the JetBrains plugin both bundle this exact server — so the
+ * cardinal sin arrived in the place with the fewest ways to notice it: an editor showing a clean file
+ * over code nothing read. The argument was already in this file four lines below, about a different
+ * cause: "an empty editor reads as 'the gate is green'".
+ *
+ * ONE RULE, NOT A SIXTH SPELLING OF IT. The condition is the CLI gate's, read off the same
+ * `reportCompleteness` value the CLI and MCP routes read, applied ONCE:
+ *
+ *   · `unread` (⟨0.32⟩) is gated on `pol.deny.length` — only a `deny`/`pure` rule's answer depends on
+ *     code outside the scan's scope, so refusing an `allow`/`forbid`/`only` policy for want of a peek
+ *     would be an over-charge. `pure` RIDES the deny vector (parsePolicy pushes it there), so the test
+ *     is `deny.length` and not a search for the token, and flattening that away would delete the rule
+ *     for every `pure`-only policy.
+ *   · `unanalyzed` (⟨0.21⟩) and `outOfScope` (⟨0.30⟩) are UNCONDITIONAL, exactly as they are on the CLI
+ *     gate: a unit candor could not read is unread whatever the policy asks, and `outOfScope` is by
+ *     construction the peek's findings UNDER the producer's own policy.
+ *
+ * ALL THREE, not just the one this rung is named for. They are one `gincomplete` disjunction on the CLI
+ * and one `incomplete` on the MCP tool; carrying one of three into this route would have left the same
+ * defect, in the same function, for the next audit to find — which is the habit this whole rung exists
+ * to break. Each cause is NAMED ONLY WHEN IT FIRED, the MCP tool's rule: a sentence about unanalyzed
+ * code beside an incompleteness that is really an unopened `dist/` sends the reader to the wrong repair.
+ *
+ * NO DIAGNOSTIC IS DRAWN, and that is the answer to "a squiggle on what". There is no source range for a
+ * file the scan never opened: the code is absent from `functions` precisely because nothing looked, so
+ * the only line available is line 0 of whatever document happens to be open — which would attribute the
+ * hole to an innocent file, in every language the client maps, on every open. That is the fabrication
+ * mirror of the silence being fixed. The ⟨0.24⟩ judged-nothing hedge reached the same conclusion for the
+ * 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) {
+  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.
+  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`
+      + unanalyzed.map((u) => `        ${u.path || "(unnamed unit)"}${u.reason ? `  (${u.reason})` : ""}`).join("\n"));
+  if (outOfScope.length)
+    causes.push(`the report names ${outOfScope.length} function(s) OUTSIDE the scan's scope performing `
+      + `an effect this policy denies (the producer's peek found them). The gate did not judge them, so the verdict is `
+      + `INCOMPLETE rather than a pass — re-scan with a selector that REACHES that code:\n`
+      + outOfScope.map((o) => `        ${o.fn} performs ${(o.effects ?? []).join(", ")}`).join("\n"));
+  if (unread.length)
+    causes.push(`the scan did not READ ${unread.join(", ")}. Those files' effects are absent from the `
+      + `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.`);
+  if (!causes.length) return;
+  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`
+    + 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.`);
+}
+
 function diagnosticsFor(docPath) {
   const text = activePolicy();
   if (text === null || !hasReport(reportPrefix)) return [];
@@ -374,6 +470,15 @@ 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
+  // `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);
+  discloseIncompleteness(dcomp.unanalyzed ?? [], dcomp.outOfScope ?? [],
+                         dpol.deny.length ? (dcomp.unread ?? []) : []);
   // ⟨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
@@ -382,9 +487,11 @@ function diagnosticsFor(docPath) {
   // never carried. `authoritative: true` for the same reason the MCP gate takes it: an entry without
   // `netClass` gets the EMPTY set rather than a derivation from `hosts`, so the report is the only source of
   // the class and nothing is re-classified with this machine's evidence about the producer's project.
-  const dnet = reportNetClasses(fns, { authoritative: true });
+  // ⟨0.32⟩ the same unit identity the CLI gate uses over these bytes (SPEC §2.2).
+  const dunits = reportUnits(fns);
+  const dnet = reportNetClasses(fns, { authoritative: true, units: dunits });
   const { unevaluated: dunevaluated, withhold: dwithhold } =
-    unanswerableScoped(dpol, fns, resolveReasonClasses(fns, Q.loadCallgraph(reportPrefix)), dnet);
+    unanswerableScoped(dpol, fns, resolveReasonClasses(fns, Q.loadCallgraph(reportPrefix), dunits), dnet, dunits);
   // ⟨0.29⟩ `forbid`/`allow` are STRIPPED and DISCLOSED here too. This path handed the whole policy to
   // `evaluatePolicy`, so an editor drew AS-EFF-009 squiggles from a report — evidence SPEC §3.1 rules
   // cannot support them — or, with no sidecar, drew nothing and said nothing, which reads as "no layering
@@ -403,7 +510,7 @@ function diagnosticsFor(docPath) {
   for (const u of dunevaluated)
     warnOnce(`candor-lsp: ${u.why}\n  NO diagnostics are drawn for that rule — their ABSENCE here is the refusal, not an all-clear.`);
   const violations = evaluatePolicy(dwp.answerable, fns, Q.loadCallgraph(reportPrefix),
-                                    new Map(), new Set(), dnet, dwithhold);
+                                    new Map(), new Set(), dnet, dwithhold, dunits);
   const locByFn = new Map(fns.filter((e) => e.loc).map((e) => [e.fn, locParts(e.loc)]));
   const out = [];
   for (const v of violations) {

package/mcp.mjs

@@ -21,7 +21,7 @@ import nodePath from "node:path";
 import * as Q from "./query-core.mjs";
 import { discoverConfigPolicy, evaluatePolicy, parsePolicy, scopeMatches, reportNetClasses,
          parseUnknownAliases, discoverConfigText, policyVocabularyAnchor, policyErrorText,
-         unanswerableScoped, wholePolicyUnanswerable, resolveReasonClasses, fatalPolicyErrors,
+         unanswerableScoped, wholePolicyUnanswerable, resolveReasonClasses, fatalPolicyErrors, reportUnits,
          policyZeroRules } from "./policy.mjs";
 
 const VERSION = createRequire(import.meta.url)("./package.json").version; // single-sourced, like scan.mjs
@@ -216,20 +216,28 @@ function capCallers(r) {
 // `{"entryPoints":0,"effects":{}}`, `candor_containment` → `{"contained":[],"ambient":{}}` — five flat
 // all-clears with no hedge. `candor_show`/`candor_impact` already fail closed on the fn-existence guard.
 //
+// ⟨0.32⟩ **AND THAT LAST SENTENCE WAS TRUE OF ONE CAUSE AND HID THREE TOOLS.** The fn-existence guard
+// fires when the report contains no such NAME; it says nothing about a report that contains the name and
+// declares part of the tree unread. MEASURED over this server's own stdio transport on a report whose
+// `excluded` names one class with `peeked: false`: `candor_impact`, `candor_callers` and `candor_path` all
+// answered FLAT — the SILENT half of the class `candor_show`/`candor_map` had the loud half of. All three
+// now take this wrapper; all three have fixed key sets, so nothing is nested and nothing is displaced.
+//
 // THE AGENT IS THE CONSUMER THAT CANNOT ASK A FOLLOW-UP QUESTION. A human running the CLI at least sees an
 // oddly bare answer; a loop reading `blindspots.sources.length === 0` records "no blind spots" and moves on.
 // Additive and a no-op on a complete report (`completenessFields` returns `{}`), so every pinned tool shape
 // is unchanged on an ordinary one.
 // The collision loop this used to carry is gone with ⟨0.28⟩ Rung A: `candor_map` was its only possible
-// trigger and now takes `caveatInstead`, where nothing is displaced. Every remaining caller has a fixed
+// trigger and now takes `nestWithCaveat`, where its namespace sits one level down and nothing is
+// displaced. Every remaining caller has a fixed
 // key set, so the condition is not constructible — and a guard whose condition cannot arise reads as
 // coverage.
 const withCompleteness = (p, doc) => ({ ...doc, ...Q.completenessFields(Q.reportCompleteness(p)) });
-// ⟨0.28⟩ RUNG A, ON THE AGENT CHANNEL — SPEC §2: a verb whose pinned shape cannot carry the caveat emits
-// the CAVEAT DOCUMENT INSTEAD of its result document. Two tools qualify and both are handled here,
-// because THE MCP HALF HAS BEEN THE MISSED ROUTE TWICE IN THIS REPO — and it is the worse one: an agent
-// reading `Object.keys(map).length === 0` records "this codebase performs no effects" and moves on, with
-// no follow-up question available to it.
+// ⟨0.28⟩ RUNG A, ON THE AGENT CHANNEL — SPEC §2: a verb whose pinned shape cannot carry the caveat
+// changes SHAPE over a hedging report. Two tools qualify and both are handled here, because THE MCP HALF
+// HAS BEEN THE MISSED ROUTE TWICE IN THIS REPO — and it is the worse one: an agent reading
+// `Object.keys(map).length === 0` records "this codebase performs no effects" and moves on, with no
+// follow-up question available to it.
 //
 //   candor_show  the CLI's `show` is pinned to an ARRAY; this tool returns `Q.show(...)`, the same array,
 //                and had no completeness reader at all.
@@ -239,30 +247,45 @@ const withCompleteness = (p, doc) => ({ ...doc, ...Q.completenessFields(Q.report
 //
 // A no-op on a complete report, so both pinned tool shapes are unchanged on an ordinary one.
 // ⟨0.28⟩ THE DOC ARRIVES AS A THUNK, and that is the whole fix rather than a style preference.
-// This took `doc` by value, so JavaScript evaluated `Q.show(loadReportLoud(p), a.fn)` BEFORE
-// `caveatInstead` was ever called — and `Q.show`'s fn-existence guard throws. Over a judged-nothing
-// report `candor_show <anything>` therefore answered "no function matching …" to an AGENT: a
-// determined negative about the code, produced by a report that examined none of it, on the surface
-// where a wrong answer is acted on rather than read. The CLI was already correct (measured: it emits
-// the caveat document), so this was the MCP half of a rung the CLI had shipped — the third time today
-// that half was the one nobody checked.
+// This took `doc` by value, so JavaScript evaluated `Q.show(loadReportLoud(p), a.fn)` BEFORE the helper
+// was ever called — and `Q.show`'s fn-existence guard throws. Over a judged-nothing report
+// `candor_show <anything>` therefore answered "no function matching …" to an AGENT: a determined
+// negative about the code, produced by a report that examined none of it, on the surface where a wrong
+// answer is acted on rather than read.
 //
-// Hedging is now decided BEFORE the answer is computed, so no guard inside the verb can pre-empt it.
 // AND CORRUPTION IS NOT A HEDGE — the deferral made that distinction load-bearing where it had been
 // free. `mustHedge` is true on the `unreadable` arm too, so simply deferring turned `candor_map` over a
 // CORRUPT report from a loud tool error into `{"incomplete": true}`: a disclosure where the contract
 // says refuse (§2 ⟨0.24⟩ — a signature key that cannot be read impeaches the document, it does not
-// qualify it). Caught by the existing row, which is the second time today that fixing a false negative
-// introduced a wrong downgrade in the same edit.
+// qualify it). So the loud causes fall THROUGH to the thunk, whose loader throws; corruption anywhere in
+// the set wins over a hedge elsewhere in it.
+//
+// ⟨0.32⟩ **AND THE HEDGING BRANCH NOW RETURNS THE RESULT *AND* THE WARNING — RULED 2026-08-25.** It used
+// to return `Q.completenessFields(comp)` alone, which was tolerable while the only triggers were a scan
+// that had FAILED (there was no answer to withhold). ⟨0.32⟩'s unread-class cause armed the same
+// substitution on nearly every no-policy report, so MEASURED over this server's own stdio transport, on a
+// report whose `excluded` names one unpeeked class: `candor_show` and `candor_map` both handed the agent
+// `{"incomplete":true}` and NOTHING ELSE. These two tools CERTIFY NOTHING — no `ok`, no verdict — so
+// there is no claim for a pessimism rule to protect, and an agent that asked what the code does was
+// answered with a caveat about a question it did not ask. `candor_gate` and the `--strict` advisory
+// tools are on the other side of that boundary and are untouched: they answer `ok` and must keep
+// refusing (⟨0.24⟩; conformance PARTs 62 and 67).
+//
+// The result NESTS under the caller's key so `map`'s module namespace cannot collide with the caveat
+// vocabulary, matching the CLI's `putNestedWithCaveat` byte for byte.
 //
-// So the loud causes fall THROUGH to the thunk, whose loader throws; only the qualifying causes
-// substitute a caveat. Corruption anywhere in the set wins over a hedge elsewhere in it.
-const caveatInstead = (p, doc) => {
+// THE THUNK IS STILL CALLED LAST AND ITS THROW IS STILL HONOURED. `Q.show`'s fn-existence guard is a
+// REFUSAL, not a result, and over a hedging report that refusal is not a fact about the code — so the
+// caveat stands alone there, exactly as this surface answered before. That is the one case where the
+// warning is all there is, and it is because there is no data, not because the data was withheld.
+const nestWithCaveat = (p, key, doc) => {
   const comp = Q.reportCompleteness(p);
   const call = () => (typeof doc === "function" ? doc() : doc);
   if (comp?.unreadable?.length) return call();          // refuse loudly, via the loader
-  if (Q.mustHedge(comp)) return Q.completenessFields(comp);
-  return call();
+  if (!Q.mustHedge(comp)) return call();
+  let result;
+  try { result = call(); } catch { return Q.completenessFields(comp); }
+  return { [key]: result, ...Q.completenessFields(comp) };
 };
 // ⟨0.28⟩ The graph the three graph verbs answer over: the §2.2 sidecar when there is one, else the
 // report's own embedded `calls` edges (Q.reportCallsGraph) — the same fallback the CLI and rust/java
@@ -279,7 +302,14 @@ const TOOLS = {
   candor_impact: {
     description: "Backward blast radius: every effectful function that transitively calls `fn`, and which runtime entry points are downstream. Answers 'if I change this, what surfaces at runtime?' — the cheapest possible alternative to tracing callers by hand.",
     schema: { type: "object", properties: { fn: { type: "string", description: "the function/unit to assess" }, ...reportArg }, required: ["fn"] },
-    run: (a, p) => { const fns = loadReportLoud(p); return capImpact(Q.impact(fns, graphOrReportEdges(p, fns), a.fn)); },
+    // ⟨0.32⟩ `withCompleteness` — this tool had NO completeness reader, and neither did `candor_path` or
+    // `candor_callers`. MEASURED over this server's own stdio transport on a report whose `excluded`
+    // names one class with `peeked: false`: all three answered FLAT, and `affectedCount: 0` on the AGENT
+    // channel is *nothing calls this, safe to change* — read by a consumer with no follow-up question
+    // available to it. Fixed key sets, so the caveat spreads at the root and every pinned tool shape is
+    // unchanged on a complete report (`completenessFields` → `{}`). These three certify nothing, so they
+    // are on the descriptive side of the ⟨0.32⟩ boundary stated on `nestWithCaveat` below.
+    run: (a, p) => { const fns = loadReportLoud(p); return withCompleteness(p, capImpact(Q.impact(fns, graphOrReportEdges(p, fns), a.fn))); },
   },
   candor_where: {
     description: "Which functions perform a given effect (e.g. Net, Db, Exec, Fs) — `directly` vs `inherited` via a callee. The effect-surface map.",
@@ -294,22 +324,25 @@ const TOOLS = {
   candor_path: {
     description: "Forward provenance: the shortest call chain from `fn` to the nearest function that performs `effect` DIRECTLY — 'this reaches Net through WHAT?'.",
     schema: { type: "object", properties: { fn: { type: "string" }, effect: { type: "string" }, ...reportArg }, required: ["fn", "effect"] },
-    run: (a, p) => { const fns = loadReportLoud(p); return Q.path(fns, graphOrReportEdges(p, fns), a.fn, a.effect); },
+    // ⟨0.32⟩ see `candor_impact` above: `path: []` to an agent is *this function does not reach that
+    // effect*, and a hop through an unread unit breaks the chain.
+    run: (a, p) => { const fns = loadReportLoud(p); return withCompleteness(p, Q.path(fns, graphOrReportEdges(p, fns), a.fn, a.effect)); },
   },
   candor_callers: {
     description: "Who calls `fn` — direct (one hop) and transitive callers over the effect-relevant call graph.",
     schema: { type: "object", properties: { fn: { type: "string" }, ...reportArg }, required: ["fn"] },
-    run: (a, p) => capCallers(Q.callers(graphOrReportEdges(p, loadReportLoud(p)), a.fn)),
+    // ⟨0.32⟩ see `candor_impact` above: an empty `direct` to an agent is *nobody calls this*.
+    run: (a, p) => withCompleteness(p, capCallers(Q.callers(graphOrReportEdges(p, loadReportLoud(p)), a.fn))),
   },
   candor_show: {
     description: "A function's effects (inferred = transitive, direct = own body) plus its literal surfaces (hosts/cmds/paths/tables) when present.",
     schema: { type: "object", properties: { fn: { type: "string" }, ...reportArg }, required: ["fn"] },
-    run: (a, p) => caveatInstead(p, () => Q.show(loadReportLoud(p), a.fn)),
+    run: (a, p) => nestWithCaveat(p, "functions", () => Q.show(loadReportLoud(p), a.fn)),
   },
   candor_map: {
     description: "Per-module effect overview: each module's union of effects and function count. The architecture-at-a-glance.",
     schema: { type: "object", properties: { ...reportArg } },
-    run: (_a, p) => caveatInstead(p, () => Q.map(loadReportLoud(p))),
+    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.",
@@ -358,7 +391,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, unanalyzed }` means the report declares code candor could not analyze, so the gate cannot be green. 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 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.",
     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;
@@ -405,8 +438,11 @@ const TOOLS = {
             : `a report found at prefix \`${clip(p)}\` failed to load — refusing to gate over a report that did not load cleanly; a partial signature makes a green verdict meaningless (the effects of the report that did not load are exactly the ones a violation would come from). Re-run the scan`));
       const gfns = g.functions;
       const cg = Q.loadCallgraph(p);
-      const gnet = reportNetClasses(gfns, { authoritative: true });
-      const { unevaluated, withhold } = unanswerableScoped(pol, gfns, resolveReasonClasses(gfns, cg), gnet);
+      // ⟨0.32⟩ the same unit identity the CLI gate uses over these bytes (SPEC §2.2) — one object, so this
+      // surface cannot join two members by name while the CLI keeps them apart.
+      const gunits = reportUnits(gfns);
+      const gnet = reportNetClasses(gfns, { authoritative: true, units: gunits });
+      const { unevaluated, withhold } = unanswerableScoped(pol, gfns, resolveReasonClasses(gfns, cg, gunits), gnet, gunits);
       // ⟨0.29⟩ …AND THE TWO WHOLE-POLICY UNANSWERABLE KINDS. This tool passed the WHOLE policy to
       // `evaluatePolicy`, so `forbid` was answered from a report — MEASURED: with no callgraph sidecar,
       // `violations: 0` and nothing disclosed (a silent green over a rule that was never enforced); with a
@@ -421,12 +457,24 @@ const TOOLS = {
       // to suppress a certain violation).
       if (wp.onlyUnanswerable)
         throw new Error(`this policy asks only questions a report cannot answer — ${wp.unevaluated[0].why}`);
-      const v = evaluatePolicy(wp.answerable, gfns, cg, new Map(), new Set(), gnet, withhold);
+      const v = evaluatePolicy(wp.answerable, gfns, cg, new Map(), new Set(), gnet, withhold, gunits);
       // ⟨0.21⟩ COMPLETENESS MANIFEST — this tool implemented no incompleteness rule at all: it answered
       // `{ok:true, violations:[]}` over a report DECLARING `unanalyzed`, where the CLI exits 2. A gate
       // cannot be green over code candor never analyzed, and the manifest travels ON the report, so the
       // same verdict follows from it here. Additive to the pinned `{ok, violations}` shape.
-      const incomplete = g.unanalyzed.length > 0;
+      // ⟨0.30⟩/⟨0.32⟩ …AND THE OTHER TWO CAUSES, which this route carried NEITHER of — the sibling-route
+      // habit again, on the channel whose consumer cannot ask a follow-up question. Both ride the REPORT,
+      // exactly as they do for `gate --report`, so this tool re-reads the producer's record rather than
+      // deriving anything of its own:
+      //   · `outOfScope` (⟨0.30⟩) — the producer's peek NAMED a function outside the scan's scope
+      //     performing an effect this policy denies. The CLI exits 2; this tool answered `ok: true`.
+      //   · `unread` (⟨0.32⟩) — a class the producer never OPENED (`excluded[].peeked: false`), so its
+      //     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.
+      const gscope = g.outOfScope ?? [];
+      const gunread = pol.deny.length ? g.unread : [];
+      const incomplete = g.unanalyzed.length > 0 || gscope.length > 0 || gunread.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,
@@ -476,7 +524,15 @@ const TOOLS = {
               + "claim about any unit they contain. The named report(s) are the gap; the verdict above covers "
               + "only the siblings that DID judge. Re-scan those sources, or point `report` at the package that "
               + "has them." } : {};
-      const inc = incomplete ? { incomplete: true, unanalyzed: g.unanalyzed } : {};
+      // EACH CAUSE NAMED ONLY WHEN IT FIRED. `unanalyzed: []` beside `incomplete: true` would be a
+      // positive claim that candor read every file — the safe-LOOKING value, and the one an agent would
+      // act on — for an incompleteness with a different cause and a different repair.
+      const inc = incomplete
+        ? { incomplete: true,
+            ...(g.unanalyzed.length ? { unanalyzed: g.unanalyzed } : {}),
+            ...(gscope.length ? { outOfScope: gscope } : {}),
+            ...(gunread.length ? { unread: gunread } : {}) }
+        : {};
       // ⟨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
       // ALL, because the gate is making no claim about violations and `[]` is precisely the claim it cannot
@@ -504,7 +560,10 @@ 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). `ok` is ABSENT for a second reason too, and the entries that come "
+                 + "an all-clear (spec §3.2). `incomplete:true` also rides the two 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 "
                  + "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 "
@@ -537,8 +596,19 @@ const TOOLS = {
       if (policyAskedNothing(upol)) return zeroRuleCaveat(polPath, p);
       // ⟨0.28⟩ `noManifest` (SPEC §2 row 3) rides here too — a report with no `analyzed` key declares
       // nothing, and listing it under `judgedNothing` would be the false disclosure the rung split out.
+      // ⟨0.30⟩/⟨0.32⟩ …AND THE TWO SCOPE CAUSES, which this call was the last route in the package to
+      // read. MEASURED: over a report whose `excluded` names a class the producing scan never opened,
+      // under `deny Exec`, `candor_gate` in THIS SAME PROCESS answered `{ok:false, incomplete:true,
+      // unread:[…]}` while this tool answered `{ok:true, unverified:[]}` — and the CLI sibling
+      // `unverified --strict` over the identical bytes omitted `ok`, named the class and exited 2.
+      // ⟨0.24⟩'s MUST binds every channel a verb answers on: an advisory verb may be LESS certain than
+      // the gate, NEVER MORE. The `unread` condition is the gate's, off the same value, applied once —
+      // 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 ?? []) : [];
       return Q.advisoryAnswer(Q.unverified(loadReportLoud(p), upol, scopeMatches),
-                              ucomp.unanalyzed, ucomp.judgedNothing, ucomp.unreadable, ucomp.noManifest);
+                              ucomp.unanalyzed, ucomp.judgedNothing, ucomp.unreadable, ucomp.noManifest,
+                              ucomp.outOfScope ?? [], uUnread);
     },
   },
   candor_containment: {

package/package.json

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