candor-ts 0.27.0 → 0.28.1

package/AGENTS.md

@@ -3,7 +3,16 @@
 You are working in a TypeScript project. **candor-ts** tells you, for every function, which side
 effects it can reach — network, filesystem, database, subprocess, env, clock — *including effects
 inherited transitively through any chain of calls across files*. Use it instead of tracing call
-chains by hand.
+chains by hand. The language-agnostic consumption contract is
+[candor-spec/AGENTS.md](https://github.com/tombaldwin/candor-spec/blob/main/AGENTS.md); this file is
+the TypeScript-specific production + query surface.
+
+> **If the repository is not TypeScript-only, start at the umbrella:**
+> [candor/AGENTS.md](https://github.com/tombaldwin/candor/blob/main/AGENTS.md). `candor` is one
+> command in front of every engine (TypeScript, JVM, Rust, Swift, agent fleets) — it picks the right
+> one per target, `candor update` installs and upgrades them, and `candor doctor` checks that every
+> installed engine agrees on a spec version. A polyglot repo scanned with this engine alone gets an
+> answer about its TypeScript and nothing that says so.
 
 > **This document ships inside the package.** `npx -y candor-ts --agents` prints the contract for
 > the *installed* version — always prefer that over a vendored or fetched copy, which can describe
@@ -12,7 +21,7 @@ chains by hand.
 > **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.27)."*
+> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.28)."*
 > 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`.
 >
@@ -73,6 +82,44 @@ pure functions are omitted** — a function present in the callgraph sidecar but
 `.functions[]` is pure (as far as the engine resolved). In *neither* file = never analyzed
 (a test file? an unexported arrow inside an object literal?) — conclude nothing.
 
+**A report with `analyzed.count: 0` is a run that FAILED, not a clean codebase.** A scan that exits 2
+leaves that fail-closed shape (`functions: []`, `analyzed.count: 0`, a non-empty `unanalyzed`) at the
+`--out` report, and it DELETES that report's `.callgraph`/`.hierarchy`/`.locs` sidecars with it — so
+`callers`/`whatif` answer from an absent call graph rather than from the last successful run. Read the
+two together: **a sidecar whose report is one of these empties tells you nothing, whatever it says.**
+Re-scan; do not conclude from either half.
+
+⟨0.28⟩ **And `callers`, `impact` and `path` SAY so in the machine channel over such a pair** — a document
+carrying `"unanswerable": "<why>"` and NO answer keys, at **exit 2**, never an empty `direct` /
+`affectedCount: 0` / `path: []` at exit 0. All three resolve their target over the call graph, and each of
+those empties is the reassurance you asked the verb for: *nothing calls this*, *safe to change*, *it does
+not reach that effect*. With no call graph the engine knows none of it — so do not read
+`d.direct ?? []`, `d.affectedCount ?? 0` or `d.path ?? []` without checking `unanswerable` first.
+Over a REAL graph the negatives stand: a function with genuinely no callers still answers `direct: []`,
+one that affects nothing still answers `affectedCount: 0`, and one that does not reach an effect still
+answers `path: []`, all at exit 0 — those are determined negatives, and they are correct.
+
+⟨0.28⟩ **A target NAME that does not resolve is a THIRD answer, and it is exit 2 as well** — `callers`,
+`impact` and `path` print `no function matching '<target>'` on stderr instead of answering `direct: []` /
+`affectedCount: 0` / `path: []`. So a query gets one of three, and a typo gets the third, not the second:
+*there is no call graph* (an `unanswerable` document), *the graph says no* (a real empty answer, exit 0),
+and *there is no such function* (stderr, and NO `unanswerable` key — a graph WAS read). If you generate
+query targets, read exit 2 + `no function matching` as **fix the name**, never as a finding.
+
+⟨0.28⟩ **And the REPORT-ONLY verbs — `where`, `map`, `blindspots`, `reachable`, `containment`, `tour` —
+carry the report's own ⟨0.21⟩ manifest instead**, because they have no call graph to be missing and their
+empty answer is the whole of the harm: `{"directly":[],"inherited":[]}`, `{}`,
+`{"sources":[],"totalUnknown":0}`, `{"entryPoints":0,"effects":{}}`, `{"contained":[],"ambient":{}}`,
+`{"reaches":[]}`. Over a report declaring a non-empty `unanalyzed` **or** `analyzed.count: 0` they add
+`"incomplete": true` (plus `unanalyzed` / `"judgedNothing": true`, naming which cause — the two want
+different repairs) to the SAME document, and the human arm withdraws its ✓. **The exit code does NOT
+move**: this rung is a caveat, not a refusal, so `if (!doc.incomplete)` is the guard and the exit is not.
+Same keys on the MCP tools (`candor_where`, `candor_map`, `candor_blindspots`, `candor_reachable`,
+`candor_containment`) and on the advisory verbs (`unverified`, `fix-gate`, `whatif`), which additionally
+OMIT `ok`. Over a COMPLETE report the answer is byte-identical to a pre-⟨0.28⟩ one — no key, no note —
+and `analyzed.count > 0` with `functions: []` is deliberately NOT hedged: that is a genuine all-pure
+claim (§2 rule 3) you should believe.
+
 A dist-CJS export unit (a `module.exports` surface scanned with `--allow-js`) carries
 `unitKind: "export"` (spec 0.8, informative); ordinary functions omit the field.
 

package/README.md

@@ -192,7 +192,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.27" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
+| `{ candor: { version, toolchain, spec: "0.28" }, 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 +210,7 @@ read the Rust source".
 
 ## Status
 
-0.19.x, speaking candor-spec 0.27: the analysis core, the gate (`--policy` / `--gate-json` /
+0.28.0, speaking candor-spec 0.28: 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/contract.mjs

@@ -8,6 +8,38 @@ import { fileURLToPath } from "node:url";
 export function printAgents() {
   const dir = path.dirname(fileURLToPath(import.meta.url)); // the package root (where AGENTS.md ships)
   const semver = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8")).version;
-  console.log(`<!-- candor-ts ${semver} · the agent contract for this installed version -->`);
-  process.stdout.write(fs.readFileSync(path.join(dir, "AGENTS.md"), "utf8"));
+  const out = `<!-- candor-ts ${semver} · the agent contract for this installed version -->\n`
+    + fs.readFileSync(path.join(dir, "AGENTS.md"), "utf8");
+  // fs.writeSync, NOT console.log/process.stdout.write. On a PIPE those are asynchronous, and scan.mjs
+  // calls `process.exit(0)` on the next line — which discards whatever is still buffered. The contract
+  // came out TRUNCATED AT 8170 OF 23121 CHARACTERS, cut mid-sentence, with exit 0 and nothing on stderr:
+  // an agent piping `candor-ts --agents` into its context silently read a third of its own instructions.
+  // Only on a pipe — a redirect to a file writes synchronously, which is why this survived a manual
+  // check and only the suite's execFileSync saw it.
+  //
+  // The comment above says one implementation cannot diverge, and it was still wrong: query.mjs `break`s
+  // and drains on the way out, scan.mjs exits. THE SIBLING ROUTE AGAIN — sharing the PRINTER does not
+  // share the EXIT, and the divergence lived in the caller the shared function was meant to protect.
+  // Fixing it here rather than in scan.mjs is deliberate: the next caller inherits the fix.
+  //
+  // Two failure modes the first version of this did not handle, both specific to a PIPE, which is the
+  // case it exists for:
+  //   EPIPE  — the reader stopped early (`| head -n5`, `| grep -m1`, a consumer that closed). The old
+  //            console.log path exited 0 silently; a bare writeSync raises, and a print-and-exit mode
+  //            answering a contract request with a Node stack trace and exit 1 is a worse regression
+  //            than the truncation this replaced. Swallowed — the reader left, that is not our error.
+  //   EAGAIN — once stdout has been initialised, libuv puts the pipe in non-blocking mode and writeSync
+  //            THROWS rather than short-writing as soon as the payload exceeds the 64 KiB pipe buffer.
+  //            The contract is 24 KiB today, so this is latent, not live — and it would come back as
+  //            exactly the truncation-plus-noise this function was written to remove. Retry with a
+  //            small backoff (Atomics.wait is the only synchronous sleep available here).
+  let off = 0;
+  const buf = Buffer.from(out, "utf8");
+  const idle = new Int32Array(new SharedArrayBuffer(4));
+  try {
+    while (off < buf.length) {
+      try { off += fs.writeSync(1, buf, off, buf.length - off); }   // a short write is legal
+      catch (e) { if (e.code !== "EAGAIN") throw e; Atomics.wait(idle, 0, 0, 1); }
+    }
+  } catch (e) { if (e.code !== "EPIPE") throw e; }
 }

package/lsp.mjs

@@ -45,7 +45,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, resolveReasonClasses, fatalPolicyErrors } from "./policy.mjs";
+import { discoverConfigPolicy, evaluatePolicy, parsePolicy, scopeMatches, reportNetClasses, parseUnknownAliases, discoverConfigText, policyVocabularyAnchor, policyErrorText, unanswerableScoped, resolveReasonClasses, fatalPolicyErrors, policyZeroRules } 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.
@@ -324,6 +324,18 @@ function activePolicyParsed(text) {
   warnOnce(`candor-lsp: ${policyErrorText(activePolicyPath ?? "(policy)", fatal)}\n  No gate diagnostics are produced from it — their ABSENCE here is the refusal, not an all-clear.`);
   return null;
 }
+// ⟨0.28⟩ SPEC §2/§6.2 — DID THIS CONFIGURED POLICY ASK ANYTHING AT ALL? Every rule vector, never a
+// subset: keying on `deny` alone would call an ordinary allow-only or forbid-only gate empty.
+const policyAskedNothing = (pol) => !!pol && !pol.deny.length && !pol.allow.length && !pol.forbid.length;
+// The editor has no exit code and no JSON document, so both of this rung's channels collapse onto the
+// one it does have. Same `warnOnce` shape (and same reasoning) as the judged-nothing warning below: there
+// is no line to pin it to, and a per-keystroke popup is how an advisory gets turned off.
+const zeroRulePolicyWarn = (what) =>
+  warnOnce(`candor-lsp: ${policyZeroRules(activePolicyPath ?? "(policy)").why} — every line was ignored, the `
+    + `file is empty, or it holds only comments. ${what} A policy with no rules ASKS NOTHING, so the silence `
+    + `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.`);
+
 function diagnosticsFor(docPath) {
   const text = activePolicy();
   if (text === null || !hasReport(reportPrefix)) return [];
@@ -346,6 +358,21 @@ function diagnosticsFor(docPath) {
   // producer's project, in both the fabricating and the fail-open direction (see reportNetClasses).
   const dpol = activePolicyParsed(text);
   if (dpol === null) return [];
+  // ⟨0.28⟩ …and a CONFIGURED policy that parsed to ZERO RULES produces no squiggles either, which in an
+  // editor is indistinguishable from a gate that ran and found nothing — §6.2's harm on the surface where
+  // it is least visible, since the live gate's entire vocabulary IS the absence or presence of squiggles.
+  if (policyAskedNothing(dpol))
+    zeroRulePolicyWarn("No gate diagnostics can come from it.");
+  // ⟨0.28⟩ SPEC §6.2 — …AND THE LINES THE PARSE DROPPED, which is the same clause one fraction down: the
+  // zero-rule warning above fires only at ZERO survivors, so a policy where three of four lines were
+  // dropped produced the surviving rule's squiggles and nothing else. In an editor that reads as the
+  // whole gate, because squiggles ARE this surface's entire vocabulary. The CLI routes carry `ignored`
+  // on the verdict document; here there is no document, so the log channel carries it — once, with the
+  // line numbers, so the operator can go to them.
+  else if (dpol.ignored?.length)
+    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.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
@@ -487,12 +514,24 @@ function runWhatif(a) {
     return null;
   }
   const policyText = activePolicy();
-  const r = Q.whatif(Q.loadCallgraph(reportPrefix), a.fn, a.effect,
-                     policyText === null ? null : activePolicyParsed(policyText), scopeMatches);
+  const wpol = policyText === null ? null : activePolicyParsed(policyText);
+  const r = Q.whatif(Q.loadCallgraph(reportPrefix), a.fn, a.effect, wpol, scopeMatches);
   if (r === null) {
     showMessage(2, `candor: no function matching \`${a.fn}\` in the call graph — the report may be stale`);
     return null;
   }
+  // ⟨0.28⟩ SPEC §2 — a CONFIGURED policy that yielded zero rules asked nothing, and `✓ no policy rule
+  // fires` IS the prose spelling of `ok: true`. The pre-edit verdict is withheld on both this channel and
+  // the executeCommand RESULT (a thick client renders that); the blast radius is not a policy claim, so it
+  // is still counted in the message the operator gets. A policy that is NOT configured keeps its own
+  // "no policy discovered" wording below — that is the honest way to say "I am not gating".
+  if (policyAskedNothing(wpol)) {
+    zeroRulePolicyWarn("No pre-edit verdict can come from it.");
+    const zcallers = r.affected.filter((f) => !r.of.includes(f));
+    showMessage(2, `candor: the configured policy has NO RULES — no pre-edit verdict (blast radius only: `
+      + `${zcallers.length} caller(s) would inherit ${a.effect})`);
+    return { unevaluated: policyZeroRules(activePolicyPath ?? "(policy)").unevaluated };
+  }
   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
@@ -549,6 +588,15 @@ function runFix(a) {
   }
   const fpol = activePolicyParsed(policyText);
   if (fpol === null) return null;
+  // ⟨0.28⟩ SPEC §2 — the same caveat, before any `crossing` reading: `${a.effect} isn't forbidden here`
+  // from a policy that forbids nothing is vacuously true, and this surface is the one that ASKED for a
+  // fix. No `crossing` key on the result either — present exactly when the verb answered.
+  if (policyAskedNothing(fpol)) {
+    zeroRulePolicyWarn("No boundary fix can be computed from it.");
+    showMessage(2, `candor: \`${a.fn}\` — no fix computed: the configured policy has NO RULES, so there is `
+      + `no boundary to have crossed. The absence of a plan here is the caveat, not an all-clear.`);
+    return { unevaluated: policyZeroRules(activePolicyPath ?? "(policy)").unevaluated };
+  }
   const r = Q.fix(Q.loadCallgraph(reportPrefix), Q.loadReport(reportPrefix), a.fn, a.effect,
                   fpol, scopeMatches);
   if (r === null) {

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, resolveReasonClasses, fatalPolicyErrors } from "./policy.mjs";
+         unanswerableScoped, resolveReasonClasses, fatalPolicyErrors, policyZeroRules } from "./policy.mjs";
 
 const VERSION = createRequire(import.meta.url)("./package.json").version; // single-sourced, like scan.mjs
 
@@ -136,6 +136,22 @@ function policyOrThrow(text, policyPath) {
   if (fatal.length) throw new Error(policyErrorText(policyPath ?? "(policy)", fatal));
   return pol;
 }
+// ⟨0.28⟩ SPEC §2 — AN ADVISORY TOOL OVER A CONFIGURED ZERO-RULE POLICY ANSWERS WITH THE CAVEAT DOCUMENT,
+// RESULT KEYS WITHHELD. The CLI half is `emitZeroRuleCaveat` in query.mjs and this is the SAME document
+// through the same builder (`policyZeroRules`), because the agent surface is a channel these verbs answer
+// on and a caveat that exists on one of them is a caveat the other silently drops. MEASURED on the CLI
+// twins before this: `{"ok": true, "unverified": []}` / `{"crossing": false, "reason": "not-forbidden"}`
+// over `# no rules yet` — an all-clear produced by deleting the question, handed to a consumer that
+// cannot ask a follow-up. `fix` emits NO `crossing` key: that key is present exactly when the verb
+// answered. §6.2's gate REFUSES over the same policy (exit 2); these are advisory, so they disclose.
+const policyAskedNothing = (pol) => !!pol && !pol.deny.length && !pol.allow.length && !pol.forbid.length;
+// `policyZeroRules` also returns a `why` — the HUMAN sentence the gate's refusal puts in `reason`. The
+// caveat document carries only `unevaluated`, so it is not spread here rather than minted as a wire key.
+const zeroRuleCaveat = (policyPath, prefix) => {
+  const { unevaluated } = policyZeroRules(policyPath ?? "(policy)");
+  return { unevaluated, ...Q.completenessFields(Q.reportCompleteness(prefix)) };
+};
+
 // The repo's .candor/config (spec §3.4), from the report's directory upward — shared impl in policy.mjs.
 function configPolicy(prefix) {
   return discoverConfigPolicy(nodePath.dirname(nodePath.resolve(prefix)) || ".");
@@ -189,41 +205,109 @@ function capCallers(r) {
     truncated: true,
   };
 }
+// ⟨0.28⟩ SPEC §2 — THE COMPLETENESS CAVEAT, ON THE AGENT-FACING CHANNEL. The same reader and the same key
+// set as the CLI (`query-core`), never a second mechanism: the CLI and this server are one implementation,
+// and a caveat that exists on one of them is a caveat the other silently drops. MEASURED here, over the
+// standard post-⟨0.28⟩ artifact (`analyzed.count: 0` + a non-empty `unanalyzed`), before this wrapper:
+// `candor_where` → `{"effect":"Fs","directly":[],"inherited":[]}`, `candor_map` → `{}`,
+// `candor_blindspots` → `{"sources":[],"totalUnknown":0}`, `candor_reachable` →
+// `{"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.
+//
+// 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
+// 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.
+//
+//   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.
+//   candor_map   keyed by the operator's own MODULE names. The merged shape it used to take displaced a
+//                real module row to make space for the hedge, and the `@`-prefix escape is unavailable
+//                for the reason the ruling names candor-ts for: `@scope/name` is a key a module owns.
+//
+// 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.
+//
+// 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.
+//
+// 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) => {
+  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();
+};
+// ⟨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
+// run, so this surface cannot refuse a report the CLI answers. The fn-existence guard below already
+// unions the report's names, so a sidecar-less locator passed the guard and then computed over an
+// EMPTY graph: `candor_callers` returned `{of:[],direct:[],transitive:[]}` — "nobody calls this,
+// safe to edit" — to an agent, over a pair whose graph was present one key over. An ARMED pair (no
+// sidecar, report judged nothing) still fails closed: both sets are empty and the guard refuses.
+const graphOrReportEdges = (p, fns) => {
+  const cg = Q.loadCallgraph(p);
+  return Object.keys(cg).length ? cg : Q.reportCallsGraph(fns);
+};
 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) => capImpact(Q.impact(loadReportLoud(p), Q.loadCallgraph(p), a.fn)),
