candor-ts 0.18.0 → 0.20.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.20)."*
 > 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.20" }, 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.19.x, speaking candor-spec 0.20: 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.20.0",
+  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.20)",
   "type": "module",
   "dependencies": {
     "@types/node": "^25.9.2",

package/policy.mjs

@@ -4,7 +4,26 @@
  * engines follow (candor-classify::policy), so the TS gate can never disagree with its own whatif.
  */
 
+import { NET_DEST_CLASSES, netClassesOf } from "./scan-core.mjs";
+
 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 +33,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 +50,59 @@ 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;
+      // Destination-class filter on a `Net` membership (NET-DESTINATION-CLASS-DESIGN.md): empty ⇒ `Net[*]`
+      // (any destination — the bare form); non-empty ⇒ only those classes. `*` = all.
+      const netClasses = new Set();
+      let netStar = false;
       for (const tok of t.slice(1)) {
-        if (EFFECTS.includes(tok) || tok === "Unknown") effects.push(tok);
-        else { scope = tok; break; }
+        const nm = /^Net\[(.*)\]$/.exec(tok);
+        if (nm) {
+          effects.push("Net");
+          for (let cn of nm[1].split(",")) {
+            cn = cn.trim();
+            if (!cn) continue;
+            if (cn === "*") netStar = true;
+            else if (NET_DEST_CLASSES.includes(cn)) netClasses.add(cn);
+            else warn(`unknown Net destination-class \`${cn}\` (known: ${NET_DEST_CLASSES.join(",")}, or *)`);
+          }
+          continue;
+        }
+        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
+          if (tok === "Net") netStar = true;         // bare Net ⇒ all destinations
+        } 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();
+      // `*` (or bare Net) means all destinations ⇒ empty filter (matches any Net).
+      const nc = netStar ? [] : [...netClasses].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, netClasses: nc, 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: [], netClasses: [], 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; }
@@ -117,11 +184,39 @@ export function literalAllowed(effect, reached, values) {
 // is the specific denied/allowed effect set the violation concerns ([] for the 009 layer-flow, which has
 // no single effect); `detail` is the message BODY (no `[AS-EFF-00x]` prefix — the rule carries the code).
 // The console gate renders `[${rule}] ${detail}`; --gate-json emits the records verbatim.
-export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()) {
+export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map(), partners = new Set()) {
   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; ⟨0.20⟩ `netClass`
+  // (all destination classes on the fn) rides a Net violation. Both omitted when empty (byte-identical verdict).
+  const push = (rule, fn, effects, detail, reasonClass, netClass) => {
+    const rec = { rule, fn, effects, detail };
+    if (reasonClass && reasonClass.length) rec.reasonClass = reasonClass;
+    if (netClass && netClass.length) rec.netClass = netClass;
+    out.push(rec);
+  };
+  // 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 +227,31 @@ 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");
+      }
+      // Net destination-class: a `deny Net[dest…]` keeps its Net hit only for a fn reaching one of those
+      // destination classes; else tolerate (only asserted-safe destinations). Fail-closed: a masked surface /
+      // a Net with no visible host is unknown-host (netClassesOf). The class travels the call graph via
+      // f.hosts + f.incomplete, both propagated transitively before the gate (scan.mjs).
+      if (kept.includes("Net") && (r.netClasses?.length)) {
+        const fnNet = netClassesOf(f.hosts ?? [], incomplete.get(f.fn)?.has("Net") ?? false, partners);
+        if (!fnNet.some((c) => r.netClasses.includes(c))) kept = kept.filter((e) => e !== "Net");
+      }
+      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;
+        // ⟨0.20⟩ when Net is denied, report ALL of the fn's destination classes (transitive).
+        const ncv = kept.includes("Net")
+          ? netClassesOf(f.hosts ?? [], incomplete.get(f.fn)?.has("Net") ?? false, partners)
+          : undefined;
+        push("AS-EFF-006", f.fn, kept, `\`${f.fn}\` performs { ${kept.join(", ")} }, forbidden by policy: \`${r.raw}\``, rc, ncv);
+      }
     }
     for (const r of pol.allow) {
       if (r.scope && !scopeMatches(f.fn, r.scope)) continue;
@@ -199,3 +318,68 @@ 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;
+}
+
+// ⟨0.20⟩ Parse `net-partner <host>` lines (NET-DESTINATION-CLASS-DESIGN.md) into a Set of host-normalized
+// partner hosts — the per-project `known-partner` set for the Net destination-class classifier. Multi-value
+// (repeatable key); the value's `:port` is stripped + lowercased like MODEL_HOSTS. Case-insensitive key,
+// mirroring parseUnknownAliases + the java/rust config loaders. A partner is per-project — never universal.
+export function parseNetPartners(configText) {
+  const out = new Set();
+  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() !== "net-partner") continue;
+    const val = m[2].trim();
+    if (val) out.add(hostPart(val).toLowerCase());
+  }
+  return out;
+}

