candor-ts 0.29.1 → 0.30.0

package/AGENTS.md

@@ -21,7 +21,7 @@ the TypeScript-specific production + query surface.
 > **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.29)."*
+> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.30)."*
 > 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`.
 >
@@ -292,3 +292,12 @@ far as candor could see, but it could not see through these" (a LOWER bound), no
 dependency can opt out of that blind spot by declaring `"candorEffects": ["Net", …]` in its
 `package.json` (the §5.1 effect manifest, read declared-not-verified) — its calls then classify to
 the declared set instead of contributing nothing.
+
+- **⟨0.30⟩ A GREEN GATE CAN NOW EXIT 2 — read `outOfScope` before you trust a pass.** When a policy is
+  configured, candor also reads the files the scan EXCLUDED (test files, build scripts, archives under the
+  root, files outside the build's program) and reports any that perform an effect the policy DENIES, under
+  the report's `outOfScope` key. A non-empty block makes the verdict `ok:false`, `incomplete:true`, exit 2
+  — *"I could not see enough of this tree to certify it"*, which is NOT the same as "your code violates":
+  those functions are never in `violations`, because the gate did not judge them. Branch on `incomplete`
+  to tell the two apart. An absent key means the producer was never asked (no policy at scan time), and an
+  empty one means asked-and-clear.

package/README.md

@@ -192,7 +192,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.29" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
+| `{ candor: { version, toolchain, spec: "0.30" }, 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 |
 
@@ -210,7 +210,7 @@ read the Rust source".
 
 ## Status
 
-0.28.0, speaking candor-spec 0.29: the analysis core, the gate (`--policy` / `--gate-json` /
+0.30.0, speaking candor-spec 0.30: the analysis core, the gate (`--policy` / `--gate-json` /
 `.candor/config`), the full §3.1 query surface (including `containment`, `blindspots`, the
 `--include-unknown` dispatch frontier, and ⟨0.24⟩ `gate --report` — the gate applied to an EXISTING
 report, byte-equivalent to `scan --policy`'s verdict), the MCP server, the LSP server, and the watch loop are

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "candor-ts",
-  "version": "0.29.1",
-  "description": "candor for TypeScript \u2014 per-function side effects, transitively, with a policy gate (candor-spec 0.29)",
+  "version": "0.30.0",
+  "description": "candor for TypeScript \u2014 per-function side effects, transitively, with a policy gate (candor-spec 0.30)",
   "type": "module",
   "dependencies": {
     "@types/node": "^25.9.2",
@@ -66,6 +66,7 @@
     "verify-emit.mjs",
     "verify-loader.mjs",
     "verify-syscall.mjs",
+    "scratch.mjs",
     "sensitivity.mjs",
     "transitive-recall.mjs"
   ],

package/query-core.mjs

@@ -557,7 +557,16 @@ export function reportCompleteness(prefix) {
   // want different repairs and because `judgedNothing` is PINNED to "reports declaring `analyzed.count:
   // 0`", which a row-3 report is not.
   return { unanalyzed: reportUnanalyzed(prefix), judgedNothing: reportJudgedNothingFiles(prefix),
-           noManifest: reportNoManifestFiles(prefix), unreadable: reportUnreadableFiles(prefix) };
+           noManifest: reportNoManifestFiles(prefix),
+           // ⟨0.30⟩ the peek's findings, so an advisory verb keying `--strict` on this object is at least
+           // as pessimistic as the gate over the same bytes (the ⟨0.24⟩ MUST).
+           ...(() => {
+             const o = reportOutOfScope(prefix);
+             // A corrupt key rides `unreadable`, which is ALREADY an arm of the strict exit — so the
+             // fail-closed path is the one the ⟨0.24⟩ rule established, not a new one beside it.
+             return { outOfScope: o.findings,
+                      unreadable: [...reportUnreadableFiles(prefix), ...o.corrupt] };
+           })() };
 }
 
 /**
@@ -574,7 +583,38 @@ export function reportCompleteness(prefix) {
  * exit code; see `advisoryAnswer`, whose exit-bearing callers key `--strict` on manifest + unreadable.
  */
 export const mustHedge = (c) => !!(c && (c.unanalyzed?.length || c.judgedNothing?.length
-                                         || c.noManifest?.length || c.unreadable?.length));
+                                         || c.noManifest?.length || c.unreadable?.length
+                                         || c.outOfScope?.length));
+
+/** ⟨0.30⟩ The peek's findings across the reports under a locator. Read leniently HERE (a malformed key is
+ *  the gate's refusal to make, and this feeds a disclosure) but non-emptiness raises the same hedge the
+ *  gate raises, which is what keeps the advisory verbs bound to it. */
+export function reportOutOfScope(prefix) {
+  const out = [];
+  // ACCEPT A FULL PATH AS WELL AS A PREFIX. `reportFilesAt` appends `.json`, so a locator that already
+  // ends in `.json` — which is exactly what `--report <file>` gives — expanded to nothing and this
+  // returned `[]`. The hedge then never fired and `unverified --strict` certified a report the gate
+  // refuses. `loadGateReport` tolerates both spellings, so the two disagreed about the same locator.
+  const files = (prefix.endsWith(".json") && fs.existsSync(prefix)) ? [prefix] : reportFilesAt(prefix);
+  const corrupt = [];
+  for (const f of files) {
+    try {
+      const d = JSON.parse(fs.readFileSync(f, "utf8"));
+      // PRESENT-BUT-NOT-A-LIST IS CORRUPT, and it must reach the ADVISORY verbs too. Read leniently here,
+      // the key vanished and `--strict` certified a report `gate --report` refuses at exit 2 — the ⟨0.24⟩
+      // relation broken one shape over from where it was closed. The gate already refuses this; an
+      // advisory verb that does not is LESS pessimistic than the gate over the same bytes.
+      if (d?.outOfScope !== undefined && !Array.isArray(d.outOfScope)) { corrupt.push(f); continue; }
+      if (Array.isArray(d?.outOfScope)) {
+        for (const e of d.outOfScope) {
+          if (e && typeof e === "object") out.push(e);
+          else { corrupt.push(f); break; }
+        }
+      }
+    } catch { /* unparseable TEXT is `unreadable`'s business, not this key's */ }
+  }
+  return { findings: out, corrupt };
+}
 
 /**
  * ⟨0.28⟩ The disclosure KEYS, defined ONCE, for spreading into a verb's answer document — `{}` when there
@@ -740,7 +780,7 @@ export function loadReport(prefix) {
  */
 export function loadGateReport(prefix) {
   const files = reportFilesAt(prefix);
-  const functions = [], unanalyzed = [], cov = new Map(), corrupt = [];
+  const functions = [], unanalyzed = [], cov = new Map(), corrupt = [], outOfScope = [];
   let hardFail = false, analyzed = 0;
   // ⟨0.24⟩ did the report handed to the gate judge ANYTHING? Per FILE, then ANDed across the multi-report
   // siblings, because the union of several reports has judged something as soon as ONE of them has — the
@@ -799,6 +839,25 @@ export function loadGateReport(prefix) {
         else unanalyzed.push({ path: typeof u.path === "string" ? u.path : "", reason: typeof u.reason === "string" ? u.reason : "" });
       }
     }