+    run: (a, p) => { const fns = loadReportLoud(p); return 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.",
     schema: { type: "object", properties: { effect: { type: "string", description: "Net|Fs|Db|Exec|Env|Clock|Ipc|Log|Rand|Clipboard|Unknown" }, ...reportArg }, required: ["effect"] },
-    run: (a, p) => capWhere(Q.where(loadReportLoud(p), a.effect)),
+    run: (a, p) => withCompleteness(p, capWhere(Q.where(loadReportLoud(p), a.effect))),
   },
   candor_reachable: {
     description: "What the program/fleet actually DOES at runtime: effects unioned over the entry points, with how many roots reach each and via which.",
     schema: { type: "object", properties: { ...reportArg } },
-    run: (_a, p) => Q.reachable(loadReportLoud(p)),
+    run: (_a, p) => withCompleteness(p, Q.reachable(loadReportLoud(p))),
   },
   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) => Q.path(loadReportLoud(p), Q.loadCallgraph(p), a.fn, a.effect),
+    run: (a, p) => { const fns = loadReportLoud(p); return 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(Q.loadCallgraph(p), a.fn)),
+    run: (a, 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) => Q.show(loadReportLoud(p), a.fn),
+    run: (a, p) => caveatInstead(p, () => 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) => Q.map(loadReportLoud(p)),
+    run: (_a, p) => caveatInstead(p, () => 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.",
@@ -236,6 +320,10 @@ const TOOLS = {
       const pol = a.policy ? policyOrThrow(confinedPolicyRead(a.policy, p), a.policy) : null;
       const r = Q.whatif(Q.loadCallgraph(p), a.fn, a.effect, pol, scopeMatches);
       if (r === null) throw new Error(`no function matching \`${clip(a.fn)}\` in the call graph`);
+      // ⟨0.28⟩ a CONFIGURED policy that parsed to zero rules asked nothing — the pre-edit verdict and the
+      // 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;
     },
   },
