candor-ts 0.25.0 → 0.27.0

package/scan.mjs

@@ -28,11 +28,11 @@ import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { execFileSync } from "node:child_process";
 import { parsePolicy, evaluatePolicy, scopeMatches, parseUnknownAliases, parseNetPartners, discoverConfigText,
-         reasonClass, discoverConfigPath, policyVocabularyAnchor, policyErrorText, policyErrorUnevaluated, policyUnreadable, fatalPolicyErrors, refusalVerdict,
+         reasonClass, discoverConfigPath, policyVocabularyAnchor, policyErrorText, policyRefusalUnevaluated, policyUnreadable, fatalPolicyErrors, refusalVerdict,
          netClassResolver, resolveReasonClasses } from "./policy.mjs";
 import { unverifiedHoleRule, ruleUpgrade, byCodePoint, claimsToHaveJudgedNothing, reportCorruptKeys, entryCorruptKeys } from "./query-core.mjs";
 import { printAgents } from "./contract.mjs";
-import { isTestPath, kappa, kappaKnows, commandHeadEffects, hostLiteral, tablesInSql,
+import { isTestPath, kappa, kappaKnows, fsKind, commandHeadEffects, hostLiteral, tablesInSql,
          modelHostEffects, isModelHost, isModelSdkPackage, netClassesOf } from "./scan-core.mjs";
 import { emitSurface } from "./surface.mjs";
 
@@ -44,7 +44,18 @@ 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.25";
+const SPEC_VERSION = "0.27";
+/** The `deps` / `CANDOR_DEPS` separator set — ASCII whitespace plus `:` and `,`.
+ *
+ * ONE CONSTANT BECAUSE TWO SPELLINGS WERE A SILENT GREEN. The §3.3.1 sink-over-input guard and the
+ * dep-chain loader each carried their own regex; they disagreed on `\n`, so a newline-separated
+ * `CANDOR_DEPS` was one unresolvable token to the guard and two real paths to the loader. A
+ * `--gate-json` naming one of those reports was therefore unguarded: arming overwrote it, the scan
+ * finished, and the operator's dep report ended up holding this run's `{"ok": true}` at exit 0.
+ *
+ * NOT JS `\s`, which includes U+00A0: these are PATHS, and a non-breaking space inside one is part of
+ * the path, not a separator — java, rust and swift all treat it that way. */
+const DEP_SEPARATORS = /[ \t\n\r:,]+/;
 
 // --version: a print-and-exit MODE, handled before the main arg walk so it never depends on a target.
 // Fully OFFLINE — candor never phones home. Staying current is the AGENT's job: read the installed
@@ -119,6 +130,164 @@ See https://github.com/tombaldwin/candor`);
 // value-consuming skip handles, nor produce a "lying unknown flag" error for a real flag given first.
 const usage = "usage: candor-ts <dir | file.ts | tsconfig.json> [--out <prefix>] [--json] [--policy <file>] [--gate-json <file>] [--allow-js] [--workspace] [--agents] [--version] [--help]";
 const argv = process.argv.slice(2);
+// Declared HERE, above the sink guard, because the guard calls `loadCandorConfig` and that reads
+// these: left below, they were in the temporal dead zone, the call threw, and the `catch` around it
+// swallowed the throw — so the config channel the guard exists to enumerate was silently empty and a
+// config-declared policy was destroyed at exit 0 again. A `catch` that hides a programming error is a
+// fail-open with a reason attached.
+const CONFIG_KEYS = new Set(["policy", "baseline", "strict", "no-ambient", "closed-world", "taint", "deps", "unknown-alias", "net-partner", "unknown-ratchet", "engine"]);
+const CONFIG_KEYS_IMPLEMENTED = new Set(["policy", "baseline", "deps", "unknown-ratchet", "engine"]);
+
+// ── SPEC §3.3.1 ⟨0.27⟩ ARM FIRST, AND NEVER OVER AN INPUT.
+//
+// This pre-pass learns the sink and this run's inputs with NO side effects, before the parse loop
+// below, for two reasons the loop cannot serve:
+//
+//  (1) the loop's own `unknown flag` exit(2) runs BEFORE the arming did, so `--frobnicate --gate-json G`
+//      exited leaving the PREVIOUS run's green document at G. §3.3 names an unknown flag as a
+//      broken-gate-config exit-2 cause, which MUST leave a refusal — the contract cannot depend on
+//      argv order, and it did.
+//  (2) arming WRITES, so a sink that names the policy DESTROYS it. Measured: `--policy P --gate-json P`
+//      on violating code exited 0 with `ok: true` — the armed JSON replaced P, every line of it parsed
+//      as an unknown rule, and the gate ran over zero rules. A machine-readable all-clear produced by
+//      deleting the question.
+const preScan = (av) => {
+  let gate = null, policy = null, target = null;
+  for (let i = 0; i < av.length; i++) {
+    const a = av[i], v = av[i + 1];
+    if (a === "--gate-json" || a === "--policy" || a === "--out") {
+      if (v === undefined || (v !== "-" && v.startsWith("--"))) continue;
+      if (a === "--gate-json") gate = v; else if (a === "--policy") policy = v;
+      i++;
+      continue;
+    }
+    // The scan TARGET, needed to discover the `.candor/config` whose `policy` key may name an input
+    // this sink must not overwrite.
+    if (!a.startsWith("-") && target === null) target = a;
+  }
+  return { gate, policy, target };
+};
+
+// Every path this run READS, whatever channel it arrived through (SPEC §3.3.1 ⟨0.27⟩).
+//
+// THE FIRST VERSION OF THIS GUARD KEYED ON THE FLAG. With the policy declared by `.candor/config` — the
+// checked-in form, i.e. the one a CI job actually has — `--gate-json <that policy>` destroyed it and
+// exited 0 with `"ok": true` in ALL FOUR ENGINES. A policy does not change what it is according to how
+// the operator handed it over. The config is read LENIENTLY (no exit, no diagnostic): this runs before
+// the real config load and must not pre-empt its refusal.
+// Artifact identity, not string identity: `--policy /w/P --gate-json ./P` from /w is one file, and the
+// engine that already had this guard compared path spellings and lost to exactly that. realpath resolves
+// `.`, `..` and symlinks; for a sink that does not exist yet its parent is resolved instead.
+const sameArtifact = (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);
+};
+
+const runInputs = (target, policyFlag) => {
+  const out = [];
+  if (policyFlag) out.push([policyFlag, "--policy"]);
+  for (const [v, label] of [["CANDOR_POLICY", "CANDOR_POLICY"], ["CANDOR_BASELINE", "CANDOR_BASELINE"],
+                            ["CANDOR_CONFIG", "CANDOR_CONFIG"]]) {
+    if (process.env[v]) out.push([process.env[v], label]);
+  }
+  // ONE DEFINITION, shared with the loader — see DEP_SEPARATORS. This comment used to claim it was
+  // "the separator set the dep loader accepts" while spelling a DIFFERENT set one screen away, and the
+  // gap between the two was a silent green: a newline-separated `CANDOR_DEPS` registered here as one
+  // unresolvable token, so the guard protected nothing, while the loader split it into real paths.
+  // `--gate-json` naming one of those reports then DESTROYED it and the run exited 0 with `ok: true`
+  // written over the operator's input — §3.3.1's own words, "a machine-readable all-clear produced by
+  // deleting the question". Measured live before this change.
+  for (const d of (process.env.CANDOR_DEPS ?? "").split(DEP_SEPARATORS).filter(Boolean)) {
+    out.push([d, "a CANDOR_DEPS report"]);
+    // A DIRECTORY DEP IS EVERY REPORT INSIDE IT. `deps` accepts a directory — `--workspace` writes
+    // `.candor/deps/` and hands that back, so it is the common spelling — and the loader then walks it
+    // and reads each `*.json`. Registering only the DIRECTORY left those files unnamed, so
+    // `--gate-json <depdir>/lib.json` was unguarded: arming destroyed the operator's dep report, the
+    // run chained the wreckage and exited 0 with `ok: true` over it. Measured in all four engines.
+    //
+    // EXPANDED HERE, not by making `sameArtifact` directory-aware. That was tried and is far too
+    // broad: the scan TARGET is an input too, and a verdict written into the tree being scanned is
+    // ordinary usage — the general rule refused it and took 33 tests with it. Only a DEP directory has
+    // its CONTENTS read, so only a dep directory expands.
+    try {
+      if (fs.statSync(d).isDirectory()) {
+        for (const f of fs.readdirSync(d)) {
+          if (f.endsWith(".json") && !f.endsWith(".callgraph.json") && !f.endsWith(".hierarchy.json")
+              && !f.endsWith(".locs.json")) {
+            out.push([path.join(d, f), "a CANDOR_DEPS report"]);
+          }
+        }
+      }
+    } catch { /* not a directory, or unreadable — the token itself is still registered above */ }
+  }
+  // …AND THE CONFIG'S OWN KEYS, THROUGH THE ENGINE'S OWN LOADER AND ITS OWN DISCOVERY. This used to
+  // re-derive both, and a review took it apart: the home directory was computed as parent-of-parent
+  // unconditionally where the loader only steps out of a trailing `.candor/` segment, so an out-of-tree
+  // CANDOR_CONFIG had its relative values anchored one level too high and the guard protected a path
+  // the run never reads. A second parser is a second set of holes; `loadCandorConfig` is called inside a
+  // try so it can still refuse for real a moment later.
+  const cfgFile = discoverConfigFile(target ?? ".");
+  if (cfgFile) {
+    out.push([cfgFile, "the discovered .candor/config"]);
+    try {
+      const cfg = loadCandorConfig(target ?? ".", { lenient: true });
+      for (const key of ["policy", "baseline"]) {
+        if (cfg[key]) out.push([cfg[key], `the config's \`${key}\``]);
+      }
+      for (const one of (cfg.deps ?? "").split(":").filter(Boolean)) {
+        out.push([one, "the config's `deps`"]);
+      }
+    } catch { /* lenient: the real load refuses on its own terms */ }
+  }
+  return out;
+};
+
+{
+  const { gate, policy, target: preTarget } = preScan(argv);
+  for (const [other, flag] of (gate ? runInputs(preTarget, policy) : [])) {
+    if (gate && sameArtifact(gate, other)) {
+      console.error(`candor-ts: --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. The per-input checks above can only name
+  // inputs the run was TOLD about; the config is DISCOVERED by walking up from the target, so by the
+  // time its path is known the arming has already destroyed it. A check on the SHAPE needs no
+  // discovery, so it runs before the first write and covers a config found anywhere up the tree.
+  if (gate && gate !== "-") {
+    const abs = path.resolve(gate);
+    if (path.basename(abs) === "config" && path.basename(path.dirname(abs)) === ".candor") {
+      console.error(`candor-ts: --gate-json ${gate} is a .candor/config — refusing (exit 2). The verdict `
+        + `is armed before the config is read, so this would destroy the config that configures this `
+        + `run. Nothing was written; give the verdict its own path.`);
+      process.exit(2);
+    }
+  }
+  if (gate && sameArtifact(gate, process.env.CANDOR_CONFIG)) {
+    console.error(`candor-ts: --gate-json ${gate} names the SAME FILE as CANDOR_CONFIG — refusing (exit 2).`);
+    process.exit(2);
+  }
+  if (gate && gate !== "-") armGateJsonFailClosed(gate);
+}
+// ⟨0.27⟩ THE STREAM SINK'S ANALOG OF ARMING — SPEC §3.1's stream-sink clause. `--gate-json -` cannot be
+// armed (a stream has no stale previous document, and a placeholder would put TWO documents in a
+// consumer's pipe), but the document-on-every-exit rule applies in full: an exit-2 cause that fires
+// before the gate tail — an unknown flag, a valueless gate-adjacent flag, a missing target — must still
+// leave the fail-closed refusal as the stream's only content. Measured: an unhonourable policy wrote the
+// refusal to stdout while an unknown flag exited 2 leaving stdout EMPTY — the same operator mistake,
+// answered or not according to which early exit fired, and an empty stream throws the consumer back to
+// scraping stderr. File sinks need nothing here: the arming above already left a refusal in place.
+const preGateSink = preScan(argv).gate;
+const refuseEarlyToStream = (why) => {
+  if (preGateSink === "-") console.log(JSON.stringify(refusalVerdict(SPEC_VERSION, why, null), null, 1));
+};
 let target = null, outPrefix = null, policyPath = process.env.CANDOR_POLICY ?? null, gateJsonPath = null, allowJs = false, wantAgents = false, wantJson = false, wantWorkspace = false, wantDepInits = false;
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -132,7 +301,11 @@ for (let i = 0; i < argv.length; i++) {
   else if (a === "--dep-inits") wantDepInits = true;
   else if (a === "--out" || a === "--policy" || a === "--gate-json") {
     const v = argv[i + 1];
-    if (v === undefined || v.startsWith("--")) { console.error(`candor-ts: ${a} requires a value (${usage})`); process.exit(2); }
+    if (v === undefined || v.startsWith("--")) {
+      console.error(`candor-ts: ${a} requires a value (${usage})`);
+      refuseEarlyToStream(`${a} requires a value`);
+      process.exit(2);
+    }
     if (a === "--out") outPrefix = v; else if (a === "--policy") policyPath = v; else gateJsonPath = v;
     i++;
   }
@@ -140,13 +313,27 @@ for (let i = 0; i < argv.length; i++) {
   // (SPEC §6.2/§7). `-h`/`-V`/`--help`/`--version` are print-and-exit modes consumed above, so by here
   // a single-dash token (`-x`, the typo `-policy`) can only be a mistake; treating it as the scan
   // target would silently scan the wrong thing.
-  else if (a.startsWith("-")) { console.error(`candor-ts: unknown flag ${a} (${usage})`); process.exit(2); }
+  else if (a.startsWith("-")) {
+    console.error(`candor-ts: unknown flag ${a} (${usage})`);
+    // ⟨0.27⟩ §3.3 names an unknown flag as a broken-gate-config exit-2 cause; the stream sink gets the
+    // refusal document too (see refuseEarlyToStream — the file sink is already armed).
+    refuseEarlyToStream(`unknown flag ${a}`);
+    process.exit(2);
+  }
   else if (target === null) target = a;
   else if (outPrefix === null) outPrefix = a; // legacy positional prefix
-  else { console.error(`candor-ts: unexpected extra argument ${a} (${usage})`); process.exit(2); }
+  else {
+    console.error(`candor-ts: unexpected extra argument ${a} (${usage})`);
+    refuseEarlyToStream(`unexpected extra argument ${a}`);
+    process.exit(2);
+  }
 }
 if (wantAgents) { printAgents(); process.exit(0); }
-if (target === null) { console.error(usage); process.exit(2); }
+if (target === null) {
+  console.error(usage);
+  refuseEarlyToStream("no scan target");
+  process.exit(2);
+}
 
 // ---- .candor/config (candor-spec §config; the checked-in alternative to the CANDOR_* env vars) -----
 // Discovery is anchored to the SCAN TARGET (walk up from the target dir to the repo root's
@@ -156,14 +343,15 @@ if (target === null) { console.error(usage); process.exit(2); }
 // never vanish silently (the §6.2 unreadable-policy posture). Only genuine absence is an empty config.
 // Keys are the shared FAMILY vocabulary; a key OUTSIDE it warns (typo protection: a misspelt `policy`
 // must not silently drop the gate).
-const CONFIG_KEYS = new Set(["policy", "baseline", "strict", "no-ambient", "closed-world", "taint", "deps", "unknown-alias", "net-partner", "unknown-ratchet"]);
+// ⟨0.27⟩ `engine` (SPEC §3.4) is RECOGNIZED and IMPLEMENTED here — see enforceEnginePin. It must be in
+// BOTH sets: missing from the vocabulary it is reported as unknown, and missing from IMPLEMENTED it is
+// disclosed as inert — both tell an operator their pin was ignored while the engine is enforcing it.
 // The subset this engine actually wires to a mode — `policy` (the gate), `baseline` (AS-EFF-005),
 // `deps` (the cross-package report chain) and `unknown-ratchet` (the baseline guard's opt-in). The rest
 // of the vocabulary is spec-inert HERE: it drives other engines' gates. But a checked-in enforcement key
 // that silently does nothing is a DECLARED-GATE-SILENTLY-OFF — the reader believes the gate is on — so
 // an inert recognized key DISCLOSES loudly (stderr only; verdict/report/exit code untouched) instead of
 // staying mute. Same posture + message shape as candor-scan's CONFIG_KEYS_IMPLEMENTED.
-const CONFIG_KEYS_IMPLEMENTED = new Set(["policy", "baseline", "deps", "unknown-ratchet"]);
 // The ANCHOR a config file's RELATIVE path values (policy/deps) resolve against: the repo the config
 // belongs to — the parent of its `.candor/` directory (the standard layout; candor-init scaffolds
 // `policy arch.policy` meaning the repo root's), else the config file's own directory. NEVER the
@@ -174,28 +362,139 @@ function configAnchor(file) {
   const dir = path.dirname(path.resolve(file));
   return path.basename(dir) === ".candor" ? path.dirname(dir) : dir;
 }
-function loadCandorConfig(targetPath) {
+// ⟨0.27⟩ SPEC §3.4 `engine` — THE ENGINE↔BASELINE COUPLING, enforced instead of hoped for.
+//
+// The committed baseline is a snapshot of what ONE engine build reported, and an engine swap is
+// baseline-invalidating. What a PIN adds over the provenance checks already in place is that it is
+// DECLARATIVE — a build id is a hash nobody can write down, so the intended version lived in CI config,
+// decoupled from the baseline it is married to. It also tells tooling which engine to FETCH, and it
+// reaches a run with NO baseline configured at all.
+//
+// TWO OF THE FIVE VERDICTS MUST NOT CHANGE THE EXIT CODE: an ABSENT pin (the key is opt-in by
+// construction) and an UNDETERMINED one, where §3.1's unanswerable-condition rule applies — disclosed,
+// never scored, INCLUDING as satisfied. Exit 2 on a mismatch, never 1: unevaluable, not violating.
+//
+// A pin qualified for another implementation is not ours to check — one config serves the whole family,
+// and the family versions as a LADDER, so a bare version in a polyglot repo would fail whichever engine
+// had not yet caught up.
+const ENGINE_IMPLS = new Set(["java", "rust", "ts", "swift", "agents"]);
+function enginePinFor(text, implName) {
+  let wild = null, qual = null, bad = false;
+  for (const rawLine of (text ?? "").split("\n")) {
+    const line = rawLine.split("#")[0].trim();
+    if (!line) continue;
+    const parts = line.split(/\s+/);
+    if (parts[0].toLowerCase() !== "engine") continue;
+    const rest = parts.slice(1);
+    // Two lines that DISAGREE about the same key are kept BOTH, so they cannot parse as a version and
+    // surface as malformed. One silently discarding the other is the failure this key exists to stop.
+    const slot = (cur, v) => (cur !== null && cur !== v ? `${cur} / ${v}` : v);
+    // A KNOWN QUALIFIER DECIDES OWNERSHIP BEFORE ARITY. Checking the one-token case first made `engine swift` a WILDCARD pin whose version is the literal "swift" -> MALFORMED -> exit 2 in every engine, so one operator forgetting a version on a qualified line killed the whole family. SPEC 3.4 says the skip is whole-line 'whatever follows it' -- and nothing following it is a case of that too.
+    if (rest.length && ENGINE_IMPLS.has(rest[0].toLowerCase())) {
+      if (rest[0].toLowerCase() === implName) { if (rest.length === 2) qual = slot(qual, rest[1]); else bad = true; }
+      continue;                                    // another impl's line, whatever follows it
+    }
+    if (rest.length === 0) bad = true;
+    else if (rest.length === 1) wild = slot(wild, rest[0]);
+    else bad = true;
+  }
+  if (bad) return "<unreadable>";
+  // AN UNREADABLE UNQUALIFIED LINE IS NOT HIDDEN BY A QUALIFIED PIN. `qual ?? wild` returned the qualifi
+  // ed value, so `engine garbage` beside a good qualified line passed SILENTLY here while candor-java exited 
+  // 2 — the exact mirror of the bug just fixed in java, four engines the other way. Unreadability is a property of the LINE; precedence only decides which VERSION applies.
+  if (wild !== null && normalizePinVersion(wild) === null) return wild;
+  return qual ?? wild;
+}
+function normalizePinVersion(raw) {
+  const s = String(raw ?? "").trim().replace(/^[vV]/, "");
+  if (!/^\d+\.\d+(\.\d+)?$/.test(s)) return null;
+  return s.split(".").length === 2 ? `${s}.0` : s;
+}
+function enforceEnginePin(targetPath) {
+  const pin = enginePinFor(discoverConfigText(targetPath), "ts");
+  if (pin === null || pin === undefined) return;                       // ABSENT
+  const want = normalizePinVersion(pin);
+  if (want === null) {
+    console.error(`candor-ts: .candor/config has an \`engine\` line that is not an engine version.`);
+    console.error(`        want \`engine <version>\` (e.g. \`engine v${PKG_VERSION}\`) or \`engine <impl> <version>\``);
+    console.error(`        (e.g. \`engine ts v${PKG_VERSION}\`) for a repo scanned by more than one engine.`);
+    console.error(`        Failing (exit 2) rather than ignoring it: a pin that cannot be read is a`);
+    console.error(`        guard the operator believes is on.`);
+    process.exit(2);
+  }
+  const running = normalizePinVersion(PKG_VERSION) ?? String(PKG_VERSION ?? "").trim();
+  if (!running || running === "unknown") {                             // UNDETERMINED — disclose, never score
+    console.error(`candor-ts: .candor/config pins engine ${pin}, and this build does not know its own release,`);
+    console.error(`        so the pin CANNOT be checked. Disclosed, not scored — neither passed nor failed.`);
+    return;
+  }
+  if (want === running) return;                                        // MATCH
+  console.error(`candor-ts: .candor/config pins engine ${pin} but this build is candor-ts ${PKG_VERSION}.`);
+  console.error(`        The pin and the committed baseline move together — a newer engine resolves more`);
+  console.error(`        dispatch, so its report is not comparable with a baseline the pinned engine wrote.`);
+  console.error(`        Either run the pinned engine, or update the pin and regenerate the baseline in the`);
+  console.error(`        same change. Exit 2 (unevaluable), not 1 — this is not a policy violation.`);
+  // ONE call, not two: an insertion script matched both pin branches to this single exit, and the
+  // duplicate put TWO documents on the stream — which parses as neither. The other branch (a build that
+  // cannot determine its own release) RETURNS rather than exiting: disclosed, not scored, so no refusal
+  // belongs there.
+  refuseEarlyToStream(`.candor/config pins engine ${pin}, which this build does not satisfy`);
+  process.exit(2);
+}
+
+// WHICH config file this run reads, with NO side effects (SPEC §3.4). Extracted so the §3.3.1 sink
+// guard asks the same question the loader answers instead of re-deriving the walk — a review took the
+// guard's own copy apart on exactly that divergence.
+function discoverConfigFile(targetPath) {
+  const env = process.env.CANDOR_CONFIG;
+  if (env) {
+    try { return fs.statSync(env).isFile() ? env : null; } catch { return null; }
+  }
+  let dir = path.resolve(targetPath ?? ".");
+  try { if (!fs.statSync(dir).isDirectory()) dir = path.dirname(dir); } catch { dir = path.dirname(dir); }
+  for (let d = dir; ; d = path.dirname(d)) {
+    const cand = path.join(d, ".candor", "config");
+    if (fs.existsSync(cand)) return cand;
+    if (path.dirname(d) === d) break;                         // filesystem root
+  }
+  return fs.existsSync(".candor/config") ? ".candor/config" : null;
+}
+
+/// `lenient: true` THROWS where this would otherwise `process.exit(2)`.
+///
+/// The collision pre-pass needs the config's DECLARED input paths before the sink is armed, and it
+/// wrapped this call in a try under the comment "the real load refuses on its own terms" — which
+/// assumes the failure arrives as an exception. It does not: `process.exit` is not catchable, so an
+/// unreadable config killed the run INSIDE that try, before arming, leaving a pre-seeded green verdict
+/// intact at the file sink. SPEC §3.3's own words for that: "a refusal that writes nothing leaves the
+/// previous run's green document on disk." java answers the same input with `refused: true`.
+///
+/// Nothing is lost by leniency here. If the config cannot be read it declares no inputs anyone can
+/// name, so the collision check over them is vacuous; arming then proceeds and the REAL load refuses a
+/// moment later — now with the sink armed, so the refusal reaches it. A second parser was the
+/// alternative, and a second parser is a second set of holes.
+function loadCandorConfig(targetPath, { lenient = false } = {}) {
   let file = process.env.CANDOR_CONFIG ?? null;
   if (file !== null) {
     if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
+      if (lenient) throw new Error(`CANDOR_CONFIG set but ${file} is not a readable file`);
       console.error(`candor-ts: CANDOR_CONFIG set but ${file} is not a readable file — failing (exit 2)`);
+      // The config is the EARLIEST exit-2 cause, and the one the stream sink is least likely to be
+      // armed for — which is exactly why it was the last one still leaving stdout empty. Found by
+      // PART 36 (b11), a row written before this line was.
+      refuseEarlyToStream(`CANDOR_CONFIG set but ${file} is not a readable file`);
       process.exit(2);
     }
   } else {
-    let dir = path.resolve(targetPath);
-    try { if (!fs.statSync(dir).isDirectory()) dir = path.dirname(dir); } catch { dir = path.dirname(dir); }
-    for (let d = dir; ; d = path.dirname(d)) {
-      const cand = path.join(d, ".candor", "config");
-      if (fs.existsSync(cand)) { file = cand; break; }
-      if (path.dirname(d) === d) break;                       // filesystem root
-    }
-    if (file === null && fs.existsSync(".candor/config")) file = ".candor/config";
+    file = discoverConfigFile(targetPath);
     if (file === null) return {};
   }
   let text;
   try { text = fs.readFileSync(file, "utf8"); }
   catch (e) {
+    if (lenient) throw new Error(`config ${file} exists but could not be read (${e.message})`);
     console.error(`candor-ts: config ${file} exists but could not be read (${e.message}) — failing (exit 2)`);
+    refuseEarlyToStream(`config ${file} exists but could not be read`);
     process.exit(2);
   }
   const cfg = {};
@@ -230,10 +529,50 @@ function loadCandorConfig(targetPath) {
   const anchor = configAnchor(file);
   if (cfg.policy) cfg.policy = path.resolve(anchor, cfg.policy);
   if (cfg.baseline) cfg.baseline = path.resolve(anchor, cfg.baseline);
-  if (cfg.deps) cfg.deps = cfg.deps.split(/[\s:,]+/).filter(Boolean).map((t) => path.resolve(anchor, t)).join(":");
+  // ASCII whitespace ONLY, like java and swift: these are PATHS, and JS `\s` includes U+00A0, so a dep
+  // path containing a non-breaking space split into two halves that were then both "skipped" — a green
+  // run with the dep silently unchained, where java and rust loaded it.
+  if (cfg.deps) cfg.deps = cfg.deps.split(/[ \t:,]+/).filter(Boolean).map((t) => path.resolve(anchor, t)).join(":");
   return cfg;
 }
+// ⟨0.24⟩/⟨0.27⟩ ARM THE VERDICT FAIL-CLOSED. Every exit path then leaves a refusal behind unless the run
+// got far enough to replace it with a real verdict. A review found the pin refusal leaving the PREVIOUS
+// run's document on disk — a CI wrapper reading the artifact instead of the exit code then reports a pass
+// over a run that refused. candor-java's `armGateJson` is the model; the wording is about the RUN, not
+// about the code.
+//
+// A `function` declaration, not a `const`: it is CALLED from the pre-pass above the arg loop, and only a
+// hoisted declaration can be. The write is inlined rather than calling `writeAtomic` for the same reason
+// in reverse — that helper is a `const` declared ~4700 lines below, so calling it would be a
+// temporal-dead-zone throw.
+function armGateJsonFailClosed(p) {
+  try {
+    const _tmp = `${p}.${process.pid}.arm`;
+    fs.writeFileSync(_tmp, JSON.stringify({
+      spec: SPEC_VERSION, ok: false, refused: true,
+      reason: "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");
+    fs.renameSync(_tmp, p);
+  } catch (e) {
+    console.error(`candor-ts: could not arm --gate-json ${p} fail-closed (${e.message}) — if this run `
+      + `does not complete, that path may still hold a PREVIOUS run's verdict`);
+  }
+}
+// MOVED ABOVE THE CONFIG LOAD. `loadCandorConfig` is ITSELF an exit-2 cause (an unusable
+// CANDOR_CONFIG, or a committed `.candor/config` that cannot be read), and arming after it left a
+// config refusal exiting 2 with the PREVIOUS run's green still on disk — while the comment below
+// said "BEFORE ANYTHING THAT CAN EXIT". The rule only holds if the arming really is first.
+// ⟨0.24⟩ ARM THE VERDICT FAIL-CLOSED BEFORE ANYTHING THAT CAN EXIT. A review found the pin refusal
+// leaving the PREVIOUS run's `--gate-json` document on disk — a CI wrapper reading the artifact instead
+// of the exit code then reports a pass over a run that refused. Arming at the START makes this a CLASS
+// fix: every exit path leaves a refusal unless the run got far enough to replace it. candor-java's
+// `armGateJson` is the model, and the wording is about the RUN, not about the code.
+// (armed by the pre-pass above, before the arg loop — see SPEC §3.3.1 ⟨0.27⟩. Arming HERE was still
+// after the loop's unknown-flag exit, so the contract depended on argv order.)
 const candorConfig = loadCandorConfig(target);
+enforceEnginePin(target);   // ⟨0.27⟩ §3.4 — AFTER the arming, so its exit 2 cannot leave a stale verdict
 // precedence: the --policy flag / CANDOR_POLICY env already populated policyPath; the config is the floor.
 // A BARE `policy` line ("" value) means configured-with-empty → the unreadable-policy path fails loud.
 if (policyPath === null && candorConfig.policy !== undefined) policyPath = candorConfig.policy;
@@ -241,7 +580,12 @@ if (policyPath === null && candorConfig.policy !== undefined) policyPath = cando
 // (path-valued keys are already resolved against the config's anchor above). No CLI flag — matching
 // candor-java, the reference engine (env/config only). A BARE `baseline` line ("") fails loud below.
 let baselinePath = process.env.CANDOR_BASELINE ?? null;
-if (baselinePath === null && candorConfig.baseline !== undefined) baselinePath = candorConfig.baseline;
+// WHICH SOURCE supplied it decides what a MISSING file means: `CANDOR_BASELINE` is set unconditionally
+// by the adopt workflow, so an absent path there is "the ratchet is not adopted yet"; a checked-in
+// `baseline` line DECLARES this repo has one, so an absent path there was deleted or never committed —
+// and the guard passing green over it is a gate that silently stopped gating.
+let baselineFromConfig = false;
+if (baselinePath === null && candorConfig.baseline !== undefined) { baselinePath = candorConfig.baseline; baselineFromConfig = true; }
 // ⟨unknown-ratchet⟩ OPT-IN (config `unknown-ratchet` / CANDOR_UNKNOWN_RATCHET, default OFF): flip an
 // Unknown-ONLY gain vs the baseline from advisory to an AS-EFF-005 failure (exit 1). Env-override truthy
 // semantics mirror candor-java's Config.flag exactly — env var PRESENCE means on (env can't express off);
@@ -290,7 +634,15 @@ function fromTsconfig(cfgPath, baseDir) {
   return names.filter((f) => !isTestPath(path.relative(baseDir, f)));
 }
 const stat = fs.existsSync(target) ? fs.statSync(target) : null;
-if (!stat) { console.error(`candor-ts: no such path: ${target}`); process.exit(2); }
+if (!stat) {
+  console.error(`candor-ts: no such path: ${target}`);
+  // The SAME two lines as every other early exit in this file. `refuseEarlyToStream` WRITES AND
+  // RETURNS — it is not a `Never`, and calling it INSTEAD of the exit lets the run continue past its
+  // own refusal (measured, while getting this wrong: an unreadable dep wrote its refusal and then
+  // exited 0). rust's equivalent is typed `-> !`, which is why the same slip could not happen there.
+  refuseEarlyToStream(`no such path: ${target}`);
+  process.exit(2);
+}
 if (stat.isFile() && /tsconfig.*\.json$/.test(path.basename(target))) {
   rootDir = path.dirname(path.resolve(target));
   fileNames = fromTsconfig(path.resolve(target), rootDir);
@@ -315,7 +667,13 @@ if (stat.isFile() && /tsconfig.*\.json$/.test(path.basename(target))) {
     })(rootDir);
   }
 }
-if (fileNames.length === 0) { console.error(`candor-ts: no TypeScript sources under ${target}`); process.exit(2); }
+if (fileNames.length === 0) {
+  console.error(`candor-ts: no TypeScript sources under ${target}`);
+  // An empty scan is an exit-2 cause like any other: a consumer reading the stream after it must not
+  // get nothing. §3.1 exempts no cause, and this one is easy to hit in CI (a path that moved).
+  refuseEarlyToStream(`no TypeScript sources under ${target}`);
+  process.exit(2);
+}
 // Builtin typings FALLBACK: the engine ships @types/node as its own dependency, so a target that
 // hasn't installed it still resolves node:fs/node:net/… (found by the first npx-distribution
 // probe: a bare fixture read Unknown for fs.readFileSync because nothing supplied the builtin
@@ -798,16 +1156,69 @@ const corruptDepPkgs = new Set();
   // --workspace's auto-scanned deps dir is prepended to the explicit CANDOR_DEPS/config spec (both chain).
   const spec = [workspaceDepsDir, depInitsDir, process.env.CANDOR_DEPS ?? candorConfig.deps ?? ""].filter(Boolean).join(":");
   const files = [];
-  for (const tok of spec.split(/[\s:,]+/).filter(Boolean)) {
+  // ASCII WHITESPACE ONLY, the same rule as the config loader above and as java, rust and swift. JS
+  // `\s` includes U+00A0, so a dep path holding a non-breaking space split into two halves — and since
+  // ⟨0.27⟩ made an unresolvable dep token FATAL, that turned a path the other three engines load into a
+  // hard exit 2 naming a truncated path the operator never wrote. The config loader was fixed and this
+  // one, which every config-declared dep is also routed through, was not: one rule, two spellings.
+  for (const tok of spec.split(DEP_SEPARATORS).filter(Boolean)) {
     try {
       if (fs.statSync(tok).isDirectory())
         for (const f of fs.readdirSync(tok)) if (f.endsWith(".json") && !f.endsWith(".callgraph.json") && !f.endsWith(".hierarchy.json") && !f.endsWith(".locs.json")) files.push(path.join(tok, f));
       if (fs.statSync(tok).isFile()) files.push(tok);
-    } catch { console.error(`candor-ts: CANDOR_DEPS entry unreadable, skipped: ${tok}`); }
+    } catch {
+      // ⟨0.27⟩ SPEC §2: A CONFIGURED DEP THAT CANNOT BE READ IS UNEVALUABLE, NOT REDUCED COVERAGE.
+      // Skipping it continued the run, and the caller of that dep then serialised `inferred: []` — a
+      // ⟨0.21⟩ purity claim, published in the REPORT, about a function whose dependency the operator
+      // configured precisely so it would not be one. This engine's note said only "skipped", so the
+      // omission was not even qualified in the channel a human reads, let alone the artifact a chained
+      // consumer reads. java and swift already refused; this engine and rust continued.
+      console.error(`candor-ts: CANDOR_DEPS names ${tok} but it is not a readable file or directory — `
+        + `failing (exit 2, unevaluable). A configured dep that is not there is not reduced coverage: `
+        + `its callers would serialise \`inferred: []\`, which is a purity claim about code this scan `
+        + `never saw. Scan that dependency, or remove it from the \`deps\` config / CANDOR_DEPS.`);
+      // The TOKEN arm needed this too. The read and parse arms below were routed to the stream and this
+      // one was not — three exits for one rule, two of them answered on the machine channel and one
+      // silent, which a conformance row (PART 36 b8) caught immediately once the cause was posed at all.
+      refuseEarlyToStream(`configured dependency ${tok} is not a readable file or directory`);
+      process.exit(2);
+    }
   }
   for (const f of files) {
+    // ⟨0.27⟩ READ AND PARSE OUTSIDE THE TRY, because SPEC §2 binds them and the try was swallowing them.
+    // The rule is one sentence — a configured dep path that "does not exist OR CANNOT BE READ MUST exit
+    // 2, naming it" — and the 0.27 work implemented only the first half, at the token check above. A path
+    // that resolved to a file which then failed to open, or held malformed JSON, was SKIPPED at exit 0,
+    // and the caller of that dep serialised `inferred: []`: the ⟨0.21⟩ purity claim the token check
+    // exists to prevent, reached by a different door.
+    //
+    // Found by the 0.27 go/no-go panel, which tested this engine's own changelog claim instead of
+    // believing it. java and swift refused on both halves already; this and rust made the family 2-v-2
+    // on a MUST. The surviving `catch` below still guards the PROCESSING of a well-formed document,
+    // which is a different failure and stays a skip.
+    let raw;
+    try {
+      raw = fs.readFileSync(f, "utf8");
+    } catch {
+      console.error(`candor-ts: CANDOR_DEPS report ${f} could not be read —`);
+      console.error(`        failing (exit 2, unevaluable). A configured dep this scan cannot read is not`);
+      console.error(`        reduced coverage: its callers would serialise \`inferred: []\`, a purity claim`);
+      console.error(`        about code this scan never saw.`);
+      refuseEarlyToStream(`configured dependency report ${f} could not be read`);
+      process.exit(2);
+    }
+    let parsed;
     try {
-      const d = JSON.parse(fs.readFileSync(f, "utf8"));
+      parsed = JSON.parse(raw);
+    } catch {
+      console.error(`candor-ts: CANDOR_DEPS report ${f} is not valid JSON —`);
+      console.error(`        failing (exit 2, unevaluable). Same reason as an unreadable one: a report`);
+      console.error(`        that cannot be parsed makes no claim, and continuing would publish one.`);
+      refuseEarlyToStream(`configured dependency report ${f} is not valid JSON`);
+      process.exit(2);
+    }
+    try {
+      const d = parsed;
       // A report whose version can't be VERIFIED is not trusted (§2.1) — a missing header is as
       // untrustworthy as a mismatched one (the Rust engine's rule; the engines split on this).
       const stale = d.candor?.version !== ENGINE_VERSION;
@@ -928,7 +1339,7 @@ const corruptDepPkgs = new Set();
         if (!stale && strs(e.netClass).includes("unknown-host")) cell.netIncomplete = true;
         crossDeps.set(e.hash, cell);
       }
-    } catch { console.error(`candor-ts: CANDOR_DEPS report unparsable, skipped: ${f}`); }
+    } catch { console.error(`candor-ts: CANDOR_DEPS report could not be processed, skipped: ${f}`); }
   }
   // A package chained TWICE — once fresh, once stale — is covered by the fresh report, so it is not a
   // stale-only package and must not pick up the disclosure below on top of a real answer.
