candor-ts 0.11.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.11)."*
+> 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,7 +86,7 @@ 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}

package/README.md

@@ -184,7 +184,7 @@ pure-vs-Unknown ruling (PART 16) — the engines must answer identically, on eve
 | A call resolving to a *type* (function-typed field/param) → `Unknown`, never silent-pure | SPEC §4 |
 | Unmatched external calls contribute nothing (curated-classifier caveat) | SEMANTICS §8 C1 |
 | The literal surfaces `hosts`/`cmds`/`paths`/`tables`, literal-read only | SPEC §2 |
-| `{ candor: { version, toolchain, spec: "0.11" }, 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 |
 
@@ -202,7 +202,7 @@ read the Rust source".
 
 ## Status
 
-0.11.x, speaking candor-spec 0.11: 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

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.11.0",
-  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.11)",
+  "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",

package/query-core.mjs

@@ -170,6 +170,13 @@ export function loadReport(prefix) {
   }
   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
@@ -180,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 ------------------------------------
@@ -523,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

@@ -49,8 +49,12 @@ const emit = (v) => console.log(JSON.stringify(v, null, 1));
 // 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.
+  // 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).
@@ -67,7 +71,7 @@ function renderPathHuman(fns, cg, fnQ, eff) {
     console.log(`${start} does not perform ${eff}  (inferred: ${dbg})`);
     return;
   }
-  const r = corePath(fns, cg, fnQ, eff);
+  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 `
@@ -90,7 +94,7 @@ function renderPathHuman(fns, cg, fnQ, eff) {
 // 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.11";
+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]
@@ -421,7 +425,13 @@ 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);
+    // 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
@@ -547,11 +557,21 @@ 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(loadReportOrDie(curPrefix), loadReportOrDie(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": {
@@ -563,7 +583,13 @@ switch (cmd) {
     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);
+    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": {

package/scan.mjs

@@ -40,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.11";
+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