@@ -257,8 +345,13 @@ const TOOLS = {
       // The sidecar is the only graph a candor-ts report carries — fail loud (tool error) when it's absent,
       // never a degenerate empty-graph remedy. (/code-review.)
       if (!cg || Object.keys(cg).length === 0) throw new Error(`no call-graph sidecar for the report — fix needs it (re-scan with --out)`);
-      const r = Q.fix(cg, loadReportLoud(p), a.fn, a.effect, policyOrThrow(text, polPath), scopeMatches);
+      const fpol = policyOrThrow(text, polPath);
+      const r = Q.fix(cg, loadReportLoud(p), a.fn, a.effect, fpol, scopeMatches);
       if (r === null) throw new Error(`no function matching \`${clip(a.fn)}\` in the call graph`);
+      // ⟨0.28⟩ …and NO `crossing` key over a zero-rule policy: this tool's own description tells an agent
+      // to read `crossing` as the answer, and `crossing: false` from a policy that forbids nothing is
+      // vacuously true. Present exactly when the verb answered.
+      if (policyAskedNothing(fpol)) return zeroRuleCaveat(polPath, p);
       return r;
     },
   },
@@ -326,10 +419,47 @@ const TOOLS = {
       // caveat is ADDITIVE (the two existing keys keep their shape and meaning, and the field is absent
       // on every ordinary report) because the verdict itself must not move: the report asserts no effect,
       // so asserting one here would be the fabrication mirror of the silence being disclosed.
-      const judged = g.judgedNothing ? { judgedNothing: true,
-        caveat: "⟨0.24⟩ this report judged NOTHING (`analyzed.count` is 0, absent with no entries, or unreadable) — "
-              + "a green verdict here certifies nothing: absence from `functions` licenses no purity claim about any "
-              + "unit. Re-scan the sources you meant to gate, or point `report` at the package that has them." } : {};
+      //
+      // `judgedNothing` IS THE ARRAY HERE TOO, and it used to be a boolean. The old comment defended the
+      // boolean on one premise — "this tool's document is ONE gate verdict about ONE locator" — and that
+      // premise is contradicted in this very file: `report` is a PREFIX (DEFAULT_PREFIX, and
+      // `loadReportLoud`, whose own message reads "every report found at prefix … failed to load" and
+      // whose header says "over a multi-report prefix"). ONE VERDICT IS NOT ONE REPORT. SPEC §2 gives
+      // precisely that reason for the array: "a verb reading a prefix answers over many sibling reports,
+      // and WHICH of them judged nothing is the whole of the actionable content".
+      //
+      // The boolean did not merely lose "which". `loadGateReport` computes it as an AND over the siblings
+      // (`let judgedNothing = true`, cleared by the first report with content), so the PARTIAL case — the
+      // common one — emitted `false` and therefore NO CAVEAT AT ALL. MEASURED 2026-08-13 on a two-report
+      // prefix, one judged-nothing and one carrying a real function: the boolean said `false` while
+      // `reportCompleteness` named `r.empty.json`. A green gate with NO disclosure over a surface half of
+      // which was never judged — on the one channel whose consumer cannot ask a follow-up question, which
+      // is the argument this file already makes immediately below about `ignored`.
+      //
+      // ⟨0.28⟩ `noManifest` (SPEC §2 row 3) rides with it, for the reason that row exists: a report with
+      // no `analyzed` key declares nothing, and listing it under `judgedNothing` would be the false
+      // disclosure the rung split out. The `unverified` route in this same file already emitted both;
+      // this route is its sibling and was never brought along.
+      //
+      // ADDITIVE STILL: `ok` does not consult either key. ⟨0.24⟩'s carve-out keeps the gate verdict's
+      // `ok`, and the report asserts no effect — asserting one here would be the fabrication mirror of
+      // the silence being disclosed.
+      // ⟨0.28⟩ SPEC §6.2 `ignored` — THE LINES THE PARSE DROPPED, on the surface where their absence is
+      // worst. MEASURED here 2026-08-12 over a policy whose 3 of 4 lines were dropped: this tool returned
+      // `{"ok":true,"violations":[]}` while the per-line warnings went to the SERVER's stderr, a channel
+      // the calling agent never reads — so the one consumer that cannot ask a follow-up question was
+      // handed a green verdict from a gate three-quarters of which was never asked. Same shape and same
+      // builder as both CLI routes; omitted when nothing was dropped, and `ok` does not consult it.
+      const ignored = pol.ignored?.length ? { ignored: pol.ignored } : {};
+      const gcomp = Q.reportCompleteness(p);
+      const judged = (gcomp.judgedNothing?.length || gcomp.noManifest?.length)
+        ? { ...(gcomp.judgedNothing?.length ? { judgedNothing: gcomp.judgedNothing } : {}),
+            ...(gcomp.noManifest?.length ? { noManifest: gcomp.noManifest } : {}),
+        caveat: "⟨0.24⟩ report(s) under this locator judged NOTHING (`analyzed.count` is 0, or absent with no "
+              + "entries) — a green verdict does not certify them: absence from `functions` licenses no purity "
+              + "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 } : {};
       // ⟨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
@@ -339,12 +469,12 @@ const TOOLS = {
       // `unevaluated` — WHICH rules went unenforced and why — which is exactly what an agent needs to fix it.
       // The document is still fail-closed to the naivest possible reader (`ok` is false), and it is the same
       // shape the agent would get from `--gate-json`, so one consumer parses both routes.
-      if (v.length) return { ok: false, violations: v, ...(unevaluated.length ? { unevaluated } : {}), ...inc, ...judged };
+      if (v.length) return { ok: false, violations: v, ...(unevaluated.length ? { unevaluated } : {}), ...ignored, ...inc, ...judged };
       if (unevaluated.length)
         return { ok: false, refused: true,
                  reason: `${unevaluated.length} policy rule(s) could not be evaluated against this report`,
                  unevaluated, ...inc, ...judged };
-      return { ok: !incomplete, violations: v, ...inc, ...judged };
+      return { ok: !incomplete, violations: v, ...ignored, ...inc, ...judged };
     },
   },
   candor_unverified: {
@@ -380,19 +510,30 @@ const TOOLS = {
       // one of them. `candor_gate` already refuses to read green over `unanalyzed`; this returned
       // `ok:true` with an empty array over the identical bytes, on the surface an agent trusts and no
       // human reads. Same `advisoryAnswer` the CLI applies, so the two cannot drift.
-      return Q.advisoryAnswer(Q.unverified(loadReportLoud(p), policyOrThrow(text, polPath), scopeMatches),
-                              Q.reportUnanalyzed(p));
+      // ⟨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.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.
+      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.
+      return Q.advisoryAnswer(Q.unverified(loadReportLoud(p), upol, scopeMatches),
+                              ucomp.unanalyzed, ucomp.judgedNothing, ucomp.unreadable, ucomp.noManifest);
     },
   },
   candor_containment: {
     description: "Per boundary effect (Db/Net/Exec/Fs/Ipc/Clipboard): how contained it is in one architectural layer — the dispersion diagnostic (spec §6.1). Not a score; per-effect facts.",
     schema: { type: "object", properties: { ...reportArg } },
-    run: (_a, p) => Q.containment(loadReportLoud(p)),
+    run: (_a, p) => withCompleteness(p, Q.containment(loadReportLoud(p))),
   },
   candor_blindspots: {
     description: "The Unknown SOURCES — calls the engine genuinely could not resolve (reflection, wide dispatch, fn-pointers) — ranked by how many functions inherit Unknown through each. Turns a high-Unknown report into a short worklist.",
     schema: { type: "object", properties: { ...reportArg } },
-    run: (_a, p) => capBlindspots(Q.blindspots(loadReportLoud(p), Q.loadCallgraph(p))),
+    run: (_a, p) => withCompleteness(p, capBlindspots(Q.blindspots(loadReportLoud(p), Q.loadCallgraph(p)))),
   },
   candor_diff: {
     description: "The per-function effect delta versus a baseline report: gained (introduced vs inherited) and lost effects. 'What did this change do to the effect surface?'.",
@@ -420,9 +561,13 @@ const TOOLS = {
       // ⟨0.15 staged⟩ coverage disclosure — the SAME gainsCoverage the CLI verb spreads (the parity
       // rule): optional `coverage` (current envelope's ledger) + `coverageDelta` (baseline names
       // differ), both omitted when nothing applies — no other field of the tool result changes.
+      // ⟨0.28⟩ …and the ⟨0.21⟩ manifest on the same terms, BOTH SIDES separately (`gainsCompleteness`,
+      // the same one the CLI verb spreads). SPEC §2 puts the obligation on the READING, not the route the
+      // report arrived by, and this is the route an agent takes: an "it gained nothing" over a report that
+      // judged nothing is the false all-clear, and no human sees this channel.
       return { baseline_version: Q.reportVersion(b) ?? "", engine_version: Q.reportVersion(p) ?? "",
                ...Q.gains(loadReportLoud(p), loadReportLoud(b), Q.loadCallgraph(b)),
-               ...Q.gainsCoverage(p, b) };
+               ...Q.gainsCoverage(p, b), ...Q.gainsCompleteness(p, b) };
     },
   },
   candor_activity: {
@@ -579,7 +724,22 @@ function handle(msg) {
       const prefix = t.noReport ? null : resolvePrefix(args);
       // A tool that targets a `fn` gets a clear "not found" rather than a silently-empty result —
       // an agent must distinguish "no such function" from "found, nothing calls it".
-      if (args.fn !== undefined) {
+      //
+      // ⟨0.28⟩ …BUT THE HEDGE OUTRANKS THE EXISTENCE GUARD, and this guard sits in the DISPATCHER, so it
+      // pre-empted the caveat for EVERY fn-taking tool rather than one. Over a judged-nothing report
+      // `candor_show`/`candor_impact`/`candor_callers`/`candor_path` answered "no function matching …"
+      // — a determined negative about the code, asserted by a report that examined none of it, to an
+      // agent that acts on it. "Found, nothing calls it" and "no such function" are indeed different
+      // answers and the guard is right to separate them; what it cannot do is choose between them from
+      // a report that judged nothing. Skipping it here hands the case to each tool's own completeness
+      // reader, which emits the caveat document (Rung A).
+      //
+      // CORRUPTION IS NOT A HEDGE and must stay loud: `unreadable` falls through to the guard, whose
+      // `loadReportLoud` throws — §2 ⟨0.24⟩ impeaches a document whose signature keys cannot be read
+      // rather than qualifying it.
+      const fnComp = t.noReport ? null : Q.reportCompleteness(prefix);
+      const fnHedges = !!fnComp && !fnComp.unreadable?.length && Q.mustHedge(fnComp);
+      if (args.fn !== undefined && !fnHedges) {
         const names = [...new Set([...Object.keys(Q.loadCallgraph(prefix)), ...loadReportLoud(prefix).map((e) => e.fn)])];
         if (Q.matches(names, args.fn).length === 0)
           return result(id, { content: [{ type: "text", text: `candor: no function matching \`${clip(args.fn)}\` in this report` }], isError: true });

package/package.json

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