candor-ts 0.16.0 → 0.18.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.16)."*
+> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.18)."*
 > 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.16" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
+| `{ candor: { version, toolchain, spec: "0.18" }, 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.16.x, speaking candor-spec 0.16: the analysis core, the gate (`--policy` / `--gate-json` /
+0.18.x, speaking candor-spec 0.18: 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.16.0",
-  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.16)",
+  "version": "0.18.0",
+  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.18)",
   "type": "module",
   "dependencies": {
     "@types/node": "^25.9.2",

package/query.mjs

@@ -41,6 +41,108 @@ 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"];
+// Suggest the nearest known flag for a typo (longest shared prefix ≥3): `--polciy` → `--policy` (#2).
+function didYouMeanFlag(unknown) {
+  const known = ["--report", "--policy", "--json", "--text", "--strict", "--include-unknown"];
+  const u = unknown.replace(/^-+/, "").toLowerCase();
+  let best = null, bestLen = 2;
+  for (const k of known) {
+    const kn = k.replace(/^-+/, "");
+    let s = 0; while (s < u.length && s < kn.length && u[s] === kn[s]) s++;
+    if (s >= 3 && s > bestLen) { bestLen = s; best = k; }
+  }
+  return best ? ` — did you mean \`${best}\`?` : "";
+}
+
+// ---- #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 +196,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.16";
+const SPEC_VERSION = "0.18";
 
 // ---- 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]
