candor-ts 0.18.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.18)."*
+> 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.18" }, 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.18.x, speaking candor-spec 0.18: 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.18.0",
-  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.18)",
+  "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";
@@ -196,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.18";
+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]
@@ -501,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": {

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.18";
+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.