@rightkit/release 0.6.13 → 0.6.15

package/freshness-census.mjs

@@ -12,6 +12,15 @@
 // Counts come from the target directory the way the broker takes them (rustright-policy cargo_freshness.rs): a unit is one directory
 // of a `.fingerprint`; a unit whose newest file is at or after the census start was rebuilt (`notFresh`, a new unit included), the
 // others were reused (`fresh`). Judging unexplained rebuilds belongs to item 11; this module only measures and records.
+//
+// GB-68 (BROKER-CONTRACT section 16; the shared vector test-support/vectors/freshness-evidence-vectors.v1.json, held by freshness-vectors.test.mjs):
+//   - the log reader reads only the ROOT's lines: those before Cargo's first execution status word (`Compiling`, `Checking`, ... `Finished`); nested
+//     Cargo chatter after it is neither counted nor stripped; a `failed to read ...fingerprint...` reason followed by a `Caused by:` not-found cause
+//     (Unix `os error 2`, Windows `os error 3`) is `FingerprintMissing`, any other cause stays `unexplained`; every reason carries its `cause`;
+//   - the census reads the SELECTED scope only: `<target>/<profile>/.fingerprint` and, for a `--target` triple, `<target>/<triple>/<profile>/.fingerprint`
+//     (never every profile or triple, never `doc` or `package`), taken from the compiling process's own arguments and environment;
+//   - a fingerprint directory or unit that exists and cannot be read is `fingerprint-census-read-failed`: unavailable, never an empty census and never a
+//     first build. Only an absent directory is empty.
 import fs from "node:fs";
 import path from "node:path";
 
@@ -28,6 +37,86 @@ export const CENSUS_ENTRY_CAP = 250_000;
 // A held partial line longer than this is not a log line.
 const PARTIAL_CAP = 64 * 1024;
 
