candor-ts 0.28.2 → 0.29.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.28)."*
+> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.29)."*
 > 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`.
 >

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

@@ -5,11 +5,35 @@ import { fileURLToPath } from "node:url";
 // The agent contract for THE INSTALLED VERSION — AGENTS.md ships in the npm tarball, so the doc and
 // engine cannot drift (the spec §2.1 version-trust rule applied to documentation). ONE implementation
 // used by both scan.mjs and query.mjs, so `--agents` output can never diverge within an install.
-export function printAgents() {
+// `fd` and `budgetMs` are parameters ONLY so the suite can drive this exact loop against a real
+// non-blocking fd. A guard that has never taken its own EAGAIN branch is a guard nobody has seen work,
+// and this file's whole history is failure modes that only appear on a pipe. Production passes neither.
+// `--agents` was never the only print-then-exit site — it was the only one that got FIXED, which is how
+// the defect survived. `printAgents` now delegates to `writeStdoutSync` below so the next bulk-output
+// site inherits the fix instead of being audited into it.
+export function printAgents(fd = 1, budgetMs = 5000) {
   const dir = path.dirname(fileURLToPath(import.meta.url)); // the package root (where AGENTS.md ships)
   const semver = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8")).version;
   const out = `<!-- candor-ts ${semver} · the agent contract for this installed version -->\n`
     + fs.readFileSync(path.join(dir, "AGENTS.md"), "utf8");
+  writeStdoutSync(out, "--agents", fd, budgetMs);
+}
+
+// ── THE SYNCHRONOUS BULK WRITER ───────────────────────────────────────────────────────────────────
+// MEASURED on `scan.mjs --json --policy <p>` over a 400-file fixture with a violation: **95281 bytes to
+// a FILE, valid JSON; 65536 bytes through a PIPE, a JSONDecodeError** — exactly the pipe buffer, exit 1
+// either way, nothing on stderr. `console.log` is asynchronous on a pipe and `process.exit()` discards
+// what is still buffered, which is the identical defect the `--agents` path was rewritten for, in the
+// path a MACHINE consumer reads. The umbrella backlog asserted the opposite — that the remaining
+// print-then-exit sites "fit the buffer and survive by SIZE" — which was true of the usage strings
+// somebody measured and false of the report envelope nobody did.
+//
+// `what` names the caller, so the stderr diagnostic points at the surface that lost bytes.
+// RETURNS true when every byte landed, false when it gave up (EAGAIN budget) or the reader left (EPIPE).
+// The test driver needs that answer — an unfinished dump is an incomplete report and must turn the run
+// red — and returning it is what let the driver delete its own private copy of this loop, which was
+// unreachable from any route the suite drives and therefore untested by construction.
+export function writeStdoutSync(out, what = "output", fd = 1, budgetMs = 5000) {
   // fs.writeSync, NOT console.log/process.stdout.write. On a PIPE those are asynchronous, and scan.mjs
   // calls `process.exit(0)` on the next line — which discards whatever is still buffered. The contract
   // came out TRUNCATED AT 8170 OF 23121 CHARACTERS, cut mid-sentence, with exit 0 and nothing on stderr:
@@ -32,14 +56,49 @@ export function printAgents() {
   //            THROWS rather than short-writing as soon as the payload exceeds the 64 KiB pipe buffer.
   //            The contract is 24 KiB today, so this is latent, not live — and it would come back as
   //            exactly the truncation-plus-noise this function was written to remove. Retry with a
-  //            small backoff (Atomics.wait is the only synchronous sleep available here).
-  let off = 0;
+  //            small backoff (Atomics.wait is the only synchronous sleep available here) — BOUNDED, see
+  //            below.
+  //
+  // WHAT THE BUDGET ACTUALLY BOUNDS: `budgetMs` of ZERO PROGRESS, not total wall-clock. The deadline
+  // resets on every successful write, including a partial one, so a reader draining a chunk at a time
+  // stretches the total to budget × the number of stalls. That is the RIGHT property — a slow reader must
+  // not be cut off for being slow, and the failure this guards is a reader that has STOPPED — but
+  // "bounded at 5s" was the wrong description of it, and the payload here is a fixed 24 KiB so the worst
+  // case is a small multiple rather than unbounded. Measured with a 500ms budget against a reader taking
+  // 4096 bytes every 400ms: 2409ms total, whole contract delivered, no give-up.
+  //
+  // THE RETRY IS BOUNDED, and it was not. `while (off < buf.length)` with an unconditional 1 ms sleep
+  // spins FOREVER against a reader that stalls without ever closing — an agent harness that stops
+  // reading while holding the pipe open, a log collector wedged on a full disk. EPIPE is the case where
+  // the reader LEFT, and it is handled; this is the case where it stayed and stopped, and the two look
+  // nothing alike from here. A hung `--agents` cannot be told from a slow one: it reports nothing, and
+  // burns whatever timeout is around it. Both endings are bad, so pick the one that is legible — say so
+  // on fd 2, in the same words as the EPIPE arm, and stop.
+  //
+  // WHY THE SAME BUDGET AS test.mjs's DRIVER: this is the identical hazard on the identical primitive,
+  // and the fix went into the driver first while this one — the one an AGENT actually reads through a
+  // pipe — was left spinning. The sibling route, again, and this side is the user-facing half.
+  const EAGAIN_BUDGET_MS = budgetMs;
+  let off = 0, deadline = 0;
   const buf = Buffer.from(out, "utf8");
   const idle = new Int32Array(new SharedArrayBuffer(4));
   try {
     while (off < buf.length) {
-      try { off += fs.writeSync(1, buf, off, buf.length - off); }   // a short write is legal
-      catch (e) { if (e.code !== "EAGAIN") throw e; Atomics.wait(idle, 0, 0, 1); }
+      try { off += fs.writeSync(fd, buf, off, buf.length - off); deadline = 0; }   // a short write is legal
+      catch (e) {
+        if (e.code !== "EAGAIN") throw e;
+        // A wall-clock deadline, not a retry count: Atomics.wait's 1 ms is a FLOOR, so N turns is not N
+        // milliseconds of anything. Reset on every byte that lands, so a slow reader is never punished
+        // for being slow — only a stopped one runs the budget down.
+        if (deadline === 0) deadline = Date.now() + EAGAIN_BUDGET_MS;
+        else if (Date.now() >= deadline) {
+          try { fs.writeSync(2, `candor-ts: ${what} output stalled at ${off} of ${buf.length} bytes `
+                              + `— the reader has not drained for ${EAGAIN_BUDGET_MS}ms. This output is INCOMPLETE.\n`); }
+          catch { /* nothing left to tell */ }
+          return false;
+        }
+        Atomics.wait(idle, 0, 0, 1);
+      }
     }
   } catch (e) {
     if (e.code !== "EPIPE") throw e;
@@ -48,7 +107,9 @@ export function printAgents() {
     // was rewritten to remove ("an agent piping candor-ts --agents into its context silently read a
     // third of its own instructions") — so the reader-left case has to be STATED. stderr may be closed
     // too; that write is best-effort by construction.
-    try { fs.writeSync(2, `candor-ts: --agents output was cut short at ${off} of ${buf.length} bytes `
-                        + `— the reader closed the pipe. This contract is INCOMPLETE.\n`); } catch { /* nothing left to tell */ }
+    try { fs.writeSync(2, `candor-ts: ${what} output was cut short at ${off} of ${buf.length} bytes `
+                        + `— the reader closed the pipe. This output is INCOMPLETE.\n`); } catch { /* nothing left to tell */ }
+    return false;
   }
+  return true;
 }

package/lsp.mjs

@@ -45,7 +45,7 @@ import { createRequire } from "node:module";
 import nodePath from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import * as Q from "./query-core.mjs";
-import { discoverConfigPolicy, evaluatePolicy, parsePolicy, scopeMatches, reportNetClasses, parseUnknownAliases, discoverConfigText, policyVocabularyAnchor, policyErrorText, unanswerableScoped, resolveReasonClasses, fatalPolicyErrors, policyZeroRules } from "./policy.mjs";
+import { discoverConfigPolicy, evaluatePolicy, parsePolicy, scopeMatches, reportNetClasses, parseUnknownAliases, discoverConfigText, policyVocabularyAnchor, policyErrorText, unanswerableScoped, wholePolicyUnanswerable, resolveReasonClasses, fatalPolicyErrors, policyZeroRules } from "./policy.mjs";
 
 // Version: from the sibling package.json when running inside the npm package; a single-file BUNDLE of
 // this server (the IDE-plugin embedding) has no sibling package.json — fall back rather than crash.
@@ -326,7 +326,8 @@ function activePolicyParsed(text) {
 }
 // ⟨0.28⟩ SPEC §2/§6.2 — DID THIS CONFIGURED POLICY ASK ANYTHING AT ALL? Every rule vector, never a
 // subset: keying on `deny` alone would call an ordinary allow-only or forbid-only gate empty.
-const policyAskedNothing = (pol) => !!pol && !pol.deny.length && !pol.allow.length && !pol.forbid.length;
+const policyAskedNothing = (pol) => !!pol && !pol.deny.length && !pol.allow.length && !pol.forbid.length
+  && !(pol.only ?? []).length;   // ⟨0.29⟩ an `only`-only policy is ARMED
 // The editor has no exit code and no JSON document, so both of this rung's channels collapse onto the
 // one it does have. Same `warnOnce` shape (and same reasoning) as the judged-nothing warning below: there
 // is no line to pin it to, and a per-keystroke popup is how an advisory gets turned off.
@@ -384,13 +385,24 @@ function diagnosticsFor(docPath) {
   const dnet = reportNetClasses(fns, { authoritative: true });
   const { unevaluated: dunevaluated, withhold: dwithhold } =
     unanswerableScoped(dpol, fns, resolveReasonClasses(fns, Q.loadCallgraph(reportPrefix)), dnet);
+  // ⟨0.29⟩ `forbid`/`allow` are STRIPPED and DISCLOSED here too. This path handed the whole policy to
+  // `evaluatePolicy`, so an editor drew AS-EFF-009 squiggles from a report — evidence SPEC §3.1 rules
+  // cannot support them — or, with no sidecar, drew nothing and said nothing, which reads as "no layering
+  // problem here". `dunevaluated` was deny-only, so neither case produced even a log line. Same defect as
+  // the MCP tool, same shared helper, because these two are each other's siblings as much as the CLI's.
+  const dwp = wholePolicyUnanswerable(dpol, "the editor's report route");
+  dunevaluated.push(...dwp.unevaluated);
   // The surface has no exit code, so the refusal is carried the way this file already carries its other two
   // (the unhonourable policy, the judged-nothing report): ONE log line naming the rules, so the missing
   // squiggle is EXPLAINED rather than read as a clean bill of health. Per rule, not per keystroke — warnOnce
   // keys on the message, and the message is a function of the policy and the report, not of the edit.
+  // NAME THE RULE, not just its kind. The message used to carry `why` alone — "this policy has 1
+  // `forbid` rule(s), which … cannot evaluate" — which tells a developer a category and leaves them to
+  // guess which line of their policy went unenforced. In an editor that is the whole cost of the refusal:
+  // the squiggle is absent either way, and the message is the only thing standing in for it.
   for (const u of dunevaluated)
     warnOnce(`candor-lsp: ${u.why}\n  NO diagnostics are drawn for that rule — their ABSENCE here is the refusal, not an all-clear.`);
-  const violations = evaluatePolicy(dpol, fns, Q.loadCallgraph(reportPrefix),
+  const violations = evaluatePolicy(dwp.answerable, fns, Q.loadCallgraph(reportPrefix),
                                     new Map(), new Set(), dnet, dwithhold);
   const locByFn = new Map(fns.filter((e) => e.loc).map((e) => [e.fn, locParts(e.loc)]));
   const out = [];

package/mcp.mjs

@@ -21,7 +21,8 @@ import nodePath from "node:path";
 import * as Q from "./query-core.mjs";
 import { discoverConfigPolicy, evaluatePolicy, parsePolicy, scopeMatches, reportNetClasses,
          parseUnknownAliases, discoverConfigText, policyVocabularyAnchor, policyErrorText,
-         unanswerableScoped, resolveReasonClasses, fatalPolicyErrors, policyZeroRules } from "./policy.mjs";
+         unanswerableScoped, wholePolicyUnanswerable, resolveReasonClasses, fatalPolicyErrors,
+         policyZeroRules } from "./policy.mjs";
 
 const VERSION = createRequire(import.meta.url)("./package.json").version; // single-sourced, like scan.mjs
 
@@ -144,7 +145,8 @@ function policyOrThrow(text, policyPath) {
 // over `# no rules yet` — an all-clear produced by deleting the question, handed to a consumer that
 // cannot ask a follow-up. `fix` emits NO `crossing` key: that key is present exactly when the verb
 // answered. §6.2's gate REFUSES over the same policy (exit 2); these are advisory, so they disclose.
