candor-ts 0.11.0 → 0.13.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.11)."*
+> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.13)."*
 > 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`.
 >
@@ -86,7 +86,7 @@ downgraded to `Unknown` rather than silently trusted (spec §2.1). Caveat: a typ
 ## Query it (same names/shapes as the Rust and JVM engines — candor-spec §3.1)
 
 ```sh
-Q() { npx -y candor-ts-query "$@"; }; P=".candor/report"   # a function — works in bash AND zsh
+Q() { npx -y -p candor-ts candor-ts-query "$@"; }; P=".candor/report"   # a function — works in bash AND zsh
 Q show     $P <fn-query> 1          # a function's effects (+ hosts/tables when visible)
 Q where    $P <Effect>   1          # {effect, directly, inherited}
 Q impact   $P <fn-query>            # THE BLAST RADIUS: {fn, affectedCount, affected, entryPoints}
@@ -110,9 +110,14 @@ Q parsepolicy <policy-file>         # the canonical §6.2 parse (what the gate w
 And as an MCP server, so an agent pulls these as tools instead of shelling out:
 `CANDOR_REPORT=$P npx -y candor-ts-mcp` (tools `candor_impact`/`candor_reachable`/`candor_where`/…,
 plus `candor_gate`/`candor_whatif`/`candor_fix` — a given-but-unreadable `policy` is a loud tool
-error, never a clean verdict). `npx -y candor-ts-watch <dir>` keeps the report fresh as you edit (and
+error, never a clean verdict — and `candor_activity`: what the edit-time gate CAUGHT, measured from
+`.candor/activity.jsonl` — edits checked, verdicts, violations by AS-EFF code, effects introduced,
+largest blast radius, deepest propagation — so you can self-inspect the loop without shelling out;
+a missing log is an empty result, not an error). `npx -y candor-ts-watch <dir>` keeps the report fresh as you edit (and
 reports the edit-delta); `candor-lsp` serves the same report as CodeLens/hover/diagnostics in any LSP
