@rightkit/release 0.6.10 → 0.6.11

package/snapshot.mjs

@@ -363,15 +363,66 @@ export function dependencyDirs(entries, platform = process.platform) {
  * carries every later checkout edit into the build, with bytes that may still equal the commit's). Hard links inside the
  * dependency directories are pnpm's own store links; their bytes are bound by the environment digest instead. Never follows a link
  * to enter it. Returns a message naming the path, or null.
+ *
+ * The stage-output ledger (item 5 row 5.09d; signed/item7-sage-decisions-2.md Q1). Given `ledger` and/or `admitNew`, the walk does not
+ * refuse the first path the commit lacks: it collects every such path as a candidate entry and admits it only when ALL hold:
+ *   - it is untracked (not in `entries`) and ignored by the COMMIT'S OWN ignore rules, judged by the neutral oracle (neutralIgnored:
+ *     `git check-ignore --no-index` against an empty bare GIT_DIR with core.excludesFile at the null device, so neither the checkout's
+ *     info/exclude nor any global excludes file widens what is ignored; probe P4);
+ *   - it is a regular file or a directory, never a link of any kind, and a file has nlink 1;
+ *   - no path segment is `target`, `.right-release`, `.git` or `node_modules` (outside the pnpm roots, which are not candidates),
+ *     and it is not named `.gitignore` (an untracked ignore file would make the oracle ignore whatever it names).
+ * `ledger` (an array of `{ path, type, size, sha256, execBit }` recorded by an earlier verify) must still match exactly, byte for byte,
+ * and none of its entries may be missing (an absent directory that only parents ledger files is implied by them). `admitNew` (end of a
+ * stage only) additionally admits candidates the ledger does not hold. Without `admitNew`, a candidate outside the ledger is refused,
+ * so the start of a stage stays as strict as the sync. In this mode the result is `{ problem, admitted }`, `admitted` being every
+ * admitted entry (ledger and new), sorted by path; otherwise it is the message or null as before.
  */