+    // ⟨0.30⟩ THE PEEK'S FINDINGS, off the report rather than recomputed — this route CANNOT peek (it has
+    // no target, only a document), and that is exactly why the field rides the report. Concatenated across
+    // siblings like `functions` and `unanalyzed` above. ABSENT stays absent: ⟨0.26⟩ makes an absent key
+    // "this producer cannot answer", and a report produced with no policy was never asked, so it must not
+    // trigger the ⟨0.30⟩ verdict. Only well-formed entries count — a malformed one is corrupt input, and
+    // silently dropping it is how a fail-closed rung turns back into a green one.
+    const oos = parsed.outOfScope;
+    // PRESENT-BUT-NOT-A-LIST IS CORRUPT, NOT ABSENT. This had no `else` on the Array.isArray guard, so
+    // `"outOfScope": "oops"` was silently coerced to nothing and `gate --report` answered exit 0,
+    // `ok:true`, "no violations" over a report whose peek had found a denied effect — the exact
+    // fail-open coercion the strict read exists to prevent, in the commit that claims to prevent it.
+    // rust, java and swift all refuse this shape; only this route did not. (Found by review, MEASURED.)
+    if (oos !== undefined && !Array.isArray(oos))
+      corrupt.push(`${f}: \`outOfScope\` is present and is not a list`);
+    else if (Array.isArray(oos))
+      for (const e of oos)
+        if (e && typeof e === "object" && Array.isArray(e.effects) && e.effects.length)
+          outOfScope.push(e);
+        else corrupt.push(`${f}: \`outOfScope\` (an element is not an object carrying a non-empty \`effects\`)`);
     // ⟨0.15⟩ the κ ledger. Merged + re-sorted the PRODUCER's way (count desc, name asc by code point —
     // reportCoverage's rule, and scan.mjs's), so a single-report prefix reproduces the emitted order exactly.
     const unc = parsed.coverage?.uncovered;
