@rightkit/release 0.6.10 → 0.6.12

package/stage-sidecar.mjs

@@ -665,8 +665,8 @@ async function defaultFetchBytes(url) {
 /** Absolute catalog file for a validated spec. Crate resolution reads the rightkit metadata listing; npm walks up node_modules. */
 function resolveCatalogFile(spec, ctx, kind) {
   const label = kind === "ffmpeg" ? "rightkit-ffmpeg" : "native-libraries";
-  if (spec.via === "absolute") return spec.file;
-  if (spec.via === "path") return path.resolve(ctx.appRoot, spec.file);
+  if (spec.via === "absolute") return requireSnapshotSource(ctx, spec.file, `the ${label} catalog`);
+  if (spec.via === "path") return requireSnapshotSource(ctx, path.resolve(ctx.appRoot, spec.file), `the ${label} catalog`);
   if (spec.via === "crate") {
     const meta = ctx.run("rustright", ["cargo", "metadata", "--format-version", "1"], { cwd: ctx.appRoot, env: ctx.env });
     let packages;
@@ -751,6 +751,23 @@ function cleanDest(ctx, entry, dest, { directory = false } = {}) {
   try { ctx.fs.rmSync(dest, { recursive: directory, force: true }); } catch (error) { fail("STAGE_SIDECAR_CLEAN_REFUSED", `cannot clean ${dest} (${error.message}); a directory is only removed for a directory resource`, { dest, cause: error }); }
 }
 
+/**
+ * Warm-cache rule (GATE-CONTRACT "rebuild only what changed"): a staged file carries the mtime of the cache file it was copied from, a
+ * lipo or merge output the newest mtime of its inputs, so a re-stage after the snapshot sync (which removes every ledger entry) does not
+ * bump the mtime and re-trigger the app crate (tauri-build emits rerun-if-changed for the staged sidecar). Bytes are bound by the
+ * ledger, never by mtime. A file system without `utimesSync` or `statSync().mtime` (a test double) is left as written.
+ */
+function carryMtime(ctx, dest, sources) {
+  const { fs } = ctx;
+  if (typeof fs.utimesSync !== "function") return;
+  let newest = null;
+  for (const source of sources) {
+    let st; try { st = fs.statSync(source); } catch { continue; }
+    if (st?.mtime instanceof Date && (!newest || st.mtime > newest)) newest = st.mtime;
+  }
+  if (newest) { try { fs.utimesSync(dest, newest, newest); } catch { /* the mtime is a cache hint, never a binding */ } }
+}
+
 function copyInto(ctx, source, dest, { executable }) {
   const { fs, windows } = ctx;
   const sourceSha256 = sha256Of(fs.readFileSync(source));
@@ -765,11 +782,44 @@ function copyInto(ctx, source, dest, { executable }) {
   } else if (executable && !windows) fs.chmodSync(dest, 0o755);
   const sha256 = sha256Of(fs.readFileSync(dest));
   if (sha256 !== sourceSha256) fail("STAGE_SIDECAR_HASH_MISMATCH", `staged ${dest} differs from its source ${source}`, { expected: sourceSha256, actual: sha256 });
+  carryMtime(ctx, dest, [source]);
   return { sha256, sizeBytes: fs.statSync(dest).size, changed };
 }
 
 const rel = (ctx, file) => path.relative(ctx.appRoot, file).replaceAll("\\", "/");
 
+/**
+ * The boundary of a split run (row 7.05a): the only checkout bytes it may read are cache entries whose digest the commit pins or
+ * tool-invalidated build caches, both under `ctx.cacheRoot`. A SOURCE the config names (a local `source.dir`, an ffmpeg `path`) must
+ * resolve inside the snapshot's app root, never into the checkout or anywhere else.
+ */
+function requireSnapshotSource(ctx, file, label) {
+  if (!ctx.split) return file;
+  const relative = path.relative(ctx.appRoot, path.resolve(file));
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) fail("STAGE_SIDECAR_SOURCE_OUTSIDE_SNAPSHOT", `${label} resolves to ${file}, outside the snapshot's app root ${ctx.appRoot}; a split run reads sources only from the snapshot (checkout bytes enter only as digest-pinned cache entries)`, { file });
+  return file;
+}
+/**
+ * The environment a split run hands to the commands it starts (a `command` entry, an ffmpeg `stage` command): Cargo's output directory is
+ * the checkout's, resolved there once and passed absolute, so a command that reaches Cargo (`rustright cargo run -p ...`) never writes
+ * `target/` into the snapshot. Without a split, or when the checkout holds no Cargo workspace, the environment is returned as it is.
+ */
+function splitCommandEnv(ctx) {
+  if (!ctx.split) return ctx.env;
+  if (ctx.splitEnv === undefined) {
+    const resolved = ctx.run("rustright", ["cargo", "metadata", "--format-version", "1", "--no-deps"], { cwd: ctx.cacheRoot, env: ctx.env });
+    let dir;
+    try { dir = JSON.parse(resolved?.stdout).target_directory; } catch { /* no workspace in the checkout: nothing to pin */ }
+    ctx.splitEnv = !resolved?.error && resolved?.status === 0 && typeof dir === "string" && path.isAbsolute(dir) ? { ...ctx.env, CARGO_TARGET_DIR: path.resolve(dir) } : ctx.env;
+  }
+  return ctx.splitEnv;
+}
+
+/** A cache directory the config names (`cacheDir`): the checkout's `.right-release` under a split, the app root otherwise. */
+const cacheDirFor = (ctx, dir) => (ctx.split ? path.resolve(ctx.cacheRoot, ".right-release", dir) : path.resolve(ctx.appRoot, dir));
+/** The per-arch slice directory of a universal staging: absolute under the checkout's cache root on a split, app-relative otherwise. */
+const sliceDirFor = (ctx, triple) => (ctx.split ? path.resolve(ctx.cacheRoot, SLICE_ROOT, triple) : `${SLICE_ROOT}/${triple}`);
+
 /** `lipo -archs <file>` as a list; a failing lipo is a typed error. */
 function lipoArchs(ctx, file) {
   const result = ctx.run("lipo", ["-archs", file], { cwd: ctx.appRoot, env: ctx.env });
@@ -804,6 +854,7 @@ function lipoMergeInto(ctx, slices, dest, label, { executable = false } = {}) {
     fs.rmSync(temporary, { force: true });
     if (executable) fs.chmodSync(dest, 0o755);
   }
+  carryMtime(ctx, dest, slices);
   return { sha256, sizeBytes: fs.statSync(dest).size, changed };
 }
 
@@ -834,6 +885,7 @@ function stageCargoBin(entry, ctx) {
   const changed = !(fs.existsSync(dest) && sha256Of(fs.readFileSync(dest)) === sha256);
   fs.chmodSync(temporary, 0o755);
   fs.renameSync(temporary, dest);
+  carryMtime(ctx, dest, slices.map((slice) => slice.source));
   return [{ kind: "cargo-bin", name: entry.name, path: rel(ctx, dest), sha256, sizeBytes: fs.statSync(dest).size, changed, sourceSha256: sha256, package: entry.package, bin: entry.bin, profile: entry.profile, features: entry.features, externalBin: !entry.dest, slices: slices.map((slice) => ({ triple: slice.triple, sha256: slice.sourceSha256 })) }];
 }
 
@@ -851,17 +903,29 @@ function stageCargoBuild(entry, ctx, triple) {
     "-p", entry.package, "--bin", entry.bin, "--target", triple, "--profile", entry.profile,
     ...(entry.features.length ? ["--features", entry.features.join(",")] : []), "--message-format=json-render-diagnostics"];
   ctx.log(`stage-sidecar: rightkit ${args.join(" ")}`);
-  const built = run("rustright", args, { cwd: appRoot, env });
+  // From a snapshot, Cargo would resolve `target/` (or a relative build.target-dir) against the snapshot: its output directory is
+  // resolved in the checkout instead and passed as an absolute CARGO_TARGET_DIR, so the warm outputs stay the checkout's and the
+  // snapshot holds no target/ (docs/GATE-CONTRACT.md "Output directory & cache").
+  let buildEnv = env;
+  if (ctx.split) {
+    const checkoutManifest = entry.manifestPath ? ["--manifest-path", path.resolve(ctx.cacheRoot, entry.manifestPath)] : [];
+    const resolved = run("rustright", ["cargo", "metadata", "--format-version", "1", "--no-deps", ...checkoutManifest], { cwd: ctx.cacheRoot, env });
+    let pinned;
+    try { pinned = JSON.parse(resolved?.stdout).target_directory; } catch { /* refused below */ }
+    if (resolved?.error || resolved?.status !== 0 || typeof pinned !== "string" || !path.isAbsolute(pinned)) fail("STAGE_SIDECAR_BUILD_FAILED", `the checkout's cargo output directory for ${entry.package} cannot be resolved (${resolved?.error?.message ?? `exit ${resolved?.status}`}); nothing was built`, { package: entry.package });
+    buildEnv = { ...env, CARGO_TARGET_DIR: path.resolve(pinned) };
+  }
+  const built = run("rustright", args, { cwd: appRoot, env: buildEnv });
   if (built?.error || built?.status !== 0) fail("STAGE_SIDECAR_BUILD_FAILED", `rustright cargo build of ${entry.package} failed (${built?.error?.message ?? `exit ${built?.status}`})`, { package: entry.package, stderr: tail(built?.stderr) });
   let source = artifactFromStream(built.stdout, entry.bin);
   if (!source || !fs.existsSync(source)) {
-    const meta = run("rustright", ["cargo", "metadata", "--format-version", "1", "--no-deps", ...(entry.manifestPath ? ["--manifest-path", path.resolve(appRoot, entry.manifestPath)] : [])], { cwd: appRoot, env });
+    const meta = run("rustright", ["cargo", "metadata", "--format-version", "1", "--no-deps", ...(entry.manifestPath ? ["--manifest-path", path.resolve(appRoot, entry.manifestPath)] : [])], { cwd: appRoot, env: buildEnv });
     let targetDir;
     try { targetDir = JSON.parse(meta.stdout).target_directory; } catch { /* refused below */ }
     if (meta?.status !== 0 || typeof targetDir !== "string" || !path.isAbsolute(targetDir)) targetDir = undefined;
     // A managed target root: the broker/cargo metadata target_directory (which cargo derives from CARGO_TARGET_DIR) is
     // authoritative; an explicit CARGO_TARGET_DIR in this environment is tried too, resolved against the app root.
-    const envDir = typeof env.CARGO_TARGET_DIR === "string" && env.CARGO_TARGET_DIR.trim() ? path.resolve(appRoot, env.CARGO_TARGET_DIR) : undefined;
+    const envDir = typeof buildEnv.CARGO_TARGET_DIR === "string" && buildEnv.CARGO_TARGET_DIR.trim() ? path.resolve(appRoot, buildEnv.CARGO_TARGET_DIR) : undefined;
     if (!targetDir && !envDir) fail("STAGE_SIDECAR_BINARY_NOT_FOUND", `cargo reported no ${entry.bin} executable and its target directory cannot be read`, { bin: entry.bin });
     const candidates = builtBinaryCandidates({ targetDir, targetDirs: envDir ? [envDir] : [], triple, profile: entry.profile, bin: entry.bin, windows: ctx.windows });
     source = candidates.find((file) => fs.existsSync(file));
@@ -877,7 +941,7 @@ const ffmpegSourceFor = (sources, tool, arch) => { const spec = sources?.[tool];
 /** The binary a local ffmpeg source names: the file itself, or `<dir>/<member>` / `<dir>/bin/<member>` (`.exe` added for a Windows target). */
 function resolveLocalFfmpegSource(ctx, spec, tool) {
   const { fs } = ctx;
-  const base = path.resolve(ctx.appRoot, spec.path);
+  const base = requireSnapshotSource(ctx, path.resolve(ctx.appRoot, spec.path), `the ffmpeg ${tool} source path`);
   if (fs.existsSync(base) && fs.statSync(base).isFile()) return base;
   const member = spec.member ?? `${tool}${ctx.windows ? ".exe" : ""}`;
   const candidates = [path.join(base, member), path.join(base, "bin", member)];
@@ -955,15 +1019,17 @@ function probeFfmpegBinary(ctx, { file, tool, target }) {
  */
 async function stageFfmpegSlice(entry, ctx, resolved, { config, t, writeNotices, flat = false }) {
   const { appRoot, run, env, fs } = ctx;
-  const planned = planMediaSidecar({ config, catalog: resolved.catalog, crateDir: resolved.crateDir, crateVersion: resolved.crateVersion, catalogBytes: resolved.catalogBytes, root: appRoot });
+  // A universal slice is staged under SLICE_ROOT, which a split keeps in the checkout's cache root, never in the snapshot.
+  const sliceRoot = ctx.split && String(config.stageDir ?? "").startsWith(SLICE_ROOT) ? ctx.cacheRoot : appRoot;
+  const planned = planMediaSidecar({ config, catalog: resolved.catalog, crateDir: resolved.crateDir, crateVersion: resolved.crateVersion, catalogBytes: resolved.catalogBytes, root: sliceRoot });
   const plan = flat ? { ...planned, files: planned.files.map((file) => ({ ...file, stagedPath: path.resolve(appRoot, entry.resourceDir, file.bundledName) })) } : planned;
   await fetchFfmpegSources(entry, ctx, plan, t.arch);
   if (config.stage) {
     const universal = ctx.target.arch === "universal";
     // A universal entry stages once per slice: `{arch}`, `{triple}` and `{stageDir}` in the stage command's arguments name the slice.
-    const args = (config.stage.args ?? []).map((arg) => (universal ? String(arg).replaceAll("{arch}", t.arch).replaceAll("{triple}", t.triple).replaceAll("{stageDir}", config.stageDir) : arg));
+    const args = (config.stage.args ?? []).map((arg) => (universal ? String(arg).replaceAll("{arch}", t.arch).replaceAll("{triple}", t.triple).replaceAll("{stageDir}", sliceRoot === appRoot ? config.stageDir : path.resolve(sliceRoot, config.stageDir)) : arg));
     ctx.log(`stage-sidecar: ${config.stage.cmd} ${args.join(" ")}`);
-    const staged = run(config.stage.cmd, args, { cwd: appRoot, env });
+    const staged = run(config.stage.cmd, args, { cwd: appRoot, env: splitCommandEnv(ctx) });
     if (staged?.error || staged?.status !== 0) fail("STAGE_SIDECAR_BUILD_FAILED", `ffmpeg stage command failed (${staged?.error?.message ?? `exit ${staged?.status}`})`);
   }
   const noticeFiles = writeNotices ? writeMediaSidecarNotices(plan, { exists: fs.existsSync, mkdir: fs.mkdirSync, copy: fs.copyFileSync, write: fs.writeFileSync }) : [];
@@ -987,13 +1053,20 @@ async function stageFfmpegUniversal(entry, ctx, resolved) {
     results.push({ slice, ...(await stageFfmpegSlice(entry, ctx, resolved, { config: slice.media, t: parseTargetTriple(slice.triple), writeNotices: false })) });
   }
   // One notice set and one source offer that names the rows of every slice (a per-slice offer would overwrite the other).
+  // A split plans each slice under the checkout's cache root (SLICE_ROOT), so the slice plans name their notices there too. The notices are FINAL
+  // outputs and belong in the snapshot beside the merged file: they are rebased onto the app root before anything is written, never into the checkout.
+  const toApp = (file) => {
+    if (!ctx.split) return file;
+    const relative = path.relative(ctx.cacheRoot, file);
+    return relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative) ? file : path.resolve(appRoot, relative);
+  };
   const noticeByDest = new Map();
-  for (const { plan } of results) for (const notice of plan.notices) noticeByDest.set(notice.dest, notice);
+  for (const { plan } of results) for (const notice of plan.notices) noticeByDest.set(toApp(notice.dest), { ...notice, dest: toApp(notice.dest) });
   const rowsById = new Map();
   for (const { plan } of results) for (const row of plan.rows) rowsById.set(row.id, row);
   const combined = {
     notices: [...noticeByDest.values()],
-    offerPath: results[0].plan.offerPath,
+    offerPath: toApp(results[0].plan.offerPath),
     offer: sourceOfferText({ rows: [...rowsById.values()], contact: entry.media.notices.sourceOfferContact, crateVersion: resolved.crateVersion }),
   };
   const noticeFiles = writeMediaSidecarNotices(combined, { exists: fs.existsSync, mkdir: fs.mkdirSync, copy: fs.copyFileSync, write: fs.writeFileSync });
@@ -1229,14 +1302,14 @@ async function prepareNativeFile(entry, ctx, loaded, item, { destDir, scratchDir
   if (fs.existsSync(dest) && !nativeDigestMismatch(entry, row, fs.readFileSync(dest), { fromSource: Boolean(entry.source) })) return prepared;
 
   if (entry.source) {
-    const file = path.resolve(appRoot, entry.source.dir, row.artifactFileName);
+    const file = requireSnapshotSource(ctx, path.resolve(appRoot, entry.source.dir, row.artifactFileName), `source.dir of the ${where} row ${row.id}`);
     if (!(fs.existsSync(file) && fs.statSync(file).isFile())) fail("STAGE_SIDECAR_BINARY_NOT_FOUND", `the ${where} row ${row.id} is staged from source.dir ${entry.source.dir}, which has no ${row.artifactFileName} (looked at ${file}); nothing is downloaded for a source dir`, { file });
     const mismatch = nativeDigestMismatch(entry, row, fs.readFileSync(file), { fromSource: true });
     if (mismatch) failNativeMismatch(row, file, mismatch);
     return { ...prepared, from: file };
   }
   if (!row.archive) fail("STAGE_SIDECAR_CONFIG_INVALID", `the ${where} row ${row.id} has no archive, so it is staged from a local build: set source: { dir } on this entry to the directory holding ${row.artifactFileName}`);
-  const archive = path.resolve(appRoot, entry.cacheDir, archiveFileName(row.archive.url));
+  const archive = path.join(cacheDirFor(ctx, entry.cacheDir), archiveFileName(row.archive.url));
   if (!(fs.existsSync(archive) && sha256Of(fs.readFileSync(archive)) === row.archive.sha256)) {
     const bytes = await ctx.fetchBytes(row.archive.url);
     const actual = sha256Of(bytes);
@@ -1378,7 +1451,7 @@ async function stageNativeLibrary(entry, ctx) {
   }
   // Otherwise each arch's files are staged thin under SLICE_ROOT, then merged file by file into the entry's resource directory.
   const slices = [];
-  for (const plan of plans) slices.push({ triple: plan.triple, files: await stageNativeSet(entry, ctx, loaded, plan.items, { destDir: `${SLICE_ROOT}/${plan.triple}` }) });
+  for (const plan of plans) slices.push({ triple: plan.triple, files: await stageNativeSet(entry, ctx, loaded, plan.items, { destDir: sliceDirFor(ctx, plan.triple) }) });
   const [first, second] = slices.map((slice) => slice.files.map((file) => file.outName));
   if ([...first].sort().join("\n") !== [...second].sort().join("\n")) fail("STAGE_SIDECAR_NOT_APPROVED", `the arch rows name different library files (aarch64: ${first.join(", ")}; x86_64: ${second.join(", ")}); each file needs one name on both arches (a single file can be renamed with "as")`);
   return first.map((name) => {
@@ -1446,7 +1519,7 @@ function stageCommand(entry, ctx) {
   const cwd = entry.cwd ? path.resolve(appRoot, entry.cwd) : appRoot;
   cleanDest(ctx, entry, destFor(entry, ctx));
   ctx.log(`stage-sidecar: ${entry.cmd} ${entry.args.join(" ")}`);
-  const built = run(entry.cmd, entry.args, { cwd, env });
+  const built = run(entry.cmd, entry.args, { cwd, env: splitCommandEnv(ctx) });
   if (built?.error || built?.status !== 0) fail("STAGE_SIDECAR_BUILD_FAILED", `command ${entry.name} (${entry.cmd}) failed (${built?.error?.message ?? `exit ${built?.status}`})`, { name: entry.name, stderr: tail(built?.stderr) });
   const source = path.resolve(appRoot, entry.output);
   if (!fs.existsSync(source) || !fs.statSync(source).isFile()) fail("STAGE_SIDECAR_BINARY_NOT_FOUND", `command ${entry.name} did not produce ${entry.output}`, { name: entry.name, output: entry.output });
@@ -1463,8 +1536,8 @@ function stageCommand(entry, ctx) {
  * fails closed with nothing staged. Returns { cached, fromCache }.
  */
 async function ensureCachedDownload(ctx, { url, sha256, size }) {
-  const { appRoot, fs } = ctx;
-  const cached = path.resolve(appRoot, REMOTE_CACHE_DIR, sha256);
+  const { fs } = ctx;
+  const cached = path.resolve(ctx.cacheRoot, REMOTE_CACHE_DIR, sha256);
   if (fs.existsSync(cached) && sha256Of(fs.readFileSync(cached)) === sha256) return { cached, fromCache: true };
   ctx.log(`stage-sidecar: GET ${url}`);
   let response;
@@ -1596,7 +1669,7 @@ function stageCmake(entry, ctx) {
   const { appRoot, fs, run, env, target } = ctx;
   const cmake = resolveCmakeBinary(ctx, entry);
   const generator = entry.platformGenerators?.[target.platform] ?? entry.generator;
-  const root = path.resolve(appRoot, CMAKE_ROOT, entry.name);
+  const root = path.resolve(ctx.cacheRoot, CMAKE_ROOT, entry.name);
   const srcDir = path.join(root, "src");
   const buildDir = path.join(root, "build");
   const dest = destFor(entry, ctx);
@@ -1783,15 +1856,22 @@ export function planSidecarStaging({ manifest, target, env = process.env } = {})
  * fs (existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, renameSync, chmodSync, statSync, readdirSync, rmSync), run, fetch (https downloads of `remote`), fetchBytes, extractMember, loadMediaCatalog, loadNativeCatalog, makeTempDir, removeDir, now, pid, log (progress), warn (warnings; defaults to log), env.
  * The API is quiet by default; the `right-release stage-sidecar` command passes `warn` so the CLI prints warnings on stderr.
  */
-export async function stageSidecars({ appRoot, manifest, target, deps = {} } = {}) {
+export async function stageSidecars({ appRoot, manifest, target, cacheRoot, deps = {} } = {}) {
   if (typeof appRoot !== "string" || !path.isAbsolute(appRoot)) fail("STAGE_SIDECAR_CONFIG_INVALID", "appRoot must be an absolute path");
+  if (cacheRoot !== undefined && (typeof cacheRoot !== "string" || !path.isAbsolute(cacheRoot))) fail("STAGE_SIDECAR_CONFIG_INVALID", "cacheRoot must be an absolute path");
   const env = deps.env ?? process.env;
   const plan = validateSidecarManifest(manifest, { target, mode: resolveBuildMode(env) });
   assertNotNested(plan, env);
+  // A source split (source-split.mjs; rightkit-gate's snapshot route): `appRoot` is the snapshot of the commit, where the declared
+  // sources are read and where the staged files and the receipt go (the Tauri build script reads them there). `cacheRoot` is the
+  // checkout's app directory, which keeps every cache, archive, slice and build tree right-release owns (`.right-release/...`) and
+  // where Cargo's target directory is resolved: only final outputs and the receipt are written under the snapshot (row 7.05a). Checkout
+  // bytes enter a split run only as cache entries whose digest the commit pins, or as tool-invalidated build caches.
+  const split = cacheRoot !== undefined && path.resolve(cacheRoot) !== path.resolve(appRoot);
   const fs = deps.fs ?? nodeFs;
   const run = deps.run ?? defaultRun;
   const ctx = {
-    appRoot, target: plan.target, stageDir: plan.stageDir, fs, env, run, protectedPaths: protectedOutputPaths(plan),
+    appRoot, cacheRoot: split ? path.resolve(cacheRoot) : appRoot, split, target: plan.target, stageDir: plan.stageDir, fs, env, run, protectedPaths: protectedOutputPaths(plan),
     windows: plan.target.os === "windows",
     pid: deps.pid ?? process.pid,
     host: deps.host ?? { os: { darwin: "macos", win32: "windows", linux: "linux" }[process.platform] ?? process.platform, arch: { arm64: "aarch64", x64: "x86_64" }[process.arch] ?? process.arch },

package/swap-helper-bundle.mjs

@@ -18,7 +18,10 @@ export const SWAP_HELPER_PACKAGE = "@rightkit/release";
 export const SWAP_HELPER_BIN = ["bin", "darwin", "rightkit-swap"];
 export const SWAP_HELPER_RECEIPT = ["bin", "darwin", "rightkit-swap.sign.json"];
 // rightkit-swap is gated on the crate feature "fs" (crates/rightkit-fs/Cargo.toml [[bin]] required-features).
-export const SWAP_HELPER_CARGO_ARGS = ["build", "--release", "-p", "rightkit-fs", "--features", "fs", "--bin", "rightkit-swap"];
+// Every crate is its own Cargo workspace (rightkit#1285): there is no root manifest, so the build and the target-directory read name crates/rightkit-fs.
+export const SWAP_HELPER_MANIFEST = "crates/rightkit-fs/Cargo.toml";
+export const SWAP_HELPER_CARGO_ARGS = ["build", "--manifest-path", SWAP_HELPER_MANIFEST, "--release", "-p", "rightkit-fs", "--features", "fs", "--bin", "rightkit-swap"];
+export const SWAP_HELPER_METADATA_ARGS = ["metadata", "--format-version", "1", "--no-deps", "--manifest-path", SWAP_HELPER_MANIFEST];
 
 /** Typed error. Codes: SWAP_HELPER_BUILD_FAILED, SWAP_HELPER_SIGN_FAILED, SWAP_HELPER_MISSING, SWAP_HELPER_UNSIGNED. */
 export class SwapHelperError extends Error {
@@ -67,7 +70,7 @@ export function prepareSwapHelper({
   const fail = (code, message) => { throw new SwapHelperError(code, message); };
   const built = run("cargo", SWAP_HELPER_CARGO_ARGS, { cwd: workspaceRoot, env });
   if (built.error || built.status !== 0) fail("SWAP_HELPER_BUILD_FAILED", `rustright cargo ${SWAP_HELPER_CARGO_ARGS.join(" ")} failed (${built.error?.message ?? `exit ${built.status}`})\n${tail(`${built.stdout ?? ""}\n${built.stderr ?? ""}`)}`);
-  const meta = run("cargo", ["metadata", "--format-version", "1", "--no-deps"], { cwd: workspaceRoot, env });
+  const meta = run("cargo", SWAP_HELPER_METADATA_ARGS, { cwd: workspaceRoot, env });
   let targetDir;
   try { targetDir = JSON.parse(meta.stdout).target_directory; } catch { /* refused below */ }
   if (meta.status !== 0 || typeof targetDir !== "string" || !path.isAbsolute(targetDir)) fail("SWAP_HELPER_BUILD_FAILED", "cannot read the Cargo target directory to find rightkit-swap");

package/unit-gate.mjs

@@ -183,12 +183,52 @@ export function resolveUnit(selector, root, { granted = localBuildGranted, readJ
   return { kind, name, version: manifest.version };
 }
 
+/** `ci/known-red.json` hosts by `process.platform`; any other platform (Linux) has no known-red table. */
+const KNOWN_RED_HOST = { darwin: "macos", win32: "windows" };
+
+/**
+ * The ci/known-red.json entry that bars this unit from a compile, or null. A unit listed for the host platform is not compiled,
+ * packaged or qualified there; one that is headed to release is barred when it is listed for either host (a known-red unit is never
+ * published, AGENTS.md; scripts/ci/publish.mjs refuses it the same way). An entry is keyed by the crate name or `rust:<crate>`, the
+ * unit's directory or `npm:<directory>` (the ids scripts/ci/gate.mjs and publish.mjs use). A missing file lists nothing; an unreadable
+ * one refuses (a table that cannot be read is not an empty table).
+ */
+export function knownRedEntry({ unit, root, platform, toRelease = false, readText = (file) => fs.readFileSync(file, "utf8") }) {
+  let table;
+  try { table = JSON.parse(readText(path.join(root, "ci", "known-red.json"))); }
+  catch (error) { if (error?.code === "ENOENT") return null; throw new Error(`ci/known-red.json cannot be read (${error?.message}); a known-red table that cannot be read is not an empty one`); }
+  const dir = unit.kind === "npm" ? `packages/${unit.name.slice("@rightkit/".length)}` : `crates/${unit.name}`;
+  const keys = [unit.name, `rust:${unit.name}`, `${unit.kind}:${unit.name}`, dir, `npm:${dir}`];
+  const hosts = toRelease ? Object.keys(table ?? {}) : [KNOWN_RED_HOST[platform]].filter(Boolean);
+  for (const host of hosts) {
+    const key = keys.find((k) => Object.hasOwn(table?.[host] ?? {}, k));
+    if (key !== undefined) {
+      const reason = table[host][key];
+      return { host, key, reason: typeof reason === "string" ? reason : JSON.stringify(reason) };
+    }
+  }
+  return null;
+}
+
 /** One invocation reruns all owed stages; reports are never read as admission evidence. */
-export async function runUnitGate({ selector, to, root, commonDir, commit, tree, executor, env, platform, check, loadOwner = () => import("./local-publish.mjs"), out = console.log, err = console.error, releaser = null, resolve = resolveUnit, writeReport, fetchReceipt = readBrokerReceipt, stageCommands = defaultStageCommands }) {
+/**
+ * `source` ({ checkout, commit, tree }) marks a run built from the door's snapshot of that commit (row 7.06a): `root` is then the
+ * snapshot, `commonDir` the checkout's, and the stages take their identity from the selection (local-publish.mjs sourceGit). `stageGuard`
+ * ({ start(stage), end(stage) } returning true or false) is the door's ledger verify around each stage (7.08); `envExtra` carries the
+ * Cargo output pin. Without `source` every behavior is the checkout route's, unchanged.
+ */
+export async function runUnitGate({ selector, to, root, commonDir, commit, tree, executor, env, platform, check, source = null, stageGuard = null, envExtra = {}, loadOwner = () => import("./local-publish.mjs"), out = console.log, err = console.error, releaser = null, resolve = resolveUnit, writeReport, fetchReceipt = readBrokerReceipt, stageCommands = defaultStageCommands, readKnownRed }) {
   const stages = stagesTo(to);
   if (!stages) { err(`rightkit-gate: invalid unit stage ${to}`); return 2; }
   let unit;
   try { unit = resolve(selector, root); } catch (error) { err(`rightkit-gate: BLOCKED: ${error.message}`); return 1; }
+  // Before any compile (so --to compile|package|qualify|release; --to check compiles nothing): a unit recorded red is refused, not built.
+  if (stages.includes("compile")) {
+    try {
+      const red = knownRedEntry({ unit, root, platform, toRelease: stages.includes("release"), ...(readKnownRed ? { readText: readKnownRed } : {}) });
+      if (red) { err(`rightkit-gate: BLOCKED: ${selector} is listed in ci/known-red.json for ${red.host} (${red.key}: ${red.reason}); a known-red unit is not compiled, packaged, qualified or published. Fix the defect and remove the entry first`); return 1; }
+    } catch (error) { err(`rightkit-gate: BLOCKED: ${error.message}`); return 1; }
+  }
   const scratch = platform === "win32" ? "D:\\scratch" : "/Volumes/D/scratch";
   const bundle = path.join(scratch, `rk-unit-${randomBytes(12).toString("hex")}`);
   const argv = ["--local", unit.kind === "npm" ? "--package" : "--crate", unit.name, "--workspace", root, "--qualify-only", "--bundle", bundle];
@@ -204,7 +244,7 @@ export async function runUnitGate({ selector, to, root, commonDir, commit, tree,
   const stageEnv = async (stage, action) => {
     const run = startRun({ commonDir, commit, tree, stage });
     const nonce = attested && ATTESTED_STAGES.includes(stage) ? { RIGHTKIT_ATTEST_NONCE: qualificationNonce({ commit, tree, unit: `${unit.kind}:${unit.name}`, stage }) } : {};
-    try { return await action({ ...env, ...nonce, ...run.env }); } finally { endRun(run); }
+    try { return await action({ ...env, ...envExtra, ...nonce, ...run.env }); } finally { endRun(run); }
   };
   const receipts = {};
   const collectReceipts = (stage, ids) => {
@@ -222,11 +262,12 @@ export async function runUnitGate({ selector, to, root, commonDir, commit, tree,
   try {
     for (const stage of stages) {
       currentStage = stage;
+      if (stageGuard && !(await stageGuard.start(stage))) throw new Error(`RK_CHECK_ERROR: the snapshot is not the commit's bytes plus the ledger before the ${stage} stage`);
       // A unit run headed to qualify or release owes the release tier: it runs here, before the compile, and qualify does not run it again.
       if (stage === "check") { checkTier = stages.includes("qualify") ? "release" : "compile"; if (await check(checkTier) !== 0) throw new Error(`class A check (${checkTier} tier) failed`); }
       else if (stage === "compile") {
         owner = await loadOwner();
-        state = await stageEnv(stage, (runEnv) => owner.compileLocalUnit(unit.kind, argv, { env: runEnv }));
+        state = await stageEnv(stage, (runEnv) => owner.compileLocalUnit(unit.kind, argv, { env: runEnv, ...(source ? { source } : {}) }));
         collectReceipts(stage, owner.localUnitCompileRequests?.(state));
       } else if (stage === "package") {
         artifact = await stageEnv(stage, (runEnv) => owner.packageLocalUnit(state, { env: runEnv }));
@@ -246,6 +287,7 @@ export async function runUnitGate({ selector, to, root, commonDir, commit, tree,
         const qualification = writeQualification({ report, artifact, unit, commit, tree, runtime, executor });
         released = await stageEnv(stage, (runEnv) => (releaser ?? releaseUnit)({ unit, root, commit, executor, env: runEnv, artifact, qualification, platform, out }));
       }
+      if (stageGuard && !(await stageGuard.end(stage))) throw new Error(`RK_CHECK_ERROR: the ${stage} stage's result covers no known bytes (a snapshot byte changed, or a write is outside the ledger)`);
       report.stages[stage] = { ok: true, ...(stage === "package" || stage === "qualify" ? { artifactFile: artifact.artifactFile, artifactSha256: artifact.artifactSha256 } : {}), ...(receipts[stage] ? { receipts: receipts[stage] } : {}), ...(released ?? {}) };
       save();
       out(`rightkit-gate: [${stage}] ${unit.kind}:${unit.name} passed`);

package/web-build.mjs

@@ -23,6 +23,7 @@ import { buildLaunch } from "./build-launch.mjs";
 import { CommandSpecError, loadAppConfig, resolveInvocation, validateStep } from "./command-spec.mjs";
 import { defaultReleaseConfigFile } from "./release-config.mjs";
 import { requireDoorRun } from "./gate-stages.mjs";
+import { doorContextFor } from "./source-split.mjs";
 
 export function parseWebBuildArgs(argv) {
   const opts = { config: defaultReleaseConfigFile(), dryRun: false };
@@ -53,10 +54,11 @@ export function planWebBuild(config) {
  * bound to a commit: refused. `spawnSyncFn` runs git; `requireDoor` is gate-stages.mjs requireDoorRun.
  */
 export function webBuildDoorRefusal({ appRoot, env = process.env, spawnSyncFn = spawnSync, requireDoor = requireDoorRun }) {
-  const gitOut = (a) => { const r = spawnSyncFn("git", a, { cwd: appRoot, encoding: "utf8" }); return r.status === 0 ? String(r.stdout).trim() : ""; };
-  const common = gitOut(["rev-parse", "--git-common-dir"]);
-  if (!common) return "right-release web-build runs only inside a git repository, under a door run";
-  return requireDoor({ env, commonDir: path.resolve(appRoot, common), commit: gitOut(["rev-parse", "HEAD"]), command: "right-release web-build" });
+  // Inside a source split (the door's snapshot of a commit) the git context is the door run's checkout and commit, not the cwd's.
+  let context;
+  try { context = doorContextFor({ cwd: appRoot, env, run: spawnSyncFn }); } catch (error) { return `right-release web-build: ${error.code ?? "RK_SOURCE_SPLIT"}: ${error.message}`; }
+  if (!context) return "right-release web-build runs only inside a git repository, under a door run";
+  return requireDoor({ env, commonDir: context.commonDir, commit: context.commit, command: "right-release web-build" });
 }
 
 function doorError(refusal) { const error = new Error(refusal); error.code = "RK_DOOR"; return error; }

package/win-package-recipe.mjs

@@ -20,6 +20,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "./background-process.mjs";
 import { verifyNsisEmbeddedBinary } from "./nsis-payload.mjs";
+import { resolveArtifactPath, splitArtifactContext } from "./release-artifact-path.mjs";
 import { signingReceiptPath } from "./signing-receipts.mjs";
 import { patchTauriBundleType } from "./tauri-bundle-marker.mjs";
 
@@ -198,7 +199,9 @@ export function defaultWinPackageDeps({ appRoot, target, env }) {
 }
 
 /** Where a produced artifact really is: the declared path, else the managed artifact directory (same rule as release.mjs). */
-function locate(declared, { env, fs }) {
+function locate(declared, { env, fs, split = false }) {
+  // A door split (row 7.04c, R-T2): the declared path is already the bound target's; there is no artifact-directory fallback for it.
+  if (split) return declared;
   if (fs.existsSync(declared)) return declared;
   const managed = env.RIGHT_RELEASE_ARTIFACT_DIR;
   if (managed) {
@@ -219,6 +222,15 @@ export function runWinPackageRecipe({ appRoot, config = {}, target, deps = {} }
   const base = defaultWinPackageDeps({ appRoot: plan.appRoot, target, env });
   const d = { ...base, ...deps, env, fs: { ...base.fs, ...(deps.fs ?? {}) } };
   const { fs } = d;
+  // A door split has no target directory in its snapshot: the plan's `<app>/src-tauri/target/...` paths mean the bound target (R-T1, R-T3), where the
+  // raw EXE is deleted before the build, signed in place, bundled and verified. Outside a split this is the identity.
+  const artifactPaths = d.artifactPaths ?? splitArtifactContext({ cwd: plan.appRoot, env, target });
+  const split = artifactPaths.mode === "split";
+  const placed = (declared) => {
+    if (!split) return declared;
+    const relative = path.relative(plan.appRoot, declared).replaceAll("\\", "/");
+    return resolveArtifactPath(relative.startsWith("..") || path.isAbsolute(relative) ? declared : relative, artifactPaths);
+  };
   const dry = d.dryRun === true;
   const phases = [];
   const phase = (name, work) => {
@@ -244,15 +256,16 @@ export function runWinPackageRecipe({ appRoot, config = {}, target, deps = {} }
 
   if (d.platform !== "win32" && !dry) throw new WinPackageRecipeError("build", `the Windows package recipe must run on Windows, not ${d.platform}`);
 
-  let raw = plan.rawExe;
+  const rawExe = placed(plan.rawExe);
+  let raw = rawExe;
   const sidecars = [...plan.sidecars];
 
   phase("build", () => {
-    if (!dry) fs.rmSync(plan.rawExe, { force: true });
+    if (!dry) fs.rmSync(rawExe, { force: true });
     tauri(["build", "--no-bundle", "--target", plan.triple], quiet);
     if (dry) return;
-    raw = locate(plan.rawExe, { env, fs });
-    if (!fs.existsSync(raw)) throw new Error(`tauri build did not produce the raw EXE: ${plan.rawExe}`);
+    raw = locate(rawExe, { env, fs, split });
+    if (!fs.existsSync(raw)) throw new Error(`tauri build did not produce the raw EXE: ${rawExe}`);
     for (const sidecar of sidecars) if (!fs.existsSync(sidecar)) throw new Error(`declared sidecar does not exist: ${sidecar}`);
   });
 
@@ -270,14 +283,14 @@ export function runWinPackageRecipe({ appRoot, config = {}, target, deps = {} }
     return { sha256: byFile.get(path.resolve(raw).toLowerCase()), sidecars: Object.fromEntries(sidecars.map((file) => [file, byFile.get(path.resolve(file).toLowerCase())])) };
   });
 
-  const installerBase = plan.installerFile;
+  const installerBase = placed(plan.installerFile);
   let installer = installerBase;
   phase("bundle", () => {
     if (!dry) for (const stale of [installerBase, `${installerBase}.sig`, `${installerBase}.zip`, `${installerBase}.zip.sig`]) fs.rmSync(stale, { force: true });
     const override = { bundle: { createUpdaterArtifacts: false, windows: { nsis: { installMode: plan.perMachine ? "perMachine" : "currentUser" } } } };
     tauri(["bundle", "--bundles", "nsis", "--target", plan.triple, "--config", JSON.stringify(override)], quiet);
     if (dry) return;
-    installer = locate(installerBase, { env, fs });
+    installer = locate(installerBase, { env, fs, split });
     if (!fs.existsSync(installer)) throw new Error(`tauri bundle did not produce the installer: ${installerBase}`);
   });