candor-ts 0.28.2 → 0.29.0

package/scan.mjs

@@ -27,11 +27,12 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { execFileSync } from "node:child_process";
+import os from "node:os";
 import { parsePolicy, evaluatePolicy, scopeMatches, parseUnknownAliases, parseNetPartners, discoverConfigText,
          reasonClass, discoverConfigPath, policyVocabularyAnchor, policyErrorText, policyRefusalUnevaluated, policyUnreadable, policyZeroRules, fatalPolicyErrors, refusalVerdict,
          netClassResolver, resolveReasonClasses } from "./policy.mjs";
 import { unverifiedHoleRule, ruleUpgrade, byCodePoint, claimsToHaveJudgedNothing, reportCorruptKeys, entryCorruptKeys } from "./query-core.mjs";
-import { printAgents } from "./contract.mjs";
+import { printAgents, writeStdoutSync } from "./contract.mjs";
 import { isTestPath, kappa, kappaKnows, fsKind, commandHeadEffects, hostLiteral, tablesInSql,
          modelHostEffects, isModelHost, isModelSdkPackage, netClassesOf } from "./scan-core.mjs";
 import { emitSurface } from "./surface.mjs";
@@ -44,7 +45,45 @@ 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.28";
+const SPEC_VERSION = "0.29";
+
+// A TREE TOO DEEP TO WALK IS "COULD NOT EVALUATE" (exit 2), NEVER "FOUND A VIOLATION" (exit 1).
+//
+// The AST passes recurse (`visitCalls` → `ts.forEachChild` → `visitCalls`), so a deeply nested
+// expression exhausts the JS stack and node dies with an uncaught RangeError — a raw stack trace on
+// stderr and exit 1. Exit 1 is the code for A VIOLATION WAS FOUND. A wrapper that reads the exit code
+// (every CI gate does) is told the gate ran and failed the tree, when in fact nothing was analyzed and
+// no report was written. That is the wrong side of the fail-closed line: loud, but loudly WRONG.
+//
+// MEASURED, this machine, `export function f(): number { return (((…1…))); }`:
+//   depth 400 → pre-⟨0.29⟩ walked it, ⟨0.29⟩ overflows      the rung grew `visitCalls`'s frame
+//   depth 800 → BOTH overflow                               so the crash long predates the rung
+// The rung did not introduce this; it lowered the ceiling past the fuzzer's fixed 400-deep bait and
+// made a standing defect visible. Shrinking the frame back would return the fuzzer to green and leave
+// the wrong exit code live one nesting level further down — the fix that deletes the evidence.
+//
+// Narrow ON PURPOSE: only the stack-exhaustion RangeError is translated. Every other uncaught error
+// keeps the behaviour it had (stack on stderr, exit 1), because widening the net here would convert
+// unknown crashes into a tidy "could not evaluate" and hide the next real bug behind a clean message.
+//
+// RESIDUAL, stated because it is real and NOT measured: runaway recursion in THIS code exhausts the
+// stack exactly as a deep tree does, so such a bug would now be reported as "nests deeper than the
+// engine can walk", and nothing here can tell the two apart. It stays LOUD either way — exit 2, no
+// report, never a green — so the cost is a misleading message, not a wrong verdict. If this message
+// ever appears on a SHALLOW tree, the message is the bug and the recursion is where to look.
+process.on("uncaughtException", (e) => {
+  if (e instanceof RangeError && /Maximum call stack/i.test(e?.message ?? "")) {
+    console.error("candor-ts: this tree nests deeper than the engine can walk — the AST passes recurse, "
+      + "and the JS stack ran out before the scan finished. NOTHING was analyzed and no report was "
+      + "written, so this is 'could not evaluate' (exit 2), not a clean tree and not a violation. "
+      + "Re-run with a larger stack — `node --stack-size=4000 scan.mjs …` — or scan the offending "
+      + "file on its own to find it.");
+    process.exit(2);
+  }
+  console.error(e?.stack ?? String(e));
+  process.exit(1);
+});
+
 /** The `deps` / `CANDOR_DEPS` separator set — ASCII whitespace plus `:` and `,`.
  *
  * ONE CONSTANT BECAUSE TWO SPELLINGS WERE A SILENT GREEN. The §3.3.1 sink-over-input guard and the
@@ -130,6 +169,15 @@ See https://github.com/tombaldwin/candor`);
 // value-consuming skip handles, nor produce a "lying unknown flag" error for a real flag given first.
 const usage = "usage: candor-ts <dir | file.ts | tsconfig.json> [--out <prefix>] [--json] [--policy <file>] [--gate-json <file>] [--allow-js] [--workspace] [--agents] [--version] [--help]";
 const argv = process.argv.slice(2);
+// ⟨0.29⟩ THE PEEK, CHILD SIDE. Set only by this file on itself (see the peek block near the report
+// write). A peek is handed an EXPLICIT file list by its parent — the very files the parent excluded —
+// so it must analyse exactly those and apply NONE of the selection rules that excluded them.
+//
+// MEASURED before this existed: the parent handed the child a `*.test.ts` that runs `execSync("ls")`,
+// the child's own `isTestPath` filter dropped it from `fileNames`, and the scan published
+// `excluded: [{class:"test-file", peeked:true}]` with `outOfScope: []` under `deny Exec` — the peek
+// reporting that it read the file and found nothing, about a file it refused to open.
+const IS_PEEK = argv.includes("--peek-excluded");
 // Declared HERE, above the sink guard, because the guard calls `loadCandorConfig` and that reads
 // these: left below, they were in the temporal dead zone, the call threw, and the `catch` around it
 // swallowed the throw — so the config channel the guard exists to enumerate was silently empty and a
@@ -279,7 +327,7 @@ const distinctOutPrefixes = (all) => {
 //     candor-ts: 1 source file(s) failed to parse — NOT analyzed …
 //     candor-ts: wrote 0 effectful functions (1 analyzed, 1 files) to .candor/report.json   exit 0
 //   $ cat src/main.ts
-//     { "spec": "0.28", "ok": false, … }          ← the operator's SOURCE, unrecoverably replaced
+//     { "spec": "0.28", "ok": false, … }          ← the operator's SOURCE, unrecoverably replaced  (measured at spec 0.28, informative)
 //
 // Unrecoverable loss of the operator's own code, reported as SUCCESS — the run destroyed the file,
 // then dutifully disclosed the parse failure it had itself caused.
@@ -900,6 +948,11 @@ for (let i = 0; i < argv.length; i++) {
   // sibling's effects instead of reading pure (the candor-ts analog of rust `--deps`, SPEC §2).
   else if (a === "--workspace" || a === "--deps") wantWorkspace = true;
   else if (a === "--dep-inits") wantDepInits = true;
+  // ⟨0.29⟩ INTERNAL — set only by this file's own peek spawn (see IS_PEEK). Accepted here so the child
+  // does not take the unknown-flag path, which prints a refusal and, on the `--json` route, still emits a
+  // report: the parent parsed THAT as a successful peek of an empty file set. Deliberately absent from
+  // the usage string — it is not a way to scan a file list, it is the marker that this run IS a peek.
+  else if (a === "--peek-excluded") { /* consumed; behaviour lives in IS_PEEK */ }
   else if (a === "--out" || a === "--policy" || a === "--gate-json") {
     const v = argv[i + 1];
     if (v === undefined || v.startsWith("--")) {
@@ -1260,7 +1313,8 @@ function fromTsconfig(cfgPath, baseDir) {
     }
     names = [...new Set(names)];
   }
-  return names.filter((f) => !isTestPath(path.relative(baseDir, f)));
+  // ⟨0.29⟩ a peek analyses the list it was handed — see IS_PEEK.
+  return IS_PEEK ? names : names.filter((f) => !isTestPath(path.relative(baseDir, f)));
 }
 const stat = fs.existsSync(target) ? fs.statSync(target) : null;
 if (!stat) {
@@ -1292,7 +1346,7 @@ if (stat.isFile() && /tsconfig.*\.json$/.test(path.basename(target))) {
     (function walk(d) {
       for (const ent of fs.readdirSync(d, { withFileTypes: true })) {
         const p = path.join(d, ent.name);
-        if (isTestPath(path.relative(rootDir, p))) continue;
+        if (!IS_PEEK && isTestPath(path.relative(rootDir, p))) continue;   // ⟨0.29⟩ see IS_PEEK
         if (ent.isDirectory()) walk(p);
         else if (/\.[mc]?tsx?$/.test(ent.name) && !ent.name.endsWith(".d.ts")) fileNames.push(p);
         else if (allowJs && /\.[mc]?jsx?$/.test(ent.name) && !/\.min\.js$/.test(ent.name)) fileNames.push(p);
@@ -1300,6 +1354,49 @@ if (stat.isFile() && /tsconfig.*\.json$/.test(path.basename(target))) {
     })(rootDir);
   }
 }
+// ── ⟨0.29⟩ THE SCOPE: what this run chose not to open ──────────────────────────────────────────────
+// `analyzed.count` is a numerator; the selection above produced it and appeared nowhere, so a consumer
+// could not tell whether the answer was to the question they asked. Every exclusion here is deliberate —
+// `isTestPath`, `.d.ts`, the tsconfig's own `include` — and being deliberate is precisely why none was
+// measured: a limitation written as a comment reads as considered.
+//
+// Walked ONCE from the same root, skipping the directories nobody means. CLASSES WITH COUNTS, never file
+// lists: an excluded set that can contain node_modules is unbounded, and a gate that prints thousands of
+// paths is one people scroll past.
+const excludedFiles = [];
+{
+  const inSet = new Set(fileNames.map((f) => path.resolve(f)));
+  const SKIP_DIR = new Set(["node_modules", ".git", "dist", "build", "out", "coverage", ".next"]);
+  let rootIsDir = false;
+  try { rootIsDir = fs.statSync(rootDir).isDirectory(); } catch { /* not walkable */ }
+  if (rootIsDir) {
+    (function walkAll(d) {
+      let ents; try { ents = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+      for (const ent of ents) {
+        const q = path.join(d, ent.name);
+        if (ent.isDirectory()) { if (!SKIP_DIR.has(ent.name) && !ent.name.startsWith(".")) walkAll(q); continue; }
+        if (!PARSED_SOURCE_EXT.test(ent.name)) continue;   // another language is not this engine's claim
+        if (inSet.has(path.resolve(q))) continue;          // analyzed, therefore not excluded
+        const rel = path.relative(rootDir, q);
+        excludedFiles.push({
+          path: rel,
+          cls: ent.name.endsWith(".d.ts") ? "declaration-only"
+             : isTestPath(rel)            ? "test-file"
+             : usedTsconfig               ? "outside-the-tsconfig-program"
+             :                              "not-a-parsed-source",
+        });
+      }
+    })(rootDir);
+  }
+}
+const EXCLUDED_REASON = {
+  "declaration-only": "a `.d.ts` declares types and carries no body, so there is nothing to judge in it",
+  "test-file": "a test file describes what the HARNESS does, not what the project does",
+  "outside-the-tsconfig-program":
+    "the tsconfig's `include`/`exclude` did not name it, so it is not part of the program this scan "
+    + "analyzed — a file your build excludes may still run in CI or at install time",
+  "not-a-parsed-source": "not in this run's parse set",
+};
 if (fileNames.length === 0) {
   console.error(`candor-ts: no TypeScript sources under ${target}`);
   // An empty scan is an exit-2 cause like any other: a consumer reading the stream after it must not
@@ -1626,7 +1723,18 @@ if (wantDepInits) {
 // banner's) that drifted from this would make the engine distrust its OWN reports at the §2.1
 // staleness check (`d.candor?.version !== ENGINE_VERSION`), silently downgrading every chained dep.
 const ENGINE_VERSION = `candor-ts-${PKG_VERSION}`;
-const crossDeps = new Map(); // hash -> {inferred:Set, hosts:[], cmds:[], paths:[], tables:[]}
+const crossDeps = new Map(); // hash -> {inferred:Set, hosts:[], cmds:[], paths:[], tables:[], incomplete:Set}
+// ⟨0.29⟩ WAS A DEPENDENCY REPORT CHAINED INTO THIS RUN? Read by the gate to disclose the bound on the
+// NAME-matching rule kinds. Keyed on the report being LOADED, not on a hit being applied: a dependency
+// whose reached function is PURE produces no hit at all, and that is precisely the fixture that caught
+// this gap — the operator chained a dep either way, so the name rules are blind to those crossings either
+// way.
+let depReportsRead = 0;
+// ⟨0.29⟩ Keyed on a report being READ, not on entries being ingested and not on a hit being applied: a
+// dependency whose reached function is PURE yields a report with NO entries and produces no hit, which is
+// exactly the fixture that caught this gap twice while I narrowed the predicate. The operator chained a
+// dep either way, so the name-matching rules are blind to those crossings either way.
+const depChained = () => depReportsRead > 0;
 // Packages a loaded sibling report COVERS — exempt from the κ ledger even when a call joins no
 // entry (reports omit pure functions: the silence is the purity claim, SPEC §2 rule 3 — the
 // serde_json rule the Rust/JVM engines already carry; /code-review found TS missing it). Fed from
@@ -1908,6 +2016,7 @@ const corruptDepPkgs = new Set();
       // coverage the first withheld.
       const covers = stale ? staleDepPkgs : incomplete ? incompleteDepPkgs : corrupt ? corruptDepPkgs
                    : judgedNothing ? unjudgedDepPkgs : depCoveredPkgs;   // an untrusted, self-declared-incomplete, corrupt or unjudged report grants no coverage
+      depReportsRead += 1;   // ⟨0.29⟩ see `depChained` — a dep was chained, whatever it contained
       if (corrupt) console.error(`candor-ts: chained dependency report ${f} has ${corruptKeys.length} present-but-unparseable §2 key(s)`
         + ` — granted NO coverage, so calls into it read as INVISIBLE rather than pure (SPEC §2 ⟨0.24⟩): ${corruptKeys.join("; ")}`);
       if (typeof d.package === "string" && d.package) covers.add(d.package);
@@ -1934,7 +2043,7 @@ const corruptDepPkgs = new Set();
         if (!stale && entryCorruptKeys(e).length) continue;
         const hashPkg = e.hash.split("#")[0];
         if (hashPkg) covers.add(hashPkg);
-        const cell = crossDeps.get(e.hash) ?? { inferred: new Set(), invisible: new Set(), why: new Set(), hosts: [], cmds: [], paths: [], tables: [], netIncomplete: false };
+        const cell = crossDeps.get(e.hash) ?? { inferred: new Set(), invisible: new Set(), why: new Set(), hosts: [], cmds: [], paths: [], tables: [], incomplete: new Set(), netIncomplete: false };
         for (const x of stale ? ["Unknown"] : strs(e.inferred)) cell.inferred.add(x);
         // ⟨0.19⟩ THE REASON CLASS TRAVELS WITH THE UNKNOWN. Without this the join copied `inferred` and
         // `invisible` only, so a dependency's `Unknown[reflect:eval]` arrived at the consumer as a bare
@@ -1976,6 +2085,11 @@ const corruptDepPkgs = new Set();
         if (!stale) for (const b of strs(e.invisible)) cell.invisible.add(b);
         if (!stale) for (const m of ["hosts", "cmds", "paths", "tables"])
           for (const v of strs(e[m])) if (!cell[m].includes(v)) cell[m].push(v);
+        // ⟨0.29⟩ …AND THE INCOMPLETENESS, which §2's chained-join clause names in the same breath as the
+        // four surfaces above: "a join that carries the effect and drops `incomplete` lets a benign
+        // literal in the consumer certify what the dependency declared uncertifiable". That is not a
+        // hypothetical — it is the measured defect this field was added to close.
+        if (!stale) for (const v of strs(e.incomplete)) cell.incomplete.add(v);
         // ⟨0.20⟩ THE NET SURFACE'S INCOMPLETENESS TRAVELS WITH ITS HOSTS. `hosts` is a LOWER bound — the
         // producer marks a masked/hostless Net internally (`rec.incomplete`) and publishes that judgment as
         // `unknown-host` in `netClass`. The join copied the host LITERALS and not the judgment, so the
@@ -1986,8 +2100,15 @@ const corruptDepPkgs = new Set();
         // lines up, one field over: a fail-CLOSED marker failing OPEN at the boundary. No format rung: the
         // dependency already published the answer under the hash the consumer joins.
         //
-        // Read off `netClass` rather than an incompleteness field because `rec.incomplete` is deliberately
-        // INTERNAL family-wide (java/rust keep it out of the report too) — `unknown-host` IS its wire form.
+        // Read off `netClass` rather than the incompleteness field because `unknown-host` IS Net's wire
+        // form of it, and re-deriving one from the other would give the consumer two sources for one fact.
+        //
+        // ⟨0.29⟩ THE PARENTHETICAL THIS COMMENT USED TO CARRY WAS FALSE, and it cost a false all-clear.
+        // It said `rec.incomplete` is "deliberately INTERNAL family-wide (java/rust keep it out of the
+        // report too)". candor-rust has emitted a per-entry `incomplete` all along — SPEC §2 says so
+        // explicitly, in the clause beside the one this engine was following — so the premise for keeping
+        // it internal here was a statement about the family that was never true. The field is emitted and
+        // joined now; see the `entry.incomplete` site and the join two lines below.
         // Carries ONLY the incompleteness, never the classes: `known-telemetry`/`known-partner` are facts
         // about the hosts already copied above, and re-deriving them from those literals is what keeps the
         // consumer's `netClass` a function of the surface it can see (the property `netClassesOf` exists to
@@ -2214,13 +2335,17 @@ function packageManifestEffects(file) {
 }
 
 // ---- the literal surfaces (SPEC §2 hosts/cmds/paths/tables): the statically-decidable subset ------
-// Read ONLY from string literals at a classified call — informative, never complete, never inferred.
-function firstStringLiteral(node) {
-  for (const a of node.arguments ?? []) {
-    if (ts.isStringLiteralLike(a)) return a.text;
-  }
-  return null;
-}
+// Read ONLY from string literals at a classified call — informative, never complete, never inferred,
+// and ALWAYS from the argument POSITION that names the locator.
+//
+// ⟨0.29⟩ `firstStringLiteral` — "the first string literal anywhere in the args" — is DELETED. It was the
+// reader for every locator surface except the `Exec` head, and it produced the same defect in each one it
+// touched: `write(userPath, "/tmp/lit")` published the bytes as the path, `send(msg, …, addr)` published
+// the payload as the host, `query(userSql, "SELECT * FROM audit_log")` published a parameter as the
+// table — each a fabricated locator that ALSO suppressed the masking guard, so a benign-looking literal
+// certified a destination nobody could see. Removed rather than left unused: a "first literal anywhere"
+// in scope is how this class comes back at the next call site somebody adds. Use
+// `programHeadLiteral` / `urlArgLiteral` / `fsPathLiteral` / argument 0 for SQL.
 
 // Is this property/element access a SETTER target reached through a destructuring assignment —
 // `({ k: x.prop } = src)` or `[x.prop] = arr` (sweep [32])? Walk up through PropertyAssignment /
@@ -2242,13 +2367,13 @@ function isDestructuringAssignTarget(node) {
 }
 
 // The literal PROGRAM head a subprocess call NAMES — argv[0] specifically, never a later argument.
-// Unlike firstStringLiteral (the first literal ANYWHERE in the args), this refuses to refine when
+// Unlike a "first literal ANYWHERE in the args" reader, this refuses to refine when
 // the program (arg0) is a runtime value but a trailing arg is a literal whose basename hits the head
 // table: `spawn(toolVar, "curl")` must NOT fabricate Net — the literal is an argument, not the
 // program (spec §4 ⟨0.5⟩: the head is argv[0]). Mirrors candor-java programHeadLiteral and the Rust
 // is_cmd_naming_method gate. Returns null when arg0 is not a static string literal — the safe
-// direction. Used ONLY for the effect refinement, never to widen it; the cosmetic `cmds` surface
-// keeps firstStringLiteral.
+// direction. ⟨0.29⟩ the `cmds` SURFACE reads this too: it was documented as cosmetic, but `cmds` is what
+// `allow Exec <cmd>` gates on (AS-EFF-008).
 function programHeadLiteral(node) {
   const a0 = (node.arguments ?? [])[0];
   return a0 && ts.isStringLiteralLike(a0) ? a0.text : null;
@@ -2262,6 +2387,54 @@ function programHeadLiteral(node) {
 // 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"]);
+// ⟨0.29⟩ dgram's `send` puts the DESTINATION ADDRESS at position 2 or 4, and position 0 is the MESSAGE.
+// Falling through to `litAt(0)` read the payload as the endpoint: MEASURED,
+// `sock.send("telemetry.example", 0, 17, 53, dst)` published `hosts: ["telemetry.example"]` with NO
+// `incomplete`, so `allow Net telemetry.example` answered `policy ✓` at exit 0 over a UDP send to a
+// runtime-controlled address. A fabricated destination masking a real one — the `Fs` content-literal
+// defect of this same rung, one effect over, in the one API whose locator is neither first nor second.
+//
+// Node documents exactly two overloads:
+//   send(msg, port, address[, cb])                    → address at 2, a numeric port at 1
+//   send(msg, offset, length, port, address[, cb])    → address at 4, a numeric port at 3
+// so the position is recovered from the NUMERIC PORT that must precede it rather than guessed from the
+// argument count (a `cb` or an options object shifts nothing, and anything that does not match both
+// shapes returns null — the destination is then not statically visible and the caller fails closed).
+const isNumericLit = (a) => a && (ts.isNumericLiteral(a)
+  || (ts.isPrefixUnaryExpression(a) && ts.isNumericLiteral(a.operand)));
+function dgramSendAddressIndex(args) {
+  if (isNumericLit(args[3])) return 4;
+  if (isNumericLit(args[1])) return 2;
+  return -1;
+}
+// ⟨0.29⟩ THE Fs PATH LITERAL, read from the PATH ARGUMENT POSITION — the third application of the
+// `programHeadLiteral` discipline, and the one that never got it. The comment above says that rule was
+// "generalized from Exec to Net"; it stopped there, and `Fs` went on reading the first literal ANYWHERE
+// in the call. MEASURED: `fs.writeFileSync(userPath, "/tmp/lit")` published `paths: ["/tmp/lit"]` — the
+// BYTES BEING WRITTEN — so `allow Fs /tmp/lit` certified a write to a runtime-controlled destination at
+// exit 0, while candor-java and candor-swift failed closed on identical code.
+//
+// Returns { lit, complete }: `lit` is the path literal at position 0 when there is one, and `complete` is
+// false when ANY path position is not a literal. Two-path operations are why that is not one boolean:
+// `fs.copyFile("/safe", userPath)` has a literal at position 0 and still writes somewhere nobody can see.
+const FS_TWO_PATH_MEMBERS = new Set([
+  "copyFile", "copyFileSync", "cp", "cpSync", "rename", "renameSync",
+  "link", "linkSync", "symlink", "symlinkSync",
+]);
+function fsPathLiteral(node, member) {
+  const args = node.arguments ?? [];
+  const at = (i) => (args[i] && ts.isStringLiteralLike(args[i]) ? args[i].text : null);
+  const a0 = at(0);
+  const needsTwo = FS_TWO_PATH_MEMBERS.has(member);
+  const a1 = needsTwo ? at(1) : null;
+  const complete = a0 !== null && (!needsTwo || a1 !== null);
+  // EVERY literal path position, not just the first. Publishing position 0 and calling a
+  // both-literal two-path call COMPLETE certified the position it never published:
+  // `copyFileSync("/tmp/lit", "/tmp/dst")` under `allow Fs /tmp/lit` answered `policy ✓` at exit 0
+  // while writing `/tmp/dst`. candor-java and candor-swift publish both. Found by generating a case
+  // per node `fs` export and comparing against the four engines, not by re-reading this function.
+  return { lits: [a0, a1].filter((x) => x !== null), complete };
+}
 // CONST-STRING PROPAGATION (java constant-inlining parity): resolve a bare identifier that references a
 // `const NAME = "literal"` string to its literal value, and ONLY then. Returns the string, or null. The
 // soundness rule is strict: resolve ONLY when EVERY value-declaration of the symbol is an immutable
@@ -2368,7 +2541,7 @@ function literalHeadHostUrl(expr) {
   }
   return null;
 }
-function urlArgLiteral(node, member) {
+function urlArgLiteral(node, member, mod) {
   const args = node.arguments ?? [];
   const litAt = (i) => {
     const a = args[i];
@@ -2379,6 +2552,12 @@ function urlArgLiteral(node, member) {
     return resolveConstUrlString(a) ?? literalHeadHostUrl(a);
   };
   if (member && NET_URL_ARG1_MEMBERS.has(member)) return litAt(0) ?? litAt(1); // (port, host) or (path)
+  // ⟨0.29⟩ dgram `send` — keyed on the MODULE, because a bare `send` elsewhere legitimately takes its
+  // URL first and reading position 2/4 there would invent a host out of an unrelated argument.
+  if (member === "send" && /^(node:)?dgram$/.test(mod ?? "")) {
+    const i = dgramSendAddressIndex(args);
+    return i < 0 ? null : litAt(i);
+  }
   return litAt(0);
 }
 // Is arg0 a RUNTIME STRING expression whose host can't be known statically — a template, a string
@@ -3315,6 +3494,7 @@ function applyDepHit(rec, hit) {
   // layer down. Additive: it can only ADD `unknown-host`, never remove a class, so it never turns a firing
   // gate green.
   if (hit.netIncomplete) rec.incomplete.add("Net");
+  for (const eff of hit.incomplete ?? []) rec.incomplete.add(eff);   // ⟨0.29⟩ see the sibling join site
 }
 function unanswerableKey(decl) {
   if (!decl) return null;
@@ -4416,14 +4596,48 @@ function visitCalls(node) {
           // key on, so they read SILENT-PURE. `XMLHttpRequest.send`/`.open` issue the HTTP request; the
           // `EventSource`/`WebSocket` constructors open a connection on construction. Net. (Found by a
           // Net-deep sweep. The npm `ws` package is already κ-covered; this is the bare browser global.)
-          if (parent === "XMLHttpRequest" && (name === "send" || name === "open")) rec.direct.add("Net");
+          // ⟨0.29⟩ …AND THE HOST SURFACE, which these branches did not touch. Adding `Net` here bypasses
+          // the `eff === "Net"` block that captures the endpoint and — when it is a runtime value — marks
+          // the surface `incomplete`. So an invisible endpoint reached this way was recorded as Net with
+          // NO hedge, and any benign literal in the same function certified it. MEASURED, `policy ✓` at
+          // exit 0 under `allow Net ok.example`:
+          //     await fetch("https://ok.example/a");   // captures ok.example
+          //     new WebSocket(u);                      // Net, no host, no `incomplete`  ← goes anywhere
+          // That is the masking evasion the `incomplete` machinery exists to prevent, reached through the
+          // two Net APIs whose branches skip it. Same shape as the EventKit/`privacyKind` and
+          // `FS_USE_VERBS` gaps: a refinement the general path performs and a carve-out does not.
+          //
+          // POSITION, per the DOM signatures: `xhr.open(method, url)` puts the URL at argument 1 — the
+          // one API in this file whose locator is neither 0 nor a labelled argument. `send` carries NO
+          // url (the endpoint was fixed at `open`), so it is a USE-VERB: it must not mark `incomplete`,
+          // or every XHR with a perfectly visible `open` literal would fail closed.
+          if (parent === "XMLHttpRequest" && (name === "send" || name === "open")) {
+            rec.direct.add("Net");
+            if (name === "open") {
+              const u = (node.arguments ?? [])[1];
+              const lit = u && ts.isStringLiteralLike(u)
+                ? u.text : (u ? (resolveConstUrlString(u) ?? literalHeadHostUrl(u)) : null);
+              const h = lit ? hostLiteral(lit) : null;
+              if (h) { rec.hosts.add(h); for (const e of modelHostEffects(h)) rec.direct.add(e); }
+              else rec.incomplete.add("Net");
+            }
+          }
           // `new EventSource(url)` / `new WebSocket(url)`: the constructor is declared on an anonymous
           // `declare var` object type (symbol `__type`, no usable parent name), but reaching the es-lib
           // branch already proves the ctor resolved to lib.dom (not a project class shadowing the name),
           // so the constructed identifier is the real browser global.
           if (ts.isNewExpression(node)) {
             const ctorName = node.expression.getText();
-            if (ctorName === "EventSource" || ctorName === "WebSocket") rec.direct.add("Net");
+            if (ctorName === "EventSource" || ctorName === "WebSocket") {
+              rec.direct.add("Net");
+              // The URL is argument 0 of both constructors — see the XHR note above for the measurement.
+              const u = (node.arguments ?? [])[0];
+              const lit = u && ts.isStringLiteralLike(u)
+                ? u.text : (u ? (resolveConstUrlString(u) ?? literalHeadHostUrl(u)) : null);
+              const h = lit ? hostLiteral(lit) : null;
+              if (h) { rec.hosts.add(h); for (const e of modelHostEffects(h)) rec.direct.add(e); }
+              else rec.incomplete.add("Net");
+            }
           }
         } else {
           // The member token κ matches: the resolved declaration's name, EXCEPT a `new X()` call,
@@ -4450,9 +4664,23 @@ function visitCalls(node) {
           // allowlist discipline, generalized from Net to all 4 effects; sweep [11]). Fs: the fd/FileHandle
           // ops (fd came from open()); the path-taking fs.* fns are establishing. Exec: ChildProcess methods
           // (the command was fixed at spawn); the spawn fns are establishing.
+          // The node `fs` verbs whose FIRST argument is a DESCRIPTOR, not a path — the fd came from a
+          // prior `open()` whose path this analysis already saw, so their invisible destination is not a
+          // gap and marking them `incomplete` charges every buffered write in a real tree.
+          //
+          // ⟨0.29⟩ `readv`/`writev` (+Sync) were MISSING, and the ⟨0.29⟩ positional-literal fix is what
+          // made it visible: before it, `writev(fd, "/tmp/lit")` had its literal found ANYWHERE in the
+          // call and published as a path — a fabrication — so the set was never consulted for these four.
+          // Killing the fabrication moved them into the other wrong bucket. Found by generating a case
+          // per node `fs` export rather than reasoning about the list (24 fd verbs in node, 20 here).
+          //
+          // Forgetting a member here OVER-charges (safe); adding a path-taking verb by mistake
+          // UNDER-reports. An allowlist is the right shape for exactly that reason — the inverse of
+          // the denylist rule that governs the classifier surface.
           const FS_USE_VERBS = new Set(["write", "writeSync", "read", "readSync", "close", "closeSync",
             "fsync", "fsyncSync", "fdatasync", "fdatasyncSync", "ftruncate", "ftruncateSync", "fchmod",
-            "fchmodSync", "fchown", "fchownSync", "futimes", "futimesSync", "fstat", "fstatSync"]);
+            "fchmodSync", "fchown", "fchownSync", "futimes", "futimesSync", "fstat", "fstatSync",
+            "readv", "readvSync", "writev", "writevSync"]);
           const EXEC_USE_VERBS = new Set(["kill", "send", "disconnect", "ref", "unref"]);
           const netEstablishing = (member) =>
             CONNECTING_CTORS.has(ctorClassName) || NET_ESTABLISHING.has(member)
@@ -4516,7 +4744,7 @@ function visitCalls(node) {
             // 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 urlLit = urlArgLiteral(node, member, mod);
             const ollama = ollamaFromUrlArg(urlLit);
             if (ollama === "capture-model" || ollama === "capture-plain") {
               const h = hostLiteral(urlLit);
@@ -4544,7 +4772,16 @@ function visitCalls(node) {
           // 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);
+            // ⟨0.29⟩ THE SQL SLOT, never the first literal anywhere. Every string-SQL client puts the
+            // query at argument 0 (`query(text, values)`, `execute(sql, params)`, `raw(sql, bindings)`,
+            // `prepare(sql)`), so a literal in a LATER position is a parameter, a fallback query, a
+            // health-check string — data, not the statement being run. MEASURED:
+            // `db.query(userSql, "SELECT * FROM audit_log")` published `tables: ["audit_log"]` and, because
+            // a table HAD been captured, the masking guard below never fired — so `allow Db audit_log`
+            // certified a query whose SQL is a runtime value. The `Fs` and `Net` defects of this rung, in
+            // the fourth and last locator surface.
+            const a0 = (node.arguments ?? [])[0];
+            const lit = a0 && ts.isStringLiteralLike(a0) ? a0.text : null;
             const before = rec.tables.size;
             for (const t of lit ? tablesInSql(lit) : []) rec.tables.add(t);
             // ORM route: `this.userRepository.find(…)` — the receiver's `Repository<UserEntity>`
@@ -4564,12 +4801,27 @@ function visitCalls(node) {
             if (rec.tables.size === before && member !== "new") rec.incomplete.add("Db");
           }
           if (eff === "Exec") {
-            const lit = firstStringLiteral(node);
-            if (lit) rec.cmds.add(lit.trim().split(/\s+/)[0]); // cosmetic cmds surface (any literal)
+            // ⟨0.29⟩ `cmds` reads argv[0] too. It was documented as "the cosmetic cmds surface (any
+            // literal)", but `cmds` is precisely what `allow Exec <cmd>` gates on (AS-EFF-008) — nothing
+            // cosmetic about it. No node API places a bare string after the head (args are an array,
+            // options an object), so this changes no measured behaviour today; it removes the hazard for
+            // the next exec-like wrapper whose second argument is a string, which is how the identical
+            // defect reached `Fs`, `Net` and `Db` in this same rung.
+            // ⟨0.29⟩ A USE-VERB NAMES NO PROGRAM, and its argument 0 is not a head. `EXEC_USE_VERBS`
+            // already says so — it is consulted for the `incomplete` branch below and was NOT consulted
+            // here, so `child.send(msg)` (IPC to an ALREADY-spawned child) read its MESSAGE as argv[0].
+            // MEASURED: `ch.send("ls")` published `cmds: ["ls"]` and certified under `allow Exec ls`
+            // though the function executes nothing, and `ch.send("curl")` FABRICATED `Net` — a function
+            // that makes no network call reported as performing one, which `deny Net` then fires on.
+            // That is exactly what the doc comment above forbids ("`spawn(toolVar, "curl")` must NOT
+            // fabricate Net — the literal is an argument, not the program"); the rule was written for the
+            // argument POSITION and never covered the same hazard reached through the RECEIVER.
+            const lit = EXEC_USE_VERBS.has(member) ? null : programHeadLiteral(node);
+            if (lit) rec.cmds.add(lit.trim().split(/\s+/)[0]);
             // a known literal head refines the cliff (curl→Net, candor→Fs/Env); Exec stays. The head
             // MUST be argv[0] (programHeadLiteral), NOT any literal arg: `spawn(toolVar, "curl")`
             // names no static program, so its trailing literal must not fabricate Net (spec §4).
-            const head = programHeadLiteral(node);
+            const head = lit;
             if (head) for (const e of commandHeadEffects(head)) rec.direct.add(e);
             // masking (sweep [11]): an Exec call whose program head is NOT a static literal (runtime
             // command) leaves the command invisible. Establishing = the spawn fns; ChildProcess use-verbs
@@ -4577,12 +4829,16 @@ function visitCalls(node) {
             else if (!EXEC_USE_VERBS.has(member)) rec.incomplete.add("Exec");
           }
           if (eff === "Fs") {
-            const lit = firstStringLiteral(node);
-            const pathCaptured = lit && /[/\\]|^[.~]/.test(lit); // path-shaped literals only
-            if (pathCaptured) rec.paths.add(lit);
+            // ⟨0.29⟩ the PATH POSITION, never the first literal anywhere — see fsPathLiteral.
+            const { lits, complete } = fsPathLiteral(node, member);
+            const captured = lits.filter((l) => /[/\\]|^[.~]/.test(l)); // path-shaped literals only
+            const pathCaptured = captured.length > 0 && captured.length === lits.length;
+            for (const l of captured) rec.paths.add(l);
             // masking (sweep [11]): a path-taking fs.* call whose path is NOT a captured literal (runtime
             // path) leaves it invisible. fd/FileHandle USE-verbs (fd came from a prior open()) are excluded.
-            else if (!FS_USE_VERBS.has(member)) rec.incomplete.add("Fs");
+            // ⟨0.29⟩ `complete` also covers a two-path op whose SECOND path is runtime, which a captured
+            // position-0 literal would otherwise certify.
+            if (!(pathCaptured && complete) && !FS_USE_VERBS.has(member)) rec.incomplete.add("Fs");
           }
           // CANDOR_DEPS: an unclassified call into a package with a loaded sibling report inherits
           // that function's recorded transitive effects (+ literal surfaces) by `hash`.
@@ -5285,7 +5541,7 @@ function depInitCell(pkg, subpath) {
   let cell = null;
   for (const [h, c] of crossDeps) {
     if (!h.startsWith(`${pkg}#`) || !h.endsWith(".<module>")) continue;
-    cell ??= { inferred: new Set(), invisible: new Set(), why: new Set(), hosts: [], cmds: [], paths: [], tables: [], netIncomplete: false };
+    cell ??= { inferred: new Set(), invisible: new Set(), why: new Set(), hosts: [], cmds: [], paths: [], tables: [], incomplete: new Set(), netIncomplete: false };
     for (const e of c.inferred) cell.inferred.add(e);
     for (const b of c.invisible) cell.invisible.add(b);
     for (const w of c.why ?? []) cell.why.add(w);
@@ -5398,6 +5654,9 @@ function resolveDepEntryKey(pkg, subpath) {
     // arm copies no `hosts` (a module unit's literals are not this caller's), so today it can only turn a
     // hostless Net that a sibling literal in THIS body would have certified back into `unknown-host`.
     if (cell.netIncomplete) rec.incomplete.add("Net");
+    // ⟨0.29⟩ every OTHER effect the dependency could not locate, carried the same way. Without this the
+    // join copies the dep's Fs and drops its "I could not see where", which is the fail-open above.
+    for (const eff of cell.incomplete ?? []) rec.incomplete.add(eff);
   }
   for (let changed = true; changed; ) {
     changed = false;
@@ -5557,7 +5816,11 @@ for (const m of ["hosts", "tables", "cmds", "paths", "blind", "incomplete", "fsK
 // ---- emit: the §2 envelope (effect-free items omitted) + the §2.2 sidecar (EVERY fn a key) --------
 // ⟨0.20⟩ Net destination-class partners from `.candor/config` — read ONCE here, used by the report's per-fn
 // `netClass` field (below) and the gate (deny Net[unknown-host]); the SAME set both surfaces resolve.
-const netPartners = parseNetPartners(discoverConfigText(target));
+// ⟨0.29⟩ …and a malformed `net-partner` line is DISCLOSED rather than kept as a junk host that matches
+// nothing for the rest of the run. Printed once, here, beside the other config diagnostics.
+const netPartnerErrs = [];
+const netPartners = parseNetPartners(discoverConfigText(target), netPartnerErrs);
+for (const e of netPartnerErrs) console.error(`candor-ts: ${e.why} — ${e.raw}`);
 const functions = [];
 for (const [name, rec] of fns) {
   const inf = [...inferred.get(name)].sort();
@@ -5592,6 +5855,19 @@ for (const [name, rec] of fns) {
   if (inf.includes("Db") && rec.tables.size) entry.tables = [...rec.tables].sort();
   if (inf.includes("Exec") && rec.cmds.size) entry.cmds = [...rec.cmds].sort();
   if (inf.includes("Fs") && rec.paths.size) entry.paths = [...rec.paths].sort();
+  // ⟨0.29⟩ SPEC §2 `incomplete` — the effects whose LOCATOR this fn could not determine. Omitted when
+  // empty, so a scan that determined everything is byte-identical to a pre-rung report.
+  //
+  // THIS ENGINE USED TO KEEP IT INTERNAL, on a premise about the family that was FALSE. The comment at the
+  // dep-join said `rec.incomplete` is "deliberately INTERNAL family-wide (java/rust keep it out of the
+  // report too)" — candor-rust has emitted it all along, and SPEC §2 says so in the clause right beside
+  // the one this engine was following. MEASURED, and the cost is a false all-clear on a configured gate:
+  // a dependency whose `Fs` path is a runtime value published NOTHING to say so, so a consumer that also
+  // writes ONE allowed literal joined `paths: ['/tmp/lit']` with no incompleteness marker and
+  // `allow Fs /tmp/lit` answered `policy ✓`. candor-rust, over the identical shape, charges AS-EFF-008.
+  // An absent `paths` is overloaded between "reaches no path" and "reaches a path I could not see", and
+  // this field is the only thing that separates them.
+  if (rec.incomplete.size) entry.incomplete = [...rec.incomplete].sort();
   // SPEC §2 `fs` — the read/write kinds this fn's OWN Fs calls revealed. Gated on `inferred` carrying Fs
   // (the spec: "applies only when `inferred` contains `Fs`") and omitted when empty.
   //
@@ -6051,7 +6327,10 @@ function fnv1aHex(sortedQuals) {
 // so it says so. A producer MUST NOT list a surface it does not compute — that turns "unimplemented" into a
 // false "undetermined", which is the inversion the field exists to prevent.
 const envelope = { candor: { version: ENGINE_VERSION, toolchain: `node-${process.versions.node}`, spec: SPEC_VERSION },
-                   resolves: ["fs"], package: pkgName, functions };
+                   // ⟨0.29⟩ `incomplete` joins `resolves`: an optional per-function refinement surface
+                   // whose absence is overloaded the way `fs`'s was — "does not compute undetermined
+                   // locators" vs "computed them and found none". This engine computes it, so it says so.
+                   resolves: ["fs", "incomplete"], package: pkgName, functions };
 // ⟨0.15 staged⟩ the κ-coverage ledger as DATA (COVERAGE-DESIGN.md §1): ONE sorted form (count desc,
 // name asc — exactly the stderr line's order) feeds the envelope field, the stderr receipt below, and
 // the --gate-json advisory, so the three can never tell different stories.
@@ -6093,9 +6372,153 @@ for (const [name, rec] of fns) cg[name] = [...rec.edges].sort();
 // ⟨0.28⟩ …and through `writeSinkAtomic`, so a symlinked or multiply-linked destination is written where
 // the operator points rather than replaced. Reports have the same layout exposure as verdicts.
 const writeAtomic = (file, text) => writeSinkAtomic(file, text);
+// ── ⟨0.29⟩ THE PEEK ───────────────────────────────────────────────────────────────────────────────
+// Read the files this run deliberately did NOT judge, and say so when they hold an effect the policy
+// DENIES. The verdict does not move: `outOfScope` is its own kind and never a violation, because a file
+// the gate declined to judge must not decide an exit code.
+//
+// A CHILD `scan.mjs`, not a second analysis path. candor-rust buys this by recursing into `scan_one`;
+// this engine is a script rather than a callable function, so the same guarantee comes from the same
+// BINARY over a different file set. That identity is the design constraint, not a convenience: a bespoke
+// second pass would be a SECOND OPINION, and a drifted second opinion reported as a warning is worse
+// than no warning — the reader cannot tell a real finding from two code paths disagreeing. The child is
+// given no policy, so it cannot gate and cannot recurse.
+//
+// PLACED HERE, ABOVE THE WRITE, on purpose. The gate block runs AFTER the envelope is serialised, so
+// computing this there would have put the finding on stderr and left it out of the artifact — the split
+// ⟨0.26⟩ calls worse than saying nothing. It reads the policy itself rather than borrowing the gate's
+// parse: one extra read of the same bytes through the same `parsePolicy`, not a second interpretation.
+//
+// POLICY-SCOPED AND POLICY-BOUNDED, which is the whole reason it stays quiet. No policy ⇒ the key is
+// ABSENT, because nothing was asked and `[]` would be a claim. With a policy, only effects that policy
+// DENIES are reported — otherwise the noise floor is "everything you excluded".
+let outOfScopeFindings = null;
+// ⟨0.29⟩ DID THE PEEK ACTUALLY READ ANYTHING? `peeked` was a constant of the exclusion CLASS, so a peek
+// that never ran, could not spawn, or produced unparseable output still published `peeked: true` beside
+// `outOfScope: []` — byte-identical to a clean peek, and the ⟨0.26⟩ partial-manifest failure inside the
+// rung built to prevent it. It is an outcome now.
+let peekRead = false;
+// ⟨0.29⟩ …AND DID IT READ THEM ALL? A child report the parent could PARSE is a different fact from every
+// excluded file having been opened. The child publishes its own ⟨0.21⟩ `unanalyzed` manifest and this
+// code read only `functions`, so an excluded file that failed to parse INSIDE the peek produced
+// `peeked: true` beside `outOfScope: []` — the same overclaim one comment up, one level down. `peeked` is
+// per CLASS, so the answer is too: a class is peeked only when no file of that class went unread.
+const peekUnread = new Set();
+let peekUnattributed = false;
+if (policyPath && excludedFiles.length) {
+  let denied = new Set();
+  try {
+    const pol = parsePolicy(fs.readFileSync(policyPath, "utf8"), {});
+    // ⟨0.29⟩ A REFUSED POLICY LEAVES THE KEY ABSENT (SPEC §2). The peek is a producer reading the policy,
+    // so §3.1 binds it exactly as it binds the gate: over a policy no route will honour, `outOfScope: []`
+    // claims a look taken against rules that never stood, and the `denied` set it would look for is the
+    // parser's SALVAGE of an unhonourable file — the rewriting `fatalPolicyErrors` exists to refuse.
+    // candor-java already withheld here; this engine, candor-rust and candor-swift did not.
+    if (!fatalPolicyErrors(pol.errors).length) {
+      denied = new Set((pol.deny ?? []).flatMap((r) => r.effects ?? []));
+    }
+  } catch { /* an unreadable policy is the gate's business to refuse, not the peek's */ }
+  if (denied.size) {
+    outOfScopeFindings = [];
+    const peekDir = fs.mkdtempSync(path.join(os.tmpdir(), "candor-ts-peek-"));
+    try {
+      fs.writeFileSync(path.join(peekDir, "tsconfig.json"), JSON.stringify({
+        compilerOptions: { target: "es2022", module: "esnext", allowJs: true, noEmit: true },
+        files: excludedFiles.map((e) => path.resolve(rootDir, e.path)),
+      }));
+      const out = execFileSync(process.execPath,
+        [fileURLToPath(import.meta.url), path.join(peekDir, "tsconfig.json"), "--json",
+         "--peek-excluded"],
+        // ⟨0.29⟩ `timeout` beside `maxBuffer`: the peek re-parses exactly the files this engine has never
+        // parsed — vendored trees, generated code, declaration bundles — i.e. the inputs least likely to
+        // have been exercised. Without a deadline one pathological file turns into a hung scan and a hung
+        // CI job, which contradicts this feature's own rule that a peek which cannot run must not fail
+        // the gate: hanging is the one failure that stops the gate completing at all. On timeout
+        // `execFileSync` throws, the catch below leaves the findings as far as they got, and `peekRead`
+        // stays false so no class claims to have been read.
+        { encoding: "utf8", maxBuffer: 1 << 28, timeout: 120_000,
+          stdio: ["ignore", "pipe", "ignore"] });
+      const doc = JSON.parse(out);
+      peekRead = true;   // the child returned a report this run could read — see `peekRead`
+      for (const u of Array.isArray(doc.unanalyzed) ? doc.unanalyzed : []) {
+        const where = String(u?.path ?? "");
+        const hit = excludedFiles.find((e) => where.endsWith(e.path)
+                                           || where.endsWith(path.basename(e.path)));
+        // The peek walks ONLY excluded files, so an unread path matching no exclusion is one this code
+        // cannot attribute — fail closed across every class rather than let one unattributable file leave
+        // all of them claiming completeness.
+        if (hit) peekUnread.add(hit.cls); else peekUnattributed = true;
+      }
+      for (const f of doc.functions ?? []) {
+        const hits = (f.inferred ?? []).filter((e) => denied.has(e));
+        if (!hits.length) continue;
+        // NAME IT FROM THE PROJECT, NOT FROM THE CHILD'S TEMP ROOT. The child's tsconfig lives in a
+        // temp directory, so it derives module qualifiers from THAT root and the fn came out as a
+        // dotted absolute path — accurate, unreadable, and pointing at a directory that no longer
+        // exists by the time anyone reads it. The project-relative path is already known here (it is
+        // what was excluded), so match on basename and report the path we already trust.
+        const childLoc = (f.loc ?? "").split(":")[0] ?? "";
+        const hit = excludedFiles.find((e) => childLoc.endsWith(e.path)
+                                           || childLoc.endsWith(path.basename(e.path)));
+        const where = hit?.path ?? childLoc;
+        const cls = hit?.cls ?? "excluded";
+        outOfScopeFindings.push({
+          fn: f.fn.split(".").pop() ?? f.fn, path: where, effects: hits, class: cls,
+          reason: `OUTSIDE this scan's scope (${cls}) — the gate did NOT judge it. `
+                + "The effect is real; the verdict does not account for it.",
+        });
+      }
+      outOfScopeFindings.sort((a, b) => (a.path + a.fn).localeCompare(b.path + b.fn));
+    } catch {
+      // A PEEK THAT CANNOT RUN MUST NOT FAIL THE GATE — it is advisory by construction, and turning a
+      // child-process failure into a red gate would make the safest thing an operator can do (add a
+      // policy) the thing that breaks their build. It stays `[]`: a policy WAS configured, so the key is
+      // a real answer, and "we looked and found nothing" is what an empty list says.
+    } finally {
+      fs.rmSync(peekDir, { recursive: true, force: true });
+    }
+  }
+}
+if (outOfScopeFindings) {
+  envelope.outOfScope = outOfScopeFindings;
+  // SAY IT ON STDERR TOO. The report block is for machines; an operator reading `policy ✓` needs to know
+  // in the same breath that a file this scan did not judge holds the effect they denied.
+  for (const f of outOfScopeFindings) {
+    console.error(`candor-ts: ⚠ ${f.fn} performs ${f.effects.join("+")} — OUTSIDE this scan's scope `
+                + `(${f.class}), so the gate did NOT judge it.`);
+    if (f.path) console.error(`             ${f.path}`);
+  }
+  if (outOfScopeFindings.length) {
+    console.error("             The verdict does not account for "
+      + (outOfScopeFindings.length === 1 ? "it." : `these ${outOfScopeFindings.length}.`));
+  }
+}
+
+// ⟨0.29⟩ THE SCOPE, BUILT AFTER THE PEEK — `peeked` is an OUTCOME, so this block cannot be assembled
+// until the peek has run. It sat above the peek and read `peekRead` before anything could set it, which
+// is the ordering bug the flag's own purpose makes fatal: a field that exists to say whether a read
+// happened, computed before the read. Emitted even when EMPTY — ⟨0.27⟩ makes zero-match a positive
+// statement, and ⟨0.26⟩ makes an ABSENT key mean "this producer cannot answer".
+{
+  const byClass = new Map();
+  for (const e of excludedFiles) byClass.set(e.cls, (byClass.get(e.cls) ?? 0) + 1);
+  envelope.excluded = [...byClass.entries()].sort((a, b) => a[0].localeCompare(b[0]))
+    .map(([cls, count]) => ({ class: cls, count,
+                              // `peekUnread` subtracts the classes the peek RAN over and could not read:
+                              // parse failures are per file, so the claim is per class.
+                              peeked: peekRead && !peekUnattributed && !peekUnread.has(cls),
+                              reason: EXCLUDED_REASON[cls] ?? `excluded (${cls})` }));
+}
+
 // --json: print the §2 envelope to STDOUT instead of writing the report files (matches candor-scan/Rust).
 if (wantJson) {
-  console.log(JSON.stringify(envelope, null, 1));
+  // writeStdoutSync, NOT console.log. MEASURED over a 400-file fixture with a violating policy: 95281
+  // bytes to a FILE and valid JSON, **65536 bytes through a PIPE and a JSONDecodeError** — exactly the
+  // pipe buffer, exit 1 either way, nothing on stderr. console.log is asynchronous on a pipe and the
+  // process.exit() sites below discard what is still buffered. This is the machine-consumer path
+  // (`candor-ts src --json --policy p | jq`), so the loss is silent and the document is invalid, which
+  // is worse than the `--agents` truncation that got this class fixed in the first place.
+  writeStdoutSync(JSON.stringify(envelope, null, 1) + "\n", "--json");
   // ⟨0.28⟩ REPORT STREAM LATCH — a successful envelope went to stdout, so a later exit-2 site (baseline
   // corrupt, policy refusal, gate NOT certified over unanalyzed) MUST NOT also write a fail-closed
   // placeholder there. Two documents on one stream parses as neither — the same shape the two-stream
@@ -6509,7 +6932,10 @@ if (policyPath !== null) {
       // `deny Fs`, absent from the exit-1 document's list, as evaluated-and-passed. The SHARED builder,
       // so this document and `gate --report`'s stay byte-equal (§3.1's acceptance test for the routes).
       policyRefusal = { why, unevaluated: policyRefusalUnevaluated(text, policyErrs) };
-    } else if (!gatePolicy.deny.length && !gatePolicy.allow.length && !gatePolicy.forbid.length) {
+    // ⟨0.29⟩ …counting `only` too: an `only`-only policy is a LIVE gate, and refusing it here would
+    // be the ⟨0.28⟩ fail-closed guard turned into a false refusal by the rung that added the kind.
+    } else if (!gatePolicy.deny.length && !gatePolicy.allow.length && !gatePolicy.forbid.length
+               && !(gatePolicy.only ?? []).length) {
       // ⟨0.28⟩ A CONFIGURED POLICY THAT YIELDED ZERO RULES IS A BROKEN GATE CONFIG (SPEC §6.2) — the same
       // refusal posture as the two branches above, and for the reason §6.2 already gives for an unreadable
       // FILE: "a typo'd policy path that runs green is a gate that silently passes everything". MEASURED
@@ -6560,6 +6986,33 @@ if (policyPath !== null) {
       // code is deliberately untouched: a zero-match rule is legitimate when one policy is shared across
       // repositories and a layer exists in only some of them, so refusal would make a shared policy
       // unusable. Printed before the violations so a typo'd layer name is visible above the verdict.
+      // ⟨0.29⟩ THE NAME RULES STOP AT THE SCAN BOUNDARY, AND NOW SAY SO. `forbid A -> B` and
+      // `only A -> B …` are matched over the call graph; a chained dependency contributes EFFECTS, not
+      // EDGES, so a function that calls into a dep has an EMPTY adjacency and the crossing is invisible.
+      // MEASURED: with a dep chained, `only model -> util` answered `policy ✓` over
+      // `model.viaDep() -> deplib.infra.dbRead()` while a LOCAL unpermitted scope in the same run fired
+      // AS-EFF-011 — so the rule was armed and the boundary, not the rule, was the gap.
+      //
+      // WORSE FOR `only` THAN FOR `forbid`, which is why this is disclosed rather than left implicit:
+      // `forbid` asks whether ONE named crossing is present, so missing a dep crossing under-reports one
+      // prohibition; `only` asserts A reaches the listed scopes AND NOTHING ELSE — a COMPLETENESS claim —
+      // and it exists precisely because `forbid` fails open. A package that calls a third-party library is
+      // not a leaf, and without this line the gate called it one.
+      //
+      // DISCLOSURE, NOT A VERDICT CHANGE, and not a re-scoping either: making the rules cross would need
+      // dep-report EDGES, and it would force operators to enumerate third-party scopes in an `only` list —
+      // the enumeration-that-rots that form was designed to escape. The ⟨0.29⟩ `outOfScope` posture
+      // exactly: say what was not judged, leave the exit code alone.
+      if (depChained()) {
+        const named = [...(gatePolicy.forbid ?? []), ...(gatePolicy.only ?? [])];
+        if (named.length) {
+          console.error(`candor-ts: ⚠ ${named.length} name-matching rule(s) (\`forbid\`/\`only\`) were `
+            + "matched over THIS scan's call graph only — a chained dependency contributes effects, not "
+            + "call edges, so a crossing INTO a dependency is invisible to them. `deny`/`allow` still "
+            + "cross (effects propagate); an `only` rule cannot certify that a package is a leaf when it "
+            + "calls into one of its dependencies.");
+        }
+      }
       for (const raw of gateOut.zeroMatch ?? []) {
         console.error(`candor: policy rule matched NO function — \`${raw}\`. It was evaluated and bound `
           + `nothing, so it cannot have caught anything. Legitimate when one policy is shared across `