-const policyAskedNothing = (pol) => !!pol && !pol.deny.length && !pol.allow.length && !pol.forbid.length;
+const policyAskedNothing = (pol) => !!pol && !pol.deny.length && !pol.allow.length && !pol.forbid.length
+  && !(pol.only ?? []).length;   // ⟨0.29⟩ an `only`-only policy is ARMED
 // `policyZeroRules` also returns a `why` — the HUMAN sentence the gate's refusal puts in `reason`. The
 // caveat document carries only `unevaluated`, so it is not spread here rather than minted as a wire key.
 const zeroRuleCaveat = (policyPath, prefix) => {
@@ -405,7 +407,21 @@ const TOOLS = {
       const cg = Q.loadCallgraph(p);
       const gnet = reportNetClasses(gfns, { authoritative: true });
       const { unevaluated, withhold } = unanswerableScoped(pol, gfns, resolveReasonClasses(gfns, cg), gnet);
-      const v = evaluatePolicy(pol, gfns, cg, new Map(), new Set(), gnet, withhold);
+      // ⟨0.29⟩ …AND THE TWO WHOLE-POLICY UNANSWERABLE KINDS. This tool passed the WHOLE policy to
+      // `evaluatePolicy`, so `forbid` was answered from a report — MEASURED: with no callgraph sidecar,
+      // `violations: 0` and nothing disclosed (a silent green over a rule that was never enforced); with a
+      // sidecar, an AS-EFF-009 violation from evidence SPEC §3.1 says cannot support one. Both outcomes the
+      // MUST forbids, on the channel an agent reads. The CLI sibling had stripped and disclosed these since
+      // ⟨0.24⟩; the shared helper is so the third route cannot drift from the first two again.
+      const wp = wholePolicyUnanswerable(pol, "`candor_gate` (a report route)");
+      unevaluated.push(...wp.unevaluated);
+      // …and a policy that is NOTHING BUT unanswerable kinds has no verdict to stand beside the refusal,
+      // so it refuses outright — the same split `gate --report` makes. Where other rules CAN fire, they
+      // decide and these ride along disclosed (§3.1 `1503368`: whole-policy granularity is not a licence
+      // to suppress a certain violation).
+      if (wp.onlyUnanswerable)
+        throw new Error(`this policy asks only questions a report cannot answer — ${wp.unevaluated[0].why}`);
+      const v = evaluatePolicy(wp.answerable, gfns, cg, new Map(), new Set(), gnet, withhold);
       // ⟨0.21⟩ COMPLETENESS MANIFEST — this tool implemented no incompleteness rule at all: it answered
       // `{ok:true, violations:[]}` over a report DECLARING `unanalyzed`, where the CLI exits 2. A gate
       // cannot be green over code candor never analyzed, and the manifest travels ON the report, so the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "candor-ts",
-  "version": "0.28.2",
-  "description": "candor for TypeScript \u2014 per-function side effects, transitively, with a policy gate (candor-spec 0.28)",
+  "version": "0.29.0",
+  "description": "candor for TypeScript \u2014 per-function side effects, transitively, with a policy gate (candor-spec 0.29)",
   "type": "module",
   "dependencies": {
     "@types/node": "^25.9.2",

package/policy.mjs

@@ -211,12 +211,12 @@ export const fatalPolicyErrors = (errors) => (errors ?? []).filter((e) => FATAL_
 // The accepted sets, as ARRAYS (SPEC §3.1 `901f14d`: `accepted` is an array of tokens, not prose — a prose
 // string is unparseable by the consumer the field exists for).
 const REASON_VOCAB = [...REASON_CLASSES, "dynamic", "*"];
-const RULE_KIND_VOCAB = ["deny", "pure", "forbid", "allow"];
+const RULE_KIND_VOCAB = ["deny", "pure", "forbid", "only", "allow"];
 const DROPPED = (why) => `policy line NOT HONOURED — DROPPED (${why}); it is absent from the parse, so the `
                        + `policy that ran is the one without it`;
 
 export function parsePolicy(text, aliases = null) {
-  const deny = [], allow = [], forbid = [];
+  const deny = [], allow = [], forbid = [], only = [];
   // ⟨0.24⟩ every line this parser could not honour AS WRITTEN, and every alias a rule RESOLVED THROUGH.
   // `aliasesUsed` is recorded at the point of USE, never from the alias map: a config defining ten aliases
   // the policy never mentions moved nothing, and naming it would train the reader to skip the field.
@@ -359,6 +359,19 @@ export function parsePolicy(text, aliases = null) {
         continue;
       }
       forbid.push({ from: a, to: b, raw: line });
+    } else if (t[0] === "only") {
+      // ⟨0.29⟩ THE PERMISSION FORM. Token-wise like its `forbid` sibling above — the arrow must be its own
+      // token — but everything AFTER the arrow is a permitted scope, so this takes a LIST where `forbid`
+      // takes one destination and ignores the tail. An EMPTY tail is dropped rather than read as "A may
+      // reach nothing at all": that is a different rule, and one far likelier typed by accident than meant.
+      const from = t[1] ?? "", arrow = t[2] ?? "", to = t.slice(3).filter(Boolean);
+      if (!from || arrow !== "->" || !to.length) {
+        warn("malformed only (want `only <scope> -> <scope> [<scope> …]`)");
+        err("rule-kind", t.slice(1).join(" "), ["only <scope> -> <scope> [<scope> …]"], line,
+            DROPPED("want `only <scope> -> <scope> [<scope> …]`"));
+        continue;
+      }
+      only.push({ from, to, raw: line });
     } else {
       warn("unknown rule kind");
       err("rule-kind", t[0], RULE_KIND_VOCAB, line, DROPPED(`unknown rule kind \`${t[0]}\``));
@@ -391,7 +404,7 @@ export function parsePolicy(text, aliases = null) {
   // the correct one on `gate --report` questions. Recorded for the spec to adjudicate.
   // ⟨0.28⟩ `ignored` rides the parse beside `errors` (SPEC §6.2) — see the note on `err`. The gate routes
   // spread it onto the verdict document; `parsepolicy`'s pinned witness shape is untouched.
-  return { deny, allow, forbid, errors, ignored,
+  return { deny, allow, forbid, only, errors, ignored,
            aliasesUsed: Object.fromEntries([...aliasesUsed.entries()].sort((x, y) => (x[0] < y[0] ? -1 : x[0] > y[0] ? 1 : 0))) };
 }
 
@@ -485,6 +498,29 @@ export function refusalVerdict(spec, reason, unevaluated = null) {
 /** §6.2 scope match: by NAME SEGMENT, last segment a prefix.
  * Segments split on BOTH "." and "::" — Rust/Java qualify with "::" while TS uses ".", and a shared
  * policy must match across engines (a `Foo::bar` scope authored against Rust was inert in TS before). */
+// ⟨0.29⟩ SCOPE MATCHING FOR A PERMISSION, where the prefix rule below is FAIL-OPEN.
+//
+// `scopeMatches`'s last segment is a PREFIX of its name-segment, so `util` matches `utilities`. For
+// deny/pure/forbid that widening is FAIL-CLOSED — a scope matching more forbids more — and it is why the
+// rule exists. For the `to` list of an `only` rule it is the exact inverse: a permitted scope matching
+// more PERMITS more, so the matcher that keeps every other rule kind safe silently widens the one form
+// whose entire purpose is to fail safe. MEASURED on the shipped ⟨0.29⟩ implementation: `only model ->
+// util` let `model.go` reach `utilities_untrusted.exfil` at `policy ✓`, while `forbid model -> util`
+// charged AS-EFF-009 on the identical reach.
+//
+// The `from` side KEEPS the prefix rule: it selects which functions the rule BINDS, so matching more
+// constrains more. Each side takes the matcher whose over-approximation errs toward the gate firing.
+export function scopeMatchesPermitted(name, scope) {
+  const segs = name.split(/[.:]+/).filter(Boolean);
+  const parts = scope.split(/[.:]+/).filter(Boolean);
+  if (parts.length === 0 || parts.length > segs.length) return false;
+  outer: for (let i = 0; i + parts.length <= segs.length; i++) {
+    for (let k = 0; k < parts.length; k++) if (segs[i + k] !== parts[k]) continue outer;
+    return true;
+  }
+  return false;
+}
+
 export function scopeMatches(name, scope) {
   const segs = name.split(/[.:]+/).filter(Boolean);
   const parts = scope.split(/[.:]+/).filter(Boolean);
@@ -631,6 +667,69 @@ export function reportNetClasses(functions, { authoritative = false } = {}) {
  * to keep the unevidenced pairs from FIRING (see the note on that parameter — flooring an empty class set
  * at `unresolved` is right for a matcher and wrong for a firing).
  */
+// ── WHOLE-POLICY UNANSWERABLE KINDS ON A REPORT ROUTE (SPEC §3.1 ⟨0.24⟩ ANSWERABILITY) ────────────
+// `forbid` and `allow` cannot be answered from a §2 report, so a route reading one must DISCLOSE them and
+// evaluate what is left — never pass them to the matcher, and never drop them silently.
+//
+// WHY THIS IS A FUNCTION AND NOT A THIRD COPY. It lived inline in `query.mjs`'s `gate --report`, and the
+// two OTHER report-reading routes in this package — the MCP `candor_gate` tool and the LSP diagnostics
+// path — passed the WHOLE policy to `evaluatePolicy`. MEASURED on the real functions with
+// `forbid model -> model`: with no callgraph sidecar (what `loadCallgraph` returns for a hand-copied
+// `report.json`) the answer was `violations: 0, unevaluated: 0` — a SILENT GREEN, the false all-clear the
+// rule exists to prevent; with a sidecar it EVALUATED the rule and returned an AS-EFF-009 violation. Both
+// outcomes the MUST forbids, on the channel an agent reads, for any engine's report (`candor mcp` routes
+// every engine's reports through here). The CLI had the rule and its two siblings did not — so the fix is
+// one implementation with three callers, not three implementations that agree today.
+//
+// Returns { unevaluated, answerable, onlyUnanswerable }:
+//   unevaluated       — [{rule, why}] to disclose on whatever channel the caller has
+//   answerable        — the policy with these kinds REMOVED, safe to hand to evaluatePolicy
+//   onlyUnanswerable  — true when nothing else remains, i.e. there is no verdict to stand beside the
+//                       refusal and the route must refuse outright (⟨0.24⟩ §3.1 `1503368`: whole-policy
+//                       granularity is not a licence to SUPPRESS a certain violation, so when other rules
+//                       can still fire, they decide and these ride along disclosed)
+export function wholePolicyUnanswerable(pol, verb = "this route") {
+  const unevaluated = [];
+  // ⟨0.29⟩ NO COUNT OF THE FILE'S RULES IN A ROW ABOUT ONE OF THEM. The `why` was phrased "this policy
+  // has N `forbid` rule(s)", so with two `forbid` lines BOTH rows said "2" — a fact about the file,
+  // attached to a row that is about one line of it, and the reader's obvious inference (that this row
+  // covers all N) is false. It is a kind-level PREDICATE now, and the SUBJECT is the rule the caller
+  // prints in front of it: `` `forbid a -> b` is a `forbid` rule, which … ``.
+  //
+  // `why` IS SELF-CONTAINED, and that is a decision about the CALLERS rather than about wording. Six
+  // sites print one of these, and THREE of them print `why` alone — `query.mjs`'s advisory disclosure,
+  // the LSP's fix path, and the MCP error, i.e. the agent channel. A predicate-style `why` ("is a
+  // `forbid` rule, which …") reads correctly only where the caller happens to prefix the rule, so those
+  // three would have lost the rule name entirely and read as fragments. Naming the rule HERE cannot be
+  // got wrong by a caller added later; the two sites that used to prefix it drop their prefix.
+  const forbidWhy = (raw) => `\`${raw.trim()}\` is a \`forbid\` rule, which ${verb} cannot evaluate — `
+    + "a report's `calls` graph is not the evidence a NAME-matching dependency rule needs, and a report "
+    + "MUST NOT be back-filled from its sidecar. Gate at scan time (candor-ts <src> --policy <file>).";
+  const allowWhy = (raw) => `\`${raw.trim()}\` is an \`allow\` rule, which ${verb} cannot evaluate — `
+    + "the AS-EFF-008 surface-completeness marker is not guaranteed to ride the wire, and an engine that "
+    + "answered where its siblings refuse would have SPLIT THE VERB. Gate at scan time.";
+  // ⟨0.29⟩ `only` IS AS UNANSWERABLE AS `forbid`, and for a STRICTER reason. Both match on NAME, which a
+  // report's effect-relevant wire cannot settle — but `forbid` asks whether ONE named crossing is present,
+  // while `only` asks whether EVERYTHING reached is on a list. A report that omits a crossing makes
+  // `forbid` read green; it makes `only` read green as a claim of COMPLETENESS.
+  const onlyWhy = (raw) => `\`${raw.trim()}\` is an \`only\` rule, which ${verb} cannot evaluate — it `
+    + "asks whether EVERYTHING a scope reaches is on a list, and a report carries an effect-relevant call "
+    + "surface rather than the complete dependency graph a NAME-matching rule needs. Answering it here "
+    + "would certify completeness from evidence that is not complete. Gate at scan time.";
+  for (const r of pol.forbid ?? []) unevaluated.push({ rule: r.raw, why: forbidWhy(r.raw) });
+  for (const r of pol.only ?? []) unevaluated.push({ rule: r.raw, why: onlyWhy(r.raw) });
+  for (const r of pol.allow ?? []) unevaluated.push({ rule: r.raw, why: allowWhy(r.raw) });
+  return {
+    unevaluated,
+    // REMOVED from the answerable policy, not merely disclosed beside it: a kind left in the object is a
+    // kind `evaluatePolicy` walks, and the disclosure would then stand next to the very evaluation it says
+    // did not happen. (Measured in the java arm of this same port, where the two sites were one line
+    // apart and only the one I was working in got updated.)
+    answerable: { ...pol, allow: [], forbid: [], only: [] },
+    onlyUnanswerable: unevaluated.length > 0 && !pol.deny?.length,
+  };
+}
+
 export function unanswerableScoped(pol, functions, reasonAcc, netMap) {
   const held = new Set(), byRule = new Map();
   const key = (raw, fn, eff) => `${raw}\u0000${fn}\u0000${eff}`;
@@ -837,6 +936,36 @@ export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()
       if (hit) push("AS-EFF-009", fn, [], `\`${fn}\` reaches into a forbidden layer (via \`${hit}\`), violating policy: \`${r.raw}\``);
     }
   }
+  // ⟨0.29⟩ AS-EFF-011 — `only A -> B …`: a fn in A may reach A and the listed scopes, NOTHING else. The
+  // same walk as `forbid` above with the test INVERTED, and the inversion is the point: `forbid` fails
+  // OPEN, so a leaf can only be protected by enumerating what it must not reach — a list that does not
+  // cover a package added tomorrow. `only` fails SAFE.
+  //
+  // THE WALK STOPS AT A PERMITTED SCOPE. A permitted callee's own dependencies are governed by the rules
+  // about IT; descending past it would make `only` demand the transitive closure of everything you permit,
+  // which is the same enumeration-that-rots one level down. `from` IS descended through — a fn in A
+  // calling another fn in A that reaches infra is still A reaching infra.
+  for (const r of pol.only ?? []) {
+    for (const fn of Object.keys(callgraph)) {
+      if (!scopeMatches(fn, r.from)) continue;
+      const seen = new Set([fn]), queue = [fn];
+      let hit = null;
+      while (queue.length && !hit) {
+        for (const c of callgraph[queue.pop()] ?? []) {
+          if (seen.has(c)) continue;
+          seen.add(c);
+          // ⟨0.29⟩ EXACT segment match — the shared prefix matcher is fail-OPEN for a permission.
+          if (r.to.some((t) => scopeMatchesPermitted(c, t))) continue;   // permitted; callees not ours
+          if (!scopeMatches(c, r.from)) { hit = c; break; }
+          queue.push(c);
+        }
+      }
+      // ⟨0.29⟩ ITS OWN CODE, not `forbid`'s — a rule code is what a CI suppression keys on, and these two
+      // are opposite constructs. Sharing 009 would make an existing `forbid` suppression silently mute
+      // `only` violations its author never accepted.
+      if (hit) push("AS-EFF-011", fn, [], `\`${fn}\` reaches \`${hit}\`, which this permission rule does not permit: \`${r.raw}\``);
+    }
+  }
   // ⟨0.27⟩ SPEC §4 — A RULE WHOSE SCOPE BOUND NO FUNCTION IS UNANSWERABLE, AND IS DISCLOSED RATHER THAN
   // SCORED AS SATISFIED. Measured on this engine before the fix: `deny Fs orders` exits 1 on a real
   // violation while `deny Fs ordrs` exits 0 in silence — a one-character typo in a layer name is a
@@ -852,6 +981,11 @@ export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()
   const zeroCount = new Map();
   for (const r of pol.deny) if (r.scope) zeroCount.set(r.raw, 0);
   for (const r of pol.forbid) zeroCount.set(r.raw, 0);
+  // ⟨0.29⟩ …and `only`, counted on `from` ALONE — deliberately not either endpoint the way a `forbid`
+  // counts. A forbid's subject is the pair; an `only`'s subject is the scope it makes a PROMISE about, so
+  // a rule whose destinations all resolve while its `from` names nothing has bound nothing, and that is
+  // exactly the typo that leaves an operator believing a leaf is protected.
+  for (const r of pol.only ?? []) zeroCount.set(r.raw, 0);
   if (zeroCount.size) {
     const names = new Set(functions.map((f) => f.fn));
     for (const k of Object.keys(callgraph ?? {})) names.add(k);
@@ -860,6 +994,9 @@ export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()
       for (const r of pol.forbid) {
         if (scopeMatches(n, r.from) || scopeMatches(n, r.to)) zeroCount.set(r.raw, zeroCount.get(r.raw) + 1);
       }
+      for (const r of pol.only ?? []) {
+        if (scopeMatches(n, r.from)) zeroCount.set(r.raw, zeroCount.get(r.raw) + 1);
+      }
     }
   }
   // ⟨0.27⟩ CODE-POINT order, explicitly — the `zeroMatch` verdict key pins the `viaDispatchOn` collation
@@ -1046,7 +1183,7 @@ export function parseUnknownAliases(configText, errors = null) {
 // partner hosts — the per-project `known-partner` set for the Net destination-class classifier. Multi-value
 // (repeatable key); the value's `:port` is stripped + lowercased like MODEL_HOSTS. Case-insensitive key,
 // mirroring parseUnknownAliases + the java/rust config loaders. A partner is per-project — never universal.
-export function parseNetPartners(configText) {
+export function parseNetPartners(configText, errs = null) {
   const out = new Set();
   if (!configText) return out;
   for (const raw of configText.split(/\r?\n/)) {
@@ -1055,7 +1192,21 @@ export function parseNetPartners(configText) {
     const m = line.match(/^(\S+)\s+(.*)$/);
     if (!m || m[1].toLowerCase() !== "net-partner") continue;
     const val = m[2].trim();
-    if (val) out.add(hostPart(val).toLowerCase());
+    // ⟨0.29⟩ A MALFORMED VALUE IS DISCLOSED, NOT SILENTLY KEPT AS JUNK. The grammar is
+    // `net-partner <host>`; the `=` spelling an operator reaches for by habit
+    // (`net-partner = partner.example`) parsed as the HOST "= partner.example", which entered the set and
+    // matched nothing for the rest of the run. The direction is safe — the gate stays armed, so nothing
+    // is certified that should not be — which is exactly why it can sit unnoticed: the operator believes
+    // a partner is declared, the verdict says otherwise, and no line connects the two. ⟨0.28⟩ gave POLICY
+    // files an `ignored` block for this; config files had no equivalent.
+    if (!val) continue;
+    if (/\s/.test(val) || val.startsWith("=")) {
+      errs?.push({ kind: "config-value", raw: raw.trim(),
+                   why: `net-partner takes a bare host — \`net-partner <host>\`, one per line; `
+                      + `'${val}' is not one and was IGNORED (an '=' or extra words is the usual cause)` });
+      continue;
+    }
+    out.add(hostPart(val).toLowerCase());
   }
   return out;
 }

package/query.mjs

@@ -27,9 +27,9 @@ import { parsePolicy, scopeMatches, discoverConfigPolicy, parseUnknownAliases, d
          evaluatePolicy, reportNetClasses, resolveReasonClasses, discoverConfigPath,
          policyVocabularyAnchor, policyErrorText, policyRefusalUnevaluated, policyUnreadable, policyZeroRules,
          fatalPolicyErrors, refusalVerdict,
-         unanswerableScoped } from "./policy.mjs";
+         unanswerableScoped, wholePolicyUnanswerable } from "./policy.mjs";
 import { hasReport } from "./query-core.mjs";
-import { printAgents } from "./contract.mjs";
+import { printAgents, writeStdoutSync } from "./contract.mjs";
 import { bestFinds } from "./surface.mjs";
 import { isTestPath } from "./scan-core.mjs";
 // ONE source of truth for loading + name-matching — query.mjs kept DRIFTED local copies that didn't
@@ -47,7 +47,12 @@ import { impact as coreImpact, path as corePath, gains as coreGains,
          reportVersion, reportPackage,
          advisoryAnswer,
          reportCompleteness, mustHedge, completenessFields, absorbCompleteness } from "./query-core.mjs";
-const emit = (v) => console.log(JSON.stringify(v, null, 1));
+// writeStdoutSync, NOT console.log — and this ONE line covers all twelve `emit` sites, which is the
+// point. console.log is asynchronous on a pipe and every verb here ends in `process.exit(...)`, which
+// discards whatever is still buffered. MEASURED on the sibling path (`scan.mjs --json`): 95281 bytes to a
+// FILE and valid JSON, 65536 bytes through a PIPE and a JSONDecodeError. These are the query documents an
+// agent pipes into `jq`; `map`/`where`/`blindspots` over a real report clear the buffer easily.
+const emit = (v) => writeStdoutSync(JSON.stringify(v, null, 1) + "\n", "the verdict document");
 // ⟨0.24⟩ SPEC §3.2 — THE OTHER CHANNEL. `advisoryAnswer` withdraws the claim from the JSON; this withdraws
 // it from the one a human reads, and the spec requires both because a test that reads one channel is
 // evidence about one channel. candor-rust built a mutant that kept the whole JSON fix and deleted only the
@@ -106,7 +111,8 @@ const UNEVAL_TAIL_STRICT = "(`ok` is OMITTED — neither value is a statement th
 //
 // A policy that is NOT CONFIGURED is untouched: that remains the honest way to say "I am not gating"
 // (§6.2), and it is exactly why a configured zero-rule policy is never a legitimate expression of it.
-const policyAskedNothing = (pol) => !!pol && !pol.deny.length && !pol.allow.length && !pol.forbid.length;
+const policyAskedNothing = (pol) => !!pol && !pol.deny.length && !pol.allow.length && !pol.forbid.length
+  && !(pol.only ?? []).length;   // ⟨0.29⟩ an `only`-only policy is ARMED
 const emitZeroRuleCaveat = (verb, policyFile, comp) => {
   const { unevaluated } = policyZeroRules(policyFile);
   console.error(`candor-ts: ${verb}: the policy at ${policyFile} yielded NO RULES — every line was ignored `
@@ -503,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.28";
+const SPEC_VERSION = "0.29";
 
 // ---- 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]
@@ -843,8 +849,9 @@ function resolveGateReportVerb(rawArgs) {
       if (gate === "-") {
         process.on("exit", (code) => {
           if (code === 2 && !globalThis.__candorGateVerdictWritten) {
-            console.log(JSON.stringify(refusalVerdict(SPEC_VERSION,
-              "the gate did not complete — this run exited before a verdict could be produced", null), null, 1));
+            writeStdoutSync(JSON.stringify(refusalVerdict(SPEC_VERSION,
+              "the gate did not complete — this run exited before a verdict could be produced", null), null, 1)
+              + "\n", "the refusal verdict");
           }
         });
       }
@@ -1543,7 +1550,7 @@ switch (cmd) {
       // mostly-Unknown graph; a report that judged nothing, or that names a file it could not read, yields
       // the IDENTICAL empty array from strictly less evidence, and an unread unit contributes no entry, so
       // it moves neither `unknown` nor `total`. Spread last, `{}` on a complete report.
-      console.log(JSON.stringify({ ...out, ...completenessFields(tourComp) }));
+      writeStdoutSync(JSON.stringify({ ...out, ...completenessFields(tourComp) }) + "\n", "tour");
       break;
     }
     incompleteAnswerNote(tourComp,
@@ -1809,6 +1816,15 @@ switch (cmd) {
     // ⟨0.24⟩ SPEC §3.2 — see `advisoryAnswer`. Over a report declaring `unanalyzed` this OMITS `ok`, adds
     // the manifest, and `--strict` (the CI form) exits 2 — could-not-fully-evaluate, the same code the gate
     // uses for the same situation — rather than the 1 that would claim a finding or the 0 that certified.
+    // ⟨0.29⟩ …AND THE TWO WHOLE-POLICY UNANSWERABLE KINDS, which this verb never received. `fix-gate`'s
+    // `unevaluated` machinery — the note, the OMITTED `ok`, the `--strict` exit 2 — has been here since
+    // ⟨0.24⟩ and works; its INPUT was incomplete. `coreUnverified`/`coreFixGate` report scoped-`deny`
+    // refusals only, so a policy whose rules were ALL `forbid` produced an empty refusal set and this verb
+    // answered `{ok: true}` over a policy nothing had evaluated. MEASURED four-way: java disclosed and
+    // withheld `ok`; rust printed a green ✓ at exit 0; ts and swift emitted `ok: true`. The reference
+    // engine was the only one right, which is the signal to fix the other three rather than argue.
+    { const wp = wholePolicyUnanswerable(fgpol, "a report route");
+      if (wp.unevaluated.length) fgr.unevaluated = [...(fgr.unevaluated ?? []), ...wp.unevaluated]; }
     const fgComp = reportCompleteness(prefix);
     const fgUnan = fgComp.unanalyzed;
     if (fgUnan.length) advisoryIncompleteNote("fix-gate", fgUnan);
@@ -1869,6 +1885,15 @@ switch (cmd) {
     // entire job is "your green gate is not provably green" was certifying a set it knows it cannot see all
     // of. A function in an unparsed file is absent from `functions`, so it cannot be enumerated as an
     // unverified pass — and that absence is exactly what this verb would have to report.
+    // ⟨0.29⟩ …AND THE TWO WHOLE-POLICY UNANSWERABLE KINDS, which this verb never received. `unverified`'s
+    // `unevaluated` machinery — the note, the OMITTED `ok`, the `--strict` exit 2 — has been here since
+    // ⟨0.24⟩ and works; its INPUT was incomplete. `coreUnverified`/`coreFixGate` report scoped-`deny`
+    // refusals only, so a policy whose rules were ALL `forbid` produced an empty refusal set and this verb
+    // answered `{ok: true}` over a policy nothing had evaluated. MEASURED four-way: java disclosed and
+    // withheld `ok`; rust printed a green ✓ at exit 0; ts and swift emitted `ok: true`. The reference
+    // engine was the only one right, which is the signal to fix the other three rather than argue.
+    { const wp = wholePolicyUnanswerable(upol, "a report route");
+      if (wp.unevaluated.length) r.unevaluated = [...(r.unevaluated ?? []), ...wp.unevaluated]; }
     const uComp = reportCompleteness(prefix);
     const uUnan = uComp.unanalyzed;
     if (uUnan.length) advisoryIncompleteNote("unverified", uUnan);
@@ -1976,7 +2001,7 @@ switch (cmd) {
     // §3.1's byte-equality MUST, which a one-route rung would break on the `# nothing` policy. Every rule
     // vector, never a subset: `deny` (deny + pure), `allow`, `forbid` — keying on one would refuse an
     // ordinary allow-only or forbid-only gate as if it had no rules.
-    if (!gpol.deny.length && !gpol.allow.length && !gpol.forbid.length) {
+    if (!gpol.deny.length && !gpol.allow.length && !gpol.forbid.length && !(gpol.only ?? []).length) {
       const { why, unevaluated } = policyZeroRules(policyFile);
       console.error(`candor-ts: gate: ${why} — refusing (exit 2, gate NOT enforced). Every line was ignored `
         + `(see the \`ignoring policy rule\` warnings above), the file is empty, or it holds only comments. A `
@@ -2000,18 +2025,18 @@ switch (cmd) {
     // does not care which KIND of refusal stands beside the firing rule. They are now UNEVALUATED rules
     // disclosed beside whatever the rest of the policy decided; a policy that is nothing BUT these still
     // refuses below, because then there is no verdict to dominate them.
-    const gunevaluated = [];
-    if (gpol.forbid.length) {
-      const why = `this policy has ${gpol.forbid.length} \`forbid\` rule(s), which \`gate --report\` cannot evaluate — a report's \`calls\` graph is EFFECT-RELEVANT (only callees with a non-empty effect set are kept), so a crossing into a wholly PURE unit is invisible in it while \`forbid\` matches on NAME. The rule would read green where a scan fails. Gate layering at scan time: candor-ts <src> --policy ${policyFile}`;
-      console.error(`candor-ts: gate: ${why}`);
-      for (const r of gpol.forbid) gunevaluated.push({ rule: r.raw, why });
-    }
-    if (gpol.allow.length) {
-      const effs = [...new Set(gpol.allow.map((r) => r.effect))].sort();
-      const why = `this policy has \`allow ${effs.join("`/`")}\` rule(s), which \`gate --report\` cannot evaluate — the AS-EFF-008 surface-completeness marker does not ride the report wire in any form, so a benign visible literal beside a runtime-computed endpoint would be CERTIFIED here and flagged by a scan. (\`netClass: unknown-host\` is NOT that marker — it also names a merely UNRECOGNISED host, so reading it as "masked" flags functions whose surface is fully visible.) Gate allowlists at scan time: candor-ts <src> --policy ${policyFile}`;
-      console.error(`candor-ts: gate: ${why}`);
-      for (const r of gpol.allow) gunevaluated.push({ rule: r.raw, why });
-    }
+    // ⟨0.29⟩ ONE IMPLEMENTATION, THREE CALLERS. This block used to live here and only here, and the two
+    // other report-reading routes in this package (the MCP `candor_gate` tool, the LSP diagnostics path)
+    // passed the whole policy to the matcher — so `forbid` was answered from a report on the agent
+    // channel while the CLI refused it. Moved into `wholePolicyUnanswerable` so the next route inherits
+    // the rule instead of being audited into it.
+    const gwp = wholePolicyUnanswerable(gpol, "`gate --report`");
+    const gunevaluated = gwp.unevaluated;
+    // One line per rule, each NAMING the rule. The previous shape printed a single kind-level sentence
+    // for the whole policy, so an operator with three `forbid` rules learned that three rules were
+    // unenforced and not which. The `unevaluated` array in the JSON document already carried `rule`; the
+    // human channel simply did not show it.
+    for (const u of gunevaluated) console.error(`candor-ts: gate: ${u.why}`);
     const g = loadGateReport(prefix);
     // ANY report under the locator that did not load cleanly REFUSES THE WHOLE GATE — not just the case
     // where they ALL failed. The old guard was `functions.length === 0 && hardFail`, i.e. it fired only
@@ -2101,7 +2126,7 @@ switch (cmd) {
     // kinds, now disclosed as `unevaluated` instead of short-circuiting (`1503368`), and handing them to the
     // matcher would be the very evaluation-on-partial-evidence they are unanswerable FOR — `allow` would
     // fire AS-EFF-008 "no visible literal" on every report entry whose surface the wire does not carry.
-    const gviol = evaluatePolicy({ deny: gpol.deny, allow: [], forbid: [] },
+    const gviol = evaluatePolicy(gwp.answerable,
                                  g.functions, {}, new Map(), new Set(), gnet, gwithhold);
     // Route the human output exactly as a scan does: to stderr whenever stdout carries the verdict
     // document, so `candor-ts-query gate … --json | jq` sees pure JSON.