candor-ts 0.9.2 → 0.11.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.9)."*
+> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.11)."*
 > 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`.
 >
@@ -93,6 +93,7 @@ Q impact   $P <fn-query>            # THE BLAST RADIUS: {fn, affectedCount, affe
 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.9" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
+| `{ candor: { version, toolchain, spec: "0.11" }, 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.9.x, speaking candor-spec 0.9: the analysis core, the gate (`--policy` / `--gate-json` /
+0.11.x, speaking candor-spec 0.11: 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "candor-ts",
-  "version": "0.9.2",
-  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.9)",
+  "version": "0.11.0",
+  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.11)",
   "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,21 +86,89 @@ 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`); }
+    const r = loadOneReport(f, f);
+    fns.push(...r.entries);
+    if (r.hardFail) hardFail = true;
   }
-  return fns;
+  return tagHardFail(fns, hardFail);
 }
 export function loadCallgraph(prefix) {
   // A `null`/non-object parse (a `null` callgraph, an array, a number) must NOT reach Object.entries —

package/query.mjs

@@ -9,19 +9,25 @@
  * but its author had by then read the reference engines; the ongoing guarantee for it is the
  * conformance differential, not clean-room provenance.
  *
- *   node query.mjs parsepolicy <file>
- *   node query.mjs show     <prefix> <query>  <0|1>
- *   node query.mjs where    <prefix> <Effect> <0|1>
- *   node query.mjs callers  <prefix> <query>  <0|1>
- *   node query.mjs map      <prefix>          <0|1>
- *   node query.mjs whatif   <prefix> <fn> <Effect> [policy-file] [0|1]
+ * CANONICAL grammar (candor-spec §3.3.1 ⟨0.10⟩ — one shape, every engine):
+ *   node query.mjs <verb> <verb-args…> [--report <locator>] [--policy <file>] [--json] [--strict] [--include-unknown]
+ * The report is DISCOVERED (walk up from CWD for a `.candor/` dir → `<that>/.candor/report`; CANDOR_REPORT
+ * overrides) unless --report gives a locator (a dir → `<dir>/.candor/report`; a `.json` path → that report
+ * path; else a prefix). diff/gains are the exception: two positional locators <current> <baseline>.
+ *
+ * DEPRECATED aliases (kept accepted through the 0.10 line, stderr-noted — candor-spec §3.3.1 / PART 17):
+ *   node query.mjs <verb> <PREFIX> <verb-args…> [0|1]      (leading-positional report + trailing 0|1 sentinel)
+ *   node query.mjs whatif/fix <prefix> <fn> <Effect> [policy-file] [0|1]   (positional policy)
  */
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { parsePolicy, scopeMatches } from "./policy.mjs";
+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
@@ -32,35 +38,263 @@ 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. corePath resolves over the callgraph keys for the chain; the two agree
+  // on any fn that has an entry, which every graphed fn does.
+  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, fnQ, 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.9";
+const SPEC_VERSION = "0.11";
+
+// ---- 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]
+// [--strict] [--include-unknown]`. The report is DISCOVERED by default; --report overrides. The old
+// leading-positional-report form, the trailing `0|1` JSON sentinel, and a positional policy stay
+// accepted as DEPRECATED aliases (stderr-noted) so the conformance suite's old-grammar invocations
+// (and every 0.9 caller) keep working — never removed before the next breaking bump.
+
+// A one-line deprecation note to STDERR (stdout stays pure JSON — the machine consumer never sees it).
+// De-duplicated so a single invocation prints each distinct note at most once.
+const _deprecated = new Set();
+const deprecate = (msg) => { if (!_deprecated.has(msg)) { _deprecated.add(msg); console.error(`candor-ts-query: [deprecated] ${msg}`); } };
+
+// Resolve a --report <locator> by the ONE §3.3.1 rule: a directory → `<dir>/.candor/report`; a path
+// ending `.json` → that full report path (minus the `.json`, since loadReport takes a prefix and adds
+// it back); otherwise a bare prefix. Returns the PREFIX loadReport/loadCallgraph expect.
+function locatorToPrefix(loc) {
+  try { if (fs.statSync(loc).isDirectory()) return path.join(loc, ".candor", "report"); } catch { /* not a dir */ }
+  if (loc.endsWith(".json")) return loc.slice(0, -".json".length);   // full report path → its prefix
+  return loc;                                                        // bare prefix
+}
+
+// DISCOVER the report prefix when no --report: CANDOR_REPORT env wins; else walk UP from CWD for a
+// `.candor/` directory and use its `report` prefix (the §3.4 discovery mechanism, the twin of scan.mjs's
+// config walk-up). Returns null when NEITHER is found — the caller then fails LOUD (exit 2). It must NOT
+// fall back to a bogus `.candor/report` prefix: that made the loaders read ZERO functions and every
+// discovery verb emit an authoritative-empty answer at exit 0 — a false all-clear, the §4 cardinal sin
+// (`where Net` in a dir with no `.candor/` up-tree). Matches the Rust engine's discover_report_prefix.
+function discoverReportPrefix() {
+  const env = process.env.CANDOR_REPORT;
+  if (env) return locatorToPrefix(env);
+  for (let d = process.cwd(); ; d = path.dirname(d)) {
+    if (fs.existsSync(path.join(d, ".candor"))) return path.join(d, ".candor", "report");
+    if (path.dirname(d) === d) break;                                // filesystem root
+  }
+  return null;                                                       // no --report, no .candor/ discovered
+}
+
+// The report prefix for a discovery verb (no --report): the parsed/explicit locator, else discovery.
+// A null prefix (no --report AND nothing discovered) is a LOUD exit-2 failure — never a silent empty
+// answer. A resolved prefix that names NO report files is likewise loud (hasReport). One helper so every
+// verb's no-report path is identical to the Rust engine's (report_or_discover + the no-files check).
+function requireReport(prefix) {
+  if (prefix === null) {
+    console.error("candor-ts: no report found (no --report and no .candor/ discovered) — scan the crate first.");
+    process.exit(2);
+  }
+  if (!hasReport(prefix)) {
+    console.error(`candor-ts: no report files at prefix '${prefix}' — check the path, or scan the crate first.`);
+    process.exit(2);
+  }
+  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`);
+// `argc` is the verb's CANONICAL positional arity (report excluded) — the sentinel/leading-report peels
+// are gated on the positional count EXCEEDING it, so a canonical arg (`show 1`, `callers 0`, `path fn 0`)
+// is never eaten as a sentinel (matches the Rust grammar's Shape.verb_args arity gate).
+// Returns { positionals, reportPrefix, reportExplicit, policyFile, strict, includeUnknown }.
+function parseCanonical(rawArgs, { policy = false, strict = false, includeUnknown = false, argc = 0 } = {}) {
+  const positionals = [];
+  let reportLocator = null, policyFile = null, wantStrict = false, wantIncludeUnknown = false;
+  for (let i = 0; i < rawArgs.length; i++) {
+    const a = rawArgs[i];
+    if (a === "--report") {
+      // A `--report` with no following value is a LOUD usage error (exit 2), never a silent fall-back to
+      // discovery and never an uncaught `locatorToPrefix(undefined)` TypeError (`where Fs --report`).
+      if (i + 1 >= rawArgs.length) { console.error("candor-ts: --report requires a <locator> value (a directory, a .json report path, or a prefix)"); process.exit(2); }
+      reportLocator = rawArgs[++i]; continue;
+    }
+    if (policy && a === "--policy") {
+      if (i + 1 >= rawArgs.length) { console.error("candor-ts: --policy requires a <file> value"); process.exit(2); }
+      policyFile = rawArgs[++i]; continue;
+    }
+    if (a === "--json") { continue; }                                // JSON is candor-ts's only output; accept + ignore
+    if (strict && a === "--strict") { wantStrict = true; continue; }
+    if (includeUnknown && a === "--include-unknown") { wantIncludeUnknown = true; continue; }
+    positionals.push(a);
+  }
+  // Deprecated trailing `0|1` JSON sentinel (Rust/TS legacy): if the LAST positional is a bare 0 or 1,
+  // strip it (candor-ts emits JSON regardless) and note the deprecation. ARITY-GATED: only when the
+  // positional count EXCEEDS the verb's canonical arity — otherwise `show 1` / `callers 0` / `where 1` /
+  // `path fn 0` would have their genuine query token eaten and run with a missing arg (degenerate empty
+  // result, exit 0). Never strip a positional the canonical form needs (matches Rust's arity gate).
+  if (positionals.length > argc && /^[01]$/.test(positionals[positionals.length - 1])) {
+    deprecate("the trailing `0|1` JSON sentinel is deprecated — candor-ts emits JSON; use --json to select it explicitly");
+    positionals.pop();
+  }
+  const reportExplicit = reportLocator !== null;
+  const reportPrefix = reportExplicit ? locatorToPrefix(reportLocator) : discoverReportPrefix();
+  return { positionals, reportPrefix, reportExplicit, policyFile, strict: wantStrict, includeUnknown: wantIncludeUnknown };
+}
+
+// A verb that takes ONE report + `argc` verb-positionals (where <Effect>: 1; show/callers/impact <fn>:
+// 1; path <fn> <Effect>: 2; map/reachable/blindspots: 0). Applies discovery + --report, then peels the
+// DEPRECATED leading-positional report: if --report wasn't given AND the first positional resolves to a
+// report AND there's one positional MORE than the verb needs, treat that first token as the report.
+// Returns { prefix, args } — `args` is exactly the verb's own positionals.
+function resolveReportVerb(rawArgs, argc, opts = {}) {
+  const p = parseCanonical(rawArgs, { ...opts, argc });
+  let { positionals, reportPrefix } = p;
+  if (!p.reportExplicit && positionals.length === argc + 1 && hasReport(locatorToPrefix(positionals[0]))) {
+    deprecate("a leading-positional report is deprecated — pass it as `--report <locator>` (a dir, a .json path, or a prefix); the report is discovered from `.candor/` by default");
+    reportPrefix = locatorToPrefix(positionals[0]);
+    positionals = positionals.slice(1);
+  }
+  return { ...p, prefix: requireReport(reportPrefix), args: positionals };
+}
+
+// whatif/fix share a shape: one report + `<fn> <Effect>` + a policy. Canonical §3.3.1: `<fn> <Effect>
+// [--policy <file>]`, report discovered/--report. DEPRECATED aliases (kept green for the old grammar):
+// a leading-positional report AND a trailing positional policy — `<prefix> <fn> <Effect> [policy]`.
+// Peels both (stderr-noted), then resolves the policy through resolvePolicy (flag > positional >
+// CANDOR_POLICY > .candor/config). Returns { prefix, target, eff, policyFile }.
+function resolveWhatifFix(rawArgs) {
+  const p = parseCanonical(rawArgs, { policy: true, argc: 2 });
+  let positionals = p.positionals, prefix = p.reportPrefix, positionalPolicy = null;
+  // A leading-positional report fires only when --report is absent, there are MORE than the 2 verb args,
+  // and the first token resolves to a report (else the extra positional is the deprecated policy).
+  if (!p.reportExplicit && positionals.length > 2 && hasReport(locatorToPrefix(positionals[0]))) {
+    deprecate("a leading-positional report is deprecated — pass it as `--report <locator>`; the report is discovered from `.candor/` by default");
+    prefix = locatorToPrefix(positionals[0]);
+    positionals = positionals.slice(1);
+  }
+  const [target, eff, posPolicy] = positionals;               // a 3rd positional is the deprecated policy
+  if (posPolicy) positionalPolicy = posPolicy;
+  const { policyFile } = resolvePolicy(p.policyFile, positionalPolicy);
+  return { prefix: requireReport(prefix), target, eff, policyFile };
+}
+
+// fix-gate/unverified share a shape: one report + a policy + no verb-positionals (unverified also takes
+// --strict). Canonical §3.3.1: `[--policy <file>] [--strict]`, report discovered/--report. DEPRECATED
+// alias: a leading report + a positional policy — `<prefix> <policy-file> [--strict]`. Peels both
+// (stderr-noted), then resolves the policy through resolvePolicy. Returns { prefix, policyFile, strict }.
+function resolveGateVerb(rawArgs, { strict = false } = {}) {
+  const p = parseCanonical(rawArgs, { policy: true, strict, argc: 0 });
+  let positionals = p.positionals, prefix = p.reportPrefix, positionalPolicy = null;
+  if (!p.reportExplicit && positionals.length && hasReport(locatorToPrefix(positionals[0]))) {
+    deprecate("a leading-positional report is deprecated — pass it as `--report <locator>`; the report is discovered from `.candor/` by default");
+    prefix = locatorToPrefix(positionals[0]);
+    positionals = positionals.slice(1);
+  }
+  if (positionals[0]) positionalPolicy = positionals[0];       // the remaining positional is the deprecated policy
+  const { policyFile } = resolvePolicy(p.policyFile, positionalPolicy);
+  return { prefix: requireReport(prefix), policyFile, strict: p.strict };
+}
+
+// Resolve the policy for the gate verbs (whatif/fix/fix-gate/unverified): the --policy flag, else the
+// deprecated positional policy, else CANDOR_POLICY, else the `.candor/config` `policy` key (§3.3/§3.4,
+// the same precedence scan.mjs uses). Returns { policyFile, fromPositional } — policyFile null if none.
+function resolvePolicy(policyFlag, positionalPolicy) {
+  if (policyFlag) return { policyFile: policyFlag, fromPositional: false };
+  if (positionalPolicy) {
+    deprecate("a positional policy file is deprecated — pass it as `--policy <file>` (or set CANDOR_POLICY / a .candor/config `policy` key)");
+    return { policyFile: positionalPolicy, fromPositional: true };
+  }
+  if (process.env.CANDOR_POLICY) return { policyFile: process.env.CANDOR_POLICY, fromPositional: false };
+  const disc = discoverConfigPolicy(process.cwd());
+  if (disc?.policyPath) return { policyFile: disc.policyPath, fromPositional: false };
+  return { policyFile: null, fromPositional: false };
+}
 
 // The full subcommand catalogue — name + one-line description (derived from the per-subcommand
 // comments + the module-doc header). The single source for the --help list AND the no-arg/unknown
 // usage, so the two can never drift back to a stale hand-list again.
+// Grammar per candor-spec §3.3.1 ⟨0.10⟩: the report is a FLAG (--report), discovered from `.candor/`
+// by default; verb args are positional; --json selects JSON; --policy supplies a policy. The old
+// leading-positional/`0|1`/positional-policy forms stay accepted as deprecated aliases (see the parser).
+const REPORT_TAIL = "[--report <locator>] [--json]";
 const SUBCOMMANDS = [
   ["parsepolicy", "<file>", "parse a policy file (candor-spec §6.2) and print it as JSON"],
-  ["show", "<prefix> <query> [0|1]", "the effect record(s) for a function — direct, inferred, surfaces"],
-  ["where", "<prefix> <Effect> [0|1]", "functions with an effect, split into directly / inherited"],
-  ["callers", "<prefix> <query> [0|1]", "who reaches a function: {of, direct, transitive} (--include-unknown)"],
-  ["map", "<prefix> [0|1]", "per-module effect rollup: {effects, functions} by module"],
-  ["containment", "<prefix> [baseline-prefix]", "§6.1 boundary-effect dispersion; with a baseline, the leak ratchet (exit 1)"],
-  ["diff", "<cur-prefix> <base-prefix>", "per-function effect delta vs a baseline: {changes:[{fn,gained,lost}]} (exit 1 on a gain)"],
-  ["reachable", "<prefix>", "effects unioned over the entry points: what the app DOES at runtime"],
-  ["impact", "<prefix> <query>", "blast radius of a function (backward dual of reachable)"],
-  ["blindspots", "<prefix>", "the Unknown sources, ranked by blast radius"],
-  ["gains", "<cur-prefix> <base-prefix>", "the supply-chain alarm: what the surface gained between two reports"],
-  ["path", "<prefix> <fn> <Effect>", "a call path from a function to where an effect enters"],
-  ["whatif", "<prefix> <fn> <Effect> [policy-file] [0|1]", "the impact of giving a function an effect, vs a policy (exit 1 on a violation)"],
-  ["fix", "<prefix> <fn> <Effect> <policy-file>", "the boundary fix: where the effect belongs + the hoist refactor"],
-  ["fix-gate", "<prefix> <policy-file>", "a fix for EVERY boundary crossing — the loop's block-message remedy"],
-  ["unverified", "<prefix> <policy-file> [--strict]", "pure/deny layers that PASS but are Unknown (not PROVABLY clean)"],
+  ["show", `<query> ${REPORT_TAIL}`, "the effect record(s) for a function — direct, inferred, surfaces"],
+  ["where", `<Effect> ${REPORT_TAIL}`, "functions with an effect, split into directly / inherited"],
+  ["callers", `<query> [--include-unknown] ${REPORT_TAIL}`, "who reaches a function: {of, direct, transitive}"],
+  ["map", REPORT_TAIL, "per-module effect rollup: {effects, functions} by module"],
+  ["containment", `[<baseline>] ${REPORT_TAIL}`, "§6.1 boundary-effect dispersion; with a baseline, the leak ratchet (exit 1)"],
+  ["diff", "<current> <baseline> [--json]", "per-function effect delta vs a baseline: {changes:[{fn,gained,lost}]} (exit 1 on a gain)"],
+  ["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)"],
+  ["fix", `<fn> <Effect> [--policy <file>] ${REPORT_TAIL}`, "the boundary fix: where the effect belongs + the hoist refactor"],
+  ["fix-gate", `[--policy <file>] ${REPORT_TAIL}`, "a fix for EVERY boundary crossing — the loop's block-message remedy"],
+  ["unverified", `[--policy <file>] [--strict] ${REPORT_TAIL}`, "pure/deny layers that PASS but are Unknown (not PROVABLY clean)"],
   ["agents", "", "print the agent contract for this build (AGENTS.md)"],
 ];
 
@@ -115,50 +349,65 @@ switch (cmd) {
     // Was a hand-copy of query-core's show that had DRIFTED — it read the wrong Fs key (`e.fs`, never
     // 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, q] = args;
-    emit(coreShow(loadReport(prefix), q));
+    const { prefix, args: [q] } = resolveReportVerb(args, 1);
+    emit(coreShow(loadReportOrDie(prefix), q));
     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;
-    emit(coreWhere(loadReport(prefix), eff));
+    const { prefix, args: [eff] } = resolveReportVerb(args, 1);
+    emit(coreWhere(loadReportOrDie(prefix), eff));
     break;
   }
   case "callers": {
     // --include-unknown ⟨0.7⟩ adds the unresolved-dispatch frontier (possibleViaUnknownDispatch); without
     // it, the byte-for-byte {of,direct,transitive} shape is unchanged (cross-engine parity). Call the
     // shared query-core so the CLI and MCP compute one truth (the prior inline copy had drifted before).
-    const includeUnknown = args.includes("--include-unknown");
-    const [prefix, q] = args.filter((a) => a !== "--include-unknown");
+    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] = args;
-    emit(coreMap(loadReport(prefix)));
+    const { prefix } = resolveReportVerb(args, 0);
+    emit(coreMap(loadReportOrDie(prefix)));
     break;
   }
   case "containment": {
-    // SPEC §6.1 boundary-effect dispersion; with a baseline prefix it's the AS-EFF-010 ratchet (exit 1 on a
-    // new leak), matching candor-java / candor-query. JSON-only, like every other candor-ts query command.
-    const [prefix, basePrefix] = args;
+    // SPEC §6.1 boundary-effect dispersion; with a baseline it's the AS-EFF-010 ratchet (exit 1 on a new
+    // leak), matching candor-java / candor-query. JSON-only, like every other candor-ts query command.
+    // Canonical §3.3.1: `containment [<baseline>]` — the main report discovered / --report, the SINGLE
+    // canonical positional is the OPTIONAL baseline (verb_args: 1). A lone bare positional is therefore
+    // the BASELINE (the gating ratchet), NEVER re-read as the deprecated leading report — which silently
+    // dropped to non-gating report-mode (exit 0), the §4 cardinal-sin gate-off this fixes. The deprecated
+    // old form (`containment <report> <baseline>`) is ARITY-GATED: the leading-report peel fires only when
+    // the positionals EXCEED 1, so `containment P` stays the ratchet and `containment leaky P` still peels
+    // `leaky` as the report and leaves `P` the baseline (both old-grammar tests stay green). Matches Rust.
+    const p = parseCanonical(args, { argc: 1 });
+    let prefix = p.reportPrefix, basePrefix;
+    if (!p.reportExplicit && p.positionals.length > 1 && hasReport(locatorToPrefix(p.positionals[0]))) {
+      deprecate("a leading-positional report is deprecated — pass it as `--report <locator>`; the baseline stays positional (`containment [<baseline>]`)");
+      prefix = locatorToPrefix(p.positionals[0]);
+      basePrefix = p.positionals[1] ? locatorToPrefix(p.positionals[1]) : undefined;
+    } else {
+      basePrefix = p.positionals[0] ? locatorToPrefix(p.positionals[0]) : undefined;
+    }
+    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": {
@@ -168,8 +417,12 @@ switch (cmd) {
     // 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 { changes } = coreDiff(loadReport(curPrefix), loadReport(basePrefix));
+    // §3.3.1: diff/gains are the exception to discovery — two positional locators <current> <baseline>,
+    // 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, {});
+    const [curPrefix, basePrefix] = positionals.map(locatorToPrefix);
+    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).
@@ -188,8 +441,8 @@ switch (cmd) {
   case "reachable": {
     // 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] = args;
-    const fns = loadReport(prefix);
+    const { prefix } = resolveReportVerb(args, 0);
+    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);
@@ -201,44 +454,133 @@ switch (cmd) {
   case "impact": {
     // 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, q] = args;
-    emit(coreImpact(loadReport(prefix), loadCallgraph(prefix), q));
+    const { prefix, args: [q] } = resolveReportVerb(args, 1);
+    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] = args;
-    emit(coreBlindspots(loadReport(prefix), loadCallgraph(prefix)));
+    const { prefix } = resolveReportVerb(args, 0);
+    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": {
     // the supply-chain alarm (SPEC §5.1): {gained:[Effect], byFunction:[{fn,effect}]} — what the
     // surface gained between two reports (base → cur), the cross-engine machine-readable form.
-    const [curPrefix, basePrefix] = args;
+    // §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, {});
+    const [curPrefix, basePrefix] = positionals.map(locatorToPrefix);
     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)) });