@@ -1729,7 +2140,7 @@ for (const sf of sources) {
       const ctorQual = `${mod}.${namespacePrefixOf(node)}${node.name.text}.constructor`;
       if (!fns.has(ctorQual)) {
         const { line, character } = sf.getLineAndCharacterOfPosition(node.getStart());
-        fns.set(ctorQual, { local: `${node.name.text}.constructor`, direct: new Set(), edges: new Set(),
+        fns.set(ctorQual, { local: `${node.name.text}.constructor`, direct: new Set(), fsKinds: new Set(), edges: new Set(),
                             hosts: new Set(), tables: new Set(), cmds: new Set(), paths: new Set(),
                             blind: new Set(), incomplete: new Set(), why: new Set(), entry: false,
                             loc: `${path.relative(rootDir, sf.fileName)}:${line + 1}:${character + 1}`,
@@ -1753,7 +2164,7 @@ for (const sf of sources) {
       // producer's namespace nesting, so widening the hash would break report chaining.
       const nsp = namespacePrefixOf(node);
       const qual = isFunctionScoped(node) ? `${mod}.${nsp}${n}#${line + 1}:${character + 1}` : `${mod}.${nsp}${n}`;
-      fns.set(qual, { local: n, direct: new Set(), edges: new Set(), hosts: new Set(), tables: new Set(),
+      fns.set(qual, { local: n, direct: new Set(), fsKinds: new Set(), edges: new Set(), hosts: new Set(), tables: new Set(),
                       cmds: new Set(), paths: new Set(), blind: new Set(), incomplete: new Set(), why: new Set(), entry: false, isCjsExport,
                       loc: `${path.relative(rootDir, sf.fileName)}:${line + 1}:${character + 1}`,
                       endLine: sf.getLineAndCharacterOfPosition(node.getEnd()).line + 1 });
@@ -2054,7 +2465,7 @@ function moduleUnit(sf) {
   const qual = `${mod}.<module>`;
   let rec = fns.get(qual);
   if (!rec) {
-    rec = { local: qual, direct: new Set(), edges: new Set(), hosts: new Set(), tables: new Set(),
+    rec = { local: qual, direct: new Set(), fsKinds: new Set(), edges: new Set(), hosts: new Set(), tables: new Set(),
             cmds: new Set(), paths: new Set(), blind: new Set(), incomplete: new Set(), why: new Set(),
             entry: false, unitKind: "initializer",
             loc: `${path.relative(rootDir, sf.fileName)}:1:1`,
@@ -2077,7 +2488,7 @@ function staticBlockUnit(node) {
   const qual = `${mod}.${cname}.<static-init>`;
   let rec = fns.get(qual);
   if (!rec) {
-    rec = { local: "<static-init>", direct: new Set(), edges: new Set(), hosts: new Set(), tables: new Set(),
+    rec = { local: "<static-init>", direct: new Set(), fsKinds: new Set(), edges: new Set(), hosts: new Set(), tables: new Set(),
             cmds: new Set(), paths: new Set(), blind: new Set(), incomplete: new Set(), why: new Set(),
             entry: false, unitKind: "initializer",
             loc: `${path.relative(rootDir, sf.fileName)}:${sf.getLineAndCharacterOfPosition(node.getStart()).line + 1}:1`,
@@ -3403,6 +3814,17 @@ function visitCalls(node) {
             eff = null;
           if (eff) {
             rec.direct.add(eff);
+            // SPEC §2 `fs` — refine an Fs we just PROVED with the direction its verb implies. DIRECT only
+            // (never propagated over edges): a caller reaching one writer and one undetermined callee would
+            // otherwise inherit ["write"] and thereby claim "writes but never reads" — the partial claim §2
+            // forbids. An unrecognised verb adds nothing, so the field stays absent rather than half-true.
+            if (eff === "Fs") {
+              // A verb revealing no direction records the POISON marker "?" rather than nothing. Abstaining
+              // would let a caller inherit a neighbour's ["write"] and claim "writes but never reads" over a
+              // reach whose kind was never determined — the partial claim §2 forbids. Suppressed at emit.
+              const ks = fsKind(mod, member);
+              if (ks.length === 0) rec.fsKinds.add("?"); else for (const k of ks) rec.fsKinds.add(k);
+            }
             // a κ rule that resolves to the Unknown trust-marker (node:vm code execution) is a direct
             // Unknown SOURCE — SPEC §4 requires a why on it, like eval's `reflect:eval`. (The rest of
             // the κ table is concrete effects, which carry no why.)
@@ -4339,7 +4761,10 @@ const inferred = new Map([...fns.keys()].map((k) => [k, new Set(fns.get(k).direc
         if (!queued.has(c)) { queued.add(c); queue.push(c); }
   }
 }
-for (const m of ["hosts", "tables", "cmds", "paths", "blind", "incomplete"]) {
+// `fsKinds` joins the propagated surfaces: kinds TRAVEL the call graph (a caller that transitively only
+// writes IS a writer), and the "?" poison travels with them so a caller of an undetermined-kind function
+// inherits the SUPPRESSION rather than a half-answer. Pinned by conformance PART 31.
+for (const m of ["hosts", "tables", "cmds", "paths", "blind", "incomplete", "fsKinds"]) {
   const queue = [...fns.keys()];
   const queued = new Set(queue);
   for (let head = 0; head < queue.length; head++) {
@@ -4371,9 +4796,13 @@ for (const [name, rec] of fns) {
     hash: `${pkgName}#${rec.local}`, // SPEC §2: the cross-package join key (package + local tail)
     inferred: inf,
     direct: [...rec.direct].sort(),
-    declared: [],
-    undeclared: [],
-    overdeclared: [],
+    // ⟨0.26⟩ `declared`/`undeclared`/`overdeclared` are DELIBERATELY ABSENT. They are the §5
+    // capability-reconciliation outputs and this engine runs no such pass, so emitting `[]` would be a
+    // positive claim — `undeclared: []` reads as "this function performs no undeclared effect", an
+    // AS-EFF-001 all-clear from a check that never ran. SPEC §2 ⟨0.26⟩: present means the pass ran,
+    // absent means it did not, and `[]` from an engine that computed nothing is forbidden.
+    // They were emitted as hardcoded constants "for cross-engine schema parity" — a schema-parity check
+    // is exactly what made that look conforming, which is why the rule now forbids requiring them.
     unresolved: inf.includes("Unknown"),
   };
   // Inline call edges (§2 `calls`) — the SAME edges the callgraph sidecar carries, embedded per entry so a
@@ -4389,6 +4818,14 @@ for (const [name, rec] of fns) {
   if (inf.includes("Db") && rec.tables.size) entry.tables = [...rec.tables].sort();
   if (inf.includes("Exec") && rec.cmds.size) entry.cmds = [...rec.cmds].sort();
   if (inf.includes("Fs") && rec.paths.size) entry.paths = [...rec.paths].sort();
+  // SPEC §2 `fs` — the read/write kinds this fn's OWN Fs calls revealed. Gated on `inferred` carrying Fs
+  // (the spec: "applies only when `inferred` contains `Fs`") and omitted when empty.
+  //
+  // Kinds TRAVEL (see the propagation loop); the "?" poison is what stops a PARTIAL answer travelling with
+  // them. Present ⇒ some contributing Fs had no determined kind ⇒ suppress the whole field, because
+  // ["write"] there would claim "writes but never reads" about a function that may do both.
+  if (inf.includes("Fs") && rec.fsKinds.size && !rec.fsKinds.has("?"))
+    entry.fs = [...rec.fsKinds].sort();
   // ⟨0.6⟩ unknownWhy — REQUIRED on a DIRECT Unknown SOURCE (this fn's own body has the unresolvable call,
   // so `rec.direct` carries Unknown), absent on a purely-transitive Unknown. The rich per-site reasons
   // (rec.why: callback:/dispatch:/dynamic-key:) when recorded, else a generic fallback so a source is
@@ -4830,8 +5267,13 @@ function fnv1aHex(sortedQuals) {
 
 // `package` names what this report COVERS — a consumer chaining it registers coverage even when
 // `functions` is empty (an all-pure package's report is its purity claim, SPEC §2 rule 3).
+// ⟨0.27⟩ SPEC §2.1 `resolves`: the OPTIONAL refinement surfaces this producer computes. Without it the
+// absence of such a field is overloaded between "does not compute this" and "computed and could not
+// determine it", and a consumer cannot read the omission at all. candor-ts resolves `fs` read/write kinds,
+// so it says so. A producer MUST NOT list a surface it does not compute — that turns "unimplemented" into a
+// false "undetermined", which is the inversion the field exists to prevent.
 const envelope = { candor: { version: ENGINE_VERSION, toolchain: `node-${process.versions.node}`, spec: SPEC_VERSION },
-                   package: pkgName, functions };
+                   resolves: ["fs"], package: pkgName, functions };
 // ⟨0.15 staged⟩ the κ-coverage ledger as DATA (COVERAGE-DESIGN.md §1): ONE sorted form (count desc,
 // name asc — exactly the stderr line's order) feeds the envelope field, the stderr receipt below, and
 // the --gate-json advisory, so the three can never tell different stories.
@@ -4909,7 +5351,13 @@ for (const sf of sources) {
           supers.push(d && d.name ? `${moduleOf(d.getSourceFile())}.${namespacePrefixOf(d)}${d.name.getText()}` : t.expression.getText());
         }
       }
-      if (supers.length) hierarchy[`${mod}.${namespacePrefixOf(node)}${node.name.getText()}`] = supers;
+      // ⟨0.26⟩ A KEY FOR EVERY TYPE INDEXED, `[]` INCLUDED — the key set IS the manifest (SPEC §2.2).
+      // This was `if (supers.length)`, so a type with no supertypes was OMITTED and absence meant BOTH
+      // "no supertypes" and "never indexed". Measured: removing one entry from a real sidecar silently
+      // dropped a `callers --include-unknown` frontier row, while removing the sidecar ENTIRELY left it
+      // correct — so LESS information was SAFER than partial information. §2.2's own example has always
+      // shown `"app.Base": []`; this producer contradicted it.
+      hierarchy[`${mod}.${namespacePrefixOf(node)}${node.name.getText()}`] = supers;
     }
     ts.forEachChild(node, walk);
   })(sf);
@@ -5013,6 +5461,11 @@ if (!wantJson) {
 // a `… | jq` / `… | candor-sarif` pipe never breaks.
 const emitViolation = (wantJson || gateJsonPath === "-") ? (l) => console.error(l) : (l) => console.log(l);
 let gateViolations = [];
+// ⟨0.27⟩ SPEC §4 `zeroMatch` — the raw text of every rule whose SCOPE bound no function, captured off the
+// gate evaluation and emitted onto the verdict document. The stderr lines alone left a machine consumer
+// unable to see that a rule bound nothing — the typo'd-scope silent green, one channel over. Disclosure
+// only: `ok` and the exit code never consult it.
+let gateZeroMatch = [];
 // ⟨0.24⟩ the `.candor/config` that supplied POLICY VOCABULARY this verdict actually used — named on the
 // document (SPEC §3.1 `99eb4e9`), null when no alias was referenced so the verdict stays byte-identical.
 let policyVocabulary = null;
@@ -5065,7 +5518,20 @@ const writeRefusal = (reason, unevaluated = null) => {
 //    must not silently NARROW the guard back to report-only.
 if (baselinePath !== null) {
   const shownB = baselinePath === "" ? "(configured empty)" : baselinePath;
-  if (baselinePath !== "" && !fs.existsSync(baselinePath)) {
+  if (baselinePath !== "" && !fs.existsSync(baselinePath) && baselineFromConfig) {
+    // A CHECKED-IN DECLARATION IS NOT THE SAME ABSENCE — see baselineFromConfig above. Exit 2: the
+    // gateless-green class, and an adopter review measured this as the second-likeliest first-commit
+    // mistake (`.candor/` committed, the baseline not).
+    console.error(`candor-ts: .candor/config declares \`baseline ${baselinePath}\` but that file is not `
+      + `there — failing (exit 2). A checked-in declaration says this repo HAS a baseline, so an absent `
+      + `one was deleted or never committed. Commit it, or record one: candor-ts <target> --out <prefix>.`);
+    // WRITE THE REFUSAL DOCUMENT BEFORE EXITING. Without this the `--gate-json` file keeps whatever the
+    // LAST run left there — so a CI wrapper that reads the artifact instead of the exit code sees the
+    // previous run's `ok: true` and reports a pass, which is the stale-artifact false green this format
+    // exists to refuse. java, rust and swift all overwrite on this branch; ts alone did not.
+    writeRefusal(`.candor/config declares \`baseline ${baselinePath}\` but that file is not there`);
+    process.exit(2);
+  } else if (baselinePath !== "" && !fs.existsSync(baselinePath)) {
     console.error(`candor-ts: CANDOR_BASELINE ${baselinePath} does not exist — the regression guard is `
       + `not active (record one: candor-ts <target> --out <prefix>, then point at the report .json).`);
   } else {
@@ -5075,6 +5541,10 @@ if (baselinePath !== null) {
     if (!Array.isArray(arr)) {
       console.error(`candor-ts: baseline ${shownB} exists but could not be parsed (corrupt/truncated?) — `
         + `failing (exit 2); the guard must not silently pass on an unreadable baseline. Regenerate it with this build.`);
+      // ⟨0.27⟩ the refusal document has no exempt cause AND no exempt sink (SPEC §3.1): a file sink holds
+      // the armed placeholder, but `--gate-json -` is not armed, so without this write the stream carried
+      // NOTHING on this cause. Writing here also replaces the placeholder with the specific reason.
+      writeRefusal(`baseline ${shownB} exists but could not be parsed — guard NOT evaluated`);
       process.exit(2);
     }
     const baseVersion = !Array.isArray(root) && root.candor && typeof root.candor === "object"
@@ -5082,12 +5552,14 @@ if (baselinePath !== null) {
     if (baseVersion === null) {
       console.error(`candor-ts: the baseline ${shownB} has no provenance header (a legacy/bare-array report) — `
         + `a baseline is comparable only to its producing build (§2.1). Failing (exit 2); regenerate it with this build.`);
+      writeRefusal(`baseline ${shownB} has no provenance header — guard NOT evaluated`);   // ⟨0.27⟩ see above
       process.exit(2);
     }
     if (baseVersion !== ENGINE_VERSION) {
       console.error(`candor-ts: the baseline ${shownB} was produced by engine build ${baseVersion} but this is `
         + `build ${ENGINE_VERSION} — an engine swap is baseline-invalidating and the gate cannot evaluate `
         + `(exit 2; never a silent skip, never a bogus AS-EFF-005 wave). Regenerate deliberately with this build.`);
+      writeRefusal(`baseline ${shownB} was produced by engine build ${baseVersion}, not this build — guard NOT evaluated`);   // ⟨0.27⟩ see above
       process.exit(2);
     }
     const base = new Map();
@@ -5114,6 +5586,7 @@ if (baselinePath !== null) {
         console.error(`candor-ts: the baseline callgraph ${sidecarPath} is present but could not be parsed `
           + `(corrupt/truncated?) — failing (exit 2); a broken sidecar must not silently narrow the guard to `
           + `report-only. Regenerate the baseline with this build.`);
+        writeRefusal(`baseline callgraph ${sidecarPath} could not be parsed — guard NOT evaluated`);   // ⟨0.27⟩ see above
         process.exit(2);
       }
       // The node set = every caller key + every callee (a pure leaf appears only as a callee), exactly
@@ -5221,9 +5694,11 @@ if (policyPath !== null) {
     if (policyErrs.length) {
       const why = policyErrorText(policyPath, policyErrs);
       console.error(why);
-      // ⟨0.24⟩ ONE `unevaluated` ENTRY PER POLICY LINE THAT COULD NOT BE HONOURED — the SHARED builder, so
-      // this document and `gate --report`'s stay byte-equal (§3.1's acceptance test for the two routes).
-      policyRefusal = { why, unevaluated: policyErrorUnevaluated(policyErrs) };
+      // ⟨0.27⟩ ONE `unevaluated` ENTRY PER RULE OF THE POLICY — not only the unhonourable lines (SPEC
+      // §3.1's composed-document clause). Measured: listing only the bad token's line let a consumer read
+      // `deny Fs`, absent from the exit-1 document's list, as evaluated-and-passed. The SHARED builder,
+      // so this document and `gate --report`'s stay byte-equal (§3.1's acceptance test for the routes).
+      policyRefusal = { why, unevaluated: policyRefusalUnevaluated(text, policyErrs) };
     } else {
       // ⟨0.24⟩ the config file that supplied vocabulary the verdict USED, so an ambient `.candor/config` — the
       // walk goes up through every parent, and CANDOR_CONFIG overrides it outright — cannot move a verdict while
@@ -5232,7 +5707,20 @@ if (policyPath !== null) {
         const p = discoverConfigPath(policyVocabularyAnchor(policyPath, target));
         if (p) policyVocabulary = { config: p, aliases: gatePolicy.aliasesUsed };
       }
-      gateViolations = gateViolations.concat(evaluatePolicy(gatePolicy, functions, cg, incompleteMap, netPartners));
+      const gateOut = evaluatePolicy(gatePolicy, functions, cg, incompleteMap, netPartners);
+      // ⟨0.27⟩ SPEC §4 — a rule that bound NO function is disclosed, never scored as satisfied. The exit
+      // code is deliberately untouched: a zero-match rule is legitimate when one policy is shared across
+      // repositories and a layer exists in only some of them, so refusal would make a shared policy
+      // unusable. Printed before the violations so a typo'd layer name is visible above the verdict.
+      for (const raw of gateOut.zeroMatch ?? []) {
+        console.error(`candor: policy rule matched NO function — \`${raw}\`. It was evaluated and bound `
+          + `nothing, so it cannot have caught anything. Legitimate when one policy is shared across `
+          + `repos; a typo'd layer name otherwise.`);
+      }
+      // ⟨0.27⟩ captured BEFORE the concat below — `concat` returns a plain array, so the `zeroMatch`
+      // property riding `gateOut` would be silently lost with it (see the gateZeroMatch declaration).
+      gateZeroMatch = gateOut.zeroMatch ?? [];
+      gateViolations = gateViolations.concat(gateOut);
       // Provable-purity DISCLOSURE (advisory — NEVER a violation, so the exit/verdict are untouched): functions
       // in a pure/deny scope that PASS but are Unknown (the Unknown could hide the forbidden effect — a
       // fn/closure-injected port). Surfaces the gap automatically (eval/fixloop/DISPATCH-NOTE.md).
@@ -5307,6 +5795,9 @@ if (gateJsonPath) {
   // consumer reading exit 1 must be able to see that the POLICY half of the gate never ran — the same
   // `unevaluated` key, in the same position, that `gate --report` uses for its answerability refusals.
   if (policyRefusal) verdictObj.unevaluated = policyRefusal.unevaluated;
+  // ⟨0.27⟩ SPEC §4 `zeroMatch` — the same list the stderr lines carry, in the machine channel. Omitted
+  // when empty so a fully-binding verdict is byte-identical; never consulted for `ok` or the exit code.
+  if (gateZeroMatch.length) verdictObj.zeroMatch = gateZeroMatch;
   // ⟨0.21⟩ (Gap 2) the machine-legible incompleteness: the units candor couldn't analyze, so a CI/agent
   // reading the JSON learns WHY the gate can't certify (the stderr warning alone used to hide this from a
   // machine). `incomplete:true` + the list; the run exits 2 (could-not-fully-evaluate) below. ok:false +