candor-ts 0.23.1 → 0.25.0

package/AGENTS.md

@@ -12,7 +12,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.23)."*
+> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.25)."*
 > 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`.
 >
@@ -80,8 +80,31 @@ A dist-CJS export unit (a `module.exports` surface scanned with `--allow-js`) ca
 (a path list, or a directory of `*.json`); an unclassified call into a package with a loaded
 report inherits that function's recorded transitive effects and literal surfaces, joined by the
 report's `hash` (`package#LocalName`). A report produced by a different candor-ts version is
-downgraded to `Unknown` rather than silently trusted (spec §2.1). Caveat: a type-only boundary
-(`import type` …, the tRPC style) has no runtime calls to inherit through — nothing to join.
+downgraded to `Unknown` rather than silently trusted, and grants that package **no coverage** — so a key it
+does not answer falls back to the κ ledger's `invisible` hedge rather than reading pure (spec §2.1). **A report
+that declares itself INCOMPLETE** — a non-empty ⟨0.21⟩ `unanalyzed` — grants **no coverage** either, for the
+same reason read one step earlier: spec §2 rule 3 makes a report's silence a purity claim, and this one has
+just said it never read some of its own source. Its entries are kept unchanged (they were derived from source
+it *did* read); only its silence hedges, and an `import` backed only by such a report discloses
+`Unknown[incomplete-dep:<pkg>]`. Chaining an incomplete report is therefore never worse than not chaining it.
+**And a report that JUDGED NOTHING** — ⟨0.24⟩ `analyzed.count: 0`, or no manifest and no entries, or a manifest
+too garbled to read — grants **no coverage** either: rule 3 turns a report's silence into a purity claim, and a
+report that judged nothing is all silence, so its package stays in the κ ledger exactly as if it were never
+chained. Keyed on the COUNT and never on `functions` being empty — `count: n > 0` with `functions: []` is a
+legitimate all-pure claim rule 3 says to believe, and it is untouched. The same reading binds every route a
+report arrives by (`gate --report`, MCP `candor_gate`, the LSP gate), each of which discloses the count-0 case
+rather than answering "no violations" flat; the verdict itself does not move, because the report gives no
+evidence of an effect and asserting one would be fabrication.
+Caveat: a type-only boundary (`import type` …, the tRPC style) has no runtime calls to inherit through —
+nothing to join.
+
+**Changing a report KEY is a wire change: bump `package.json`'s version in the same commit.** `candor.version`
+is the only discriminator §2.1 has, so two builds that disagree about a key while sharing a version string
+disarm it — and note what the bump does and does not buy. It downgrades the entries a report *carries*; it
+cannot conjure a key the report *lacks*, so an already-installed consumer that looks up a key this build no
+longer emits simply misses, whatever the version says. That direction is unfixable from the producing side
+(the consumer's code is frozen), which is why a stale report is denied coverage here: it is what stops the
+NEXT key change reading as a purity claim.
 
 ## Query it (same names/shapes as the Rust and JVM engines — candor-spec §3.1)
 
@@ -101,6 +124,21 @@ Q whatif   $P <fn> <Effect> [policy]  # pre-edit gate verdict (exit 1 if it woul
 Q fix      $P <fn> <Effect> <policy>  # the boundary FIX: where the effect belongs + the hoist refactor
 Q unverified $P <policy> [--strict]  # pure/deny layers that PASS but are Unknown (not PROVABLY clean)
 Q fix-gate $P <policy>              # a fix for EVERY crossing — the loop's block-message remedy
+                                    # ⟨0.24⟩ BOTH, and `fix`: an advisory verb may be LESS certain than
+                                    # the gate, never MORE (SPEC §3.2). Where `gate --report` REFUSES a
+                                    # narrowed rule for want of evidence, `unverified` NAMES the function
+                                    # with the MISSING EVIDENCE as its reason (never a derived class),
+                                    # `fix-gate`/`fix` offer NO remedy premised on it, both carry the
+                                    # gate's `unevaluated:[{rule,why}]`, `ok` is OMITTED, `--strict` → 2.
+Q gate --report $P --policy <file> [--json] [--gate-json <f>]
+                                    # ⟨0.24⟩ apply a policy to an EXISTING report, NO scan (exit 0/1/2).
+                                    # The supply-chain verb: gate a DEPENDENCY's published report. Reads
+                                    # the report and nothing else — no callgraph sidecar, no chained dep,
+                                    # no re-classification; an ABSENT entry stays absent (the ⟨0.21⟩
+                                    # purity claim). Its --gate-json is BYTE-EQUAL to `scan --policy`'s.
+                                    # `forbid`, `allow`, and a class-scoped `deny` whose scoping datum
+                                    # the report does not carry are REFUSED (exit 2), never evaluated on
+                                    # partial evidence — gate those at scan time instead.
 Q diff     $P <baseline-prefix> 1   # per-function effect delta (exit 1 on a gained effect)
 Q gains    $P <baseline-prefix>     # supply-chain alarm: {gained, byFunction} — effects a surface grew
 Q reachable $P 1                    # what the app DOES at runtime: effects over the entry points
@@ -159,9 +197,19 @@ want-JSON flag.
   `class PgStore implements Store`) resolves to the local implementors when the dispatch is narrow
   (≤12 classes) — the layered-DI pattern carries its real effects; only an interface with no
   visible implementor still reads `Unknown` (`dispatch:<Type>`).