-editor, plus two code actions (plain LSP — helix/neovim/VS Code/JetBrains-via-LSP4IJ all get them
+editor (and TAILS `.candor/activity.jsonl`: a new blocked gate record pushes the delta — gained
+effects, blast radius, deepest propagation, the AS-EFF cause — as a showMessage + a transient
+diagnostic on the edited files, cleared by the next clean record; `CANDOR_LSP_ACTIVITY=off` disables), plus two code actions (plain LSP — helix/neovim/VS Code/JetBrains-via-LSP4IJ all get them
 without client code): the pre-edit whatif (`candor: what if <fn> performed <E>?` → the `candor.whatif`
 command) and, when the cursor sits in a function that actually violates the policy, the boundary FIX
 (`candor fix: hoist <E> out of <fn>` → the `candor.fix` command: where the effect belongs + the hoist

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.11" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
+| `{ candor: { version, toolchain, spec: "0.13" }, 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.11.x, speaking candor-spec 0.11: the analysis core, the gate (`--policy` / `--gate-json` /
+0.13.x, speaking candor-spec 0.13: 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/lsp.mjs

@@ -43,7 +43,7 @@
 import fs from "node:fs";
 import { createRequire } from "node:module";
 import nodePath from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import * as Q from "./query-core.mjs";
 import { discoverConfigPolicy, evaluatePolicy, parsePolicy, scopeMatches } from "./policy.mjs";
 
@@ -58,6 +58,118 @@ let reportPrefix = process.env.CANDOR_REPORT || process.argv[2] || null;
 
 const hasReport = Q.hasReport; // single-sourced with the loader predicate (query-core) — see mcp.mjs
 
+// ---- the activity push (AGENT-SURFACE-DESIGN.md P2) --------------------------------------------------
+// The Stop hook / standalone reviews append to .candor/activity.jsonl (lib-candor-summary.sh's pinned
+// record shape); the LSP tails it and surfaces each new BLOCKED record in-editor — the same payload the
+// hook shows the agent, pushed to the human. This is the LSP's ONE watcher (everything else stays
+// re-read-per-request): a small stat poll, unref'd so it never holds the process open, off-switchable
+// (CANDOR_LSP_ACTIVITY=off). Only records appended AFTER startup push (no history replay); a SHRUNKEN
+// log (the writer's cap trim-rewrite, or a rotation) skips to its end — never replays; a partial
+// trailing line waits for its newline; corrupt lines are skipped.
+let activityLog = null, activityOffset = 0, activityTimer = null;
+// The activity gate overlay has its OWN store, SEPARATE from the whatif/fix `transient` map: the two
+// are set by different actors (the tailer vs the client's executeCommand) and clear on different events
+// (next clean record vs the file's next didOpen/didSave/didChange) — sharing one map let a blocked
+// record clobber a live whatif overlay, and a clean record delete an unrelated whatif set afterwards.
+// Keys are canonicalDocKey() paths, NOT uri strings: the setter's path is server-computed while the
+// clearer's comes from the client's uri, and the two encodings diverge (Windows drive-case/%3A,
+// symlinked workspaces) — a string-keyed overlay wedged, uncleanable by any didOpen/didSave.
+const activityTransient = new Map();  // canonical doc key -> Diagnostic[] (the gate overlay)
+const activityOverlaid = new Set();   // canonical doc keys carrying a gate overlay — cleared on the next clean record
+// One canonical key for the activity overlay maps: the RESOLVED filesystem path — realpath when the
+// file exists (symlinked workspaces: /var vs /private/var), case-folded on win32 (drive-letter case).
+// Both the server-computed side (activity records' `edited` paths) and the client side (didOpen/
+// didSave uris, via fileURLToPath) funnel through this, so an encoding divergence cannot wedge the
+// overlay. The whatif/fix `transient` map deliberately does NOT get this treatment: its keys are only
+// ever CLIENT-supplied uris on both sides (codeAction arguments echo the client's own uri back into
+// executeCommand, and the clear reads the same client field), so set and clear already agree
+// byte-for-byte — canonicalizing there would be motion without a divergence to fix.
+function canonicalDocKey(p) {
+  let abs = nodePath.resolve(p);
+  try { abs = fs.realpathSync.native(abs); } catch { /* not on disk (yet) — resolve() is the best we have */ }
+  return process.platform === "win32" ? abs.toLowerCase() : abs;
+}
+function startActivityWatch() {
+  if ((process.env.CANDOR_LSP_ACTIVITY || "").toLowerCase() === "off") return;
+  const dir = rootPath ? nodePath.join(rootPath, ".candor")
+            : reportPrefix ? nodePath.dirname(reportPrefix) : null;
+  if (!dir) return;
+  activityLog = nodePath.join(dir, "activity.jsonl");
+  try { activityOffset = fs.statSync(activityLog).size; } catch { activityOffset = 0; }
+  const ms = Math.max(50, parseInt(process.env.CANDOR_LSP_ACTIVITY_POLL_MS || "2000", 10) || 2000);
+  activityTimer = setInterval(pollActivity, ms);
+  activityTimer.unref();
+}
+function pollActivity() {
+  let size;
+  try { size = fs.statSync(activityLog).size; } catch { return; }   // absent — keep waiting
+  if (size < activityOffset) {
+    // Shrunk — NOT an exceptional rotation: the writer (lib-candor-summary.sh candor_log_activity)
+    // rewrites the log via tail+mv on EVERY append once past its line cap, so past that point every
+    // poll sees a smaller file. Restarting the tail at 0 replayed the whole trimmed rewrite (~cap
+    // lines) each poll — a showMessage flood of historical blocked records. Skip to the END instead:
+    // the rewrite's tail is overwhelmingly history we already pushed. Trade-off, made deliberately —
+    // we may MISS the few genuinely-new records that arrived in the same rewrite, and that beats
+    // flooding the editor with thousands of stale ones.
+    activityOffset = size;
+    return;
+  }
+  if (size === activityOffset) return;
+  let text;
+  try {
+    const fd = fs.openSync(activityLog, "r");
+    const buf = Buffer.alloc(size - activityOffset);
+    fs.readSync(fd, buf, 0, buf.length, activityOffset);
+    fs.closeSync(fd);
+    text = buf.toString("utf8");
+  } catch { return; }
+  activityOffset = size;
+  const lastNl = text.lastIndexOf("\n");
+  if (lastNl < 0) { activityOffset -= Buffer.byteLength(text); return; }        // mid-write — retry next poll
+  if (lastNl < text.length - 1) { activityOffset -= Buffer.byteLength(text.slice(lastNl + 1)); text = text.slice(0, lastNl + 1); }
+  for (const l of text.split("\n")) {
+    if (!l.trim()) continue;
+    let r; try { r = JSON.parse(l); } catch { continue; }            // corrupt line — skipped, like stats
+    if (r && typeof r === "object" && !Array.isArray(r)) onActivityRecord(r);
+  }
+}
+function onActivityRecord(r) {
+  if (r.verdict === "clean") {
+    // the gate went green again — drop the GATE overlays only (a live whatif/fix overlay on the same
+    // file is the client's own question, not the gate's — it clears on the file's next open/save/edit,
+    // never here). The message noise stays hook-side; quiet here.
+    for (const key of activityOverlaid) { activityTransient.delete(key); publishDiagnostics(pathToFileURL(key).href); }
+    activityOverlaid.clear();
+    return;
+  }
+  if (r.verdict !== "blocked") return;                               // setup records aren't editor events
+  const parts = [];
+  if (Array.isArray(r.gained) && r.gained.length) parts.push(`introduces {${r.gained.join(", ")}}`);
+  if (Number.isInteger(r.blastRadius) && r.blastRadius > 0) parts.push(`blast radius ${r.blastRadius} fn(s)`);
+  if (Number.isInteger(r.maxHops)) parts.push(`deepest propagation ${r.maxHops} hop(s)`);
+  const codes = Array.isArray(r.violations) && r.violations.length ? ` [${r.violations.join(", ")}]` : "";
+  const msg = `candor gate: blocked — ${parts.join("; ") || "see the review output"}${codes}`;
+  showMessage(2, msg);
+  // pin the delta to the edited files as the gate's own transient overlay (activityTransient — cleared
+  // on the file's next open/save, or by the next clean record above; a whatif/fix overlay on the same
+  // file coexists rather than being overwritten). Hook records carry `edited`; standalone records have
+  // edited=null — the showMessage above is then the whole push.
+  for (const p of Array.isArray(r.edited) ? r.edited : []) {
+    if (typeof p !== "string" || !p) continue;
+    let key, uri;
+    try {
+      key = canonicalDocKey(nodePath.resolve(rootPath ?? process.cwd(), p));
+      uri = pathToFileURL(key).href;
+    } catch { continue; }
+    activityTransient.set(key, [{
+      range: { start: { line: 0, character: 0 }, end: { line: 0, character: 200 } },
+      severity: 2, source: "candor", code: "gate", message: msg,
+    }]);
+    activityOverlaid.add(key);
+    publishDiagnostics(uri);
+  }
+}
+
 // ---- fn → document mapping --------------------------------------------------------------------------
 // A report `loc` is `<file>:<line>[:col…]` where <file> is either a repo-relative PATH (the scan-source
 // engines) or a BARE filename (JVM bytecode SourceFile) — for the bare form the path is rebuilt from the
@@ -205,7 +317,13 @@ function publishDiagnostics(uri) {
   let docPath;
   try { docPath = fileURLToPath(uri); } catch { return; }
   try {
-    const diags = diagnosticsFor(docPath).concat(transient.get(uri) ?? []);
+    // three layers, merged: the standing gate verdict + the client's whatif/fix overlay (keyed by the
+    // client's uri string) + the activity gate overlay (keyed by the canonical path derived from the
+    // uri being published — so the lookup meets the tailer's server-computed key whatever the client's
+    // uri encoding looks like).
+    const diags = diagnosticsFor(docPath)
+      .concat(transient.get(uri) ?? [])
+      .concat(activityTransient.get(canonicalDocKey(docPath)) ?? []);
     send({ jsonrpc: "2.0", method: "textDocument/publishDiagnostics", params: { uri, diagnostics: diags } });
   } catch (e) {
     logMessage(`candor-lsp: diagnostics failed for ${uri}: ${e.message}`);
@@ -263,13 +381,29 @@ function codeActions(docPath, uri, range) {
   return out;
 }
 
-// Transient whatif diagnostics (Information severity, appended to the gate diagnostics on publish):
+// Transient whatif/fix diagnostics (Information severity, appended to the gate diagnostics on publish):
 // uri -> Diagnostic[]. Cleared on the next didOpen/didSave/didChange of that file; re-running the
 // action replaces the previous answer (one live whatif overlay per file, not an accumulating pile).
+// Keyed by the CLIENT's uri string on both sides (the set comes from executeCommand arguments that
+// echo the client's own uri; the clear reads the same field) — no canonicalization needed here, unlike
+// activityTransient whose setter computes its own paths (see canonicalDocKey).
 const transient = new Map();
 function clearTransient(uri) {
   if (transient.delete(uri)) publishDiagnostics(uri);   // republish without the overlay
 }
+// didOpen/didSave drop BOTH per-file overlays: the client's whatif/fix answer (a fresh look at the
+// file invalidates a hypothetical answered against its previous state) and the activity gate overlay
+// (same rationale — plus pruning activityOverlaid so a later clean record can't touch a file whose
+// overlay the user already dismissed). The activity side goes through canonicalDocKey to meet the
+// tailer's server-computed keys.
+function clearOverlays(uri) {
+  transient.delete(uri);
+  try {
+    const key = canonicalDocKey(fileURLToPath(uri));
+    activityTransient.delete(key);
+    activityOverlaid.delete(key);
+  } catch { /* non-file uri — no activity overlay possible */ }
+}
 
 // The candor.whatif command: the SAME query-core whatif the CLI (`query.mjs whatif`) and MCP
 // (`candor_whatif`) run — blast radius over the callgraph + the deny rules that WOULD fire, against the
@@ -379,6 +513,7 @@ function handle(msg) {
       const cand = nodePath.join(rootPath, ".candor", "report");
       if (hasReport(cand)) reportPrefix = cand;
     }
+    startActivityWatch();
     return result(id, {
       capabilities: {
         textDocumentSync: { openClose: true, save: true, change: 0 },  // report-backed: buffer edits don't move the map
@@ -391,11 +526,12 @@ function handle(msg) {
     });
   }
   if (method === "initialized" || method === "$/cancelRequest" || method === "$/setTrace") return;
-  // didOpen/didSave/didChange drop the file's transient whatif overlay — a fresh look at the file (or an
-  // edit) invalidates a hypothetical answered against the previous state. didChange is not negotiated
-  // (change: 0) but is handled defensively for clients that send it anyway.
-  if (method === "textDocument/didOpen") { transient.delete(params.textDocument.uri); return publishDiagnostics(params.textDocument.uri); }
-  if (method === "textDocument/didSave") { transient.delete(params.textDocument.uri); return publishDiagnostics(params.textDocument.uri); }
+  // didOpen/didSave drop the file's transient overlays (whatif/fix + activity gate — clearOverlays);
+  // a fresh look at the file (or an edit) invalidates an answer given against its previous state.
+  // didChange is not negotiated (change: 0) but is handled defensively for clients that send it anyway
+  // (whatif overlay only — the activity overlay clears on open/save or the next clean record).
+  if (method === "textDocument/didOpen") { clearOverlays(params.textDocument.uri); return publishDiagnostics(params.textDocument.uri); }
+  if (method === "textDocument/didSave") { clearOverlays(params.textDocument.uri); return publishDiagnostics(params.textDocument.uri); }
   if (method === "textDocument/didChange") return clearTransient(params.textDocument.uri);
   if (method === "textDocument/didClose")
     return send({ jsonrpc: "2.0", method: "textDocument/publishDiagnostics", params: { uri: params.textDocument.uri, diagnostics: [] } });
@@ -421,6 +557,7 @@ function handle(msg) {
     try { return result(id, run(params?.arguments?.[0])); }
     catch (e) { logMessage(`candor-lsp: ${params?.command} failed: ${e.message}`); return result(id, null); }
   }
+  if (method === "shutdown" && activityTimer) clearInterval(activityTimer);
   if (method === "shutdown") return result(id, null);
   if (method === "exit") process.exit(0);
   if (id !== undefined) error(id, -32601, `method not found: ${method}`);

package/mcp.mjs

@@ -48,9 +48,32 @@ function resolvePrefix(args) {
   if (!Q.hasReport(p)) throw new Error(`no report at \`${p}\` (.json or .<crate>.scan.json) — run a candor scan first`);
   return p;
 }
+// Resolve a BASELINE prefix (candor_diff / candor_gains): the EXISTENCE check stays loud — a typo'd
+// baseline that loads [] would diff/gain as an authoritative empty, a silent all-clear on the
+// supply-chain alarm — but the --root confinement deliberately does NOT apply. A baseline is read-only
+// comparison input the agent explicitly names (a prior-release report is routinely, and correctly, kept
+// OUTSIDE the repo tree so the new scan can't clobber it), not a served-workspace resource: nothing is
+// anchored to it that --root defends — its policy is never read, only its function/effect rows and
+// callgraph sidecar are compared. Confining it broke that legitimate out-of-tree workflow.
+function resolveBaseline(p) {
+  if (!Q.hasReport(p)) throw new Error(`no report at \`${clip(p)}\` (.json or .<crate>.scan.json) — run a candor scan first`);
+  return p;
+}
 // Truncate a caller-supplied value echoed back in an error (a multi-MB `fn` would otherwise be reflected
 // verbatim — token/memory amplification over the agent transport, the opposite of the list-cap thrift).
 const clip = (s, n = 120) => { s = String(s); return s.length > n ? s.slice(0, n) + "…" : s; };
