candor-ts 0.25.0 → 0.27.0

package/AGENTS.md

@@ -12,7 +12,7 @@ chains by hand.
 > **Already installed? Report the version and ask before upgrading — before you scan.** If this
 > project already has candor (a `.candor/` report directory, or `candor-ts` reachable via `npx`/a
 > global install), do this *first*: run `npx -y candor-ts --version` (offline) and **tell the user
-> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.25)."*
+> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.27)."*
 > 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.25" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
+| `{ candor: { version, toolchain, spec: "0.27" }, 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.19.x, speaking candor-spec 0.25: the analysis core, the gate (`--policy` / `--gate-json` /
+0.19.x, speaking candor-spec 0.27: 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.25.0",
-  "description": "candor for TypeScript \u2014 per-function side effects, transitively, with a policy gate (candor-spec 0.25)",
+  "version": "0.27.0",
+  "description": "candor for TypeScript \u2014 per-function side effects, transitively, with a policy gate (candor-spec 0.27)",
   "type": "module",
   "dependencies": {
     "@types/node": "^25.9.2",

package/policy.mjs

@@ -796,6 +796,65 @@ 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.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
+  // permanently green gate, and `unverified` then calls the layer "PROVABLY clean". The asymmetry is the
+  // tell: a typo'd EFFECT token already exits 2 naming the accepted vocabulary.
+  //
+  // Carried as a PROPERTY on the returned array rather than as a second return value, so every existing
+  // caller keeps working unchanged and `--gate-json` is untouched: JSON.stringify ignores non-index
+  // properties on an array, so the verdict document cannot acquire a field the spec has not pinned.
+  //
+  // A `deny`/`pure` with NO scope applies to every function and so can never be this kind of typo —
+  // excluded. A `forbid` counts a match on either endpoint. Counted over the same names the gate saw.
+  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);
+  if (zeroCount.size) {
+    const names = new Set(functions.map((f) => f.fn));
+    for (const k of Object.keys(callgraph ?? {})) names.add(k);
+    for (const n of names) {
+      for (const r of pol.deny) if (r.scope && scopeMatches(n, r.scope)) zeroCount.set(r.raw, zeroCount.get(r.raw) + 1);
+      for (const r of pol.forbid) {
+        if (scopeMatches(n, r.from) || scopeMatches(n, r.to)) zeroCount.set(r.raw, zeroCount.get(r.raw) + 1);
+      }
+    }
+  }
+  // ⟨0.27⟩ CODE-POINT order, explicitly — the `zeroMatch` verdict key pins the `viaDispatchOn` collation
+  // (SPEC §4), and JS's default sort orders by UTF-16 code unit, which disagrees above the BMP. The raw
+  // line is built from user identifiers, so this is reachable rather than theoretical.
+  out.zeroMatch = [...zeroCount].filter(([, c]) => c === 0).map(([raw]) => raw)
+    .sort((a, b) => {
+      const ai = [...a], bi = [...b];
+      for (let i = 0; i < Math.min(ai.length, bi.length); i++) {
+        const d = ai[i].codePointAt(0) - bi[i].codePointAt(0);
+        if (d) return d;
+      }
+      return ai.length - bi.length;
+    });
+  return out;
+}
+
+// ⟨0.27⟩ EVERY RULE OF A REFUSED POLICY, one `unevaluated` entry per raw line (SPEC §3.1's
+// composed-document clause; candor-java `unhonouredRules` is the model). `policyErrorUnevaluated` above
+// names only the UNHONOURABLE lines — measured, that let a consumer read `deny Fs`, absent from the list
+// on an exit-1 document, as evaluated-and-passed: a per-rule false all-clear arriving through the
+// disclosure itself. The unhonourable lines keep their specific `why`; every other rule line carries the
+// whole-policy refusal, because a policy is evaluated as a whole or not at all. ONE builder for both gate
+// routes, for the same byte-equality reason as its siblings above.
+export function policyRefusalUnevaluated(policyText, errors) {
+  const fatal = new Map(policyErrorUnevaluated(errors).map((e) => [e.rule, e.why]));
+  const out = [];
+  for (const raw of policyText.split(/\r?\n/)) {
+    const line = raw.split("#", 1)[0].trim();
+    if (!line) continue;
+    out.push({ rule: line,
+      why: fatal.get(line)
+        ?? "NOT EVALUATED — a rule elsewhere in this policy cannot be honoured as written (named beside "
+         + "its own entry in this list), and a policy is evaluated as a whole or not at all: a verdict "
+         + "from its readable subset would be a verdict on a policy nobody wrote." });
+  }
   return out;
 }
 
@@ -813,7 +872,13 @@ export function discoverConfigPolicy(fromDir) {
   for (;;) {
     const cand = nodePath.join(dir, ".candor", "config");
     if (fs.existsSync(cand)) {
-      const m = fs.readFileSync(cand, "utf8").split(/\r?\n/)
+      // A config that EXISTS but cannot be READ is configured-but-unusable, which §3.4 makes exit 2 —
+      // never a silent "absent" and never an uncaught throw. The bare `readFileSync` here let an EACCES
+      // escape as an uncaught exception: node exits 1, which is the POLICY VIOLATION code, and the
+      // armed sentinel survived because nothing replaced it. Two wrong answers from one missing catch.
+      // The siblings below swallow to null, which is the other wrong answer — an unreadable pin or
+      // policy silently not enforced — so all three now refuse the same way.
+      const m = readConfigOrRefuse(cand).split(/\r?\n/)
         .map((l) => l.split("#", 1)[0].trim()).filter(Boolean)
         .map((l) => l.match(/^(\S+)\s*(.*)$/)).find((mm) => mm && mm[1].toLowerCase() === "policy");
       if (!m) return null;
@@ -829,11 +894,11 @@ export function discoverConfigPolicy(fromDir) {
 // nearest `.candor/config` walking UP, else null. Read-only + lenient (the caller decides fail-closed).
 export function discoverConfigText(fromDir) {
   const env = process.env.CANDOR_CONFIG;
-  if (env) { try { return fs.readFileSync(env, "utf8"); } catch { return null; } }
+  if (env) { return readConfigOrRefuse(env, "CANDOR_CONFIG"); }
   let dir = nodePath.resolve(fromDir);
   for (;;) {
     const cand = nodePath.join(dir, ".candor", "config");
-    if (fs.existsSync(cand)) { try { return fs.readFileSync(cand, "utf8"); } catch { return null; } }
+    if (fs.existsSync(cand)) { return readConfigOrRefuse(cand); }
     const parent = nodePath.dirname(dir);
     if (parent === dir) return null;
     dir = parent;
@@ -846,9 +911,31 @@ export function discoverConfigText(fromDir) {
 // see named anywhere in the output — can decide the verdict. That is the ambient-input failure this format
 // exists to refuse, and the remedy is the usual one: not to forbid the input, but to make it unable to act
 // unnamed. Same walk as `discoverConfigText`, deliberately, so the two cannot name different files.
+/**
+ * Read a `.candor/config` that DISCOVERY has already found, or refuse (exit 2).
+ *
+ * The three readers in this file each handled an unreadable-but-present config differently: one let the
+ * exception escape (node exits 1 — the POLICY VIOLATION code — with a stack trace, and an armed
+ * `--gate-json` sentinel left in place), and two swallowed it to `null`, which reads as "no config" and
+ * silently drops whatever the file configured: a policy, a baseline, or an engine pin the operator
+ * believes is guarding them. §3.4's posture is the unreadable-policy one — configured-but-unusable
+ * fails loud — so all three route through here.
+ */
+function readConfigOrRefuse(p, via = null) {
+  try {
+    return fs.readFileSync(p, "utf8");
+  } catch (e) {
+    console.error(`candor-ts: ${via ? `${via}=` : ""}${p} exists but could not be read (${e.code ?? e.message}) `
+      + `— failing (exit 2, unevaluable). A config that cannot be read is a guard the operator believes `
+      + `is on: it may name a policy, a baseline or an engine pin, and treating it as absent would run `
+      + `without them.`);
+    process.exit(2);
+  }
+}
+
 export function discoverConfigPath(fromDir) {
   const env = process.env.CANDOR_CONFIG;
-  if (env) { try { fs.readFileSync(env, "utf8"); return nodePath.resolve(env); } catch { return null; } }
+  if (env) { readConfigOrRefuse(env, "CANDOR_CONFIG"); return nodePath.resolve(env); }
   let dir = nodePath.resolve(fromDir);
   for (;;) {
     const cand = nodePath.join(dir, ".candor", "config");

package/query-core.mjs

@@ -696,13 +696,37 @@ export const byCodePoint = (a, b) => {
 };
 
 // Reflexive+transitive subtype test over the hierarchy sidecar.
-function isSubtypeOf(type, owner, hierarchy) {
-  if (type === owner) return true;
+//
+// ⟨0.26⟩ THREE-VALUED, because the format now distinguishes what it could not before. SPEC §2.2 makes the
+// KEY SET the manifest: a producer emits a key for every type it indexed, `[]` included, so a type with NO
+// key is one the pass never looked at. `hierarchy[t] ?? []` read those two cases alike and answered
+// `false` — a positive claim about a type nobody analysed.
+//
+// MEASURED before the rung, doctoring only the sidecar of a real scan: removing the REACHING implementor's
+// entry silently dropped the dispatcher from `possibleViaUnknownDispatch` (`[]` where the control gives
+// `[Dispatcher.run]`), while removing the sidecar ENTIRELY left it correct — the ⟨0.24⟩ per-file rule
+// over-lists. LESS information was SAFER than partial information. candor-java behaved identically, which
+// is what said the defect was the FORMAT rather than either consumer.
+//
+// A POSITIVE DOMINATES: if a known path reaches `owner` the answer is YES even when another branch ran
+// into an unindexed type — the relation is established and an unknown branch cannot un-establish it. NO is
+// reserved for a walk that stayed entirely inside types the sidecar answers for.
+function subtypeOf(type, owner, hierarchy) {
+  if (type === owner) return "YES";
+  let sawUnindexed = false;
   const seen = new Set(), stack = [type];
   while (stack.length) {
-    for (const s of hierarchy[stack.pop()] ?? []) { if (s === owner) return true; if (!seen.has(s)) { seen.add(s); stack.push(s); } }
+    const cur = stack.pop();
+    if (!Object.prototype.hasOwnProperty.call(hierarchy, cur)) { sawUnindexed = true; continue; }
+    for (const s of hierarchy[cur]) { if (s === owner) return "YES"; if (!seen.has(s)) { seen.add(s); stack.push(s); } }
   }
-  return false;
+  return sawUnindexed ? "UNANSWERABLE" : "NO";
+}
+
+// The two-valued form. UNANSWERABLE collapses to TRUE — disclose, never drop — which is the direction
+// §2.2 ⟨0.26⟩ requires and the opposite of what absence used to do.
+function isSubtypeOf(type, owner, hierarchy) {
+  return subtypeOf(type, owner, hierarchy) !== "NO";
 }
 
 // callers + the unresolved-dispatch frontier (--include-unknown, SPEC §3.1/§4 0.7): the CONFIRMED set,
@@ -1236,7 +1260,7 @@ export function narrowingContext(fns, cg = {}, policyParsed = null) {
           const u = byRaw.get(r.raw);
           if (!u) continue;                                  // unreachable: every held triple has a group
           const cur = heldByFn.get(f.fn) ?? new Map();
-          cur.set(`${r.raw}${eff}`, { fn: f.fn, rule: r.raw, effect: eff, why: u.why });
+          cur.set(`${r.raw}\0${eff}`, { fn: f.fn, rule: r.raw, effect: eff, why: u.why });
           heldByFn.set(f.fn, cur);
         }
   return {

package/query.mjs

@@ -25,7 +25,7 @@ import { fileURLToPath } from "node:url";
 
 import { parsePolicy, scopeMatches, discoverConfigPolicy, parseUnknownAliases, discoverConfigText,
          evaluatePolicy, reportNetClasses, resolveReasonClasses, discoverConfigPath,
-         policyVocabularyAnchor, policyErrorText, policyErrorUnevaluated, policyUnreadable,
+         policyVocabularyAnchor, policyErrorText, policyRefusalUnevaluated, policyUnreadable,
          fatalPolicyErrors, refusalVerdict,
          unanswerableScoped } from "./policy.mjs";
 import { hasReport } from "./query-core.mjs";
@@ -232,7 +232,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.25";
+const SPEC_VERSION = "0.27";
 
 // ---- 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]
@@ -437,9 +437,122 @@ function resolveGateVerb(rawArgs, { strict = false } = {}) {
 // deprecated-alias machinery, because it has NO POSITIONALS: a stray argument is a usage error, never
 // probed as a report or a policy. Kept out of parseCanonical for that reason — the peel helpers exist to
 // accept the old grammar, and there is no old grammar for a verb introduced at ⟨0.24⟩.
+// ── SPEC §3.3.1 ⟨0.27⟩ sink-arming helpers, shared by the gate verb. The scan entry point has its own
+// copies (scan.mjs) because it must not import from this file; the RULES are the spec's, not shared code.
+
+/** Learn `--gate-json` and `--policy` from a verb's argv with NO side effects. */
+function preScanGateArgs(av) {
+  let gate = null, policy = null, report = null;
+  for (let i = 0; i < av.length; i++) {
+    const a = av[i], v = av[i + 1];
+    if (a !== "--gate-json" && a !== "--policy" && a !== "--report") continue;
+    if (v === undefined || (v.startsWith("-") && v !== "-")) continue;
+    if (a === "--gate-json") gate = v; else if (a === "--policy") policy = v; else report = v;
+    i++;
+  }
+  return { gate, policy, report };
+}
+
+/** Artifact identity, not string identity — `--policy /w/P --gate-json ./P` from /w is one file. */
+function sameArtifactPath(a, b) {
+  if (!a || !b || a === "-" || b === "-") return false;
+  const resolve = (p) => {
+    try { return fs.realpathSync(p); } catch { /* not there yet — resolve the parent */ }
+    try { return path.join(fs.realpathSync(path.dirname(path.resolve(p))), path.basename(p)); }
+    catch { return null; }
+  };
+  const x = resolve(a);
+  return x !== null && x === resolve(b);
+}
+
+/** The files the CWD-discovered \`.candor/config\` names, resolved as the loader resolves them. */
+function configDeclaredInputs() {
+  const out = [];
+  try {
+    const disc = discoverConfigPolicy(process.cwd());
+    if (disc?.policyPath) out.push([disc.policyPath, "the config policy key"]);
+    const cfgPath = discoverConfigPath(process.cwd());
+    if (cfgPath) out.push([cfgPath, 'the discovered .candor/config']);
+  } catch { /* lenient: the real load refuses on its own terms */ }
+  return out;
+}
+
+/** Refuse a sink that names an input of this run, having written nothing. */
+function refuseGateJsonOverInput(gate, other, flag) {
+  if (!sameArtifactPath(gate, other)) return;
+  console.error(`candor-ts-query: --gate-json ${gate} names the SAME FILE as ${flag} ${other} — refusing `
+    + `(exit 2). The verdict is armed before the policy is read, so this would overwrite your policy and `
+    + `then gate on the wreckage. Nothing was written; give the verdict its own path.`);
+  process.exit(2);
+}
+
+/** `.candor/config` is never a verdict sink, wherever it is. */
+function refuseGateJsonAtConfig(gate) {
+  if (!gate || gate === "-") return;
+  const abs = path.resolve(gate);
+  if (path.basename(abs) !== "config" || path.basename(path.dirname(abs)) !== ".candor") return;
+  console.error(`candor-ts-query: --gate-json ${gate} is a .candor/config — refusing (exit 2). This would `
+    + `destroy the config that configures this run. Nothing was written; give the verdict its own path.`);
+  process.exit(2);
+}
+
+/** Write the fail-closed refusal every later exit inherits unless a real verdict replaces it. */
+function armQueryGateJson(p) {
+  try {
+    fs.writeFileSync(p, JSON.stringify(
+      refusalVerdict(SPEC_VERSION, "the gate did not complete — this document was written when the run "
+        + "STARTED and was never replaced by a verdict, so the run failed, crashed or was killed before "
+        + "it could decide. It is NOT a verdict about the code; see the run's stderr for the cause."),
+      null, 1) + "\n");
+  } catch (e) {
+    console.error(`candor-ts-query: could not arm --gate-json ${p} fail-closed (${e.message})`);
+  }
+}
+
 function resolveGateReportVerb(rawArgs) {
   const usageLine = "usage: candor-ts-query gate --report <locator> --policy <file> [--json] [--gate-json <file>]";
   let reportLocator = null, policyFile = null, gateJsonPath = null, json = false;
+  // SPEC §3.3.1 ⟨0.27⟩ — ARM FIRST, AND NEVER OVER AN INPUT. A pre-pass with no side effects, so both
+  // the collision refusal and the arming precede every exit in the loop below. See the note where the
+  // arming used to live for why the previous ordering was wrong.
+  {
+    const { gate, policy, report } = preScanGateArgs(rawArgs);
+    if (gate) {
+      refuseGateJsonOverInput(gate, policy, "--policy");
+      // §3.3.1 names "a report being read (`gate --report`)" as an input. Writing the verdict there
+      // destroys the very report the gate was asked to judge, and the diagnostic then blames the report
+      // rather than the collision.
+      refuseGateJsonOverInput(gate, report, "--report");
+      refuseGateJsonOverInput(gate, process.env.CANDOR_POLICY, "CANDOR_POLICY");
+      // THE CONFIG-DECLARED POLICY. This verb's policy ladder falls back to the \`policy\` key of the
+      // config discovered from the CWD, and the guard checked only the flags — so the checked-in form,
+      // which is the one a CI job has, was destroyed at exit 0 while the flag form refused. The same
+      // hole the scan route closed, one route across.
+      for (const [p2, label] of configDeclaredInputs()) refuseGateJsonOverInput(gate, p2, label);
+      refuseGateJsonAtConfig(gate);
+      if (gate !== "-") armQueryGateJson(gate);
+      // …AND THE STREAM'S ANALOG OF ARMING. `armQueryGateJson` writes a fail-closed placeholder to a
+      // FILE; a stream cannot hold one, so the equivalent is a hook that emits the refusal on any
+      // exit-2 path that has not already written a verdict.
+      //
+      // Without it, this verb exited 2 during ARGUMENT PARSING with stdout EMPTY, while the same verb
+      // refusing later from inside the gate streamed the document — the same operator mistake, two
+      // answers, decided by how early it was caught. A machine consumer reading an empty stream after
+      // exit 2 cannot tell it from a clean gate.
+      //
+      // Measured at the 0.27 go/no-go: java, swift and ts all had this hole on the `gate` verb, and
+      // PART 36's stream rows never reached it because every one of them runs the SCAN route. The row
+      // that catches it is now there.
+      else {
+        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));
+          }
+        });
+      }
+    }
+  }
   for (let i = 0; i < rawArgs.length; i++) {
     const a = rawArgs[i];
     if (a === "--report") {
@@ -469,8 +582,18 @@ function resolveGateReportVerb(rawArgs) {
     console.error(`candor-ts-query gate: unexpected argument '${a}' — \`gate\` takes no positionals; the report is a --report locator and the policy a --policy file\n  ${usageLine}`);
     process.exit(2);
   }
