@rightkit/release 0.6.10 → 0.6.11

package/direct-receipt.mjs

@@ -0,0 +1,135 @@
+// The direct (Linux) host's evidence for a snapshot compile (item 7 rows 7.09, 7.12, 7.18; GATE-CONTRACT "Broker interface"):
+//   - the output directory, resolved in the PRIMARY CHECKOUT with the stage's environment before the source location changes, with
+//     its inputs recorded (7.09);
+//   - the receipt the gate writes itself, "the same field names minus the broker-only ones (admission, queue, reusedFrom)" (7.18),
+//     and the consumer-side matrix that refuses a receipt that lacks one, carries a broker-only one, or holds no census (7.22 Linux half).
+// Pure functions with injected spawn and file system: the gate (bin/rightkit-gate.mjs) wires them to the host.
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { validateFreshness } from "./freshness-census.mjs";
+
+export const DIRECT_RECEIPT_SCHEMA = "rightkit.gate-direct-receipt/1";
+export const DIAGNOSTICS_SCHEMA = "rightkit.gate-direct-diagnostics/1";
+/** The names GATE-CONTRACT lists as broker-only: a direct receipt never carries them. */
+export const BROKER_ONLY_FIELDS = Object.freeze(["admission", "queue", "reusedFrom"]);
+/** The contract's returned-evidence names a direct receipt carries (7.18). `snapshot.path|treeAtStart|treeAtExit` are checked inside `snapshot`. */
+export const DIRECT_RECEIPT_REQUIRED = Object.freeze(["requestId", "brokerVersion", "executor", "commit", "snapshot", "declaredInputDigests", "verdict", "freshness", "timingsMs", "exit", "diagnosticsPath", "outputDir", "refreshed"]);
+export const TIMING_FIELDS = Object.freeze(["bind", "cargo", "afterExitBind", "diagnostics"]);
+/** The environment a `cargo metadata` target resolution reads: recorded by value (the rest of the environment by digest only). */
+export const TARGET_ENV_NAMES = Object.freeze(["CARGO_TARGET_DIR", "CARGO_BUILD_TARGET_DIR", "CARGO_HOME", "RUSTUP_TOOLCHAIN"]);
+
+const failed = (r) => !r || Boolean(r.error) || r.status !== 0;
+const why = (r) => String(r?.error?.message ?? r?.stderr ?? "").trim().split(/\r?\n/).slice(-3).join(" | ");
+
+/** True when `child` is `parent` or below it (lexically, after resolving both). */
+export function isWithin(parent, child) {
+  const rel = path.relative(path.resolve(parent), path.resolve(child));
+  return rel === "" || (rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel));
+}
+
+/** The stage environment a resolution ran with: the target-relevant names by value, the whole environment by digest. */
+export function envInputs(env) {
+  const record = {};
+  for (const name of TARGET_ENV_NAMES) record[name] = typeof env?.[name] === "string" ? env[name] : null;
+  const all = Object.keys(env ?? {}).sort().map((k) => `${k}=${env[k]}`).join("\n");
+  return { ...record, digest: createHash("sha256").update(all).digest("hex") };
+}
+
+/**
+ * The absolute output directory Cargo would use for one workspace, resolved where the contract says: `cargo metadata --format-version 1
+ * --no-deps` run with its working directory in the PRIMARY CHECKOUT (never the snapshot) and with the stage's environment, so
+ * `CARGO_TARGET_DIR`, `.cargo/config.toml` `build.target-dir` (relative to the checkout's config, or absolute) and the default `target/`
+ * all resolve as they do for a developer's own build. Returns `{ dir, inputs }` (the inputs are recorded in the receipt) or throws an
+ * `RK_TARGET_RESOLUTION` error whose message names why: a resolution made in the snapshot, no absolute directory, or a directory that
+ * lies inside the snapshot (a second output directory).
+ */
+export function resolveTargetDirectory({ spawn, cargoCommand, manifest, env, checkoutRoot, snapshotRoot = null, workspace = "." }) {
+  const fail = (message) => Object.assign(new Error(message), { code: "RK_TARGET_RESOLUTION" });
+  const cwd = path.dirname(manifest);
+  if (!isWithin(checkoutRoot, cwd)) throw fail(`the output directory of workspace ${workspace} must be resolved in the primary checkout ${checkoutRoot}, not in ${cwd}`);
+  if (snapshotRoot && isWithin(snapshotRoot, cwd)) throw fail(`the output directory of workspace ${workspace} must be resolved before the source location changes, not in the snapshot ${snapshotRoot}`);
+  const args = [...cargoCommand.slice(1), "metadata", "--offline", "--format-version", "1", "--no-deps", "--manifest-path", manifest];
+  const r = spawn(cargoCommand[0], args, { cwd, env });
+  let dir = null;
+  try { dir = failed(r) ? null : JSON.parse(String(r.stdout ?? "")).target_directory; } catch { dir = null; }
+  if (typeof dir !== "string" || !path.isAbsolute(dir)) throw fail(`cargo metadata in the checkout reported no absolute target_directory for ${workspace}${failed(r) ? ` (${why(r)})` : ""}`);
+  const resolved = path.resolve(dir);
+  if (snapshotRoot && isWithin(snapshotRoot, resolved)) throw fail(`the output directory of workspace ${workspace} resolves to ${resolved}, inside the snapshot ${snapshotRoot}; a snapshot compile writes only to the checkout's directory, never a second one under the commit`);
+  return { dir: resolved, inputs: { cwd, manifest, command: [cargoCommand[0], ...args], env: envInputs(env), targetDirectory: resolved } };
+}
+
+/** The Class A and B result the receipt's `verdict` carries (a direct compile reuses nothing, so no `reusedFrom`). */
+export function directVerdict({ scans = [], failures = [], deferrals = [] } = {}) {
+  const byClass = (c) => { const rows = scans.filter((s) => s.class === c); return { scans: rows.length, failed: rows.filter((s) => s.status === "fail").length }; };
+  return { result: failures.length ? "FAILED" : "PASSED", classA: byClass("A"), classB: byClass("B"), deferred: deferrals.length };
+}
+
+/** Writes the structured diagnostics of one direct compile and returns the file's absolute path (the receipt's `diagnosticsPath`). */
+export function writeDirectDiagnostics({ dir, requestId, commit, exit, scans = [], failures = [], deferrals = [], notes = [], freshness = null, writeFile = fs.writeFileSync, mkdir = fs.mkdirSync }) {
+  mkdir(dir, { recursive: true });
+  const file = path.resolve(dir, `direct-diagnostics-${requestId}.json`);
+  const rows = scans.map((s) => ({ id: s.id, class: s.class ?? null, status: s.status, ...(s.code ? { code: s.code } : {}), ...(s.detail ? { detail: String(s.detail).slice(0, 1000) } : {}) }));
+  writeFile(file, `${JSON.stringify({ schema: DIAGNOSTICS_SCHEMA, requestId, commit, exit, scans: rows, failures, deferrals, notes, freshness }, null, 2)}\n`);
+  return file;
+}
+
+/** The receipt of one direct compile: the contract's returned-evidence names, no broker-only one. Throws nothing; `verifyDirectReceipt` judges it. */
+export function buildDirectReceipt({ requestId, issuedAt, commit, snapshotPath, treeAtStart, treeAtExit, ownershipHandle = null, declaredInputDigests = [], verdict, freshness, timingsMs, exit, diagnosticsPath, outputDirs = {}, outputResolution = {}, cargoWrapper = null }) {
+  const dirs = [...new Set(Object.values(outputDirs))];
+  return {
+    schema: DIRECT_RECEIPT_SCHEMA, requestId, brokerVersion: null, executor: "direct", issuedAt,
+    commit: { sha: commit.sha, tree: commit.tree },
+    snapshot: { path: snapshotPath, treeAtStart, treeAtExit },
+    declaredInputDigests, ownership: { handle: ownershipHandle },
+    verdict, freshness, timingsMs, exit, exitStatus: exit, diagnosticsPath,
+    outputDir: dirs.length === 1 ? dirs[0] : null, outputDirs: { ...outputDirs }, outputResolution,
+    refreshed: [], cargoWrapper,
+  };
+}
+
+/**
+ * The consumer's matrix over a direct receipt (the Linux half of row 7.22): every contract name present with the right type, the
+ * snapshot bound to the commit's tree at start and exit, a well formed freshness census, and none of the broker-only names.
+ * Returns the list of problems; an empty list means the receipt verifies.
+ */
+export function verifyDirectReceipt(receipt) {
+  const problems = [];
+  if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)) return ["the receipt is not an object"];
+  if (receipt.schema !== DIRECT_RECEIPT_SCHEMA) problems.push(`schema is ${JSON.stringify(receipt.schema)}, not ${DIRECT_RECEIPT_SCHEMA}`);
+  for (const name of DIRECT_RECEIPT_REQUIRED) if (!Object.hasOwn(receipt, name)) problems.push(`${name} is absent`);
+  for (const name of BROKER_ONLY_FIELDS) if (Object.hasOwn(receipt, name)) problems.push(`${name} is a broker-only field; a direct receipt never carries it`);
+  const text = (v) => typeof v === "string" && v !== "";
+  if (Object.hasOwn(receipt, "requestId") && !text(receipt.requestId)) problems.push("requestId is not a string");
+  if (Object.hasOwn(receipt, "brokerVersion") && receipt.brokerVersion !== null) problems.push("brokerVersion is not null on a direct host");
+  if (Object.hasOwn(receipt, "executor") && receipt.executor !== "direct") problems.push(`executor is ${JSON.stringify(receipt.executor)}, not "direct"`);
+  const commit = receipt.commit;
+  if (Object.hasOwn(receipt, "commit") && !(commit && text(commit.sha) && text(commit.tree))) problems.push("commit has no sha and tree");
+  const snap = receipt.snapshot;
+  if (Object.hasOwn(receipt, "snapshot")) {
+    if (!(snap && text(snap.path) && text(snap.treeAtStart) && text(snap.treeAtExit))) problems.push("snapshot has no path, treeAtStart and treeAtExit");
+    else if (commit && text(commit.tree) && (snap.treeAtStart !== commit.tree || snap.treeAtExit !== commit.tree)) problems.push("snapshot.treeAtStart and treeAtExit are not the commit's tree");
+  }
+  if (Object.hasOwn(receipt, "declaredInputDigests") && !Array.isArray(receipt.declaredInputDigests)) problems.push("declaredInputDigests is not a list");
+  const verdict = receipt.verdict;
+  if (Object.hasOwn(receipt, "verdict") && !(verdict && (verdict.result === "PASSED" || verdict.result === "FAILED"))) problems.push("verdict has no PASSED or FAILED result");
+  if (Object.hasOwn(receipt, "freshness")) for (const p of validateFreshness(receipt.freshness)) problems.push(p);
+  const timings = receipt.timingsMs;
+  if (Object.hasOwn(receipt, "timingsMs")) {
+    if (!timings || typeof timings !== "object") problems.push("timingsMs is not an object");
+    else {
+      for (const name of TIMING_FIELDS) if (!(Number.isFinite(timings[name]) && timings[name] >= 0)) problems.push(`timingsMs.${name} is not a duration`);
+      for (const name of BROKER_ONLY_FIELDS) if (Object.hasOwn(timings, name)) problems.push(`timingsMs.${name} is a broker-only field`);
+    }
+  }
+  if (Object.hasOwn(receipt, "exit") && !Number.isInteger(receipt.exit)) problems.push("exit is not an exit status");
+  if (Object.hasOwn(receipt, "diagnosticsPath") && !(text(receipt.diagnosticsPath) && path.isAbsolute(receipt.diagnosticsPath))) problems.push("diagnosticsPath is not an absolute path");
+  if (Object.hasOwn(receipt, "outputDir")) {
+    const dirs = receipt.outputDirs && typeof receipt.outputDirs === "object" ? Object.values(receipt.outputDirs) : [];
+    if (text(receipt.outputDir)) { if (!path.isAbsolute(receipt.outputDir)) problems.push("outputDir is not absolute"); }
+    else if (!(receipt.outputDir === null && new Set(dirs).size !== 1)) problems.push("outputDir is not the resolved absolute path (null only when the commit has no Cargo workspace, or several workspaces name several directories)");
+    for (const d of dirs) if (!(text(d) && path.isAbsolute(d))) problems.push(`outputDirs holds ${JSON.stringify(d)}, not an absolute path`);
+  }
+  if (Object.hasOwn(receipt, "refreshed") && !Array.isArray(receipt.refreshed)) problems.push("refreshed is not a list");
+  return problems;
+}

