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

package/policy.mjs

@@ -5,6 +5,23 @@
  */
 
 export const EFFECTS = ["Net", "Fs", "Db", "Exec", "Env", "Clock", "Ipc", "Log", "Rand", "Clipboard", "Llm"];
+
+// Reason-scoped Unknown (REASON-SCOPED-UNKNOWN-DESIGN.md): the CLOSED, cross-engine reason-class set a
+// `deny E Unknown[class…]` rule quantifies over. Must be IDENTICAL to candor-java's ReasonClass and
+// candor-rust's — the mapping below mirrors java's prefix-based ReasonClass.classify(String).
+export const REASON_CLASSES = ["reflect", "dispatch", "indirect", "native", "unresolved", "setup"];
+// `dynamic` = every GENUINE blind-spot class (excludes `setup`), incl. `unresolved` so it never under-gates.
+const DYNAMIC_CLASSES = ["reflect", "dispatch", "indirect", "native", "unresolved"];
+/** Map a raw `unknownWhy` token (e.g. `reflect:eval`, `callback:fetch`) to its normative reason class. */
+export function reasonClass(why) {
+  const w = String(why).trim().toLowerCase();
+  if (w.startsWith("reflect") || w === "dynamicmemberlookup") return "reflect";
+  if (w.startsWith("native")) return "native";
+  if (w.startsWith("callback") || w.startsWith("closure") || w.startsWith("task-handoff")) return "indirect";
+  if (w.startsWith("dispatch") || w.startsWith("indy") || w.startsWith("ambiguous")) return "dispatch";
+  if (w.startsWith("missing-config") || w.startsWith("no-tsconfig") || w.startsWith("no-node_modules")) return "setup";
+  return "unresolved"; // conservative catch-all
+}
 // The literal surfaces `allow` can restrict. `Llm` ⟨0.13⟩ rides Net's host literal (SPEC §1) —
 // `allow Llm <host…>` restricts which MODEL hosts a scope may reach, matched by hostname like Net.
 const ALLOW_EFFECTS = new Set(["Net", "Exec", "Fs", "Db", "Llm"]);
@@ -14,7 +31,10 @@ const ALLOW_EFFECTS = new Set(["Net", "Exec", "Fs", "Db", "Llm"]);
 // (adversarial DSL review). A non-ASCII space stays part of its token → the rule is malformed, dropped.
 const ASCII_WS = /[ \t\n\v\f\r]+/;
 const ASCII_WS_TRIM = /^[ \t\n\v\f\r]+|[ \t\n\v\f\r]+$/g;
