candor-ts 0.19.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.19)."*
+> 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.19" }, 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.19: 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.19.0",
-  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.19)",
+  "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,6 +4,8 @@
  * 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
@@ -52,7 +54,23 @@ export function parsePolicy(text, aliases = null) {
       // 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)) {
+        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");
@@ -70,18 +88,21 @@ export function parsePolicy(text, aliases = null) {
         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; }
       // `*` (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, raw: line }); // dedup: a set, like rust/java
+      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] ?? "", unknownClasses: [], 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; }
@@ -163,13 +184,18 @@ 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" };
-  // §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 });
+  // §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
@@ -209,10 +235,22 @@ export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()
         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;
-        push("AS-EFF-006", f.fn, kept, `\`${f.fn}\` performs { ${kept.join(", ")} }, forbidden by policy: \`${r.raw}\``, rc);
+        // ⟨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) {
@@ -327,3 +365,21 @@ export function parseUnknownAliases(configText) {
   }
   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

@@ -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.19";
+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"],
@@ -656,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": {
@@ -894,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, parseUnknownAliases, discoverConfigText, reasonClass } 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.19";
+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
@@ -2563,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();
@@ -2586,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();
@@ -2875,7 +2882,7 @@ if (policyPath !== null) {
   for (const [name, rec] of fns) if (rec.incomplete.size) incompleteMap.set(name, rec.incomplete);
   // ⟨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));
+  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).