candor-ts 0.4.5 → 0.5.0

package/query-core.mjs

@@ -0,0 +1,302 @@
+/**
+ * candor query core — the SPEC §3.1 read-only queries as PURE functions over a loaded report +
+ * callgraph sidecar. Shared by the MCP server (mcp.mjs) so the agent surface and the CLI compute
+ * the same answers. Shapes match the reference engines (candor-query / candor-java); a cross-check
+ * test (test.mjs) pins them against query.mjs and the Rust binary so this can't drift — the family's
+ * no-two-truths rule, enforced by test rather than (yet) by query.mjs importing this.
+ *
+ * Every function takes already-loaded data (fns = the report's `functions`; cg = the callgraph
+ * object name->callees) and RETURNS a plain object — no I/O, no process exit. The caller emits.
+ */
+import fs from "node:fs";
+import nodePath from "node:path";
+
+// 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.
+// This is the cross-engine premise: an agent queries a report from any language identically.
+function siblings(prefix, predicate) {
+  const dir = nodePath.dirname(prefix) || ".";
+  const base = nodePath.basename(prefix);
+  try {
+    return fs.readdirSync(dir).filter((f) => f.startsWith(base + ".") && f.endsWith(".json") && predicate(f))
+      .map((f) => nodePath.join(dir, f));
+  } catch { return []; }
+}
+// A sibling filename that is a real REPORT (not a callgraph sidecar, an encountered-crate ledger, or a
+// calibrated-coverage sidecar). Exported so `hasReport` (the MCP existence check) uses the SAME predicate
+// as the loader — else a prefix whose only sibling is `.encountered-*`/`.calibrated.json` passes the
+// existence check but loads ZERO functions → an authoritative-empty result (silent under-report; review find).
+export const isReport = (f) => !f.endsWith(".callgraph.json") && !f.includes(".encountered-") && !f.endsWith(".calibrated.json");
+
+// Defend the queries against a partial/old-engine/hand-edited report: the §2 required fields are
+// defaulted, and a WRONG-TYPE field is coerced — a non-array `inferred` (e.g. the string "Net") must
+// NOT survive, or `new Set("Net")` iterates characters into {N,e,t} (a fabricated effect set). Array
+// only when actually an array; else []. The §2 forward-compatibility posture applied to the consumer.
+function normFn(e) {
+  const arr = (v) => (Array.isArray(v) ? v : []);
+  return { ...e, inferred: arr(e.inferred), direct: arr(e.direct), calls: arr(e.calls) };
+}
+
+// Normalize a parsed report's `functions` into clean entries. A non-array `functions`, or an entry that
+// isn't an object with a STRING `fn`, is DISCLOSED and dropped — it would otherwise crash a query
+// (`map()` deref on a fn-less entry) or fabricate a junk entity (a primitive normalized into `{0:'t',…}`).
+// The never-crash / never-fabricate posture for malformed input from any engine's report.
+function normFns(parsed, source) {
+  const raw = parsed && typeof parsed === "object" && parsed.functions !== undefined ? parsed.functions : parsed;
+  if (!Array.isArray(raw)) {
+    console.error(`candor-ts: report ${source} has no functions array — OMITTED from this query (malformed report)`);
+    return [];
+  }
+  const out = [];
+  for (const e of raw) {
+    if (e && typeof e === "object" && typeof e.fn === "string") out.push(normFn(e));
+    else console.error(`candor-ts: report ${source} has a malformed entry (no string \`fn\`) — skipped`);
+  }
+  return out;
+}
+
+export function loadReport(prefix) {
+  if (fs.existsSync(`${prefix}.json`)) {
+    // The PRIMARY report parse must DISCLOSE-and-tolerate like the sibling path — a bare JSON.parse here
+    // threw an uncaught stack trace on the CLI for a corrupt `<prefix>.json` (asymmetric with siblings).
+    try { return normFns(JSON.parse(fs.readFileSync(`${prefix}.json`, "utf8")), `${prefix}.json`); }
+    catch { console.error(`candor-ts: report ${prefix}.json failed to parse — OMITTED (corrupt or mid-write); re-run the scan`); return []; }
+  }
+  // No exact <prefix>.json — merge the multi-report siblings (the Rust/workspace form).
+  const fns = [];
+  for (const f of siblings(prefix, isReport)) {
+    // DISCLOSE a malformed sibling — never silently drop it (a vanished report reads as "no effect").
+    try { fns.push(...normFns(JSON.parse(fs.readFileSync(f, "utf8")), f)); }
+    catch { console.error(`candor-ts: report ${f} failed to parse — its functions are OMITTED from this query (corrupt or mid-write); re-run the scan`); }
+  }
+  return fns;
+}
+export function loadCallgraph(prefix) {
+  // A `null`/non-object parse (a `null` callgraph, an array, a number) must NOT reach Object.entries —
+  // it throws "Cannot convert null to object". Coerce anything but a plain object to {} (an empty
+  // graph), the never-crash direction.
+  const norm = (cg) => (cg && typeof cg === "object" && !Array.isArray(cg))
+    ? Object.fromEntries(Object.entries(cg).map(([k, v]) => [k, Array.isArray(v) ? v : []]))
+    : {};
+  if (fs.existsSync(`${prefix}.callgraph.json`)) {
+    // The PRIMARY callgraph parse must DISCLOSE-and-tolerate like the sibling path below and like
+    // loadReport — a bare JSON.parse here threw an uncaught stack trace on the CLI for a corrupt or
+    // `null` `<prefix>.callgraph.json` (asymmetric with siblings). Tolerate (empty graph) + disclose.
+    try { return norm(JSON.parse(fs.readFileSync(`${prefix}.callgraph.json`, "utf8"))); }
+    catch { console.error(`candor-ts: callgraph ${prefix}.callgraph.json failed to parse — its edges are OMITTED from this query (corrupt or mid-write); re-run the scan`); return {}; }
+  }
+  const cg = {};
+  for (const f of siblings(prefix, (x) => x.endsWith(".callgraph.json"))) {
+    try { Object.assign(cg, JSON.parse(fs.readFileSync(f, "utf8"))); }
+    catch { console.error(`candor-ts: callgraph ${f} failed to parse — its edges are OMITTED from this query (corrupt or mid-write); re-run the scan`); }
+  }
+  return norm(cg);
+}
+
+// ---- the §3.1 match ladder: exact > segment-suffix > substring ------------------------------------
+function matchTier(name, q) {
+  if (name === q) return 3;
+  if (name.endsWith(q) && /[.$#]$/.test(name.slice(0, name.length - q.length))) return 2;
+  if (name.includes(q)) return 1;
+  return 0;
+}
+export function matches(names, q) {
+  const best = Math.max(0, ...names.map((n) => matchTier(n, q)));
+  return best === 0 ? [] : names.filter((n) => matchTier(n, q) >= best);
+}
+
+function reverseGraph(cg) {
+  const rev = new Map();
+  for (const [caller, callees] of Object.entries(cg))
+    for (const c of callees) {
+      if (!rev.has(c)) rev.set(c, []);
+      rev.get(c).push(caller);
+    }
+  return rev;
+}
+
+// what effects a function carries (its row), and a name->row index for loc/direct lookups.
+function indexFns(fns) {
+  return new Map(fns.map((e) => [e.fn, e]));
+}
+
+export function show(fns, q) {
+  const hit = new Set(matches(fns.map((e) => e.fn), q));
+  return fns.filter((e) => hit.has(e.fn)).map((e) => {
+    const o = { fn: e.fn, inferred: e.inferred, direct: e.direct };
+    // Literal Fs paths live under the report's `paths` key (scan emits `entry.paths`), NOT `fs` — the
+    // old `e.fs` read a field this engine never writes, so `show`/`candor_show` silently dropped every
+    // file path (the MCP tool's own doc promises "hosts/cmds/paths/tables"). Surface it as `paths`, the
+    // report's key, mirroring hosts/cmds/tables below.
+    if (e.paths?.length) o.paths = e.paths;
+    if (e.hosts?.length) o.hosts = e.hosts;
+    if (e.cmds?.length) o.cmds = e.cmds;
+    if (e.tables?.length) o.tables = e.tables;
+    o.unresolved = e.unresolved;
+    return o;
+  });
+}
+
+export function where(fns, eff) {
+  return {
+    effect: eff,
+    directly: fns.filter((e) => e.direct.includes(eff)).map((e) => e.fn).sort(),
+    inherited: fns.filter((e) => e.inferred.includes(eff) && !e.direct.includes(eff)).map((e) => e.fn).sort(),
+  };
+}
+
+export function callers(cg, q) {
+  const targets = matches(Object.keys(cg), q);
+  const rev = reverseGraph(cg);
+  const direct = new Set(), transitive = new Set();
+  for (const t of targets) for (const c of rev.get(t) ?? []) direct.add(c);
+  const queue = [...targets];
+  while (queue.length) {
+    const n = queue.pop();
+    for (const c of rev.get(n) ?? []) if (!transitive.has(c) && !targets.includes(c)) { transitive.add(c); queue.push(c); }
+  }
+  return { of: targets, direct: [...direct].sort(), transitive: [...transitive].sort() };
+}
+
+export function map(fns) {
+  const mods = {};
+  for (const e of fns) {
+    const mod = e.fn.includes(".") ? e.fn.split(".").slice(0, -1).join(".") : "(root)";
+    const m = (mods[mod] ??= { effects: new Set(), functions: 0 });
+    for (const x of e.inferred) m.effects.add(x);
+    m.functions += 1;
+  }
+  return Object.fromEntries(Object.entries(mods).sort()
+    .map(([k, v]) => [k, { effects: [...v.effects].sort(), functions: v.functions }]));
+}
+
+export function reachable(fns) {
+  const roots = fns.filter((e) => e.entryPoint);
+  const byEff = {};
+  for (const e of roots) for (const x of e.inferred) (byEff[x] ??= []).push(e.fn);
+  return {
+    entryPoints: roots.length,
+    effects: Object.fromEntries(Object.entries(byEff).sort()
+      .map(([k, v]) => [k, { count: v.length, via: v.sort() }])),
+  };
+}
+
+// impact: the BACKWARD blast radius — every effectful fn that transitively calls the target, and
+// which ENTRY POINTS are downstream. Matches candor-query's {fn, affectedCount, entryPoints} and adds
+// the `affected` list (a forward-compatible extension: an agent wants the names, not just a count).
+export function impact(fns, cg, q) {
+  const targets = matches(Object.keys(cg), q);
+  const rev = reverseGraph(cg);
+  const idx = indexFns(fns);
+  const effectful = new Set(fns.map((e) => e.fn)); // the report lists only effect-carrying units
+  const entrySet = new Set(fns.filter((e) => e.entryPoint).map((e) => e.fn));
+  const reached = new Set();
+  const queue = [...targets];
+  while (queue.length) {
+    const n = queue.pop();
+    for (const c of rev.get(n) ?? []) if (!reached.has(c) && !targets.includes(c)) { reached.add(c); queue.push(c); }
+  }
+  const tgt = targets[0];
+  const affected = [...reached].filter((n) => effectful.has(n)).sort();
+  const rootNames = [];
+  if (idx.get(tgt)?.entryPoint) rootNames.push(tgt); // the target itself, if a runtime root
+  rootNames.push(...[...reached].filter((n) => entrySet.has(n)).sort());
+  const entryPoints = rootNames.map((n) => ({ fn: n, inferred: idx.get(n)?.inferred ?? [] }));
+  return { fn: tgt ?? q, affectedCount: affected.length, affected, entryPoints };
+}
+
+// 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) {
+  const idx = indexFns(fns);
+  const targets = matches(Object.keys(cg), fnQ);
+  const start = targets[0];
+  const isSource = (n) => idx.get(n)?.direct?.includes(eff);
+  if (start === undefined) return { effect: eff, fn: fnQ, path: [] };
+  // BFS, tracking predecessor for path reconstruction.
+  const prev = new Map([[start, null]]);
+  const queue = [start];
+  let found = isSource(start) ? start : null;
+  while (queue.length && found === null) {
+    const n = queue.shift();
+    for (const c of cg[n] ?? []) {
+      if (prev.has(c)) continue;
+      prev.set(c, n);
+      if (isSource(c)) { found = c; break; }
+      queue.push(c);
+    }
+  }
+  if (found === null) return { effect: eff, fn: fnQ, path: [] }; // honest: no local source on a path
+  const chain = [];
+  for (let n = found; n !== null; n = prev.get(n)) chain.unshift(n);
+  return {
+    effect: eff,
+    fn: start,
+    path: chain.map((n) => ({ fn: n, loc: idx.get(n)?.loc ?? "", source: n === found })),
+  };
+}
+
+// diff: the per-unit effect delta between two reports (cur vs base) — {changes:[{fn, gained, lost}]}.
+// The same shape query.mjs emits; the watcher uses it to tell an agent what its edit changed.
+// Effects keyed by fn name, UNIONED across rows that share a name. A plain `new Map(fns.map(...))`
+// keeps only the LAST same-named row — so when the multi-report loader merges workspace members that
+// share a short fn name, one member's effects silently vanish from diff/gains → a SUPPLY-CHAIN MISS
+// (gains fails to flag a gained Net). Unioning is the safe direction (never drops an effect).
+function effectsByFn(fns) {
+  const m = new Map();
+  for (const e of fns) {
+    const s = m.get(e.fn) ?? new Set();
+    for (const x of (Array.isArray(e.inferred) ? e.inferred : [])) s.add(x);  // a string "Net" would iter chars
+    m.set(e.fn, s);
+  }
+  return m;
+}
+
+export function diff(curFns, baseFns) {
+  const cur = effectsByFn(curFns);
+  const base = effectsByFn(baseFns);
+  const changes = [];
+  for (const fn of new Set([...cur.keys(), ...base.keys()])) {
+    const c = cur.get(fn) ?? new Set(), b = base.get(fn) ?? new Set();
+    const gained = [...c].filter((e) => !b.has(e)).sort();
+    const lost = [...b].filter((e) => !c.has(e)).sort();
+    if (gained.length || lost.length) changes.push({ fn, gained, lost });
+  }
+  changes.sort((a, b) => a.fn.localeCompare(b.fn));
+  return { changes };
+}
+
+// gains: the package-level SUPPLY-CHAIN alarm (spec §5.1) — the UNION of effects the surface gained
+// between two reports (base → cur), with per-function detail. A dependency that grows a Net/Exec reach
+// between releases. Same shape as candor-query's `gains --json`. Built on diff so it can't drift.
+export function gains(curFns, baseFns) {
+  const gained = new Set(), byFunction = [];
+  for (const c of diff(curFns, baseFns).changes) {
+    for (const e of c.gained) { gained.add(e); byFunction.push({ fn: c.fn, effect: e }); }
+  }
+  return { gained: [...gained].sort(), byFunction };
+}
+
+// whatif: hypothetically add `eff` to `target` and report the blast radius + any policy violations.
+// `policyParsed` is an already-parsed policy object (or null); kept I/O-free for the core.
+export function whatif(cg, target, eff, policyParsed, scopeMatches) {
+  const targets = matches(Object.keys(cg), target);
+  if (targets.length === 0) return null; // caller decides how to surface "no such fn"
+  const rev = reverseGraph(cg);
+  const affected = new Set(targets);
+  const queue = [...targets];
+  while (queue.length) {
+    const n = queue.pop();
+    for (const c of rev.get(n) ?? []) if (!affected.has(c)) { affected.add(c); queue.push(c); }
+  }
+  const violations = [];
+  if (policyParsed) {
+    for (const r of policyParsed.deny) {
+      if (r.effects.length && !r.effects.includes(eff)) continue; // pure ([]) forbids ANY effect
+      for (const fn of affected)
+        if (!r.scope || scopeMatches(fn, r.scope))
+          violations.push({ fn, rule: `deny ${r.effects.join(" ") || "(pure)"} ${r.scope}`.trim() });
+    }
+  }
+  return { of: targets, effect: eff, affected: [...affected].sort(), violations, ok: violations.length === 0 };
+}

package/query.mjs

@@ -20,26 +20,13 @@ import fs from "node:fs";
 
 import { parsePolicy, scopeMatches } from "./policy.mjs";
 import { printAgents } from "./contract.mjs";
-
-// ---- the §3.1 match ladder: exact > segment-suffix > substring ------------------------------------
-function matchTier(name, q) {
-  if (name === q) return 3;
-  if (name.endsWith(q) && /[.$]$/.test(name.slice(0, name.length - q.length))) return 2;
-  if (name.includes(q)) return 1;
-  return 0;
-}
-function matches(names, q) {
-  const best = Math.max(0, ...names.map((n) => matchTier(n, q)));
-  return best === 0 ? [] : names.filter((n) => matchTier(n, q) >= best);
-}
-
-function loadReport(prefix) {
-  const d = JSON.parse(fs.readFileSync(`${prefix}.json`, "utf8"));
-  return d.functions ?? d;
-}
-function loadCallgraph(prefix) {
-  return JSON.parse(fs.readFileSync(`${prefix}.callgraph.json`, "utf8"));
-}
+// ONE source of truth for loading + name-matching — query.mjs kept DRIFTED local copies that didn't
+// merge sibling reports, didn't tolerate a corrupt report (bare JSON.parse → uncaught crash), and used
+// 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,
+         loadReport, loadCallgraph, matches } from "./query-core.mjs";
 const emit = (v) => console.log(JSON.stringify(v, null, 1));
 
 const [, , cmd, ...args] = process.argv;