+// Load a report but FAIL LOUD (a thrown tool-level error) when files were FOUND yet nothing parsed —
+// Q.loadReport discloses-and-tolerates, returning [] with the non-enumerable `hardFail` tag there, and
+// an empty SUCCESSFUL result ({gained:[],byFunction:[]}, [] show, {} map) reads as an all-clear over a
+// corrupt report — the §4 cardinal sin, exactly what the CLI's loadReportOrDie exits 2 on. The throw
+// surfaces as the same isError result shape every other tool failure uses. EVERY tool that loads a
+// report (main prefix or baseline) goes through this — never bare Q.loadReport.
+function loadReportLoud(p) {
+  const fns = Q.loadReport(p);
+  if (fns.length === 0 && fns.hardFail)
+    throw new Error(`every report found at prefix \`${clip(p)}\` failed to load — refusing to report an empty (all-clear) answer over a corrupt report; re-run the scan`);
+  return fns;
+}
 // The confinement root for a caller-supplied policy path: the repo the report belongs to — the
 // .candor/config-discovered repo root when there is one, else the parent of a `.candor/` report
 // directory, else the report's own directory. The old default (always dirname(prefix)) was the
@@ -132,22 +155,22 @@ const TOOLS = {
   candor_impact: {
     description: "Backward blast radius: every effectful function that transitively calls `fn`, and which runtime entry points are downstream. Answers 'if I change this, what surfaces at runtime?' — the cheapest possible alternative to tracing callers by hand.",
     schema: { type: "object", properties: { fn: { type: "string", description: "the function/unit to assess" }, ...reportArg }, required: ["fn"] },
-    run: (a, p) => capImpact(Q.impact(Q.loadReport(p), Q.loadCallgraph(p), a.fn)),
+    run: (a, p) => capImpact(Q.impact(loadReportLoud(p), Q.loadCallgraph(p), a.fn)),
   },
   candor_where: {
     description: "Which functions perform a given effect (e.g. Net, Db, Exec, Fs) — `directly` vs `inherited` via a callee. The effect-surface map.",
     schema: { type: "object", properties: { effect: { type: "string", description: "Net|Fs|Db|Exec|Env|Clock|Ipc|Log|Rand|Clipboard|Unknown" }, ...reportArg }, required: ["effect"] },
-    run: (a, p) => capWhere(Q.where(Q.loadReport(p), a.effect)),
+    run: (a, p) => capWhere(Q.where(loadReportLoud(p), a.effect)),
   },
   candor_reachable: {
     description: "What the program/fleet actually DOES at runtime: effects unioned over the entry points, with how many roots reach each and via which.",
     schema: { type: "object", properties: { ...reportArg } },
-    run: (_a, p) => Q.reachable(Q.loadReport(p)),
+    run: (_a, p) => Q.reachable(loadReportLoud(p)),
   },
   candor_path: {
     description: "Forward provenance: the shortest call chain from `fn` to the nearest function that performs `effect` DIRECTLY — 'this reaches Net through WHAT?'.",
     schema: { type: "object", properties: { fn: { type: "string" }, effect: { type: "string" }, ...reportArg }, required: ["fn", "effect"] },
-    run: (a, p) => Q.path(Q.loadReport(p), Q.loadCallgraph(p), a.fn, a.effect),
+    run: (a, p) => Q.path(loadReportLoud(p), Q.loadCallgraph(p), a.fn, a.effect),
   },
   candor_callers: {
     description: "Who calls `fn` — direct (one hop) and transitive callers over the effect-relevant call graph.",
@@ -157,12 +180,12 @@ const TOOLS = {
   candor_show: {
     description: "A function's effects (inferred = transitive, direct = own body) plus its literal surfaces (hosts/cmds/paths/tables) when present.",
     schema: { type: "object", properties: { fn: { type: "string" }, ...reportArg }, required: ["fn"] },
-    run: (a, p) => Q.show(Q.loadReport(p), a.fn),
+    run: (a, p) => Q.show(loadReportLoud(p), a.fn),
   },
   candor_map: {
     description: "Per-module effect overview: each module's union of effects and function count. The architecture-at-a-glance.",
     schema: { type: "object", properties: { ...reportArg } },
-    run: (_a, p) => Q.map(Q.loadReport(p)),
+    run: (_a, p) => Q.map(loadReportLoud(p)),
   },
   candor_whatif: {
     description: "Hypothetically add `effect` to `fn` and report the blast radius; with `policy`, also the deny-rule violations it would cause. Pre-edit gate check.",
@@ -195,7 +218,7 @@ const TOOLS = {
       // The sidecar is the only graph a candor-ts report carries — fail loud (tool error) when it's absent,
       // never a degenerate empty-graph remedy. (/code-review.)
       if (!cg || Object.keys(cg).length === 0) throw new Error(`no call-graph sidecar for the report — fix needs it (re-scan with --out)`);
-      const r = Q.fix(cg, Q.loadReport(p), a.fn, a.effect, parsePolicy(text), scopeMatches);
+      const r = Q.fix(cg, loadReportLoud(p), a.fn, a.effect, parsePolicy(text), scopeMatches);
       if (r === null) throw new Error(`no function matching \`${clip(a.fn)}\` in the call graph`);
       return r;
     },
@@ -211,7 +234,7 @@ const TOOLS = {
         if (!cfg) throw new Error("no policy: pass `policy`, or check one into the repo's .candor/config (spec §3.4)");
         text = confinedPolicyRead(cfg.policyPath, p, cfg.repoRoot);
       }
-      const v = evaluatePolicy(parsePolicy(text), Q.loadReport(p), Q.loadCallgraph(p));
+      const v = evaluatePolicy(parsePolicy(text), loadReportLoud(p), Q.loadCallgraph(p));
       return { ok: v.length === 0, violations: v };
     },
   },
@@ -232,33 +255,126 @@ const TOOLS = {
         if (!cfg) throw new Error("no policy: pass `policy`, or check one into the repo's .candor/config (spec §3.4)");
         text = confinedPolicyRead(cfg.policyPath, p, cfg.repoRoot);
       }
-      return Q.unverified(Q.loadReport(p), parsePolicy(text), scopeMatches);
+      return Q.unverified(loadReportLoud(p), parsePolicy(text), scopeMatches);
     },
   },
   candor_containment: {
     description: "Per boundary effect (Db/Net/Exec/Fs/Ipc/Clipboard): how contained it is in one architectural layer — the dispersion diagnostic (spec §6.1). Not a score; per-effect facts.",
     schema: { type: "object", properties: { ...reportArg } },
-    run: (_a, p) => Q.containment(Q.loadReport(p)),
+    run: (_a, p) => Q.containment(loadReportLoud(p)),
   },
   candor_blindspots: {
     description: "The Unknown SOURCES — calls the engine genuinely could not resolve (reflection, wide dispatch, fn-pointers) — ranked by how many functions inherit Unknown through each. Turns a high-Unknown report into a short worklist.",
     schema: { type: "object", properties: { ...reportArg } },
-    run: (_a, p) => capBlindspots(Q.blindspots(Q.loadReport(p), Q.loadCallgraph(p))),
+    run: (_a, p) => capBlindspots(Q.blindspots(loadReportLoud(p), Q.loadCallgraph(p))),
   },
   candor_diff: {
     description: "The per-function effect delta versus a baseline report: gained (introduced vs inherited) and lost effects. 'What did this change do to the effect surface?'.",
     schema: { type: "object", properties: { baseline: { type: "string", description: "the baseline report prefix" }, ...reportArg }, required: ["baseline"] },
-    run: (a, p) => ({ baseline_version: Q.reportVersion(a.baseline) ?? "", engine_version: Q.reportVersion(p) ?? "",
-                      ...Q.diff(Q.loadReport(p), Q.loadReport(a.baseline)) }),
+    run: (a, p) => {
+      // Baseline existence is loud (a typo'd baseline loaded [] with hardFail=false and diffed as an
+      // authoritative empty {changes:[]}; the CLI exits 2 on the same miss) — but NOT --root-confined:
+      // see resolveBaseline for the out-of-tree-baseline trust argument.
+      const b = resolveBaseline(a.baseline);
+      return { baseline_version: Q.reportVersion(b) ?? "", engine_version: Q.reportVersion(p) ?? "",
+               ...Q.diff(loadReportLoud(p), loadReportLoud(b)) };
+    },
   },
   candor_gains: {
     description: "The supply-chain alarm: effects the surface GAINED versus a baseline (package-level + per-function) — 'did this dependency bump add Net/Exec somewhere?'.",
     schema: { type: "object", properties: { baseline: { type: "string", description: "the baseline report prefix" }, ...reportArg }, required: ["baseline"] },
-    run: (a, p) => ({ baseline_version: Q.reportVersion(a.baseline) ?? "", engine_version: Q.reportVersion(p) ?? "",
-                      ...Q.gains(Q.loadReport(p), Q.loadReport(a.baseline)) }),
+    run: (a, p) => {
+      // Same baseline posture as candor_diff (loud existence, no --root confinement — resolveBaseline):
+      // an empty {gained:[]} over a typo'd baseline is a silent all-clear on the supply-chain ALARM
+      // tool, while a prior-release baseline legitimately lives outside the served tree.
+      const b = resolveBaseline(a.baseline);
+      // ⟨spec 0.12 staged⟩ baseline callgraph → byFunction[].origin, same as the CLI (parity). The
+      // loader's non-enumerable `partial` tag rides along: a corrupt baseline sidecar (edges dropped,
+      // disclosed) downgrades origin to "unknown", never a fabricated "new" over a truncated graph.
+      return { baseline_version: Q.reportVersion(b) ?? "", engine_version: Q.reportVersion(p) ?? "",
+               ...Q.gains(loadReportLoud(p), loadReportLoud(b), Q.loadCallgraph(b)) };
+    },
+  },
+  candor_activity: {
+    description: "What the edit-time gate caught: MEASURED activity from .candor/activity.jsonl (the Stop-hook / standalone review log) — edits checked, verdicts, violations by AS-EFF code, effects introduced, largest blast radius, deepest propagation (hops), plus the most recent records. Counted from the log, no model. A missing log is an empty result (the loop isn't wired here — not an error); corrupt lines are skipped.",
+    schema: { type: "object", properties: {
+      log: { type: "string", description: "activity log path (default .candor/activity.jsonl under --root, else beside the served report prefix, else cwd)" },
+      session: { type: "string", description: "filter to one sessionId" },
+      since: { type: "string", description: "ISO timestamp lower bound (records with no ts are kept)" },
+      limit: { type: "number", description: "how many recent records to return (default 5, max 50)" },
+    } },
+    noReport: true,   // reads the activity log, not a report — usable before any scan exists
+    run: (a) => readActivity(a),
   },
 };
 