-export function parsePolicy(text) {
+// ⟨0.19⟩ `aliases` (a Map name→class-token[], from `.candor/config` `unknown-alias`) lets an `Unknown[<name>]`
+// filter resolve a user-defined name (SPEC §6.2). A config alias never changes what bare `deny E Unknown`
+// means (always `Unknown[*]`), so a rule's denied set stays legible from the policy alone.
+export function parsePolicy(text, aliases = null) {
   const deny = [], allow = [], forbid = [];
   // Split LINES on \n / \r\n / bare \r — the three forms Java's Files.readAllLines (the reference parser)
   // breaks on. Splitting on \n ONLY let a classic-Mac (bare-\r) file collapse to one line: \r is also an
@@ -28,14 +48,40 @@ export function parsePolicy(text) {
     if (t[0] === "deny") {
       const effects = [];
       let scope = "";
+      // Reason-class filter on an `Unknown` membership: empty ⇒ `Unknown[*]` (any reason — the bare
+      // form); non-empty ⇒ only those classes. `*` = all; `dynamic` = every genuine class.
+      const unknownClasses = new Set();
+      let unknownStar = false;
       for (const tok of t.slice(1)) {
-        if (EFFECTS.includes(tok) || tok === "Unknown") effects.push(tok);
-        else { scope = tok; break; }
+        const m = /^Unknown\[(.*)\]$/.exec(tok);
+        if (m) {
+          effects.push("Unknown");
+          for (let cn of m[1].split(",")) {
+            cn = cn.trim();
+            if (!cn) continue;
+            if (cn === "*") unknownStar = true;
+            else if (cn === "dynamic") DYNAMIC_CLASSES.forEach((c) => unknownClasses.add(c));
+            else if (REASON_CLASSES.includes(cn)) unknownClasses.add(cn);
+            else if (aliases && aliases.has(cn)) aliases.get(cn).forEach((c) => unknownClasses.add(c)); // ⟨0.19⟩ config unknown-alias
+            else warn(`unknown reason-class/alias \`${cn}\` (known: ${REASON_CLASSES.join(",")}; aliases: dynamic,*, or a config \`unknown-alias\`)`);
+          }
+          continue;
+        }
+        if (EFFECTS.includes(tok) || tok === "Unknown") {
+          effects.push(tok);
+          if (tok === "Unknown") unknownStar = true; // bare Unknown ⇒ all classes
+        } else { scope = tok; break; }
       }
       if (effects.length === 0) { warn("deny names no known effect"); continue; }
-      deny.push({ effects: [...new Set(effects)].sort(), scope, raw: line }); // dedup: a set, like rust/java
+      // `*` (or bare Unknown) means all classes ⇒ empty filter (matches any Unknown).
+      let uc = unknownStar ? [] : [...unknownClasses].sort();
+      // A2 under-gating lint: a narrowed scope omitting `unresolved` (the catch-all for holes the engine
+      // couldn't classify) may silently tolerate exactly those — flag it (advisory, non-fatal).
+      if (uc.length && !uc.includes("unresolved"))
+        console.error(`candor: policy rule narrows \`Unknown[…]\` but omits \`unresolved\` — may UNDER-gate on holes the engine couldn't classify; add \`unresolved\` (or use \`dynamic\`): ${line}`);
+      deny.push({ effects: [...new Set(effects)].sort(), scope, unknownClasses: uc, raw: line }); // dedup: a set, like rust/java
     } else if (t[0] === "pure") {
-      deny.push({ effects: [], scope: t[1] ?? "", raw: line });
+      deny.push({ effects: [], scope: t[1] ?? "", unknownClasses: [], raw: line });
     } else if (t[0] === "allow") {
       if (t.length < 3) { warn("allow names no values"); continue; }
       if (!ALLOW_EFFECTS.has(t[1])) { warn("allow supports only Net hosts / Llm hosts / Exec commands / Fs paths / Db tables"); continue; }
@@ -121,7 +167,30 @@ export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()
   const out = [];
   // `Llm` ⟨0.13⟩ reaches the SAME hosts surface as Net (an Llm host WAS captured as a Net host literal).
   const surfaces = { Net: "hosts", Llm: "hosts", Exec: "cmds", Fs: "paths", Db: "tables" };
-  const push = (rule, fn, effects, detail) => out.push({ rule, fn, effects, detail });
+  // §6.2 ⟨0.19⟩: `reasonClass` (all classes on the fn) rides an AS-EFF-006 Unknown violation; omitted otherwise.
+  const push = (rule, fn, effects, detail, reasonClass) =>
+    out.push(reasonClass && reasonClass.length ? { rule, fn, effects, detail, reasonClass } : { rule, fn, effects, detail });
+  // Reason-scoped Unknown: the Unknown reason CLASS must travel the call graph the same way the Unknown
+  // EFFECT does (unknownWhy in the report is direct-only). Classify each fn's DIRECT reasons to class
+  // tokens, then propagate transitively over `callgraph` to a fixpoint — so `deny E Unknown[reflect]` at a
+  // caller inheriting Unknown from a reflect-caused callee still fires (matches java/rust reasonClassAcc).
+  const reasonAcc = new Map();
+  for (const f of functions) {
+    const cs = new Set((f.unknownWhy ?? []).map(reasonClass));
+    if (cs.size) reasonAcc.set(f.fn, cs);
+  }
+  for (let changed = true; changed; ) {
+    changed = false;
+    for (const [caller, callees] of Object.entries(callgraph)) {
+      for (const callee of callees) {
+        const cc = reasonAcc.get(callee);
+        if (!cc) continue;
+        let set = reasonAcc.get(caller);
+        if (!set) { set = new Set(); reasonAcc.set(caller, set); }
+        for (const c of cc) if (!set.has(c)) { set.add(c); changed = true; }
+      }
+    }
+  }
   for (const f of functions) {
     for (const r of pol.deny) {
       if (r.scope && !scopeMatches(f.fn, r.scope)) continue;
@@ -132,7 +201,19 @@ export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()
       const hits = r.effects.length === 0
         ? f.inferred.filter((e) => e !== "Unknown")
         : f.inferred.filter((e) => r.effects.includes(e));
-      if (hits.length) push("AS-EFF-006", f.fn, hits, `\`${f.fn}\` performs { ${hits.join(", ")} }, forbidden by policy: \`${r.raw}\``);
+      // Reason-scoped Unknown: a `deny E Unknown[classes]` keeps its Unknown hit only for a fn whose
+      // TRANSITIVE reason classes include one of those; an Unknown with no recorded reason ⇒ `unresolved`.
+      let kept = hits;
+      if (hits.includes("Unknown") && (r.unknownClasses?.length)) {
+        const cs = reasonAcc.get(f.fn);
+        const fnClasses = cs && cs.size ? [...cs] : ["unresolved"];
+        if (!fnClasses.some((c) => r.unknownClasses.includes(c))) kept = hits.filter((e) => e !== "Unknown");
+      }
+      if (kept.length) {
+        // When Unknown is denied, report ALL reason classes on the fn (transitive) — every reason the gate bit.
+        const rc = kept.includes("Unknown") ? [...(reasonAcc.get(f.fn) ?? [])].sort() : undefined;
+        push("AS-EFF-006", f.fn, kept, `\`${f.fn}\` performs { ${kept.join(", ")} }, forbidden by policy: \`${r.raw}\``, rc);
+      }
     }
     for (const r of pol.allow) {
       if (r.scope && !scopeMatches(f.fn, r.scope)) continue;
@@ -199,3 +280,50 @@ export function discoverConfigPolicy(fromDir) {
     dir = parent;
   }
 }
+
+// ⟨0.19⟩ Discover `.candor/config` TEXT anchored at `fromDir`: $CANDOR_CONFIG if set + readable, else the
+// nearest `.candor/config` walking UP, else null. Read-only + lenient (the caller decides fail-closed).
+export function discoverConfigText(fromDir) {
+  const env = process.env.CANDOR_CONFIG;
+  if (env) { try { return fs.readFileSync(env, "utf8"); } catch { return null; } }
+  let dir = nodePath.resolve(fromDir);
+  for (;;) {
+    const cand = nodePath.join(dir, ".candor", "config");
+    if (fs.existsSync(cand)) { try { return fs.readFileSync(cand, "utf8"); } catch { return null; } }
+    const parent = nodePath.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// ⟨0.19⟩ Parse `unknown-alias <name> = <class,…>` lines (SPEC §6.2) into a Map name→class-token[]. A name
+// that shadows a built-in (`*`/`dynamic`/a class token) is warned-and-skipped, as is a no-valid-class def.
+// Byte-shape with the java `Config.addAlias` / rust `parse_unknown_aliases`.
+export function parseUnknownAliases(configText) {
+  const out = new Map();
+  if (!configText) return out;
+  for (const raw of configText.split(/\r?\n/)) {
+    const line = raw.split("#", 1)[0].trim();
+    if (!line) continue;
+    const m = line.match(/^(\S+)\s+(.*)$/);
+    if (!m || m[1].toLowerCase() !== "unknown-alias") continue;
+    const eq = m[2].indexOf("=");
+    if (eq < 0) { console.error(`candor: ignoring \`unknown-alias\` (want \`unknown-alias <name> = <class,…>\`): ${m[2]}`); continue; }
+    const name = m[2].slice(0, eq).trim();
+    if (!name || name === "*" || name === "dynamic" || REASON_CLASSES.includes(name)) {
+      console.error(`candor: ignoring \`unknown-alias\` with reserved/empty name \`${name}\` (may not shadow \`*\`/\`dynamic\`/a class token)`);
+      continue;
+    }
+    const classes = new Set();
+    for (let cn of m[2].slice(eq + 1).split(",")) {
+      cn = cn.trim();
+      if (!cn) continue;
+      if (cn === "dynamic") DYNAMIC_CLASSES.forEach((c) => classes.add(c));
+      else if (REASON_CLASSES.includes(cn)) classes.add(cn);
+      else console.error(`candor: \`unknown-alias ${name}\` names unknown reason-class \`${cn}\` — skipped`);
+    }
+    if (classes.size === 0) console.error(`candor: ignoring \`unknown-alias ${name}\` — no valid reason-class`);
+    else out.set(name, [...classes]);
+  }
+  return out;
+}

package/query.mjs

@@ -23,7 +23,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { parsePolicy, scopeMatches, discoverConfigPolicy } from "./policy.mjs";
+import { parsePolicy, scopeMatches, discoverConfigPolicy, parseUnknownAliases, discoverConfigText } from "./policy.mjs";
 import { hasReport } from "./query-core.mjs";
 import { printAgents } from "./contract.mjs";
 import { bestFinds } from "./surface.mjs";
@@ -44,6 +44,18 @@ 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
@@ -184,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.17";
+const SPEC_VERSION = "0.19";
 
 // ---- 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]
@@ -272,14 +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 (strict && a === "--strict") { wantStrict = true; continue; }
-    if (includeUnknown && a === "--include-unknown") { wantIncludeUnknown = true; continue; }
+    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);
+    }
     positionals.push(a);
   }
   // Deprecated trailing `0|1` JSON sentinel (Rust/TS legacy): if the LAST positional is a bare 0 or 1,
@@ -384,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)"],
 ];
@@ -447,7 +466,9 @@ OPTIONS  (uniform across every engine)
   --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
 
@@ -480,7 +501,10 @@ switch (cmd) {
       console.error(`candor: policy ${args[0] ?? "(no file given)"} could not be read`);
       process.exit(2);
     }
-    emit(parsePolicy(text));
+    // ⟨0.19⟩ config-aware: resolve `Unknown[<alias>]` via a checked-in `unknown-alias`, anchored to the
+    // policy file (or CANDOR_CONFIG) — the dump reflects real gate resolution + pins the four-way expansion.
+    const aliases = parseUnknownAliases(discoverConfigText(path.dirname(path.resolve(args[0]))));
+    emit(parsePolicy(text, aliases));
     break;
   }
   case "show": {
@@ -693,13 +717,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}:`);
@@ -716,8 +760,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
@@ -736,10 +785,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).
+    const gainsResult = coreGains(loadReportOrDie(curPrefix), loadReportOrDie(basePrefix), loadCallgraph(basePrefix));
     put(args, { baseline_version: gbv ?? "", engine_version: gv ?? "",
-           ...coreGains(loadReportOrDie(curPrefix), loadReportOrDie(basePrefix), loadCallgraph(basePrefix)),
-           ...gainsCoverage(curPrefix, basePrefix) }, P.gains);
-    break;
+           ...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
@@ -818,15 +870,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

@@ -26,7 +26,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
-import { parsePolicy, evaluatePolicy, scopeMatches } from "./policy.mjs";
+import { parsePolicy, evaluatePolicy, scopeMatches, parseUnknownAliases, discoverConfigText, reasonClass } from "./policy.mjs";
 import { unverifiedHoleRule, ruleUpgrade } from "./query-core.mjs";
 import { printAgents } from "./contract.mjs";
 import { isTestPath, kappa, kappaKnows, commandHeadEffects, hostLiteral, tablesInSql,
@@ -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.17";
+const SPEC_VERSION = "0.19";
 
 // --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
@@ -294,6 +294,13 @@ if (!wantJson) fs.mkdirSync(path.dirname(path.resolve(outPrefix)), { recursive:
 // A target with declared dependencies but no node_modules resolves almost nothing — the scan
 // would "succeed" with a near-total-Unknown report a fresh user could ship (CTA-dogfood finding).
 // Warn LOUDLY; the report is still written (it is sound), but the cause must be visible.
+// ⟨0.19⟩ Also compute `declaredButUninstalled` (SPEC §6.2 §3, the setup/genuine split): a declared dep
+// whose `node_modules/<dep>` is absent. An `Unknown` caused by a call into one of these is a SETUP hole
+// (`no-node_modules:<pkg>` → reason class `setup`), NOT a genuine dynamic blind spot — the fix is
+// `npm install`, not a policy decision. Tagging them separates the fatigue-vector (the referee's
+// week-two-uninstall) from real dynamism, so a team can `Unknown[dynamic]` a strict gate AND be told
+// exactly what to configure to shrink the rest.
+const declaredButUninstalled = new Set();
 {
   // Find the nearest package.json AT OR ABOVE the scan root: scanning a `src/` subdirectory must still see
   // the project manifest one level up, else the warning stays silent and a deps-less scan reads as a
@@ -303,14 +310,25 @@ if (!wantJson) fs.mkdirSync(path.dirname(path.resolve(outPrefix)), { recursive:
     if (fs.existsSync(path.join(d, "package.json"))) { projDir = d; break; }
     if (path.dirname(d) === d) break;                       // filesystem root
   }
-  if (projDir && !fs.existsSync(path.join(projDir, "node_modules"))) {
+  if (projDir) {
     try {
       // BOTH dependency kinds: `npm install` installs devDependencies too, and a project can import a
       // dev/vendored package in its source (zx imports `chalk` as a devDependency) — a `dependencies`-only
       // check left exactly that case unwarned.
       const pj = JSON.parse(fs.readFileSync(path.join(projDir, "package.json"), "utf8"));
       const deps = { ...(pj.dependencies ?? {}), ...(pj.devDependencies ?? {}) };
-      if (Object.keys(deps).length > 0)
+      // "Installed?" follows node resolution: node_modules is searched at projDir AND every ANCESTOR, so a
+      // dep HOISTED to a monorepo/workspace root counts as installed. Checking only projDir wrongly named a
+      // hoisted-but-resolvable package in the SETUP diagnostic (review-found; cosmetic — the gate was already
+      // safe via the resolve-first ordering, but the message must not cry wolf).
+      const installed = (dep) => {
+        for (let d = projDir; ; d = path.dirname(d)) {
+          if (fs.existsSync(path.join(d, "node_modules", dep))) return true;
+          if (path.dirname(d) === d) return false;
+        }
+      };
+      for (const dep of Object.keys(deps)) if (!installed(dep)) declaredButUninstalled.add(dep);
+      if (Object.keys(deps).length > 0 && !fs.existsSync(path.join(projDir, "node_modules")))
         console.error("candor-ts: WARNING — the project declares dependencies but has no node_modules; " +
                       "imports won't resolve, so calls into those packages can't be analyzed (they read " +
                       "`Unknown`, and their types don't resolve). Run `npm install` in the project first.");
@@ -407,6 +425,33 @@ function declModule(decl) {
   return f;
 }
 
+// ⟨0.19⟩ The bare-package ROOT of an import specifier: `@scope/pkg/sub` → `@scope/pkg`, `pkg/sub` → `pkg`,
+// a relative/absolute path → null (not a package). Used to match an import against `declaredButUninstalled`.
+function pkgRoot(spec) {
+  if (!spec || spec.startsWith(".") || spec.startsWith("/")) return null;
+  const seg = spec.split("/");
+  return spec.startsWith("@") ? seg.slice(0, 2).join("/") : seg[0];
+}
+
+// ⟨0.19⟩ The import module a call's HEAD identifier binds to (`winston.info()` → head `winston`; `chalk()` →
+// `chalk`) via its import declaration — resolvable even when the package ISN'T installed, because the import
+// statement is syntactically present in the local file. Mirrors the specifier extraction at the κ seam.
+// Returns the bare-package root, or null when the head isn't an imported binding.
+function importPkgOfHead(expr) {
+  let head = expr;
+  while (head && ts.isPropertyAccessExpression(head)) head = head.expression;
+  if (!head || !ts.isIdentifier(head)) return null;
+  const sym = checker.getSymbolAtLocation(head);
+  for (const d of sym?.declarations ?? []) {
+    let spec = null;
+    if (ts.isNamespaceImport(d)) spec = d.parent?.parent?.moduleSpecifier;
+    else if (ts.isImportClause(d)) spec = d.parent?.moduleSpecifier;              // default import
+    else if (ts.isImportSpecifier(d)) spec = d.parent?.parent?.parent?.moduleSpecifier; // named import
+    if (spec && ts.isStringLiteralLike(spec)) return pkgRoot(spec.text);
+  }
+  return null;
+}
+
 // SPEC §5.1 — the effect manifest. An uncurated package MAY declare its effect surface in its
 // package.json (`"candorEffects": ["Net"]`), read as the declared-not-verified tier: it kills the
 // silent pure/blind-spot the package would otherwise carry, exactly like a cap type (and unlike
@@ -1662,8 +1707,16 @@ function visitCalls(node) {
                                    // 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);
-            rec.why.add(`callback:${callee}`); // an `any`-typed/indeterminate callee (a function VALUE) — canonical `callback:`
+            // ⟨0.19⟩ SETUP split (SPEC §6.2 §3): if the callee binds to a DECLARED-but-UNINSTALLED package,
+            // this Unknown is a mis-configuration (the pkg isn't `npm install`ed), not a genuine dynamic hole
+            // — tag `no-node_modules:<pkg>` (reason class `setup`) so it's SEPARABLE + `npm install`-fixable.
+            const setupPkg = declaredButUninstalled.size ? importPkgOfHead(node.expression) : null;
+            if (setupPkg && declaredButUninstalled.has(setupPkg)) {
+              rec.why.add(`no-node_modules:${setupPkg}`);
+            } else {
+              const callee = (node.expression?.getText?.() ?? "?").replace(/\s+/g, "").slice(0, 60);
+              rec.why.add(`callback:${callee}`); // an `any`-typed/indeterminate callee (a function VALUE) — canonical `callback:`
+            }
           }
         }
       } else {
@@ -2620,6 +2673,30 @@ if (!wantJson) {
     console.error(`  ${breakdown}${unknown ? `${breakdown ? "   ·   " : ""}Unknown ${unknown} (disclosed)` : ""}`);
   }
 }
+{
+  // ⟨0.19⟩ SETUP diagnostic (SPEC §6.2 §3, the setup/genuine split): functions that read Unknown ONLY
+  // because the scan isn't configured (a declared dep not installed → `no-node_modules:<pkg>`, reason class
+  // `setup`) are a FIXABLE mis-configuration, not a genuine dynamic blind spot. Surface them LOUDLY with the
+  // fix and separate from real dynamism — so a team runs `npm install` instead of disabling a strict gate on
+  // unconfigured analysis (the referee's week-two-uninstall). `Unknown[dynamic]` EXCLUDES `setup`, so a
+  // strict gate can bite genuine dynamism while tolerating these until the config is fixed.
+  const setupPkgs = new Set();
+  let setupFns = 0;
+  for (const e of functions) {
+    const why = e.unknownWhy ?? [];
+    if (!why.some((w) => reasonClass(w) === "setup")) continue;
+    setupFns++;
+    for (const w of why) { const m = /^no-node_modules:(.+)$/.exec(w); if (m) setupPkgs.add(m[1]); }
+  }
+  if (setupFns > 0) {
+    const pkgs = [...setupPkgs].sort();
+    const shown = pkgs.slice(0, 6).join(", ") + (pkgs.length > 6 ? `, +${pkgs.length - 6} more` : "");
+    console.error(`candor-ts: SETUP — ${setupFns} function(s) read Unknown ONLY because ${pkgs.length} declared `
+      + `package(s) aren't installed (${shown}); run \`npm install\`, then re-scan. These are unconfigured `
+      + `analysis, NOT real blind spots — a strict gate can still bite genuine dynamism with `
+      + `\`deny E Unknown[dynamic]\` (which tolerates \`setup\`), then shrink to zero once installed.`);
+  }
+}
 if (unlistedSeen.size > 0) {
   const top = uncoveredLedger; // ⟨0.15 staged⟩ the shared sorted ledger — same names/counts as envelope `coverage`
   const shown = top.slice(0, 8).map(([p, n]) => `${p} (${n} call${n === 1 ? "" : "s"})`).join(", ");
@@ -2796,11 +2873,13 @@ if (policyPath !== null) {
   // java/rust engines (not a report field) — passed to the gate so an incomplete surface fails closed.
   const incompleteMap = new Map();
   for (const [name, rec] of fns) if (rec.incomplete.size) incompleteMap.set(name, rec.incomplete);
-  gateViolations = gateViolations.concat(evaluatePolicy(parsePolicy(text), functions, cg, incompleteMap));
+  // ⟨0.19⟩ reason-class aliases (SPEC §6.2) from `.candor/config`, so `Unknown[<alias>]` resolves at the gate.
+  const unknownAliases = parseUnknownAliases(discoverConfigText(target));
+  gateViolations = gateViolations.concat(evaluatePolicy(parsePolicy(text, unknownAliases), functions, cg, incompleteMap));
   // Provable-purity DISCLOSURE (advisory — NEVER a violation, so the exit/verdict are untouched): functions
   // in a pure/deny scope that PASS but are Unknown (the Unknown could hide the forbidden effect — a
   // fn/closure-injected port). Surfaces the gap automatically (eval/fixloop/DISPATCH-NOTE.md).
-  const disclosePolicy = parsePolicy(text);
+  const disclosePolicy = parsePolicy(text, unknownAliases);
   const purityHoles = [];
   for (const f of functions) {
     // Same predicate + upgrade as `candor-ts-query unverified` (query-core.mjs) — one source of truth.

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;
   }