@@ -53,18 +40,11 @@ switch (cmd) {
     break;
   }
   case "show": {
+    // Was a hand-copy of query-core's show that had DRIFTED — it read the wrong Fs key (`e.fs`, never
+    // written; the paths silently vanished) and dropped Exec `cmds` entirely. Call the shared show so
+    // the CLI and the MCP `candor_show` are one implementation that cannot diverge again.
     const [prefix, q] = args;
-    const fns = loadReport(prefix);
-    const hit = new Set(matches(fns.map((e) => e.fn), q));
-    const out = fns.filter((e) => hit.has(e.fn)).map((e) => {
-      const o = { fn: e.fn, inferred: e.inferred, direct: e.direct };
-      if (e.fs?.length) o.fs = e.fs;
-      if (e.hosts?.length) o.hosts = e.hosts;
-      if (e.tables?.length) o.tables = e.tables;
-      o.unresolved = e.unresolved;
-      return o;
-    });
-    emit(out);
+    emit(coreShow(loadReport(prefix), q));
     break;
   }
   case "where": {
@@ -125,6 +105,7 @@ switch (cmd) {
     changes.sort((a, b) => a.fn.localeCompare(b.fn));
     emit({ changes });
     process.exit(changes.some((c) => c.gained.length) ? 1 : 0);
+    break; // unreachable (process.exit), but eslint can't prove it — defends against fallthrough
   }
   case "reachable": {
     // what the app DOES at runtime: effects unioned over the entry points (SPEC §3.1; same JSON
@@ -139,6 +120,25 @@ switch (cmd) {
              .map(([k, v]) => [k, { count: v.length, via: v.sort() }])) });
     break;
   }