+// The candor_activity reader. Field SEMANTICS mirror `candor-agents stats` (the two count the same
+// pinned record shape — lib-candor-summary.sh's writer — so they cannot tell different stories):
+// non-object lines skipped, bool-typed numerics ignored, `since` keeps null-ts records, verdict
+// buckets clean/blocked/setup. The `edited` paths in `recent` are the hook's local-only fields —
+// the MCP transport is the same machine (the agent already reads those files), so serving them is
+// not the off-box transmission FEEDBACK-SPEC's privacy note forbids.
+// The anchor a relative/default activity-log path resolves against — a LADDER, mirroring how the LSP
+// derives its watch dir (rootPath ?? dirname(reportPrefix)):
+//   1. --root: the served workspace is the explicit truth when one is declared;
+//   2. the served report prefix ($CANDOR_REPORT / CLI arg): the documented
+//      `CANDOR_REPORT=/repo/.candor/report npx candor-ts-mcp` invocation runs from ANY cwd, and the
+//      activity log lives beside the report — anchoring at cwd found nothing. A `<repo>/.candor/report`
+//      prefix anchors at `<repo>` (so the `.candor/activity.jsonl` default lands beside the report);
+//      any other prefix anchors at its own directory (its `.candor/` sits with it);
+//   3. cwd — nothing else to go on.
+function activityAnchor() {
+  if (WORKSPACE_ROOT) return WORKSPACE_ROOT;
+  if (DEFAULT_PREFIX) {
+    const dir = nodePath.resolve(nodePath.dirname(DEFAULT_PREFIX));
+    return nodePath.basename(dir) === ".candor" ? nodePath.dirname(dir) : dir;
+  }
+  return process.cwd();
+}
+function readActivity(a) {
+  const log = nodePath.resolve(activityAnchor(), a?.log || ".candor/activity.jsonl");
+  if (WORKSPACE_ROOT && !within(log, WORKSPACE_ROOT))
+    throw new Error(`activity log \`${clip(a?.log)}\` is outside the served workspace (--root ${WORKSPACE_ROOT}) — refusing`);
+  let lines = [];
+  try { lines = fs.readFileSync(log, "utf8").split("\n"); }
+  catch { return { log: null, edits: 0, note: "no activity log — the edit-time loop isn't wired here (integrations/claude-code)" }; }
+  const recs = [];
+  for (const l of lines) {
+    if (!l.trim()) continue;
+    try { const r = JSON.parse(l); if (r && typeof r === "object" && !Array.isArray(r)) recs.push(r); } catch { /* corrupt line — skipped, like stats */ }
+  }
+  const since = a?.since;
+  // `since` compares TEMPORALLY when the caller's value parses: a bytewise ISO compare mis-filters the
+  // offset/millis variants an agent naturally supplies ("…T11:30:00+01:00" sorts after "…T11:00:00Z"
+  // lexicographically yet is the earlier instant). The log's own ts format is pinned, but records are
+  // read tolerantly: a record whose ts doesn't parse is KEPT, matching the null-ts posture (a filter
+  // must never silently hide records it can't place). Only when the caller's `since` itself doesn't
+  // parse do we fall back to the old lexicographic compare (best effort over refusing).
+  const sinceMs = since ? Date.parse(since) : NaN;
+  const afterSince = (r) => {
+    if (!since || typeof r.ts !== "string") return true;
+    if (Number.isNaN(sinceMs)) return r.ts >= since;      // unparseable bound — lexicographic fallback
+    const tsMs = Date.parse(r.ts);
+    return Number.isNaN(tsMs) ? true : tsMs >= sinceMs;   // unparseable record ts — kept, like null ts
+  };
+  const kept = recs.filter((r) => (!a?.session || r.sessionId === a.session) && afterSince(r));
+  const summary = { log, edits: kept.length, clean: 0, blocked: 0, setup: 0,
+                    violations: {}, effectsIntroduced: new Set(),
+                    largestBlastRadius: 0, deepestPropagation: 0, from: null, to: null };
+  for (const r of kept) {
+    const v = r.verdict === "clean" || r.verdict === "blocked" ? r.verdict : "setup";
+    summary[v]++;
+    for (const code of Array.isArray(r.violations) ? r.violations : []) summary.violations[code] = (summary.violations[code] ?? 0) + 1;
+    for (const e of Array.isArray(r.gained) ? r.gained : []) summary.effectsIntroduced.add(e);
+    if (typeof r.blastRadius === "number" && Number.isInteger(r.blastRadius)) summary.largestBlastRadius = Math.max(summary.largestBlastRadius, r.blastRadius);
+    if (typeof r.maxHops === "number" && Number.isInteger(r.maxHops)) summary.deepestPropagation = Math.max(summary.deepestPropagation, r.maxHops);
+    if (typeof r.ts === "string") { if (!summary.from || r.ts < summary.from) summary.from = r.ts; if (!summary.to || r.ts > summary.to) summary.to = r.ts; }
+  }
+  summary.effectsIntroduced = [...summary.effectsIntroduced].sort();
+  const limit = Math.min(Math.max(1, Number.isInteger(a?.limit) ? a.limit : 5), 50);
+  return { ...summary, recent: kept.slice(-limit) };
+}
+
 // ---- MCP resources: the report + the checked-in policy, readable directly --------------------------
 function listResources(prefix) {
   const res = [{ uri: `candor://report?prefix=${encodeURIComponent(prefix)}`, name: "candor report",
@@ -270,7 +386,7 @@ function listResources(prefix) {
   return res;
 }
 function readResource(uri, prefix) {
-  if (uri.startsWith("candor://report")) return { mimeType: "application/json", text: JSON.stringify(Q.loadReport(prefix)) };
+  if (uri.startsWith("candor://report")) return { mimeType: "application/json", text: JSON.stringify(loadReportLoud(prefix)) };
   if (uri.startsWith("candor://policy")) {
     const cfg = configPolicy(prefix);
     if (!cfg) throw new Error("no checked-in policy (no .candor/config with a `policy` key)");
@@ -328,11 +444,13 @@ function handle(msg) {
       const missing = (t.schema.required || []).filter((k) => args[k] === undefined || args[k] === "");
       if (missing.length)
         return result(id, { content: [{ type: "text", text: `candor: missing required argument(s): ${missing.join(", ")}` }], isError: true });
-      const prefix = resolvePrefix(args);
+      // A log-only tool (candor_activity) needs no report — resolving one would wrongly demand a
+      // scan before the gate's own activity can be read.
+      const prefix = t.noReport ? null : resolvePrefix(args);
       // A tool that targets a `fn` gets a clear "not found" rather than a silently-empty result —
       // an agent must distinguish "no such function" from "found, nothing calls it".
       if (args.fn !== undefined) {
-        const names = [...new Set([...Object.keys(Q.loadCallgraph(prefix)), ...Q.loadReport(prefix).map((e) => e.fn)])];
+        const names = [...new Set([...Object.keys(Q.loadCallgraph(prefix)), ...loadReportLoud(prefix).map((e) => e.fn)])];
         if (Q.matches(names, args.fn).length === 0)
           return result(id, { content: [{ type: "text", text: `candor: no function matching \`${clip(args.fn)}\` in this report` }], isError: true });
       }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "candor-ts",
-  "version": "0.11.0",
-  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.11)",
+  "version": "0.13.0",
+  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.13)",
   "type": "module",
   "dependencies": {
     "@types/node": "^25.9.2",

package/policy.mjs

@@ -4,8 +4,10 @@
  * engines follow (candor-classify::policy), so the TS gate can never disagree with its own whatif.
  */
 
-export const EFFECTS = ["Net", "Fs", "Db", "Exec", "Env", "Clock", "Ipc", "Log", "Rand", "Clipboard"];
-const ALLOW_EFFECTS = new Set(["Net", "Exec", "Fs", "Db"]); // the four literal surfaces
+export const EFFECTS = ["Net", "Fs", "Db", "Exec", "Env", "Clock", "Ipc", "Log", "Rand", "Clipboard", "Llm"];
+// 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"]);
 
 // The §6.2 token separator: ASCII whitespace ONLY (space/tab/LF/VT/FF/CR). JS `\s`/`String.trim` strip
 // Unicode spaces (NBSP, ideographic, …) that Java drops — a gateless-green cross-engine divergence
@@ -36,7 +38,7 @@ export function parsePolicy(text) {
       deny.push({ effects: [], scope: t[1] ?? "", 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 / Exec commands / Fs paths / Db tables"); continue; }
+      if (!ALLOW_EFFECTS.has(t[1])) { warn("allow supports only Net hosts / Llm hosts / Exec commands / Fs paths / Db tables"); continue; }
       let scope = "", vi = 2;
       if (t[2] === "in") { scope = t[3] ?? ""; vi = 4; }
       const values = t.slice(vi);
@@ -97,6 +99,8 @@ export function tableCovered(a, r) {
 export function literalAllowed(effect, reached, values) {
   switch (effect) {
     case "Net":  return values.some((a) => hostPart(a) === hostPart(reached));
+    // `Llm` ⟨0.13⟩ rides Net's host literal (SPEC §1) — matched by hostname exactly like Net.
+    case "Llm":  return values.some((a) => hostPart(a) === hostPart(reached));
     case "Exec": return values.some((a) => cmdBase(a) === cmdBase(reached));
     case "Fs":   return values.some((a) => pathCovered(a, reached));
     case "Db":   return values.some((a) => tableCovered(a, reached));
@@ -115,7 +119,8 @@ export function literalAllowed(effect, reached, values) {
 // The console gate renders `[${rule}] ${detail}`; --gate-json emits the records verbatim.
 export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()) {
   const out = [];
-  const surfaces = { Net: "hosts", Exec: "cmds", Fs: "paths", Db: "tables" };
+  // `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 });
   for (const f of functions) {
     for (const r of pol.deny) {
@@ -136,7 +141,11 @@ export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()
       // An INCOMPLETE surface (a structurally-invisible reach — a host-establishing call with a runtime/
       // invisible host) can't be certified even with visible hosts, else a benign literal masks the
       // invisible forbidden endpoint (the masking evasion). Matches candor-java 0.5.29 / candor-rust.
-      const surfaceIncomplete = incomplete.get(f.fn)?.has(r.effect);
+      // `Llm` ⟨0.13⟩ rides the Net host literal (SPEC §1), so a runtime/masked host that makes the Net
+      // surface incomplete must fail-close `allow Llm …` identically (java parity #3): a benign visible
+      // model host must not certify a scope that also reaches a hidden one.
+      const surfaceIncomplete = incomplete.get(f.fn)?.has(r.effect)
+        || (r.effect === "Llm" && incomplete.get(f.fn)?.has("Net"));
       if (reached.length === 0 || surfaceIncomplete) {
         push("AS-EFF-008", f.fn, [r.effect], `\`${f.fn}\` performs ${r.effect} with no visible literal — the surface cannot be certified: \`${r.raw}\``);
       } else {

package/query-core.mjs

@@ -170,6 +170,13 @@ export function loadReport(prefix) {
   }
   return tagHardFail(fns, hardFail);
 }
+// The returned graph carries a non-enumerable `partial` flag (the loadReport `hardFail` precedent):
+// true iff a sidecar file was MATCHED but failed to read/parse — its edges were DROPPED (disclosed on
+// stderr above), so the graph is an UNDER-approximation. An ABSENT sidecar is NOT partial: nothing
+// matched, and the empty graph is the whole (disclosable) truth. gains' origin ladder needs the
+// distinction: over a partial baseline graph, absence from the surviving edges proves nothing, so
+// labeling a dropped file's fns "new" would downgrade the attack signal — fall back to "unknown".
+const tagPartial = (cg, partial) => { Object.defineProperty(cg, "partial", { value: partial, enumerable: false }); return cg; };
 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
@@ -180,16 +187,18 @@ export function loadCallgraph(prefix) {
   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 {}; }
+    // `null` `<prefix>.callgraph.json` (asymmetric with siblings). Tolerate (empty graph) + disclose,
+    // and TAG the drop (`partial`) so a consumer never mistakes the truncated graph for the whole one.
+    try { return tagPartial(norm(JSON.parse(fs.readFileSync(`${prefix}.callgraph.json`, "utf8"))), false); }
+    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 tagPartial({}, true); }
   }
   const cg = {};
+  let partial = false;
   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`); }
+    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`); partial = true; }
   }
-  return norm(cg);
+  return tagPartial(norm(cg), partial);
 }
 
 // ---- the §3.1 match ladder: exact > segment-suffix > substring ------------------------------------
@@ -334,7 +343,7 @@ export function map(fns) {
 // with the AS-EFF-010 ratchet when a baseline is given. Mirrors candor-java Query.containment and
 // candor-query cmd_containment: boundary effects are scored, ambient ones reported-not-scored; a layer is
 // the segment AFTER the common dotted prefix ("(root)" when no package layer follows). Uses DIRECT effects.
-export const CONTAINED = ["Db", "Net", "Exec", "Fs", "Ipc", "Clipboard"];
+export const CONTAINED = ["Db", "Net", "Llm", "Exec", "Fs", "Ipc", "Clipboard"];
 export const AMBIENT = ["Log", "Clock", "Rand", "Env"];
 function commonPrefixLen(fns) {
   let best = null;
@@ -523,10 +532,34 @@ export function diff(curFns, baseFns) {
 // 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) {
+//
+// ⟨spec 0.12 staged⟩ each byFunction entry carries `origin` — the candor-gains prototype's key finding
+// promoted into the open query. A gain on a fn that EXISTED at the baseline (shipped pure, now does
+// Net — the supply-chain attack signal) is a different alarm from a NEW fn that does Net (a feature).
+// Reports OMIT pure functions (§2), so existence is keyed on the baseline CALLGRAPH (a baseline-pure
+// fn is a graph node with no report entry):
+//   "existing" — in the baseline report, or a baseline-callgraph node (caller key or callee);
+//   "new"      — a COMPLETE baseline callgraph was loaded and the fn is in neither (did not exist);
+//   "unknown"  — absent from the baseline report AND the graph cannot decide: no baseline callgraph
+//                found (empty graph) OR the graph is PARTIAL (loadCallgraph's non-enumerable `partial`
+//                tag — a matched sidecar failed to load, its edges were dropped-and-disclosed, so
+//                absence from the survivors proves nothing). Undecidable is DISCLOSED, never guessed
+//                (§4) — a partial graph must not downgrade the attack signal from a dropped file's
+//                fns to a benign-looking "new".
+// `baseCg` defaults to {} (no callgraph → "unknown") so core-only callers keep working unchanged.
+export function gains(curFns, baseFns, baseCg = {}) {
+  const baseSet = new Set(baseFns.map((e) => e.fn));
+  const cgNodes = new Set(Object.entries(baseCg).flatMap(([k, vs]) => [k, ...vs]));
+  // The ladder: report hit → existing; graph node → existing (a surviving node is real even in a
+  // partial graph — the drop loses nodes, never invents them); else "new" only when a COMPLETE
+  // non-empty graph can vouch for non-existence; else "unknown".
+  const graphDecides = cgNodes.size > 0 && baseCg.partial !== true;
+  const originOf = (fn) => baseSet.has(fn) ? "existing"
+    : cgNodes.has(fn) ? "existing"
+    : graphDecides ? "new" : "unknown";
   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 }); }
+    for (const e of c.gained) { gained.add(e); byFunction.push({ effect: e, fn: c.fn, origin: originOf(c.fn) }); }
   }
   return { gained: [...gained].sort(), byFunction };
 }

package/query.mjs

@@ -49,8 +49,12 @@ const emit = (v) => console.log(JSON.stringify(v, null, 1));
 // Prints to stdout and returns nothing (matches the JSON-only verbs' fire-and-forget style).
 function renderPathHuman(fns, cg, fnQ, eff) {
   // Resolve the start over the REPORT entries (as Rust does) — that's where `inferred` lives, and the
-  // no-effect wording quotes it. corePath resolves over the callgraph keys for the chain; the two agree
-  // on any fn that has an entry, which every graphed fn does.
+  // no-effect wording quotes it. The RESOLVED name (not the raw query) is then handed to corePath,
+  // which re-resolves over the CALLGRAPH keys — a DIFFERENT name set: a raw partial query could pick
+  // a different fn there (report `app.db.save`, graph `app.cache.save` for the query "save"), so the
+  // header described one function and the chain/verdict another (a misleading "not statically
+  // traceable" over a traceable fn). An exact name resolves identically in both sets (match tier 3,
+  // exact, beats every partial tier and only its own name can equal it), so they cannot disagree.
   const start = coreMatches(fns.map((e) => e.fn), fnQ)[0];
   if (start === undefined) {
     // No matching function at all — parity with Rust/Java's "no function matching" (stderr, exit 2).
@@ -67,7 +71,7 @@ function renderPathHuman(fns, cg, fnQ, eff) {
     console.log(`${start} does not perform ${eff}  (inferred: ${dbg})`);
     return;
   }
-  const r = corePath(fns, cg, fnQ, eff);
+  const r = corePath(fns, cg, start, eff);
   if (r.path.length === 0) {
     // Inferred, but no LOCAL direct source on a `calls` path — reached cross-crate or via Unknown.
     console.log(`${start} performs ${eff} but its source is not a local function `
@@ -90,7 +94,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.11";
+const SPEC_VERSION = "0.13";
 
 // ---- 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]
@@ -421,7 +425,13 @@ switch (cmd) {
     // each resolved by the shared locator rule (dir / .json path / prefix). --json is accepted (JSON is
     // the only output). No leading-positional-report alias here: both positionals ARE the reports.
     const { positionals } = parseCanonical(args, {});
+    if (positionals.length < 2) { console.error("usage: candor-ts-query diff <current> <baseline> [--json]"); process.exit(2); }
     const [curPrefix, basePrefix] = positionals.map(locatorToPrefix);
+    // BOTH locators must name real report files (the Rust engine's no-files check, named per side so
+    // the user knows which path to fix): a typo'd prefix loaded [] with hardFail=false and emitted an
+    // authoritative EMPTY {changes:[]} at exit 0 — the §4 false all-clear on the ratchet verb.
+    if (!hasReport(curPrefix)) { console.error(`candor-ts: no report files at current prefix '${curPrefix}' — check the path.`); process.exit(2); }
+    if (!hasReport(basePrefix)) { console.error(`candor-ts: no report files at baseline prefix '${basePrefix}' — check the path.`); process.exit(2); }
     const { changes } = coreDiff(loadReportOrDie(curPrefix), loadReportOrDie(basePrefix));
     // §2.1: a baseline is comparable only to its own producing build — disclose a mismatch (the gains
     // may be the engine reclassifying after a coverage batch, not the code changing). Same note + JSON
@@ -547,11 +557,21 @@ switch (cmd) {
     // §3.3.1: like diff, two positional locators <current> <baseline> (no discovery), each resolved by
     // the shared locator rule; --json accepted.
     const { positionals } = parseCanonical(args, {});
+    if (positionals.length < 2) { console.error("usage: candor-ts-query gains <current> <baseline> [--json]"); process.exit(2); }
     const [curPrefix, basePrefix] = positionals.map(locatorToPrefix);
+    // BOTH locators must name real report files (the Rust engine's no-files check, named per side):
+    // a typo'd prefix loaded [] with hardFail=false and emitted an authoritative EMPTY
+    // {gained:[],byFunction:[]} at exit 0 — a silent all-clear on the supply-chain ALARM verb.
+    if (!hasReport(curPrefix)) { console.error(`candor-ts: no report files at current prefix '${curPrefix}' — check the path.`); process.exit(2); }
+    if (!hasReport(basePrefix)) { console.error(`candor-ts: no report files at baseline prefix '${basePrefix}' — check the path.`); process.exit(2); }
     const gv = reportVersion(curPrefix), gbv = reportVersion(basePrefix);
     if (gv && gbv && gv !== gbv)
       console.error(`candor-ts: ⚠ baseline @${gbv} ≠ engine @${gv} — a "gained capability" may be the engine reclassifying, not the dependency changing. Regenerate both reports with one build to compare releases.`);
-    emit({ baseline_version: gbv ?? "", engine_version: gv ?? "", ...coreGains(loadReportOrDie(curPrefix), loadReportOrDie(basePrefix)) });
+    // ⟨spec 0.12 staged⟩ the BASELINE callgraph feeds byFunction[].origin (existing/new/unknown) —
+    // a MISSING sidecar loads {} and a corrupt (matched-but-unparseable) one is tagged `partial`
+    // with its edges dropped-and-disclosed: either way "new" is unavailable and origin falls back
+    // to "unknown" — the JSON itself discloses, never guessing "new" over a truncated graph.
+    emit({ baseline_version: gbv ?? "", engine_version: gv ?? "", ...coreGains(loadReportOrDie(curPrefix), loadReportOrDie(basePrefix), loadCallgraph(basePrefix)) });
     break;
   }
   case "path": {
@@ -563,7 +583,13 @@ switch (cmd) {
     const fns = loadReportOrDie(prefix);
     const cg = loadCallgraph(prefix);
     if (wantJson) emit(corePath(fns, cg, fn, eff));           // conformance PART 5 shape — UNCHANGED
-    else renderPathHuman(fns, cg, fn, eff);
+    else {
+      // The accepted 0.11 default change (the human chain replaced JSON as the no-flag output) gets a
+      // ONE-line stderr breadcrumb, so a pre-0.11 pipeline that broke on the new default is pointed at
+      // --json rather than left guessing. stderr only — stdout stays the human chain; --json untouched.
+      console.error("candor-ts-query: tip — `--json` selects the machine-readable path shape (the default before 0.11)");
+      renderPathHuman(fns, cg, fn, eff);
+    }
     break;
   }
   case "whatif": {

package/scan-core.mjs

@@ -185,7 +185,25 @@ export const KAPPA_RULES = [
   [/^drizzle-orm$/, /^(execute|transaction|findMany|findFirst|all|get|run)$/, "Db"],
   // Nest's HttpService wraps axios — the request verbs are Net.
   [/^@nestjs\/axios$/, /^(get|post|put|patch|delete|head|request)$/, "Net"],
+  // SPEC §1 ⟨0.13⟩ `Llm` model-SDK surface — the curated model-provider clients (Rules.MODEL_SDK_PACKAGES
+  // in the java reference). These are SINGLE-PURPOSE: any call into them dispatches a model request, which
+  // IS network I/O — so they classify Net here (the whole-module Net machinery: host literals, the masking
+  // gate) and the classify site adds `Llm` on top via isModelSdkPackage() (Net is never dropped). NO
+  // method-name gating (java parity #1: any call into a model-SDK package is Llm+Net). Sub-path imports
+  // (`openai/resources`, `@langchain/core/language_models`) are covered by the `(/|$)` tail. Curated
+  // STARTER list — the §7 coverage ledger discloses an uncovered provider package like any other.
+  [/^(openai|@anthropic-ai\/sdk|@google\/generative-ai|@aws-sdk\/client-bedrock-runtime|ai|@mistralai\/mistralai|cohere-ai|groq-sdk|ollama|langchain|@langchain\/core)(\/|$)/,
+   null, "Net"],
 ];
+// SPEC §1 ⟨0.13⟩ `Llm` model-SDK packages — the curated model-provider clients whose calls refine Net to
+// Llm (mirrors Literals.modelHostEffects on the SDK side; matched by the same regex the KAPPA_RULES Net
+// entry uses, so the two can never drift). isModelSdkPackage answers "is this resolved module a model
+// SDK?" — a call into it is Llm+Net (Net comes from the κ rule above; the classify site adds Llm).
+export const MODEL_SDK_RE =
+  /^(openai|@anthropic-ai\/sdk|@google\/generative-ai|@aws-sdk\/client-bedrock-runtime|ai|@mistralai\/mistralai|cohere-ai|groq-sdk|ollama|langchain|@langchain\/core)(\/|$)/;
+export function isModelSdkPackage(moduleName) {
+  return MODEL_SDK_RE.test(moduleName);
+}
 export function kappa(moduleName, member) {
   for (const [mre, vre, eff] of KAPPA_RULES) {
     if (mre.test(moduleName) && (!vre || vre.test(member))) return eff;
@@ -228,6 +246,53 @@ export function hostLiteral(s) {
   if (/^[a-z0-9._-]+(:\d+)?$/i.test(s) && s.includes(".")) return s; // bare host[.tld][:port]
   return null;
 }
+// SPEC §1 ⟨0.13⟩ `Llm` HOST-LITERAL refinement — the known machine-learning model-provider hosts. A
+// statically-known Net request to one of these classifies `Llm` IN ADDITION to `Net` (Net is never
+// dropped — a model call IS network I/O), just as a jdbc URL classifies `Db`. The four reference engines
+// share this table VERBATIM (java Literals.MODEL_HOSTS). Matched by host, case-insensitive; a SUBDOMAIN
+// of a listed host counts. Curated STARTER set; the §7 coverage ledger discloses an uncovered provider.
+export const MODEL_HOSTS = new Set([
+  "api.openai.com",
+  "api.anthropic.com",
+  "generativelanguage.googleapis.com",
+  "api.mistral.ai",
+  "api.cohere.ai", "api.cohere.com",
+  "api.groq.com",
+  "api.together.xyz",
+  "api.perplexity.ai",
+  "openrouter.ai",
+]);
+// Whether an endpoint HOST literal is a known model provider (case-insensitive; a subdomain of a
+// MODEL_HOSTS entry counts). Strips a `:port` suffix first. Two special forms carry their own rule (java
+// Literals.isModelHost parity): any host whose port is 11434 is a local Ollama endpoint
+// (`localhost:11434`, `127.0.0.1:11434`); and an AWS Bedrock runtime host `*.bedrock*.amazonaws.com`
+// (host CONTAINS "bedrock" AND ends `.amazonaws.com` — java parity #4).
+// Ollama is a LOCAL endpoint: :11434 → Llm ONLY on a loopback host (max-review r3 parity fix — "any host
+// on :11434" fabricated Llm on an unrelated internal service). Bedrock matches the EXACT model-inference
+// service label, not the substring "bedrock" (which caught `bedrock-backups.s3.amazonaws.com`, an S3 bucket).
+const OLLAMA_LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
+const BEDROCK_RUNTIME_LABELS = new Set(["bedrock-runtime", "bedrock-agent-runtime"]);
+export function isModelHost(hostLiteral) {
+  if (hostLiteral == null) return false;
+  // hostPart: strip a trailing :port (keep a bracketed/unbracketed IPv6 intact, like policy.hostPart);
+  // also recover the port for the Ollama loopback check.
+  let host = hostLiteral, port = null;
+  if (host.startsWith("[")) { const e = host.indexOf("]"); if (e >= 0) { const rest = host.slice(e + 1); if (rest.startsWith(":")) port = rest.slice(1); host = host.slice(1, e); } }
+  else if ((host.match(/:/g) ?? []).length === 1) { const p = host.split(":"); host = p[0]; port = p[1]; }
+  host = host.toLowerCase();
+  if (port === "11434") return OLLAMA_LOCAL_HOSTS.has(host);   // Ollama: loopback only
+  if (MODEL_HOSTS.has(host)) return true;
+  for (const m of MODEL_HOSTS) if (host.endsWith("." + m)) return true; // a subdomain counts
+  // AWS Bedrock runtime: the FIRST label is the model-inference service (bedrock-runtime.<region>.amazonaws.com).
+  if (host.endsWith(".amazonaws.com") && BEDROCK_RUNTIME_LABELS.has(host.split(".")[0])) return true;
+  return false;
+}
+// The effects a model-host literal implies: ["Llm"] for a known model host, else []. Shared with the
+// sibling engines like commandHeadEffects; `Net` is added by the caller (the host was captured on a
+// Net-bearing call), so this returns ONLY the refinement.
+export function modelHostEffects(hostLiteral) {
+  return isModelHost(hostLiteral) ? ["Llm"] : [];
+}
 // 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

@@ -29,7 +29,8 @@ import { createRequire } from "node:module";
 import { parsePolicy, evaluatePolicy, scopeMatches } from "./policy.mjs";
 import { unverifiedHoleRule, ruleUpgrade } from "./query-core.mjs";
 import { printAgents } from "./contract.mjs";
-import { isTestPath, kappa, kappaKnows, commandHeadEffects, hostLiteral, tablesInSql } from "./scan-core.mjs";
+import { isTestPath, kappa, kappaKnows, commandHeadEffects, hostLiteral, tablesInSql,
+         modelHostEffects, isModelHost, isModelSdkPackage } from "./scan-core.mjs";
 import { emitSurface } from "./surface.mjs";
 
 const ENGINE_DIR = path.dirname(fileURLToPath(import.meta.url));
@@ -40,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.11";
+const SPEC_VERSION = "0.13";
 
 // --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
@@ -391,7 +392,7 @@ function declModule(decl) {
 // silent pure/blind-spot the package would otherwise carry, exactly like a cap type (and unlike
 // candor's own analysis, which is checked). A name outside §1 VOIDS the declaration loudly — a typo
 // must never silently narrow a surface. Cached per package. `file` is the resolved declaration source.
-const EFFECT_VOCAB = new Set(["Net", "Fs", "Db", "Exec", "Env", "Clock", "Ipc", "Log", "Rand", "Clipboard"]);
+const EFFECT_VOCAB = new Set(["Net", "Fs", "Db", "Exec", "Env", "Clock", "Ipc", "Log", "Rand", "Clipboard", "Llm"]);
 const _manifestCache = new Map();
 // Returns the declared effect array (possibly EMPTY — `[]` is an explicit "declared pure", covered, not
 // a blind spot), or `null` for no/invalid declaration (still a blind spot). A name outside §1 voids the
@@ -467,6 +468,66 @@ function programHeadLiteral(node) {
   const a0 = (node.arguments ?? [])[0];
   return a0 && ts.isStringLiteralLike(a0) ? a0.text : null;
 }
+// The URL/endpoint literal of a host-bearing Net call, read from the DOCUMENTED URL arg position — a host
+// predicate must run against the extracted URL argument, never the first literal ANYWHERE in the args:
+// `fetch(runtimeUrl, "some-literal")` must NOT read the trailing literal (headers/body/options) as the
+// host (the programHeadLiteral discipline, generalized from Exec to Net — FINDING 6). Position is
+// member-aware: the HTTP verbs (fetch/get/post/put/patch/delete/head/options/request) take the URL FIRST;
+// net.connect/createConnection put the host at arg1 in the `(port, host)` overload (and arg0 is a path/
+// options in the other overloads) — so those two members read arg0-or-arg1. Only STRING-LITERAL positions
+// are considered; returns null when the URL slot is not a static string literal — the safe direction.
+const NET_URL_ARG1_MEMBERS = new Set(["connect", "createConnection"]);
+function urlArgLiteral(node, member) {
+  const args = node.arguments ?? [];
+  const litAt = (i) => (args[i] && ts.isStringLiteralLike(args[i]) ? args[i].text : null);
+  if (member && NET_URL_ARG1_MEMBERS.has(member)) return litAt(0) ?? litAt(1); // (port, host) or (path)
+  return litAt(0);
+}
+// Is arg0 a RUNTIME STRING expression whose host can't be known statically — a template, a string
+// concat, or a `string`-typed variable/member/call? Only THIS shape masks the host and must fail the
+// surface closed. A STRUCTURED url arg (`new URL(...)`, a `Request` object, any non-string value) carries
+// its host in a form the literal gate never saw, but it did not mask a literal that WAS there — pre-Llm
+// behavior added Net and moved on, so it must NOT regress to fail-closed. Absent arg0 → not a masking
+// string either (never fabricate incompleteness). A static string literal is handled by urlArgLiteral, so
+// it is excluded here.
+function urlArgIsRuntimeString(node) {
+  const a0 = (node.arguments ?? [])[0];
+  if (!a0 || ts.isStringLiteralLike(a0)) return false;
+  if (ts.isTemplateExpression(a0)) return true; // `${base}/path` — host built at runtime
+  if (ts.isBinaryExpression(a0) && a0.operatorToken.kind === ts.SyntaxKind.PlusToken) return true; // concat
+  // a variable/member/call arg: a masking runtime host only when its static type is `string` (a
+  // `new URL()`/`Request`/other object is NOT a string type — leave it clean, as before the Llm port).
+  const t = checker.getTypeAtLocation(a0);
+  return t ? (t.flags & (ts.TypeFlags.String | ts.TypeFlags.StringLiteral)) !== 0 : false;
+}
+// The Ollama local-endpoint decision (java Literals parity #2), routed through the EXTRACTED host, never
+// a raw literal that merely CONTAINS ":11434". `urlLit` is arg0's string text; `host` is hostLiteral(urlLit)
+// (null when arg0 didn't parse as a structured host/URL). Returns "capture" (a dotted model/Ollama host
+// hostLiteral kept — the caller captures it and adds modelHostEffects), "llm-no-capture" (a DOTLESS
+// `localhost:11434`/`127.0.0.1:11434` — refine to Llm but do NOT capture the host as a Net allowlist
+// literal, so the host gate stays intact: java parity #2), or null (no model signal). CRITICAL: the
+// :11434 → Llm rule fires ONLY when arg0 parsed as a STRUCTURED host:port whose port is 11434 — a raw
+// relative path like `/v1/models:11434/generate` never parses as a host, so it can never fabricate Llm.
+function isDotlessLocalOllama(host) {
+  if (host == null) return false;
+  const colon = host.lastIndexOf(":");
+  if (colon < 0 || host.slice(colon + 1) !== "11434") return false;
+  const hostPart = host.slice(0, colon).toLowerCase();
+  return hostPart === "localhost" || hostPart === "127.0.0.1"; // dotless local endpoint only
+}
+function ollamaFromUrlArg(urlLit) {
+  if (urlLit == null) return null;
+  // Parse arg0 as a host[:port] the same way the capture path does. `scheme://host[:port]/…` yields the
+  // authority even when the host is dotless; a bare `foo.internal:11434` yields itself; a relative path
+  // (`/v1/x:11434/y`) parses to NOTHING → never a host, so it can never fabricate Llm (FINDING 1).
+  const parsed = hostLiteral(urlLit);
+  if (parsed == null) return null;
+  // FINDING 9: a DOTLESS local Ollama endpoint (`http://localhost:11434/…`) refines to Llm WITHOUT
+  // capturing the host as a Net allowlist literal (java parity #2 — preserve the host gate). A DOTTED
+  // model/Ollama host (`foo.internal:11434`, `api.anthropic.com`) is captured as before.
+  if (isDotlessLocalOllama(parsed)) return "llm-no-capture";
+  return isModelHost(parsed) ? "capture-model" : "capture-plain";
+}
 // qualifies by the file's basename (`Cases.union_a`).
 const fns = new Map();           // qualified name -> { direct, edges, hosts, tables, cmds, paths, loc }
 const unlistedSeen = new Map();  // the κ-coverage ledger: unlisted npm package -> call-site count
@@ -1654,18 +1715,37 @@ function visitCalls(node) {
           }
           // the literal surfaces, read only at a CLASSIFIED call (SPEC §2)
           if (eff === "Net") {
-            const lit = firstStringLiteral(node);
-            const h = lit && hostLiteral(lit);
-            if (h) rec.hosts.add(h);
-            // MASKING fix: a host-ESTABLISHING Net call whose host is NOT a captured literal (runtime URL, or
-            // built elsewhere) leaves the host invisible to the gate → mark the surface incomplete so a
-            // benign literal can't mask it. ALLOWLIST of establishing forms only — NEVER use-calls
-            // (write/end/non-dgram send), which would false-positive on `socket.connect("h").write(data)`
-            // (the host is captured at connect). Under-catches an unlisted establishing verb (safe
-            // direction); never over-flags a use-call.
-            else if (netEstablishing(member))
-              rec.incomplete.add("Net");
+            // The host predicate runs against the EXTRACTED URL argument (arg0 — the URL/endpoint slot of
+            // fetch/axios/the HTTP verbs), NEVER the first literal anywhere in the args: a trailing literal
+            // in headers/body/options must not be read as the host (FINDING 6). Ollama's model decision runs
+            // through the parsed host too, never a raw string that merely contains ":11434" (FINDING 1/9).
+            const urlLit = urlArgLiteral(node, member);
+            const ollama = ollamaFromUrlArg(urlLit);
+            if (ollama === "capture-model" || ollama === "capture-plain") {
+              const h = hostLiteral(urlLit);
+              rec.hosts.add(h);
+              // SPEC §1 ⟨0.13⟩ Llm host-literal refinement: a known model host makes this a model call
+              // (Llm + Net — Net is never dropped), exactly as a jdbc URL classifies Db.
+              for (const e of modelHostEffects(h)) rec.direct.add(e);
+            } else {
+              // No captured host literal. §1 ⟨0.13⟩ Ollama LOCAL endpoint (`localhost:11434`/`127.0.0.1:11434`):
+              // refine to Llm but do NOT capture the host as a Net allowlist literal (java parity #2 —
+              // preserve the host gate so `deny Llm` catches it while `allow Llm localhost` fails closed).
+              if (ollama === "llm-no-capture") rec.direct.add("Llm");
+              // MASKING fix: a host-ESTABLISHING Net call whose host is NOT a captured literal (runtime URL, or
+              // built elsewhere) leaves the host invisible to the gate → mark the surface incomplete so a
+              // benign literal can't mask it. ALLOWLIST of establishing forms only — NEVER use-calls
+              // (write/end/non-dgram send), which would false-positive on `socket.connect("h").write(data)`
+              // (the host is captured at connect). Under-catches an unlisted establishing verb (safe
+              // direction); never over-flags a use-call.
+              if (netEstablishing(member)) rec.incomplete.add("Net");
+            }
           }
+          // SPEC §1 ⟨0.13⟩ `Llm` model-SDK surface: a call into a curated model-provider client (the
+          // scan-core MODEL_SDK regex, also the whole-module Net κ rule above) dispatches a model request
+          // → Llm + Net. Net came from κ (eff === "Net"); add Llm on top. NO method-name gating (java
+          // parity #1) — any call into these single-purpose clients is a model dispatch. Additive.
+          if (isModelSdkPackage(mod)) rec.direct.add("Llm");
           if (eff === "Db") {
             const lit = firstStringLiteral(node);
             const before = rec.tables.size;
@@ -1818,7 +1898,33 @@ function visitCalls(node) {
       geff = "Net";
     if (geff) {
       const owner = enclosing(node);
-      if (owner) fns.get(owner).direct.add(geff);
+      if (owner) {
+        const rec = fns.get(owner);
+        rec.direct.add(geff); // Net is added unconditionally for a global fetch (never gated on host capture)
+        // The global `fetch(url)` is a host-bearing Net call — capture its URL-ARGUMENT host (arg0, like the
+        // κ-Net path) so the allowlist/masking gate sees it, and refine to `Llm` on a known model host (SPEC
+        // §1 ⟨0.13⟩). Without this, `fetch("https://api.anthropic.com/…")` read bare Net with no host at all.
+        if (geff === "Net") {
+          // Host predicate runs against arg0 (the URL slot), NEVER the first literal anywhere in the args:
+          // `fetch(runtimeUrl, "literal")` must not read the trailing literal as the host (FINDING 6). Ollama's
+          // model decision runs through the parsed host, never a raw ":11434" substring (FINDING 1/9).
+          const urlLit = urlArgLiteral(node);
+          const ollama = ollamaFromUrlArg(urlLit);
+          if (ollama === "capture-model" || ollama === "capture-plain") {
+            const h = hostLiteral(urlLit);
+            rec.hosts.add(h);
+            for (const e of modelHostEffects(h)) rec.direct.add(e);
+          } else if (ollama === "llm-no-capture") {
+            // §1 ⟨0.13⟩ dotless local Ollama endpoint: Llm WITHOUT capturing the host (java parity #2).
+            rec.direct.add("Llm");
+          } else if (urlArgIsRuntimeString(node)) {
+            // Only a RUNTIME STRING url (template/concat/`string`-typed value) masks the host → fail closed,
+            // like a host-establishing κ call. A structured `new URL(...)`/`Request` arg (or absent arg) did
+            // NOT mask a literal — it passed clean pre-Llm-port, so it must NOT regress to fail-closed (FINDING 7).
+            rec.incomplete.add("Net");
+          }
+        }
+      }
     }
     // dynamic `require(<non-literal>)` — the CJS twin of `import(m)` (which already discloses Unknown):
     // it loads an arbitrary module and runs its top-level code, so the effects are opaque → Unknown. A
@@ -2182,7 +2288,7 @@ if (!wantJson) {
   // Effect breakdown — make the result visible at a glance, not just a count + a file path.
   const counts = {};
   for (const e of functions) for (const x of e.inferred) counts[x] = (counts[x] || 0) + 1;
-  const breakdown = ["Net", "Fs", "Db", "Exec", "Ipc", "Env", "Clipboard", "Clock", "Log", "Rand"]
+  const breakdown = ["Net", "Llm", "Fs", "Db", "Exec", "Ipc", "Env", "Clipboard", "Clock", "Log", "Rand"]
     .filter((k) => counts[k]).map((k) => `${k} ${counts[k]}`).join(" · ");
   const unknown = counts.Unknown || 0;
   if (breakdown || unknown) {

package/surface.mjs

@@ -84,7 +84,7 @@ function hasToken(name, lexicon) {
 // Matches the Rust reference (candor-classify/src/surface.rs) + the java/swift ports.
 function salience(effect) {
   switch (effect) {
-    case "Net": case "Exec": case "Db": case "Ipc": return 5;
+    case "Net": case "Llm": case "Exec": case "Db": case "Ipc": return 5;
     case "Fs": case "Env": return 3;
     default: return 0; // Clock/Log/Rand/Unknown/everything-else — mundane, never surfaced
   }