-- **`unknownWhy` names each direct Unknown's origin** (`call:jwt.sign`, `callback:param#0`,
-  `dispatch:<Type>`) — triage starts at the named site. Inheritors carry `Unknown` with no why;
-  follow the callgraph down to the root.
+- **`unknownWhy` names each direct Unknown's origin** as `kind:detail` — triage starts at the named
+  site. Inheritors carry `Unknown` with no why; follow the callgraph down to the root. The `kind` is
+  drawn from §4's closed **five**-kind vocabulary — `reflect:` / `native:` / `dispatch:` /
+  `callback:` / `ambiguous:` — of which candor-ts's language model produces three:
+  `reflect:eval`, `reflect:defineProperty:dynamic-key` (TypeScript folds its native boundary into
+  `reflect:`, so no bare `native:`), `callback:param#0`, and `dispatch:<pkg>.<Type>.<member>` —
+  the one **normative** detail shape, and what the `callers --include-unknown` frontier resolves
+  overrides against. It also carries `no-node_modules:<pkg>` for the *setup* class (a declared dep
+  that isn't installed — a mis-configuration, not a blind spot). A kind candor-ts never emits can
+  still appear in its output: a chained dependency's reasons are relayed verbatim, and every query
+  verb reads other engines' reports — `ambiguous:` (name resolution was ambiguous, so no owner type
+  was formed at all) is candor-rust's and arrives that way. Any kind outside the five round-trips
+  untouched and classifies through the conservative catch-all (§2 forward-compatibility).
 - **`entryPoint: true` marks runtime-invoked roots** (Nest `@Get/@Post/…` handler methods, Next
   `route.ts` HTTP exports and `middleware`) — their effects are never orphaned; `reachable` unions
   over them. Pure entry points stay visible in the report.

package/README.md

@@ -34,6 +34,14 @@ node query.mjs blindspots  .candor/report          # the Unknown SOURCES, ranked
 node query.mjs whatif   .candor/report db.save Net policy  # pre-edit gate verdict (exit 1)
 node query.mjs diff     .candor/report baseline 1  # per-function effect delta (exit 1 on a gain;
                                                    #   a baseline from a DIFFERENT build ⇒ disclosed ⚠ + exit 0)