+  case "impact": {
+    // blast radius (backward dual of reachable) — reuses the shared query-core, the same logic the
+    // MCP server serves. SPEC §3.1: {fn, affectedCount, affected, entryPoints:[{fn,inferred}]}.
+    const [prefix, q] = args;
+    emit(coreImpact(loadReport(prefix), loadCallgraph(prefix), q));
+    break;
+  }
+  case "gains": {
+    // the supply-chain alarm (SPEC §5.1): {gained:[Effect], byFunction:[{fn,effect}]} — what the
+    // surface gained between two reports (base → cur), the cross-engine machine-readable form.
+    const [curPrefix, basePrefix] = args;
+    emit(coreGains(loadReport(curPrefix), loadReport(basePrefix)));
+    break;
+  }
+  case "path": {
+    const [prefix, fn, eff] = args;
+    emit(corePath(loadReport(prefix), loadCallgraph(prefix), fn, eff));
+    break;
+  }
   case "whatif": {
     const [prefix, target, eff, maybePolicy] = args;
     const cg = loadCallgraph(prefix);
@@ -169,6 +169,7 @@ switch (cmd) {
     }
     emit({ of: targets, effect: eff, affected: [...affected].sort(), violations, ok: violations.length === 0 });
     process.exit(violations.length ? 1 : 0);
+    break; // unreachable (process.exit), but eslint can't prove it — defends against fallthrough
   }
   default:
     console.error("usage: node query.mjs <parsepolicy|show|where|callers|map|whatif> …");