-export function snapshotProblem({ dir, entries, checkout, platform = process.platform, originUrl }) {
+export function snapshotProblem(options) {
+  const r = inspectSnapshot(options);
+  return options.ledger !== undefined || options.admitNew ? r : r.problem;
+}
+
+const RESERVED_SEGMENTS = new Set(["target", ".right-release", ".git", "node_modules"]);
+
+/**
+ * Which of `paths` (relative, `/`-separated, existing under `dir`) the snapshot's own ignore rules ignore, and nothing else: the
+ * sealed runner (snapshot-git.mjs) gives an empty info/exclude and an empty private file for core.excludesFile (never a null device,
+ * so Windows needs no `NUL`), and `--no-index` so only the work tree's `.gitignore` files count. Returns a Set of the ignored paths as given.
+ */
+export function neutralIgnored(dir, paths) {
+  if (!paths.length) return new Set();
+  return withSealedGit({ snapshot: dir }, (git) => {
+    const r = git.run(["check-ignore", "--no-index", "-z", "--stdin"], { input: `${paths.join("\0")}\0` });
+    if (r.error) throw new SnapshotError("error", `git check-ignore: ${r.error.message}`);
+    // Exit 0: some path is ignored; 1: none is; anything else is git failing, which must never read as "not ignored" or "ignored".
+    if (r.status !== 0 && r.status !== 1) throw new SnapshotError("error", `git check-ignore: ${String(r.stderr).trim() || `exit ${r.status}`}`);
+    return new Set(String(r.stdout ?? "").split("\0").filter(Boolean));
+  });
+}
+
+/** sha256 of a file, read in chunks (a staged sidecar can be large). */
+function sha256File(file) {
+  const h = crypto.createHash("sha256");
+  const fd = fs.openSync(file, "r");
+  try {
+    const buf = Buffer.allocUnsafe(1 << 20);
+    for (let n; (n = fs.readSync(fd, buf, 0, buf.length, null)) > 0;) h.update(buf.subarray(0, n));
+  } finally { fs.closeSync(fd); }
+  return h.digest("hex");
+}
+
+function inspectSnapshot({ dir, entries, checkout, platform = process.platform, originUrl, ledger, admitNew = false }) {
+  const problem = (message) => ({ problem: message, admitted: [] });
+  const ledgerMode = ledger !== undefined || admitNew === true;
   const fold = foldFor(platform);
+  const candidates = [];
   const byKey = new Map(entries.map((e) => [fold(e.path), e]));
   const dirs = new Set();
   for (const e of entries) { const parts = e.path.split("/"); for (let i = 1; i < parts.length; i++) dirs.add(fold(parts.slice(0, i).join("/"))); }
   const deps = dependencyDirs(entries, platform);
   let realDir; let realCheckout = checkout;
-  try { realDir = fs.realpathSync.native(dir); } catch (e) { return `${dir} cannot be resolved: ${e.message}`; }
+  try { realDir = fs.realpathSync.native(dir); } catch (e) { return problem(`${dir} cannot be resolved: ${e.message}`); }
   try { realCheckout = fs.realpathSync.native(checkout); } catch { /* the path as given */ }
   const linkProblem = (rel, p) => {
     let real;
@@ -416,6 +467,38 @@ export function snapshotProblem({ dir, entries, checkout, platform = process.pla
     }
     return null;
   };
+  // Ledger mode: a path the commit lacks is a candidate. Everything about it that does not need git is decided here; whether the
+  // commit's own rules ignore it is decided for all candidates at once afterwards (neutralIgnored).
+  const reserved = (rel) => {
+    const parts = rel.split("/").map(fold);
+    const bad = parts.find((x) => RESERVED_SEGMENTS.has(x));
+    if (bad !== undefined) return `${rel} is under ${JSON.stringify(bad)}, a reserved path no stage output may occupy (target/ is the checkout's output directory, .right-release holds right-release's, .git is the gate's config-only file, node_modules is allowed only as the pnpm roots' installed dependencies)`;
+    if (fold(parts.at(-1)) === ".gitignore") return `${rel} is an ignore file the commit does not have: an untracked .gitignore would decide what counts as ignored`;
+    return null;
+  };
+  const candidate = (p, rel) => {
+    const bad = reserved(rel);
+    if (bad) return bad;
+    const s = lstat(p);
+    if (!s) return `${rel} vanished while it was checked`;
+    if (s.isSymbolicLink()) return `${rel} is a link: a link is never admitted to the stage-output ledger`;
+    if (!s.isFile()) return `${rel} is not a regular file or a directory`;
+    if (s.nlink > 1n) return `${rel} has ${s.nlink} hard links: a checkout edit made through another name for it would reach the build`;
+    candidates.push({ path: rel, type: "file", size: Number(s.size), sha256: sha256File(p), execBit: platform !== "win32" && (Number(s.mode) & 0o111) !== 0 });
+    return null;
+  };
+  const candidateDir = (p, rel) => {
+    const bad = reserved(rel);
+    if (bad) return bad;
+    candidates.push({ path: rel, type: "dir", size: 0, sha256: null, execBit: false });
+    for (const e of fs.readdirSync(p, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+      const r = `${rel}/${e.name}`;
+      const q = path.join(p, e.name);
+      const found = e.isSymbolicLink() ? `${r} is a link: a link is never admitted to the stage-output ledger` : e.isDirectory() ? candidateDir(q, r) : candidate(q, r);
+      if (found) return found;
+    }
+    return null;
+  };
   const walk = (d, rel, inDeps) => {
     const names = fs.readdirSync(d, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
     for (const e of names) {
@@ -426,19 +509,42 @@ export function snapshotProblem({ dir, entries, checkout, platform = process.pla
       if (e.isSymbolicLink()) {
         // The landing is named first when it is the worse news (into the checkout, out of the snapshot); a link the commit lacks is refused either way.
         found = linkProblem(r, p);
-        if (!found && !inDeps) found = !byKey.has(key) ? `${r} is not in the commit's tree (a link the commit does not have)` : fileProblem(r, p, byKey.get(key));
+        if (!found && !inDeps) found = !byKey.has(key) ? (ledgerMode ? `${r} is a link the commit does not have: a link is never admitted to the stage-output ledger` : `${r} is not in the commit's tree (a link the commit does not have)`) : fileProblem(r, p, byKey.get(key));
       } else if (e.isDirectory()) {
         if (inDeps) found = walk(p, r, true);
         else if (deps.has(key)) found = walk(p, r, true);
         else if (dirs.has(key)) found = walk(p, r, false);
         else if (key === ".git") found = gitConfigProblem(r, p);
-        else found = `${r} is not in the commit's tree (a directory the commit does not have)`;
-      } else if (!inDeps) found = !byKey.has(key) ? `${r} is not in the commit's tree` : fileProblem(r, p, byKey.get(key));
+        else found = ledgerMode ? candidateDir(p, r) : `${r} is not in the commit's tree (a directory the commit does not have)`;
+      } else if (!inDeps) found = !byKey.has(key) ? (ledgerMode ? candidate(p, r) : `${r} is not in the commit's tree`) : fileProblem(r, p, byKey.get(key));
       if (found) return found;
     }
     return null;
   };
-  return walk(dir, "", false);
+  const found = walk(dir, "", false);
+  if (found || !ledgerMode) return { problem: found, admitted: [] };
+
+  // The ledger's entries, keyed like the walk's, must all be here and byte-identical; anything else the walk met is new.
+  const held = new Map((ledger ?? []).map((e) => [fold(e.path), e]));
+  const seen = new Map(candidates.map((c) => [fold(c.path), c]));
+  for (const [key, want] of held) {
+    const have = seen.get(key);
+    if (!have) return problem(`${want.path} is a ledger entry (recorded at the end of an earlier stage) and is missing`);
+    if (have.type !== want.type || have.size !== want.size || have.sha256 !== want.sha256 || have.execBit !== want.execBit) {
+      return problem(`${want.path} is a ledger entry and changed since it was recorded (${want.type} ${want.size} bytes sha256 ${want.sha256}${want.execBit ? " executable" : ""} was recorded; ${have.type} ${have.size} bytes sha256 ${have.sha256}${have.execBit ? " executable" : ""} is here)`);
+    }
+  }
+  // A directory that only parents ledger entries is implied by them; any other candidate must be admitted as new.
+  const parents = new Set();
+  for (const e of held.values()) { const parts = e.path.split("/"); for (let i = 1; i < parts.length; i++) parents.add(fold(parts.slice(0, i).join("/"))); }
+  for (const c of candidates) {
+    const key = fold(c.path);
+    if (!held.has(key) && !(c.type === "dir" && parents.has(key)) && !admitNew) return problem(`${c.path} is not in the commit's tree and not in the stage-output ledger (new stage outputs are admitted only at the end of a stage)`);
+  }
+  // Every candidate, ledger or new, must be ignored by the commit's own rules, as the neutral oracle judges them.
+  const ignored = neutralIgnored(dir, candidates.map((c) => c.path));
+  for (const c of candidates) if (!ignored.has(c.path)) return problem(`${c.path} is not in the commit's tree and is not ignored by the commit's own ignore rules (the checkout's info/exclude and global excludes do not count)`);
+  return { problem: null, admitted: [...candidates].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)) };
 }
 
 function blobId(content, objectFormat) {
@@ -775,8 +881,14 @@ export function syncSnapshot({ checkout, rev = "HEAD", root = snapshotRoot(), ma
  * digest (the caller supplies it: the digest is the gate's, bin/rightkit-gate.mjs classAEnvironmentDigest); a difference is a
  * mismatch, so dependency bytes changed or planted mid-stage refuse at the end verify. Callers run this at the start and again at
  * the end of a stage (the stage-level calls are item 7, 7.08). `managedRoot` and `device` as for syncSnapshot.
+ *
+ * Stage-output ledger (row 5.09d, snapshotProblem): `ledger` is the array of entries an earlier verify returned (the start of a stage
+ * passes the whole ledger and no `admitNew`: nothing new, nothing changed, nothing missing); `admitNew: true` (the END of a stage
+ * only) also admits the ignored, untracked, regular-file-or-directory outputs the stage's children wrote. Either option makes the
+ * result carry `ledger: [{ path, type, size, sha256, execBit }]`, every admitted entry. The tree id is still the commit's tree:
+ * an ignored output does not change it. With neither option nothing beyond the commit (and 5.09's allowances) is accepted.
  */
-export function verifySnapshot({ checkout, rev = "HEAD", root = snapshotRoot(), dir, managedRoot = hostManagedRootFor(root), device, environment } = {}) {
+export function verifySnapshot({ checkout, rev = "HEAD", root = snapshotRoot(), dir, managedRoot = hostManagedRootFor(root), device, environment, ledger, admitNew } = {}) {
   const repo = repositoryOf(checkout);
   const { commit, tree } = resolveCommit(repo.checkout, rev);
   if (managedRoot) requireManagedRoot(managedRoot, { device });
@@ -785,8 +897,9 @@ export function verifySnapshot({ checkout, rev = "HEAD", root = snapshotRoot(),
   if (path.resolve(path.dirname(at)) === path.resolve(root)) requirePrivateRoot(root, lstat(root));
   if (!lstat(at)?.isDirectory()) throw new SnapshotError("mismatch", `no snapshot directory at ${at}`);
   // The seeded tree id cannot see an ignored file or follow a link, so the directory itself is walked first (E6, §1 exact snapshot).
-  const extra = snapshotProblem({ dir: at, entries: treeEntries(repo.checkout, commit), checkout: repo.checkout });
-  if (extra) throw new SnapshotError("mismatch", `the snapshot at ${at} is not exactly commit ${commit}: ${extra}`);
+  const inspected = snapshotProblem({ dir: at, entries: treeEntries(repo.checkout, commit), checkout: repo.checkout, ledger, admitNew });
+  const extra = ledger !== undefined || admitNew ? inspected.problem : inspected;
+  if (extra) throw new SnapshotError("mismatch", `the snapshot at ${at} is not exactly commit ${commit}${ledger !== undefined || admitNew ? " plus its stage-output ledger" : ""}: ${extra}`);
   const actual = snapshotTree({ checkout: repo.checkout, dir: at, baseTree: tree, repo });
   if (actual !== tree) throw new SnapshotError("mismatch", `the snapshot at ${at} is tree ${actual}, not tree ${tree} of commit ${commit}`);
   if (environment !== undefined) {
@@ -796,7 +909,7 @@ export function verifySnapshot({ checkout, rev = "HEAD", root = snapshotRoot(),
     catch (e) { throw new SnapshotError("error", `the environment digest of the snapshot at ${at} cannot be computed: ${e.message}`); }
     if (now !== environment.expected) throw new SnapshotError("mismatch", `the installed environment of the snapshot at ${at} changed: env=${now}, recorded env=${environment.expected}`);
   }
-  return { schema: SNAPSHOT_SCHEMA, path: at, repoKey: repo.key, commit, tree, ...(environment !== undefined ? { env: environment.expected } : {}) };
+  return { schema: SNAPSHOT_SCHEMA, path: at, repoKey: repo.key, commit, tree, ...(environment !== undefined ? { env: environment.expected } : {}), ...(ledger !== undefined || admitNew ? { ledger: inspected.admitted } : {}) };
 }
 
 /**

package/source-split.mjs

@@ -0,0 +1,73 @@
+// The right-release source split (docs/GATE-CONTRACT.md "Commit-only build"; item 7 rows 7.03 to 7.05).
+//
+// Under the commit-only build the gate selects a commit, syncs it into a gate-owned snapshot and runs every stage from there. A
+// right-release child the door starts for a stage (dev, test, stage-sidecar) therefore runs with its cwd inside the SNAPSHOT: its
+// sources, its config and every command it spawns resolve there. What stays with the CHECKOUT is the git context the door run was
+// made in (the run file, the primary-checkout rule, the commit's object database) and every output or cache right-release owns
+// (`.right-release/...`).
+//
+// The split is never taken from a flag or from the child's own idea of the repository. The door writes it into its live run file
+// (gate-stages.mjs startRun `source`) and names the checkout in RK_GATE_CHECKOUT; this module re-reads the run file, requires the
+// run alive, and requires the process to sit inside the snapshot that run names. Anything inconsistent throws (fail closed): a
+// child told it is split that cannot prove it never builds from where it stands.
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "./background-process.mjs";
+import { CHECKOUT_ENV, readDoorRun } from "./gate-stages.mjs";
+
+export { CHECKOUT_ENV };
+export const SOURCE_SPLIT_CODE = "RK_SOURCE_SPLIT";
+export const SOURCE_SPLIT_UNSUPPORTED = "RK_SOURCE_SPLIT_UNSUPPORTED";
+
+export class SourceSplitError extends Error {
+  constructor(message, code = SOURCE_SPLIT_CODE) { super(message); this.name = "SourceSplitError"; this.code = code; }
+}
+
+const real = (p) => { try { return fs.realpathSync.native(p); } catch { return path.resolve(p); } };
+const fold = (p) => (process.platform === "win32" || process.platform === "darwin" ? p.toLowerCase() : p);
+const contains = (parent, child) => { const rel = path.relative(fold(real(parent)), fold(real(child))); return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel)); };
+
+/**
+ * The split this process runs under, or null when RK_GATE_CHECKOUT is not set (the checkout route: hosted CI, or no door).
+ * Throws SourceSplitError when it is set and anything about it cannot be proven. `run` runs git (tests inject a double).
+ */
+export function readSourceSplit({ env = process.env, cwd = process.cwd(), run = spawnSync, readFile, alive } = {}) {
+  const named = env[CHECKOUT_ENV];
+  if (named === undefined || named === "") return null;
+  if (!path.isAbsolute(named)) throw new SourceSplitError(`${CHECKOUT_ENV} must be an absolute path (got ${JSON.stringify(named)})`);
+  const common = run("git", ["rev-parse", "--git-common-dir"], { cwd: named, encoding: "utf8", windowsHide: true });
+  if (common.status !== 0 || !String(common.stdout).trim()) throw new SourceSplitError(`${CHECKOUT_ENV} ${named} is not a git checkout`);
+  const commonDir = path.resolve(named, String(common.stdout).trim());
+  const found = readDoorRun({ env, commonDir, ...(readFile ? { readFile } : {}), ...(alive ? { alive } : {}) });
+  if (found.problem) throw new SourceSplitError(`no live door run ${found.problem === "ended" ? "(it has ended)" : "(RK_GATE_RUN names none)"} under ${named}; a source split exists only inside one`);
+  const source = found.run.source;
+  if (!source || typeof source !== "object") throw new SourceSplitError("the live door run carries no source split");
+  for (const key of ["checkout", "snapshot"]) if (typeof source[key] !== "string" || !path.isAbsolute(source[key])) throw new SourceSplitError(`the door run's source.${key} is not an absolute path`);
+  for (const key of ["commit", "tree"]) if (!/^[0-9a-f]{40}([0-9a-f]{24})?$/.test(source[key] ?? "")) throw new SourceSplitError(`the door run's source.${key} is not an object id`);
+  if (typeof source.appDir !== "string" || source.appDir.startsWith("/") || source.appDir.split("/").includes("..") || source.appDir.includes("\\")) throw new SourceSplitError("the door run's source.appDir is not a contained relative path");
+  if (real(source.checkout) !== real(named)) throw new SourceSplitError(`the door run was made in ${source.checkout}, not in ${named}`);
+  if (found.run.commit !== source.commit) throw new SourceSplitError("the door run's commit and its source split's commit differ");
+  const appRoot = source.appDir === "." ? source.snapshot : path.join(source.snapshot, ...source.appDir.split("/"));
+  if (!contains(source.snapshot, cwd)) throw new SourceSplitError(`this process runs in ${cwd}, outside the snapshot ${source.snapshot} its door run names; a split child runs only inside the snapshot`);
+  return Object.freeze({
+    checkout: source.checkout, snapshot: source.snapshot, commit: source.commit, tree: source.tree, appDir: source.appDir, commonDir,
+    appRoot, checkoutAppRoot: source.appDir === "." ? source.checkout : path.join(source.checkout, ...source.appDir.split("/")),
+    stage: found.run.stage,
+  });
+}
+
+/** Whether `file` lies inside the split's snapshot. */
+export const inSnapshot = (split, file) => contains(split.snapshot, file);
+
+/**
+ * The git context a door-checked step needs: `{ commonDir, commit }` of the live run for a split process, else of the git
+ * repository at `cwd` (HEAD), else null. door.mjs, web-build and the right-release CLI ask the same question, so they share it.
+ */
+export function doorContextFor({ cwd = process.cwd(), env = process.env, run = spawnSync } = {}) {
+  const split = readSourceSplit({ env, cwd, run });
+  if (split) return { commonDir: split.commonDir, commit: split.commit, split };
+  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 null;
+  return { commonDir: path.resolve(cwd, common), commit: git(["rev-parse", "HEAD"]), split: null };
+}

package/stage-commands.mjs

@@ -4,7 +4,7 @@
 // a signed receipt of its own job; a missing command is a refusal that names it.
 import path from "node:path";
 import { CARGO_METADATA_ARGS, cargoPackageArgs, localTestPlan, npmPackArgs, qualifyFmtArgs } from "./local-publish.mjs";
-import { SWAP_HELPER_CARGO_ARGS, SWAP_HELPER_PACKAGE } from "./swap-helper-bundle.mjs";
+import { SWAP_HELPER_CARGO_ARGS, SWAP_HELPER_METADATA_ARGS, SWAP_HELPER_PACKAGE } from "./swap-helper-bundle.mjs";
 
 /** Stands for the one argument that is a fresh absolute scratch path (`pnpm pack --pack-destination <mkdtemp>`). */
 export const ANY_ABSOLUTE_PATH = Object.freeze({ anyAbsolutePath: true });
@@ -27,7 +27,7 @@ export function expectedStageCommands({ kind, unit, config, manifest, platform }
   if (kind === "npm") {
     if (unit === SWAP_HELPER_PACKAGE) {
       // The swap helper builds and signs a binary, then packs from a scratch copy of its directory.
-      pack.push(CARGO(SWAP_HELPER_CARGO_ARGS), CARGO(["metadata", "--format-version", "1", "--no-deps"]), PNPM(npmPackArgs(ANY_ABSOLUTE_PATH, ANY_ABSOLUTE_PATH)));
+      pack.push(CARGO(SWAP_HELPER_CARGO_ARGS), CARGO(SWAP_HELPER_METADATA_ARGS), PNPM(npmPackArgs(ANY_ABSOLUTE_PATH, ANY_ABSOLUTE_PATH)));
     } else pack.push(PNPM(npmPackArgs(dir, ANY_ABSOLUTE_PATH)));
   } else {
     compile.unshift(CARGO(qualifyFmtArgs(unit)));

package/stage-ledger.mjs

@@ -0,0 +1,204 @@
+// The stage-output ledger (docs/GATE-CONTRACT.md "Commit-only build"; item 7 decision 2, question 1, rows 7.05/7.05b/7.07/7.08).
+//
+// A real build writes into the directory it builds from: Tauri's `gen/schemas`, staged sidecars, a frontend `dist`. The snapshot is
+// exactly the commit's tree (plus the gate's installed dependencies) at the start of every stage; what a stage's own children write
+// during it may remain at the stage's end only as LEDGER ENTRIES, each of which must be:
+//   1. not tracked (not in `ls-tree <commit>`) and ignored by the commit's own ignore rules, judged with an empty bare GIT_DIR and a null
+//      core.excludesFile, so neither the checkout's `info/exclude` nor a global excludes file ever widens what is ignored;
+//   2. a regular file (a directory only as the parent of one), never a link, and with exactly one hard link;
+//   3. never under a reserved path: a `target` segment, `.right-release`, `.git`, or a `node_modules` outside the gate's own dependency roots;
+//   4. recorded by THIS walk, never by a child: the ledger lives in the door's memory and in the door receipt under the checkout's git
+//      common directory, never inside the snapshot (GC:162).
+// This module only walks, classifies and compares. The exact-snapshot verify is snapshot.mjs verifySnapshot, which takes the ledger.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "./background-process.mjs";
+
+export const LEDGER_RESERVED_SEGMENTS = Object.freeze(["target", ".right-release", ".git", "node_modules"]);
+export const NULL_DEVICE = process.platform === "win32" ? "NUL" : "/dev/null";
+
+const fold = (platform = process.platform) => (platform === "darwin" || platform === "win32" ? (s) => s.toLowerCase() : (s) => s);
+
+/** The comparable form of an entry: what the next stage's start verify must find unchanged. */
+export const entryKey = (e) => `${e.path}\0${e.type}\0${e.size}\0${e.sha256}\0${e.execBit ? 1 : 0}`;
+
+/** A clean env for the git calls below: nothing of the caller's GIT_* and no global or system configuration. */
+function gitEnv(env = process.env) {
+  const clean = Object.fromEntries(Object.entries(env).filter(([k]) => !/^GIT_/i.test(k)));
+  return { ...clean, GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: NULL_DEVICE, GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0" };
+}
+
+/**
+ * Which of `paths` (posix, relative to `dir`) the commit's own ignore rules ignore: `git check-ignore --no-index` run with an empty
+ * bare GIT_DIR, the snapshot as the work tree and a null core.excludesFile, so only the snapshot's own `.gitignore` files apply.
+ * Throws when git cannot answer (the caller fails closed).
+ */
+export function neutralIgnored({ dir, paths, run = spawnSync, env = process.env }) {
+  if (!paths.length) return new Set();
+  const bare = fs.mkdtempSync(path.join(os.tmpdir(), "rk-ignore-oracle-"));
+  try {
+    const made = run("git", ["init", "--bare", "-q", "--template=", bare], { encoding: "utf8", env: gitEnv(env), windowsHide: true });
+    if (made.error || made.status !== 0) throw new Error(`cannot create the empty git directory for the ignore check: ${made.error?.message ?? String(made.stderr).trim()}`);
+    const r = run("git", [`--git-dir=${bare}`, `--work-tree=${dir}`, "-c", `core.excludesFile=${NULL_DEVICE}`, "check-ignore", "--no-index", "-z", "--stdin"], {
+      cwd: dir, input: `${paths.join("\0")}\0`, encoding: "utf8", env: gitEnv(env), windowsHide: true, maxBuffer: 1 << 28,
+    });
+    // 0: some path is ignored; 1: none is; anything else is git failing.
+    if (r.error || (r.status !== 0 && r.status !== 1)) throw new Error(`git check-ignore failed (${r.error?.message ?? `exit ${r.status}: ${String(r.stderr).trim()}`})`);
+    return new Set(String(r.stdout ?? "").split("\0").filter(Boolean));
+  } finally { fs.rmSync(bare, { recursive: true, force: true }); }
+}
+
+/**
+ * Walks `dir` and returns what it holds beyond the commit: `{ entries, problems }`. `tracked` is the set of every path in
+ * `ls-tree <commit>` (posix); `dependencyRoots` the `node_modules` directories the gate installed under 5.09a (posix, relative; their
+ * bytes are bound by the class A environment digest, not here). `entries` are admissible ledger entries; `problems` name every write
+ * that cannot be one (not ignored, a link, a hard link, reserved, an empty directory, a `.git` holding more than the gate's config).
+ */
+export function walkSnapshot({ dir, tracked, dependencyRoots = new Set(), run = spawnSync, env = process.env, platform = process.platform }) {
+  const f = fold(platform);
+  const trackedFolded = new Set([...tracked].map(f));
+  const trackedDirs = new Set();
+  for (const p of tracked) { const parts = f(p).split("/"); for (let i = 1; i < parts.length; i++) trackedDirs.add(parts.slice(0, i).join("/")); }
+  const deps = new Set([...dependencyRoots].map(f));
+  const candidates = []; const problems = [];
+  const reserved = (rel) => rel.split("/").find((seg) => LEDGER_RESERVED_SEGMENTS.includes(f(seg)));
+  const walk = (abs, rel) => {
+    let names;
+    try { names = fs.readdirSync(abs, { withFileTypes: true }); } catch (e) { problems.push(`${rel || "."} cannot be read: ${e.message}`); return; }
+    names.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    let any = false;
+    for (const d of names) {
+      const r = rel ? `${rel}/${d.name}` : d.name;
+      const key = f(r);
+      const p = path.join(abs, d.name);
+      if (deps.has(key)) continue;
+      any = true;
+      if (key === ".git" && rel === "") {
+        // 5.09b: only the gate's config-only origin file; its exact bytes are item 5's to verify.
+        let inner = [];
+        try { inner = fs.readdirSync(p); } catch { /* reported below */ }
+        if (inner.length !== 1 || inner[0] !== "config") problems.push(`${r} holds more than the gate's config-only file (.git is reserved)`);
+        continue;
+      }
+      let st;
+      try { st = fs.lstatSync(p); } catch (e) { problems.push(`${r} cannot be read: ${e.message}`); continue; }
+      if (st.isSymbolicLink()) { if (!trackedFolded.has(key)) problems.push(`${r} is a link the commit does not have (a stage output is never a link)`); continue; }
+      if (st.isDirectory()) {
+        if (trackedDirs.has(key)) { walk(p, r); continue; }
+        const bad = reserved(r);
+        if (bad) { problems.push(`${r} is under the reserved path segment ${JSON.stringify(bad)} (a stage output is never written there)`); continue; }
+        const before = candidates.length + problems.length;
+        walk(p, r);
+        if (candidates.length + problems.length === before) problems.push(`${r} is an empty directory the commit does not have`);
+        continue;
+      }
+      if (!st.isFile()) { problems.push(`${r} is neither a regular file nor a directory`); continue; }
+      if (trackedFolded.has(key)) continue; // a tracked file: its bytes are verifySnapshot's
+      const bad = reserved(r);
+      if (bad) { problems.push(`${r} is under the reserved path segment ${JSON.stringify(bad)} (a stage output is never written there)`); continue; }
+      if (st.nlink > 1) { problems.push(`${r} has ${st.nlink} hard links (a stage output has exactly one)`); continue; }
+      candidates.push({ rel: r, abs: p, size: st.size, execBit: platform !== "win32" && (st.mode & 0o111) !== 0 });
+    }
+    return any;
+  };
+  walk(dir, "");
+  let ignored;
+  try { ignored = neutralIgnored({ dir, paths: candidates.map((c) => c.rel), run, env }); }
+  catch (e) { return { entries: [], problems: [...problems, `the ignore rules of the commit could not be evaluated: ${e.message}`] }; }
+  const ignoredFolded = new Set([...ignored].map(f));
+  const entries = [];
+  for (const c of candidates) {
+    // A split package stage writes a declared root output (a DMG, an updater tarball) into the snapshot as a generated entry (row 7.04c R-T2 rule 5): it must be
+    // ignored by the commit itself, so the message names the declared fields such an output comes from and the fix.
+    if (!ignoredFolded.has(f(c.rel))) { problems.push(`${c.rel} is not ignored by the commit's own ignore rules (the checkout's info/exclude and global excludes never count); if the release config declares it (updater.artifacts[].file, installer.artifacts[].file, notarize.file, artifacts[] or a postSign output), add ${c.rel} to the commit's .gitignore`); continue; }
+    let bytes;
+    try { bytes = fs.readFileSync(c.abs); } catch (e) { problems.push(`${c.rel} cannot be read: ${e.message}`); continue; }
+    entries.push({ path: c.rel, type: "file", size: bytes.length, sha256: crypto.createHash("sha256").update(bytes).digest("hex"), execBit: c.execBit });
+  }
+  entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return { entries, problems };
+}
+
+/** What changed between two entry lists: `{ added, changed, removed }` as paths. */
+export function diffEntries(before, after) {
+  const b = new Map(before.map((e) => [e.path, e])); const a = new Map(after.map((e) => [e.path, e]));
+  return {
+    added: [...a.keys()].filter((p) => !b.has(p)),
+    changed: [...a.keys()].filter((p) => b.has(p) && entryKey(b.get(p)) !== entryKey(a.get(p))),
+    removed: [...b.keys()].filter((p) => !a.has(p)),
+  };
+}
+
+export const sameEntries = (x, y) => { const d = diffEntries(x, y); return !d.added.length && !d.changed.length && !d.removed.length; };
+
+/**
+ * The attribution diff of a staging step: every path the step added must be one it reported (or its receipt), and every path it
+ * reported must exist. Anything else is an unattributed write. `reported` and `receipt` are snapshot-relative posix paths.
+ */
+export function attributionProblems({ before, after, reported, receipt }) {
+  const d = diffEntries(before, after);
+  const allowed = new Set([...reported, ...(receipt ? [receipt] : [])]);
+  const problems = [];
+  for (const p of [...d.added, ...d.changed]) if (!allowed.has(p)) problems.push(`${p} was written by the staging step but it did not report it`);
+  for (const p of d.removed) problems.push(`${p} was removed by the staging step`);
+  const present = new Set(after.map((e) => e.path));
+  for (const p of allowed) if (!present.has(p)) problems.push(`${p} was reported by the staging step but is not in the snapshot as a ledger entry`);
+  return problems;
+}
+
+/** Every `path` string a staging receipt or its `--json` result carries (files, their notices), app-relative. */
+export function reportedPaths(result) {
+  const out = new Set();
+  const visit = (v) => {
+    if (Array.isArray(v)) { v.forEach(visit); return; }
+    if (v && typeof v === "object") { for (const [k, x] of Object.entries(v)) { if (k === "path" && typeof x === "string") out.add(x.replaceAll("\\", "/")); else visit(x); } }
+  };
+  visit(result?.files ?? []);
+  return out;
+}
+
+/**
+ * The cross-check with `.rightkit/compile-inputs.json` (decision 2, Q1): for each declared input that covers ledger entries, the digest
+ * the compile receipt names must equal the gate's own digest of those bytes (compile-inputs.mjs judgeCompileInputs, the broker's
+ * algorithm). Returns problems; `judge` is judgeCompileInputs.
+ */
+export function declaredInputProblems({ snapshot, entries, receiptDigests, judge }) {
+  const judged = judge(snapshot);
+  const problems = judged.findings.map((x) => `declared compile input: ${x}`);
+  const named = new Map((receiptDigests ?? []).map((d) => [d.path, d.sha256]));
+  for (const input of judged.inputs) {
+    const covers = entries.some((e) => e.path === input.path || e.path.startsWith(`${input.path}/`));
+    if (!covers) continue;
+    if (!named.has(input.path)) problems.push(`declared compile input ${input.path} covers ledger entries but the receipt carries no digest for it`);
+    else if (named.get(input.path) !== input.sha256) problems.push(`declared compile input ${input.path}: the receipt's digest ${named.get(input.path)} differs from the gate's digest ${input.sha256} of the ledger bytes`);
+  }
+  return problems;
+}
+
+/**
+ * Whether the entries the snapshot verify admitted (snapshot.mjs verifySnapshot / snapshot-check.mjs verifySnapshotDir with a ledger,
+ * row 5.09d) agree with the entries this gate's own walk recorded. The verify's `admitted` lists FILES and the DIRECTORIES that parent them
+ * (`type: "dir"`); the walk records files only (a directory is implied by its files). They agree when the admitted files are exactly the
+ * walk's files (same path, size, digest and exec bit when the verify names them) and every admitted directory parents one of them.
+ * Returns a message naming the first disagreement, or null.
+ */
+export function admittedMismatch(admitted, entries) {
+  const files = admitted.filter((e) => (e.type ?? "file") !== "dir");
+  const dirs = admitted.filter((e) => e.type === "dir");
+  const mine = new Map(entries.map((e) => [e.path, e])); const theirs = new Map(files.map((e) => [e.path, e]));
+  for (const p of mine.keys()) if (!theirs.has(p)) return `${p} is in the door's walk but the verify did not admit it`;
+  for (const p of theirs.keys()) if (!mine.has(p)) return `${p} was admitted by the verify but the door's walk did not record it`;
+  for (const [p, e] of theirs) {
+    const w = mine.get(p);
+    if (e.sha256 !== undefined && (e.sha256 !== w.sha256 || e.size !== w.size || Boolean(e.execBit) !== Boolean(w.execBit))) return `${p} differs between the verify's entry and the door's walk`;
+  }
+  const parents = new Set();
+  for (const p of mine.keys()) { const parts = p.split("/"); for (let i = 1; i < parts.length; i++) parents.add(parts.slice(0, i).join("/")); }
+  for (const d of dirs) if (!parents.has(d.path)) return `the directory ${d.path} was admitted by the verify but parents no ledger entry`;
+  return null;
+}
+
+/** The receipt form of the ledger: no absolute path, no bytes. */
+export const receiptLedger = (entries) => entries.map((e) => ({ path: e.path, kind: e.kind, type: e.type, size: e.size, sha256: e.sha256, execBit: e.execBit, producer: e.producer }));

package/stage-sidecar-command.mjs

@@ -6,6 +6,7 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { defaultReleaseConfigFile, importReleaseConfig } from "./release-config.mjs";
 import { planSidecarStaging, resolveTargetTriple, stageSidecars } from "./stage-sidecar.mjs";
+import { readSourceSplit } from "./source-split.mjs";
 
 export function parseStageSidecarArgs(argv, cwd = process.cwd()) {
   const opts = { config: defaultReleaseConfigFile(cwd), target: undefined, json: false, check: false };
@@ -50,6 +51,9 @@ async function main() {
   const opts = parseStageSidecarArgs(process.argv.slice(2));
   const configPath = path.resolve(opts.config);
   const appRoot = path.dirname(configPath);
+  // Inside the door's source split the config and every declared source are the snapshot's; the caches and build trees right-release
+  // owns stay in the checkout's app directory (stage-sidecar.mjs `cacheRoot`).
+  const split = readSourceSplit({ cwd: appRoot });
   const config = await importReleaseConfig(configPath, { lenient: true });
   if (config?.sidecars === undefined) throw new Error(`${opts.config} declares no sidecars`);
   if (opts.check) {
@@ -61,7 +65,7 @@ async function main() {
   }
   const target = resolveTargetTriple({ target: opts.target, cwd: appRoot });
   // Warnings (a never-run row, a catalog row that is not staged) go to stderr; stdout stays the staged-file list or the --json document.
-  const result = await stageSidecars({ appRoot, manifest: config.sidecars, target, deps: { warn: (line) => console.error(line) } });
+  const result = await stageSidecars({ appRoot, manifest: config.sidecars, target, ...(split ? { cacheRoot: split.checkoutAppRoot } : {}), deps: { warn: (line) => console.error(line) } });
   if (opts.json) console.log(JSON.stringify(result, null, 2));
   else {
     for (const file of result.files ?? []) console.log(`right-release stage-sidecar: staged ${typeof file === "string" ? file : file.path ?? JSON.stringify(file)}`);