candor-ts 0.10.0 → 0.12.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.10)."*
+> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.12)."*
 > 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`.
 >
@@ -86,13 +86,14 @@ downgraded to `Unknown` rather than silently trusted (spec §2.1). Caveat: a typ
 ## Query it (same names/shapes as the Rust and JVM engines — candor-spec §3.1)
 
 ```sh
-Q() { npx -y candor-ts-query "$@"; }; P=".candor/report"   # a function — works in bash AND zsh
+Q() { npx -y -p candor-ts candor-ts-query "$@"; }; P=".candor/report"   # a function — works in bash AND zsh
 Q show     $P <fn-query> 1          # a function's effects (+ hosts/tables when visible)
 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 tour [N] --report $P              # the N (default 10) most surprising transitive reaches
 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
@@ -142,9 +143,9 @@ want-JSON flag.
   "classifier" paragraph is the ONE current list (this file deliberately doesn't duplicate it — a
   vendored copy here drifted a full generation once).
   An unlisted package contributes nothing — an effect through it is invisible, not `Unknown`. The
-  scanner **names these per scan**: the receipt's `κ doesn't know N packages…` line lists every npm
-  package the code demonstrably calls that κ neither classifies nor has reviewed-pure — read it
-  before concluding "no effect" through anything it names.
+  scanner **names these per scan**: the receipt's coverage-ledger line (marker: `classifier doesn't
+  cover`) lists every npm package the code demonstrably calls that candor's classifier neither
+  classifies nor has reviewed-pure — read it before concluding "no effect" through anything it names.
 - **`process.env.X` reads are `Env`** (a property read, not a call); `Date.now()` is `Clock`.
 - **DI-style code reads `Unknown` a lot, by design**: a function-typed parameter or field being
   called is genuinely indeterminate (rimraf's injected-fs style yields many `Unknown`s — that's the
@@ -180,12 +181,12 @@ present — a callback value, an `any`-typed callee, resolution landing on a typ
 body), the set may be incomplete: read the source for *that* function before relying on it. Never
 conclude a function is pure while it is marked unresolved. The literal surfaces (`hosts`/`tables`/
 `cmds`/`paths`) are the decidable subset only — absence is never a claim of absence. **And the
-curated-κ caveat cuts the other way:** a call into an npm package κ doesn't know contributes
-NOTHING — invisible, not `Unknown`. The scan's receipt now DISCLOSES these by name (`κ doesn't
-know N packages…`), so the blind spots are per-scan evidence, not a doc footnote: never conclude
+curated-classifier caveat cuts the other way:** a call into an npm package the classifier doesn't
+cover contributes NOTHING — invisible, not `Unknown`. The scan's receipt now DISCLOSES these by name
+(the coverage ledger, marker: `classifier doesn't cover`), so the blind spots are per-scan evidence, not a doc footnote: never conclude
 "no effect" through a package that line names (the documented weaker edge of the
 never-silently-pure promise, same as every candor engine's curated classifier). Each function ALSO
-carries an `invisible` list — the κ-unknown packages it (transitively) reaches — so `inferred` is
+carries an `invisible` list — the uncovered packages it (transitively) reaches — so `inferred` is
 never an unqualified claim PER FUNCTION: `inferred: []` with a non-empty `invisible` means "pure as
 far as candor could see, but it could not see through these" (a LOWER bound), not "pure". An uncurated
 dependency can opt out of that blind spot by declaring `"candorEffects": ["Net", …]` in its

package/README.md

@@ -88,9 +88,10 @@ posthog-node, bull/bullmq), the database drivers (pg/mysql2/mongodb/redis/ioredi
 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.
+nothing — candor never guesses an effect — but the scan **names it**: the receipt's coverage-ledger
+line (marker: `classifier doesn't cover`) lists every package the code demonstrably calls that
+candor's classifier neither classifies nor has reviewed-pure, and each function carries the
+`invisible` list it (transitively) reaches.
 
 ## MCP server — candor as agent ground truth
 
@@ -155,7 +156,7 @@ field being called, an `any`-typed callee, resolution landing on a type rather t
 An **uncurated dependency** can opt out of `Unknown`/silent-pure by **declaring its effects** in its
 `package.json` — `"candorEffects": ["Net"]` (spec §5.1, the effect manifest). candor-ts reads it as
 the declared-not-verified tier: the package's calls classify to the declared set, and it stops being
-a κ-ledger blind spot. A name outside the §1 vocabulary voids the declaration loudly (a typo must not
+a coverage-ledger blind spot. A name outside the §1 vocabulary voids the declaration loudly (a typo must not
 silently narrow a surface). And `candor-ts-query gains <cur> <base>` flags the **supply-chain**
 delta — the effects a surface *gained* between two reports.
 Real-world consequence, measured on [rimraf](https://github.com/isaacs/rimraf) (50 files, 55
@@ -176,14 +177,14 @@ pure-vs-Unknown ruling (PART 16) — the engines must answer identically, on eve
 | Piece | Spec source |
 |---|---|
 | Resolve every call via the compiler API (`getResolvedSignature`), never syntax | CLASSIFIER §1 |
-| κ classifies the resolved target's module (`node:fs`→Fs, `node:net`→Net, …) | CLASSIFIER §2, TS notes |
+| The classifier maps the resolved target's module (`node:fs`→Fs, `node:net`→Net, …) | CLASSIFIER §2, TS notes |
 | `process.env` property read → Env; `Date.now` → Clock | SPEC §1 |
 | Local edges (cross-file) + least-fixpoint propagation | SEMANTICS §5a |
 | Closure bodies attribute to the nearest enclosing function | SEMANTICS §2 |
 | 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 |
+| 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.10" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
+| `{ candor: { version, toolchain, spec: "0.12" }, 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 |
 
@@ -201,7 +202,7 @@ read the Rust source".
 
 ## Status
 
-0.10.x, speaking candor-spec 0.10: the analysis core, the gate (`--policy` / `--gate-json` /
+0.12.x, speaking candor-spec 0.12: 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` — the behavioral suite across six harnesses), **soundness-fuzzed
@@ -228,5 +229,5 @@ node scan.mjs <dir | file.ts | tsconfig.json> --out .candor/report   # scan a pr
 ```
 
 The pure cores are factored into importable modules — `query-core.mjs` (the §3.1 queries),
-`policy.mjs` (the §6.2 DSL + literal matchers), and `scan-core.mjs` (the κ classifier + the SQL/
+`policy.mjs` (the §6.2 DSL + literal matchers), and `scan-core.mjs` (the classifier + the SQL/
 command/host extractors) — so they're unit-tested directly; the TS-compiler-driven walk stays in `scan.mjs`.

package/mcp.mjs

@@ -51,6 +51,18 @@ function resolvePrefix(args) {
 // 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; };
+// Load a report but FAIL LOUD (a thrown tool-level error) when files were FOUND yet nothing parsed —
+// Q.loadReport discloses-and-tolerates, returning [] with the non-enumerable `hardFail` tag there, and
+// an empty SUCCESSFUL result ({gained:[],byFunction:[]}, [] show, {} map) reads as an all-clear over a
+// 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) {
+  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`);
+  return fns;
+}
 // 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