@@ -811,7 +870,7 @@ export function loadGateReport(prefix) {
   }
   const coverage = [...cov.entries()].sort((a, b) => b[1] - a[1] || byCodePoint(a[0], b[0]))
     .map(([name, calls]) => ({ name, calls }));
-  return { functions, analyzed, unanalyzed, coverage, judgedNothing, hardFail: hardFail || corrupt.length > 0, corrupt };
+  return { functions, analyzed, unanalyzed, coverage, judgedNothing, outOfScope, hardFail: hardFail || corrupt.length > 0, corrupt };
 }
 // The returned graph carries a non-enumerable `partial` flag (the loadReport `hardFail` precedent):
 // true iff a sidecar file was MATCHED but failed to read/parse — its edges were DROPPED (disclosed on

package/query.mjs

@@ -509,7 +509,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.29";
+const SPEC_VERSION = "0.30";
 
 // ---- 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]
@@ -1852,7 +1852,12 @@ switch (cmd) {
     // --report` REFUSES over a corrupt member — measured, exit 2 — so exiting 0/1 here claimed this verb
     // got FURTHER than the gate on identical bytes. The unreadable note above already SAID the exit was
     // bounded by the gate's while this line did not read the field — a documented limitation, unmeasured.
-    process.exit(fgUnan.length || fgComp.unreadable.length || fgr.unevaluated?.length ? (strict ? 2 : 0) : (strict && !fgr.ok ? 1 : 0));
+    // ⟨0.30⟩ …and the peek's findings, because ⟨0.24⟩ binds this verb to the GATE's pessimism: "AN
+    // ADVISORY VERB MUST NEVER BE LESS SENSITIVE TO INCOMPLETENESS THAN THE GATE OVER THE SAME BYTES",
+    // and "THE SAME RULE BINDS EVERY ADVISORY VERB THAT ANSWERS `ok` — `unverified`, `fix-gate`, and any
+    // later sibling". ⟨0.30⟩ moved the gate to exit 2 on this cause and left these verbs certifying:
+    // MEASURED, `gate --report` exited 2 while this printed a clean answer at exit 0 over the same bytes.
+    process.exit(fgUnan.length || fgComp.unreadable.length || fgComp.outOfScope?.length || fgr.unevaluated?.length ? (strict ? 2 : 0) : (strict && !fgr.ok ? 1 : 0));
     break; // unreachable
   }
   case "unverified": {
@@ -1917,7 +1922,8 @@ switch (cmd) {
     // ⟨0.28⟩ `unreadable` joins the `--strict` exit-2 trigger — see fix-gate above. Measured on this verb
     // before the fix: over one good report plus one unparsable sibling, `gate --report` exited 2 and
     // `unverified --strict` exited 0 — and `--strict` is how CI consumes it.
-    process.exit(uUnan.length || uComp.unreadable.length || r.unevaluated?.length ? (strict ? 2 : 0) : (strict && !r.ok ? 1 : 0));
+    // ⟨0.30⟩ the peek's findings too — see the fix-gate exit above for the ⟨0.24⟩ MUST this satisfies.
+    process.exit(uUnan.length || uComp.unreadable.length || uComp.outOfScope?.length || r.unevaluated?.length ? (strict ? 2 : 0) : (strict && !r.ok ? 1 : 0));
     break; // unreachable
   }
   case "gate": {
@@ -2146,7 +2152,11 @@ switch (cmd) {
     // ⟨0.21⟩ COMPLETENESS MANIFEST: a gate cannot be green over code candor never analyzed. The scan path
     // exits 2 on its OWN `unanalyzed`; here the same manifest travels ON the report, so the same verdict
     // follows from it. A real violation (exit 1) dominates, as it does there.
-    const gincomplete = g.unanalyzed.length > 0;
+    // ⟨0.30⟩ the SECOND cause, read off the report because this route cannot peek — the report carries the
+    // peek's findings, which is what makes §3.1 byte-equality hold here by construction rather than by two
+    // authors agreeing. ABSENT is not empty: a report produced with no policy was never asked.
+    const gscope = g.outOfScope ?? [];
+    const gincomplete = g.unanalyzed.length > 0 || gscope.length > 0;
     // The verdict document — the SAME builder shape scan.mjs writes, field for field and in the same key
     // order, because §3.1 ⟨0.24⟩ makes byte-equality with `scan --policy`'s `--gate-json` the acceptance
     // test. `analyzed.count`, `incomplete`/`unanalyzed` and the ⟨0.15⟩ coverage advisory all come off the
@@ -2172,7 +2182,12 @@ switch (cmd) {
     // not be answered, this carries text that never became a rule at all. Omitted when empty; `ok` and
     // the exit do not consult it (the line-level leniency is unchanged, only disclosed).
     if (gpol.ignored?.length) gverdictObj.ignored = gpol.ignored;
-    if (gincomplete) { gverdictObj.incomplete = true; gverdictObj.unanalyzed = g.unanalyzed; }
+    if (gincomplete) {
+      gverdictObj.incomplete = true;
+      if (g.unanalyzed.length) gverdictObj.unanalyzed = g.unanalyzed;
+    }
+    // ⟨0.30⟩ same key, same position as the scan route's — §3.1's byte-equality is the acceptance test.
+    if (gscope.length) gverdictObj.outOfScope = gscope;
     if (g.coverage.length)
       gverdictObj.coverage = { uncovered: g.coverage.length, packages: g.coverage.map((c) => c.name) };
     if (gviol.length) {
@@ -2186,7 +2201,12 @@ switch (cmd) {
     if (gunevaluated.length)
       grefuse(`${gunevaluated.length} policy rule(s) could not be evaluated against this report`, gunevaluated);
     if (gincomplete) {
-      const why = `gate NOT certified — the report declares ${g.unanalyzed.length} unit(s) candor could not analyze; a gate cannot be green over unanalyzed code`;
+      // ⟨0.30⟩ NAME THE CAUSE THAT ACTUALLY FIRED. Two causes reach this exit now, and a message that
+      // always says "could not analyze" would report the wrong repair for the scope one — the operator
+      // would go looking for a parse failure that is not there.
+      const why = g.unanalyzed.length
+        ? `gate NOT certified — the report declares ${g.unanalyzed.length} unit(s) candor could not analyze; a gate cannot be green over unanalyzed code`
+        : `gate NOT certified — the report names ${gscope.length} function(s) OUTSIDE the scan's scope performing an effect this policy denies; the gate did not judge them, so the verdict is incomplete rather than a pass`;
       console.error(`candor-ts: ${why}`);
       // The INCOMPLETE verdict is a JUDGEMENT, not a refusal: it names what was analyzed and what was not,
       // and §3.1 makes byte-equality with `scan --policy`'s document the acceptance test for exactly it.

package/scan.mjs

@@ -45,7 +45,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.29";
+const SPEC_VERSION = "0.30";
 
 // A TREE TOO DEEP TO WALK IS "COULD NOT EVALUATE" (exit 2), NEVER "FOUND A VIOLATION" (exit 1).
 //
@@ -6646,7 +6646,8 @@ for (const [name, rec] of fns) cg[name] = [...rec.edges].sort();
 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
+// DENIES. ⟨0.30⟩ THE VERDICT DOES MOVE — see the exit site below: a non-empty block makes it
+// `ok:false, incomplete:true` at exit 2. It is still 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`;
@@ -6678,7 +6679,11 @@ let peekRead = false;
 const peekUnread = new Set();
 let peekUnattributed = false;
 if (policyPath && excludedFiles.length) {
-  let denied = new Set();
+  // ⟨0.30⟩ HOISTED, because the matcher below needs it. It was a `const` inside the try, so the
+  // evaluatePolicy call added in this rung threw ReferenceError straight into the "a peek that cannot
+  // run must not fail the gate" catch — findings silently empty, gate green. The catch is right; a bug
+  // hiding behind it is not, which is why the trigger below is now a POSITIVE test on the rules.
+  let peekPolicy = null;
   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,
@@ -6687,10 +6692,14 @@ if (policyPath && excludedFiles.length) {
     // 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 ?? []));
+      peekPolicy = pol;
     }
   } catch { /* an unreadable policy is the gate's business to refuse, not the peek's */ }
-  if (denied.size) {
+  // ⟨0.30⟩ THE TRIGGER IS "ARE THERE DENY RULES", not "is the flattened effect-name set non-empty". The
+  // old test read the name set, and `pure` is a deny rule with an EMPTY effect list meaning "every effect
+  // except Unknown" — so under the STRICTEST policy the set was empty, the peek never ran, and the tree
+  // passed at exit 0 while the strictly weaker `deny Exec` exited 2 on the same files. MEASURED four-way.
+  if ((peekPolicy?.deny ?? []).length) {
     outOfScopeFindings = [];
     const peekDir = fs.mkdtempSync(path.join(os.tmpdir(), "candor-ts-peek-"));
     try {
@@ -6721,8 +6730,62 @@ if (policyPath && excludedFiles.length) {
         // all of them claiming completeness.
         if (hit) peekUnread.add(hit.cls); else peekUnattributed = true;
       }
+      // ⟨0.30⟩ THE PEEK ASKS THE GATE'S OWN MATCHER, not a flat set of effect NAMES. §6.2 already
+      // requires it — "THE GATE AND THE DISCLOSURE MUST APPLY THE SAME RULE, AND SHOULD SHARE THE SAME
+      // CODE" — and the name-set approximation was wrong in BOTH directions once ⟨0.30⟩ made this
+      // verdict-bearing (both MEASURED four-way in review):
+      //
+      //   OVER-CHARGE: `deny Net[known-partner]` denies only that destination class, but the name set
+      //   held bare "Net", so a peeked fn fetching an UNKNOWN host — which the rule does not deny —
+      //   turned the verdict red, while the identical code IN scope passed. Rule SCOPES were dropped the
+      //   same way: a layer-scoped `deny Exec server` fired on a test file the scope excludes.
+      //
+      //   UNDER-REPORT: `pure` is a deny rule with an EMPTY effect list, meaning "every effect except
+      //   Unknown". Flattened, it contributed NOTHING, so the denied set was empty and the peek never
+      //   ran — the STRICTEST policy silently disarmed the rung while the strictly weaker `deny Exec`
+      //   exited 2 on the identical tree. A four-way false all-clear.
+      //
+      // Only the DENY rules are handed over: ⟨0.29⟩ bounds this block to "effects that policy DENIES",
+      // and evaluating `allow`/`forbid`/`only` here would widen it past the bound that keeps it quiet.
+      // ⟨0.30⟩ THE PROJECT'S OWN `net-partner` SET, not an empty one. The child scan runs over a temp
+      // tsconfig and never sees the project's `.candor/config`, and this call passed `new Set()` on top of
+      // that — so a `deny Net[known-partner]` peek asked "is this host a declared partner?" against a set
+      // that was always empty. MEASURED both ways: a test file reaching a DECLARED partner answered exit 0
+      // where the same code in scope exits 1 (a false all-clear), and `deny Net[unknown-host]` answered
+      // exit 2 over that same declared partner where in scope it exits 0 (the mirror over-charge).
+      // candor-rust never had this — its peek runs in-process and inherits the config.
+      //
+      // `netClasses` stays null so the resolver recomputes each entry's class from the `hosts` the child
+      // DID capture, against these partners — the child's own `netClass` was computed partner-blind and
+      // must not be trusted here.
+      // ⟨0.30⟩ MATCH SCOPES AGAINST A PROJECT-RELATIVE QUALIFIER, not the child's. The child scan runs
+      // under a temp-directory tsconfig, so its `fn` is derived from THAT root — an absolute dotted path.
+      // Handing those to the matcher made a rule's SCOPE match segments of the checkout directory: on a
+      // tree at `…/fresh/src/execa`, `deny Net src` armed the peek while binding nothing in scope, so the
+      // verdict depended on where the repo happened to be cloned. CI checkouts live under names nobody
+      // chose (Bitbucket uses `agent/build`), which makes that a verdict decided by infrastructure.
+      //
+      // The project-relative path is already known here — it is what this run disclosed as excluded — and
+      // the finding below is already named from it. The MATCHER must see the same thing the FINDING does.
+      const relQual = (f) => {
+        const childLoc = (f.loc ?? "").split(":")[0] ?? "";
+        const hit = excludedFiles.find((e) => childLoc.endsWith(e.path)
+                                           || childLoc.endsWith(path.basename(e.path)));
+        if (!hit) return f.fn;
+        const stem = hit.path.replace(/\.[cm]?[jt]sx?$/, "").split(path.sep).join(".");
+        const leaf = f.fn.split(".").pop() ?? f.fn;
+        return `${stem}.${leaf}`;
+      };
+      const peekEntries = (doc.functions ?? []).map((f) => ({ ...f, fn: relQual(f) }));
+      const peekViolations = evaluatePolicy({ ...peekPolicy, allow: [], forbid: [], only: [] },
+                                            peekEntries, {}, new Map(), netPartners, null, null);
+      const deniedByFn = new Map();
+      for (const v of peekViolations) {
+        if (!deniedByFn.has(v.fn)) deniedByFn.set(v.fn, new Set());
+        for (const e of v.effects ?? []) deniedByFn.get(v.fn).add(e);
+      }
       for (const f of doc.functions ?? []) {
-        const hits = (f.inferred ?? []).filter((e) => denied.has(e));
+        const hits = [...(deniedByFn.get(relQual(f)) ?? [])].sort();
         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
@@ -6737,7 +6800,9 @@ if (policyPath && excludedFiles.length) {
         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.",
+                + "candor's ANALYSIS of that file reaches this effect; the gate did not judge it, so "
+                + "the verdict is INCOMPLETE rather than a pass. (An analysis result, not a claim about "
+                + "what the code does at runtime — see the release notes' known over-charge.)",
         });
       }
       outOfScopeFindings.sort((a, b) => (a.path + a.fn).localeCompare(b.path + b.fn));
@@ -6761,7 +6826,7 @@ if (outOfScopeFindings) {
     if (f.path) console.error(`             ${f.path}`);
   }
   if (outOfScopeFindings.length) {
-    console.error("             The verdict does not account for "
+    console.error("             The verdict below is INCOMPLETE because of "
       + (outOfScopeFindings.length === 1 ? "it." : `these ${outOfScopeFindings.length}.`));
   }
 }
@@ -7356,7 +7421,14 @@ if (gateJsonPath) {
   // must NOT read green — those effects are invisible, so a `deny`/`pure` that "passes" over them is a
   // false-pure. `ok` requires BOTH no violation AND a complete analysis. `analyzed:{count}` (Gap 1) mirrors
   // the report envelope so a --gate-json consumer sees the scan's scope from the verdict alone.
-  const incomplete = unanalyzedUnits.length > 0;
+  // ⟨0.30⟩ THE SECOND CAUSE OF INCOMPLETENESS — a peeked function performs an effect the policy DENIES.
+  // ⟨0.29⟩ required the verdict NOT to move here, on the assumption the peek surfaces uncertainty a gate
+  // may decline to act on. It does not: measured on published 0.29.1 the peek resolves a CONCRETE denied
+  // effect and names the function (axios 37 × `performs Net`, exit 0, `policy ✓`). Reported through
+  // `incomplete`, never through `violations`, because the gate did not JUDGE these units — see the exit
+  // site below for why that makes the code 2 and not 1.
+  const scopeIncomplete = Array.isArray(outOfScopeFindings) && outOfScopeFindings.length > 0;
+  const incomplete = unanalyzedUnits.length > 0 || scopeIncomplete;
   const verdictObj = { spec: SPEC_VERSION, ok: gateViolations.length === 0 && !incomplete,
                        analyzed: { count: fns.size } };
   // ⟨0.24⟩ the vocabulary file that moved the verdict, in the SAME position `gate --report` puts it, because
@@ -7388,8 +7460,14 @@ if (gateJsonPath) {
   // incomplete:true is honest — never a fabricated pass. OMITTED when complete (byte-compatible verdict).
   if (incomplete) {
     verdictObj.incomplete = true;
-    verdictObj.unanalyzed = unanalyzedUnits.map((u) => ({ path: u.path, reason: u.reason }));
-  }
+    if (unanalyzedUnits.length)
+      verdictObj.unanalyzed = unanalyzedUnits.map((u) => ({ path: u.path, reason: u.reason }));
+  }
+  // ⟨0.30⟩ …and WHICH functions made it incomplete, in the machine channel. The same array the report
+  // carries, so `gate --report` re-emits it from the report and §3.1 byte-equality holds by construction —
+  // this is the anchor the `net-partner` attempt lacked. Omitted when empty, so a clean verdict is
+  // byte-identical to a pre-⟨0.30⟩ one.
+  if (scopeIncomplete) verdictObj.outOfScope = outOfScopeFindings;
   // ⟨0.15 staged⟩ coverage ADVISORY (COVERAGE-DESIGN.md §3): when the κ ledger is non-empty, the
   // verdict discloses what the gate could NOT see — VERDICT-PRESERVING (the ⟨0.9⟩ provable-purity
   // auto-disclosure precedent exactly): ok/violations/exit are computed above and untouched here. A
@@ -7429,5 +7507,21 @@ if (gateConfigured && unanalyzedUnits.length) {
   console.error(`candor-ts: gate NOT certified — ${unanalyzedUnits.length} source file(s) could not be analyzed (see above); a gate cannot be green over unanalyzed code`);
   process.exit(2);
 }
+// ⟨0.30⟩ THE SCOPE HALF OF THE SAME POSTURE. `unanalyzed` above is "I opened this file and could not read
+// it"; this is "I never opened it, and when I looked afterwards it performed the effect you denied". Both
+// mean the same thing to a consumer — the gate could not see enough of this tree to certify it — so both
+// are exit 2.
+//
+// EXIT 2, NOT 1, DELIBERATELY: these functions are not in `violations` and not in `functions`, because the
+// gate did not judge them. Exit 1 would claim "I judged your code and it breaks the policy", which is
+// false in the other direction. Exit 2 says "I could not see enough to answer", which is what happened.
+// A real violation (exit 1, above) still dominates: certain beats unevaluable.
+if (gateConfigured && Array.isArray(outOfScopeFindings) && outOfScopeFindings.length) {
+  const n = outOfScopeFindings.length;
+  console.error(`candor-ts: gate NOT certified — ${n} function(s) OUTSIDE this scan's scope perform an `
+    + `effect this policy denies (named above); the gate did not judge them, so the verdict is `
+    + `incomplete rather than a pass`);
+  process.exit(2);
+}
 if (policyPath !== null) console.error("candor-ts: policy ✓");
 if (baselinePath !== null && fs.existsSync(baselinePath)) console.error("candor-ts: baseline ✓"); // absent = inactive (noted above)

package/scratch.mjs

@@ -0,0 +1,58 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// Scratch directories for the harnesses, removed when the run ends.
+//
+// WHY THIS EXISTS. Every harness here made fixture trees with a bare `fs.mkdtempSync` and removed none
+// of them. Measured 2026-08-14: 46,919 `candor-*` directories in $TMPDIR, ~7,300 of them from test.mjs's
+// `project()` alone, which mints one per fixture and is called ~1,300 times a run. It is not only
+// untidy — it made a single `candor-swift privacy-manifest --verify` take 72 seconds, because listing
+// the plist's ancestor meant listing all of $TMPDIR. The engine side of that was fixed in 2026-08-07;
+// this is the side that keeps refilling the directory.
+//
+// KEPT ON FAILURE, DELIBERATELY. A failing assertion prints the path to its fixture tree, and deleting
+// it on the way out would remove the evidence at exactly the moment someone needs it. `keepOnFailure()`
+// lets a harness say "this run failed" and the trees survive, with a line saying where they are.
+// Success is the common case and the one that accumulates.
+//
+// SIGINT/SIGTERM are handled because the killed-mid-run case was the obvious contributor — though 46,919
+// is not all killed runs.
+const made = [];
+let keep = false;
+
+export function scratch(prefix) {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  made.push(d);
+  return d;
+}
+
+/** Call before exiting when the run FAILED — the trees are evidence, so they stay. */
+export function keepOnFailure() { keep = true; }
+
+function sweep() {
+  if (keep) {
+    if (made.length) console.log(`  (${made.length} fixture tree(s) kept for inspection under ${os.tmpdir()})`);
+    return;
+  }
+  for (const d of made) { try { fs.rmSync(d, { recursive: true, force: true }); } catch { /* best effort */ } }
+  made.length = 0;
+}
+
+process.on("exit", sweep);
+// An uncaught throw still runs `exit` handlers — with `keep` false, so a harness that dies mid-assertion
+// would sweep away the very trees whose paths the crash just printed. Treat any abnormal end as failure.
+for (const ev of ["uncaughtException", "unhandledRejection"]) {
+  process.on(ev, (e) => { keepOnFailure(); console.error(e); process.exit(1); });
+}
+// A signal does NOT run `exit` handlers on its own, which is the killed-mid-run leak. Re-raise after
+// sweeping so the exit status still reflects the signal rather than becoming a clean 0.
+//
+// `removeAllListeners` FIRST, and it is the whole trick: installing a listener REPLACES Node's default
+// disposition for that signal, so `process.kill(process.pid, sig)` re-enters this same handler. The
+// first version of this shipped without it and made the harness unkillable — Ctrl-C swept, re-signalled,
+// swept, forever, and a second Ctrl-C did not help either. Removing the listener restores the default,
+// so the re-raise terminates with the right status.
+for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(sig, () => { sweep(); process.removeAllListeners(sig); process.kill(process.pid, sig); });
+}