package/door-policy.mjs

@@ -144,6 +144,10 @@ function argvViolation(argv, depth = 0, stdin = null) {
     else if (script) return null;
     else { a = rest; tool = base(a[0]); }
   }
+  // `rightkit-gate clippy [<cargo clippy args>]` is the agent entry for Clippy (GATE-CONTRACT §1 "Clippy route & batching", item 8 row
+  // 8.14): like every `rightkit-gate` subcommand it is the door, taken through the pinned gate (build-control-policy agentDoorViolation
+  // denies an unpinned copy as untrusted-gate) and run in the same order for a human and an agent. Direct `cargo clippy` and
+  // `cargo +<toolchain> clippy` stay denied by CARGO_COMPILES above, with the route named in the denial.
   if (tool === "rightkit-gate" || tool === "rustright") return null;
   if (tool === "tauri" && TAURI_BUILDS.has(a[1])) return `tauri ${a[1]}`;
   // Apple: xcrun wraps the tool it names; xcodebuild builds by default (no action word is `build`); swift build|test|run and swiftc compile.
@@ -262,7 +266,13 @@ export function doorViolation(command, depth = 0) {
   return null;
 }
 
+/** The agent entry for Clippy; a direct `cargo clippy` is denied in its favour. */
+export const CLIPPY_ROUTE = "rightkit-gate clippy [<cargo clippy args>]";
+
 export function doorDenial(violation) {
+  if (violation === "cargo clippy") {
+    return `[HOOK:one-door:block]\nWhy: \`${violation}\` builds outside the one door. Every check, compile, test, package and release goes through rightkit-gate, class A first.\nRequired: ${CLIPPY_ROUTE} (Clippy on HEAD's commit, class A first).`;
+  }
   const mobile = /^(cargo )?tauri (android|ios)$|^xcodebuild (archive|install)|^gradle (assemble|bundle|build|publish|install)/.test(violation) ? (/ios|xcodebuild/.test(violation) ? "ios" : "android") : null;
   const stage = /^right-release (dev|test)$/.test(violation) ? violation.slice("right-release ".length) : /^(cargo )?tauri dev$/.test(violation) ? "dev"
     : /^right-release (upload|publish|publish-update|github)$/.test(violation) ? "release" : /^right-release qa$/.test(violation) ? "qualify"

package/door.mjs

@@ -2,16 +2,16 @@
 // packager) that right-release runs inside a stage. The step proceeds only when a live `rightkit-gate --to` run for HEAD launched it,
 // the same check right-release makes for itself (gate-stages.mjs requireDoorRun), so `node scripts/release/<step>.mjs` run by hand is
 // refused instead of becoming a side door around class A.
-import path from "node:path";
 import { spawnSync } from "./background-process.mjs";
 import { requireDoorRun } from "./gate-stages.mjs";
+import { doorContextFor } from "./source-split.mjs";
 
-/** null when a live door run for HEAD launched this process, else the refusal message. */
+/** null when a live door run for HEAD (or, inside a source split, for the split's commit) launched this process, else the refusal message. */
 export function doorRefusal({ cwd = process.cwd(), env = process.env, command = "this build step", run = spawnSync, alive } = {}) {
-  const git = (args) => { const r = run("git", args, { cwd, encoding: "utf8" }); return r.status === 0 ? String(r.stdout).trim() : ""; };
-  const common = git(["rev-parse", "--git-common-dir"]);
-  if (!common) return `${command} runs only in a git checkout, through the one door: rightkit-gate --to <stage>`;
-  return requireDoorRun({ env, commonDir: path.resolve(cwd, common), commit: git(["rev-parse", "HEAD"]), command, ...(alive ? { alive } : {}) });
+  let context;
+  try { context = doorContextFor({ cwd, env, run }); } catch (error) { return `${command}: ${error.code ?? "RK_SOURCE_SPLIT"}: ${error.message}`; }
+  if (!context) return `${command} runs only in a git checkout, through the one door: rightkit-gate --to <stage>`;
+  return requireDoorRun({ env, commonDir: context.commonDir, commit: context.commit, command, ...(alive ? { alive } : {}) });
 }
 
 /** Exits 2 with the refusal unless a live door run launched this process. */

package/freshness-census.mjs

@@ -0,0 +1,257 @@
+// The freshness census of a direct (Linux) snapshot compile (item 7 row 7.19; GATE-CONTRACT "Returned evidence", `freshness`:
+// `{ unitsAtStart, fresh, notFresh, invalidationReasons }`, the census the measured-cache rule is judged from; E16: "the second
+// build's census shows reuse").
+//
+// Cargo keeps no invalidation reason on disk: a fingerprint file holds the current hash only. The reason exists only in Cargo's own
+// fingerprint log (`CARGO_LOG=cargo::core::compiler::fingerprint=info`: a `fingerprint dirty for <unit>` line, then `dirty: <reason>`),
+// the same source the RustRight broker reads for its receipt (rustright-broker job_service/cargo_evidence.rs; attested-runs.md).
+// The gate turns that log on for the cargo processes that compile a workspace, on THAT process only (never in the scan environment
+// the repository's own tests and scripts inherit), reads it from the process's standard error, and keeps the lines out of the output
+// unless the caller set CARGO_LOG itself (a caller's own CARGO_LOG is read the same way and left visible).
+//
+// 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.
+import fs from "node:fs";
+import path from "node:path";
+
+/** The `CARGO_LOG` filter the gate sets for a compiling cargo process (the broker's FINGERPRINT_LOG_FILTER). */
+export const FINGERPRINT_LOG_FILTER = "cargo::core::compiler::fingerprint=info";
+const FINGERPRINT_TARGET = "cargo::core::compiler::fingerprint";
+export const FRESHNESS_SOURCE = "cargo-fingerprint-log+fingerprint-mtime";
+/** Reasons kept in the receipt; the rest are counted. */
+export const REASONS_CAP = 200;
+/** Characters kept of one reason (Cargo prints it with `Debug`, paths and mtimes included). */
+export const REASON_TEXT_CAP = 512;
+/** Unit directories and files visited before the census is declared unavailable rather than partial. */
+export const CENSUS_ENTRY_CAP = 250_000;
+// A held partial line longer than this is not a log line.
+const PARTIAL_CAP = 64 * 1024;
+
+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);
+  return null;
+};
+
+/** `name version` and the target of the unit a dirty line names (the span carries `target="..."`; the message `<name> v<ver> (<src>)/<mode>/...`). */
+function unitOf(prefix, rest) {
+  let target = null;
+  const at = prefix.indexOf('target="');
+  if (at >= 0) {
+    const value = prefix.slice(at + 8);
+    const end = value.indexOf('"');
+    if (end >= 0) target = value.slice(0, end);
+  }
+  const head = rest.split("/")[0] ?? rest;
+  const unit = (head.split(" (")[0] ?? head).trim();
+  return { unit, target };
+}
+
+/** The reason's variant name (`FsStatusOutdated`, `RustflagsChanged`, ...): what a summary groups by. */
+const reasonKind = (reason) => {
+  const kind = reason.split(/[^\p{L}\p{N}_]/u)[0];
+  return kind ? kind : "unknown";
+};
+
+/** Reads Cargo's fingerprint log from a process's standard error; `strip` keeps its lines out of what the caller sees. */
+export class FingerprintLog {
+  constructor({ strip = false } = {}) {
+    this.strip = strip;
+    this.partial = "";
+    this.current = null;
+    this.dirtyUnits = 0;
+    this.reasons = [];
+    this.truncated = 0;
+  }
+
+  /** One chunk of standard error in; what the caller sees out. Without stripping that is the chunk itself. */
+  feed(chunk) {
+    this.partial += String(chunk);
+    let shown = "";
+    for (let at = this.partial.indexOf("\n"); at >= 0; at = this.partial.indexOf("\n")) {
+      const line = this.partial.slice(0, at + 1);
+      this.partial = this.partial.slice(at + 1);
+      const isLog = this.#line(line);
+      if (!isLog || !this.strip) shown += line;
+    }
+    if (this.partial.length > PARTIAL_CAP) {
+      const rest = this.partial;
+      this.partial = "";
+      if (this.strip) shown += rest;
+    }
+    return this.strip ? shown : String(chunk);
+  }
+
+  /** The end of the stream: a held partial line is judged and, when stripping and it is not a log line, returned. */
+  finish() {
+    const rest = this.partial;
+    this.partial = "";
+    if (rest === "" || this.#line(rest) || !this.strip) return "";
+    return rest;
+  }
+
+  #line(raw) {
+    const line = stripAnsi(raw.replace(/\s+$/, ""));
+    const at = line.indexOf(FINGERPRINT_TARGET);
+    if (at < 0) return false;
+    const message = line.slice(at + FINGERPRINT_TARGET.length).replace(/^:+/, "").trim();
+    const unitLine = afterPrefix(message, ["fingerprint dirty for ", "fingerprint error for "]);
+    if (unitLine !== null) {
+      this.dirtyUnits += 1;
+      this.current = unitOf(line.slice(0, at), unitLine);
+      return true;
+    }
+    const reason = afterPrefix(message, ["dirty:", "err:"]);
+    if (reason !== null) this.#record(reason.trim());
+    return true;
+  }
+
+  #record(reason) {
+    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 });
+  }
+
+  /** What another log's reading adds to this one (the census keeps one aggregate over every compiling process). */
+  merge(other) {
+    this.dirtyUnits += other.dirtyUnits;
+    this.truncated += other.truncated;
+    for (const reason of other.reasons) {
+      if (this.reasons.length >= REASONS_CAP) this.truncated += 1;
+      else this.reasons.push(reason);
+    }
+  }
+}
+
+// Cargo subcommands that compile a workspace's units (the wrapper's COMPILE set without metadata and package, which the census
+// does not count). `--` ends cargo's own arguments; `--color` and `--explain` take a value.
+const COMPILING = new Set(["build", "b", "check", "c", "test", "t", "bench", "run", "r", "doc", "d", "rustc", "rustdoc", "clippy"]);
+const GLOBAL_VALUE = new Set(["--color", "--explain"]);
+
+/** True when `command args` is a cargo process that compiles a workspace's units (its fingerprint log is the census's). */
+export function compilesWorkspace(command, args) {
+  if (path.basename(String(command)).replace(/\.exe$/i, "") !== "cargo") return false;
+  const words = Array.isArray(args) ? args : [];
+  let i = typeof words[0] === "string" && words[0].startsWith("+") ? 1 : 0;
+  for (; i < words.length; i += 1) {
+    const w = String(words[i]);
+    if (w === "--") return false;
+    if (GLOBAL_VALUE.has(w)) { i += 1; continue; }
+    if (w.startsWith("-")) continue;
+    return COMPILING.has(w);
+  }
+  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"]);
+
+/** 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;
+}
+
+/**
+ * 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.
+ */
+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);
+      }
+    }
+  }
+  return { units, capped: false };
+}
+
+/**
+ * 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.
+ */
+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;
+  return {
+    start() { since = now(); atStart = walkFingerprints(dirs, { withTimes: false, cap, fsApi }); },
+    wrapSpawn(spawn) {
+      return async (command, args, options = {}) => {
+        if (!compilesWorkspace(command, args)) return spawn(command, args, options);
+        const env = options.env ?? process.env;
+        // 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);
+        processes += 1;
+        if (!result || typeof result.stderr !== "string") return result;
+        if (result.truncated) outputCut = true;
+        const reading = new FingerprintLog({ strip: ours });
+        const shown = reading.feed(result.stderr) + reading.finish();
+        log.merge(reading);
+        return { ...result, stderr: shown };
+      };
+    },
+    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 (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 };
+    },
+  };
+}
+
+const isCount = (n) => Number.isInteger(n) && n >= 0;
+
+/** What is wrong with a `freshness` object (an empty list: it is the census the contract names, well formed). */
+export function validateFreshness(freshness) {
+  const problems = [];
+  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`); });
+  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-stages.mjs

@@ -15,9 +15,62 @@ import path from "node:path";
 export const STAGES = Object.freeze(["check", "compile", "package", "qualify", "release"]);
 export const RECEIPT_SCHEMA = "rightkit.gate-receipt/1";
 export const RUN_ENV = "RK_GATE_RUN";
+/** Set beside RUN_ENV for a run that carries a source split: the checkout whose git directory holds the run file. */
+export const CHECKOUT_ENV = "RK_GATE_CHECKOUT";
 
 const sha256 = (data) => createHash("sha256").update(data).digest("hex");
 
+/**
+ * Where every stage the gate runs reads its source from (docs/GATE-CONTRACT.md "Commit-only build": every stage, `--to dev` and
+ * `--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 "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.
+ * door-stages.test.mjs fails on a stage with no row, on a compiling or packaging row that has none of these, and on a gap that is
+ * not in its expected list.
+ */
+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" },
+  // 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" },
+  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" },
+  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" },
+  "unit:release": { compiles: false, packages: false, source: "publisher", basis: "a unit release is dispatched to the trusted publisher (releaseUnit); it compiles nothing here" },
+});
+
+/** 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 = [];
+  for (const [stage, row] of Object.entries(table)) {
+    if (!row.compiles && !row.packages) continue;
+    if (row.source === "snapshot") continue;
+    if (typeof row.basis === "string" && row.basis && ["sealed", "publisher"].includes(row.source)) continue;
+    if (row.source === "checkout" && typeof row.gap === "string" && row.gap) continue;
+    out.push({ stage, problem: `${stage} compiles or packages and its source is ${JSON.stringify(row.source)} with no snapshot source, exclusion basis or registered gap` });
+  }
+  return out;
+}
+
+/** The registered breaches in `table`: stages that compile or package from the checkout. */
+export function stageSourceGaps(table = STAGE_SOURCES) {
+  return Object.entries(table).filter(([, row]) => row.source === "checkout" && (row.compiles || row.packages)).map(([stage]) => stage);
+}
+
 /** The stages a run to `target` covers, in order; null when `target` is not a stage. */
 export function stagesTo(target) {
   const i = STAGES.indexOf(target);
@@ -29,14 +82,18 @@ export function gateStateDir(commonDir) {
   return path.join(commonDir, "rightkit-gate");
 }
 
-/** Starts a door run: writes the run file and returns { nonce, file, env }. The caller removes it with endRun. */
-export function startRun({ commonDir, commit, tree, stage, pid = process.pid, write = fs.writeFileSync, mkdir = fs.mkdirSync }) {
+/**
+ * Starts a door run: writes the run file and returns { nonce, file, env }. The caller removes it with endRun. `source` is the
+ * commit-only build's source split (source-split.mjs): { checkout, snapshot, commit, tree, appDir }, written into the run so a
+ * right-release child can learn which snapshot it may read; its env then names the checkout the run file lives under.
+ */
+export function startRun({ commonDir, commit, tree, stage, source, pid = process.pid, write = fs.writeFileSync, mkdir = fs.mkdirSync }) {
   const nonce = randomBytes(16).toString("hex");
   const dir = path.join(gateStateDir(commonDir), "runs");
   mkdir(dir, { recursive: true });
   const file = path.join(dir, `${nonce}.json`);
-  write(file, `${JSON.stringify({ pid, commit, tree, stage, startedAt: new Date().toISOString() })}\n`);
-  return { nonce, file, env: { [RUN_ENV]: nonce } };
+  write(file, `${JSON.stringify({ pid, commit, tree, stage, ...(source ? { source } : {}), startedAt: new Date().toISOString() })}\n`);
+  return { nonce, file, env: { [RUN_ENV]: nonce, ...(source ? { [CHECKOUT_ENV]: source.checkout } : {}) } };
 }
 
 export function endRun(run, rm = fs.rmSync) {
@@ -48,16 +105,25 @@ export function endRun(run, rm = fs.rmSync) {
  * whose pid is gone, or that names another commit, is no run.
  */
 export function requireDoorRun({ env = process.env, commonDir, commit, readFile = (f) => fs.readFileSync(f, "utf8"), alive = pidAlive, command = "this command" }) {
-  const nonce = env[RUN_ENV];
   const refusal = `${command} runs only through the one door: rightkit-gate --to <check|compile|package|qualify|release> (it runs class A first, then every stage in order)`;
-  if (!nonce || !/^[0-9a-f]{32}$/.test(nonce)) return refusal;
-  let run;
-  try { run = JSON.parse(readFile(path.join(gateStateDir(commonDir), "runs", `${nonce}.json`))); } catch { return `${refusal}; RK_GATE_RUN names no live door run`; }
-  if (!alive(run.pid)) return `${refusal}; the door run that launched it has ended`;
-  if (commit && run.commit !== commit) return `${refusal}; the door run is for ${String(run.commit).slice(0, 12)}, HEAD is ${commit.slice(0, 12)}`;
+  const found = readDoorRun({ env, commonDir, readFile, alive });
+  if (found.problem === "none") return refusal;
+  if (found.problem === "unread") return `${refusal}; RK_GATE_RUN names no live door run`;
+  if (found.problem === "ended") return `${refusal}; the door run that launched it has ended`;
+  if (commit && found.run.commit !== commit) return `${refusal}; the door run is for ${String(found.run.commit).slice(0, 12)}, HEAD is ${commit.slice(0, 12)}`;
   return null;
 }
 
+/** The live door run RK_GATE_RUN names: { run } or { problem: "none" | "unread" | "ended" }. */
+export function readDoorRun({ env = process.env, commonDir, readFile = (f) => fs.readFileSync(f, "utf8"), alive = pidAlive }) {
+  const nonce = env[RUN_ENV];
+  if (!nonce || !/^[0-9a-f]{32}$/.test(nonce)) return { problem: "none" };
+  let run;
+  try { run = JSON.parse(readFile(path.join(gateStateDir(commonDir), "runs", `${nonce}.json`))); } catch { return { problem: "unread" }; }
+  if (!alive(run.pid)) return { problem: "ended" };
+  return { run };
+}
+
 function pidAlive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
   try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }

package/hook-retirement.mjs

@@ -0,0 +1,65 @@
+// Retirement of the git hooks RightKit used to write (docs/GATE-CONTRACT.md: "Commit and push run no gate and no local hook
+// checks"). `rightkit-gate install-hook` and `right-release hooks install` no longer write a pre-push gate, the forwarders
+// that chained .git/hooks beside it, or the advisory ownership pre-commit step; they remove the ones an earlier release wrote.
+//
+// A file is ours only by its own text, never by its name or its place:
+//   - the gate hook      : line 2 is the header every published hook carries ("# Mandatory local [check and] gate before every
+//                          push (rightkit-gate install-hook). Never bypass with --no-verify.");
+//   - a forwarder        : line 2 is the forwarder header naming the hook it forwards, and that hook is the file's own name
+//                          (pre-commit.rightkit-foreign may forward `pre-commit` or itself);
+//   - the ownership step : the HOOK_MARKER sits in the first three lines.
+// Anything else is a foreign hook and is never read for change, moved, rewritten or deleted. A symbolic link is never ours.
+// One exception to "never moved": the foreign pre-commit the ownership step preserved as pre-commit.rightkit-foreign goes back to
+// pre-commit when the ownership step that displaced it is removed.
+import path from "node:path";
+
+export const HOOK_MARKER = "rightkit-ownership-precommit v1";
+export const FOREIGN_PRE_COMMIT = "pre-commit.rightkit-foreign";
+
+const GATE_HEADER = /^# Mandatory local (?:check and )?gate before every push \(rightkit-gate install-hook\)\. Never bypass with --no-verify\.$/;
+const FORWARDER_HEADER = /^# rightkit-gate install-hook: core\.hooksPath=\.githooks hides \.git\/hooks, so run this repository's own (\S+) hook from there\.$/;
+
+const lines = (text) => String(text).replace(/\r\n/g, "\n").split("\n");
+
+/** What a hook file is, by its text and its name: "gate", "forwarder", "ownership" or null (foreign). `scripts` is false for a directory the gate never wrote into. */
+export function hookKind(name, text, { scripts = true } = {}) {
+  const [shebang, second = "", third = ""] = lines(text);
+  if (shebang !== "#!/bin/sh") return null;
+  if ([second, third].some((line) => line.startsWith(`# ${HOOK_MARKER}`))) return "ownership";
+  if (!scripts) return null;
+  if (name === "pre-push" && GATE_HEADER.test(second)) return "gate";
+  const forwarded = FORWARDER_HEADER.exec(second)?.[1];
+  if (forwarded && (forwarded === name || (name === FOREIGN_PRE_COMMIT && forwarded === "pre-commit"))) return "forwarder";
+  return null;
+}
+
+/**
+ * Remove the hooks RightKit wrote from `dir`. `ops` = { readdir, readFile, lstat, unlink, rename, rmdir } (fs-shaped). Returns
+ * { found, removed: [name], restored: [name], remaining: [name] }: `found` is false when `dir` cannot be listed, `remaining` is every
+ * file left in it (foreign hooks), and an emptied directory is removed (`removedDir`).
+ */
+export function retireHooksIn(dir, ops, { scripts = true, removeEmptyDir = scripts } = {}) {
+  let names;
+  try { names = [...ops.readdir(dir)].map(String).sort(); } catch { return { found: false, removed: [], restored: [], remaining: [], removedDir: false }; }
+  const removed = []; const restored = []; const kinds = new Map();
+  for (const name of names) {
+    const file = path.join(dir, name);
+    let kind = null;
+    try {
+      const stat = ops.lstat(file);
+      if (stat.isFile() && !stat.isSymbolicLink()) kind = hookKind(name, ops.readFile(file), { scripts });
+    } catch { kind = null; }
+    kinds.set(name, kind);
+    if (!kind) continue;
+    try { ops.unlink(file); removed.push(name); } catch { kinds.set(name, null); }
+  }
+  // The ownership step displaced a foreign pre-commit into pre-commit.rightkit-foreign: it goes back where git runs it.
+  if (kinds.get("pre-commit") === "ownership" && removed.includes("pre-commit") && names.includes(FOREIGN_PRE_COMMIT) && kinds.get(FOREIGN_PRE_COMMIT) === null) {
+    try { ops.rename(path.join(dir, FOREIGN_PRE_COMMIT), path.join(dir, "pre-commit")); restored.push("pre-commit"); } catch { /* left where it is, still foreign */ }
+  }
+  let left = names.filter((name) => !removed.includes(name));
+  if (restored.length) left = [...left.filter((name) => name !== FOREIGN_PRE_COMMIT), "pre-commit"].sort();
+  let removedDir = false;
+  if (removeEmptyDir && removed.length && !left.length) { try { ops.rmdir(dir); removedDir = true; } catch { /* not empty after all */ } }
+  return { found: true, removed, restored, remaining: left, removedDir };
+}