candor-ts 0.15.0 → 0.17.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.15)."*
+> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.17)."*
 > 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`.
 >

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.15" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
+| `{ candor: { version, toolchain, spec: "0.17" }, 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.15.x, speaking candor-spec 0.15: the analysis core, the gate (`--policy` / `--gate-json` /
+0.17.x, speaking candor-spec 0.17: 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "candor-ts",
-  "version": "0.15.0",
-  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.15)",
+  "version": "0.17.0",
+  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.17)",
   "type": "module",
   "dependencies": {
     "@types/node": "^25.9.2",

package/query.mjs

@@ -41,6 +41,96 @@ import { impact as coreImpact, path as corePath, gains as coreGains,
          matches as coreMatches, gainsCoverage,
          loadReport, loadCallgraph, reportVersion, reportPackage } from "./query-core.mjs";
 const emit = (v) => console.log(JSON.stringify(v, null, 1));
+// The §6 effect vocabulary — used to reject a typo'd effect name in `where` (corpus-audit #3). Kept in step
+// with SPEC §6 / the umbrella's list; an unknown name PRESENT in a report (a spec extension) is still allowed.
+const KNOWN_EFFECTS = ["Net", "Fs", "Db", "Llm", "Exec", "Env", "Clock", "Ipc", "Log", "Rand", "Clipboard", "Unknown"];
+
+// ---- #8 output mode: PROSE at a TTY, JSON when piped or `--json` — so interactive `candor where Db` reads
+// like candor-java/-rust instead of dumping raw JSON, while a pipe/redirect (never a TTY) still yields the
+// pinned JSON untouched. MCP/LSP call query-core directly (not this CLI), so they're unaffected; conformance
+// passes `--json` or captures over a pipe → JSON. `--json` forces JSON; `--text`/`--human` forces prose. -----
+const wantJsonOut = (a) =>
+  a.includes("--json") || (!a.includes("--text") && !a.includes("--human") && !process.stdout.isTTY);
+// Emit the pinned JSON, or render prose via proseFn(data). Returns data so the caller can still exit on it.
+const put = (a, data, proseFn) => { if (!proseFn || wantJsonOut(a)) emit(data); else proseFn(data); return data; };
+const csv = (xs) => (xs && xs.length ? xs.join(", ") : "none");
+const rows = (xs, pre = "    ") => { for (const x of xs) console.log(pre + x); };
+// Per-verb prose renderers. Read the SAME shapes query-core returns (so JSON and prose can't drift); kept
+// terse and scannable, in candor's voice (cf. the existing `tour`/`path` human forms).
+const P = {
+  where: (d) => {
+    const n = d.directly.length + d.inherited.length;
+    if (n === 0) { console.log(`candor: 0 functions perform ${d.effect} in this report.`); return; }
+    console.log(`candor where ${d.effect} — ${n} function${n === 1 ? "" : "s"}:`);
+    if (d.directly.length) { console.log(`  perform it directly (${d.directly.length}):`); rows(d.directly); }
+    if (d.inherited.length) { console.log(`  reach it transitively (${d.inherited.length}):`); rows(d.inherited); }
+  },
+  callers: (d) => {
+    if (!d.of.length) { console.log("candor: no function in the call graph matches that name."); return; }
+    console.log(`candor callers — who reaches \`${d.of.join("`, `")}\`:`);
+    console.log(`  direct callers (${d.direct.length}): ${csv(d.direct)}`);
+    console.log(`  transitive callers (${d.transitive.length}): ${csv(d.transitive)}`);
+  },
+  show: (d) => {
+    if (!d.length) { console.log("candor: no effectful function matches that name (pure functions are omitted from the report)."); return; }
+    d.forEach((e, i) => {
+      if (i) console.log("");
+      console.log(`${e.fn}`);
+      console.log(`  effects: ${csv(e.inferred)}${e.direct && e.direct.length ? `   (direct: ${e.direct.join(", ")})` : ""}`);
+      if (e.hosts?.length)  console.log(`  hosts:   ${e.hosts.join(", ")}`);
+      if (e.cmds?.length)   console.log(`  cmds:    ${e.cmds.join(", ")}`);
+      if (e.paths?.length)  console.log(`  paths:   ${e.paths.join(", ")}`);
+      if (e.tables?.length) console.log(`  tables:  ${e.tables.join(", ")}`);
+    });
+  },
+  map: (d) => {
+    const mods = Object.entries(d);
+    if (!mods.length) { console.log("candor: no effectful modules in this report."); return; }
+    console.log("candor map — effects by module:");
+    for (const [m, v] of mods) console.log(`  ${m} — ${csv(v.effects)}  (${v.functions} fn${v.functions === 1 ? "" : "s"})`);
+  },
+  containment: (d) => {
+    if ("leaks" in d) { // ratchet (a baseline was given)
+      if (!d.leaks.length) console.log("candor containment — no boundary effect reached a new layer vs the baseline. ✓");
+      else { console.log(`candor containment — ${d.leaks.length} boundary effect(s) reached a NEW layer (leak):`); rows(d.leaks); }
+      if (d.cleanups && d.cleanups.length) { console.log(`  no longer present (${d.cleanups.length}):`); rows(d.cleanups); }
+      return;
+    }
+    if (!d.contained.length && !Object.keys(d.ambient).length) { console.log("candor containment — no boundary effects in this report."); return; }
+    console.log("candor containment — how well each boundary effect stays in one layer:");
+    for (const c of d.contained)
+      console.log(`  ${c.effect}: ${c.containmentPct}% in \`${c.owner}\` (spread across ${c.layers} layer${c.layers === 1 ? "" : "s"})`);
+    const amb = Object.entries(d.ambient);
+    if (amb.length) console.log(`  ambient (reported, not scored): ${amb.map(([e, n]) => `${e}×${n}`).join(", ")}`);
+  },
+  reachable: (d) => {
+    const effs = Object.entries(d.effects);
+    console.log(`candor reachable — what the ${d.entryPoints} entry point${d.entryPoints === 1 ? "" : "s"} do at runtime:`);
+    if (!effs.length) { console.log("  no effect reaches an entry point."); return; }
+    for (const [e, v] of effs) console.log(`  ${e}: ${v.count} (via ${csv(v.via)})`);
+  },
+  impact: (d) => {
+    console.log(`candor impact — the blast radius of \`${d.fn}\`:`);
+    console.log(`  ${d.affectedCount} effectful function(s) transitively call it${d.affected.length ? ":" : "."}`);
+    if (d.affected.length) rows(d.affected);
+    if (d.entryPoints.length) { console.log(`  reachable from ${d.entryPoints.length} entry point(s):`); rows(d.entryPoints.map((ep) => `${ep.fn}  [${csv(ep.inferred)}]`)); }
+  },
+  blindspots: (d) => {
+    if (!d.sources.length) { console.log(`candor blindspots — no Unknown sources${d.totalUnknown ? " (all Unknown here is inherited, not rooted in a call)" : ""}. ✓`); return; }
+    console.log(`candor blindspots — ${d.sources.length} Unknown source${d.sources.length === 1 ? "" : "s"} (of ${d.totalUnknown} function(s) carrying Unknown), most-smearing first:`);
+    for (const s of d.sources) console.log(`  \`${s.fn}\` — ${csv(s.why)}; reaches ${s.reaches} caller(s)`);
+  },
+  gains: (d) => {
+    if (!d.gained.length) { console.log("candor gains — no newly-reached effects vs the baseline. ✓"); return; }
+    console.log(`candor gains — the surface newly reaches: ${d.gained.join(", ")}`);
+    for (const g of d.byFunction) console.log(`  \`${g.fn}\` gained ${g.effect}${g.origin ? `  (${g.origin})` : ""}`);
+  },
+  diff: (d) => {
+    if (!d.changes.length) { console.log("candor diff — no effect changes vs the baseline. ✓"); return; }
+    console.log(`candor diff — ${d.changes.length} function(s) changed vs the baseline:`);
+    for (const c of d.changes) console.log(`  \`${c.fn}\`${c.gained.length ? `  +${c.gained.join(",")}` : ""}${c.lost.length ? `  -${c.lost.join(",")}` : ""}`);
+  },
+};
 
 // 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
@@ -94,7 +184,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.15";
+const SPEC_VERSION = "0.17";
 
 // ---- 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]
@@ -186,7 +276,8 @@ function parseCanonical(rawArgs, { policy = false, strict = false, includeUnknow
       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 (a === "--json" || a === "--text" || a === "--human") { continue; } // output-mode flags (#8) — consumed by
+                                                                            // wantJsonOut(rawArgs), never a positional
     if (strict && a === "--strict") { wantStrict = true; continue; }
     if (includeUnknown && a === "--include-unknown") { wantIncludeUnknown = true; continue; }
     positionals.push(a);
@@ -307,7 +398,7 @@ const SUBCOMMANDS = [
 const usage = () => {
   const w = Math.max(...SUBCOMMANDS.map(([n, a]) => `${n} ${a}`.trimEnd().length));
   const lines = SUBCOMMANDS.map(([n, a, d]) => `  ${`${n} ${a}`.trimEnd().padEnd(w)}  ${d}`);
-  lines.push(`  ${"-V, --version".padEnd(w)}  print the build and spec version (offline)`);
+  lines.push(`  ${"-V, --version".padEnd(w)}  print the installed version + upgrade line (offline)`);
   lines.push(`  ${"-h, --help".padEnd(w)}  show this help`);
   return `USAGE: candor-ts-query <command> [args]\n\n${lines.join("\n")}`;
 };
@@ -321,12 +412,55 @@ if (process.argv.includes("--version") || process.argv.includes("-V")) {
 }
 
 // -h / --help: a print-and-exit MODE, handled before the switch (so `-h`'s single dash is never
-// mistaken for a command). Banner + USAGE + the full described subcommand list + the github footer.
+// mistaken for a command). House-style page: identity + model paragraph + COMMON/ALL ACTIONS
+// (the action names derived from SUBCOMMANDS, so the list can never go stale) + OPTIONS + footer.
+// The exit-2 error path keeps the denser fully-described usage() above.
 if (process.argv.includes("-h") || process.argv.includes("--help")) {
-  console.log(`candor-ts-query ${PKG_VERSION} — read-only queries over a candor report (candor-spec ${SPEC_VERSION})
+  const names = SUBCOMMANDS.map(([n]) => n);
+  const allActions = [names.slice(0, 9), names.slice(9)].map((row) => `  ${row.join("  ")}`).join("\n");
+  console.log(`candor-ts-query — read-only queries over a candor report.
+
+Answers come from the report candor-ts wrote — discovered by walking up from the
+cwd to a .candor/ dir (CANDOR_REPORT overrides; --report pins a locator). No
+re-scan, no network. Every engine speaks the same grammar, so these actions and
+flags match the rest of the family.
+
+USAGE
+  candor-ts-query <action> [args] [options]
 
-${usage()}
+COMMON ACTIONS
+  where <Effect>            the functions that perform an effect
+  path <fn> <Effect>        the call path by which a function reaches an effect
+  callers <fn>              who calls a function, direct and transitive
+  tour [N]                  the N most surprising transitive reaches (default 10)
+  blindspots                the Unknown sources worth resolving, ranked by reach
+  gains <current> <base>    what a new version newly reaches (the supply-chain diff)
+  fix <fn> <Effect>         the boundary hoist that would clear a violation
 
+ALL ACTIONS
+${allActions}
+
+OPTIONS  (uniform across every engine)
+  --report <locator>        use this report instead of discovering .candor/
+  --policy <file>           evaluate a policy — exit 1 on a violation (whatif, fix, fix-gate,
+                            unverified; CANDOR_POLICY / a .candor/config \`policy\` key when absent)
+  --json                    machine-readable JSON (the default when output is piped/redirected)
+  --text, --human           human-readable prose (the default at a terminal)
+  --include-unknown         callers: also list the unresolved-dispatch frontier
+  --strict                  unverified: exit 1 on an unverified hole (advisory otherwise)
+  -V, --version             print the installed version + upgrade line (offline)
+  -h, --help                show this help
+
+  diff and gains take two positional report locators: <current> <baseline>. Run
+  candor-ts-query with no action for the full per-action argument list.
+
+EXAMPLES
+  candor-ts-query where Db
+  candor-ts-query path app.orders.render Net
+  candor-ts-query gains new/.candor/report.json old/.candor/report.json
+  candor-ts-query fix-gate --policy candor.policy
+
+Docs: candor.poly.io   ·   Verify an install: candor doctor
 See https://github.com/tombaldwin/candor`);
   process.exit(0);
 }
@@ -354,7 +488,10 @@ switch (cmd) {
     // written; the paths silently vanished) and dropped Exec `cmds` entirely. Call the shared show so
     // the CLI and the MCP `candor_show` are one implementation that cannot diverge again.
     const { prefix, args: [q] } = resolveReportVerb(args, 1);
-    emit(coreShow(loadReportOrDie(prefix), q));
+    // A missing/empty <query> is a LOUD usage error (exit 2, like candor-java) — never a silently-empty
+    // `[]` at exit 0, which reads as an authoritative "no such function" over a question never asked.
+    if (!q) { console.error("usage: candor-ts-query show <query> [--report <locator>] [--json]"); process.exit(2); }
+    put(args, coreShow(loadReportOrDie(prefix), q), P.show);
     break;
   }
   case "where": {
@@ -362,7 +499,18 @@ switch (cmd) {
     // Hand-copies of core functions in this file have drifted three times (show, callers, diff); the
     // fix each time was the same: delegate, keep query.mjs as arg-parsing + emit + exit codes only.
     const { prefix, args: [eff] } = resolveReportVerb(args, 1);
-    emit(coreWhere(loadReportOrDie(prefix), eff));
+    // A missing/empty <Effect> is a LOUD usage error (exit 2, like candor-java's missing-arg path) —
+    // never an authoritative-empty {directly:[],inherited:[]} at exit 0 (a false all-clear shape).
+    if (!eff) { console.error("usage: candor-ts-query where <Effect> [--report <locator>] [--json]"); process.exit(2); }
+    // A typo'd / unknown effect NAME is a LOUD error (exit 2) — never a false-empty {directly:[],inherited:[]}
+    // at exit 0, which reads as an authoritative "nothing performs Net" when the user actually typed "Network"
+    // (corpus-audit #3). A KNOWN effect that is simply absent stays a valid 0-result; an unknown name that is
+    // PRESENT in the report (a spec extension effect) is allowed — so error only when the name is NEITHER.
+    const fnsW = loadReportOrDie(prefix);
+    if (!KNOWN_EFFECTS.includes(eff) && !new Set(fnsW.flatMap((e) => e.inferred || [])).has(eff)) {
+      console.error(`candor-ts-query where: unknown effect '${eff}' (known: ${KNOWN_EFFECTS.join(", ")})`); process.exit(2);
+    }
+    put(args, coreWhere(fnsW, eff), P.where);
     break;
   }
   case "callers": {
@@ -370,15 +518,24 @@ switch (cmd) {
     // 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 { prefix, args: [q], includeUnknown } = resolveReportVerb(args, 1, { includeUnknown: true });
+    // A missing/empty <query> is a LOUD usage error (exit 2, like candor-java) — never an empty
+    // {of:[],direct:[],transitive:[]} at exit 0 (reads as "nothing reaches it" for a fn never named).
+    if (!q) { console.error("usage: candor-ts-query callers <query> [--include-unknown] [--report <locator>] [--json]"); process.exit(2); }
     const cg = loadCallgraph(prefix);
-    if (includeUnknown) emit(callersFrontier(cg, loadReportOrDie(prefix), loadHierarchy(prefix), q));
-    else emit(coreCallers(cg, q));
+    const cres = includeUnknown ? callersFrontier(cg, loadReportOrDie(prefix), loadHierarchy(prefix), q) : coreCallers(cg, q);
+    // A nonexistent function is a LOUD error (exit 2), like path/impact — never an empty {of:[],direct:[],
+    // transitive:[]} at exit 0, which reads as an authoritative "nothing calls it" for a fn that doesn't exist
+    // (corpus-audit #3). Gated on a NON-empty callgraph so a missing sidecar isn't misreported as "no such fn".
+    if (Object.keys(cg).length > 0 && cres.of.length === 0) {
+      console.error(`candor-ts-query callers: no function matching '${q}' in the call graph`); process.exit(2);
+    }
+    put(args, cres, P.callers);
     break;
   }
   case "map": {
     // Shared query-core — the CLI and MCP `candor_map` are one implementation (see `where` above).
     const { prefix } = resolveReportVerb(args, 0);
-    emit(coreMap(loadReportOrDie(prefix)));
+    put(args, coreMap(loadReportOrDie(prefix)), P.map);
     break;
   }
   case "containment": {
@@ -408,10 +565,10 @@ switch (cmd) {
         process.exit(2);
       }
       const r = coreContainment(loadReportOrDie(prefix), baseFns);
-      emit(r);
+      put(args, r, P.containment);
       process.exit(r.leaks.length ? 1 : 0);
     }
-    emit(coreContainment(loadReportOrDie(prefix)));
+    put(args, coreContainment(loadReportOrDie(prefix)), P.containment);
     break;
   }
   case "diff": {
@@ -440,7 +597,7 @@ switch (cmd) {
     const versionMismatch = engineV && baseV && engineV !== baseV;
     if (versionMismatch)
       console.error(`candor-ts: ⚠ baseline @${baseV} ≠ engine @${engineV} — some changes may be the engine reclassifying, not your code. Treat an engine swap as baseline-invalidating: review, then regenerate the baseline.`);
-    emit({ baseline_version: baseV ?? "", engine_version: engineV ?? "", changes });
+    put(args, { baseline_version: baseV ?? "", engine_version: engineV ?? "", changes }, P.diff);
     // diff DISCLOSES (the posture) — it is not a gate. Its gained-effect exit 1 is a convenience for
     // same-build ratchet use; under a version mismatch that signal is BOGUS (unmasking, not regression),
     // so exit 0 and let the ⚠ inform — never deliver the wave as a CI failure (review §2.1: guards fail
@@ -456,23 +613,26 @@ switch (cmd) {
     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);
-    emit({ entryPoints: roots.length,
+    put(args, { entryPoints: roots.length,
            effects: Object.fromEntries(Object.entries(byEff).sort()
-             .map(([k, v]) => [k, { count: v.length, via: v.sort() }])) });
+             .map(([k, v]) => [k, { count: v.length, via: v.sort() }])) }, P.reachable);
     break;
   }
   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, args: [q] } = resolveReportVerb(args, 1);
-    emit(coreImpact(loadReportOrDie(prefix), loadCallgraph(prefix), q));
+    // A missing/empty <query> is a LOUD usage error (exit 2, like candor-java) — never an
+    // affectedCount:0 blast radius at exit 0 for a function that was never named.
+    if (!q) { console.error("usage: candor-ts-query impact <query> [--report <locator>] [--json]"); process.exit(2); }
+    put(args, coreImpact(loadReportOrDie(prefix), loadCallgraph(prefix), q), P.impact);
     break;
   }
   case "blindspots": {
     // the Unknown SOURCES, ranked by blast radius — the actionable inverse of a widely-propagated
     // Unknown (SPEC §3.1 ⟨0.6⟩): { sources:[{fn,why,reaches,affected}], totalUnknown }.
     const { prefix } = resolveReportVerb(args, 0);
-    emit(coreBlindspots(loadReportOrDie(prefix), loadCallgraph(prefix)));
+    put(args, coreBlindspots(loadReportOrDie(prefix), loadCallgraph(prefix)), P.blindspots);
     break;
   }
   case "tour": {
@@ -576,9 +736,9 @@ switch (cmd) {
     // read as total), plus `coverageDelta` when the baseline names different blind packages. Both
     // OMITTED when nothing applies, so a coverage-free comparison is byte-identical to ⟨0.14⟩.
     // Shared with the MCP `candor_gains` tool (gainsCoverage — the parity rule).
-    emit({ baseline_version: gbv ?? "", engine_version: gv ?? "",
+    put(args, { baseline_version: gbv ?? "", engine_version: gv ?? "",
            ...coreGains(loadReportOrDie(curPrefix), loadReportOrDie(basePrefix), loadCallgraph(basePrefix)),
-           ...gainsCoverage(curPrefix, basePrefix) });
+           ...gainsCoverage(curPrefix, basePrefix) }, P.gains);
     break;
   }
   case "path": {
@@ -587,6 +747,10 @@ switch (cmd) {
     // 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);
+    // BOTH positionals are required (`path <fn> <Effect>`) — a missing/empty one is a LOUD usage error
+    // (exit 2, like candor-java). Before this gate, one arg slid through as `<fn> undefined` and printed
+    // "does not perform undefined" at exit 0 — a false all-clear over a question that was never posed.
+    if (!fn || !eff) { console.error("usage: candor-ts-query path <fn> <Effect> [--report <locator>] [--json]"); process.exit(2); }
     const fns = loadReportOrDie(prefix);
     const cg = loadCallgraph(prefix);
     if (wantJson) emit(corePath(fns, cg, fn, eff));           // conformance PART 5 shape — UNCHANGED

package/scan.mjs

@@ -41,7 +41,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.15";
+const SPEC_VERSION = "0.17";
 
 // --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
@@ -55,25 +55,45 @@ if (process.argv.includes("--version") || process.argv.includes("-V")) {
 // -h / --help: a print-and-exit MODE (like --version), handled before the arg walk so `-h` (a single
 // dash) is never mistaken for the scan target by the positional fallthrough below.
 if (process.argv.includes("-h") || process.argv.includes("--help")) {
-  console.log(`candor-ts ${PKG_VERSION} — TypeScript/JavaScript effect scanner (candor-spec ${SPEC_VERSION})
+  console.log(`candor-ts — the TypeScript/JavaScript effect analyzer.
 
-USAGE: candor-ts <dir | file.ts | tsconfig.json> [--out <prefix>] [--json] [--policy <file>] [--gate-json <file>] [--allow-js] [--agents] [--version]
+Reads TS/JS source through the TypeScript compiler API — no build needed. Calls
+are resolved through the checker; a call that cannot be resolved reads Unknown,
+never silently pure. The report lands in .candor/, where candor-ts-query and the
+umbrella \`candor\` CLI discover it.
 
-  <target>          a dir, a .ts file, or a tsconfig.json to scan
-  --out <prefix>    write the report to <prefix>.json + <prefix>.callgraph.json
-  --json            print the report as JSON to stdout (instead of writing files)
-  --policy <file>   enforce a policy file (deny/pure/allow/forbid, candor-spec §6.2) — exit 1 on a
-                    violation, 2 if unreadable; honours $CANDOR_POLICY when the flag is absent
-  --gate-json <f>   write the structured gate verdict { spec, ok, violations } as JSON (candor-spec §3.3)
-  --allow-js        also scan plain JS/Node (.js/.mjs/.cjs), not just TypeScript
-  --agents          print the agent contract for this build (AGENTS.md)
-  -V, --version     print the build and spec version (offline)
-  -h, --help        show this help
+USAGE
+  candor-ts <dir | file.ts | tsconfig.json> [flags]
 
-CANDOR_BASELINE=<report.json> (or a .candor/config \`baseline\` key) runs the AS-EFF-005 regression
-guard against a saved same-build report: exit 1 when an existing function gained an effect, exit 2
-on an unparseable or different-build baseline (never evaluated), a stderr note when absent.
+  The target is a project directory, a single .ts file, or a tsconfig.json.
 
+OPTIONS
+  --out <prefix>            write the report to <prefix>.json + <prefix>.callgraph.json
+  --json                    print the report as JSON to stdout (instead of writing files)
+  --policy <file>           enforce a policy file (deny/pure/allow/forbid) — exit 1 on a
+                            violation, 2 if unreadable
+  --gate-json <file>        write the structured gate verdict { spec, ok, violations } as JSON
+  --allow-js                also scan plain JS/Node (.js/.mjs/.cjs), not just TypeScript
+  --agents                  print the agent contract for this build (AGENTS.md)
+  -V, --version             print the installed version + upgrade line (offline)
+  -h, --help                show this help
+
+ENVIRONMENT / CONFIG
+  CANDOR_POLICY=<file>           the policy when --policy is absent (a .candor/config
+                                 \`policy\` key works too)
+  CANDOR_BASELINE=<report.json>  (or a .candor/config \`baseline\` key) runs the AS-EFF-005
+                                 regression guard against a saved same-build report: exit 1
+                                 when an existing function gained an effect, exit 2 on an
+                                 unparseable or different-build baseline (never evaluated),
+                                 a stderr note when absent
+
+EXAMPLES
+  candor-ts .
+  candor-ts src --allow-js
+  candor-ts . --policy candor.policy --gate-json gate.json
+  candor-ts-query where Db          query the report this scan wrote
+
+Docs: candor.poly.io   ·   Verify an install: candor doctor
 See https://github.com/tombaldwin/candor`);
   process.exit(0);
 }
@@ -1554,6 +1574,32 @@ const identIsEnvAlias = (id) => {
 // The receiver expression READS process.env — it is either `process.env` itself or a confirmed alias.
 const readsProcessEnv = (expr) => isProcessEnvExpr(expr) || identIsEnvAlias(expr);
 
+// A bare-identifier call whose callee is DEFAULT- or NAMED-imported from a known HTTP-client package is a
+// Net call (corpus-audit #13). The κ table lists these packages, but its rule only fires on a MEMBER call
+// (`axios.get(…)`); a default-imported callable invoked bare — the canonical `import fetch from 'node-fetch';
+// fetch(url)` — resolves to no signature when the package isn't installed, so it read Unknown (callback:fetch)
+// instead of Net, the effect users most care about. Resolve the identifier's symbol up to its
+// ImportDeclaration and match the specifier; used both to CLASSIFY the call Net and to SUPPRESS the spurious
+// callback-Unknown for the same node.
+const NET_REQUEST_NAMED = new Set(["fetch", "request", "stream", "pipeline"]); // undici/node-fetch callables
+const importedFromNetPkg = (id) => {
+  if (!id || !ts.isIdentifier(id)) return false;
+  for (const d of checker.getSymbolAtLocation(id)?.declarations ?? []) {
+    let n = d;
+    while (n && !ts.isImportDeclaration(n)) n = n.parent;
+    if (!(n && ts.isImportDeclaration(n) && ts.isStringLiteralLike(n.moduleSpecifier)
+        && /^(node-fetch|undici|axios|got|superagent|phin)$/.test(n.moduleSpecifier.text))) continue;
+    // Only the package's CLIENT CALLABLE is Net: the DEFAULT import (`import fetch from 'node-fetch'`,
+    // `import got from 'got'`) or a NAMED request function (`import { fetch, request } from 'undici'`). A
+    // named CLASS/utility export — `Headers`, `Response`, `Request`, `CookieJar`, `FormData` — is NOT a
+    // request and must not be over-reported as Net (review finding). Namespace imports resolve via κ member
+    // calls elsewhere, not as a bare callable here.
+    if (ts.isImportClause(d)) return true;                                  // default import = the client
+    if (ts.isImportSpecifier(d) && NET_REQUEST_NAMED.has((d.propertyName ?? d.name).text)) return true;
+  }
+  return false;
+};
+
 // ---- pass 2: per call site, the (CLASSIFY)/(EDGE)/(UNKNOWN) resolution of SEMANTICS §4 ------------
 function visitCalls(node) {
   if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
@@ -1610,6 +1656,10 @@ function visitCalls(node) {
           }
           if (kEff) {
             rec.direct.add(kEff); // κ-modeled package reached via an uninstalled namespace import
+          } else if (ts.isCallExpression(node) && importedFromNetPkg(node.expression)) {
+            rec.direct.add("Net"); // bare call to an HTTP-client default/named import whose pkg isn't installed
+                                   // (so its signature didn't resolve) — Net, not Unknown (#13). Host capture
+                                   // happens in the global/builtin arm below, which fires for the same node.
           } else {
             rec.direct.add("Unknown"); // unresolvable call → Unknown, never silent-pure (SPEC §4)
             const callee = (node.expression?.getText?.() ?? "?").replace(/\s+/g, "").slice(0, 60);
@@ -2143,6 +2193,9 @@ function visitCalls(node) {
     };
     if ((ctext === "process.hrtime" || ctext === "process.hrtime.bigint") && processIsGlobal()) geff = "Clock";
     else if (ctext === "process.send" && processIsGlobal()) geff = "Ipc";
+    else if (ts.isIdentifier(callee) && importedFromNetPkg(callee))
+      geff = "Net"; // a bare call to an HTTP-client default/named import (installed → sig resolves here) — #13
+
     else if (ts.isIdentifier(callee) && callee.text === "fetch"
              && !(checker.getSymbolAtLocation(callee)?.declarations ?? [])
                   .some((d) => projectFiles.has(path.resolve(d.getSourceFile().fileName))))
@@ -2616,6 +2669,20 @@ let gateViolations = [];
 //  · Valid + same build → per-fn compare: an EXISTING fn gaining an effect is an [AS-EFF-005]
 //    violation (exit 1, joins --gate-json); a fn absent from the baseline is NEW code, reviewed as
 //    such, not a regression. Baselines omit pure fns (spec §2), so absent-prior means no prior claim.
+//
+// ⟨0.16⟩ Callgraph-aware existence (SPEC §7 item 5). Reports OMIT pure functions, so a fn that
+// shipped PURE and now performs an effect is absent from the baseline report and reads as exempt "new
+// code" — the sharpest supply-chain shape escaping the guard. Fix: key existence on the baseline
+// CALLGRAPH sidecar (<baseline>.callgraph.json, §2.2 — it lists every project fn INCLUDING pure
+// leaves), exactly as `gains`'s `origin` existence test does (query-core.mjs `gains`: a fn is
+// "existing" if it is a baseline-callgraph node — a caller key or a callee):
+//  · sidecar PRESENT + loaded → a fn that is a baseline-callgraph node has baseline effect set ∅
+//    (pure → omitted from the report) and any effect now is a GAIN violation. pure→effectful is caught.
+//    A fn in NEITHER report nor callgraph genuinely did not exist → stays exempt "new".
+//  · sidecar ABSENT → degrade to report-only existence (pre-⟨0.16⟩: a formerly-pure fn reads as new;
+//    still catches an already-effectful fn WIDENING). One stderr note that the guard is weaker.
+//  · sidecar PRESENT-but-CORRUPT → fail closed (exit 2), like a corrupt baseline: a broken sidecar
+//    must not silently NARROW the guard back to report-only.
 if (baselinePath !== null) {
   const shownB = baselinePath === "" ? "(configured empty)" : baselinePath;
   if (baselinePath !== "" && !fs.existsSync(baselinePath)) {
@@ -2647,14 +2714,66 @@ if (baselinePath !== null) {
     for (const e of arr) {
       if (e && typeof e.fn === "string" && e.fn) base.set(e.fn, new Set(Array.isArray(e.inferred) ? e.inferred : []));
     }
+    // ⟨0.16⟩ Load the baseline callgraph sidecar next to the baseline report. The sidecar for a
+    // report at <stem>.json is <stem>.callgraph.json (scan.mjs writes exactly this pair). Three states:
+    //   loaded  — a parsed object → its node set (every key + every callee) keys existence, mirroring
+    //             the `gains` origin test (query-core.mjs). A baseline-callgraph node whose baseline
+    //             effects are ∅ (pure → omitted from the report) that now performs an effect is a GAIN.
+    //   absent  — no sidecar file → degrade to report-only existence + one stderr note (guard weaker).
+    //   corrupt — file present but not parseable / not a plain object → fail closed (exit 2). A broken
+    //             sidecar must not silently narrow the guard (SPEC §7 item 5).
+    // shownB may be "(configured empty)"; the real path is baselinePath here (non-null, exists).
+    const sidecarPath = baselinePath.replace(/\.json$/i, "") + ".callgraph.json";
+    let cgNodes = null;                                     // null = sidecar absent (report-only degrade)
+    if (fs.existsSync(sidecarPath)) {
+      let baseCg = null;
+      try { baseCg = JSON.parse(fs.readFileSync(sidecarPath, "utf8")); } catch { baseCg = undefined; }
+      // A non-object parse (null / array / number) is a corrupt sidecar: it cannot list nodes, and
+      // treating it as "absent" would silently narrow the guard — fail closed like a corrupt baseline.
+      if (baseCg === undefined || baseCg === null || typeof baseCg !== "object" || Array.isArray(baseCg)) {
+        console.error(`candor-ts: the baseline callgraph ${sidecarPath} is present but could not be parsed `
+          + `(corrupt/truncated?) — failing (exit 2); a broken sidecar must not silently narrow the guard to `
+          + `report-only. Regenerate the baseline with this build.`);
+        process.exit(2);
+      }
+      // The node set = every caller key + every callee (a pure leaf appears only as a callee), exactly
+      // as `gains` computes cgNodes. Non-array edge values are tolerated (skipped), matching loadCallgraph.
+      cgNodes = new Set(Object.entries(baseCg).flatMap(([k, vs]) => [k, ...(Array.isArray(vs) ? vs : [])]));
+    } else {
+      console.error(`candor-ts: no baseline callgraph sidecar at ${sidecarPath} — the AS-EFF-005 guard is `
+        + `WEAKER: existence falls back to the report, which omits pure functions, so a formerly-PURE fn `
+        + `turning effectful reads as new code and is NOT caught (only an already-effectful fn widening is). `
+        + `Regenerate the baseline with --out so the .callgraph.json is written alongside it.`);
+    }
+    const unknownOnly = [];   // ⟨0.16⟩ advisory: fns that gained ONLY Unknown vs the baseline
     for (const name of [...inferred.keys()].sort()) {
       const prior = base.get(name);
-      if (prior === undefined) continue;                    // new function — not a regression
-      const gained = [...inferred.get(name)].filter((x) => !prior.has(x)).sort();
-      if (gained.length) {
-        gateViolations.push({ rule: "AS-EFF-005", fn: name, effects: gained,
-          detail: `\`${name}\` gained effect { ${gained.join(", ")} } not present in the baseline` });
-      }
+      // ⟨0.16⟩ Existence ladder: in the baseline REPORT → its recorded inferred set is the prior;
+      // else a baseline-callgraph NODE (sidecar present) → it existed and was pure, so prior = ∅ (any
+      // effect now is a gain); else genuinely absent → new code, exempt. Without the sidecar (cgNodes
+      // null) only the report path decides, the pre-⟨0.16⟩ semantics.
+      const priorSet = prior !== undefined ? prior
+        : (cgNodes !== null && cgNodes.has(name)) ? new Set()   // baseline-pure node → ∅ prior
+        : null;                                                 // new function — not a regression
+      if (priorSet === null) continue;
+      const gained = [...inferred.get(name)].filter((x) => !priorSet.has(x)).sort();
+      if (!gained.length) continue;
+      // ⟨0.16⟩ the ratchet fires only on gaining a REAL boundary effect. An Unknown-ONLY gain is
+      // the §4 trust marker, not an effect (`pure` policies exclude it), and on version bumps it is
+      // dominated by resolution noise — DISCLOSE it (advisory), never fail the gate on it. Mirrors the
+      // reference engine (candor-scan gate.rs check_baseline).
+      const real = gained.filter((x) => x !== "Unknown");
+      if (!real.length) { unknownOnly.push(name); continue; }
+      gateViolations.push({ rule: "AS-EFF-005", fn: name, effects: real,
+        detail: `\`${name}\` gained effect { ${real.join(", ")} } not present in the baseline` });
+    }
+    if (unknownOnly.length) {
+      unknownOnly.sort();
+      const shown = unknownOnly.slice(0, 3).join(", ");
+      const more = unknownOnly.length > 3 ? ` (+${unknownOnly.length - 3} more)` : "";
+      console.error(`candor-ts: note — ${unknownOnly.length} function(s) gained an unresolved call `
+        + `(Unknown) vs the baseline but no real effect — advisory, NOT a regression (Unknown is the §4 `
+        + `trust marker, dominated by resolution noise on version bumps): ${shown}${more}`);
     }
   }
 }
@@ -2721,6 +2840,10 @@ if (gateJsonPath) {
 // gateViolations is non-empty only when a gate surface (policy / baseline) was active and fired.
 if (gateViolations.length) {
   console.error(`candor-ts: ${gateViolations.length} policy violation(s)`);
+  // FAILURE-only pointer at the engine's own remedy verb (append-only, same stream as the summary; a
+  // zero-violation run is byte-identical — the exit code, violation lines and summary text are pinned
+  // by the conformance suite and stay untouched).
+  console.error("→ candor-ts-query fix-gate names the remedy for each");
   process.exit(1);
 }
 if (policyPath !== null) console.error("candor-ts: policy ✓");