candor-ts 0.8.5 → 0.8.6

package/AGENTS.md

@@ -43,7 +43,12 @@ This writes `<project-dir>/.candor/report.json` and `.candor/report.callgraph.js
 with `--out <prefix>`). **Install the TARGET's dependencies first** (`npm install` in the project)
 — without node_modules, imports don't resolve and most functions honestly read `Unknown` (the
 scanner warns loudly). Add `--policy <file>` (or set `CANDOR_POLICY`) to enforce a §6.2 policy over the
-scan: exit 1 on violation, exit 2 LOUDLY if the policy file is unreadable.
+scan: exit 1 on violation, exit 2 LOUDLY if the policy file is unreadable. `--gate-json <file|->`
+additionally writes the structured verdict `{spec, ok, violations:[{rule,fn,effects,detail}]}`
+(spec §3.3) — the machine-readable form CI/SARIF converters consume, from the SAME violations that
+set the exit code. A checked-in `.candor/config` (spec §3.4; `policy <file>` / `deps <paths>`, one
+key per line, discovered walking UP from the scan target, relative values anchored to the config's
+repo) is the no-env-wiring floor; flag → env → config → default.
 
 **Report shape:** the file is `{ "candor": {version, toolchain, spec}, "functions": [...] }`;
 `functions` is an **array** of entries (not a map — don't index it by name), each carrying **`fn`**
@@ -73,9 +78,11 @@ Q show     $P <fn-query> 1          # a function's effects (+ hosts/tables when
 Q where    $P <Effect>   1          # {effect, directly, inherited}
 Q impact   $P <fn-query>            # THE BLAST RADIUS: {fn, affectedCount, affected, entryPoints}
 Q callers  $P <fn-query> 1          # the lower-level form: {of, direct, transitive} — works for pure fns
+Q callers  $P <fn-query> --include-unknown 1  # + possibleViaUnknownDispatch: the unresolved-dispatch frontier
 Q path     $P <fn> <Effect>         # how a fn reaches an effect: the chain to the nearest source
 Q map      $P 1                     # {module: {effects, functions}}
 Q containment $P [baseline-prefix]  # §6.1 boundary-effect dispersion; with a baseline = AS-EFF-010 ratchet (exit 1 on a leak)
+Q blindspots $P                     # the Unknown SOURCES (fns with unknownWhy), ranked by Unknown blast radius
 Q whatif   $P <fn> <Effect> [policy]  # pre-edit gate verdict (exit 1 if it would violate)
 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
@@ -84,8 +91,14 @@ Q parsepolicy <policy-file>         # the canonical §6.2 parse (what the gate w
 ```
 
 And as an MCP server, so an agent pulls these as tools instead of shelling out:
-`CANDOR_REPORT=$P npx -y candor-ts-mcp` (tools `candor_impact`/`candor_reachable`/`candor_where`/…).
-`npx -y candor-ts-watch <dir>` keeps the report fresh as you edit (and reports the edit-delta).
+`CANDOR_REPORT=$P npx -y candor-ts-mcp` (tools `candor_impact`/`candor_reachable`/`candor_where`/…,
+plus `candor_gate`/`candor_whatif` — a given-but-unreadable `policy` is a loud tool error, never a
+clean verdict). `npx -y candor-ts-watch <dir>` keeps the report fresh as you edit (and reports the
+edit-delta); `candor-lsp` serves the same report as CodeLens/hover/diagnostics in any LSP editor.
+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.
 
 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

package/README.md

@@ -19,6 +19,7 @@ npm install   # typescript + @types/node
 node scan.mjs <project-dir>                 # tsconfig.json honored; tests excluded; writes
                                             #   <dir>/.candor/report.json + .callgraph.json
 node scan.mjs . --policy .candor/policy     # the §6.2 gate: exit 1 on violation, 2 if unreadable
+node scan.mjs . --gate-json gate.json       # + the structured verdict {spec, ok, violations} (§3.3)
 
 node scan.mjs --version                     # installed build + spec contract (offline), + upgrade line
 
@@ -26,10 +27,18 @@ node query.mjs show     .candor/report db.save 1   # a function's effects (match
 node query.mjs where    .candor/report Net 1       # direct sources vs inheritors
 node query.mjs callers  .candor/report db.save 1   # the blast radius (transitive callers)
 node query.mjs map      .candor/report 1           # module → effects overview
+node query.mjs containment .candor/report          # §6.1 boundary-effect dispersion (+ baseline = ratchet)
+node query.mjs blindspots  .candor/report          # the Unknown SOURCES, ranked by blast radius
 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)
+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)
 ```
 
+A checked-in **`.candor/config`** (spec §3.4) replaces the env wiring — `policy arch.policy` /
+`deps <report paths>` one per line, discovered by walking up from the scan target; relative values
+resolve against the config's repo, so CI is "point at the repo". A configured-but-unusable
+config/policy fails loud (exit 2), never silently gateless.
+
 **Staying current:** check your installed version and upgrade — [candor/AGENTS.md §2a](https://github.com/tombaldwin/candor/blob/main/AGENTS.md#2a-staying-current--check-the-version-upgrade). `npx -y candor-ts --version` prints the build, the spec, and the upgrade one-liner (offline; candor never phones home).
 
 Function names are module-qualified with `.` segments (`src.db.save`), so policy scopes read
@@ -53,10 +62,16 @@ Nest app this makes table-level policy live: `allow Db in article.service articl
 the service reaching `user` and `follows`.
 
 **The classifier** is curated (the same under-report-and-say-so posture as the other engines): the