@@ -182,13 +284,21 @@ function parseCanonical(rawArgs, { policy = false, strict = false, includeUnknow
       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 (a === "--policy") { // consumed for EVERY verb (a valid candor flag); used only by policy verbs
       if (i + 1 >= rawArgs.length) { console.error("candor-ts: --policy requires a <file> value"); process.exit(2); }
-      policyFile = rawArgs[++i]; continue;
+      const v = rawArgs[++i]; if (policy) policyFile = v; continue;
+    }
+    if (a === "--json" || a === "--text" || a === "--human") { continue; } // output-mode flags (#8) — consumed by
+                                                                            // wantJsonOut(rawArgs), never a positional
+    if (a === "--strict") { if (strict) wantStrict = true; continue; }                       // vocabulary — tolerated everywhere,
+    if (a === "--include-unknown") { if (includeUnknown) wantIncludeUnknown = true; continue; } // used only by the verb that reads it
+    if (a.startsWith("-") && a.length > 1) {
+      // An unrecognized flag is a TYPO, not a positional — reject it LOUD (exit 2), never silently swallow.
+      // A swallowed `--polciy` runs the query with NO policy and exits green: a CI author who typos --policy
+      // ships a gate that never fires (corpus re-audit cardinal sin — a loud error, never a silent guess).
+      console.error(`candor-ts-query: unknown flag '${a}'${didYouMeanFlag(a)}\n  known flags: --report, --policy, --json, --text, --strict, --include-unknown`);
+      process.exit(2);
     }
-    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,
@@ -293,11 +403,11 @@ const SUBCOMMANDS = [
   ["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"],
+  ["gains", "<current> <baseline> [--json] [--strict]", "the supply-chain alarm: what the surface gained between two reports (--strict: exit 1 on ANY gain)"],
   ["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"],
+  ["fix-gate", `[--policy <file>] [--strict] ${REPORT_TAIL}`, "a fix for EVERY boundary crossing — advisory (--strict: exit 1 while any remains)"],
   ["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)"],
 ];
@@ -353,9 +463,12 @@ 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 output
+  --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)
+  --strict                  make an advisory verb a CI gate — exit 1 while a finding remains:
+                            unverified (an unverified-purity hole), fix-gate (a boundary
+                            crossing), gains (ANY gained effect). Advisory (exit 0) otherwise.
   -V, --version             print the installed version + upgrade line (offline)
   -h, --help                show this help
 
@@ -399,7 +512,7 @@ switch (cmd) {
     // 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); }
-    emit(coreShow(loadReportOrDie(prefix), q));
+    put(args, coreShow(loadReportOrDie(prefix), q), P.show);
     break;
   }
   case "where": {
@@ -410,7 +523,15 @@ switch (cmd) {
     // 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); }
-    emit(coreWhere(loadReportOrDie(prefix), eff));
+    // 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": {
@@ -422,14 +543,20 @@ switch (cmd) {
     // {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": {
@@ -459,10 +586,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": {
@@ -491,7 +618,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
@@ -507,9 +634,9 @@ 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": {
@@ -519,14 +646,14 @@ switch (cmd) {
     // 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); }
-    emit(coreImpact(loadReportOrDie(prefix), loadCallgraph(prefix), q));
+    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": {
@@ -587,13 +714,33 @@ switch (cmd) {
       const out = { reaches: finds.map((f) => ({
         effect: f.effect, fn: f.func, hops: f.hops, loc: f.sourceLoc, score: f.score, source: f.source,
       })) };
+      // The MACHINE half of the mostly-Unknown disclosure (Fable-review finding E): a JSON consumer (the
+      // agent loop) got a bare `{"reaches":[]}` and read it as clean — the same false all-clear the text
+      // branch qualifies. ADDITIVE + present only when the ≥⅓-Unknown threshold trips (byte-identical
+      // otherwise). Keys sorted after `reaches` (reaches < unknown) to match Rust's serde output.
+      const teff = fns.filter((e) => (e.inferred ?? []).length > 0).length;
+      const tunk = fns.filter((e) => (e.inferred ?? []).includes("Unknown")).length;
+      if (teff > 0 && tunk * 3 >= teff) out.unknown = { count: tunk, total: teff };
       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.");
+      // answer (never a manufactured surprise) — mirrors the scan-note fallback + the Rust engine. BUT never
+      // reassure "nothing hidden" over a meaningfully-Unknown graph (unresolved calls — missing tsconfig /
+      // imports): those Unknowns ARE the hidden part, their transitive effects unanalyzed (re-audit cardinal
+      // sin). Same ≥⅓-effectful-Unknown gate as the scan opener (surface.mjs emitSurface).
+      const teff = fns.filter((e) => (e.inferred ?? []).length > 0).length;
+      const tunk = fns.filter((e) => (e.inferred ?? []).includes("Unknown")).length;
+      if (teff > 0 && tunk * 3 >= teff) {
+        console.log(
+          `candor: no surprising reaches — but ${tunk} of ${teff} function(s) are Unknown `
+          + `(unresolved calls; their transitive effects are NOT analyzed). Run \`candor blindspots\`; `
+          + `a missing tsconfig.json or unresolvable imports are the usual cause.`,
+        );
+      } else {
+        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}:`);
@@ -610,8 +757,13 @@ switch (cmd) {
     // surface gained between two reports (base → cur), the cross-engine machine-readable form.
     // §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); }
+    // gains has no `--policy` of its own: parseCanonical consumes `--policy` for every verb (a valid flag),
+    // which for gains would SILENTLY drop it and exit 0 — a CI author who reaches for `--policy` to gate a
+    // supply-chain diff ships a gate that never fires. Reject it loud and point at the real gate. `--strict`
+    // (below) fails on ANY gained effect; the effect-SPECIFIC gate is a `deny <E> gained` scan policy.
+    if (args.includes("--policy")) { console.error("candor-ts-query gains: unknown flag '--policy' — gains is a diff view; to FAIL CI on a newly-gained effect gate at scan time with a `deny <E> gained` policy (AS-EFF-005), or use `--strict` to fail on ANY gain\n  known flags: --json, --strict"); process.exit(2); }
+    const { positionals, strict } = parseCanonical(args, { strict: true });
+    if (positionals.length < 2) { console.error("usage: candor-ts-query gains <current> <baseline> [--json] [--strict]"); 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
@@ -630,10 +782,13 @@ 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 ?? "",
-           ...coreGains(loadReportOrDie(curPrefix), loadReportOrDie(basePrefix), loadCallgraph(basePrefix)),
-           ...gainsCoverage(curPrefix, basePrefix) });
-    break;
+    const gainsResult = coreGains(loadReportOrDie(curPrefix), loadReportOrDie(basePrefix), loadCallgraph(basePrefix));
+    put(args, { baseline_version: gbv ?? "", engine_version: gv ?? "",
+           ...gainsResult, ...gainsCoverage(curPrefix, basePrefix) }, P.gains);
+    // Advisory by default (exit 0 — gains is a diff view); `--strict` fails on ANY gained effect so a
+    // supply-chain CI job can require a bump introduce no new capability (mirrors `unverified --strict`).
+    process.exit(strict && (gainsResult.gained?.length ?? 0) > 0 ? 1 : 0);
+    break; // unreachable
   }
   case "path": {
     // BOTH a human default AND a --json form (like the Rust/Java engines). The surface opener suggests
@@ -712,15 +867,19 @@ switch (cmd) {
     // A remedy for EVERY deny/pure crossing — the shape the edit-time loop folds into its block message.
     // §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);
+    // Advisory by default (exit 0 — the agent fix-loop reads the remedy and edits); `--strict` makes the
+    // exit follow `ok`, so CI can REQUIRE zero outstanding crossings (mirrors `unverified --strict`).
+    const { prefix, policyFile, strict } = resolveGateVerb(args, { strict: true });
     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, loadReportOrDie(prefix), parsePolicy(ptext), scopeMatches));
-    break;
+    const fgr = coreFixGate(cg, loadReportOrDie(prefix), parsePolicy(ptext), scopeMatches);
+    emit(fgr);
+    process.exit(strict && !fgr.ok ? 1 : 0);
+    break; // unreachable
   }
   case "unverified": {
     // PROVABLE-PURITY disclosure: pure/deny layers that PASS but contain Unknown (not provably clean). A

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.16";
+const SPEC_VERSION = "0.18";
 
 // --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
@@ -1574,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)) {
@@ -1630,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);
@@ -2163,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))))

package/surface.mjs

@@ -215,8 +215,26 @@ export function bestFind(inferred, direct, calls, isTest = () => false) {
 // 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) {
+  // A real SURPRISING reach is a genuine finding — show it (below), even amid Unknowns.
+  if (res !== null && res.winner !== null) { /* fall through to the surprising-reach message */ }
+  else {
+    // No surprising reach. But do NOT reassure "nothing hidden" over a meaningfully-UNKNOWN graph: those
+    // Unknowns (unresolved calls — e.g. a missing tsconfig.json, unresolvable imports) ARE the hidden part,
+    // and their transitive effects are unanalyzed. "nothing hidden" there is a false all-clear — the
+    // cardinal sin for a tool that sells transitive-reach detection (corpus re-audit). Qualify + point at
+    // blindspots. `bestFind` returns null for BOTH "no effectful fns" and "effectful-but-nothing-surprising
+    // (incl. all-Unknown)", so measure the Unknown fraction from `inferred` directly, not from `res`.
+    const total = [...inferred.values()].filter((s) => s.size > 0).length; // EFFECTFUL fns (pure units excluded)
+    const unknown = [...inferred.values()].filter((s) => s.has("Unknown")).length;
+    if (total > 0 && unknown * 3 >= total) { // ≥ ~1/3 of effectful functions Unknown → meaningfully unresolved
+      log(
+        `candor: no surprising reaches — but ${unknown} of ${total} function(s) are Unknown `
+        + `(unresolved calls; their transitive effects are NOT analyzed). Run \`candor blindspots\`; `
+        + `a missing tsconfig.json or unresolvable imports are the usual cause.`,
+      );
+      return;
+    }
+    if (res === null) return; // genuinely nothing effectful/surprising and few Unknowns — emit nothing
     log("candor: nothing hidden — every effect sits where its name says it should.");
     return;
   }