candor-ts 0.12.0 → 0.14.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.12)."*
+> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.14)."*
 > 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`.
 >
@@ -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.12" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
+| `{ candor: { version, toolchain, spec: "0.14" }, 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.12.x, speaking candor-spec 0.12: the analysis core, the gate (`--policy` / `--gate-json` /
+0.14.x, speaking candor-spec 0.14: 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,6 +48,17 @@ 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; };
@@ -261,10 +272,10 @@ const TOOLS = {
     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) => {
-      // The BASELINE locator gets the SAME existence + --root confinement checks as the main report
-      // (resolvePrefix) — a typo'd baseline loaded [] with hardFail=false and diffed as an
-      // authoritative empty {changes:[]} (the CLI now exits 2 on the same miss).
-      const b = resolvePrefix({ report: a.baseline });
+      // 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)) };
     },
@@ -273,9 +284,10 @@ const TOOLS = {
     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) => {
-      // Same baseline existence + --root confinement as candor_diff — an empty {gained:[]} over a
-      // typo'd baseline is a silent all-clear on the supply-chain ALARM tool.
-      const b = resolvePrefix({ report: a.baseline });
+      // 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.
@@ -283,8 +295,86 @@ const TOOLS = {
                ...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",
@@ -354,7 +444,9 @@ 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) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "candor-ts",
-  "version": "0.12.0",
-  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.12)",
+  "version": "0.14.0",
+  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.14)",
   "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

@@ -343,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;

package/query.mjs

@@ -94,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.12";
+const SPEC_VERSION = "0.14";
 
 // ---- 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]

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.12";
+const SPEC_VERSION = "0.14";
 
 // --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
@@ -1030,6 +1091,29 @@ function enumerateGetters(owner, type) {
   }
 }
 
+// The synthesized `<module>` unit for a source file's TOP-LEVEL executable statements (spec §2
+// unitKind "initializer" — java's `<clinit>` twin). Top-level `await fetch(…)`, a bare
+// `readFileSync(…)`, an IIFE, `export const r = await fetch(…)` execute at MODULE-LOAD time and
+// belong to nothing named — without this unit their effects reached the SourceFile in `enclosing`,
+// resolved to `null`, and were DROPPED → a false "pure" verdict (the cardinal sin: ESM top-level
+// await / serverless handler files / side-effecting config modules scanned as functions: []). This
+// is the field-initializer `Class.constructor` synthesis (~scan.mjs:774) one level up: the module
+// body is the file's own initializer. Minted LAZILY — only when a top-level statement actually
+// attributes an effect/edge here — so a pure top-level never gains a unit (pure units are omitted).
+// The qual mirrors sibling top-level units (`moduleOf(sf).<module>`); the bare local is `<module>`.
+function moduleUnit(sf) {
+  const mod = moduleOf(sf);
+  const qual = `${mod}.<module>`;
+  let rec = fns.get(qual);
+  if (!rec) {
+    rec = { local: "<module>", direct: new Set(), edges: new Set(), hosts: new Set(), tables: new Set(),
+            cmds: new Set(), paths: new Set(), blind: new Set(), incomplete: new Set(), why: new Set(),
+            entry: false, unitKind: "initializer",
+            loc: `${path.relative(rootDir, sf.fileName)}:1:1` };
+    fns.set(qual, rec);
+  }
+  return qual;
+}
 // nearest enclosing analyzed function (closures attribute to it — SEMANTICS §2)
 function enclosing(node) {
   for (let p = node; p; p = p.parent) {
@@ -1043,6 +1127,9 @@ function enclosing(node) {
     if (ts.isDecorator(p)) return null;
     const n = nodeName.get(p);
     if (n) return n;
+    // Reached the SourceFile with no named unit: a TOP-LEVEL executable statement. Attribute to the
+    // file's synthesized `<module>` initializer unit (minted lazily here) rather than dropping it.
+    if (ts.isSourceFile(p)) return moduleUnit(p);
   }
   return null;
 }
@@ -1654,18 +1741,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 +1924,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
@@ -2130,7 +2262,10 @@ for (const [name, rec] of fns) {
   // them are NOT in `inferred`, so it is a LOWER BOUND when this is non-empty. Omitted when none.
   if (rec.blind.size) entry.invisible = [...rec.blind].sort();
   if (rec.entry) entry.entryPoint = true;
-  if (rec.isCjsExport) entry.unitKind = "export"; // spec 0.5 draft, informative — per-unit, not by name
+  // unitKind (spec §2, informative — per-unit, not by name): the synthesized `<module>` initializer
+  // carries its own kind (set at mint), a CJS export is tagged "export".
+  if (rec.unitKind) entry.unitKind = rec.unitKind;
+  else if (rec.isCjsExport) entry.unitKind = "export"; // spec 0.5 draft, informative — per-unit, not by name
   functions.push(entry);
 }
 // `package` names what this report COVERS — a consumer chaining it registers coverage even when
@@ -2182,7 +2317,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
   }