package/query-core.mjs

@@ -10,6 +10,7 @@
  */
 import fs from "node:fs";
 import nodePath from "node:path";
+import { reasonClass } from "./policy.mjs";
 
 // Sibling report/callgraph files of a multi-report prefix (candor-scan writes <prefix>.<crate>.scan.json,
 // one per workspace member) — so the loaders read ANY engine's output, not just candor-ts's <prefix>.json.
@@ -498,13 +499,32 @@ export function impact(fns, cg, q) {
 // Unknown through it). The actionable inverse of a widely-propagated Unknown: a report can read mostly
 // Unknown from a handful of root causes — this names them, ranked, to declare/resolve/accept. Matches
 // candor-java/candor-query: { sources:[{fn,why,reaches,affected}], totalUnknown }.
-export function blindspots(fns, cg) {
+// ⟨0.20⟩ `--class <c,…>` filter: the six reason classes, `dynamic` (every genuine class), or `*` (all).
+// null spec ⇒ no filter; an unknown token warns; an all-unknown spec ⇒ an empty set that matches nothing.
+const ALL_CLASSES = ["reflect", "dispatch", "indirect", "native", "unresolved", "setup"];
+export function parseClassFilter(spec) {
+  if (!spec) return null;
+  const out = new Set();
+  for (let t of spec.split(",")) {
+    t = t.trim();
+    if (!t) continue;
+    if (t === "*") return new Set(ALL_CLASSES);
+    if (t === "dynamic") { for (const c of ALL_CLASSES) if (c !== "setup") out.add(c); continue; }
+    if (ALL_CLASSES.includes(t)) out.add(t);
+    else console.error(`candor-ts: --class ignores unknown reason-class \`${t}\` (known: ${ALL_CLASSES.join(",")}; aliases: dynamic,*)`);
+  }
+  return out;
+}
+const classMatches = (cf, why) => cf === null || (why ?? []).some((w) => cf.has(reasonClass(w)));
+
+export function blindspots(fns, cg, classSpec = null) {
+  const cf = parseClassFilter(classSpec);
   const rev = reverseGraph(cg);
   const totalUnknown = fns.filter((e) => (e.inferred ?? []).includes("Unknown")).length;
   const sources = [];
   for (const e of fns) {
     const why = e.unknownWhy ?? [];
-    if (why.length === 0) continue; // a SOURCE carries its own unknownWhy; a purely-transitive Unknown does not
+    if (why.length === 0 || !classMatches(cf, why)) continue; // a SOURCE of a matching reason class
     const reached = new Set();
     const queue = [e.fn];
     const seen = new Set([e.fn]);
@@ -519,6 +539,26 @@ export function blindspots(fns, cg) {
   return { sources, totalUnknown };
 }
 
+// `blindspots --stats` (SPEC §3.1 ⟨0.20⟩): the reason-class DISTRIBUTION over the Unknown SOURCES — how
+// much Unknown, by class {reflect,dispatch,indirect,native,unresolved,setup} — so a team can SIZE the
+// blind-spot cost (and separate genuine dynamism from `setup` mis-config) BEFORE `deny E Unknown`. Counts
+// SOURCE functions per class (a multi-reason fn counts in each class it has). Matches candor-java/rust/swift.
+export function blindspotsStats(fns, classSpec = null) {
+  const cf = parseClassFilter(classSpec);
+  const ORDER = ["reflect", "dispatch", "indirect", "native", "unresolved", "setup"];
+  const byClass = Object.fromEntries(ORDER.map((c) => [c, 0]));
+  const totalUnknown = fns.filter((e) => (e.inferred ?? []).includes("Unknown")).length;
+  let sources = 0;
+  for (const e of fns) {
+    const why = e.unknownWhy ?? [];
+    if (why.length === 0 || !classMatches(cf, why)) continue;
+    sources++;
+    const classes = new Set(why.map(reasonClass));
+    for (const c of classes) byClass[c]++;
+  }
+  return { byClass, sources, totalUnknown };
+}
+
 // path: the FORWARD provenance — a shortest BFS over the calls graph from `fn` to the nearest unit
 // that performs `eff` DIRECTLY (the source). Matches candor-query's {effect, fn, path:[{fn,loc,source}]}.
 export function path(fns, cg, fnQ, eff) {
@@ -806,12 +846,13 @@ export function unverifiedHoleRule(fn, inferred, policyParsed, scopeMatches) {
   return null;
 }
 
-export function unverified(fns, policyParsed, scopeMatches) {
+export function unverified(fns, policyParsed, scopeMatches, classSpec = null) {
+  const cf = parseClassFilter(classSpec);   // ⟨0.20⟩ --class: keep only holes of a matching reason class
   const holes = [];
   for (const e of fns) {
     // Same predicate + upgrade as the gate note (scan.mjs) — one source of truth for a hole.
     const r = unverifiedHoleRule(e.fn, e.inferred, policyParsed, scopeMatches);
-    if (!r) continue;
+    if (!r || !classMatches(cf, e.unknownWhy)) continue;
     const [rule, upgrade] = ruleUpgrade(r);
     holes.push({ fn: e.fn, rule, unknownWhy: e.unknownWhy ?? [], upgrade });
   }

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";
@@ -33,7 +33,7 @@ import { isTestPath } from "./scan-core.mjs";
 // a `matchTier` missing `#` (so the SAME query resolved differently between `impact` and `callers` on a
 // JVM `Type#method` report). Importing the shared functions removes all three divergences (review find).
 import { impact as coreImpact, path as corePath, gains as coreGains,
-         show as coreShow, blindspots as coreBlindspots,
+         show as coreShow, blindspots as coreBlindspots, blindspotsStats as coreBlindspotsStats,
          callers as coreCallers, callersFrontier, loadHierarchy,
          containment as coreContainment, diff as coreDiff,
          where as coreWhere, map as coreMap, whatif as coreWhatif,
@@ -46,7 +46,7 @@ const emit = (v) => console.log(JSON.stringify(v, null, 1));
 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 known = ["--report", "--policy", "--json", "--text", "--strict", "--include-unknown", "--stats", "--class"];
   const u = unknown.replace(/^-+/, "").toLowerCase();
   let best = null, bestLen = 2;
   for (const k of known) {
@@ -132,6 +132,12 @@ const P = {
     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)`);
   },
+  blindspotsStats: (d) => {
+    if (!d.sources) { console.log("candor blindspots --stats — no Unknown sources (nothing to classify). ✓"); return; }
+    console.log(`candor blindspots --stats — ${d.sources} Unknown source(s) by reason class (of ${d.totalUnknown} function(s) carrying Unknown) — size the blind-spot cost before \`deny E Unknown[…]\`:`);
+    Object.entries(d.byClass).filter(([, v]) => v > 0).sort((a, b) => b[1] - a[1])
+      .forEach(([k, v]) => console.log(`  ${k.padEnd(12)} ${String(v).padStart(4)}${k === "setup" ? "   ← fixable: the scan isn't configured, not a real blind spot" : ""}`));
+  },
   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(", ")}`);
@@ -196,7 +202,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.20";
 
 // ---- 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]
@@ -292,11 +298,16 @@ function parseCanonical(rawArgs, { policy = false, strict = false, includeUnknow
                                                                             // 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 === "--stats") { continue; }   // ⟨0.20⟩ tolerated everywhere; read by the `blindspots` case via args.includes
+    if (a === "--class") { // ⟨0.20⟩ value flag; the value is read by the `blindspots` case
+      if (i + 1 >= rawArgs.length) { console.error("candor-ts: --class requires a <class,…> value (reflect,dispatch,indirect,native,unresolved,setup; aliases: dynamic,*)"); process.exit(2); }
+      i++; continue;
+    }
     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`);
+      console.error(`candor-ts-query: unknown flag '${a}'${didYouMeanFlag(a)}\n  known flags: --report, --policy, --json, --text, --strict, --include-unknown, --stats`);
       process.exit(2);
     }
     positionals.push(a);
@@ -401,7 +412,7 @@ const SUBCOMMANDS = [
   ["diff", "<current> <baseline> [--json]", "per-function effect delta vs a baseline: {changes:[{fn,gained,lost}]} (exit 1 on a gain)"],
   ["reachable", REPORT_TAIL, "effects unioned over the entry points: what the app DOES at runtime"],
   ["impact", `<query> ${REPORT_TAIL}`, "blast radius of a function (backward dual of reachable)"],
-  ["blindspots", REPORT_TAIL, "the Unknown sources, ranked by blast radius"],
+  ["blindspots", `${REPORT_TAIL} [--stats] [--class <c,…>]`, "the Unknown sources ranked by blast radius; --stats: reason-class distribution; --class: drill down"],
   ["tour", `[<N>] ${REPORT_TAIL}`, "the N most surprising transitive reaches — the guided cold-repo poke (no re-scan)"],
   ["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"],
@@ -501,7 +512,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": {
@@ -653,7 +667,13 @@ switch (cmd) {
     // 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);
-    put(args, coreBlindspots(loadReportOrDie(prefix), loadCallgraph(prefix)), P.blindspots);
+    const ci = args.indexOf("--class");
+    const classFilter = ci >= 0 ? args[ci + 1] : null;   // ⟨0.20⟩ drill-down by reason class
+    if (args.includes("--stats")) {   // ⟨0.20⟩ the reason-class distribution, not the source list
+      put(args, coreBlindspotsStats(loadReportOrDie(prefix), classFilter), P.blindspotsStats);
+    } else {
+      put(args, coreBlindspots(loadReportOrDie(prefix), loadCallgraph(prefix), classFilter), P.blindspots);
+    }
     break;
   }
   case "tour": {
@@ -891,7 +911,8 @@ switch (cmd) {
     let ptext;
     try { ptext = fs.readFileSync(policyFile, "utf8"); }
     catch { console.error(`candor: policy ${policyFile} could not be read`); process.exit(2); }
-    const r = coreUnverified(loadReportOrDie(prefix), parsePolicy(ptext), scopeMatches);
+    const uci = args.indexOf("--class");   // ⟨0.20⟩ drill-down by reason class
+    const r = coreUnverified(loadReportOrDie(prefix), parsePolicy(ptext), scopeMatches, uci >= 0 ? args[uci + 1] : null);
     emit(r);
     process.exit(strict && !r.ok ? 1 : 0);
     break; // unreachable

package/scan-core.mjs

@@ -293,6 +293,65 @@ export function isModelHost(hostLiteral) {
 export function modelHostEffects(hostLiteral) {
   return isModelHost(hostLiteral) ? ["Llm"] : [];
 }
+// ⟨0.20⟩ Curated telemetry / analytics / APM hosts — the `Net` destination-class `known-telemetry` set
+// (NET-DESTINATION-CLASS-DESIGN.md), shared VERBATIM with the sibling engines (java Literals.TELEMETRY_HOSTS
+// / rust TELEMETRY_HOSTS), like MODEL_HOSTS. A benign observability endpoint. Matched by host,
+// case-insensitive; a SUBDOMAIN of a listed host counts. Tight, high-precision STARTER set — mis-including
+// an exfil-capable host would under-gate `deny Net[unknown-host]`.
+export const TELEMETRY_HOSTS = new Set([
+  "sentry.io",
+  "bugsnag.com",
+  "rollbar.com",
+  "segment.io", "segment.com",
+  "mixpanel.com",
+  "amplitude.com",
+  "google-analytics.com", "analytics.google.com",
+  "datadoghq.com", "datadoghq.eu",
+  "newrelic.com", "nr-data.net",
+  "honeycomb.io",
+  "logtail.com",
+]);
+// Normalize a `host[:port]` literal to a bare lowercase hostname (the MODEL_HOSTS stripping), for the
+// destination-class membership tests.
+function normHost(hostLiteral) {
+  if (hostLiteral == null) return "";
+  let host = hostLiteral;
+  if (host.startsWith("[")) { const e = host.indexOf("]"); if (e >= 0) host = host.slice(1, e); }
+  else if ((host.match(/:/g) ?? []).length === 1) host = host.split(":")[0];
+  return host.toLowerCase();
+}
+// Subdomain-aware membership of `hostLiteral` in a host `set` (mirrors java Literals.hostInSet).
+function hostInSet(hostLiteral, set) {
+  const host = normHost(hostLiteral);
+  if (set.has(host)) return true;
+  for (const e of set) if (host.endsWith("." + e)) return true;
+  return false;
+}
+export function isTelemetryHost(hostLiteral) { return hostInSet(hostLiteral, TELEMETRY_HOSTS); }
+// ⟨0.20⟩ The `Net` DESTINATION CLASS of a host literal (NET-DESTINATION-CLASS-DESIGN.md): `known-telemetry`
+// (curated), `known-partner` (config `net-partner` OR a model host — a declared-ish external API), else
+// `unknown-host` — the HONEST default (candor makes no claim; the security gate bites this). `partners` is a
+// per-project Set (config-declared). Never fabricated: a null/unresolved host is unknown-host. Mirrors java
+// Literals.netDestClass.
+export function netDestClass(hostLiteral, partners) {
+  if (isTelemetryHost(hostLiteral)) return "known-telemetry";
+  const host = normHost(hostLiteral);
+  const partnerMatch = partners && (partners.has(host) || [...partners].some((p) => host.endsWith("." + p)));
+  if (partnerMatch || isModelHost(hostLiteral)) return "known-partner";
+  return "unknown-host";
+}
+// ⟨0.20⟩ The closed `Net` destination-class vocabulary, for the `deny Net[<dest…>]` policy filter.
+export const NET_DEST_CLASSES = ["known-telemetry", "known-partner", "unknown-host"];
+// ⟨0.20⟩ The `Net` destination classes an fn reaches — the SINGLE derivation shared by the report's
+// `netClass` field (scan.mjs) and the gate (policy.mjs), so they can never drift: an exact host-literal
+// match (netDestClass) for the visible (transitive) hosts, plus the fail-closed `unknown-host` when the Net
+// surface is masked (`netIncomplete`) OR carries no visible host (a runtime endpoint). `hostsArr` is an
+// array; call only for an fn with Net. Returns sorted. Mirrors java Policy.netClassesOf / rust net_classes_of.
+export function netClassesOf(hostsArr, netIncomplete, partners) {
+  const classes = new Set(hostsArr.map((h) => netDestClass(h, partners)));
+  if (netIncomplete || hostsArr.length === 0) classes.add("unknown-host");
+  return [...classes].sort();
+}
 // Table-position identifiers in a SQL string literal (SPEC §2 `tables`). Mirrors the Rust
 // tables_in_sql exactly: must open with a statement keyword; FROM/JOIN/INTO anywhere,
 // statement-leading UPDATE/TRUNCATE, TABLE (skipping ONLY/IF NOT EXISTS); a FOR UPDATE locking

package/scan.mjs

@@ -26,11 +26,11 @@ 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, parseNetPartners, discoverConfigText, reasonClass } from "./policy.mjs";
 import { unverifiedHoleRule, ruleUpgrade } from "./query-core.mjs";
 import { printAgents } from "./contract.mjs";
 import { isTestPath, kappa, kappaKnows, commandHeadEffects, hostLiteral, tablesInSql,
-         modelHostEffects, isModelHost, isModelSdkPackage } from "./scan-core.mjs";
+         modelHostEffects, isModelHost, isModelSdkPackage, netClassesOf } from "./scan-core.mjs";
 import { emitSurface } from "./surface.mjs";
 
 const ENGINE_DIR = path.dirname(fileURLToPath(import.meta.url));
@@ -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.20";
 
 // --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 {
@@ -2510,6 +2563,9 @@ for (const m of ["hosts", "tables", "cmds", "paths", "blind", "incomplete"]) {
 }
 
 // ---- emit: the §2 envelope (effect-free items omitted) + the §2.2 sidecar (EVERY fn a key) --------
+// ⟨0.20⟩ Net destination-class partners from `.candor/config` — read ONCE here, used by the report's per-fn
+// `netClass` field (below) and the gate (deny Net[unknown-host]); the SAME set both surfaces resolve.
+const netPartners = parseNetPartners(discoverConfigText(target));
 const functions = [];
 for (const [name, rec] of fns) {
   const inf = [...inferred.get(name)].sort();
@@ -2533,6 +2589,10 @@ for (const [name, rec] of fns) {
   // entries carry `calls`); omitted when a fn has no outgoing edges to keep pure leaves lean.
   if (rec.edges.size) entry.calls = [...rec.edges].sort();
   if (inf.includes("Net") && rec.hosts.size) entry.hosts = [...rec.hosts].sort();
+  // ⟨0.20⟩ Net destination-class (NET-DESTINATION-CLASS-DESIGN.md): the classes present in this fn's
+  // transitive Net surface — exact host-literal match, fail-closed unknown-host on a masked surface (rec
+  // .incomplete has Net) OR a Net with no visible host. The class travels the call graph like the effect.
+  if (inf.includes("Net")) entry.netClass = netClassesOf([...rec.hosts], rec.incomplete.has("Net"), netPartners);
   if (inf.includes("Db") && rec.tables.size) entry.tables = [...rec.tables].sort();
   if (inf.includes("Exec") && rec.cmds.size) entry.cmds = [...rec.cmds].sort();
   if (inf.includes("Fs") && rec.paths.size) entry.paths = [...rec.paths].sort();
@@ -2620,6 +2680,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 +2880,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, netPartners));
   // 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.