+  // ARMING MOVED ABOVE THE FLAG LOOP (SPEC §3.3.1 ⟨0.27⟩).
+  //
+  // It used to sit here, and the comment justified it with a ⟨0.24⟩ ruling of my own: "a USAGE error was
+  // never a gate invocation, so it must write NOTHING". SPEC §3.3 says the opposite in terms — it names
+  // an unknown flag as a broken-gate-config exit-2 cause, and §3.1 adds that "if `--gate-json` was
+  // requested and the run exits 2 for ANY reason, a fail-closed document is written", calling a
+  // carve-out "a fail-open path with a reason attached". The ruling I built here was that carve-out, and
+  // the test pinning it pinned a reading the spec had already superseded. The stale green does not care
+  // that the operator's shell also failed.
+  const _policy = resolvePolicy(policyFile, null).policyFile;
   const prefix = requireReport(reportLocator !== null ? locatorToPrefix(reportLocator) : discoverReportPrefix());
-  return { prefix, policyFile: resolvePolicy(policyFile, null).policyFile, gateJsonPath, json };
+  return { prefix, policyFile: _policy, gateJsonPath, json };
 }
 
 /**
@@ -1139,7 +1262,13 @@ switch (cmd) {
     const gwrite = (obj) => {
       const text = JSON.stringify(obj, null, 1);
       for (const dest of gdests) {
-        if (dest === "-") { console.log(text); continue; }
+        // THE FLAG IS SET WHERE THE WRITE HAPPENS, not where the gate is entered. It was set on
+        // entering this verb, under the comment "reaching here means the gate ran and will write its
+        // own document" — which is a claim about the future, and false: the `--policy` fallback ladder
+        // can still exit 2 below without writing. That suppressed the pre-pass hook and returned the
+        // run to EMPTY stdout after exit 2, which is the exact channel the hook was added to close.
+        // Caught by the second go/no-go panel; the first flag placement lasted about an hour.
+        if (dest === "-") { globalThis.__candorGateVerdictWritten = true; console.log(text); continue; }
         // A SURFACING side-output: an unwritable path is one stderr line, never a raw ENOENT crash whose
         // exit 1 would read as a policy violation on a clean run (the scan path's rule).
         try {
@@ -1182,7 +1311,9 @@ switch (cmd) {
     // uses (SPEC §3.1 makes byte-equality between the two documents the acceptance test — the scan route
     // needed this list so a dominating baseline regression could carry the refusal beside it, and a list on
     // one route only would break the equality on the very change that repaired the precedence).
-    if (gfatal.length) { const why = policyErrorText(policyFile, gfatal); console.error(why); grefuse(why, policyErrorUnevaluated(gfatal)); }
+    // ⟨0.27⟩ …listing EVERY rule of the refused policy, not only the unhonourable lines — the shared
+    // builder with the scan route (SPEC §3.1's composed-document clause; byte-equality binds the two).
+    if (gfatal.length) { const why = policyErrorText(policyFile, gfatal); console.error(why); grefuse(why, policyRefusalUnevaluated(gtext, gfatal)); }
     // ⟨0.24⟩ THE CONFIG FILE THAT SUPPLIED VOCABULARY THE VERDICT USED (SPEC §3.1 `99eb4e9`) — named on a
     // REFERENCE, not only on a firing, because the measured harm was a GREEN verdict a vocabulary file made
     // green. Omitted when no alias was used, so every other verdict stays byte-identical to before.
@@ -1305,6 +1436,17 @@ switch (cmd) {
     // 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.
     const gsay = (json || gateJsonPath === "-") ? (l) => console.error(l) : (l) => console.log(l);
+    // ⟨0.27⟩ SPEC §4 — THE ZERO-MATCH DISCLOSURE BELONGS ON THIS ROUTE TOO. Its absence was found by a
+    // cross-engine differential: java and swift disclosed on `gate --report`, rust and ts did not, so
+    // the same typo'd policy was reported by two engines and silently scored as satisfied by two. §4's
+    // MUST carries no route qualifier, and this is the SUPPLY-CHAIN gate — a consumer pointing a policy
+    // at a report someone else produced. ALWAYS on stderr, never through `gsay`: this is a disclosure
+    // about the policy, not a verdict line, and stdout may be carrying the verdict document.
+    for (const raw of gviol.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 `
+        + `repos; a typo'd layer name otherwise.`);
+    }
     for (const x of gviol) gsay(`[${x.rule}] ${x.detail}`);
     // ⟨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
@@ -1325,6 +1467,9 @@ switch (cmd) {
     if (gvocab) gverdictObj.policyVocabulary = gvocab;
     gverdictObj.violations = gviol;
     if (gunevaluated.length) gverdictObj.unevaluated = gunevaluated;
+    // ⟨0.27⟩ SPEC §4 `zeroMatch` — the same list the stderr lines above carry, in the machine channel,
+    // in the same position the scan route puts it (§3.1's byte-equality MUST binds the two documents).
+    if (gviol.zeroMatch?.length) gverdictObj.zeroMatch = gviol.zeroMatch;
     if (gincomplete) { gverdictObj.incomplete = true; gverdictObj.unanalyzed = g.unanalyzed; }
     if (g.coverage.length)
       gverdictObj.coverage = { uncovered: g.coverage.length, packages: g.coverage.map((c) => c.name) };

package/scan-core.mjs

@@ -215,6 +215,45 @@ export const MODEL_SDK_RE =
 export function isModelSdkPackage(moduleName) {
   return MODEL_SDK_RE.test(moduleName);
 }
+/// SPEC §2 `fs` — for a call ALREADY classified `Fs`, the read/write direction its verb implies.
+/// Returns ["read"], ["write"], ["read","write"], or [] when the verb does not say.
+///
+/// THE EMPTY CASE IS THE POINT. §2: "when `Fs` is reached but its kind is unknown … the field MUST be
+/// omitted rather than guessed. An empty or partial `fs` would be read as a positive claim ('reads but
+/// never writes'), which is the §4 trust contract's forbidden direction." So an unrecognised verb
+/// contributes nothing and the field stays absent — absence means "kind undetermined", never "read-only".
+///
+/// A syntactic refinement of an effect candor already proved, NOT a soundness claim: a wrong direction
+/// misreports a detail, a wrong EFFECT is the cardinal sin, and those are different failures. Deliberately
+/// the same vocabulary and shape as candor-java's `fsKind` and candor-swift's — the surface is spec'd
+/// four-way, and three engines inventing three verb tables for one field is how a shared field stops
+/// meaning one thing. Node's sync/promise variants are handled by stripping the `Sync` suffix rather than
+/// by listing every pair.
+export function fsKind(moduleName, member) {
+  if (!member) return [];
+  const m = member.endsWith("Sync") ? member.slice(0, -4) : member;
+  // Reads the source AND writes the destination, in one call.
+  if (m === "copyFile" || m === "cp") return ["read", "write"];
+  const WRITE = new Set([
+    "writeFile", "appendFile", "write", "writev", "mkdir", "mkdtemp", "rmdir", "rm", "unlink",
+    "rename", "truncate", "ftruncate", "chmod", "fchmod", "lchmod", "chown", "fchown", "lchown",
+    "utimes", "futimes", "lutimes", "symlink", "link", "createWriteStream", "outputFile", "ensureDir",
+    "ensureFile", "emptyDir", "remove", "move", "outputJson", "writeJson", "writeJSON",
+  ]);
+  const READ = new Set([
+    "readFile", "readdir", "read", "readv", "stat", "lstat", "fstat", "statfs", "access", "exists",
+    "realpath", "readlink", "createReadStream", "opendir", "watch", "watchFile", "readJson",
+    "readJSON", "pathExists", "lstatSync",
+  ]);
+  if (WRITE.has(m)) return ["write"];
+  if (READ.has(m)) return ["read"];
+  // `open`/`openSync` take a MODE — "r", "w", "a" — so the verb alone does not say. Deliberately no claim
+  // rather than a guess at the common case.
+  if (m.startsWith("write") || m.startsWith("append")) return ["write"];
+  if (m.startsWith("read")) return ["read"];
+  return [];
+}
+
 export function kappa(moduleName, member) {
   for (const [mre, vre, eff] of KAPPA_RULES) {
     if (mre.test(moduleName) && (!vre || vre.test(member))) return eff;