-Node builtins (`fs`, `net`/`http`/`tls`, `child_process`, `node:sqlite`, `process.env`, the clock)
-plus a small npm tier (axios/got/node-fetch/undici/ws, pg/mysql2/mongodb/redis/knex,
-execa/cross-spawn, fs-extra/rimraf/glob, dotenv, winston/pino). An unlisted package contributes
-nothing — candor never guesses an effect.
+Node builtins (`fs`, `net`/`http`/`tls`, `dns`, `child_process`, `worker_threads`, `node:sqlite`,
+`node:vm`, `process.env`, the clock), the HTTP/queue/mail tier (axios/got/node-fetch/undici/ws/
+socket.io/nodemailer, gaxios + googleapis-common + google-auth-library, stripe, @sentry/*,
+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
+nothing — candor never guesses an effect — but the scan **names it**: the receipt's `κ doesn't
+know N packages…` line lists every package the code demonstrably calls that κ neither classifies
+nor has reviewed-pure, and each function carries the `invisible` list it (transitively) reaches.
 
 ## MCP server — candor as agent ground truth
 
@@ -73,10 +88,21 @@ tracing the call graph by hand (the measured ~700–2000× token win on blast-ra
 
 Tools: `candor_impact` (backward blast radius), `candor_reachable` (what runs at runtime),
 `candor_where` (effect surface), `candor_path` (how an effect is reached), `candor_callers`,
-`candor_show`, `candor_map`, `candor_whatif` (pre-edit gate check). Each takes an optional `report`
-prefix (else `$CANDOR_REPORT`). The server is **query-only** — it never scans (the analyzer
-self-boundary, spec §7.12: an agent or a hook produces the report; the server reads it, Fs only). The
-query logic is the shared `query-core.mjs`, the same answers the CLI gives.
+`candor_show`, `candor_map`, `candor_containment`, `candor_blindspots`, `candor_whatif` (pre-edit
+gate check — a given-but-unreadable policy is a loud error, never a clean verdict), `candor_gate`
+(the checked-in `.candor/config` policy verdict), `candor_diff`/`candor_gains` (baseline deltas).
+Each takes an optional `report` prefix (else `$CANDOR_REPORT`); `--root <dir>` locks the server to
+one workspace. The server is **query-only** — it never scans (the analyzer self-boundary, spec
+§7.12: an agent or a hook produces the report; the server reads it, Fs only). The query logic is
+the shared `query-core.mjs`, the same answers the CLI gives.
+
+**`candor-lsp`** renders the same report where the code is, for any LSP-native editor (helix,
+neovim; the JetBrains plugin bundles it): a CodeLens per effectful function (`⚡ Db, Net · blast
+radius 12`), hover provenance (the hop chain to where an inherited effect is performed), and the
+repo's policy verdict as diagnostics. Like the MCP server it is a pure report consumer — any
+engine's report — and never scans. (Both report-computed gates are advisory: the engine's own
+`--gate-json` run additionally fails masked/incomplete literal surfaces and is the authoritative
+CI form.)
 
 **The live loop** — `candor-ts-watch` keeps the report fresh as the agent edits, so the answers are
 about the *current* code, not a stale snapshot:
@@ -129,7 +155,7 @@ every push to the spec.
 | A call resolving to a *type* (function-typed field/param) → `Unknown`, never silent-pure | SPEC §4 |
 | Unmatched external calls contribute nothing (curated-κ caveat) | SEMANTICS §8 C1 |
 | The literal surfaces `hosts`/`cmds`/`paths`/`tables`, literal-read only | SPEC §2 |
-| `{ candor: { version, toolchain, spec: "0.5" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
+| `{ candor: { version, toolchain, spec: "0.8" }, 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 |
 
@@ -147,13 +173,16 @@ read the Rust source".
 
 ## Status
 
-Young product (0.1.x): the analysis core, the gate, and the query surface are real,
-behaviorally tested (`node test.mjs`), **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. The npm classifier tier is
-deliberately curated and will keep growing case-by-case. Entry points (Nest/Next populations),
-`unknownWhy` origins, `reachable`, cross-package inheritance (`CANDOR_DEPS` + the spec §2 `hash`,
-version-trusted per §2.1), and `--allow-js` are all in. On npm: `npx -y candor-ts <dir>`.
+0.8.x, speaking candor-spec 0.8: 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
+real, behaviorally tested (`npm test` — ~360 assertions across six suites), **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
+npm classifier tier is deliberately curated and keeps growing case-by-case. Entry points
+(Nest/Next populations), `unknownWhy` origins, `reachable`, cross-package inheritance
+(`CANDOR_DEPS` + the spec §2 `hash`, version-trusted per §2.1), and `--allow-js` are all in.
+On npm: `npx -y candor-ts <dir>`.
 
 ## Development
 

package/lsp.mjs

@@ -7,6 +7,10 @@
  *     how many functions transitively call it (who is affected if it changes).
  *   • Diagnostics: the repo's architecture-policy verdict (the §6.2 gate, resolved from CANDOR_POLICY
  *     or the checked-in .candor/config — spec §3.4) as squiggles at each violating function's line.
+ *     CAVEAT — a report-computed gate is WEAKER than the engine's own --gate-json run: the scan-time
+ *     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).
  *   • 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.
  *
@@ -40,14 +44,7 @@ try { VERSION = createRequire(import.meta.url)("./package.json").version; } catc
 let rootPath = null;
 let reportPrefix = process.env.CANDOR_REPORT || process.argv[2] || null;
 
-function hasReport(p) {
-  if (!p) return false;
-  if (fs.existsSync(`${p}.json`)) return true;
-  const base = nodePath.basename(p);
-  try {
-    return fs.readdirSync(nodePath.dirname(p) || ".").some((f) => f.startsWith(base + ".") && f.endsWith(".json") && Q.isReport(f));
-  } catch { return false; }
-}
+const hasReport = Q.hasReport; // single-sourced with the loader predicate (query-core) — see mcp.mjs
 
 // ---- fn → document mapping --------------------------------------------------------------------------
 // A report `loc` is `<file>:<line>[:col…]` where <file> is either a repo-relative PATH (the scan-source
@@ -70,29 +67,41 @@ function docMatches(docPath, fn, file) {
   const norm = docPath.split(nodePath.sep).join("/");
   return candidatePaths(fn, file).some((c) => norm === c || norm.endsWith("/" + c));
 }
-/** Every report entry whose loc maps into this document: [{ entry, line }]. Loaded FRESH per call. */
-function entriesInDoc(docPath) {
+/** Every report entry whose loc maps into this document: [{ entry, line }]. Loaded FRESH per call
+ *  (the per-request re-read is the freshness design); a caller that already has the report passes
+ *  it via `fns` so one request never parses the same file twice. */
+function entriesInDoc(docPath, fns = null) {
   if (!hasReport(reportPrefix)) return null;
   const out = [];
-  for (const e of Q.loadReport(reportPrefix)) {
+  for (const e of (fns ?? Q.loadReport(reportPrefix))) {
     const lp = e.loc && locParts(e.loc);
     if (lp && docMatches(docPath, e.fn, lp.file)) out.push({ entry: e, line: lp.line });
   }
   return out;
 }
 
+// The transitive-caller COUNT for an exact fn name over an already-inverted graph. The lenses used
+// Q.callers per entry, and every callers() call rebuilt reverseGraph from scratch — a 50-fn document
+// over a JVM-scale callgraph did 50 full graph inversions PER codeLens request (review find). One
+// inversion per request + a plain BFS; report fn names are exact cg keys, so no match ladder needed.
+function transitiveCallerCount(rev, fn) {
+  const seen = new Set([fn]);
+  const queue = [fn];
+  while (queue.length) {
+    const n = queue.pop();
+    for (const c of rev.get(n) ?? []) if (!seen.has(c)) { seen.add(c); queue.push(c); }
+  }
+  return seen.size - 1; // minus the target itself
+}
+
 // ---- CodeLens ---------------------------------------------------------------------------------------
 function codeLenses(docPath) {
   const found = entriesInDoc(docPath);
   if (found === null) return [];
-  const cg = Q.loadCallgraph(reportPrefix);
+  let rev = null;
+  try { rev = Q.reverseGraph(Q.loadCallgraph(reportPrefix)); } catch { /* no callgraph — effects-only lens */ }
   return found.map(({ entry, line }) => {
-    let blast = "";
-    try {
-      const c = Q.callers(cg, entry.fn);
-      const n = (c && c.transitive && c.transitive.length) || 0;
-      blast = ` · blast radius ${n}`;
-    } catch { /* no callgraph — effects-only lens */ }
+    const blast = rev ? ` · blast radius ${transitiveCallerCount(rev, entry.fn)}` : "";
     const eff = (entry.inferred || []).join(", ") || "pure";
     return {
       range: { start: { line, character: 0 }, end: { line, character: 0 } },
@@ -107,12 +116,13 @@ function codeLenses(docPath) {
 // needs no parser). For each inferred effect: direct → "performed here"; inherited → the §3.1 `path`
 // chain to the direct source. unknownWhy rides along when the fn introduces opacity.
 function hoverAt(docPath, line) {
-  const found = entriesInDoc(docPath);
+  if (!hasReport(reportPrefix)) return null;
+  const fns = Q.loadReport(reportPrefix);          // ONE load per request (entriesInDoc reuses it)
+  const found = entriesInDoc(docPath, fns);
   if (!found || !found.length) return null;
   const at = found.filter((x) => x.line <= line).sort((a, b) => b.line - a.line)[0];
   if (!at) return null;
   const { entry } = at;
-  const fns = Q.loadReport(reportPrefix);
   const cg = Q.loadCallgraph(reportPrefix);
   const lines = [`**${entry.fn}** — ⚡ { ${(entry.inferred || []).join(", ") || "pure"} }`];
   for (const eff of entry.inferred || []) {
@@ -139,9 +149,16 @@ function hoverAt(docPath, line) {
 }
 
 // ---- Diagnostics (the live gate) ---------------------------------------------------------------------
+const warned = new Set();
+function warnOnce(message) { if (!warned.has(message)) { warned.add(message); logMessage(message); } }
 function activePolicy() {
   const env = process.env.CANDOR_POLICY;
-  if (env && fs.existsSync(env)) return fs.readFileSync(env, "utf8");
+  if (env) {
+    if (fs.existsSync(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");

package/mcp.mjs

@@ -23,41 +23,57 @@ import { discoverConfigPolicy, evaluatePolicy, parsePolicy, scopeMatches } from
 
 const VERSION = createRequire(import.meta.url)("./package.json").version; // single-sourced, like scan.mjs
 
-const DEFAULT_PREFIX = process.env.CANDOR_REPORT || process.argv[2]
+// CLI: [prefix] [--root <dir>]. `--root` LOCKS the server to a workspace: every report prefix (and
+// therefore every policy read, whose confinement root derives from the prefix) must live inside it.
+// Without it the confinement is only RELATIVE — the `report` arg is client-chosen, so a client that can
+// also plant a parseable report in a target tree could anchor policy reads there (review find).
+const CLI_ARGS = process.argv.slice(2);
+let WORKSPACE_ROOT = null;
+{
+  const i = CLI_ARGS.indexOf("--root");
+  if (i >= 0) { WORKSPACE_ROOT = nodePath.resolve(CLI_ARGS[i + 1] ?? "."); CLI_ARGS.splice(i, 2); }
+}
+const DEFAULT_PREFIX = process.env.CANDOR_REPORT || CLI_ARGS[0]
   || (fs.existsSync(".candor") ? ".candor/report" : null);   // the engines' default --out convention
 
-// A report exists at the prefix if there's an exact `<prefix>.json` (candor-ts) OR a sibling
-// `<prefix>.<crate>.scan.json` (the candor-scan/Rust multi-report form) — the loaders read both, so
-// the MCP server serves a report from ANY engine, not just candor-ts's.
-function hasReport(p) {
-  if (fs.existsSync(`${p}.json`)) return true;
-  const base = nodePath.basename(p);
-  try {
-    // SAME predicate (Q.isReport) the loader uses — a prefix whose only sibling is `.encountered-*` /
-    // `.calibrated.json` must NOT pass here, else loadReport finds zero functions and the tool returns an
-    // authoritative-empty result instead of "no report" (a silent under-report — review find).
-    return fs.readdirSync(nodePath.dirname(p) || ".").some((f) =>
-      f.startsWith(base + ".") && f.endsWith(".json") && Q.isReport(f));
-  } catch { return false; }
-}
+const within = (abs, root) => abs === root || abs.startsWith(root + nodePath.sep);
+// hasReport is the shared query-core check — the SAME predicate (Q.isReport) the loader uses, so a
+// prefix whose only sibling is `.encountered-*`/`.calibrated.json` can't pass existence yet load zero
+// functions (an authoritative-empty result — a silent under-report; review find).
 function resolvePrefix(args) {
   const p = args?.report || DEFAULT_PREFIX;
   if (!p) throw new Error("no report prefix: pass `report`, set $CANDOR_REPORT, or give one as the CLI arg");
-  if (!hasReport(p)) throw new Error(`no report at \`${p}\` (.json or .<crate>.scan.json) — run a candor scan first`);
+  if (WORKSPACE_ROOT && !within(nodePath.resolve(p), WORKSPACE_ROOT))
+    throw new Error(`report prefix \`${clip(p)}\` is outside the served workspace (--root ${WORKSPACE_ROOT}) — refusing`);
+  if (!Q.hasReport(p)) throw new Error(`no report at \`${p}\` (.json or .<crate>.scan.json) — run a candor scan first`);
   return p;
 }
 // Truncate a caller-supplied value echoed back in an error (a multi-MB `fn` would otherwise be reflected
 // verbatim — token/memory amplification over the agent transport, the opposite of the list-cap thrift).
 const clip = (s, n = 120) => { s = String(s); return s.length > n ? s.slice(0, n) + "…" : s; };
-// Read a caller-supplied policy file CONFINED to the report's directory tree. The MCP surface is
+// The confinement root for a caller-supplied policy path: the repo the report belongs to — the
+// .candor/config-discovered repo root when there is one, else the parent of a `.candor/` report
+// directory, else the report's own directory. The old default (always dirname(prefix)) was the
+// `.candor/` dir itself under the standard `.candor/report` layout, so a legitimate repo-root policy —
+// the very layout candor_gate resolves via cfg.repoRoot — was refused (review find).
+function policyRoot(prefix) {
+  const cfg = configPolicy(prefix);
+  if (cfg) return cfg.repoRoot;
+  const dir = nodePath.resolve(nodePath.dirname(prefix));
+  return nodePath.basename(dir) === ".candor" ? nodePath.dirname(dir) : dir;
+}
+// Read a caller-supplied policy file CONFINED to the report's repo tree. The MCP surface is
 // report-query-only (spec §7.12); an arbitrary `policy` path (/etc/passwd, ~/.aws/credentials) whose
 // parsed deny-rule scopes are reflected back in violations[].rule is an arbitrary-file-read exfiltration
-// channel — tie the policy to the project it gates.
-function confinedPolicyRead(policyPath, prefix, root = nodePath.resolve(nodePath.dirname(prefix))) {
+// channel — tie the policy to the project it gates. FAIL CLOSED on an unreadable path: the thrown error
+// surfaces as the tool-level isError — a typo'd policy must be LOUD, never a clean no-policy verdict
+// (the gateless-green shape the CLI's whatif exits 2 on).
+function confinedPolicyRead(policyPath, prefix, root = policyRoot(prefix)) {
   const abs = nodePath.resolve(policyPath);
-  if (abs !== root && !abs.startsWith(root + nodePath.sep))
-    throw new Error(`policy must be within the report's directory (${root}) — refusing to read \`${clip(policyPath)}\``);
-  return fs.readFileSync(abs, "utf8");
+  if (!within(abs, root) || (WORKSPACE_ROOT && !within(abs, WORKSPACE_ROOT)))
+    throw new Error(`policy must be within the report's repo (${root}) — refusing to read \`${clip(policyPath)}\``);
+  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)`); }
 }
 // The repo's .candor/config (spec §3.4), from the report's directory upward — shared impl in policy.mjs.
 function configPolicy(prefix) {
@@ -75,8 +91,32 @@ const reportArg = { report: { type: "string", description: "report prefix (optio
 // only shapes the MCP result for its token-sensitive transport). Small results are returned verbatim.
 const MCP_LIST_CAP = 50;
 function capImpact(r) {
-  if (!Array.isArray(r.affected) || r.affected.length <= MCP_LIST_CAP) return r; // affectedCount is the full count
-  return { ...r, affected: r.affected.slice(0, MCP_LIST_CAP), affectedTruncated: true };
+  let out = r;
+  if (Array.isArray(r.affected) && r.affected.length > MCP_LIST_CAP)   // affectedCount is the full count
+    out = { ...out, affected: r.affected.slice(0, MCP_LIST_CAP), affectedTruncated: true };
+  if (Array.isArray(r.entryPoints) && r.entryPoints.length > MCP_LIST_CAP)
+    out = { ...out, entryPointCount: r.entryPoints.length, entryPoints: r.entryPoints.slice(0, MCP_LIST_CAP), entryPointsTruncated: true };
+  return out;
+}
+// The same token-amplification argument as capImpact, for the other unbounded lists: `where` on a
+// pervasive effect (Log, Unknown) lists most of a large repo; a blindspot source's `affected` is a
+// transitive-caller list. Counts stay exact; truncation is flagged.
+function capWhere(r) {
+  const cap = (k) => Array.isArray(r[k]) && r[k].length > MCP_LIST_CAP;
+  if (!cap("directly") && !cap("inherited")) return r;
+  return {
+    effect: r.effect,
+    directlyCount: r.directly.length, directly: r.directly.slice(0, MCP_LIST_CAP),
+    inheritedCount: r.inherited.length, inherited: r.inherited.slice(0, MCP_LIST_CAP),
+    truncated: true,
+  };
+}
+function capBlindspots(r) {
+  const sources = (r.sources ?? []).map((s) =>
+    Array.isArray(s.affected) && s.affected.length > MCP_LIST_CAP
+      ? { ...s, affected: s.affected.slice(0, MCP_LIST_CAP), affectedTruncated: true }  // `reaches` is the full count
+      : s);
+  return { ...r, sources };
 }
 function capCallers(r) {
   const d = r.direct ?? [], t = r.transitive ?? [];
@@ -97,7 +137,7 @@ const TOOLS = {
   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) => Q.where(Q.loadReport(p), a.effect),
+    run: (a, p) => capWhere(Q.where(Q.loadReport(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.",
@@ -128,14 +168,18 @@ const TOOLS = {
     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.",
     schema: { type: "object", properties: { fn: { type: "string" }, effect: { type: "string" }, policy: { type: "string", description: "path to a CANDOR_POLICY file (optional)" }, ...reportArg }, required: ["fn", "effect"] },
     run: (a, p) => {
-      const pol = a.policy && fs.existsSync(a.policy) ? parsePolicy(confinedPolicyRead(a.policy, p)) : null;
+      // A GIVEN policy path is always read (confined, fail-closed) — the old `existsSync` guard made a
+      // 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 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_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 (an engine's own --gate-json run is the authoritative CI form).",
+    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.",
     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;
@@ -157,7 +201,7 @@ const TOOLS = {
   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) => Q.blindspots(Q.loadReport(p), Q.loadCallgraph(p)),
+    run: (_a, p) => capBlindspots(Q.blindspots(Q.loadReport(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?'.",
@@ -211,13 +255,19 @@ function handle(msg) {
   if (method === "notifications/initialized" || method === "notifications/cancelled") return; // notifications: no reply
   if (method === "ping") return result(id, {});
   if (method === "resources/list") {
-    try { return result(id, { resources: DEFAULT_PREFIX && hasReport(DEFAULT_PREFIX) ? listResources(DEFAULT_PREFIX) : [] }); }
+    try { return result(id, { resources: DEFAULT_PREFIX && Q.hasReport(DEFAULT_PREFIX) ? listResources(DEFAULT_PREFIX) : [] }); }
     catch { return result(id, { resources: [] }); }
   }
   if (method === "resources/read") {
     try {
-      const prefix = resolvePrefix({});
-      const r = readResource(params?.uri || "", prefix);
+      // Honor the prefix ENCODED in the resource URI (resources/list mints `?prefix=…`) — it was
+      // decorative before, always resolving the default (review find). resolvePrefix keeps the
+      // existence + --root checks on whatever the client asked for.
+      const uri = params?.uri || "";
+      let encoded = null;
+      try { encoded = new URL(uri).searchParams.get("prefix"); } catch { /* not URL-shaped — default */ }
+      const prefix = resolvePrefix(encoded ? { report: encoded } : {});
+      const r = readResource(uri, prefix);
       return result(id, { contents: [{ uri: params?.uri, ...r }] });
     } catch (e) { return error(id, -32602, `candor: ${e.message}`); }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "candor-ts",
-  "version": "0.8.5",
+  "version": "0.8.6",
   "description": "candor for TypeScript \u2014 per-function side effects, transitively, with a policy gate (candor-spec 0.8)",
   "type": "module",
   "dependencies": {

package/policy.mjs

@@ -161,8 +161,11 @@ export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()
 
 // ---- .candor/config discovery (spec §3.4) — shared by the MCP + LSP surfaces -----------------------
 // Walk UP from `fromDir` to the nearest .candor/config and return its `policy` entry resolved against
-// that config's repo root: { policyPath, repoRoot } — or null. Read-only + best-effort (a consumer
-// surface never gates a build; a broken config surfaces as the caller's error).
+// that config's repo root: { policyPath, repoRoot } — or null. A RELATIVE `policy` value resolves
+// against the repo the config belongs to (the parent of its `.candor/`), NEVER the process CWD — the
+// family rule (scan.mjs configAnchor is the producer-side twin): a checked-in config means the same
+// file wherever the consumer process was launched. Read-only + best-effort (a consumer surface never
+// gates a build; a broken config surfaces as the caller's error).
 import fs from "node:fs";
 import nodePath from "node:path";
 export function discoverConfigPolicy(fromDir) {

package/query-core.mjs

@@ -22,11 +22,27 @@ function siblings(prefix, predicate) {
       .map((f) => nodePath.join(dir, f));
   } catch { return []; }
 }
-// A sibling filename that is a real REPORT (not a callgraph sidecar, an encountered-crate ledger, or a
-// calibrated-coverage sidecar). Exported so `hasReport` (the MCP existence check) uses the SAME predicate
-// as the loader — else a prefix whose only sibling is `.encountered-*`/`.calibrated.json` passes the
-// existence check but loads ZERO functions → an authoritative-empty result (silent under-report; review find).
-export const isReport = (f) => !f.endsWith(".callgraph.json") && !f.endsWith(".hierarchy.json") && !f.includes(".encountered-") && !f.endsWith(".calibrated.json");
+// A sibling filename that is a real REPORT (not a callgraph sidecar, an encountered-crate ledger, a
+// calibrated-coverage sidecar, or a --gate-json verdict written beside the prefix). Exported so
+// `hasReport` (the MCP existence check) uses the SAME predicate as the loader — else a prefix whose only
+// sibling is `.encountered-*`/`.calibrated.json` passes the existence check but loads ZERO functions →
+// an authoritative-empty result (silent under-report; review find). `.gate.json` has no functions array,
+// so merging it "disclosed a malformed report" on every query over the recommended CI layout — noisy, excluded.
+export const isReport = (f) => !f.endsWith(".callgraph.json") && !f.endsWith(".hierarchy.json") && !f.includes(".encountered-") && !f.endsWith(".calibrated.json") && !f.endsWith(".gate.json");
+
+// A report exists at the prefix if there's an exact `<prefix>.json` (candor-ts) OR a sibling
+// `<prefix>.<crate>.scan.json` (the candor-scan/Rust multi-report form) — the loaders read both, so a
+// consumer (MCP/LSP) serves a report from ANY engine. ONE copy here: the check was triplicated across
+// mcp.mjs/lsp.mjs, and an earlier divergence from the loader predicate was itself a review find.
+export function hasReport(p) {
+  if (!p) return false;
+  if (fs.existsSync(`${p}.json`)) return true;
+  const base = nodePath.basename(p);
+  try {
+    return fs.readdirSync(nodePath.dirname(p) || ".").some((f) =>
+      f.startsWith(base + ".") && f.endsWith(".json") && isReport(f));
+  } catch { return false; }
+}
 
 // Defend the queries against a partial/old-engine/hand-edited report: the §2 required fields are
 // defaulted, and a WRONG-TYPE field is coerced — a non-array `inferred` (e.g. the string "Net") must
@@ -120,7 +136,9 @@ export function matches(names, q) {
   return best === 0 ? [] : names.filter((n) => matchTier(n, q) >= best);
 }
 
-function reverseGraph(cg) {
+// Exported for consumers that answer MANY caller-count questions over one loaded graph (the LSP
+// codeLens): building the inversion once per request instead of once per `callers()` call.
+export function reverseGraph(cg) {
   const rev = new Map();
   for (const [caller, callees] of Object.entries(cg))
     for (const c of callees) {

package/query.mjs

@@ -29,8 +29,9 @@ import { printAgents } from "./contract.mjs";
 import { impact as coreImpact, path as corePath, gains as coreGains,
          show as coreShow, blindspots as coreBlindspots,
          callers as coreCallers, callersFrontier, loadHierarchy,
-         containment as coreContainment,
-         loadReport, loadCallgraph, matches , reportVersion } from "./query-core.mjs";
+         containment as coreContainment, diff as coreDiff,
+         where as coreWhere, map as coreMap, whatif as coreWhatif,
+         loadReport, loadCallgraph, reportVersion } from "./query-core.mjs";
 const emit = (v) => console.log(JSON.stringify(v, null, 1));
 
 // ONE version + spec source, the SAME way scan.mjs reads them: PKG_VERSION is the bare semver from
@@ -115,13 +116,11 @@ switch (cmd) {
     break;
   }
   case "where": {
+    // Shared query-core (like show/callers) — the CLI and MCP `candor_where` are ONE implementation.
+    // Hand-copies of core functions in this file have drifted three times (show, callers, diff); the
+    // fix each time was the same: delegate, keep query.mjs as arg-parsing + emit + exit codes only.
     const [prefix, eff] = args;
-    const fns = loadReport(prefix);
-    emit({
-      effect: eff,
-      directly: fns.filter((e) => e.direct.includes(eff)).map((e) => e.fn).sort(),
-      inherited: fns.filter((e) => e.inferred.includes(eff) && !e.direct.includes(eff)).map((e) => e.fn).sort(),
-    });
+    emit(coreWhere(loadReport(prefix), eff));
     break;
   }
   case "callers": {
@@ -136,17 +135,9 @@ switch (cmd) {
     break;
   }
   case "map": {
+    // Shared query-core — the CLI and MCP `candor_map` are one implementation (see `where` above).
     const [prefix] = args;
-    const fns = loadReport(prefix);
-    const mods = {};
-    for (const e of fns) {
-      const mod = e.fn.includes(".") ? e.fn.split(".").slice(0, -1).join(".") : "(root)";
-      const m = (mods[mod] ??= { effects: new Set(), functions: 0 });
-      for (const x of e.inferred) m.effects.add(x);
-      m.functions += 1;
-    }
-    emit(Object.fromEntries(Object.entries(mods).sort()
-      .map(([k, v]) => [k, { effects: [...v.effects].sort(), functions: v.functions }])));
+    emit(coreMap(loadReport(prefix)));
     break;
   }
   case "containment": {
@@ -168,18 +159,13 @@ switch (cmd) {
   }
   case "diff": {
     // per-function effect delta vs a baseline: {changes: [{fn, gained, lost}]} — the envelope shape
-    // the conformance suite pins (diff-vs-self must be {changes: []}).
+    // the conformance suite pins (diff-vs-self must be {changes: []}). Shared query-core: the CLI's
+    // former inline copy built `new Map(fns.map((e) => [e.fn, …]))` — the exact last-wins collapse
+    // core's effectsByFn was rewritten to avoid (merged multi-report siblings sharing a short fn name
+    // dropped one member's effects, so a gained Net could VANISH from diff and its exit-1 contract —
+    // a supply-chain miss, and the CLI disagreeing with MCP `candor_diff` on the same reports).
     const [curPrefix, basePrefix] = args;
-    const cur = new Map(loadReport(curPrefix).map((e) => [e.fn, new Set(e.inferred)]));
-    const base = new Map(loadReport(basePrefix).map((e) => [e.fn, new Set(e.inferred)]));
-    const changes = [];
-    for (const fn of new Set([...cur.keys(), ...base.keys()])) {
-      const c = cur.get(fn) ?? new Set(), b = base.get(fn) ?? new Set();
-      const gained = [...c].filter((e) => !b.has(e)).sort();
-      const lost = [...b].filter((e) => !c.has(e)).sort();
-      if (gained.length || lost.length) changes.push({ fn, gained, lost });
-    }
-    changes.sort((a, b) => a.fn.localeCompare(b.fn));
+    const { changes } = coreDiff(loadReport(curPrefix), loadReport(basePrefix));
     // §2.1: a baseline is comparable only to its own producing build — disclose a mismatch (the gains
     // may be the engine reclassifying after a coverage batch, not the code changing). Same note + JSON
     // provenance fields as the Rust candor-query (cross-engine parity, item 10).
@@ -239,26 +225,10 @@ switch (cmd) {
   }
   case "whatif": {
     const [prefix, target, eff, maybePolicy] = args;
-    const cg = loadCallgraph(prefix);
-    const names = Object.keys(cg);
-    const targets = matches(names, target);
-    if (targets.length === 0) {
-      console.error(`candor: no function matching \`${target}\` in the call graph`);
-      process.exit(2);
-    }
-    const rev = new Map();
-    for (const [caller, callees] of Object.entries(cg))
-      for (const c of callees) (rev.get(c) ?? rev.set(c, []).get(c)).push(caller);
-    const affected = new Set(targets);
-    const queue = [...targets];
-    while (queue.length) {
-      const n = queue.pop();
-      for (const c of rev.get(n) ?? []) if (!affected.has(c)) { affected.add(c); queue.push(c); }
-    }
-    const violations = [];
     // A present policy arg (anything but the 0/1 verbosity sentinels) MUST exist and be readable —
     // a typo'd path must be LOUD, not silently "no policy → ok:true, exit 0" (mirrors scan's --policy,
     // which exits 2 on an unreadable file: a gate that can't read its policy can't certify anything).
+    let pol = null;
     if (maybePolicy && maybePolicy !== "0" && maybePolicy !== "1") {
       let text;
       try {
@@ -267,16 +237,17 @@ switch (cmd) {
         console.error(`candor: policy ${maybePolicy} could not be read; whatif NOT evaluated against it`);
         process.exit(2);
       }
-      const pol = parsePolicy(text);
-      for (const r of pol.deny) {
-        if (r.effects.length && !r.effects.includes(eff)) continue; // pure ([]) forbids ANY effect
-        for (const fn of affected)
-          if (!r.scope || scopeMatches(fn, r.scope))
-            violations.push({ fn, rule: `deny ${r.effects.join(" ") || "(pure)"} ${r.scope}`.trim() });
-      }
+      pol = parsePolicy(text);
+    }
+    // Shared query-core — the CLI and MCP `candor_whatif` are one blast-radius + deny evaluation
+    // (the CLI keeps the I/O + exit codes; the core is pure — see `where` above for the drift class).
+    const r = coreWhatif(loadCallgraph(prefix), target, eff, pol, scopeMatches);
+    if (r === null) {
+      console.error(`candor: no function matching \`${target}\` in the call graph`);
+      process.exit(2);
     }
-    emit({ of: targets, effect: eff, affected: [...affected].sort(), violations, ok: violations.length === 0 });
-    process.exit(violations.length ? 1 : 0);
+    emit(r);
+    process.exit(r.violations.length ? 1 : 0);
     break; // unreachable (process.exit), but eslint can't prove it — defends against fallthrough
   }
   default:

package/scan.mjs

@@ -110,6 +110,16 @@ if (target === null) { console.error(usage); process.exit(2); }
 // implements `policy` + `deps` — the others are inert here (they drive other engines' gates), and a key
 // OUTSIDE the vocabulary warns (typo protection: a misspelt `policy` must not silently drop the gate).
 const CONFIG_KEYS = new Set(["policy", "baseline", "strict", "no-ambient", "closed-world", "taint", "deps"]);
+// The ANCHOR a config file's RELATIVE path values (policy/deps) resolve against: the repo the config
+// belongs to — the parent of its `.candor/` directory (the standard layout; candor-init scaffolds
+// `policy arch.policy` meaning the repo root's), else the config file's own directory. NEVER the
+// process CWD (family rule, matching policy.mjs discoverConfigPolicy's repoRoot): a checked-in config
+// must mean the same file whether the scan is launched from the repo, from $HOME, or from a CI step's
+// working-directory. Env/CLI values stay CWD-relative — they're per-invocation, not checked in.
+function configAnchor(file) {
+  const dir = path.dirname(path.resolve(file));
+  return path.basename(dir) === ".candor" ? path.dirname(dir) : dir;
+}
 function loadCandorConfig(targetPath) {
   let file = process.env.CANDOR_CONFIG ?? null;
   if (file !== null) {
@@ -146,6 +156,12 @@ function loadCandorConfig(targetPath) {
     }
     cfg[key] = val;
   }
+  // Resolve the PATH-valued keys against the config's anchor (see configAnchor). `deps` is a path
+  // LIST — each token resolves; an empty value stays empty (configured-with-empty fails loud below).
+  const anchor = configAnchor(file);
+  if (cfg.policy) cfg.policy = path.resolve(anchor, cfg.policy);
+  if (cfg.baseline) cfg.baseline = path.resolve(anchor, cfg.baseline);
+  if (cfg.deps) cfg.deps = cfg.deps.split(/[\s:,]+/).filter(Boolean).map((t) => path.resolve(anchor, t)).join(":");
   return cfg;
 }
 const candorConfig = loadCandorConfig(target);
@@ -2128,14 +2144,18 @@ if (unlistedSeen.size > 0) {
 }
 
 // ---- the standing §6.2 gate (--policy / CANDOR_POLICY) --------------------------------------------
+// `!== null`, not truthiness: a CONFIGURED-but-EMPTY policy (a bare `policy` config line, a set-but-
+// empty CANDOR_POLICY) is "" — falsy, so a truthy check silently skipped the gate, the exact quiet
+// drop the config comment above promises fails loud. "" now reaches the read, which fails → exit 2
+// (the Rust engine's behavior on the same input).
 let gateViolations = [];
-if (policyPath) {
+if (policyPath !== null) {
   let text;
   try {
     text = fs.readFileSync(policyPath, "utf8");
   } catch {
     // a set-but-unreadable policy must be LOUD — silently passing would let a violation ship
-    console.error(`candor-ts: policy ${policyPath} could not be read; gate NOT enforced`);
+    console.error(`candor-ts: policy ${policyPath === "" ? "(configured empty)" : policyPath} could not be read; gate NOT enforced`);
     process.exit(2);
   }
   // The masking-incompleteness map (fn -> effects whose surface is incomplete), kept INTERNAL like the
@@ -2162,8 +2182,8 @@ if (gateJsonPath) {
     catch (e) { console.error(`candor-ts: could not write --gate-json ${gateJsonPath}: ${e.message}`); }
   }
 }
-if (policyPath && gateViolations.length) {
+if (policyPath !== null && gateViolations.length) {
   console.error(`candor-ts: ${gateViolations.length} policy violation(s)`);
   process.exit(1);
 }
-if (policyPath) console.error("candor-ts: policy ✓");
+if (policyPath !== null) console.error("candor-ts: policy ✓");