@@ -132,22 +144,22 @@ const TOOLS = {
   candor_impact: {
     description: "Backward blast radius: every effectful function that transitively calls `fn`, and which runtime entry points are downstream. Answers 'if I change this, what surfaces at runtime?' — the cheapest possible alternative to tracing callers by hand.",
     schema: { type: "object", properties: { fn: { type: "string", description: "the function/unit to assess" }, ...reportArg }, required: ["fn"] },
-    run: (a, p) => capImpact(Q.impact(Q.loadReport(p), Q.loadCallgraph(p), a.fn)),
+    run: (a, p) => capImpact(Q.impact(loadReportLoud(p), Q.loadCallgraph(p), a.fn)),
   },
   candor_where: {
     description: "Which functions perform a given effect (e.g. Net, Db, Exec, Fs) — `directly` vs `inherited` via a callee. The effect-surface map.",
     schema: { type: "object", properties: { effect: { type: "string", description: "Net|Fs|Db|Exec|Env|Clock|Ipc|Log|Rand|Clipboard|Unknown" }, ...reportArg }, required: ["effect"] },
-    run: (a, p) => capWhere(Q.where(Q.loadReport(p), a.effect)),
+    run: (a, p) => capWhere(Q.where(loadReportLoud(p), a.effect)),
   },
   candor_reachable: {
     description: "What the program/fleet actually DOES at runtime: effects unioned over the entry points, with how many roots reach each and via which.",
     schema: { type: "object", properties: { ...reportArg } },
-    run: (_a, p) => Q.reachable(Q.loadReport(p)),
+    run: (_a, p) => Q.reachable(loadReportLoud(p)),
   },
   candor_path: {
     description: "Forward provenance: the shortest call chain from `fn` to the nearest function that performs `effect` DIRECTLY — 'this reaches Net through WHAT?'.",
     schema: { type: "object", properties: { fn: { type: "string" }, effect: { type: "string" }, ...reportArg }, required: ["fn", "effect"] },
-    run: (a, p) => Q.path(Q.loadReport(p), Q.loadCallgraph(p), a.fn, a.effect),
+    run: (a, p) => Q.path(loadReportLoud(p), Q.loadCallgraph(p), a.fn, a.effect),
   },
   candor_callers: {
     description: "Who calls `fn` — direct (one hop) and transitive callers over the effect-relevant call graph.",
@@ -157,12 +169,12 @@ const TOOLS = {
   candor_show: {
     description: "A function's effects (inferred = transitive, direct = own body) plus its literal surfaces (hosts/cmds/paths/tables) when present.",
     schema: { type: "object", properties: { fn: { type: "string" }, ...reportArg }, required: ["fn"] },
-    run: (a, p) => Q.show(Q.loadReport(p), a.fn),
+    run: (a, p) => Q.show(loadReportLoud(p), a.fn),
   },
   candor_map: {
     description: "Per-module effect overview: each module's union of effects and function count. The architecture-at-a-glance.",
     schema: { type: "object", properties: { ...reportArg } },
-    run: (_a, p) => Q.map(Q.loadReport(p)),
+    run: (_a, p) => Q.map(loadReportLoud(p)),
   },
   candor_whatif: {
     description: "Hypothetically add `effect` to `fn` and report the blast radius; with `policy`, also the deny-rule violations it would cause. Pre-edit gate check.",
@@ -195,7 +207,7 @@ 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, Q.loadReport(p), a.fn, a.effect, parsePolicy(text), scopeMatches);
+      const r = Q.fix(cg, loadReportLoud(p), a.fn, a.effect, parsePolicy(text), scopeMatches);
       if (r === null) throw new Error(`no function matching \`${clip(a.fn)}\` in the call graph`);
       return r;
     },
@@ -211,7 +223,7 @@ const TOOLS = {
         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), Q.loadReport(p), Q.loadCallgraph(p));
+      const v = evaluatePolicy(parsePolicy(text), loadReportLoud(p), Q.loadCallgraph(p));
       return { ok: v.length === 0, violations: v };
     },
   },
@@ -232,30 +244,44 @@ const TOOLS = {
         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(Q.loadReport(p), parsePolicy(text), scopeMatches);
+      return Q.unverified(loadReportLoud(p), parsePolicy(text), scopeMatches);
     },
   },
   candor_containment: {
     description: "Per boundary effect (Db/Net/Exec/Fs/Ipc/Clipboard): how contained it is in one architectural layer — the dispersion diagnostic (spec §6.1). Not a score; per-effect facts.",
     schema: { type: "object", properties: { ...reportArg } },
-    run: (_a, p) => Q.containment(Q.loadReport(p)),
+    run: (_a, p) => Q.containment(loadReportLoud(p)),
   },
   candor_blindspots: {
     description: "The Unknown SOURCES — calls the engine genuinely could not resolve (reflection, wide dispatch, fn-pointers) — ranked by how many functions inherit Unknown through each. Turns a high-Unknown report into a short worklist.",
     schema: { type: "object", properties: { ...reportArg } },
-    run: (_a, p) => capBlindspots(Q.blindspots(Q.loadReport(p), Q.loadCallgraph(p))),
+    run: (_a, p) => capBlindspots(Q.blindspots(loadReportLoud(p), Q.loadCallgraph(p))),
   },
   candor_diff: {
     description: "The per-function effect delta versus a baseline report: gained (introduced vs inherited) and lost effects. 'What did this change do to the effect surface?'.",
     schema: { type: "object", properties: { baseline: { type: "string", description: "the baseline report prefix" }, ...reportArg }, required: ["baseline"] },
-    run: (a, p) => ({ baseline_version: Q.reportVersion(a.baseline) ?? "", engine_version: Q.reportVersion(p) ?? "",
-                      ...Q.diff(Q.loadReport(p), Q.loadReport(a.baseline)) }),
+    run: (a, p) => {
+      // The BASELINE locator gets the SAME existence + --root confinement checks as the main report
+      // (resolvePrefix) — a typo'd baseline loaded [] with hardFail=false and diffed as an
+      // authoritative empty {changes:[]} (the CLI now exits 2 on the same miss).
+      const b = resolvePrefix({ report: a.baseline });
+      return { baseline_version: Q.reportVersion(b) ?? "", engine_version: Q.reportVersion(p) ?? "",
+               ...Q.diff(loadReportLoud(p), loadReportLoud(b)) };
+    },
   },
   candor_gains: {
     description: "The supply-chain alarm: effects the surface GAINED versus a baseline (package-level + per-function) — 'did this dependency bump add Net/Exec somewhere?'.",
     schema: { type: "object", properties: { baseline: { type: "string", description: "the baseline report prefix" }, ...reportArg }, required: ["baseline"] },
-    run: (a, p) => ({ baseline_version: Q.reportVersion(a.baseline) ?? "", engine_version: Q.reportVersion(p) ?? "",
-                      ...Q.gains(Q.loadReport(p), Q.loadReport(a.baseline)) }),
+    run: (a, p) => {
+      // Same baseline existence + --root confinement as candor_diff — an empty {gained:[]} over a
+      // typo'd baseline is a silent all-clear on the supply-chain ALARM tool.
+      const b = resolvePrefix({ report: a.baseline });
+      // ⟨spec 0.12 staged⟩ baseline callgraph → byFunction[].origin, same as the CLI (parity). The
+      // loader's non-enumerable `partial` tag rides along: a corrupt baseline sidecar (edges dropped,
+      // disclosed) downgrades origin to "unknown", never a fabricated "new" over a truncated graph.
+      return { baseline_version: Q.reportVersion(b) ?? "", engine_version: Q.reportVersion(p) ?? "",
+               ...Q.gains(loadReportLoud(p), loadReportLoud(b), Q.loadCallgraph(b)) };
+    },
   },
 };
 
