@rightkit/release 0.6.10 → 0.6.12

package/release-artifact-path.mjs

@@ -0,0 +1,341 @@
+// One resolver for every declared artifact path (item 7 row 7.04c; signed/item7-sage-decisions-3.md R-T1 to R-T5; docs/GATE-CONTRACT.md
+// "Commit-only build" and "Output directory & cache").
+//
+// A release config names its outputs relative to the app: `src-tauri/target/release/bundle/...`, a root `App.dmg`. Checkout mode reaches
+// them through the app root (and the managed artifact directory), exactly as it always did. A door split has no `target/` in its
+// snapshot (a link into the editable checkout is refused, GC:24, and a copy is the rightkit#924 bridge), so the same declared path must
+// mean the Cargo target the gate bound for that manifest. This module is the one place that decides which:
+//
+//   checkout  today's `resolveReleaseArtifactPath`, byte for byte: `<app root>/<declared>` when it exists, else
+//             `RIGHT_RELEASE_ARTIFACT_DIR/<basename>` when that exists, else `<app root>/<declared>`.
+//   split     R-T2:
+//     1. A relative path starting with a target prefix maps to `<bound target>/<rest>`. No fallback to the snapshot, the checkout or the artifact directory.
+//     2. An absolute path is accepted only inside a bound target or inside RIGHT_RELEASE_ARTIFACT_DIR (realpath; case-folded on Windows).
+//        Anything else is RK_SPLIT_TARGET_PATH, a path into the editable checkout other than its bound target included.
+//     3. A relative path with a `..` segment is refused.
+//     4. Any other relative path resolves to `<snapshot app root>/P` when it exists, then `RIGHT_RELEASE_ARTIFACT_DIR/<basename>` when
+//        that exists, else `<snapshot app root>/P`. It never resolves to the checkout app root: a stale DMG left in the editable checkout
+//        must never be sealed.
+//     5. Outputs written under rule 4 into the snapshot are Q1 `generated` ledger entries (stage-ledger.mjs); the door refuses a
+//        non-ignored one at the end of the stage.
+//
+// The bound target of a Cargo manifest is `resolveTargetRoot(<snapshot manifest>)` (cargo-target.mjs, the published resolver), resolved
+// once. On Linux it equals the absolute CARGO_TARGET_DIR the gate resolved in the checkout and passed (row 7.09); on Mac and Dell it is the
+// snapshot carrier's answer. A manifest whose target cannot be resolved is RK_SPLIT_TARGET_UNRESOLVED: there is never a snapshot-relative
+// `target/` fallback (R7). The door cross-checks the recorded targets against its own resolution (RK_SPLIT_TARGET_DRIFT).
+import { existsSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveTargetRoot as cargoResolveTargetRoot } from "./cargo-target.mjs";
+import { expandRecipeBuildCommands } from "./recipe-build.mjs";
+import { SourceSplitError, readSourceSplit } from "./source-split.mjs";
+
+export const SPLIT_TARGET_PATH_CODE = "RK_SPLIT_TARGET_PATH";
+export const SPLIT_TARGET_UNRESOLVED_CODE = "RK_SPLIT_TARGET_UNRESOLVED";
+export const SPLIT_TARGET_DRIFT_CODE = "RK_SPLIT_TARGET_DRIFT";
+
+const DEFAULT_MANIFEST = "src-tauri/Cargo.toml";
+const TOOL_ROOT = path.dirname(fileURLToPath(import.meta.url));
+
+/** A declared artifact path or bound target a split refuses. `code` is one of the three codes above. */
+export class ArtifactPathError extends Error {
+  constructor(code, message, problems = []) { super(`${code}: ${message}`); this.name = "ArtifactPathError"; this.code = code; this.problems = problems; }
+}
+
+const posix = (value) => String(value).replaceAll("\\", "/");
+const folded = (value) => (process.platform === "win32" ? value.toLowerCase() : value);
+const isAbsoluteDeclared = (value) => path.isAbsolute(value) || /^[A-Za-z]:[\\/]/.test(value) || /^[\\/]{2}/.test(value);
+
+/** The real path of the deepest existing ancestor of `file`, with the missing tail appended: comparable before the file exists. */
+function canonical(file) {
+  const absolute = path.resolve(file);
+  let head = absolute;
+  const tail = [];
+  for (;;) {
+    try { return folded(path.join(realpathSync.native(head), ...tail.reverse())); } catch { /* not there yet */ }
+    const parent = path.dirname(head);
+    if (parent === head) return folded(absolute);
+    tail.push(path.basename(head));
+    head = parent;
+  }
+}
+
+const insideCanonical = (child, parent) => {
+  const relative = path.relative(parent, child);
+  return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+};
+
+/** True when this process is a child of a door run (`RK_GATE_CHECKOUT` names the checkout): artifacts resolve through the split. */
+export const isSplitArtifactEnv = (env = process.env) => typeof env?.RK_GATE_CHECKOUT === "string" && env.RK_GATE_CHECKOUT !== "";
+
+/** `<dir>/` form, posix, relative: the prefix a declared path starts with. */
+function prefixOf(appRoot, dir) {
+  const relative = posix(path.relative(appRoot, dir)).replace(/\/+$/, "");
+  return relative && relative !== "." && !relative.startsWith("..") ? `${relative}/` : "";
+}
+
+/**
+ * Every Cargo manifest the app declares, with the target prefix its declared paths use (R-T1): the native layout's prefixes, each recipe
+ * `cargoTargetRoot` manifest, and the default `<cargoDir>/target/`. `[{ prefix, manifest }]`, longest prefix first, one row per prefix.
+ */
+export function declaredTargetManifests({ appRoot, nativeLayout = null, target = null, exists = existsSync } = {}) {
+  const rows = [];
+  const add = (prefix, manifest) => { if (prefix && !rows.some((row) => row.prefix === prefix)) rows.push({ prefix, manifest: path.resolve(manifest) }); };
+  if (nativeLayout?.manifestPath) for (const prefix of nativeLayout.targetPrefixes ?? [nativeLayout.targetPrefix]) add(posix(prefix ?? "").replace(/\/*$/, "/").replace(/^\/$/, ""), nativeLayout.manifestPath);
+  // A declarative recipe: `cargoTargetRoot: true` is `<tauriCwd>/src-tauri/Cargo.toml`, a string is an app-relative Cargo.toml.
+  const targets = Array.isArray(target) ? target : [target];
+  for (const spec of targets.flatMap((entry) => [entry?.winPackage, entry?.macPackage])) {
+    if (!spec || typeof spec !== "object") continue;
+    const explicit = spec.cargoTargetRoot;
+    if (explicit !== true && typeof explicit !== "string") continue;
+    const cwd = typeof spec.tauriCwd === "string" && spec.tauriCwd !== "." ? posix(spec.tauriCwd) : "";
+    const manifestRel = typeof explicit === "string" ? posix(explicit) : path.posix.join(cwd, DEFAULT_MANIFEST);
+    const manifest = path.resolve(appRoot, manifestRel);
+    add(prefixOf(appRoot, path.join(path.dirname(manifest), "target")), manifest);
+  }
+  // The historical default: an app with `src-tauri/Cargo.toml` and no declared layout still addresses `src-tauri/target/`.
+  const fallback = path.resolve(appRoot, DEFAULT_MANIFEST);
+  if (!rows.length && exists(fallback)) add("src-tauri/target/", fallback);
+  return rows.sort((left, right) => right.prefix.length - left.prefix.length);
+}
+
+/**
+ * The artifact-path context of this process.
+ *   `{ mode: "checkout", appRoot, artifactDir, env }`                                   (no door run: nothing changes)
+ *   `{ mode: "split", snapshotAppRoot, boundTargets: [{ prefix, manifest, dir }], artifactDir, ... }`
+ * `cwd` is the app root (the snapshot's in a split). `nativeLayout` is resolveNativeCargoLayout's answer (null for a Cargo-less app), `target`
+ * the UNEXPANDED `config.targets[platform]` (the recipe keys are gone after expansion; a list of targets binds each). `resolve: false` skips the Cargo calls (the prefixes
+ * alone, for the command scan). `resolveTargetRoot`, `exists` and `snapshotRoot` are injectable.
+ * Throws ArtifactPathError RK_SPLIT_TARGET_UNRESOLVED when a manifest's target cannot be resolved or resolves inside the snapshot, and
+ * RK_SPLIT_TARGET_DRIFT when it differs from the absolute CARGO_TARGET_DIR the gate handed this process.
+ */
+export function splitArtifactContext({
+  cwd, env = process.env, nativeLayout = null, config = {}, target = null, resolveTargetRoot = cargoResolveTargetRoot,
+  exists = existsSync, snapshotRoot, resolve = true,
+} = {}) {
+  void config;
+  if (!cwd) throw new TypeError("splitArtifactContext requires cwd (the app root)");
+  const appRoot = path.resolve(cwd);
+  const artifactDir = env.RIGHT_RELEASE_ARTIFACT_DIR ? path.resolve(env.RIGHT_RELEASE_ARTIFACT_DIR) : null;
+  if (!isSplitArtifactEnv(env)) return Object.freeze({ mode: "checkout", appRoot, snapshotAppRoot: null, boundTargets: Object.freeze([]), prefixes: Object.freeze([]), artifactDir, env, exists });
+  const declared = declaredTargetManifests({ appRoot, nativeLayout, target, exists });
+  let root = snapshotRoot ? path.resolve(snapshotRoot) : null;
+  if (!root) { try { root = readSourceSplit({ env, cwd: appRoot })?.snapshot ?? null; } catch (error) { if (!(error instanceof SourceSplitError)) throw error; } }
+  const snapshot = canonical(root ?? appRoot);
+  const pinned = typeof env.CARGO_TARGET_DIR === "string" && path.isAbsolute(env.CARGO_TARGET_DIR) ? canonical(env.CARGO_TARGET_DIR) : null;
+  const cache = new Map();
+  const boundTargets = declared.map(({ prefix, manifest }) => {
+    if (!resolve) return Object.freeze({ prefix, manifest, dir: null });
+    if (!cache.has(manifest)) cache.set(manifest, bindManifest({ manifest, appRoot, snapshot, pinned, resolveTargetRoot, exists }));
+    return Object.freeze({ prefix, manifest, dir: cache.get(manifest) });
+  });
+  return Object.freeze({
+    mode: "split", appRoot, snapshotAppRoot: appRoot, snapshotRoot: root ?? appRoot, boundTargets: Object.freeze(boundTargets),
+    prefixes: Object.freeze(declared.map((row) => row.prefix)), artifactDir, env, exists,
+  });
+}
+
+function bindManifest({ manifest, appRoot, snapshot, pinned, resolveTargetRoot, exists }) {
+  if (!exists(manifest)) throw new ArtifactPathError(SPLIT_TARGET_UNRESOLVED_CODE, `the Cargo manifest ${manifest} is not in the snapshot, so its target directory cannot be bound; a split never falls back to a snapshot-relative target/`);
+  let dir;
+  try { dir = resolveTargetRoot(manifest); } catch (error) {
+    throw new ArtifactPathError(SPLIT_TARGET_UNRESOLVED_CODE, `cargo metadata for ${manifest} reported no target directory (${error.message}); a split never falls back to a snapshot-relative target/ (the snapshot carrier must serve cargo metadata for a split child)`);
+  }
+  if (typeof dir !== "string" || !path.isAbsolute(dir)) throw new ArtifactPathError(SPLIT_TARGET_UNRESOLVED_CODE, `cargo metadata for ${manifest} did not report an absolute target directory`);
+  const real = canonical(dir);
+  if (insideCanonical(real, snapshot) || insideCanonical(real, canonical(appRoot))) {
+    throw new ArtifactPathError(SPLIT_TARGET_UNRESOLVED_CODE, `the Cargo target of ${manifest} resolves inside the snapshot (${dir}); the gate binds a split's target outside it (CARGO_TARGET_DIR, row 7.09) and never to a snapshot-relative target/`);
+  }
+  if (pinned && real !== pinned) throw new ArtifactPathError(SPLIT_TARGET_DRIFT_CODE, `the Cargo target of ${manifest} is ${dir}, not the CARGO_TARGET_DIR the gate bound for this stage`);
+  return path.resolve(dir);
+}
+
+/**
+ * The context for a RightKit subcommand that gets only its argv and cwd (create-mac-updater, sign-updater, mirror-root-artifact, win-package-recipe):
+ * it reads the release config in `cwd`, so the target prefixes are the app's own, for every platform's target. Checkout mode needs no config.
+ */
+export async function loadSplitArtifactContext({ cwd = process.cwd(), env = process.env, configName, ...inject } = {}) {
+  if (!isSplitArtifactEnv(env)) return splitArtifactContext({ cwd, env, ...inject });
+  const { defaultReleaseConfigFile, importReleaseConfig } = await import("./release-config.mjs");
+  const { resolveNativeCargoLayout, nativeCargoDeclared } = await import("./native-cargo-layout.mjs");
+  const appRoot = path.resolve(cwd);
+  let config = {};
+  try { config = await importReleaseConfig(path.resolve(appRoot, configName ?? defaultReleaseConfigFile(appRoot)), { lenient: true }); } catch { /* an app with no readable config binds the default manifest only */ }
+  let nativeLayout = null;
+  try { if (nativeCargoDeclared({ appRoot, config })) nativeLayout = resolveNativeCargoLayout({ appRoot, config }); } catch { nativeLayout = null; }
+  return splitArtifactContext({ cwd: appRoot, env, nativeLayout, config, target: Object.values(config?.targets ?? {}), ...inject });
+}
+
+const insideBound = (file, ctx) => ctx.boundTargets.find((bound) => bound.dir && insideCanonical(canonical(file), canonical(bound.dir)));
+
+/**
+ * The file a declared artifact path means (R-T2). Checkout mode is the historical rule; see the module header for the split rules.
+ * Throws ArtifactPathError RK_SPLIT_TARGET_PATH for a split path the rules refuse.
+ */
+export function resolveArtifactPath(declared, ctx, { write = false } = {}) {
+  if (typeof declared !== "string" || !declared) throw new TypeError("a declared artifact path is required");
+  if (!ctx || (ctx.mode !== "split" && ctx.mode !== "checkout")) throw new TypeError("resolveArtifactPath requires a context from splitArtifactContext");
+  if (ctx.mode === "checkout") {
+    const local = path.resolve(ctx.appRoot, declared);
+    if (ctx.exists(local)) return local;
+    const managed = ctx.env.RIGHT_RELEASE_ARTIFACT_DIR;
+    if (managed) {
+      const candidate = path.join(path.resolve(managed), path.basename(declared));
+      if (ctx.exists(candidate)) return candidate;
+    }
+    return local;
+  }
+  const normalized = posix(declared);
+  if (isAbsoluteDeclared(declared)) {
+    const absolute = path.resolve(declared);
+    if (insideBound(absolute, ctx)) return absolute;
+    if (ctx.artifactDir && insideCanonical(canonical(absolute), canonical(ctx.artifactDir))) return absolute;
+    throw new ArtifactPathError(SPLIT_TARGET_PATH_CODE, `${declared} is neither inside a bound Cargo target (${ctx.boundTargets.map((bound) => bound.dir).filter(Boolean).join(", ") || "none"}) nor inside RIGHT_RELEASE_ARTIFACT_DIR; a split reads declared artifacts only there, never from the editable checkout or an unrelated directory`);
+  }
+  if (normalized.split("/").includes("..")) throw new ArtifactPathError(SPLIT_TARGET_PATH_CODE, `${declared} contains a .. segment; a split resolves a declared artifact path only below the snapshot app root or a bound target`);
+  const relative = path.posix.normalize(normalized).replace(/^\.\//, "");
+  for (const bound of ctx.boundTargets) {
+    const prefix = bound.prefix.replace(/\/+$/, "");
+    if (relative === prefix || relative.startsWith(`${prefix}/`)) {
+      if (!bound.dir) throw new ArtifactPathError(SPLIT_TARGET_UNRESOLVED_CODE, `${declared} is below ${prefix}/, whose Cargo target was not resolved`);
+      return path.join(bound.dir, relative.slice(prefix.length).replace(/^\/+/, ""));
+    }
+  }
+  const local = path.resolve(ctx.snapshotAppRoot, relative);
+  // A writer (a file the step is about to create) never lands in the managed artifact directory by accident of a stale copy there.
+  if (write) return local;
+  if (ctx.exists(local)) {
+    // A link out of the snapshot would be a checkout read in disguise.
+    if (!insideCanonical(canonical(local), canonical(ctx.snapshotRoot ?? ctx.snapshotAppRoot))) throw new ArtifactPathError(SPLIT_TARGET_PATH_CODE, `${declared} resolves outside the snapshot (${local}); a split never reads the editable checkout`);
+    return local;
+  }
+  if (ctx.artifactDir) {
+    const candidate = path.join(ctx.artifactDir, path.basename(relative));
+    if (ctx.exists(candidate)) return candidate;
+  }
+  return local;
+}
+
+/**
+ * Where a step writes a declared output (create-mac-updater's tarball, a DMG): the same refusals and target mapping as `resolveArtifactPath`, but a
+ * relative non-target path is always `<snapshot app root>/P`. Checkout mode is `path.resolve(app root, declared)`, as those writers always did.
+ */
+export function resolveArtifactWritePath(declared, ctx) {
+  if (ctx?.mode !== "split") return path.resolve(ctx?.appRoot ?? process.cwd(), declared);
+  return resolveArtifactPath(declared, ctx, { write: true });
+}
+
+/** What the sealed manifest records so the door can cross-check it (`boundTargets`, R-T1): `[{ prefix, manifest, dir }]`, manifest posix-relative to the app. */
+export function boundTargetsEvidence(ctx) {
+  if (ctx?.mode !== "split") return [];
+  return ctx.boundTargets.map((bound) => ({ prefix: bound.prefix, manifest: posix(path.relative(ctx.snapshotAppRoot, bound.manifest)), dir: bound.dir }));
+}
+
+/**
+ * The door's cross-check (R-T1, 7.08): every target the child recorded must be the one the door resolved itself (`expected`, absolute
+ * directories: on Linux the gate's 7.09 resolution, on Mac and Dell the verified receipts' `outputDir`s). Returns problems, [] when equal.
+ * A recorded list that is missing or empty while the door expected a target is a problem too: the child's value is never trusted alone.
+ */
+export function crossCheckBoundTargets({ recorded, expected }) {
+  const want = [...new Set((expected ?? []).filter(Boolean).map((dir) => canonical(dir)))];
+  const got = Array.isArray(recorded) ? recorded.map((entry) => (entry?.dir ? canonical(entry.dir) : null)) : [];
+  const problems = [];
+  if (want.length && !got.length) problems.push(`the sealed manifest records no bound Cargo target, but the gate bound ${want.join(", ")}`);
+  for (const [index, dir] of got.entries()) {
+    if (!dir) problems.push(`boundTargets[${index}] records no directory`);
+    else if (!want.includes(dir)) problems.push(`boundTargets[${index}] is ${recorded[index].dir}, not the directory the gate bound (${want.join(", ") || "none"})`);
+  }
+  return problems;
+}
+
+// ---- R-T4: no target-prefixed relative path in a command a RightKit entry does not own -------------------------------------------
+
+const RIGHTKIT_BINS = new Set(["right-release", "rightkit-qa"]);
+const RIGHTKIT_SCRIPTS = new Set(["recipe-build.mjs", "create-mac-updater.mjs", "sign-updater.mjs", "mirror-root-artifact.mjs", "win-package-recipe.mjs", "mac-package-recipe.mjs", "right-release.mjs"]);
+const binName = (token) => path.posix.basename(posix(token)).replace(/\.(?:cmd|exe|ps1)$/i, "");
+
+/** True for `right-release ...`, `rightkit-qa ...`, `pnpm exec right-release ...` and `node <this package's own script> ...`: commands RightKit resolves itself. */
+export function isRightKitEntry(command) {
+  const cmd = typeof command === "string" ? command : command?.cmd;
+  const args = typeof command === "string" ? [] : (command?.args ?? []).map(String);
+  if (typeof cmd !== "string") return false;
+  if (RIGHTKIT_BINS.has(binName(cmd))) return true;
+  if (["pnpm", "npx"].includes(binName(cmd)) && args[0] === "exec" && RIGHTKIT_BINS.has(binName(args[1] ?? ""))) return true;
+  if (["pnpm", "npx"].includes(binName(cmd)) && RIGHTKIT_BINS.has(binName(args[0] ?? ""))) return true;
+  if (binName(cmd) === "node" && args[0]) {
+    const script = path.resolve(args[0]);
+    if (!RIGHTKIT_SCRIPTS.has(path.basename(script))) return false;
+    const dir = path.dirname(script);
+    return dir === TOOL_ROOT || dir === path.join(TOOL_ROOT, "cli") || /[\\/]@rightkit[\\/]release(?:[\\/]cli)?$/.test(dir);
+  }
+  return false;
+}
+
+const escapeRegExp = (value) => String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** The first target-prefixed relative path in `text` (at token start, or after `=`, a quote, `:`, `,` or whitespace; `\` read as `/`), or null. */
+export function findTargetPrefixedPath(text, prefixes) {
+  const value = posix(text);
+  for (const prefix of prefixes) {
+    const stem = escapeRegExp(prefix.replace(/\/+$/, ""));
+    const match = new RegExp(`(?:^|[=:"',\\s])(?:\\./)?(${stem}(?:/[^\\s"',]*)?)(?=$|[\\s"',])`).exec(value);
+    if (match) return match[1];
+  }
+  return null;
+}
+
+const COMMAND_KEYS = ["prePackage", "package", "postBuild", "postSign", "preSeal", "publish"];
+
+/**
+ * Every command step a release runs for `target` (R-T4): prePackage, package, postBuild, postSign, preSeal and publish (each one command or a
+ * list), the native package hook, and the prepare / postBuild steps inside a declarative recipe's `recipe-build` plan (the wrapper itself is a
+ * RightKit entry; the steps it runs are the app's). `[{ name, cmd, args?, env? }]`. A recipe plan that cannot be read throws: fail closed.
+ */
+export function releaseCommandSteps({ target, config = {}, root = process.cwd() }) {
+  const steps = [];
+  const add = (name, command) => {
+    if (!command || typeof command !== "object") return;
+    for (const [index, step] of expandRecipeBuildCommands(command, { root }).entries()) steps.push({ name: index === 0 ? name : `${name} (recipe step ${index})`, ...step });
+  };
+  for (const key of COMMAND_KEYS) {
+    const value = target?.[key];
+    (Array.isArray(value) ? value : [value]).forEach((command, index, list) => add(list.length > 1 ? `${key}[${index}]` : key, command));
+  }
+  add("nativeAssembly.packageHook", config?.nativeAssembly?.packageHook);
+  // A declarative recipe still unexpanded (the controller reads the raw config): the steps it will run around the Tauri build.
+  for (const recipe of ["winPackage", "macPackage"]) {
+    for (const phase of ["prepare", "postBuild"]) {
+      const list = target?.[recipe]?.[phase];
+      if (Array.isArray(list)) list.forEach((command, index) => add(`${recipe}.${phase}[${index}]`, command));
+    }
+  }
+  return steps;
+}
+
+/**
+ * R-T4: a split's command step must not name a target-prefixed relative path (`src-tauri/target/...`): the snapshot has no such directory, and a
+ * non-RightKit command cannot be remapped. `steps` are `{ name?, cmd, args?, env? }` (or a command string); RightKit entries are skipped.
+ * Throws ArtifactPathError RK_SPLIT_TARGET_PATH naming each step and the fix, before anything builds. A checkout-mode context checks nothing.
+ */
+export function assertSplitCommandPaths(steps, ctx) {
+  if (!ctx || ctx.mode !== "split") return;
+  const prefixes = ctx.prefixes ?? ctx.boundTargets.map((bound) => bound.prefix);
+  if (!prefixes.length) return;
+  const problems = [];
+  steps.forEach((step, index) => {
+    const command = typeof step === "string" ? { cmd: step } : step;
+    if (!command || isRightKitEntry(command)) return;
+    const name = command.name ?? `step ${index + 1}`;
+    const values = [command.cmd, ...(command.args ?? []), ...Object.values(command.env ?? {})].filter((value) => typeof value === "string");
+    for (const value of values) {
+      const hit = findTargetPrefixedPath(value, prefixes);
+      if (hit) {
+        problems.push(`${name} (${command.cmd}) names the target-relative path ${hit}`);
+        break;
+      }
+    }
+  });
+  if (problems.length) {
+    throw new ArtifactPathError(SPLIT_TARGET_PATH_CODE, `${problems.join("; ")}. A door split has no target directory in its snapshot, and only RightKit's own steps are remapped. Pass the path absolute from resolveTargetRoot (@rightkit/release/cargo-target.mjs), as postright and cutright do; nothing was built`, problems);
+  }
+}

package/release-invocation.mjs

@@ -17,7 +17,13 @@ function canonical(file) {
   return path.normalize(realpathSync.native(file)).toLowerCase();
 }
 
-export function assertPrimaryReleaseCheckout(repoRoot, env = process.env) {
+/**
+ * The release must run from the primary Git worktree. `split` is a door source split (release-source-identity.mjs, row 7.04): the
+ * process then builds the selected commit's snapshot, so the checkout's branch, its HEAD and whether it is detached are irrelevant
+ * (GATE-CONTRACT.md: the primary checkout's state is not a build input). Only the primary-worktree identity is still required. Without
+ * `split` every check is exactly as it was.
+ */
+export function assertPrimaryReleaseCheckout(repoRoot, env = process.env, { split = false } = {}) {
   const worktrees = git(repoRoot, ["worktree", "list", "--porcelain"]);
   const gitDir = git(repoRoot, ["rev-parse", "--git-dir"]).trim();
   const configured = spawnSync("git", ["config", "--path", "--get", "core.worktree"], {
@@ -33,6 +39,7 @@ export function assertPrimaryReleaseCheckout(repoRoot, env = process.env) {
   if (canonical(repoRoot) !== canonical(primary)) {
     throw new Error(`right-release must be invoked from the primary Git worktree: ${primary}`);
   }
+  if (split) return;
   const branch = spawnSync("git", ["symbolic-ref", "--quiet", "HEAD"], { cwd: repoRoot, encoding: "utf8", windowsHide: true });
   if (
     branch.status !== 0

package/release-qa-command.mjs

@@ -25,8 +25,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "./background-process.mjs";
 import { defaultReleaseConfigFile, importReleaseConfig } from "./release-config.mjs";
-import { assertPrimaryReleaseCheckout } from "./release-invocation.mjs";
-import { assertCleanSource } from "./source-gate.mjs";
+import { NO_REPOSITORY_CODE, assertBindsSource, assertInsideSource, assertReleaseSource, gitRootOf, isSnapshotSource, resolveReleaseSource, snapshotSourceIdentity } from "./release-source-identity.mjs";
 import { verifySealedRelease } from "./release-state.mjs";
 import { auditMain } from "./release-qa-audit.mjs";
 import { journeyRequiredItem, QA_RUN_ENV, relativePosix, validateJourneysReceipt } from "./release-qa-hardening.mjs";
@@ -102,11 +101,18 @@ export async function runQa({ stage, platform, releaseIdArg, configPath, carryTo
   const executionStartedAt = new Date();
   const gitRunner = deps.gitRunner ?? spawnSync;
   const appRoot = path.dirname(configPath);
-  const repoRoot = String(gitRunner("git", ["-C", appRoot, "rev-parse", "--show-toplevel"], { encoding: "utf8", windowsHide: true }).stdout ?? "").trim();
-  if (!repoRoot) throw new Error("release config must live inside a Git repository");
-  if (!deps.skipPrimaryCheckout) assertPrimaryReleaseCheckout(repoRoot);
-  assertCleanSource({ status: String(gitRunner("git", ["-C", repoRoot, "status", "--porcelain=v1", "-z", "--untracked-files=all"], { encoding: "utf8", windowsHide: true }).stdout ?? ""), commandId: "right-release qa" });
-  const source = sourceIdentity(repoRoot, gitRunner);
+  // Source identity (release-source-identity.mjs, item 7 row 7.04). Outside a door run the checkout is the source, proven by the primary
+  // worktree and a clean status exactly as before. Inside one (RK_GATE_CHECKOUT) the source is the selected commit's objects and its
+  // verified snapshot: no HEAD, status or branch of the checkout is read, and the config, QA plan and journeys all come from the snapshot.
+  let release;
+  try { release = resolveReleaseSource({ cwd: appRoot, env: deps.env ?? process.env, git: gitRunner }); }
+  catch (error) { if (error.code === NO_REPOSITORY_CODE) throw new Error("release config must live inside a Git repository"); throw error; }
+  const split = isSnapshotSource(release);
+  // Outputs, the sealed vault and the QA receipts live in the checkout's `.right-release` either way (GC:31, GC:65).
+  const repoRoot = gitRootOf(release);
+  assertReleaseSource(release, { commandId: "right-release qa", env: deps.env ?? process.env, git: gitRunner, skipPrimaryCheckout: Boolean(deps.skipPrimaryCheckout) });
+  assertInsideSource(release, configPath, "the release config");
+  const source = split ? snapshotSourceIdentity(release, gitRunner) : sourceIdentity(repoRoot, gitRunner);
   const config = await importReleaseConfig(configPath, { query: `qa=${source.commit}` });
   if (!config?.app || !config?.version) throw new Error("release config must expose app and version");
   const { floor, digest: floorDigest } = loadQaFloor(deps.floorDir);
@@ -121,13 +127,23 @@ export async function runQa({ stage, platform, releaseIdArg, configPath, carryTo
   else {
     if (!releaseId) throw new Error("--release <sealed-id> is required for the installed stage");
     sealed = verifySealedRelease(path.join(repoRoot, ".right-release", "sealed", releaseId, platform === "win" ? "windows" : "mac"));
-    if (sealed.manifest.commit !== source.commit) throw new Error("sealed release was built from a different commit than the current checkout");
+    // R4: a split binds the sealed release to the selected commit (and its tree), never to the checkout's HEAD.
+    if (split) assertBindsSource(release, sealed.manifest, "the sealed release");
+    else if (sealed.manifest.commit !== source.commit) throw new Error("sealed release was built from a different commit than the current checkout");
     sourceReceiptDigest = sealed.manifest.qa?.sourceReceiptDigest ?? null;
     if (!sourceReceiptDigest) throw new Error("sealed release records no source QA receipt; it was not built through the QA gate; rebuild after `right-release qa --stage source`");
     artifacts = sealed.manifest.files.map((file) => ({ name: file.name, sha256: file.sha256, sizeBytes: file.sizeBytes }));
   }
 
   const key = ensureQaReceiptKey({ env: deps.env ?? process.env, credentialStore: deps.credentialStore, provision: deps.provision ?? provisionKeyOnHost });
+  // R5: the QA plan, the journeys manifest and a named journeys receipt are read from the snapshot, and so is a runner the config names.
+  const journeysDeclared = config.qa.journeys ?? null;
+  assertInsideSource(release, path.resolve(appRoot, config.qa.config), "qa.config");
+  if (journeysDeclared) {
+    assertInsideSource(release, path.resolve(appRoot, journeysDeclared.manifest ?? "journeys.toml"), "qa.journeys.manifest");
+    if (journeysDeclared.receipt) assertInsideSource(release, path.resolve(appRoot, String(journeysDeclared.receipt)), "qa.journeys.receipt");
+  }
+  if (config.qa.runner && !deps.runnerFile) assertInsideSource(release, path.resolve(appRoot, config.qa.runner), "qa.runner");
   const runnerFile = deps.runnerFile ?? resolveRunner({ qa: config.qa, appRoot });
   const runnerSha = sha256File(runnerFile);
   const journeysConfig = config.qa.journeys ?? null;
@@ -183,7 +199,7 @@ export async function runQa({ stage, platform, releaseIdArg, configPath, carryTo
     const manifestFile = path.resolve(appRoot, journeysConfig.manifest ?? "journeys.toml");
     const receiptFile = journeysConfig.receipt ? path.resolve(appRoot, String(journeysConfig.receipt)) : journeysReceiptFromOutput(journeysRun?.stdout);
     const validation = receiptFile
-      ? validateJourneysReceipt({ runnerFile, runnerSha256: runnerSha, receiptFile, manifestFile, manifestRelPath: relativePosix(repoRoot, manifestFile), platform, spawn: deps.spawnValidator ?? deps.spawnRunner ?? spawnSync })
+      ? validateJourneysReceipt({ runnerFile, runnerSha256: runnerSha, receiptFile, manifestFile, manifestRelPath: relativePosix(split ? release.snapshot : repoRoot, manifestFile), platform, spawn: deps.spawnValidator ?? deps.spawnRunner ?? spawnSync })
       : { ok: false, problems: ["rightkit-qa journeys run reported no run directory, so there is no journeys receipt to validate"], block: null };
     if (!deps.quiet) for (const problem of validation.problems) console.error(`[qa] journeys: ${problem}`);
     journeys = validation.block;

package/release-source-brand.mjs

@@ -0,0 +1,17 @@
+// The mark of a release source minted by release-source-identity.mjs `resolveReleaseSource` (item 7 row 7.04).
+//
+// A leaf with no imports, so that the ownership evidence (an enforcement entrypoint whose import closure is pinned into the policy
+// bundle) can refuse a hand-built source without pulling the door's modules into that closure. Only the resolver marks a source; a
+// plain object with the same fields is not one.
+const minted = new WeakSet();
+
+/** Marks `source` as resolved by the identity module and returns it. */
+export function brandReleaseSource(source) {
+  minted.add(source);
+  return source;
+}
+
+/** Whether `source` is an object `brandReleaseSource` marked. */
+export function isReleaseSource(source) {
+  return typeof source === "object" && source !== null && minted.has(source);
+}

package/release-source-identity.mjs

@@ -0,0 +1,171 @@
+// Release source identity (item 7 row 7.04; signed/item7-sage-decisions-2.md Q2; docs/GATE-CONTRACT.md "Commit-only build").
+//
+// Every right-release command that builds, qualifies or ships a door stage asks one question before it trusts anything it reads: which
+// source is this, and what proves it? There are exactly two answers.
+//
+//   checkout  RK_GATE_CHECKOUT is not set (hosted CI, no door, or the Mac/Dell route before the cutover). The source is the checkout's
+//             HEAD, proven the way it always was: the primary worktree, a branch-attached HEAD and a clean status (R1). Nothing here
+//             changes for that route.
+//   snapshot  RK_GATE_CHECKOUT is set: this process is a child of a live door run (source-split.mjs `readSourceSplit`). The identity is
+//             the SELECTED COMMIT's immutable objects plus the gate's start and end verification of the snapshot under held ownership.
+//             It is never the checkout's HEAD, status or branch (GC:24 "no dirty-tree condition", GC:156 item 1, GC:182 E1): the
+//             checkout may be dirty, ahead, behind or detached.
+//
+// A process that names a split it cannot prove (no live run, an ended run, another checkout, a cwd outside the snapshot) is refused
+// (R2); it never falls back to the checkout checks, because that would build bytes the identity does not describe.
+//
+// `resolveReleaseSource` is the single owner. It returns a frozen record that only it can mint (release-source-brand.mjs), so the
+// evidence, QA and upload code can refuse a hand-built one. The record's fields are frozen by the decision record:
+//   { mode: "snapshot", commit, tree, checkout, checkoutAppRoot, snapshot, appRoot, commonDir }
+//   { mode: "checkout", commit, tree, repoRoot, appRoot }
+import path from "node:path";
+import { spawnSync } from "./background-process.mjs";
+import { resolveSelectedCommit } from "./committed-source.mjs";
+import { canonicalRepositoryIdentity } from "./ownership-approval.mjs";
+import { assertPrimaryReleaseCheckout } from "./release-invocation.mjs";
+import { dependencyClosure } from "./release-qa-receipt.mjs";
+import { brandReleaseSource, isReleaseSource } from "./release-source-brand.mjs";
+import { assertCleanSource } from "./source-gate.mjs";
+import { SOURCE_SPLIT_CODE, SourceSplitError, inSnapshot, readSourceSplit } from "./source-split.mjs";
+
+export const RELEASE_SOURCE_IDENTITY_CODE = "RK_SOURCE_IDENTITY";
+export const NO_REPOSITORY_CODE = "RK_SOURCE_NO_REPOSITORY";
+
+/** A release source whose identity does not hold (a commit or tree that is not the selected one, a file outside the snapshot). */
+export class ReleaseSourceError extends Error {
+  constructor(message, code = RELEASE_SOURCE_IDENTITY_CODE) { super(message); this.name = "ReleaseSourceError"; this.code = code; }
+}
+
+// What each resolved source was resolved with, so `assertReleaseSource` can prove the same facts again (a run that has ended since is no
+// split any longer) without the caller threading the context through.
+const contexts = new WeakMap();
+
+const OBJECT_ID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+
+function plainGit(git, cwd, args) {
+  const result = git("git", args, { cwd, encoding: "utf8", windowsHide: true, maxBuffer: 64 * 1024 * 1024 });
+  if (result?.status !== 0) throw new Error(`git ${args.join(" ")} failed: ${String(result?.stderr ?? "").trim() || "no output"}`);
+  return String(result.stdout);
+}
+
+/**
+ * The source this process runs under. `git` runs git (a spawnSync-shaped function; tests inject a recorder). `readFile` and `alive` are
+ * passed to the door-run reader (tests only). Throws SourceSplitError (R2, R3) when a split is named but cannot be proven; throws
+ * an Error outside a git repository when no split is named.
+ */
+export function resolveReleaseSource({ cwd = process.cwd(), env = process.env, git = spawnSync, readFile, alive } = {}) {
+  const context = Object.freeze({ cwd, env, git, ...(readFile ? { readFile } : {}), ...(alive ? { alive } : {}) });
+  // 1. A live door run under the named checkout, the same checkout, and a cwd inside the run's snapshot. Throws when anything is off.
+  const split = readSourceSplit({ env, cwd, run: git, ...(readFile ? { readFile } : {}), ...(alive ? { alive } : {}) });
+  if (split) {
+    // 2. The tree is re-derived from the object database. It is never taken from the run file alone (R3).
+    let objects;
+    try { objects = resolveSelectedCommit(split.checkout, split.commit, { runner: git }); }
+    catch (error) { throw new SourceSplitError(`the door run's commit ${split.commit.slice(0, 12)} cannot be read from the object database of ${split.checkout}: ${error.message}`); }
+    if (objects.commit !== split.commit) throw new SourceSplitError(`the object database of ${split.checkout} answers ${objects.commit} for the door run's commit ${split.commit}`);
+    if (objects.tree !== split.tree) throw new SourceSplitError(`the door run records tree ${split.tree.slice(0, 12)} for commit ${split.commit.slice(0, 12)}, but the object database says ${objects.tree.slice(0, 12)} (R3)`);
+    const source = brandReleaseSource(Object.freeze({
+      mode: "snapshot", commit: objects.commit, tree: objects.tree, checkout: split.checkout, checkoutAppRoot: split.checkoutAppRoot,
+      snapshot: split.snapshot, appRoot: split.appRoot, commonDir: split.commonDir,
+    }));
+    contexts.set(source, context);
+    return source;
+  }
+  // The checkout route: HEAD of the repository at cwd, read exactly as each command always read it.
+  let repoRoot = "";
+  let detail = "";
+  try { repoRoot = plainGit(git, cwd, ["rev-parse", "--show-toplevel"]).trim(); } catch (error) { detail = ` (${error.message})`; }
+  if (!repoRoot) throw new ReleaseSourceError(`${cwd} is not inside a Git repository${detail}`, NO_REPOSITORY_CODE);
+  const commit = plainGit(git, repoRoot, ["rev-parse", "HEAD"]).trim();
+  const tree = plainGit(git, repoRoot, ["rev-parse", `${commit}^{tree}`]).trim();
+  if (!OBJECT_ID.test(commit) || !OBJECT_ID.test(tree)) throw new Error("the checkout's HEAD is not a commit");
+  const source = brandReleaseSource(Object.freeze({ mode: "checkout", commit, tree, repoRoot, appRoot: path.resolve(cwd) }));
+  contexts.set(source, context);
+  return source;
+}
+
+/** The record `resolveReleaseSource` minted, or a refusal: a hand-built look-alike never carries an identity. */
+export function requireReleaseSource(source) {
+  if (!isReleaseSource(source)) throw new SourceSplitError("the release source was not resolved by resolveReleaseSource; a hand-built source carries no identity");
+  return source;
+}
+
+export const isSnapshotSource = (source) => requireReleaseSource(source).mode === "snapshot";
+/** The root every git object read and every output, state, lock and sealed directory belongs to: the checkout (`.right-release` lives there). */
+export const gitRootOf = (source) => (requireReleaseSource(source).mode === "snapshot" ? source.checkout : source.repoRoot);
+/** The root every source, config, input and QA file is read from: the snapshot in a split, else the checkout. */
+export const sourceRootOf = (source) => (requireReleaseSource(source).mode === "snapshot" ? source.snapshot : source.repoRoot);
+
+/**
+ * Proves the source's identity holds now, for the command `commandId`.
+ *   checkout  R1, byte for byte as before: the primary worktree (branch-attached HEAD) and a clean status. `skipPrimaryCheckout` and
+ *             `skipCleanCheck` are the two existing seams (a test double; a phase resume that reads no unrelated source).
+ *   snapshot  The door run is proven again (live, this checkout, this cwd, the tree from the object database), then the checkout must
+ *             still be the primary worktree. No status, no HEAD and no branch is read: a dirty or moved checkout is irrelevant.
+ *             Writes into the snapshot are decided by the door's start and end verification, not here.
+ * Returns the source.
+ */
+export function assertReleaseSource(source, { commandId = "release", env, git, skipPrimaryCheckout = false, skipCleanCheck = false } = {}) {
+  requireReleaseSource(source);
+  const context = contexts.get(source);
+  const runGit = git ?? context.git;
+  const environment = env ?? context.env;
+  if (source.mode === "checkout") {
+    if (!skipPrimaryCheckout) assertPrimaryReleaseCheckout(source.repoRoot, environment);
+    if (!skipCleanCheck) assertCleanSource({ status: plainGit(runGit, source.repoRoot, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]), commandId });
+    return source;
+  }
+  const again = resolveReleaseSource({ ...context, env: environment, git: runGit });
+  if (again.mode !== "snapshot") throw new SourceSplitError("the door run's source split is gone; nothing may continue from a snapshot that is no longer proven");
+  for (const key of ["commit", "tree", "checkout", "snapshot", "appRoot", "checkoutAppRoot"]) {
+    if (again[key] !== source[key]) throw new SourceSplitError(`the door run's source.${key} changed while ${commandId} ran`);
+  }
+  // The primary worktree identity stays (GC:31); only the branch-attached refusal, which reads HEAD, is skipped (GC:156).
+  if (!skipPrimaryCheckout) assertPrimaryReleaseCheckout(source.checkout, environment, { split: true });
+  return source;
+}
+
+/**
+ * R5: in a split, a config, build input, QA plan or test file must resolve inside the snapshot (symlinks resolved). In the checkout
+ * route there is no containment to prove and this does nothing.
+ */
+export function assertInsideSource(source, file, label = "a source file") {
+  if (!isSnapshotSource(source)) return;
+  if (typeof file !== "string" || !file) throw new ReleaseSourceError(`${label} has no path; a split build reads only the snapshot of ${source.commit.slice(0, 12)}`);
+  if (!inSnapshot({ snapshot: source.snapshot }, path.resolve(file))) {
+    throw new ReleaseSourceError(`${label} ${file} is outside the snapshot ${source.snapshot} of ${source.commit.slice(0, 12)}; a split build reads the commit's snapshot and never the checkout (R5)`);
+  }
+}
+
+/**
+ * R4 (and R8): a record that claims a source (a sealed manifest, ownership evidence, a resumed build's state) is for the selected
+ * commit and, when it names a tree, that commit's tree. Another commit or tree is refused, never reinterpreted.
+ */
+export function assertBindsSource(source, record, label = "the record") {
+  requireReleaseSource(source);
+  if (!record || typeof record !== "object") throw new ReleaseSourceError(`${label} is missing, so it cannot be bound to commit ${source.commit.slice(0, 12)}`);
+  if (record.commit !== source.commit) throw new ReleaseSourceError(`${label} is for commit ${String(record.commit ?? "(none)").slice(0, 12)}, not the selected commit ${source.commit.slice(0, 12)} (R4)`);
+  if (record.tree !== undefined && record.tree !== source.tree) throw new ReleaseSourceError(`${label} is for tree ${String(record.tree).slice(0, 12)}, not the selected commit's tree ${source.tree.slice(0, 12)} (R4)`);
+}
+
+/**
+ * The `{ commit, tree, repositoryIdentity }` a source QA receipt binds, for a snapshot source: the selected commit and tree, and the
+ * repository identity from the checkout's origin. Reads no HEAD. (The checkout route keeps release-qa-receipt.mjs `sourceIdentity`.)
+ */
+export function snapshotSourceIdentity(source, git = spawnSync) {
+  if (!isSnapshotSource(source)) throw new ReleaseSourceError("snapshotSourceIdentity is for a door source split");
+  const origin = plainGit(git, source.checkout, ["remote", "get-url", "origin"]).trim();
+  return { commit: source.commit, tree: source.tree, repositoryIdentity: canonicalRepositoryIdentity(origin) };
+}
+
+/**
+ * The `{ source, closure }` options `admitSourceQa` / `assertSourceQaAdmission` / `assertInstalledQaAdmission` take so that the receipt they
+ * verify is compared with the SELECTED commit (its tree, its repository identity, its lockfile closure read from its objects) instead of the
+ * checkout's HEAD. `{}` for the checkout route: those functions then read HEAD exactly as before. Spread it into their options.
+ */
+export function qaAdmissionSourceOptions(source, git = spawnSync) {
+  if (!isSnapshotSource(source)) return {};
+  return { source: snapshotSourceIdentity(source, git), closure: dependencyClosure(source.checkout, source.commit, git) };
+}
+
+export { SOURCE_SPLIT_CODE };