+node query.mjs gate --report dep/.candor/report.json --policy arch.policy --gate-json -
+                                                   # ⟨0.24⟩ apply a policy to an EXISTING report, NO scan
+                                                   #   (exit 0/1/2) — the supply-chain verb: gate a
+                                                   #   DEPENDENCY's published report without its source.
+                                                   #   Reads that report and nothing else; a rule the wire
+                                                   #   cannot answer (`forbid`, `allow`, a class-scoped
+                                                   #   `deny` with the scoping field absent) is REFUSED
+                                                   #   with exit 2, never evaluated on partial evidence.
 ```
 
 A checked-in **`.candor/config`** (spec §3.4) replaces the env wiring — `policy arch.policy` /
@@ -184,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.23" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
+| `{ candor: { version, toolchain, spec: "0.25" }, 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 |
 
@@ -202,9 +210,10 @@ read the Rust source".
 
 ## Status
 
-0.19.x, speaking candor-spec 0.23: the analysis core, the gate (`--policy` / `--gate-json` /
+0.19.x, speaking candor-spec 0.25: the analysis core, the gate (`--policy` / `--gate-json` /
 `.candor/config`), the full §3.1 query surface (including `containment`, `blindspots`, the
-`--include-unknown` dispatch frontier), the MCP server, the LSP server, and the watch loop are
+`--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
 real, behaviorally tested (`npm test` — the behavioral suite across six harnesses), **soundness-fuzzed
 with verified teeth** (`node fuzz.mjs` — spec §7.13: generated effect chains through every encoded
 call form, any silent-pure = red), and conformance-held against the Rust/JVM/Swift engines. The

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 } from "./policy.mjs";
+import { discoverConfigPolicy, evaluatePolicy, parsePolicy, scopeMatches, reportNetClasses, parseUnknownAliases, discoverConfigText, policyVocabularyAnchor, policyErrorText, unanswerableScoped, resolveReasonClasses, fatalPolicyErrors } 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,24 +280,91 @@ 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.24⟩ the file `activePolicy()` last read, so the vocabulary anchor can be the POLICY FILE's dir.
+let activePolicyPath = null;
 function activePolicy() {
   const env = process.env.CANDOR_POLICY;
   if (env) {
-    if (fs.existsSync(env)) return fs.readFileSync(env, "utf8");
+    if (fs.existsSync(env)) { activePolicyPath = env; return fs.readFileSync(env, "utf8"); }
     // Set-but-missing must be LOUD (the family's configured-but-unusable posture — scan exits 2 here).
     // This is an advisory surface, so: disclose the policy-source swap, then fall through to discovery.
     warnOnce(`candor-lsp: CANDOR_POLICY is set but ${env} does not exist — falling back to .candor/config discovery (diagnostics may reflect a different policy than you configured)`);
   }
   const from = reportPrefix ? nodePath.dirname(nodePath.resolve(reportPrefix)) : rootPath;
   const cfg = from ? discoverConfigPolicy(from) : null;
-  if (cfg && fs.existsSync(cfg.policyPath)) return fs.readFileSync(cfg.policyPath, "utf8");
+  if (cfg && fs.existsSync(cfg.policyPath)) { activePolicyPath = cfg.policyPath; return fs.readFileSync(cfg.policyPath, "utf8"); }
+  activePolicyPath = null;
+  return null;
+}
+
+/**
+ * ⟨0.24⟩ ONE policy PARSE for this surface — the LSP twin of query.mjs's `loadPolicyOrDie` and mcp.mjs's
+ * `policyOrThrow`, and it closes the same drift. Every call site here parsed with NO alias map, so a rule
+ * written against a checked-in `unknown-alias` was silently WIDENED to the bare effect: the editor drew
+ * squiggles for a class the operator had deliberately excluded, and drew none for the one they had named.
+ * The vocabulary anchors at the POLICY FILE, as it does on both CLI routes, so the same policy means the
+ * same thing in the editor and in the gate that judges the edit.
+ *
+ * On a policy this engine CANNOT HONOUR AS WRITTEN (§6.2 `be0b9a9`), it returns null and says so ONCE.
+ * This surface has no exit code, so the enforcement posture cannot be borrowed wholesale — but evaluating
+ * a policy the engine has silently rewritten is the fail-open the ruling exists to close, and it is worse
+ * here than elsewhere because a squiggle that does not appear is invisible. What the disclosure buys is
+ * that the empty editor is EXPLAINED rather than read as a clean bill of health, which is the same
+ * argument this file already makes about a report that judged nothing.
+ */
+function activePolicyParsed(text) {
+  const errs = [];
+  const aliases = parseUnknownAliases(discoverConfigText(policyVocabularyAnchor(activePolicyPath, rootPath || process.cwd())), errs);
+  const pol = parsePolicy(text, aliases);
+  errs.push(...pol.errors);
+  // ⟨0.24⟩ FATAL only: `errors` also carries every LINE the parser dropped whole (SPEC §3.1
+  // `195d45a`) — additive to the `parsepolicy` witness, deliberately silent about the gate.
+  const fatal = fatalPolicyErrors(errs);
+  if (!fatal.length) return pol;
+  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;
 }
 function diagnosticsFor(docPath) {
   const text = activePolicy();
   if (text === null || !hasReport(reportPrefix)) return [];
   const fns = Q.loadReport(reportPrefix);
-  const violations = evaluatePolicy(parsePolicy(text), fns, Q.loadCallgraph(reportPrefix));
+  // ⟨0.24⟩ A report that JUDGED NOTHING is not a clean bill of health, and this surface is where that is
+  // hardest to notice: the live gate's whole vocabulary is squiggles, and a report with `analyzed.count: 0`
+  // has no entries, so it produces none — an empty editor reads as "the gate is green" when the truth is
+  // that nothing was ever judged. SPEC §2's three-row table, bound here by §3.1 ⟨0.24⟩ ("the obligation is
+  // on the reading, not on the route by which the report arrived"); this route takes a `report` locator,
+  // so a FOREIGN report arrives by it. The channel is the LOG and `warnOnce` rather than a diagnostic on
+  // every publish, because there is no line to pin it to and a per-keystroke popup is how an advisory gets
+  // turned off. The verdict is untouched: no effect is asserted that the report does not carry.
+  if (Q.reportJudgedNothing(reportPrefix))
+    warnOnce(`candor-lsp: the report at ${reportPrefix} judged NOTHING (⟨0.24⟩ \`analyzed.count\` is 0, absent with no `
+      + `entries, or unreadable) — no gate diagnostics can come from it, and their absence is NOT an all-clear: `
+      + `absence from \`functions\` licenses no purity claim about any unit. Re-scan the sources you meant to gate `
+      + `(candor-ts <src> --out ${reportPrefix}).`);
+  // ⟨0.24⟩ `netClass` VERBATIM off the wire — the same report-route rule as the MCP `candor_gate` tool and
+  // `gate --report`; re-deriving it here would answer with the CONSUMER's `net-partner` evidence about the
+  // producer's project, in both the fabricating and the fail-open direction (see reportNetClasses).
+  const dpol = activePolicyParsed(text);
+  if (dpol === null) return [];
+  // ⟨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
+  // where `gate --report` exits 2 (a squiggle that does not appear is the least visible false all-clear this
+  // project has), and `deny Net[unknown-host]` drew one whose message ASSERTS a destination class the report
+  // 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 });
+  const { unevaluated: dunevaluated, withhold: dwithhold } =
+    unanswerableScoped(dpol, fns, resolveReasonClasses(fns, Q.loadCallgraph(reportPrefix)), dnet);
+  // The surface has no exit code, so the refusal is carried the way this file already carries its other two
+  // (the unhonourable policy, the judged-nothing report): ONE log line naming the rules, so the missing
+  // squiggle is EXPLAINED rather than read as a clean bill of health. Per rule, not per keystroke — warnOnce
+  // keys on the message, and the message is a function of the policy and the report, not of the edit.
+  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(dpol, fns, Q.loadCallgraph(reportPrefix),
+                                    new Map(), new Set(), dnet, dwithhold);
   const locByFn = new Map(fns.filter((e) => e.loc).map((e) => [e.fn, locParts(e.loc)]));
   const out = [];
   for (const v of violations) {
@@ -360,7 +427,8 @@ function codeActions(docPath, uri, range) {
   // function that actually violates the boundary. Same policy source as the diagnostics + the whatif action.
   const policyText = activePolicy();
   if (policyText !== null && hasReport(reportPrefix)) {
-    const pol = parsePolicy(policyText);
+    const pol = activePolicyParsed(policyText);
+    if (pol === null) return out;
     const cg = Q.loadCallgraph(reportPrefix);
     const fns = Q.loadReport(reportPrefix);
     for (const eff of Q.CONTAINED) {
@@ -420,23 +488,36 @@ function runWhatif(a) {
   }
   const policyText = activePolicy();
   const r = Q.whatif(Q.loadCallgraph(reportPrefix), a.fn, a.effect,
-                     policyText === null ? null : parsePolicy(policyText), scopeMatches);
+                     policyText === null ? null : activePolicyParsed(policyText), scopeMatches);
   if (r === null) {
     showMessage(2, `candor: no function matching \`${a.fn}\` in the call graph — the report may be stale`);
     return null;
   }
   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
+  // surface becomes the one place the defect still lives — and it is the sharpest place for it, because
+  // `rules[0]` is now the operator's RAW line. Without the condition the squiggle would read
+  // `✗ deny Net[unknown-host] app would fire`: a narrowed rule beside an unconditional verdict, which SPEC
+  // §3.1 calls WORSE than printing the rule stripped of its filter, since it reads as a narrowing candor
+  // evaluated and did not.
+  const condOf = new Map(r.violations.filter((v) => v.conditional).map((v) => [v.rule, v.conditional]));
   const verdict = policyText === null
     ? `candor: no policy discovered — blast radius only: ${callers.length} caller(s) would inherit ${a.effect}`
     : rules.length
-      ? `✗ ${rules[0]} would fire — ${callers.length} caller(s) inherit ${a.effect}`
+      ? `✗ ${rules[0]} would fire${condOf.has(rules[0]) ? ` IF ${condOf.get(rules[0])}` : ""} — ${callers.length} caller(s) inherit ${a.effect}`
       : `✓ no policy rule fires — ${callers.length} caller(s) would inherit ${a.effect}`;
   showMessage(rules.length ? 2 : 3, verdict);                    // warning when a rule fires, info otherwise
   if (typeof a.uri === "string" && Number.isInteger(a.line)) {   // the detail, pinned at the fn's line
     const head = callers.slice(0, 10);
     const lines = [`what if ${r.of.join(", ")} performed ${a.effect}? ${verdict}`];
     if (rules.length > 1) lines.push(`rules: ${rules.join("; ")}`);
+    // The one-liner has room for the condition but not for WHY there is one; the pinned detail has room for
+    // both, and the reason is the half that stops an operator reading a fail-closed hedge as a false alarm.
+    for (const [rule, c] of condOf)
+      lines.push(`conditional — \`${rule}\` fires IF ${c}. That rule NARROWS, and the effect you have not `
+                 + "written yet has no class to match, so candor charges it fail-closed rather than guessing "
+                 + "which class your edit would land in.");
     lines.push(head.length
       ? `callers: ${head.join(", ")}${callers.length > head.length ? ` +${callers.length - head.length} more` : ""}`
       : "no callers — the blast radius is the function itself");
@@ -466,12 +547,26 @@ function runFix(a) {
     showMessage(2, "candor: no policy discovered — a fix is defined relative to a boundary; set CANDOR_POLICY or check one into .candor/config");
     return null;
   }
+  const fpol = activePolicyParsed(policyText);
+  if (fpol === null) return null;
   const r = Q.fix(Q.loadCallgraph(reportPrefix), Q.loadReport(reportPrefix), a.fn, a.effect,
-                  parsePolicy(policyText), scopeMatches);
+                  fpol, scopeMatches);
   if (r === null) {
     showMessage(2, `candor: no function matching \`${a.fn}\` in the call graph — the report may be stale`);
     return null;
   }
+  // ⟨0.24⟩ SPEC §3.2 `4fd140c` — THE REFUSAL, BEFORE the `crossing` test and not folded into it. `Q.fix`
+  // now returns `{refused:true, unevaluated}` with NO `crossing` key where the gate could not adjudicate the
+  // boundary, and a falsy-`crossing` reading of that lands on "isn't forbidden here; no boundary fix
+  // needed" — the derived second opinion, delivered as a clean bill of health, on the surface that ASKED
+  // for a fix. Same disclosure the diagnostics path already makes (dunevaluated), repeated here because a
+  // code action can be invoked on a file whose diagnostics were never published.
+  if (r.refused) {
+    showMessage(2, `candor: \`${a.fn}\` — no fix computed: the gate could NOT judge ${a.effect} here (this report does not carry the evidence the policy narrows on), and a hoist plan for a boundary the gate could not adjudicate would rest on a guess`);
+    for (const u of r.unevaluated ?? [])
+      logMessage(`candor-lsp: ${u.why}\n  NO fix is offered for that rule — the ABSENCE of a remedy here is the refusal, not an all-clear.`);
+    return r;
+  }
   if (!r.crossing) {
     showMessage(3, `candor: \`${a.fn}\` — ${a.effect} isn't forbidden here; no boundary fix needed`);
     return r;

package/mcp.mjs

@@ -19,7 +19,9 @@ import fs from "node:fs";
 import { createRequire } from "node:module";
 import nodePath from "node:path";
 import * as Q from "./query-core.mjs";
-import { discoverConfigPolicy, evaluatePolicy, parsePolicy, scopeMatches } from "./policy.mjs";
+import { discoverConfigPolicy, evaluatePolicy, parsePolicy, scopeMatches, reportNetClasses,
+         parseUnknownAliases, discoverConfigText, policyVocabularyAnchor, policyErrorText,
+         unanswerableScoped, resolveReasonClasses, fatalPolicyErrors } from "./policy.mjs";
 
 const VERSION = createRequire(import.meta.url)("./package.json").version; // single-sourced, like scan.mjs
 
@@ -68,10 +70,19 @@ const clip = (s, n = 120) => { s = String(s); return s.length > n ? s.slice(0, n
 // corrupt report — the §4 cardinal sin, exactly what the CLI's loadReportOrDie exits 2 on. The throw
 // surfaces as the same isError result shape every other tool failure uses. EVERY tool that loads a
 // report (main prefix or baseline) goes through this — never bare Q.loadReport.
-function loadReportLoud(p) {
+// `partialIsFatal` raises the bar from "NOTHING parsed" to "not EVERYTHING parsed", and `candor_gate`
+// passes it because that tool emits a VERDICT: `{ok: true, violations: []}` over a multi-report prefix
+// with one clean sibling and one truncated one is a green document over a package half of whose signature
+// never loaded, and the disclosure Q.loadReport writes goes to the SERVER's stderr — a channel the calling
+// agent never reads. Same rule, same argument as the CLI `gate --report` (see query.mjs). The read-only
+// tools keep the looser bar deliberately: they return what they found rather than asserting a clean bill
+// of health, so the partial answer is a smaller claim than a green gate.
+function loadReportLoud(p, { partialIsFatal = false } = {}) {
   const fns = Q.loadReport(p);
-  if (fns.length === 0 && fns.hardFail)
-    throw new Error(`every report found at prefix \`${clip(p)}\` failed to load — refusing to report an empty (all-clear) answer over a corrupt report; re-run the scan`);
+  if (fns.hardFail && (partialIsFatal || fns.length === 0))
+    throw new Error(fns.length === 0
+      ? `every report found at prefix \`${clip(p)}\` failed to load — refusing to report an empty (all-clear) answer over a corrupt report; re-run the scan`
+      : `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`);
   return fns;
 }
 // The confinement root for a caller-supplied policy path: the repo the report belongs to — the
@@ -98,6 +109,33 @@ function confinedPolicyRead(policyPath, prefix, root = policyRoot(prefix)) {
   try { return fs.readFileSync(abs, "utf8"); }
   catch { throw new Error(`policy \`${clip(policyPath)}\` could not be read — NOT evaluated (a missing gate source must be loud, never a clean verdict)`); }
 }
+/**
+ * ⟨0.24⟩ ONE policy PARSE for every tool here that consults one — the MCP twin of query.mjs's
+ * `loadPolicyOrDie`, and it closes the same two defects on the agent-facing surface.
+ *
+ * These tools called `parsePolicy(text)` with NO alias map, so a rule written against a checked-in
+ * `unknown-alias` was silently REWRITTEN — widened to the bare effect — in the very tools an agent
+ * consults before and after an edit, while the CLI gate honoured it. And with ⟨0.24⟩ making an
+ * unrecognised value token a POLICY ERROR (§6.2 `382a7e0`/`be0b9a9`), `candor_gate` would otherwise
+ * have kept enforcing a policy it cannot honour as written — the narrowing case stops gating what the
+ * operator spelled while the gate still looks armed, which is the fail-open the ruling exists to
+ * close, arriving here through the surface an agent trusts most.
+ *
+ * The vocabulary anchors at the POLICY FILE (§3.1 `99eb4e9`), as it does on both CLI routes, so the
+ * same policy means the same thing however it is reached. A policy error throws, which the tool layer
+ * renders as `isError` — the MCP shape of the CLI's exit 2.
+ */
+function policyOrThrow(text, policyPath) {
+  const errs = [];
+  const aliases = parseUnknownAliases(discoverConfigText(policyVocabularyAnchor(policyPath, process.cwd())), errs);
+  const pol = parsePolicy(text, aliases);
+  errs.push(...pol.errors);
+  // ⟨0.24⟩ FATAL only: `errors` also carries every LINE the parser dropped whole (SPEC §3.1
+  // `195d45a`) — additive to the `parsepolicy` witness, deliberately silent about the gate.
+  const fatal = fatalPolicyErrors(errs);
+  if (fatal.length) throw new Error(policyErrorText(policyPath ?? "(policy)", fatal));
+  return pol;
+}
 // 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)) || ".");
@@ -195,22 +233,23 @@ const TOOLS = {
       // typo'd/missing path silently evaluate with NO policy → `ok:true, violations:[]`, a false green
       // on the agent-facing pre-edit gate (exactly what the CLI whatif exits 2 to prevent). The read's
       // throw lands as the tool-level isError, mirroring the CLI's fail-closed posture.
-      const pol = a.policy ? parsePolicy(confinedPolicyRead(a.policy, p)) : null;
+      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`);
       return r;
     },
   },
   candor_fix: {
-    description: "THE BOUNDARY FIX: when `fn` performs `effect` in a layer the policy forbids (a violation candor_whatif/candor_gate reports), compute the architectural REMEDY — not just 'the domain can't do Net', but WHERE the effect belongs and the refactor to put it there: the direct call site to hoist, the forbidden-layer functions that become pure and thread the value as a parameter, and the nearest allowed-layer caller to perform the effect ({ crossing, site, deniedSpan, hoistTo, policyAlternative }). The remedial inverse of candor_whatif. Call this INSTEAD OF guessing a fix (adding `allow` to the domain, moving the I/O one call up, threading a handle the wrong way). Advisory: it names the structure, you write the code; the gate re-scan verifies. Uses `policy` if given, else the repo's checked-in .candor/config policy (spec §3.4).",
+    description: "THE BOUNDARY FIX: when `fn` performs `effect` in a layer the policy forbids (a violation candor_whatif/candor_gate reports), compute the architectural REMEDY — not just 'the domain can't do Net', but WHERE the effect belongs and the refactor to put it there: the direct call site to hoist, the forbidden-layer functions that become pure and thread the value as a parameter, and the nearest allowed-layer caller to perform the effect ({ crossing, site, deniedSpan, hoistTo, policyAlternative }). The remedial inverse of candor_whatif. Call this INSTEAD OF guessing a fix (adding `allow` to the domain, moving the I/O one call up, threading a handle the wrong way). Advisory: it names the structure, you write the code; the gate re-scan verifies. Uses `policy` if given, else the repo's checked-in .candor/config policy (spec §3.4). ALWAYS CHECK `refused` BEFORE `crossing`: where the policy narrows on evidence this report does not carry, candor_gate REFUSES and no remedy is computed — the result is `{ fn, effect, refused:true, unevaluated:[{rule, why}] }` WITH NO `crossing` KEY, an absent key rather than `crossing:false`, because 'no boundary fix needed' is a claim and that is the one thing the tool cannot claim here (spec §3.2: an advisory verb may be LESS certain than the gate, never MORE). Re-scan so the report carries the narrowing evidence, or widen the rule; do not read the missing plan as an all-clear.",
     schema: { type: "object", properties: { fn: { type: "string" }, effect: { type: "string" }, policy: { type: "string", description: "path to a §6.2 policy file (optional; defaults to the repo's .candor/config `policy`)" }, ...reportArg }, required: ["fn", "effect"] },
     run: (a, p) => {
       // The fix is defined relative to a boundary — a policy is required. Given → confined fail-closed read;
       // else the repo's checked-in policy (same resolution as candor_gate), so it works zero-config.
-      let text;
+      let text, polPath = a.policy ?? null;
       if (a.policy) text = confinedPolicyRead(a.policy, p);
       else {
         const cfg = configPolicy(p);
+        polPath = cfg?.policyPath ?? null;
         if (!cfg) throw new Error("no policy: pass `policy`, or check one into the repo's .candor/config (spec §3.4) — the fix is defined relative to the boundary it crosses");
         text = confinedPolicyRead(cfg.policyPath, p, cfg.repoRoot);
       }
@@ -218,24 +257,94 @@ 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, parsePolicy(text), scopeMatches);
+      const r = Q.fix(cg, loadReportLoud(p), a.fn, a.effect, policyOrThrow(text, polPath), scopeMatches);
       if (r === null) throw new Error(`no function matching \`${clip(a.fn)}\` in the call graph`);
       return r;
     },
   },
   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). 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, 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.",
     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;
+      let text, polPath = a.policy ?? null;
       if (a.policy) text = confinedPolicyRead(a.policy, p);
       else {
         const cfg = configPolicy(p);
+        polPath = cfg?.policyPath ?? null;
         if (!cfg) throw new Error("no policy: pass `policy`, or check one into the repo's .candor/config (spec §3.4)");
         text = confinedPolicyRead(cfg.policyPath, p, cfg.repoRoot);
       }
-      const v = evaluatePolicy(parsePolicy(text), loadReportLoud(p), Q.loadCallgraph(p));
-      return { ok: v.length === 0, violations: v };
+      // ⟨0.24⟩ THE SAME THREE-PIECE GATE THE CLI RUNS, because this tool is a REPORT route exactly as
+      // `gate --report` is, and the two pieces it was missing were BOTH live harms on the surface an
+      // agent trusts and no human reads. Measured, same report, same policy, against the CLI:
+      //
+      //   deny Unknown[reflect] app   -> CLI exit 2 (refused);  here {"ok":true,"violations":[]}
+      //   deny Net[unknown-host] app  -> CLI exit 2 (refused);  here FIRES, asserting
+      //                                                         "netClass":["unknown-host"] the report never carried
+      //
+      // (1) `authoritative` netClass. The DEFAULT mode maps only entries that CARRY the field and lets the
+      // rest fall back to `netClassesOf`, which floors an empty surface at `unknown-host`. That was chosen
+      // as a hedge because "neither surface can refuse a question" — but a hedge that ASSERTS a destination
+      // class in the violation record is not a hedge, it is the re-derivation §3.1 ⟨0.24⟩ forbids, in a
+      // field a consumer reads as the PRODUCER's judgment. Now that the tool discloses (3), it can refuse,
+      // so the authoritative mode is the correct one and the two routes read one report identically.
+      // (2) `withhold` (unanswerableScoped). A scoped `deny` whose narrowing evidence the wire does not
+      // carry is NOT EVALUATED, per (rule, function, effect) — never scored as a filter that succeeded for
+      // lack of evidence, and never fired on `reasonClassesMatch`'s empty-set floor, which is right for a
+      // MATCHER and wrong for a FIRING.
+      // (3) the disclosure, which is what makes (1) and (2) safe here: an unevaluated rule rides the tool
+      // result, so the agent sees WHICH part of its policy went unenforced rather than an empty list.
+      //
+      // ONE PASS over the report files (`loadGateReport`), the same reader `gate --report` uses: it yields
+      // the entries AND the ⟨0.21⟩/⟨0.15⟩ envelope out of the same bytes. Three separate reads (functions,
+      // 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);
+      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("; ")}. `
+            : "")
+          + (g.functions.length === 0
+            ? `every report found at prefix \`${clip(p)}\` failed to load — refusing to report an empty (all-clear) answer over a corrupt report; re-run the scan`
+            : `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);
+      const v = evaluatePolicy(pol, gfns, cg, new Map(), new Set(), gnet, withhold);
+      // ⟨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.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,
+      // which is how a FOREIGN report arrives here — and `{ok: true, violations: []}` over a report with
+      // `analyzed.count: 0` tells an agent the code is clean when nothing in it was ever judged. The
+      // 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." } : {};
+      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
+      // ALL, because the gate is making no claim about violations and `[]` is precisely the claim it cannot
+      // make. THE TOOL-RESULT SHAPE DECISION, stated: a refusal is returned as this structured document and
+      // NOT as `isError`. `isError` flattens to a text blob, and the machine-actionable half of a refusal is
+      // `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 (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 };
     },
   },
   candor_unverified: {
@@ -245,17 +354,34 @@ const TOOLS = {
                  + "case is a fn/closure-injected 'port' — the domain reads as Unknown, so `deny Net domain`/`pure "
                  + "domain` clear it though it may reach Net at runtime. Returns each such function + the `deny <E> "
                  + "Unknown <scope>` upgrade that makes the layer PROVABLY clean. Uses `policy` if given, else the "
-                 + "repo's checked-in .candor/config policy.",
+                 + "repo's checked-in .candor/config policy. ALWAYS CHECK `ok`, never the length of `unverified`: "
+                 + "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 "
+                 + "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 "
+                 + "own `unevaluated:[{rule, why}]`. Those entries carry no `upgrade`: whether they pass at all is "
+                 + "the open question, so there is nothing to upgrade yet — re-scan so the report carries the "
+                 + "evidence, or widen the rule (spec §3.2: an advisory verb may be LESS certain than the gate, "
+                 + "never MORE).",
     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;
+      let text, polPath = a.policy ?? null;
       if (a.policy) text = confinedPolicyRead(a.policy, p);
       else {
         const cfg = configPolicy(p);
+        polPath = cfg?.policyPath ?? null;
         if (!cfg) throw new Error("no policy: pass `policy`, or check one into the repo's .candor/config (spec §3.4)");
         text = confinedPolicyRead(cfg.policyPath, p, cfg.repoRoot);
       }
-      return Q.unverified(loadReportLoud(p), parsePolicy(text), scopeMatches);
+      // ⟨0.24⟩ SPEC §3.2 — the agent surface is a CHANNEL this verb answers on, and the rule binds every
+      // 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));
     },
   },
   candor_containment: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "candor-ts",
-  "version": "0.23.1",
-  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.23)",
+  "version": "0.25.0",
+  "description": "candor for TypeScript \u2014 per-function side effects, transitively, with a policy gate (candor-spec 0.25)",
   "type": "module",
   "dependencies": {
     "@types/node": "^25.9.2",
@@ -15,14 +15,16 @@
     "candor-mcp": "./mcp.mjs",
     "candor-lsp": "./lsp.mjs",
     "candor-ts-verify": "./verify.mjs",
-    "candor-ts-sensitivity": "./sensitivity.mjs"
+    "candor-ts-sensitivity": "./sensitivity.mjs",
+    "candor-ts-transitive-recall": "./transitive-recall.mjs"
   },
   "scripts": {
     "lint": "eslint *.mjs",
     "test": "npm run lint && node --test test-unit.mjs && node test.mjs && node test-mcp.mjs && node test-lsp.mjs && node test-watch.mjs && npm run test:probe && npm run test:fuzz",
     "test:unit": "node --test test-unit.mjs",
     "test:probe": "node fabrication_probe.mjs",
-    "test:fuzz": "node fuzz.mjs"
+    "test:fuzz": "node fuzz.mjs",
+    "test:transitive-recall": "node transitive-recall.mjs"
   },
   "license": "(MIT OR Apache-2.0)",
   "repository": {
@@ -64,7 +66,8 @@
     "verify-emit.mjs",
     "verify-loader.mjs",
     "verify-syscall.mjs",
-    "sensitivity.mjs"
+    "sensitivity.mjs",
+    "transitive-recall.mjs"
   ],
   "devDependencies": {
     "@eslint/js": "^9.39.4",