@@ -270,7 +296,7 @@ function listResources(prefix) {
   return res;
 }
 function readResource(uri, prefix) {
-  if (uri.startsWith("candor://report")) return { mimeType: "application/json", text: JSON.stringify(Q.loadReport(prefix)) };
+  if (uri.startsWith("candor://report")) return { mimeType: "application/json", text: JSON.stringify(loadReportLoud(prefix)) };
   if (uri.startsWith("candor://policy")) {
     const cfg = configPolicy(prefix);
     if (!cfg) throw new Error("no checked-in policy (no .candor/config with a `policy` key)");
@@ -332,7 +358,7 @@ function handle(msg) {
       // A tool that targets a `fn` gets a clear "not found" rather than a silently-empty result —
       // an agent must distinguish "no such function" from "found, nothing calls it".
       if (args.fn !== undefined) {
-        const names = [...new Set([...Object.keys(Q.loadCallgraph(prefix)), ...Q.loadReport(prefix).map((e) => e.fn)])];
+        const names = [...new Set([...Object.keys(Q.loadCallgraph(prefix)), ...loadReportLoud(prefix).map((e) => e.fn)])];
         if (Q.matches(names, args.fn).length === 0)
           return result(id, { content: [{ type: "text", text: `candor: no function matching \`${clip(args.fn)}\` in this report` }], isError: true });
       }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "candor-ts",
-  "version": "0.10.0",
-  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.10)",
+  "version": "0.12.0",
+  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.12)",
   "type": "module",
   "dependencies": {
     "@types/node": "^25.9.2",
@@ -52,6 +52,7 @@
     "LICENSE-APACHE",
     "query-core.mjs",
     "scan-core.mjs",
+    "surface.mjs",
     "mcp.mjs",
     "watch.mjs",
     "lsp.mjs"

package/query-core.mjs

@@ -86,22 +86,97 @@ export function reportVersion(prefix) {
   return null;
 }
 
+/** The report's §2 envelope `package` name — meaningful and locator-independent, so every engine and
+ *  every --report form print the same crate in the `tour` header. null when absent/unreadable (the
+ *  caller falls back to the prefix basename). Mirrors surface.rs/tour.rs::report_package. */
+export function reportPackage(prefix) {
+  const files = fs.existsSync(`${prefix}.json`) ? [`${prefix}.json`] : siblings(prefix, isReport);
+  for (const f of files) {
+    try {
+      const doc = JSON.parse(fs.readFileSync(f, "utf8"));
+      const p = doc?.package;
+      if (typeof p === "string" && p) return p;
+      // The `packages` PLURAL envelope — the JVM shape (SPEC §2): one entry names it verbatim; several
+      // name their longest common dotted prefix (`com.a.x` + `com.a.y` → `com.a`); none shared → null.
+      if (Array.isArray(doc?.packages)) {
+        const label = packagesLabel(doc.packages.filter((x) => typeof x === "string" && x));
+        if (label) return label;
+      }
+    } catch { /* unreadable sibling — keep looking */ }
+  }
+  return null;
+}
+
+// The longest common dot-separated prefix of a plural `packages` list — whole segments only (`com.ab` +
+// `com.ac` share `com`, not `com.a`); null when nothing is shared. Mirrors Rust's packages_label (tour.rs).
+function packagesLabel(pkgs) {
+  if (pkgs.length === 0) return null;
+  if (pkgs.length === 1) return pkgs[0];
+  const first = pkgs[0].split(".");
+  let n = first.length;
+  for (const p of pkgs.slice(1)) {
+    const segs = p.split(".");
+    let i = 0;
+    while (i < Math.min(n, segs.length) && segs[i] === first[i]) i++;
+    n = i;
+    if (n === 0) return null; // nothing shared — the basename fallback is more honest
+  }
+  return first.slice(0, n).join(".");
+}
+
+// The returned array carries a non-enumerable `hardFail` flag: true iff a report file was FOUND but
+// yielded NO trustworthy functions — a parse failure OR a malformed shape (a `null`/array/wrong-typed
+// doc, a non-array `functions`, all-junk entries). The loud CLI wrapper (loadReportOrDie) needs it to
+// tell "the report we found was corrupt" (never an all-clear) apart from a well-formed EMPTY report.
+const tagHardFail = (fns, hardFail) => { Object.defineProperty(fns, "hardFail", { value: hardFail, enumerable: false }); return fns; };
+
+// A well-formed report that legitimately lists ZERO functions — the ONLY empty result that is NOT a
+// corruption (parity with the Rust engine, which returns Ok(empty) for a valid empty envelope). A §2
+// envelope with `functions: []`, or a legacy bare `[]`. Anything else empty is malformed → hard fail.
+const isCleanEmptyReport = (parsed) =>
+  (parsed && typeof parsed === "object" && !Array.isArray(parsed) && Array.isArray(parsed.functions) && parsed.functions.length === 0)
+  || (Array.isArray(parsed) && parsed.length === 0);
+
+// Load ONE report file → { entries, hardFail }. A read/parse throw, or an empty result over a doc that
+// is NOT a clean-empty report, is a hard fail (the file was found but carries no trustworthy functions —
+// letting it read as [] would be the §4 false all-clear). Discloses every failure mode on stderr.
+function loadOneReport(file, label) {
+  let parsed;
+  try { parsed = JSON.parse(fs.readFileSync(file, "utf8")); }
+  catch { console.error(`candor-ts: report ${label} failed to parse — its functions are OMITTED from this query (corrupt or mid-write); re-run the scan`); return { entries: [], hardFail: true }; }
+  const entries = normFns(parsed, label);
+  // normFns already DISCLOSED any malformation (no functions array / dropped entries). If nothing usable
+  // survived AND the doc wasn't a clean-empty report, the report is corrupt — fail loud, never empty.
+  if (entries.length === 0 && !isCleanEmptyReport(parsed)) {
+    console.error(`candor-ts: report ${label} yielded no usable functions — OMITTED (malformed report); re-run the scan`);
+    return { entries, hardFail: true };
+  }
+  return { entries, hardFail: false };
+}
+
 export function loadReport(prefix) {
   if (fs.existsSync(`${prefix}.json`)) {
-    // The PRIMARY report parse must DISCLOSE-and-tolerate like the sibling path — a bare JSON.parse here
-    // threw an uncaught stack trace on the CLI for a corrupt `<prefix>.json` (asymmetric with siblings).
-    try { return normFns(JSON.parse(fs.readFileSync(`${prefix}.json`, "utf8")), `${prefix}.json`); }
-    catch { console.error(`candor-ts: report ${prefix}.json failed to parse — OMITTED (corrupt or mid-write); re-run the scan`); return []; }
+    const { entries, hardFail } = loadOneReport(`${prefix}.json`, `${prefix}.json`);
+    return tagHardFail(entries, hardFail);
   }
   // No exact <prefix>.json — merge the multi-report siblings (the Rust/workspace form).
   const fns = [];
+  let hardFail = false;
   for (const f of siblings(prefix, isReport)) {
     // DISCLOSE a malformed sibling — never silently drop it (a vanished report reads as "no effect").
-    try { fns.push(...normFns(JSON.parse(fs.readFileSync(f, "utf8")), f)); }
-    catch { console.error(`candor-ts: report ${f} failed to parse — its functions are OMITTED from this query (corrupt or mid-write); re-run the scan`); }
-  }
-  return fns;
-}
+    const r = loadOneReport(f, f);
+    fns.push(...r.entries);
+    if (r.hardFail) hardFail = true;
+  }
+  return tagHardFail(fns, hardFail);
+}
+// The returned graph carries a non-enumerable `partial` flag (the loadReport `hardFail` precedent):
+// true iff a sidecar file was MATCHED but failed to read/parse — its edges were DROPPED (disclosed on
+// stderr above), so the graph is an UNDER-approximation. An ABSENT sidecar is NOT partial: nothing
+// matched, and the empty graph is the whole (disclosable) truth. gains' origin ladder needs the
+// distinction: over a partial baseline graph, absence from the surviving edges proves nothing, so
+// labeling a dropped file's fns "new" would downgrade the attack signal — fall back to "unknown".
+const tagPartial = (cg, partial) => { Object.defineProperty(cg, "partial", { value: partial, enumerable: false }); return cg; };
 export function loadCallgraph(prefix) {
   // A `null`/non-object parse (a `null` callgraph, an array, a number) must NOT reach Object.entries —
   // it throws "Cannot convert null to object". Coerce anything but a plain object to {} (an empty
@@ -112,16 +187,18 @@ export function loadCallgraph(prefix) {
   if (fs.existsSync(`${prefix}.callgraph.json`)) {
     // The PRIMARY callgraph parse must DISCLOSE-and-tolerate like the sibling path below and like
     // loadReport — a bare JSON.parse here threw an uncaught stack trace on the CLI for a corrupt or
-    // `null` `<prefix>.callgraph.json` (asymmetric with siblings). Tolerate (empty graph) + disclose.
-    try { return norm(JSON.parse(fs.readFileSync(`${prefix}.callgraph.json`, "utf8"))); }
-    catch { console.error(`candor-ts: callgraph ${prefix}.callgraph.json failed to parse — its edges are OMITTED from this query (corrupt or mid-write); re-run the scan`); return {}; }
+    // `null` `<prefix>.callgraph.json` (asymmetric with siblings). Tolerate (empty graph) + disclose,
+    // and TAG the drop (`partial`) so a consumer never mistakes the truncated graph for the whole one.
+    try { return tagPartial(norm(JSON.parse(fs.readFileSync(`${prefix}.callgraph.json`, "utf8"))), false); }
+    catch { console.error(`candor-ts: callgraph ${prefix}.callgraph.json failed to parse — its edges are OMITTED from this query (corrupt or mid-write); re-run the scan`); return tagPartial({}, true); }
   }
   const cg = {};
+  let partial = false;
   for (const f of siblings(prefix, (x) => x.endsWith(".callgraph.json"))) {
     try { Object.assign(cg, JSON.parse(fs.readFileSync(f, "utf8"))); }
-    catch { console.error(`candor-ts: callgraph ${f} failed to parse — its edges are OMITTED from this query (corrupt or mid-write); re-run the scan`); }
+    catch { console.error(`candor-ts: callgraph ${f} failed to parse — its edges are OMITTED from this query (corrupt or mid-write); re-run the scan`); partial = true; }
   }
-  return norm(cg);
+  return tagPartial(norm(cg), partial);
 }
 
 // ---- the §3.1 match ladder: exact > segment-suffix > substring ------------------------------------
@@ -455,10 +532,34 @@ export function diff(curFns, baseFns) {
 // gains: the package-level SUPPLY-CHAIN alarm (spec §5.1) — the UNION of effects the surface gained
 // between two reports (base → cur), with per-function detail. A dependency that grows a Net/Exec reach
 // between releases. Same shape as candor-query's `gains --json`. Built on diff so it can't drift.
-export function gains(curFns, baseFns) {
+//
+// ⟨spec 0.12 staged⟩ each byFunction entry carries `origin` — the candor-gains prototype's key finding
+// promoted into the open query. A gain on a fn that EXISTED at the baseline (shipped pure, now does
+// Net — the supply-chain attack signal) is a different alarm from a NEW fn that does Net (a feature).
+// Reports OMIT pure functions (§2), so existence is keyed on the baseline CALLGRAPH (a baseline-pure
+// fn is a graph node with no report entry):
+//   "existing" — in the baseline report, or a baseline-callgraph node (caller key or callee);
+//   "new"      — a COMPLETE baseline callgraph was loaded and the fn is in neither (did not exist);
+//   "unknown"  — absent from the baseline report AND the graph cannot decide: no baseline callgraph
+//                found (empty graph) OR the graph is PARTIAL (loadCallgraph's non-enumerable `partial`
+//                tag — a matched sidecar failed to load, its edges were dropped-and-disclosed, so
+//                absence from the survivors proves nothing). Undecidable is DISCLOSED, never guessed
+//                (§4) — a partial graph must not downgrade the attack signal from a dropped file's
+//                fns to a benign-looking "new".
+// `baseCg` defaults to {} (no callgraph → "unknown") so core-only callers keep working unchanged.
+export function gains(curFns, baseFns, baseCg = {}) {
+  const baseSet = new Set(baseFns.map((e) => e.fn));
+  const cgNodes = new Set(Object.entries(baseCg).flatMap(([k, vs]) => [k, ...vs]));
+  // The ladder: report hit → existing; graph node → existing (a surviving node is real even in a
+  // partial graph — the drop loses nodes, never invents them); else "new" only when a COMPLETE
+  // non-empty graph can vouch for non-existence; else "unknown".
+  const graphDecides = cgNodes.size > 0 && baseCg.partial !== true;
+  const originOf = (fn) => baseSet.has(fn) ? "existing"
+    : cgNodes.has(fn) ? "existing"
+    : graphDecides ? "new" : "unknown";
   const gained = new Set(), byFunction = [];
   for (const c of diff(curFns, baseFns).changes) {
-    for (const e of c.gained) { gained.add(e); byFunction.push({ fn: c.fn, effect: e }); }
+    for (const e of c.gained) { gained.add(e); byFunction.push({ effect: e, fn: c.fn, origin: originOf(c.fn) }); }
   }
   return { gained: [...gained].sort(), byFunction };
 }

package/query.mjs

@@ -26,6 +26,8 @@ import { fileURLToPath } from "node:url";
 import { parsePolicy, scopeMatches, discoverConfigPolicy } from "./policy.mjs";
 import { hasReport } from "./query-core.mjs";
 import { printAgents } from "./contract.mjs";
+import { bestFinds } from "./surface.mjs";
+import { isTestPath } from "./scan-core.mjs";
 // ONE source of truth for loading + name-matching — query.mjs kept DRIFTED local copies that didn't
 // merge sibling reports, didn't tolerate a corrupt report (bare JSON.parse → uncaught crash), and used
 // a `matchTier` missing `#` (so the SAME query resolved differently between `impact` and `callers` on a
@@ -36,14 +38,63 @@ import { impact as coreImpact, path as corePath, gains as coreGains,
          containment as coreContainment, diff as coreDiff,
          where as coreWhere, map as coreMap, whatif as coreWhatif,
          fix as coreFix, fixGate as coreFixGate, unverified as coreUnverified,
-         loadReport, loadCallgraph, reportVersion } from "./query-core.mjs";
+         matches as coreMatches,
+         loadReport, loadCallgraph, reportVersion, reportPackage } from "./query-core.mjs";
 const emit = (v) => console.log(JSON.stringify(v, null, 1));
 
+// Render `path` in HUMAN (non-`--json`) form — the indented provenance chain, BYTE-IDENTICAL to the
+// Rust reference (candor-query/src/callers.rs) and the Java port (Query.java). The `--json` shape is
+// UNTOUCHED (conformance PART 5 pins `{effect, fn, path:[{fn,loc,source}]}` four-way): this path is
+// only taken when the caller did NOT pass --json, and it reads the SAME `path` array corePath computes.
+// Prints to stdout and returns nothing (matches the JSON-only verbs' fire-and-forget style).
+function renderPathHuman(fns, cg, fnQ, eff) {
+  // Resolve the start over the REPORT entries (as Rust does) — that's where `inferred` lives, and the
+  // no-effect wording quotes it. The RESOLVED name (not the raw query) is then handed to corePath,
+  // which re-resolves over the CALLGRAPH keys — a DIFFERENT name set: a raw partial query could pick
+  // a different fn there (report `app.db.save`, graph `app.cache.save` for the query "save"), so the
+  // header described one function and the chain/verdict another (a misleading "not statically
+  // traceable" over a traceable fn). An exact name resolves identically in both sets (match tier 3,
+  // exact, beats every partial tier and only its own name can equal it), so they cannot disagree.
+  const start = coreMatches(fns.map((e) => e.fn), fnQ)[0];
+  if (start === undefined) {
+    // No matching function at all — parity with Rust/Java's "no function matching" (stderr, exit 2).
+    console.error(`candor-query path: no function matching '${fnQ}'`);
+    process.exit(2);
+  }
+  const startEntry = fns.find((e) => e.fn === start);
+  const inferred = startEntry?.inferred ?? [];
+  if (!inferred.includes(eff)) {
+    // The effect is not even inferred — the honest "does not perform" answer (SPEC §3.1), NOT an error.
+    // `inferred` is printed in Rust's `{:?}` debug shape: each name quoted, ", "-joined, in `[...]`,
+    // in the report's original order (unsorted). An empty set prints `[]`.
+    const dbg = `[${inferred.map((e) => `"${e}"`).join(", ")}]`;
+    console.log(`${start} does not perform ${eff}  (inferred: ${dbg})`);
+    return;
+  }
+  const r = corePath(fns, cg, start, eff);
+  if (r.path.length === 0) {
+    // Inferred, but no LOCAL direct source on a `calls` path — reached cross-crate or via Unknown.
+    console.log(`${start} performs ${eff} but its source is not a local function `
+      + `(cross-crate, or via Unknown) — not statically traceable.`);
+    return;
+  }
+  console.log(`candor path — how \`${start}\` comes to perform ${eff}:\n`);
+  r.path.forEach((step, i) => {
+    const indent = "  ".repeat(i + 1);
+    const arrow = i === 0 ? "" : "→ ";
+    const isSource = i === r.path.length - 1;
+    const tag = isSource
+      ? `   [${eff} source${step.loc ? ` @ ${step.loc}` : ""}]`
+      : "";
+    console.log(`${indent}${arrow}${step.fn}${tag}`);
+  });
+}
+
 // ONE version + spec source, the SAME way scan.mjs reads them: PKG_VERSION is the bare semver from
 // package.json; SPEC_VERSION is the spec contract this build speaks. Reused, never re-littered.
 const QUERY_DIR = path.dirname(fileURLToPath(import.meta.url));
 const PKG_VERSION = JSON.parse(fs.readFileSync(path.join(QUERY_DIR, "package.json"), "utf8")).version;
-const SPEC_VERSION = "0.10";
+const SPEC_VERSION = "0.12";
 
 // ---- the §3.3.1 canonical query grammar (⟨0.10⟩, additive over 0.9) --------------------------------
 // One shape for every verb: `<verb> <verb-args…> [--report <locator>] [--policy <file>] [--json]
@@ -98,6 +149,21 @@ function requireReport(prefix) {
   return prefix;
 }
 
+// Load a report, but FAIL LOUD (exit 2) when a file was found yet nothing parsed — the disclose-and-
+// tolerate loadReport returns [] there, which every verb would read as "no effects": `tour` prints
+// "nothing hidden", a policy `map`/gate PASSES — the §4 cardinal-sin false all-clear over a corrupt
+// report. A legitimately effect-free crate still writes a report that LISTS its functions, so empty +
+// hardFail is always the corrupt case (mirrors candor-rust load_entries_loud; java/swift already die
+// loud). One corrupt file among several still merges (non-empty → returned), staying tolerant.
+function loadReportOrDie(prefix) {
+  const fns = loadReport(prefix);
+  if (fns.length === 0 && fns.hardFail) {
+    console.error(`candor-ts: every report found at prefix '${prefix}' failed to load — refusing to report an empty (all-clear) answer over a corrupt report; re-run the scan.`);
+    process.exit(2);
+  }
+  return fns;
+}
+
 // Parse the canonical flags out of a verb's args, leaving the POSITIONAL verb-args behind. Handles the
 // deprecated `0|1` trailing sentinel (→ noted, dropped; JSON is the default here anyway) so the old
 // grammar stays green. `flags` names the boolean flags this verb honours (`strict`/`includeUnknown`);
@@ -226,6 +292,7 @@ const SUBCOMMANDS = [
   ["reachable", REPORT_TAIL, "effects unioned over the entry points: what the app DOES at runtime"],
   ["impact", `<query> ${REPORT_TAIL}`, "blast radius of a function (backward dual of reachable)"],
   ["blindspots", REPORT_TAIL, "the Unknown sources, ranked by blast radius"],
+  ["tour", `[<N>] ${REPORT_TAIL}`, "the N most surprising transitive reaches — the guided cold-repo poke (no re-scan)"],
   ["gains", "<current> <baseline> [--json]", "the supply-chain alarm: what the surface gained between two reports"],
   ["path", `<fn> <Effect> ${REPORT_TAIL}`, "a call path from a function to where an effect enters"],
   ["whatif", `<fn> <Effect> [--policy <file>] ${REPORT_TAIL}`, "the impact of giving a function an effect, vs a policy (exit 1 on a violation)"],
@@ -287,7 +354,7 @@ switch (cmd) {
     // written; the paths silently vanished) and dropped Exec `cmds` entirely. Call the shared show so
     // the CLI and the MCP `candor_show` are one implementation that cannot diverge again.
     const { prefix, args: [q] } = resolveReportVerb(args, 1);
-    emit(coreShow(loadReport(prefix), q));
+    emit(coreShow(loadReportOrDie(prefix), q));
     break;
   }
   case "where": {
@@ -295,7 +362,7 @@ switch (cmd) {
     // 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, args: [eff] } = resolveReportVerb(args, 1);
-    emit(coreWhere(loadReport(prefix), eff));
+    emit(coreWhere(loadReportOrDie(prefix), eff));
     break;
   }
   case "callers": {
@@ -304,14 +371,14 @@ switch (cmd) {
     // shared query-core so the CLI and MCP compute one truth (the prior inline copy had drifted before).
     const { prefix, args: [q], includeUnknown } = resolveReportVerb(args, 1, { includeUnknown: true });
     const cg = loadCallgraph(prefix);
-    if (includeUnknown) emit(callersFrontier(cg, loadReport(prefix), loadHierarchy(prefix), q));
+    if (includeUnknown) emit(callersFrontier(cg, loadReportOrDie(prefix), loadHierarchy(prefix), q));
     else emit(coreCallers(cg, q));
     break;
   }
   case "map": {
     // Shared query-core — the CLI and MCP `candor_map` are one implementation (see `where` above).
     const { prefix } = resolveReportVerb(args, 0);
-    emit(coreMap(loadReport(prefix)));
+    emit(coreMap(loadReportOrDie(prefix)));
     break;
   }
   case "containment": {
@@ -335,16 +402,16 @@ switch (cmd) {
     }
     prefix = requireReport(prefix);
     if (basePrefix) {
-      const baseFns = loadReport(basePrefix);
+      const baseFns = loadReportOrDie(basePrefix);
       if (baseFns.length === 0) {   // fail CLOSED (exit 2), not a wall of bogus "everything leaked" (exit 1)
         console.error(`candor-ts: no report at baseline prefix '${basePrefix}' — check the path`);
         process.exit(2);
       }
-      const r = coreContainment(loadReport(prefix), baseFns);
+      const r = coreContainment(loadReportOrDie(prefix), baseFns);
       emit(r);
       process.exit(r.leaks.length ? 1 : 0);
     }
-    emit(coreContainment(loadReport(prefix)));
+    emit(coreContainment(loadReportOrDie(prefix)));
     break;
   }
   case "diff": {
@@ -358,8 +425,14 @@ switch (cmd) {
     // each resolved by the shared locator rule (dir / .json path / prefix). --json is accepted (JSON is
     // the only output). No leading-positional-report alias here: both positionals ARE the reports.
     const { positionals } = parseCanonical(args, {});
+    if (positionals.length < 2) { console.error("usage: candor-ts-query diff <current> <baseline> [--json]"); process.exit(2); }
     const [curPrefix, basePrefix] = positionals.map(locatorToPrefix);
-    const { changes } = coreDiff(loadReport(curPrefix), loadReport(basePrefix));
+    // BOTH locators must name real report files (the Rust engine's no-files check, named per side so
+    // the user knows which path to fix): a typo'd prefix loaded [] with hardFail=false and emitted an
+    // authoritative EMPTY {changes:[]} at exit 0 — the §4 false all-clear on the ratchet verb.
+    if (!hasReport(curPrefix)) { console.error(`candor-ts: no report files at current prefix '${curPrefix}' — check the path.`); process.exit(2); }
+    if (!hasReport(basePrefix)) { console.error(`candor-ts: no report files at baseline prefix '${basePrefix}' — check the path.`); process.exit(2); }
+    const { changes } = coreDiff(loadReportOrDie(curPrefix), loadReportOrDie(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).
@@ -379,7 +452,7 @@ switch (cmd) {
     // what the app DOES at runtime: effects unioned over the entry points (SPEC §3.1; same JSON
     // shape as the Rust engine: {entryPoints, effects: {Eff: {count, via}}}).
     const { prefix } = resolveReportVerb(args, 0);
-    const fns = loadReport(prefix);
+    const fns = loadReportOrDie(prefix);
     const roots = fns.filter((e) => e.entryPoint);
     const byEff = {};
     for (const e of roots) for (const x of e.inferred) (byEff[x] ??= []).push(e.fn);
@@ -392,14 +465,90 @@ switch (cmd) {
     // blast radius (backward dual of reachable) — reuses the shared query-core, the same logic the
     // MCP server serves. SPEC §3.1: {fn, affectedCount, affected, entryPoints:[{fn,inferred}]}.
     const { prefix, args: [q] } = resolveReportVerb(args, 1);
-    emit(coreImpact(loadReport(prefix), loadCallgraph(prefix), q));
+    emit(coreImpact(loadReportOrDie(prefix), loadCallgraph(prefix), q));
     break;
   }
   case "blindspots": {
     // the Unknown SOURCES, ranked by blast radius — the actionable inverse of a widely-propagated
     // Unknown (SPEC §3.1 ⟨0.6⟩): { sources:[{fn,why,reaches,affected}], totalUnknown }.
     const { prefix } = resolveReportVerb(args, 0);
-    emit(coreBlindspots(loadReport(prefix), loadCallgraph(prefix)));
+    emit(coreBlindspots(loadReportOrDie(prefix), loadCallgraph(prefix)));
+    break;
+  }
+  case "tour": {
+    // The ON-DEMAND, top-N cold-repo opener (SURFACE-BEST-FIND-DESIGN.md, P2): the N most SURPRISING
+    // transitive reaches in an existing report — NO re-scan. Delegates to the SHARED surface.mjs
+    // bestFinds (the same heuristic the scan-time note uses, so the ranking can't drift), reading the
+    // report + callgraph sidecar the scan already wrote. Port of candor-rust's candor-query tour verb —
+    // human + --json output byte-identical (a conformance PART pins it four-way).
+    // §3.3.1: `tour [<N>]`, report discovered / --report; the lone OPTIONAL positional is N (default 10).
+    // Unlike the JSON-only verbs, tour has BOTH a human default AND a --json form (like the Rust engine),
+    // so detect --json explicitly (parseCanonical otherwise silently swallows it).
+    const wantJson = args.includes("--json");
+    const { prefix, args: tourArgs } = resolveReportVerb(args, 1);
+    let n = 10;
+    if (tourArgs.length) {
+      // N MUST be a positive integer ≥ 1 that fits a safe integer — like the Rust engine, which rejects
+      // `tour 0` and a non-usize. `tour 0` printing "nothing hidden" over an effectful crate would be a
+      // false all-clear (the §4 cardinal sin), so a non-integer, zero, or out-of-range value → exit 2.
+      const parsed = /^\d+$/.test(tourArgs[0]) ? Number(tourArgs[0]) : NaN;
+      if (!Number.isSafeInteger(parsed) || parsed < 1) {
+        console.error("usage: candor-ts-query tour [<N>] [--report <locator>] [--json]   (N is a positive integer ≥ 1)");
+        process.exit(2);
+      }
+      n = parsed;
+    }
+    const fns = loadReportOrDie(prefix);
+    const cg = loadCallgraph(prefix);
+    // Build the maps the heuristic wants from the report entries + the callgraph sidecar. `inferred`/
+    // `direct` come from the report; `loc` maps a function to its "file:line" for the source callout.
+    const inferred = new Map(), direct = new Map(), loc = new Map(), calls = new Map();
+    for (const e of fns) {
+      inferred.set(e.fn, new Set(e.inferred));
+      if (e.direct.length) direct.set(e.fn, new Set(e.direct));
+      if (e.loc) loc.set(e.fn, e.loc);
+    }
+    // `calls` prefers the FULL callgraph sidecar (every edge — the graph the scan held in memory). When
+    // the sidecar is absent/empty, FALL BACK to each entry's inline `.calls` (mirrors tour.rs:66-77:
+    // `if cg.is_empty() { use entry.calls } else { use cg }`). Without this fallback a report whose
+    // sidecar was deleted/never-written yields an empty graph, nearestSource finds nothing, and tour
+    // prints a FALSE "nothing hidden" at exit 0 — a silent under-report (the §4 cardinal sin). A corrupt
+    // sidecar is already disclosed on stderr by loadCallgraph, which then returns {} → we fall back here.
+    if (Object.keys(cg).length === 0) {
+      for (const e of fns) if (e.calls.length) calls.set(e.fn, e.calls);
+    } else {
+      for (const [k, v] of Object.entries(cg)) calls.set(k, v);
+    }
+    // Exclude test scaffolding — a qual is test code iff its recorded loc lies on a test path, the SAME
+    // isTestPath predicate the scan-note passes (scan.mjs's isTestQual). Without it `tour` surfaces test
+    // functions the scan-note (and every other engine) hides — an inconsistent, noisier reach list.
+    const isTestQual = (q) => { const l = loc.get(q); return l ? isTestPath(l) : false; };
+    const finds = bestFinds(inferred, direct, calls, loc, n, isTestQual);
+    // The header names the report's §2 envelope `package` — meaningful and locator-independent, so every
+    // engine and every --report form print the SAME crate. Falls back to the prefix basename.
+    const crateName = reportPackage(prefix) ?? path.basename(prefix);
+    if (wantJson) {
+      // Pure JSON to STDOUT: {"reaches":[{effect,fn,hops,loc,score,source}, …]} — ALPHABETICAL keys, the
+      // same order Rust+Swift emit (loc is the SOURCE's file:line, "" when absent).
+      const out = { reaches: finds.map((f) => ({
+        effect: f.effect, fn: f.func, hops: f.hops, loc: f.sourceLoc, score: f.score, source: f.source,
+      })) };
+      console.log(JSON.stringify(out));
+      break;
+    }
+    if (finds.length === 0) {
+      // Effectful-but-nothing-surprising vs genuinely-pure both land here; the honest line is the useful
+      // answer (never a manufactured surprise) — mirrors the scan-note fallback + the Rust engine.
+      console.log("candor: nothing hidden — every effect sits where its name says it should.");
+      break;
+    }
+    console.log(`candor tour — the ${finds.length} most surprising reach${finds.length === 1 ? "" : "es"} in ${crateName}:`);
+    finds.forEach((f, i) => {
+      const hopWord = f.hops === 1 ? "hop" : "hops";
+      const whereS = f.sourceLoc ? ` (${f.sourceLoc})` : "";
+      console.log(`  ${i + 1}. \`${f.func}\` performs ${f.effect}, ${f.hops} ${hopWord} away via \`${f.source}\`${whereS}`);
+      console.log(`     →  candor path ${f.func} ${f.effect}`);
+    });
     break;
   }
   case "gains": {
@@ -408,16 +557,39 @@ switch (cmd) {
     // §3.3.1: like diff, two positional locators <current> <baseline> (no discovery), each resolved by
     // the shared locator rule; --json accepted.
     const { positionals } = parseCanonical(args, {});
+    if (positionals.length < 2) { console.error("usage: candor-ts-query gains <current> <baseline> [--json]"); process.exit(2); }
     const [curPrefix, basePrefix] = positionals.map(locatorToPrefix);
+    // BOTH locators must name real report files (the Rust engine's no-files check, named per side):
+    // a typo'd prefix loaded [] with hardFail=false and emitted an authoritative EMPTY
+    // {gained:[],byFunction:[]} at exit 0 — a silent all-clear on the supply-chain ALARM verb.
+    if (!hasReport(curPrefix)) { console.error(`candor-ts: no report files at current prefix '${curPrefix}' — check the path.`); process.exit(2); }
+    if (!hasReport(basePrefix)) { console.error(`candor-ts: no report files at baseline prefix '${basePrefix}' — check the path.`); process.exit(2); }
     const gv = reportVersion(curPrefix), gbv = reportVersion(basePrefix);
     if (gv && gbv && gv !== gbv)
       console.error(`candor-ts: ⚠ baseline @${gbv} ≠ engine @${gv} — a "gained capability" may be the engine reclassifying, not the dependency changing. Regenerate both reports with one build to compare releases.`);
-    emit({ baseline_version: gbv ?? "", engine_version: gv ?? "", ...coreGains(loadReport(curPrefix), loadReport(basePrefix)) });
+    // ⟨spec 0.12 staged⟩ the BASELINE callgraph feeds byFunction[].origin (existing/new/unknown) —
+    // a MISSING sidecar loads {} and a corrupt (matched-but-unparseable) one is tagged `partial`
+    // with its edges dropped-and-disclosed: either way "new" is unavailable and origin falls back
+    // to "unknown" — the JSON itself discloses, never guessing "new" over a truncated graph.
+    emit({ baseline_version: gbv ?? "", engine_version: gv ?? "", ...coreGains(loadReportOrDie(curPrefix), loadReportOrDie(basePrefix), loadCallgraph(basePrefix)) });
     break;
   }
   case "path": {
+    // BOTH a human default AND a --json form (like the Rust/Java engines). The surface opener suggests
+    // `candor path <fn> <effect>`, so the DEFAULT is the readable indented chain; --json selects the
+    // pinned JSON shape. parseCanonical otherwise swallows --json, so detect it explicitly (as `tour` does).
+    const wantJson = args.includes("--json");
     const { prefix, args: [fn, eff] } = resolveReportVerb(args, 2);
-    emit(corePath(loadReport(prefix), loadCallgraph(prefix), fn, eff));
+    const fns = loadReportOrDie(prefix);
+    const cg = loadCallgraph(prefix);
+    if (wantJson) emit(corePath(fns, cg, fn, eff));           // conformance PART 5 shape — UNCHANGED
+    else {
+      // The accepted 0.11 default change (the human chain replaced JSON as the no-flag output) gets a
+      // ONE-line stderr breadcrumb, so a pre-0.11 pipeline that broke on the new default is pointed at
+      // --json rather than left guessing. stderr only — stdout stays the human chain; --json untouched.
+      console.error("candor-ts-query: tip — `--json` selects the machine-readable path shape (the default before 0.11)");
+      renderPathHuman(fns, cg, fn, eff);
+    }
     break;
   }
   case "whatif": {
@@ -466,7 +638,7 @@ switch (cmd) {
     // The sidecar is the ONLY graph a candor-ts report carries (it embeds no inline `calls`). Fail LOUD when
     // it's absent — never compute a degenerate empty-graph remedy that reads as a false "no clean hoist".
     if (!cg || Object.keys(cg).length === 0) { console.error(`candor: no call-graph sidecar for '${prefix}' — fix needs it (re-run: candor-ts <src> --out ${prefix})`); process.exit(2); }
-    const r = coreFix(cg, loadReport(prefix), target, eff, parsePolicy(ptext), scopeMatches);
+    const r = coreFix(cg, loadReportOrDie(prefix), target, eff, parsePolicy(ptext), scopeMatches);
     if (r === null) { console.error(`candor: no function matching \`${target}\` in the call graph`); process.exit(2); }
     emit(r);
     break;
@@ -482,7 +654,7 @@ switch (cmd) {
     catch { console.error(`candor: policy ${policyFile} could not be read — no fix computed`); process.exit(2); }
     const cg = loadCallgraph(prefix);
     if (!cg || Object.keys(cg).length === 0) { console.error(`candor: no call-graph sidecar for '${prefix}' — fix-gate needs it (re-run: candor-ts <src> --out ${prefix})`); process.exit(2); }
-    emit(coreFixGate(cg, loadReport(prefix), parsePolicy(ptext), scopeMatches));
+    emit(coreFixGate(cg, loadReportOrDie(prefix), parsePolicy(ptext), scopeMatches));
     break;
   }
   case "unverified": {
@@ -495,7 +667,7 @@ switch (cmd) {
     let ptext;
     try { ptext = fs.readFileSync(policyFile, "utf8"); }
     catch { console.error(`candor: policy ${policyFile} could not be read`); process.exit(2); }
-    const r = coreUnverified(loadReport(prefix), parsePolicy(ptext), scopeMatches);
+    const r = coreUnverified(loadReportOrDie(prefix), parsePolicy(ptext), scopeMatches);
     emit(r);
     process.exit(strict && !r.ok ? 1 : 0);
     break; // unreachable

package/scan.mjs

@@ -30,6 +30,7 @@ import { parsePolicy, evaluatePolicy, scopeMatches } from "./policy.mjs";
 import { unverifiedHoleRule, ruleUpgrade } from "./query-core.mjs";
 import { printAgents } from "./contract.mjs";
 import { isTestPath, kappa, kappaKnows, commandHeadEffects, hostLiteral, tablesInSql } from "./scan-core.mjs";
+import { emitSurface } from "./surface.mjs";
 
 const ENGINE_DIR = path.dirname(fileURLToPath(import.meta.url));
 
@@ -39,7 +40,7 @@ const ENGINE_DIR = path.dirname(fileURLToPath(import.meta.url));
 // literal stamped into the envelope's `spec` field, so the doc lines and the report can never drift.
 // Reused, never re-littered.
 const PKG_VERSION = JSON.parse(fs.readFileSync(path.join(ENGINE_DIR, "package.json"), "utf8")).version;
-const SPEC_VERSION = "0.10";
+const SPEC_VERSION = "0.12";
 
 // --version: a print-and-exit MODE, handled before the main arg walk so it never depends on a target.
 // Fully OFFLINE — candor never phones home. Staying current is the AGENT's job: read the installed
@@ -1733,7 +1734,7 @@ function visitCalls(node) {
           }
           // unmatched external = (OPAQUE): contributes nothing — the curated-κ caveat C1. The
           // κ-coverage LEDGER makes the caveat per-scan evidence instead of a doc footnote: count
-          // every npm package the code demonstrably calls that κ doesn't know and no sibling
+          // every npm package the code demonstrably calls that the classifier doesn't cover ("classifier doesn't cover" marker) and no sibling
           // report covers (the argon2 lesson — the blind spot landed on exactly the call a
           // security review cared about). Builtins are excluded: κ's builtin coverage is the
           // bounded frontier, and an unlisted builtin (path, util) is known-pure, not blind.
@@ -2111,6 +2112,11 @@ for (const [name, rec] of fns) {
     overdeclared: [],
     unresolved: inf.includes("Unknown"),
   };
+  // Inline call edges (§2 `calls`) — the SAME edges the callgraph sidecar carries, embedded per entry so a
+  // consumer without the sidecar (deleted, never-written, an old workspace) can still reconstruct the graph.
+  // `tour` falls back to these when the sidecar is empty (surface robustness — mirrors the Rust report, whose
+  // entries carry `calls`); omitted when a fn has no outgoing edges to keep pure leaves lean.
+  if (rec.edges.size) entry.calls = [...rec.edges].sort();
   if (inf.includes("Net") && rec.hosts.size) entry.hosts = [...rec.hosts].sort();
   if (inf.includes("Db") && rec.tables.size) entry.tables = [...rec.tables].sort();
   if (inf.includes("Exec") && rec.cmds.size) entry.cmds = [...rec.cmds].sort();
@@ -2187,8 +2193,29 @@ if (unlistedSeen.size > 0) {
   const top = [...unlistedSeen.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
   const shown = top.slice(0, 8).map(([p, n]) => `${p} (${n} call${n === 1 ? "" : "s"})`).join(", ");
   const more = top.length > 8 ? ` + ${top.length - 8} more` : "";
-  console.error(`candor-ts: κ doesn't know ${top.length} package${top.length === 1 ? "" : "s"} this code calls into — `
-    + `effects through ${top.length === 1 ? "it are" : "them are"} INVISIBLE (not Unknown): ${shown}${more}`);
+  console.error(`candor-ts: candor's classifier doesn't cover ${top.length} package${top.length === 1 ? "" : "s"} this code calls into — `
+    + `their effects are INVISIBLE to the scan (absent from the report, NOT a claim they're pure): ${shown}${more}`);
+}
+
+// ---- the cold-repo hook: surface the single most SURPRISING transitive reach (surface.mjs) ---------
+// One extra stderr line after the coverage ledger — the most benign-named function reaching a scary
+// effect a few hops away + a ready-to-run `candor path`. Deterministic; honest "nothing hidden"
+// fallback. Ported EXACTLY from candor-rust's surface.rs so every engine surfaces the SAME reach on a
+// shared fixture. Prefix is `candor:` (brand voice) and the command is `candor path …` — identical on
+// every engine. STDERR only, so the --json report on stdout stays clean.
+if (!wantJson) {
+  const directMap = new Map();
+  const callsMap = new Map();
+  const locMap = new Map();
+  for (const [name, rec] of fns) {
+    directMap.set(name, rec.direct);
+    callsMap.set(name, rec.edges);
+    if (rec.loc) locMap.set(name, rec.loc);
+  }
+  // A qual is test code iff its recorded loc (file:line[:col]) lies on a test path — the same predicate
+  // the scan already uses to keep test files out of the report.
+  const isTestQual = (q) => { const l = locMap.get(q); return l ? isTestPath(l) : false; };
+  emitSurface(inferred, directMap, callsMap, locMap, isTestQual);
 }
 
 // ---- the gate surfaces: the AS-EFF-005 baseline guard + the standing §6.2 policy gate --------------

package/surface.mjs

@@ -0,0 +1,233 @@
+// Surface the single most SURPRISING transitive reach (the cold-repo hook).
+//
+// After the effect summary + coverage ledger, candor-ts emits ONE more stderr line: the most surprising
+// transitive reach in the project + a ready-to-run `candor path` command. Port of candor-rust's
+// crates/candor-scan/src/surface.rs — same behavior, idiomatic JS. See SURFACE-BEST-FIND-DESIGN.md.
+//
+// Fully deterministic — pure call-graph + name analysis, NO LLM. A CANDIDATE is a function `F` that
+// INHERITS an effect `E` (E ∈ inferred[F] but E ∉ direct[F]); we BFS to the nearest local direct SOURCE
+// `S` and score by how surprising the reach is (a benign-named function reaching a scary effect). The
+// find is never *wrong*: `candor path` re-derives the chain and the gate is ground truth. When nothing
+// clears the bar we emit an honest "nothing hidden" fallback — never a manufactured surprise.
+
+// Name tokens that read as local / pure / config — a function whose leaf is named like this reaching a
+// scary effect is the core surprise signal. Copied verbatim from surface.rs BENIGN.
+const BENIGN = new Set([
+  "settings", "config", "conf", "options", "opts", "util", "utils", "helper", "helpers", "model",
+  "models", "dto", "entity", "format", "fmt", "parse", "get", "load", "new", "default", "validate",
+  "valid", "render", "view", "build", "builder", "item", "entry", "record", "state", "context",
+  "ctx", "info", "meta", "data", "value", "node", "field", "name", "key", "id", "path", "kind",
+  "type", "status", "check", "init", "setup",
+]);
+
+// Name tokens that are effect-suggestive — a function in/near an effect-flavored context reaching that
+// effect is EXPECTED, not surprising, so we EXCLUDE it. Copied verbatim from surface.rs EFFECTY.
+const EFFECTY = new Set([
+  "fetch", "http", "https", "client", "api", "sync", "request", "req", "download", "upload", "query",
+  "sql", "store", "save", "persist", "connect", "conn", "socket", "send", "recv", "read", "write",
+  "open", "file", "fs", "io", "net", "tcp", "udp", "dns", "url", "host", "port", "cmd", "command",
+  "shell", "process", "proc", "exec", "spawn", "env", "clock", "time", "now", "rand", "random",
+  "log", "logger", "trace", "db",
+]);
+
+// The qualified-name separator. Rust uses `::`; candor-ts quals are `mod.Class.member`.
+const SEP = ".";
+
+// Split a qualified name (or a leaf) into lowercase tokens on the separator, `_`, and camelCase
+// boundaries. Mirrors surface.rs::tokenize (which splits on `_`, `:` and camelCase).
+export function tokenize(name) {
+  const out = [];
+  let cur = "";
+  let prevLower = false;
+  for (const ch of name) {
+    if (ch === "_" || ch === "." || ch === ":") {
+      if (cur) { out.push(cur); cur = ""; }
+      prevLower = false;
+      continue;
+    }
+    // Unicode-aware uppercase (matches surface.rs's `ch.is_uppercase()`): a letter that differs from
+    // its lowercase form and equals its uppercase form. ASCII-only for the digit check (surface.rs uses
+    // `is_ascii_digit`), so a non-ASCII uppercase letter STILL starts a new token.
+    const lower = ch.toLowerCase();
+    const isUpper = ch !== lower && ch === ch.toUpperCase();
+    const isLower = ch !== ch.toUpperCase() && ch === lower;
+    // camelCase boundary: a lower/digit followed by an upper starts a new token.
+    if (isUpper && prevLower && cur) { out.push(cur); cur = ""; }
+    cur += lower;
+    prevLower = isLower || (ch >= "0" && ch <= "9");
+  }
+  if (cur) out.push(cur);
+  return out;
+}
+
+// The leaf (final segment) of a qualified name.
+function leaf(qual) {
+  const i = qual.lastIndexOf(SEP);
+  return i < 0 ? qual : qual.slice(i + SEP.length);
+}
+
+// The module portion of a qualified name (everything before the leaf).
+function moduleOf(qual) {
+  const i = qual.lastIndexOf(SEP);
+  return i < 0 ? "" : qual.slice(0, i);
+}
+
+// The first token of `name` that appears in `lexicon`, or null.
+function hasToken(name, lexicon) {
+  for (const t of tokenize(name)) if (lexicon.has(t)) return t;
+  return null;
+}
+
+// Salience of an effect — the boundary/security-relevant effects a reviewer cares about score higher.
+// Clock/Log/Rand are DELIBERATELY 0 (not surfaced): a mundane clock/log reach isn't "the most
+// surprising reach", and a repo whose only reaches are mundane should honestly say "nothing hidden".
+// Matches the Rust reference (candor-classify/src/surface.rs) + the java/swift ports.
+function salience(effect) {
+  switch (effect) {
+    case "Net": case "Exec": case "Db": case "Ipc": return 5;
+    case "Fs": case "Env": return 3;
+    default: return 0; // Clock/Log/Rand/Unknown/everything-else — mundane, never surfaced
+  }
+}
+
+function hopsFactor(hops) {
+  if (hops === 1) return 2;
+  if (hops >= 2 && hops <= 4) return 3;
+  if (hops >= 5 && hops <= 6) return 2;
+  return 1; // ≥7 (hops is always ≥1 for an inherited reach)
+}
+
+// BFS from `func` over `calls` (follow callees, shortest hops) to the nearest function `S` with
+// `effect` ∈ direct[S]. Returns { hops≥1, source } or null. Only traverses through callees that
+// transitively carry the effect, so the frontier stays on-effect (matches `candor path`'s walk).
+function nearestSource(func, effect, direct, inferred, calls) {
+  const seen = new Set([func]);
+  const q = [[func, 0]];
+  let head = 0;
+  while (head < q.length) {
+    const [cur, d] = q[head++];
+    // A direct source found at distance d≥1 is the nearest (BFS). The start `func` itself is an
+    // INHERITED reach (E ∉ direct[func]) so it never matches at d==0.
+    if (d >= 1 && direct.get(cur)?.has(effect)) return { hops: d, source: cur };
+    const cs = calls.get(cur);
+    if (cs) {
+      // Iterate callees in SORTED order — surface.rs/Java/Swift walk a BTreeSet<String> (sorted), so at
+      // an equal-distance tie the SAME source/score/`candor path` is chosen on every engine. Raw Map/JSON
+      // insertion order here would let a tie resolve differently (non-determinism vs the reference).
+      for (const c of [...cs].sort()) {
+        if (!seen.has(c) && inferred.get(c)?.has(effect)) {
+          seen.add(c);
+          q.push([c, d + 1]);
+        }
+      }
+    }
+  }
+  return null;
+}
+
+// Collect EVERY scored candidate reach (unranked), plus whether the project is effectful at all. The
+// single source of the candidate pool for both bestFind (top-1) and bestFinds (top-N) — one heuristic,
+// no drift. `loc` is a Map<qual, "file:line"> for the source callout ("" when absent). Returns
+// { cands: <Find[]>, anyEffectful }.
+function collectCandidates(inferred, direct, calls, loc, isTest) {
+  // Any function carrying a real (non-Unknown) effect makes the project "effectful" — governs
+  // whether the caller emits the fallback vs nothing.
+  let anyEffectful = false;
+
+  // Deterministic iteration: sort quals ascending so the tie-break (qual ascending) is stable and
+  // Map insertion order never leaks into the result.
+  const quals = [...inferred.keys()].sort();
+
+  const cands = [];
+
+  for (const f of quals) {
+    const inf = inferred.get(f);
+    for (const e of inf) if (e !== "Unknown") { anyEffectful = true; break; }
+    if (isTest(f)) continue;
+    const fLeaf = leaf(f);
+    const fMod = moduleOf(f);
+    // EXCLUDE the whole function if its leaf OR module reads effecty — its reach is obvious.
+    if (hasToken(fLeaf, EFFECTY) || hasToken(fMod, EFFECTY)) continue;
+    const dir = direct.get(f) ?? new Set();
+    // Candidate effects: inherited (in inferred, not direct), not Unknown; sorted ascending.
+    const effects = [...inf].filter((e) => e !== "Unknown" && !dir.has(e)).sort();
+    for (const e of effects) {
+      const sal = salience(e);
+      if (sal === 0) continue;
+      const ns = nearestSource(f, e, direct, inferred, calls);
+      if (!ns) continue; // no LOCAL direct source — nothing to show
+      const benign = hasToken(fLeaf, BENIGN);
+      const benignity = benign ? 3 : 1;
+      const crossing = moduleOf(ns.source) !== fMod ? 2 : 1;
+      const score = sal * benignity * hopsFactor(ns.hops) * crossing;
+      if (score === 0) continue;
+      cands.push({
+        func: f, effect: e, hops: ns.hops, source: ns.source,
+        sourceLoc: loc?.get(ns.source) ?? "", benignToken: benign ?? "", score,
+      });
+    }
+  }
+  return { cands, anyEffectful };
+}
+
+// Compute the top-`n` most surprising reaches, most-surprising first. DEDUPED by function — each
+// function appears at most once (its single highest-scoring reach). The list is empty when nothing
+// clears the bar. Each Find carries { func, effect, hops, source, sourceLoc, benignToken, score }.
+//
+// Ranking (the tie-break, applied to the whole candidate pool before the per-function dedup + take):
+// score DESC → hops ASC → qualified name ASC. With `n === 1` the result is BYTE-IDENTICAL to the old
+// bestFind's winner — the shared candidate pool + this same tie-break, one implementation. Port of
+// surface.rs::best_finds. `loc` is a Map<qual, "file:line"> for the source callout (optional).
+export function bestFinds(inferred, direct, calls, loc, n, isTest = () => false) {
+  const { cands } = collectCandidates(inferred, direct, calls, loc, isTest);
+  // Rank the whole pool: score DESC, hops ASC, qual ASC. Quals were iterated ascending and effects
+  // ascending, so on a full tie the first-pushed (smallest qual) candidate sorts first — matching the
+  // old bestFind's "keep the earliest winner on an exact tie" (a stable sort preserves push order).
+  cands.sort((a, b) => (b.score - a.score) || (a.hops - b.hops) || (a.func < b.func ? -1 : a.func > b.func ? 1 : 0));
+  // DEDUP by function — each appears at most once (its highest-scoring reach, first in ranked order).
+  // Then take up to `n` distinct functions.
+  const seenFns = new Set();
+  const out = [];
+  for (const c of cands) {
+    if (out.length >= n) break;
+    if (!seenFns.has(c.func)) { seenFns.add(c.func); out.push(c); }
+  }
+  return out;
+}
+
+// Compute the single most surprising reach (the scan-time note).
+//   · returns null                      — ZERO effectful functions (caller emits nothing)
+//   · returns { winner: null }          — effectful, but none cleared the bar (honest fallback)
+//   · returns { winner: <Find> }        — the winning reach
+//
+// `inferred`/`direct` are Map<qual, Set<effect>>; `calls` is Map<qual, Iterable<qual>>; `isTest` is an
+// optional (qual) => bool predicate (defaults to false — the caller supplies path-based test detection).
+// ONE implementation with bestFinds — the winner is exactly bestFinds(…, 1)[0] (the scan-note output
+// stays byte-identical, verified by the surface tests + conformance).
+export function bestFind(inferred, direct, calls, isTest = () => false) {
+  const { anyEffectful } = collectCandidates(inferred, direct, calls, undefined, isTest);
+  if (!anyEffectful) return null;
+  const top = bestFinds(inferred, direct, calls, undefined, 1, isTest);
+  return { winner: top.length ? top[0] : null };
+}
+
+// Emit the surface note to STDERR. `loc` is a Map<qual, "file:line"> for the source callout; `log` is
+// the sink (defaults to console.error). Mirrors surface.rs::emit exactly.
+export function emitSurface(inferred, direct, calls, loc, isTest = () => false, log = console.error) {
+  const res = bestFind(inferred, direct, calls, isTest);
+  if (res === null) return; // zero effectful functions — emit nothing
+  if (res.winner === null) {
+    log("candor: nothing hidden — every effect sits where its name says it should.");
+    return;
+  }
+  const f = res.winner;
+  const whereS = loc.get(f.source) ?? "?";
+  const hopWord = f.hops === 1 ? "hop" : "hops";
+  const benignNote = f.benignToken
+    ? `          a "${f.benignToken}"-named function reaching ${f.effect}.\n`
+    : "";
+  log(
+    `candor: most surprising reach — \`${f.func}\` performs ${f.effect}, ${f.hops} ${hopWord} away via `
+    + `\`${f.source}\` (${whereS}).\n${benignNote}          →  candor path ${f.func} ${f.effect}`,
+  );
+}