+/** Cargo's execution-phase status words: the first one ends the window in which fingerprint lines are the root's (pre-resolution words do not). */
+export const EXECUTION_STATUS = Object.freeze(["Compiling", "Checking", "Documenting", "Fresh", "Dirty", "Running", "Finished", "Scraping"]);
+const EXECUTION_WORDS = new Set(EXECUTION_STATUS);
+
+const SOURCE_OR_DEPENDENCY = new Set(["FsStatusOutdated", "PathToSourceChanged", "NumberOfDependenciesChanged", "UnitDependencyNameChanged", "UnitDependencyInfoChanged", "LocalLengthsChanged", "PrecalculatedComponentsChanged", "DepInfoOutputChanged", "RerunIfChangedOutputFileChanged", "RerunIfChangedOutputPathsChanged"]);
+const ENV_RUSTFLAGS_PROFILE_FEATURES_TARGET = new Set(["EnvVarChanged", "EnvVarsChanged", "RustflagsChanged", "ProfileConfigurationChanged", "FeaturesChanged", "DeclaredFeaturesChanged", "TargetConfigurationChanged", "CompileKindChanged", "LocalFingerprintTypeChanged", "FingerprintMethodChanged", "ConfigSettingsChanged"]);
+
+/**
+ * The cause a reason's `kind` explains (RustRight cargo_evidence.rs `cause_of`; the vector's `causes`): the first build, a missing fingerprint (named apart, and still unexplained
+ * by itself), a toolchain change, a source or dependency change, an environment, rustflags, profile, features or target change. Any other kind, one Cargo adds later included, is `unexplained`.
+ */
+export function causeOf(kind) {
+  if (kind === "FreshBuild") return "first-build";
+  if (kind === "FingerprintMissing") return "fingerprint-missing";
+  if (kind === "RustcChanged") return "toolchain-changed";
+  if (SOURCE_OR_DEPENDENCY.has(kind)) return "source-or-dependency-changed";
+  if (ENV_RUSTFLAGS_PROFILE_FEATURES_TARGET.has(kind)) return "env-rustflags-profile-features-or-target-changed";
+  return "unexplained";
+}
+
+/** Whether a `Caused by:` line says the fingerprint file was absent: `No such file or directory (os error 2)` on Unix, `... (os error 2)` or `... path specified. (os error 3)` on Windows. */
+const missingFingerprint = (cause) => cause.endsWith("(os error 2)") || cause.endsWith("(os error 3)");
+
+/** The profile directory a command line selects (RustRight `cargo_profile_directory`): `--release`/`-r`, `--profile X` (`dev` and `test` are `debug`, `bench` is `release`, a custom name is itself); nothing after `--`. */
+export function cargoProfileDirectory(argv) {
+  let profile = null; let release = false;
+  const words = Array.isArray(argv) ? argv.map(String) : [];
+  for (let i = 0; i < words.length && words[i] !== "--"; i += 1) {
+    const item = words[i];
+    if (item === "--release" || item === "-r") release = true;
+    else if (item === "--profile") profile = words[i + 1] ?? null;
+    else if (item.startsWith("--profile=")) profile = item.slice("--profile=".length);
+  }
+  if (profile === "dev" || profile === "test") return "debug";
+  if (profile === "bench") return "release";
+  if (profile !== null) return profile;
+  return release ? "release" : "debug";
+}
+
+/** Whether a command line asks for JSON messages (`--message-format json*` in any spelling, before `--`). */
+export function wantsCargoJson(argv) {
+  const words = Array.isArray(argv) ? argv.map(String) : [];
+  for (let i = 0; i < words.length; i += 1) {
+    const item = words[i];
+    if (item === "--") break;
+    const value = item === "--message-format" ? words[i + 1] : item.startsWith("--message-format=") ? item.slice("--message-format=".length) : undefined;
+    if (value !== undefined && value.split(",").some((segment) => segment.startsWith("json"))) return true;
+  }
+  return false;
+}
+
+/** The triples a command line names with `--target` (before `--`), then `CARGO_BUILD_TARGET` when the line names none. */
+export function cargoTargetTriples(argv, env = {}) {
+  const words = Array.isArray(argv) ? argv.map(String) : [];
+  const found = [];
+  for (let i = 0; i < words.length && words[i] !== "--"; i += 1) {
+    const item = words[i];
+    const value = item === "--target" ? words[i + 1] : item.startsWith("--target=") ? item.slice("--target=".length) : undefined;
+    if (typeof value === "string" && value !== "" && !found.includes(value)) found.push(value);
+  }
+  if (found.length === 0) {
+    const named = Object.entries(env ?? {}).find(([key]) => key.toUpperCase() === "CARGO_BUILD_TARGET");
+    if (named && typeof named[1] === "string" && named[1].trim() !== "") for (const t of named[1].trim().split(/\s+/)) if (!found.includes(t)) found.push(t);
+  }
+  return found;
+}
+
+/**
+ * The `.fingerprint` directories one compile selects in a target directory: `<target>/<triple>/<profile>/.fingerprint` for each selected triple, then `<target>/<profile>/.fingerprint`
+ * (RustRight `fingerprint_census_start`). Never every profile or triple, never `doc` or `package`.
+ */
+export function selectedFingerprintDirectories(targetDir, { argv = [], triples = [] } = {}) {
+  const profile = cargoProfileDirectory(argv);
+  const found = [];
+  for (const triple of triples) { const dir = path.join(targetDir, triple, profile, ".fingerprint"); if (!found.includes(dir)) found.push(dir); }
+  const plain = path.join(targetDir, profile, ".fingerprint");
+  if (!found.includes(plain)) found.push(plain);
+  return found;
+}
+
 const stripAnsi = (text) => text.replace(/\u001b\[[^A-Za-z]*[A-Za-z]/g, "");
 const afterPrefix = (message, prefixes) => {
   for (const prefix of prefixes) if (message.startsWith(prefix)) return message.slice(prefix.length);
@@ -63,6 +152,10 @@ export class FingerprintLog {
     this.dirtyUnits = 0;
     this.reasons = [];
     this.truncated = 0;
+    // Cargo printed its first execution-phase status line: later fingerprint lines are not the root's (a nested Cargo's).
+    this.executing = false;
+    // The reason just recorded was Cargo's `failed to read` of a `.fingerprint` file: its `Caused by:` chain follows on the next lines and says whether the file was simply absent.
+    this.awaitingCause = null;
   }
 
   /** One chunk of standard error in; what the caller sees out. Without stripping that is the chunk itself. */
@@ -91,8 +184,25 @@ export class FingerprintLog {
     return rest;
   }
 
+  /** Whether `raw` is one of the ROOT's fingerprint lines (counted, and stripped when stripping). */
   #line(raw) {
     const line = stripAnsi(raw.replace(/\s+$/, ""));
+    // GB-68: after the first execution status word nothing is the root's: nested Cargo chatter is neither counted nor stripped.
+    if (this.executing) { this.awaitingCause = null; return false; }
+    const first = line.trim().split(/\s+/)[0];
+    if (EXECUTION_WORDS.has(first)) { this.executing = true; return false; }
+    // The `Caused by:` chain of a `failed to read` reason: the heading, then the cause, indented. Blank lines inside the chain belong to it.
+    if (this.awaitingCause !== null) {
+      const text = line.trim();
+      if (text === "") return true;
+      if (!this.awaitingCause.headingSeen && text === "Caused by:") { this.awaitingCause.headingSeen = true; return true; }
+      const { index, headingSeen } = this.awaitingCause;
+      this.awaitingCause = null;
+      if (headingSeen && /^\s/.test(line)) {
+        if (missingFingerprint(text) && this.reasons[index]) { this.reasons[index].kind = "FingerprintMissing"; this.reasons[index].cause = causeOf("FingerprintMissing"); }
+        return true;
+      }
+    }
     const at = line.indexOf(FINGERPRINT_TARGET);
     if (at < 0) return false;
     const message = line.slice(at + FINGERPRINT_TARGET.length).replace(/^:+/, "").trim();
@@ -111,8 +221,11 @@ export class FingerprintLog {
     if (this.reasons.length >= REASONS_CAP) { this.truncated += 1; return; }
     const { unit, target } = this.current ?? { unit: "unknown", target: null };
     const chars = Array.from(reason);
-    const text = chars.length > REASON_TEXT_CAP ? `${chars.slice(0, REASON_TEXT_CAP).join("")}…` : reason;
-    this.reasons.push({ unit, target, kind: reasonKind(reason), reason: text });
+    const text = chars.length > REASON_TEXT_CAP ? `${chars.slice(0, REASON_TEXT_CAP).join("")}\u2026` : reason;
+    const kind = reasonKind(reason);
+    this.reasons.push({ unit, target, kind, cause: causeOf(kind), reason: text });
+    const readsFingerprint = reason.startsWith("failed to read `") && (reason.includes("/.fingerprint/") || reason.includes("\\.fingerprint\\"));
+    this.awaitingCause = readsFingerprint ? { index: this.reasons.length - 1, headingSeen: false } : null;
   }
 
   /** What another log's reading adds to this one (the census keeps one aggregate over every compiling process). */
@@ -146,76 +259,108 @@ export function compilesWorkspace(command, args) {
   return false;
 }
 
-// Directories never searched for `.fingerprint`s: rustdoc output and packaging verification are not a profile's units.
-const NOT_PROFILES = new Set(["doc", "package", "tmp", "incremental"]);
+/** An error that says the path is not there (an empty profile), as opposed to being there and unreadable. */
+const isAbsent = (error) => error?.code === "ENOENT";
 
-/** The `.fingerprint` directories of one target directory: `<target>/<profile>/.fingerprint` and `<target>/<triple>/<profile>/.fingerprint`. */
-export function fingerprintDirectories(targetDir, fsApi = fs) {
-  const found = [];
-  const subdirs = (dir) => {
-    try { return fsApi.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory() && !NOT_PROFILES.has(e.name)).map((e) => e.name); } catch { return []; }
-  };
-  const has = (dir) => { try { return fsApi.statSync(dir).isDirectory(); } catch { return false; } };
-  for (const first of subdirs(targetDir)) {
-    const direct = path.join(targetDir, first, ".fingerprint");
-    if (has(direct)) { found.push(direct); continue; }
-    for (const second of subdirs(path.join(targetDir, first))) {
-      const nested = path.join(targetDir, first, second, ".fingerprint");
-      if (has(nested)) found.push(nested);
-    }
-  }
-  return found;
+/** The fingerprint directory's entries: `{ names }`, `{ names: [] }` when it is absent, or `{ error }` when it exists and cannot be read (a file, permission, I/O: never read as empty). */
+function readFingerprintDirectory(dir, fsApi) {
+  try { return { names: fsApi.readdirSync(dir) }; } catch (error) { return isAbsent(error) ? { names: [] } : { error: `${dir}: ${error?.code ?? error?.message ?? "unreadable"}` }; }
 }
 
 /**
- * Walks every fingerprint directory of `targetDirs`. `withTimes: false` only counts units; `withTimes: true` also takes each unit's
- * newest file time. `capped` is set when more than `cap` entries (units and files) were visited.
+ * The `build.target` triples `.cargo/config.toml` / `.cargo/config` name for a compile run from `cwd` (the process's own directory upward, then `$CARGO_HOME`): the compile's output then
+ * sits under `<target>/<triple>/<profile>`, so the selected scope must name it as `--target` would. A simple reader of the `[build]` table's `target` string or string list.
  */
-export function walkFingerprints(targetDirs, { withTimes, cap = CENSUS_ENTRY_CAP, fsApi = fs } = {}) {
-  const units = new Map();
-  let visited = 0;
-  for (const targetDir of targetDirs) {
-    for (const fpDir of fingerprintDirectories(targetDir, fsApi)) {
-      let names;
-      try { names = fsApi.readdirSync(fpDir); } catch { continue; }
-      for (const name of names) {
-        visited += 1;
-        if (visited > cap) return { units, capped: true };
-        const unitDir = path.join(fpDir, name);
-        if (!withTimes) { units.set(unitDir, 0); continue; }
-        let newest = 0;
-        try {
-          const own = fsApi.statSync(unitDir);
-          newest = own.mtimeMs;
-          if (own.isDirectory()) {
-            for (const file of fsApi.readdirSync(unitDir)) {
-              visited += 1;
-              if (visited > cap) return { units, capped: true };
-              try { newest = Math.max(newest, fsApi.statSync(path.join(unitDir, file)).mtimeMs); } catch { /* vanished: ignore */ }
-            }
-          }
-        } catch { /* vanished: counted with the time it had */ }
-        units.set(unitDir, newest);
-      }
+export function configuredBuildTargets(cwd, { env = {}, fsApi = fs } = {}) {
+  const files = [];
+  if (typeof cwd === "string" && cwd) for (let dir = path.resolve(cwd); ; dir = path.dirname(dir)) { files.push(path.join(dir, ".cargo", "config.toml"), path.join(dir, ".cargo", "config")); if (path.dirname(dir) === dir) break; }
+  const home = Object.entries(env ?? {}).find(([key]) => key.toUpperCase() === "CARGO_HOME")?.[1];
+  if (typeof home === "string" && home) files.push(path.join(home, "config.toml"), path.join(home, "config"));
+  for (const file of files) {
+    let text;
+    try { text = fsApi.readFileSync(file, "utf8"); } catch { continue; }
+    let inBuild = false;
+    for (const raw of String(text).split(/\r?\n/)) {
+      const line = raw.replace(/#.*$/, "").trim();
+      const table = /^\[\s*([^\]]+?)\s*\]$/.exec(line);
+      if (table) { inBuild = table[1] === "build"; continue; }
+      const dotted = /^build\.target\s*=\s*(.+)$/.exec(line);
+      const plain = inBuild ? /^target\s*=\s*(.+)$/.exec(line) : null;
+      const value = (dotted ?? plain)?.[1];
+      if (value !== undefined) return [...value.matchAll(/["']([^"']+)["']/g)].map((m) => m[1]);
     }
   }
-  return { units, capped: false };
+  return [];
 }
 
 /**
- * One census for one stage of a direct compile: `start()` before the scans, `wrapSpawn(spawn)` around the scan runner's spawner
- * (it turns the fingerprint log on for the compiling cargo processes only), `finish()` after them.
+ * One census for one stage of a direct compile: `start()` before the scans, `wrapSpawn(spawn)` around the scan runner's spawner (it selects each compiling cargo process's scope and
+ * turns the fingerprint log on for it only), `finish()` after them. `start({ argv, triples, env })` selects a scope itself (a caller that knows the command).
+ *
+ * The scope is what the compiling processes SELECT (cargoProfileDirectory, cargoTargetTriples), not every profile directory of the target: each selected directory's baseline is read
+ * before the first process that selects it, and `since` is the census start. A directory that exists and cannot be read, at the baseline or in the walk, makes the census
+ * unavailable (`fingerprint-census-read-failed`); with no compiling process there is no scope and the census is unavailable (`fingerprint-census-no-compiling-process`).
  */
 export function createFreshnessCensus({ targetDirs, now = Date.now, fsApi = fs, cap = CENSUS_ENTRY_CAP } = {}) {
   const dirs = [...new Set(Object.values(targetDirs ?? {}).filter((d) => typeof d === "string" && d))];
   const log = new FingerprintLog({ strip: false });
-  let since = null; let atStart = null; let processes = 0; let outputCut = false;
+  let since = null; let processes = 0; let outputCut = false;
+  const baselines = new Map(); // fingerprint directory -> { count } | { error }
+  let unitsAtStart = 0; let capped = false; let readError = null; let selected = false;
+
+  const select = ({ argv = [], triples = null, env = {}, cwd = null } = {}) => {
+    const named = triples ?? [...cargoTargetTriples(argv, env), ...(cargoTargetTriples(argv, env).length === 0 ? configuredBuildTargets(cwd, { env, fsApi }) : [])];
+    for (const targetDir of dirs) {
+      for (const dir of selectedFingerprintDirectories(targetDir, { argv, triples: [...new Set(named)] })) {
+        selected = true;
+        if (baselines.has(dir)) continue;
+        const read = readFingerprintDirectory(dir, fsApi);
+        if (read.error !== undefined) { baselines.set(dir, { error: read.error }); readError ??= read.error; continue; }
+        baselines.set(dir, { count: read.names.length });
+        unitsAtStart += read.names.length;
+        if (unitsAtStart > cap) capped = true;
+      }
+    }
+  };
+
+  /** Walks the selected directories: the units' newest file times, or why the walk cannot be trusted. */
+  const walk = () => {
+    const units = new Map();
+    let visited = 0;
+    for (const dir of baselines.keys()) {
+      const read = readFingerprintDirectory(dir, fsApi);
+      if (read.error !== undefined) return { reason: "fingerprint-census-read-failed" };
+      for (const name of read.names) {
+        visited += 1;
+        if (visited > cap) return { reason: "fingerprint-census-entry-cap-exceeded" };
+        const unitDir = path.join(dir, name);
+        let newest = 0;
+        let files = [];
+        try { files = fsApi.readdirSync(unitDir); } catch (error) {
+          // A unit that vanished meanwhile, or is a plain file, holds no files; any other failure means its freshness was never read.
+          if (!isAbsent(error) && error?.code !== "ENOTDIR") return { reason: "fingerprint-census-read-failed" };
+        }
+        for (const file of files) {
+          visited += 1;
+          if (visited > cap) return { reason: "fingerprint-census-entry-cap-exceeded" };
+          try { newest = Math.max(newest, fsApi.statSync(path.join(unitDir, file)).mtimeMs); } catch { /* vanished: it holds no time */ }
+        }
+        units.set(unitDir, newest);
+      }
+    }
+    return { units };
+  };
+
   return {
-    start() { since = now(); atStart = walkFingerprints(dirs, { withTimes: false, cap, fsApi }); },
+    start(selection) { since = now(); if (selection) select(selection); },
+    select,
+    /** What the selection reads at the start: the directories, the units counted there, whether the entry cap was passed and the first read error. */
+    scope() { return { directories: [...baselines.keys()], unitsAtStart, capped, readError }; },
     wrapSpawn(spawn) {
       return async (command, args, options = {}) => {
         if (!compilesWorkspace(command, args)) return spawn(command, args, options);
         const env = options.env ?? process.env;
+        if (since !== null) select({ argv: Array.isArray(args) ? args : [], env, cwd: options.cwd ?? process.cwd() });
         // A caller's own CARGO_LOG stands and stays visible; the gate's own is kept out of the output.
         const ours = !Object.keys(env).some((k) => k.toUpperCase() === "CARGO_LOG");
         const result = await spawn(command, args, ours ? { ...options, env: { ...env, CARGO_LOG: FINGERPRINT_LOG_FILTER } } : options);
@@ -231,13 +376,16 @@ export function createFreshnessCensus({ targetDirs, now = Date.now, fsApi = fs,
     finish() {
       const base = { source: FRESHNESS_SOURCE, cargoProcesses: processes, dirtyUnits: log.dirtyUnits, truncated: log.truncated, ...(outputCut ? { outputCut: true } : {}) };
       const unavailable = (reason) => ({ unitsAtStart: 0, fresh: 0, notFresh: 0, invalidationReasons: log.reasons, available: false, reason, ...base });
-      if (since === null || atStart === null) return unavailable("fingerprint-census-not-started");
-      const end = walkFingerprints(dirs, { withTimes: true, cap, fsApi });
-      if (atStart.capped || end.capped) return unavailable("fingerprint-census-entry-cap-exceeded");
+      if (since === null) return unavailable("fingerprint-census-not-started");
+      if (!selected) return unavailable("fingerprint-census-no-compiling-process");
+      if (capped) return unavailable("fingerprint-census-entry-cap-exceeded");
+      if (readError !== null) return unavailable("fingerprint-census-read-failed");
+      const end = walk();
+      if (end.reason) return unavailable(end.reason);
       if (end.units.size === 0) return unavailable("no-fingerprint-units-found");
       let notFresh = 0;
       for (const newest of end.units.values()) if (newest >= since) notFresh += 1;
-      return { unitsAtStart: atStart.units.size, fresh: end.units.size - notFresh, notFresh, invalidationReasons: log.reasons, available: true, ...base };
+      return { unitsAtStart, fresh: end.units.size - notFresh, notFresh, invalidationReasons: log.reasons, available: true, ...base };
     },
   };
 }
@@ -250,7 +398,7 @@ export function validateFreshness(freshness) {
   if (!freshness || typeof freshness !== "object" || Array.isArray(freshness)) return ["freshness is absent"];
   for (const key of ["unitsAtStart", "fresh", "notFresh"]) if (!isCount(freshness[key])) problems.push(`freshness.${key} is not a count`);
   if (!Array.isArray(freshness.invalidationReasons)) problems.push("freshness.invalidationReasons is not a list");
-  else freshness.invalidationReasons.forEach((r, i) => { if (!r || typeof r.unit !== "string" || typeof r.kind !== "string" || typeof r.reason !== "string") problems.push(`freshness.invalidationReasons[${i}] has no unit, kind and reason`); });
+  else freshness.invalidationReasons.forEach((r, i) => { if (!r || typeof r.unit !== "string" || typeof r.kind !== "string" || typeof r.reason !== "string") problems.push(`freshness.invalidationReasons[${i}] has no unit, kind and reason`); else if (r.cause !== undefined && typeof r.cause !== "string") problems.push(`freshness.invalidationReasons[${i}].cause is not a string`); });
   if (freshness.available !== undefined && typeof freshness.available !== "boolean") problems.push("freshness.available is not a boolean");
   if (freshness.available === false && typeof freshness.reason !== "string") problems.push("an unavailable census names no reason");
   return problems;

package/gate-executor.mjs

@@ -2,27 +2,45 @@
 //   broker  - `rustright` is on PATH, or the first `cargo` is the broker's managed shim: every cargo call goes through the broker.
 //   refuse  - a broker-managed machine (Mac/Dell markers, broker socket, managed agent-bin) whose broker cannot be reached from here:
 //             the gate never compiles around it.
-//   direct  - every Linux host (WSL2, VM, cloud, CI, Linux hosted on the Dell) always, and any unmanaged Mac or Windows host: cargo
-//             runs directly, through the same gates and stages.
+//   direct  - every Linux host (WSL2, VM, cloud, CI, Linux hosted on the Dell) that has not declared a broker route, and any unmanaged Mac or
+//             Windows host: cargo runs directly, through the same gates and stages.
+//   Linux optional broker (Adrian, 2026-10-31: Linux normally needs no broker, but a broker is allowed there): a Linux host that EXPLICITLY declares
+//   RIGHTKIT_LINUX_BROKER_CLIENT + RIGHTKIT_LINUX_BROKER_SOCKET (managed-cargo.mjs resolveLinuxBrokerRoute) gets kind "broker" with route
+//   "linux-broker" when the client, endpoint and optional pinned digest validate, and kind "refuse" when they do not. A declared Linux broker never
+//   falls back to direct cargo; a `rustright` on PATH, a shim directory or a socket named in another variable never declares it.
 import { brokerManagedHost, managedCargoShimOnPath } from "./cargo-contract.mjs";
-import { directCargoPath, directPlatform } from "./managed-cargo.mjs";
+import { LINUX_BROKER_ROUTE, directCargoPath, directPlatform, resolveLinuxBrokerRoute } from "./managed-cargo.mjs";
 
-export { directCargoPath };
+export { directCargoPath, LINUX_BROKER_ROUTE };
 
 export const EXECUTOR_KINDS = Object.freeze(["broker", "refuse", "direct"]);
 
 /**
- * @param {{ env?: object, platform?: string, exists?: (p: string) => boolean, which: (cmd: string) => string[], readFile: (p: string) => string }} o
- * @returns {{ kind: "broker" | "refuse" | "direct", cargo: string[] | null, problem?: string, env?: { PATH: string }, note?: string }}
+ * @param {{ forceDirect?: boolean, env?: object, platform?: string, exists?: (p: string) => boolean, which: (cmd: string) => string[], readFile: (p: string) => string, fsOps?: object }} o
+ * @returns {{ kind: "broker" | "refuse" | "direct", cargo: string[] | null, problem?: string, code?: string, route?: "linux-broker", client?: string, socket?: string, clientSha256?: string, env?: { PATH?: string, RUSTRIGHT_BUILD_BROKER_SOCKET?: string }, note?: string }}
  */
-export function resolveExecutor({ env = process.env, platform = process.platform, exists, which, readFile }) {
+export function resolveExecutor({ env = process.env, platform = process.platform, exists, which, readFile, fsOps, forceDirect = false }) {
   // Every Linux (and any other non-Mac, non-Windows) execution host runs direct, whatever is on PATH or in the environment: WSL2, a VM,
-  // a cloud or CI runner, or Linux hosted on the Dell (GATE-CONTRACT §1 "One entry"; joint plan step 4). Only Adrian's Mac and Windows
-  // hosts use the broker.
+  // a cloud or CI runner, or Linux hosted on the Dell (GATE-CONTRACT §1 "One entry"; joint plan step 4), unless the host explicitly declared
+  // the optional Linux broker route (below). Adrian's Mac and Windows hosts use the broker as before.
   // `cargo` there must be a real toolchain: RustRight shim directories are taken off the PATH the gate hands its children (`env`).
-  if (directPlatform(platform)) {
-    const direct = directCargoPath({ env, exists });
-    return { kind: "direct", cargo: ["cargo"], ...(direct.dropped.length ? { env: { PATH: direct.path }, note: `RustRight shims taken off PATH for direct cargo: ${direct.dropped.join(", ")}` } : {}), ...(direct.cargo ? {} : { note: `no direct cargo on PATH${direct.dropped.length ? ` (RustRight shims skipped: ${direct.dropped.join(", ")})` : ""}; cargo scans fail as a missing tool` }) };
+  // `forceDirect` is the one documented exception (broker-exception.mjs, validated by the gate before it is passed): a Mac or Dell run
+  // outside the broker, by Adrian's recorded approval. It takes the direct route with the same shim scrub, never the Linux broker route.
+  if (forceDirect || directPlatform(platform)) {
+    const linux = forceDirect ? { declared: false } : resolveLinuxBrokerRoute({ env, platform, fsOps });
+    if (linux.declared) {
+      // One typed choice for the gate, managed-cargo, the carried adapters and every child (they read it again from the same environment): the
+      // validated client and endpoint, never a PATH lookup. `env` is what the gate hands its children: the endpoint the client must talk to.
+      if (!linux.ok) return { kind: "refuse", cargo: null, route: LINUX_BROKER_ROUTE, code: linux.code, problem: linux.problem };
+      return {
+        kind: "broker", route: LINUX_BROKER_ROUTE, cargo: [linux.client, "cargo"], client: linux.client, socket: linux.socket, clientSha256: linux.clientSha256,
+        env: { RUSTRIGHT_BUILD_BROKER_SOCKET: linux.socket },
+        note: `declared Linux broker route: client ${linux.client} (sha256 ${linux.clientSha256.slice(0, 12)}), endpoint ${linux.socket}`,
+      };
+    }
+    const pathKey = platform === "win32" ? Object.keys(env).find((k) => k.toUpperCase() === "PATH") ?? "PATH" : "PATH";
+    const direct = directCargoPath({ env: { ...env, PATH: env[pathKey] }, exists, platform });
+    return { kind: "direct", cargo: ["cargo"], ...(direct.dropped.length ? { env: { [pathKey]: direct.path }, note: `RustRight shims taken off PATH for direct cargo: ${direct.dropped.join(", ")}` } : {}), ...(direct.cargo ? {} : { note: `no direct cargo on PATH${direct.dropped.length ? ` (RustRight shims skipped: ${direct.dropped.join(", ")})` : ""}; cargo scans fail as a missing tool` }) };
   }
   if (which("rustright").length) return { kind: "broker", cargo: ["rustright", "cargo"] };
   const first = which("cargo")[0];

package/gate-stages.mjs

@@ -11,6 +11,8 @@
 import { createHash, randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { writeFileAtomic } from "./atomic-write.mjs";
+import { platformDirOf } from "./platform-dir.mjs";
 
 export const STAGES = Object.freeze(["check", "compile", "package", "qualify", "release"]);
 export const RECEIPT_SCHEMA = "rightkit.gate-receipt/1";
@@ -25,8 +27,11 @@ const sha256 = (data) => createHash("sha256").update(data).digest("hex");
  * `--to test` included, builds a commit; uncommitted changes never enter a build). One row per stage name the gate dispatches:
  * the STAGES, `dev` and `test`, `stage` (the hand-off to the publisher) and each STAGES entry again as a RightKit unit stage
  * (`--to <stage> --unit <selector>`). `compiles` and `packages` say whether the stage starts a compiler or seals bytes.
- *   source "snapshot": the gate-owned snapshot of the selected commit (`wired: false` names a stage whose snapshot route is
- *     refused today, `blocker` saying why; it still never reads the checkout).
+ *   source "snapshot": the gate-owned snapshot of the selected commit (the checkout is never a build source on any host: rightkit#1301 deleted
+ *     the checkout route, so no row carries an interim checkout rule). `implemented: true` says the executable route exists in code and runs;
+ *     `witnessed: false` with `pending` says which host acceptance (native fixture witness on the Mac and the Dell) has not yet been proved. The two
+ *     are separate facts (GB-86): an implemented route may run for its witness, and a route whose host acceptance is unproved is never presented as
+ *     ready for apps (`appFacingReady`). A stage the route planner cannot run fails at planning with a named capability, not through this table.
  *   source "sealed" or "publisher", with `basis`: the stage compiles nothing from source (it acts on bytes an earlier stage
  *     sealed, or runs only in the trusted publisher on hosted CI with its normal checkout, docs/GATE-CONTRACT.md).
  *   source "checkout", with `gap`: a known breach, listed so it cannot grow; stageSourceProblems ignores it, stageSourceGaps names it.
@@ -35,24 +40,35 @@ const sha256 = (data) => createHash("sha256").update(data).digest("hex");
  */
 export const STAGE_SOURCES = Object.freeze({
   check: { compiles: false, packages: false, source: "snapshot" },
-  compile: { compiles: true, packages: false, source: "snapshot", interim: "Mac and Dell: the clean-HEAD checkout route until the cutover" },
-  // Wired in code (row 7.04: build-release.mjs, release.mjs, cli/right-release.mjs, release-source-identity.mjs): right-release builds and seals the selected commit from the snapshot. `wired` becomes true when door-package.test.mjs passes on L and on M and D (dev broker).
-  package: { compiles: true, packages: true, source: "snapshot", wired: false, blocker: "wired in code (rows 7.04 and 7.04c: release-artifact-path.mjs binds each Cargo manifest's target, one resolver reads every declared artifact path); awaiting 7.04c green on L, M and D: the dev-broker rows need the snapshot carrier (rows 7.20 to 7.24) and RustRight's item-4 dev pins" },
+  compile: { compiles: true, packages: false, source: "snapshot" },
+  // Implemented in code (row 7.04: build-release.mjs, release.mjs, cli/right-release.mjs, release-source-identity.mjs): right-release builds and seals the selected commit from the snapshot. `witnessed` becomes true (and `pending` goes) when door-package.test.mjs passes on Linux and the native fixture witness passes on the Mac and the Dell (dev broker).
+  package: { compiles: true, packages: true, source: "snapshot", implemented: true, witnessed: false, pending: "route implemented in code (rows 7.04 and 7.04c: release-artifact-path.mjs binds each Cargo manifest's target, one resolver reads every declared artifact path); awaiting 7.04c green on L, M and D: the dev-broker rows need the snapshot carrier (rows 7.20 to 7.24) and RustRight's item-4 dev pins" },
   // Narrowed by decision 2 (7.06 correction): qualification rebuilds nothing, but its source reads (config, QA plan, test code) go through the split.
-  qualify: { compiles: false, packages: false, source: "snapshot", wired: false, blocker: "qa --stage installed takes its identity from the split (release-qa-command.mjs, row 7.04); awaiting its tests on every host" },
+  qualify: { compiles: false, packages: false, source: "snapshot", implemented: true, witnessed: false, pending: "qa --stage installed takes its identity from the split (release-qa-command.mjs, row 7.04); awaiting its tests on every host" },
   release: { compiles: false, packages: false, source: "publisher", basis: "--to release runs only in the trusted publisher on hosted CI with its normal checkout (docs/GATE-CONTRACT.md), and only uploads sealed bytes" },
-  dev: { compiles: true, packages: false, source: "snapshot", interim: "Mac and Dell: the checkout route (check --worktree) until the cutover" },
-  test: { compiles: true, packages: false, source: "snapshot", interim: "Mac and Dell: the checkout route (check --worktree) until the cutover" },
+  dev: { compiles: true, packages: false, source: "snapshot" },
+  test: { compiles: true, packages: false, source: "snapshot" },
   stage: { compiles: false, packages: false, source: "sealed", basis: "stage packs the sealed directory and its receipt into the publisher's draft release; it compiles nothing" },
-  // Row 7.06a: a unit stage builds the selected commit's snapshot (Linux now; Mac and Dell at the cutover commit, until which they take
-  // the clean-HEAD checkout route, decision 2 "Interim").
-  "unit:check": { compiles: false, packages: false, source: "snapshot", interim: "Mac and Dell: clean HEAD of the checkout until the cutover" },
-  "unit:compile": { compiles: true, packages: false, source: "snapshot", interim: "Mac and Dell: clean HEAD of the checkout until the cutover" },
-  "unit:package": { compiles: true, packages: true, source: "snapshot", interim: "Mac and Dell: clean HEAD of the checkout until the cutover" },
-  "unit:qualify": { compiles: false, packages: false, source: "snapshot", interim: "Mac and Dell: clean HEAD of the checkout until the cutover" },
+  // Row 7.06a: a unit stage builds the selected commit's snapshot on every host (runUnitSnapshot); hosted CI keeps its runner checkout, which is the commit.
+  "unit:check": { compiles: false, packages: false, source: "snapshot" },
+  "unit:compile": { compiles: true, packages: false, source: "snapshot" },
+  "unit:package": { compiles: true, packages: true, source: "snapshot" },
+  "unit:qualify": { compiles: false, packages: false, source: "snapshot" },
   "unit:release": { compiles: false, packages: false, source: "publisher", basis: "a unit release is dispatched to the trusted publisher (releaseUnit); it compiles nothing here" },
 });
 
+/**
+ * What a row says about readiness: `implemented` (the executable route exists), `witnessed` (host acceptance proved; absent means nothing is pending for the
+ * row) and `pending` (what remains). `appFacingReady` is true only for an implemented route with no pending host acceptance.
+ */
+export function stageReadiness(stage, table = STAGE_SOURCES) {
+  const row = table[stage];
+  if (!row) return null;
+  const implemented = row.source === "snapshot" ? row.implemented !== false : true;
+  const pending = typeof row.pending === "string" && row.pending ? row.pending : null;
+  return { stage, implemented, witnessed: pending === null && row.witnessed !== false, pending, appFacingReady: implemented && pending === null && row.witnessed !== false };
+}
+
 /** Rows of `table` that compile or package without a snapshot source, a stated exclusion basis or a registered gap. */
 export function stageSourceProblems(table = STAGE_SOURCES) {
   const out = [];
@@ -148,7 +164,7 @@ export function readReceipt({ commonDir, commit, app = ".", readFile = (f) => fs
   return null;
 }
 
-export function writeReceipt({ commonDir, receipt, write = fs.writeFileSync, mkdir = fs.mkdirSync }) {
+export function writeReceipt({ commonDir, receipt, write = (file, data) => writeFileAtomic(file, data), mkdir = fs.mkdirSync }) {
   const dir = path.join(gateStateDir(commonDir), "receipts");
   mkdir(dir, { recursive: true });
   write(path.join(dir, `${receiptKey(receipt.commit, receipt.app ?? ".")}.json`), `${JSON.stringify(receipt, null, 2)}\n`);
@@ -173,13 +189,74 @@ export function sameSource(a, b) {
   return Boolean(a && b) && a.tree === b.tree && a.gate === b.gate && JSON.stringify(a.locks) === JSON.stringify(b.locks);
 }
 
+/** Entries a compile-output census walks before it gives up (and the compile is then run again, warm, rather than trusted). */
+export const OUTPUT_CENSUS_LIMIT = 250000;
+
+/**
+ * What the compile stage produced, as the door can prove it later (GB-13, GATE E6/E7/E16): for each output directory the broker's
+ * receipt (or the direct host's resolution) named, every file's relative path and size, digested together. `truncated` means the walk
+ * hit `limit`; such a census never proves anything. A missing directory is recorded as missing, never as empty.
+ */
+export function outputCensus(dirs = [], { limit = OUTPUT_CENSUS_LIMIT, readdir = (d) => fs.readdirSync(d, { withFileTypes: true }), stat = (f) => fs.statSync(f) } = {}) {
+  const unique = [...new Set(dirs.filter((d) => typeof d === "string" && d))].sort();
+  const lines = []; let truncated = false; const missing = [];
+  for (const dir of unique) {
+    const stack = [""];
+    let exists = true;
+    while (stack.length && !truncated) {
+      const rel = stack.pop();
+      let entries;
+      try { entries = readdir(path.join(dir, rel)); } catch { if (rel === "") exists = false; continue; }
+      for (const e of entries) {
+        const next = rel ? `${rel}/${e.name}` : e.name;
+        if (e.isDirectory()) { stack.push(next); continue; }
+        let size = -1; try { size = stat(path.join(dir, next)).size; } catch { /* vanished while walking: recorded as -1 */ }
+        lines.push(`${dir}\0${next}\0${size}`);
+        if (lines.length > limit) { truncated = true; break; }
+      }
+    }
+    if (!exists) missing.push(dir);
+  }
+  lines.sort();
+  return { dirs: unique, entries: lines.length, truncated, missing, digest: sha256(lines.join("\n")) };
+}
+
+/** The environment a Cargo compile reads that picks its profile, target or flags: part of what a compile result is valid for. */
+const COMPILE_ENV = /^(CARGO_(?!HOME$|TARGET_DIR$|BUILD_TARGET_DIR$|REGISTRIES_|NET_|HTTP_|TERM_)|RUSTFLAGS$|RUSTDOCFLAGS$|RUSTC(_|$)|RUSTUP_TOOLCHAIN$)/;
+export function compileKeyOf(env = {}) {
+  const picked = Object.entries(env).filter(([k, v]) => COMPILE_ENV.test(k) && v !== undefined).sort(([a], [b]) => a.localeCompare(b));
+  return sha256(JSON.stringify(picked));
+}
+
+/** What a passed compile stage records about its outputs: the directories, their census and the key of the compile environment. */
+export function compileOutputsRecord({ dirs = [], env = {}, census = outputCensus }) {
+  const c = census(dirs);
+  return { dirs: c.dirs, entries: c.entries, digest: c.digest, truncated: c.truncated, key: compileKeyOf(env) };
+}
+
+/**
+ * Whether a recorded compile still stands for the outputs on disk now: null when it does, else the reason it does not. A record with no
+ * `outputs` (a receipt from before this binding) proves nothing and does not stand.
+ */
+export function compileReuseProblem(recorded, { env = {}, census = outputCensus } = {}) {
+  const out = recorded?.outputs;
+  if (!out || typeof out !== "object" || !Array.isArray(out.dirs) || typeof out.digest !== "string") return "the compile result records no outputs";
+  if (out.truncated) return "the recorded output census was incomplete";
+  if (out.key !== compileKeyOf(env)) return "the compile environment (profile, target or flags) differs from the recorded one";
+  const now = census(out.dirs);
+  if (now.missing.length) return `output directory ${now.missing[0]} is gone`;
+  if (now.truncated) return "the output census is too large to prove";
+  if (now.digest !== out.digest || now.entries !== out.entries) return "the compile outputs on disk differ from the recorded census (a required output was removed, replaced or added)";
+  return null;
+}
+
 /** The sealed release directory build-release wrote for `commit` on `platform`: { id, manifest, digest } or null. */
 export function sealedFor({ root, commit, platform, readdir = fs.readdirSync, readFile = (f) => fs.readFileSync(f) }) {
   const base = path.join(root, ".right-release", "sealed");
   let ids = [];
   try { ids = readdir(base).filter((id) => id.endsWith(`-${commit.slice(0, 8)}`)); } catch { return null; }
   for (const id of ids.sort()) {
-    const file = path.join(base, id, platform, "release-manifest.json");
+    const file = path.join(base, id, platformDirOf(platform), "release-manifest.json");
     try { const bytes = readFile(file); return { id, manifest: file, digest: sha256(bytes) }; } catch { /* not this platform */ }
   }
   return null;

package/github-release.mjs

@@ -11,6 +11,7 @@ import { verifySealedRelease } from "./release-state.mjs";
 import { admitInstalledQa } from "./release-qa-audit.mjs";
 import { addonManifestSha256, validateAddonConfig, validateAddonManifest } from "./addon-contract.mjs";
 import { RIGHTRELEASE_MANIFEST_SIGNER, verifyManifestCatalogSignature } from "./sign-release-manifest.mjs";
+import { platformDirOf } from "./platform-dir.mjs";
 
 const REPO_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\/[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
 const RELEASE_RE = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,159}$/;
@@ -21,7 +22,7 @@ export function prepareGitHubRelease({ repoRoot, releaseId, platform, repo, stat
   if (!RELEASE_RE.test(releaseId)) throw new Error(`invalid release id: ${releaseId}`);
   if (platform !== "mac" && platform !== "win") throw new Error("platform must be mac or win");
   if (!REPO_RE.test(repo)) throw new Error(`invalid GitHub repository: ${repo}`);
-  const platformDir = platform === "win" ? "windows" : "mac";
+  const platformDir = platformDirOf(platform);
   const sealed = verifySealedRelease(path.join(repoRoot, ".right-release", "sealed", releaseId, platformDir));
   if (sealed.manifest.platform !== platform) throw new Error("sealed release platform mismatch");
   const installers = sealed.manifest.files.filter((file) => file.role === "installer");

package/github-upload-gate.mjs

@@ -18,6 +18,7 @@ import { verifyOwnershipEvidence } from "./ownership-evidence.mjs";
 import { assertPrimaryReleaseCheckout } from "./release-invocation.mjs";
 import { verifySealedRelease } from "./release-state.mjs";
 import { assertCleanSource } from "./source-gate.mjs";
+import { platformDirOf } from "./platform-dir.mjs";
 
 /** Throws unless the operator named a tier. There is no default and no inference from the version or the notes. */
 export function assertUploadTier(tier) {
@@ -63,7 +64,7 @@ export async function authorizeGitHubUpload({
     status: git(repoRoot, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]),
     commandId: command,
   });
-  const platformDir = platform === "win" ? "windows" : "mac";
+  const platformDir = platformDirOf(platform);
   const sealed = verifySealedRelease(path.join(repoRoot, ".right-release", "sealed", releaseId, platformDir));
   if (sealed.manifest.commit !== candidateCommit) throw new Error("sealed release was built from a different commit than the current checkout");