+    emit({ baseline_version: gbv ?? "", engine_version: gv ?? "", ...coreGains(loadReportOrDie(curPrefix), loadReportOrDie(basePrefix)) });
     break;
   }
   case "path": {
-    const [prefix, fn, eff] = args;
-    emit(corePath(loadReport(prefix), loadCallgraph(prefix), fn, eff));
+    // 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);
+    const fns = loadReportOrDie(prefix);
+    const cg = loadCallgraph(prefix);
+    if (wantJson) emit(corePath(fns, cg, fn, eff));           // conformance PART 5 shape — UNCHANGED
+    else renderPathHuman(fns, cg, fn, eff);
     break;
   }
   case "whatif": {
-    const [prefix, target, eff, maybePolicy] = args;
-    // 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).
+    // §3.3.1: `whatif <fn> <Effect> [--policy <file>]`, report discovered / --report. DEPRECATED aliases:
+    // a leading-positional report and a trailing positional policy (`whatif <prefix> <fn> <Effect>
+    // [policy]`). resolveWhatifFix peels both (stderr-noted) so the old grammar stays green.
+    const { prefix, target, eff, policyFile } = resolveWhatifFix(args);
+    // A present policy 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). Flag, positional, CANDOR_POLICY and .candor/config all land here.
     let pol = null;
-    if (maybePolicy && maybePolicy !== "0" && maybePolicy !== "1") {
+    if (policyFile) {
       let text;
       try {
-        text = fs.readFileSync(maybePolicy, "utf8");
+        text = fs.readFileSync(policyFile, "utf8");
       } catch {
-        console.error(`candor: policy ${maybePolicy} could not be read; whatif NOT evaluated against it`);
+        console.error(`candor: policy ${policyFile} could not be read; whatif NOT evaluated against it`);
         process.exit(2);
       }
       pol = parsePolicy(text);
@@ -258,9 +600,11 @@ switch (cmd) {
     // THE BOUNDARY FIX (integrations/FIX-SPEC.md): where a forbidden effect belongs + the hoist refactor.
     // The remedial inverse of whatif. A policy is REQUIRED and must be readable (the fix is defined relative
     // to the boundary the edit crossed) — a typo'd path fails LOUD, never a silently-empty "no crossing".
-    const [prefix, target, eff, policyFile] = args;
-    if (!target || !eff) { console.error("usage: candor-ts-query fix <prefix> <fn> <Effect> <policy-file>"); process.exit(2); }
-    if (!policyFile) { console.error("candor: fix requires a policy file — the fix is the refactor that restores the boundary the edit crossed"); process.exit(2); }
+    // §3.3.1: `fix <fn> <Effect> [--policy <file>]`, report discovered / --report; the old
+    // `fix <prefix> <fn> <Effect> <policy-file>` form (leading report + positional policy) stays accepted.
+    const { prefix, target, eff, policyFile } = resolveWhatifFix(args);
+    if (!target || !eff) { console.error("usage: candor-ts-query fix <fn> <Effect> [--policy <file>] [--report <locator>]"); process.exit(2); }
+    if (!policyFile) { console.error("candor: fix requires a policy file — the fix is the refactor that restores the boundary the edit crossed (pass --policy <file>, or set CANDOR_POLICY / a .candor/config `policy` key)"); process.exit(2); }
     let ptext;
     try { ptext = fs.readFileSync(policyFile, "utf8"); }
     catch { console.error(`candor: policy ${policyFile} could not be read — no fix computed`); process.exit(2); }
@@ -268,33 +612,36 @@ 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;
   }
   case "fix-gate": {
     // A remedy for EVERY deny/pure crossing — the shape the edit-time loop folds into its block message.
-    const [prefix, policyFile] = args;
-    if (!policyFile) { console.error("candor: fix-gate requires a policy file"); process.exit(2); }
+    // §3.3.1: `fix-gate [--policy <file>]`, report discovered / --report. DEPRECATED alias: the old
+    // `fix-gate <prefix> <policy-file>` (leading report + positional policy).
+    const { prefix, policyFile } = resolveGateVerb(args);
+    if (!policyFile) { console.error("candor: fix-gate requires a policy file (pass --policy <file>, or set CANDOR_POLICY / a .candor/config `policy` key)"); process.exit(2); }
     let ptext;
     try { ptext = fs.readFileSync(policyFile, "utf8"); }
     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": {
     // PROVABLE-PURITY disclosure: pure/deny layers that PASS but contain Unknown (not provably clean). A
     // policy is required; `--strict` exits 1 on a hole. Advisory (exit 0) otherwise.
-    const strict = args.includes("--strict");
-    const [prefix, policyFile] = args.filter((a) => a !== "--strict");
-    if (!policyFile) { console.error("candor: unverified requires a policy file"); process.exit(2); }
+    // §3.3.1: `unverified [--policy <file>] [--strict]`, report discovered / --report. DEPRECATED alias:
+    // the old `unverified <prefix> <policy-file> [--strict]` (leading report + positional policy).
+    const { prefix, policyFile, strict } = resolveGateVerb(args, { strict: true });
+    if (!policyFile) { console.error("candor: unverified requires a policy file (pass --policy <file>, or set CANDOR_POLICY / a .candor/config `policy` key)"); process.exit(2); }
     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.9";
+const SPEC_VERSION = "0.11";
 
 // --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}`,
+  );
+}