package/scan-core.mjs

@@ -0,0 +1,161 @@
+/**
+ * scan-core — the PURE classifier + literal-extraction leaves of scan.mjs, factored out so they can be
+ * unit-tested directly (scan.mjs proper is the TS-compiler-driven walk; these take plain strings). No
+ * TypeScript-AST dependency, no I/O, no scan state: the κ rules table + its two readers, the §6.2
+ * Exec-head refinement, the bare host-literal matcher, the SPEC §2 SQL-table extraction, and the
+ * test-path predicate. scan.mjs imports them; the behavior is identical (this is a move, not a rewrite).
+ */
+
+// A source path that is test/spec/dependency code, not the package's own production surface.
+export function isTestPath(p) {
+  return /(^|\/)(node_modules|__tests__|tests?|spec)(\/|$)/.test(p) || /\.(test|spec)\.[mc]?tsx?$/.test(p);
+}
+
+// ---- κ — the curated classifier (CLASSIFIER §2: the dispatch/execution boundary, not builders) ----
+// Node builtins + a curated npm tier (the same under-report-and-say-so posture as the crate table:
+// an unlisted package contributes nothing — never a guess).
+// One rules TABLE, two readers: kappa() classifies a call; kappaKnows() answers "is this package
+// curated at all?" for the coverage ledger (a κ-known package whose given call is pure — a TypeORM
+// builder — is covered, not a blind spot). A single source so the two can never drift.
+// [module-name regex, member regex (null = any member), effect]
+// The member token a rule matches against is the resolved declaration's name, EXCEPT a constructor
+// call (`new X()`), whose synthesized token is "new" (its decl `name` is empty — see CLASSIFY). This
+// lets a rule keep the effect on the module's function/verb surface while exempting inert CONSTRUCTION.
+export const KAPPA_RULES = [
+  [/^(node:)?fs(\/promises)?$/, null, "Fs"],
+  // The net cluster (net/dgram/tls/http/http2/https) is I/O on its FUNCTION/verb surface
+  // (request/get/connect/createConnection/createServer/createSocket/listen…), but inert on
+  // CONSTRUCTION: `new http.Agent()` is a connection-pool config object, `new http.Server()` /
+  // `new net.Socket()` open nothing until a later `.listen()`/`.connect()`/request uses them — no
+  // syscall, no fd. So Net for every member EXCEPT a constructor (token "new"); construction is pure.
+  // Conservative by the cardinal rule: any NON-constructor member — listed verb or not — keeps Net,
+  // so an unlisted effectful function can never under-report; only proven-inert construction is freed.
+  // (The pure CONSTANTS http.STATUS_CODES/METHODS/maxHeaderSize and the https.globalAgent accessor are
+  // property reads, not calls — they never reach κ and are already pure.)
+  // Also exempt node:net's PURE STRING VALIDATORS isIP/isIPv4/isIPv6: they parse a string and return
+  // 0/4/6 (or a boolean) with no socket, no fd, no syscall — pure functions. The whole-module Net rule
+  // once fabricated Net onto them; a real-world sweep on node-fetch caught it (its trustworthy URL
+  // predicates isOriginPotentiallyTrustworthy/isUrlPotentiallyTrustworthy call isIP() and inherited a
+  // FABRICATED Net — the cardinal sin — purely from this classification, with no local Net edge). Only
+  // these three named validators are freed; every genuine verb (connect/createConnection/createServer…)
+  // stays Net (the matcher excludes ONLY new + the three validators, nothing else).
+  [/^(node:)?(net|dgram|tls|http2?|https)$/, /^(?!(new|isIP|isIPv4|isIPv6)$)/, "Net"],
+  [/^(node:)?child_process$/, null, "Exec"],
+  [/^(node:)?sqlite$/, null, "Db"],
+  // the curated npm tier
+  [/^(axios|got|node-fetch|undici|ws|socket\.io(-client)?|nodemailer)$/, null, "Net"],
+  [/^(pg|mysql2?|mongodb|ioredis|redis|sqlite3|better-sqlite3|knex)$/, null, "Db"],
+  [/^(execa|cross-spawn|shelljs)$/, null, "Exec"],
+  [/^(fs-extra|graceful-fs|rimraf|glob|chokidar)$/, null, "Fs"],
+  [/^dotenv$/, null, "Env"],
+  [/^(winston|pino|bunyan|npmlog)$/, null, "Log"],
+  // entropy: node:crypto's random surface + the password-hashing libs (salted -> Rand). Found by
+  // the CTA dogfood on a Nest app: argon2.hash came out SILENTLY PURE (the curated-kappa caveat
+  // landing on exactly the call a security review cares about).
+  [/^(node:)?crypto$/, /^random/, "Rand"],
+  [/^(argon2|bcrypt|bcryptjs)$/, null, "Rand"],
+  // The ORM tier — VERB-PRECISE (the CLASSIFIER discipline: tag the execution boundary, not
+  // builders; `createQueryBuilder` is pure, its `getMany`/`execute` is the I/O). Found on the
+  // first framework-APP scan: a TypeORM/Nest application — Db-heavy by construction — read zero
+  // Db because the ORM resolved into an unlisted package (the JVM's Spring-Data lesson, replayed).
+  [/^(typeorm|@nestjs\/typeorm)$/,
+   /^(find|save|remove|softRemove|recover|insert|update|upsert|delete|restore|count|exist|sum|average|minimum|maximum|query|clear|increment|decrement|getMany|getOne|getOneOrFail|getRawMany|getRawOne|getCount|getExists|execute|stream|transaction)/,
+   "Db"],
+  [/^(@prisma\/client|\.prisma|\.prisma\/client)$/,
+   /^(\$?(queryRaw|executeRaw|transaction)|find(Many|Unique|First)|create|createMany|update|updateMany|upsert|delete|deleteMany|aggregate|count|groupBy)/,
+   "Db"],
+  [/^mongoose$/,
+   /^(find|save|create|insertMany|updateOne|updateMany|replaceOne|deleteOne|deleteMany|aggregate|countDocuments|estimatedDocumentCount|distinct|exec|bulkWrite)/,
+   "Db"],
+  [/^(sequelize|drizzle-orm)$/,
+   /^(find|create|update|destroy|upsert|count|max|min|sum|query|select|insert|delete|execute|transaction)/,
+   "Db"],
+  // Nest's HttpService wraps axios — the request verbs are Net.
+  [/^@nestjs\/axios$/, /^(get|post|put|patch|delete|head|request)$/, "Net"],
+];
+export function kappa(moduleName, member) {
+  for (const [mre, vre, eff] of KAPPA_RULES) {
+    if (mre.test(moduleName) && (!vre || vre.test(member))) return eff;
+  }
+  return null;
+}
+// Packages REVIEWED and ratified effect-free at the call boundary (decorator/metadata plumbing,
+// pure computation, operator algebras whose side effects live in visible user callbacks). This is
+// the ledger's triage outlet: an unlisted package either earns KAPPA_RULES entries or lands here —
+// never silently. NOT for anything that mints entropy (uuid), reads clocks, or signs with RSA-PSS
+// (jsonwebtoken stays unlisted on purpose).
+export const KAPPA_PURE = new Set([
+  "@nestjs/common", "@nestjs/core", "@nestjs/swagger", "@nestjs/platform-express",
+  "class-validator", "class-transformer", "reflect-metadata",
+  "rxjs", "zod", "lodash", "ramda", "date-fns",
+]);
+export function kappaKnows(moduleName) {
+  return KAPPA_PURE.has(moduleName) || KAPPA_RULES.some(([mre]) => mre.test(moduleName));
+}
+
+// Refine the Exec cliff (spec §4 ⟨0.5⟩): the effects a literal, statically-known subprocess head
+// implies, matched by basename. ADDED to a caller that already carries Exec (a subprocess is still
+// spawned — Exec is never dropped); an unrecognised head returns [] and keeps the bare cliff (never
+// guess). A candor engine reads Fs/Env only — spec §7 item 12 (the analyzer self-boundary) guarantees
+// it, so that case is spec-supplied. Only UNAMBIGUOUS single-effect tools belong here: a multi-modal
+// head (git status local vs git push Net; rsync local vs remote; make/npm run project code) would
+// fabricate the effect for its common case. The reference engines share this table verbatim.
+export function commandHeadEffects(cmd) {
+  const base = cmd.trim().split(/\s+/)[0].split(/[/\\]/).pop();
+  if (["curl", "wget", "http", "ssh", "scp", "sftp", "ftp", "telnet"].includes(base)) return ["Net"];
+  if (["psql", "mysql", "sqlite3", "mongosh", "mongo", "redis-cli", "cqlsh", "influx"].includes(base)) return ["Db"];
+  if (["candor", "candor-run.sh", "candor-scan", "candor-query", "candor-java",
+       "candor-classify", "candor-report", "cargo-candor"].includes(base)) return ["Env", "Fs"];
+  return [];
+}
+// host[:port] from an address/URL literal; non-address strings yield nothing (never fabricate).
+export function hostLiteral(s) {
+  const m = s.match(/^[a-z][a-z0-9+.-]*:\/\/([^/]+)/i);   // scheme://host[:port]/…
+  if (m) return m[1].replace(/^.*@/, "");
+  if (/^[a-z0-9._-]+(:\d+)?$/i.test(s) && s.includes(".")) return s; // bare host[.tld][:port]
+  return null;
+}
+// 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
+// clause yields nothing. Conservative in the fabrication direction.
+export function tablesInSql(sql) {
+  const stmt = new Set(["select","insert","update","delete","create","drop","alter","truncate","merge","replace","with"]);
+  const skip = new Set(["only","if","not","exists","table"]);
+  const stop = new Set(["select","set","where","values","on","using","group","order","by","limit",
+    "returning","as","inner","outer","left","right","cross","lateral","natural","union","all",
+    "distinct","case","when","null","default","skip","nowait","of","from","join","into","update",
+    "delete","insert"]);
+  // `,` survives as its OWN token: it lets `FROM t1, t2` continue the table list without
+  // fabricating from other comma-ridden positions (column lists, ON clauses).
+  const toks = sql.toLowerCase().replace(/[();]/g, " ").replace(/,/g, " , ").trim().split(/\s+/);
+  if (!toks.length || !stmt.has(toks[0])) return [];
+  const out = [];
+  const ident = (raw) => {
+    const t = raw.replace(/^["'`]+|["'`]+$/g, "");
+    if (!t || stop.has(t) || !/^[a-z_][a-z0-9_.$"`]*$/.test(t)) return null;
+    return t.replace(/["`]/g, "");
+  };
+  for (let i = 0; i < toks.length; i++) {
+    const tablePos = ["from","join","into","table"].includes(toks[i])
+      || ((toks[i] === "update" || toks[i] === "truncate") && i === 0);
+    if (!tablePos) continue;
+    let j = i + 1;
+    while (j < toks.length && skip.has(toks[j])) j++;
+    if (j >= toks.length) continue;
+    const first = ident(toks[j]);
+    if (first === null) continue;
+    if (!out.includes(first)) out.push(first);
+    // Comma-ADJACENT continuation only: `FROM t1, t2, t3` takes all three, while an alias breaks
+    // the chain (`FROM t1 a, t2` keeps just t1 — an under-report, never a guess: skipping an alias
+    // to chase the comma would fabricate tables out of `INSERT INTO t (a, b)`'s column list, whose
+    // parens are spaces by the time we tokenize).
+    while (j + 2 < toks.length && toks[j + 1] === ",") {
+      const more = ident(toks[j + 2]);
+      if (more === null) break;
+      if (!out.includes(more)) out.push(more);
+      j += 2;
+    }
+  }
+  return out;
+}