@rightkit/release 0.2.38 → 0.2.40

package/cache-policy.test.mjs

@@ -0,0 +1,263 @@
+import assert from "node:assert/strict";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+
+import {
+  CACHE_SCHEMA,
+  DEFAULT_DESIRED_FREE_BYTES,
+  DEFAULT_HARD_FREE_BYTES,
+  DEFAULT_SCCACHE_MAX_BYTES,
+  DEFAULT_TARGET_MAX_BYTES,
+  acquireCacheLease,
+  acquireSuiteBuildSlot,
+  applyCachePrune,
+  assertWriteVolumeFloors,
+  ensureCacheEntry,
+  inspectWriteVolumes,
+  markCacheEntrySuccessful,
+  migrateLegacyCache,
+  planCachePrune,
+  readCachePolicy,
+  resolveCacheLayout,
+  resolveSharedCacheIdentity,
+  resolveSharedCacheRoot,
+} from "./cache-policy.mjs";
+
+function root() { return path.join(os.tmpdir(), `rightkit-cache-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`); }
+function layout(dir, fingerprint = "a1b2c3d4e5f60708") {
+  return resolveCacheLayout({ cacheRoot: dir, platform: "mac", architecture: "aarch64", app: "fixture", fingerprint, kind: "release" });
+}
+
+function migrationFixture() {
+  const base = root();
+  const fingerprint = "abcdef0123456789";
+  const legacyRoot = path.join(base, "repo", "app", "src-tauri", "target");
+  const legacyTargetRoot = path.join(base, "repo", ".right-release", "cache", "cargo-target", "mac", fingerprint);
+  const legacyCargoHome = path.join(base, "repo", ".right-release", "cache", "cargo-home");
+  mkdirSync(legacyTargetRoot, { recursive: true });
+  writeFileSync(path.join(legacyTargetRoot, "artifact"), "legacy-target");
+  mkdirSync(legacyCargoHome, { recursive: true });
+  writeFileSync(path.join(legacyCargoHome, "registry"), "legacy-cargo-home");
+  mkdirSync(path.dirname(legacyRoot), { recursive: true });
+  symlinkSync(legacyTargetRoot, legacyRoot);
+  const sharedCacheRoot = path.join(base, "shared-cache");
+  return {
+    fingerprint,
+    legacyRoot,
+    legacyTargetRoot,
+    legacyCargoHome,
+    layout: layout(sharedCacheRoot, fingerprint),
+    app: "fixture",
+    legacyReleaseLockPath: path.join(base, "repo", ".right-release", "locks", "mac.lock.json"),
+  };
+}
+
+test("cache roots are platform-native and overrides must be absolute", () => {
+  assert.equal(resolveSharedCacheRoot({ platform: "mac", home: "/Users/test", env: {} }), "/Users/test/Library/Caches/RightSuite/release");
+  assert.equal(resolveSharedCacheRoot({ platform: "win", env: { LOCALAPPDATA: "C:/Users/test/AppData/Local" } }), "C:\\Users\\test\\AppData\\Local\\RightSuite\\Cache\\release");
+  assert.equal(resolveSharedCacheRoot({ platform: "linux", home: "/home/test", xdgCacheHome: "/tmp/xdg", env: {} }), "/tmp/xdg/rightsuite/release");
+  assert.equal(resolveSharedCacheRoot({ platform: "mac", env: { RIGHT_RELEASE_CACHE_ROOT: "/tmp/cache" } }), "/tmp/cache");
+  assert.throws(() => resolveSharedCacheRoot({ platform: "mac", env: { RIGHT_RELEASE_CACHE_ROOT: "relative" } }), /absolute/i);
+});
+
+test("layout isolates app, platform, kind, and fingerprint", () => {
+  const base = root();
+  const release = layout(base);
+  const testLayout = resolveCacheLayout({ cacheRoot: base, platform: "mac", architecture: "aarch64", app: "other", fingerprint: "a1b2c3d4e5f60708", kind: "test" });
+  assert.match(release.targetDir, /targets[\\/]mac[\\/]fixture[\\/]a1b2c3d4e5f60708$/);
+  assert.match(testLayout.targetDir, /test-targets[\\/]mac[\\/]other[\\/]a1b2c3d4e5f60708$/);
+  assert.notEqual(release.targetDir, testLayout.targetDir);
+});
+
+test("policy defaults are the approved target, compiler, desired and hard limits", () => {
+  const policy = readCachePolicy({});
+  assert.equal(CACHE_SCHEMA, 1);
+  assert.equal(policy.targetMaxBytes, DEFAULT_TARGET_MAX_BYTES);
+  assert.equal(policy.sccacheMaxBytes, DEFAULT_SCCACHE_MAX_BYTES);
+  assert.equal(policy.desiredFreeBytes, DEFAULT_DESIRED_FREE_BYTES);
+  assert.equal(policy.hardFreeBytes, DEFAULT_HARD_FREE_BYTES);
+});
+
+test("entry metadata is atomic, complete, and updates success only after requested", () => {
+  const entry = layout(root());
+  ensureCacheEntry({ layout: entry, metadata: { toolchain: { cargo: "cargo 1", rustc: "rustc 1", host: "host" } }, now: new Date("2026-07-21T00:00:00Z") });
+  const created = JSON.parse(readFileSync(entry.markerPath, "utf8"));
+  assert.equal(created.schema, CACHE_SCHEMA);
+  assert.equal(created.id, "target:mac:fixture:a1b2c3d4e5f60708");
+  assert.equal(created.lastSuccessfulBuildAt, null);
+  markCacheEntrySuccessful({ layout: entry, now: new Date("2026-07-21T01:00:00Z") });
+  assert.equal(JSON.parse(readFileSync(entry.markerPath, "utf8")).lastSuccessfulBuildAt, "2026-07-21T01:00:00.000Z");
+});
+
+test("entry leases protect live entries, reclaim stale owners, and suite slots time out without a fallback", () => {
+  const entry = layout(root());
+  ensureCacheEntry({ layout: entry });
+  const lease = acquireCacheLease({ layout: entry, pid: process.pid, argv: ["test"] });
+  assert.throws(() => acquireCacheLease({ layout: entry, pid: process.pid + 100000, argv: ["second"] }), /lease.*active/i);
+  lease.release();
+  writeFileSync(entry.leasePath, JSON.stringify({ pid: 99999999, createdAt: "2000-01-01T00:00:00.000Z" }));
+  const reclaimed = acquireCacheLease({ layout: entry, pid: process.pid, argv: ["reclaimed"] });
+  reclaimed.release();
+  const slot = acquireSuiteBuildSlot({ layout: entry, pid: process.pid, argv: ["holder"], waitMs: 0 });
+  assert.throws(() => acquireSuiteBuildSlot({ layout: entry, pid: process.pid + 100000, argv: ["waiter"], waitMs: 0, sleep: () => {} }), /suite build slot.*active|timed out/i);
+  slot.release();
+});
+
+test("build and migration derive identical native-feature cache fingerprints", () => {
+  const base = root(); const cargoLock = path.join(base, "Cargo.lock"); const cargoToml = path.join(base, "Cargo.toml");
+  mkdirSync(base, { recursive: true });
+  writeFileSync(cargoLock, "[[package]]\nname = 'fixture'\n");
+  writeFileSync(cargoToml, "[dependencies]\nrusqlite = { version = '1', features = [\"bundled-sqlcipher\"] }\n");
+  const inputs = { cargoLockPath: cargoLock, cargoTomlPath: cargoToml, rustcVerbose: "rustc 1.91.0\nhost: aarch64-apple-darwin", targetTriple: "aarch64-apple-darwin", profile: "release" };
+  const build = resolveSharedCacheIdentity(inputs);
+  const migration = resolveSharedCacheIdentity(inputs);
+  assert.equal(build.fingerprint, migration.fingerprint);
+  assert.notEqual(build.fingerprint, resolveSharedCacheIdentity({ ...inputs, features: [] }).fingerprint);
+});
+
+test("migration moves an actual src-tauri target symlink and keeps dry-run physically pure", () => {
+  const fixture = migrationFixture();
+  const preview = migrateLegacyCache({ ...fixture, dryRun: true });
+  assert.equal(preview.moved, false);
+  assert.equal(existsSync(fixture.layout.cacheRoot), false);
+  assert.equal(lstatSync(fixture.legacyRoot).isSymbolicLink(), true);
+  const result = migrateLegacyCache({ ...fixture, dryRun: false });
+  assert.equal(result.moved, true);
+  assert.equal(existsSync(fixture.legacyRoot), false);
+  assert.equal(readFileSync(path.join(fixture.layout.targetDir, "artifact"), "utf8"), "legacy-target");
+  assert.equal(readFileSync(path.join(fixture.layout.cargoHome, "registry"), "utf8"), "legacy-cargo-home");
+});
+
+test("migration rejects target symlinks outside the exact derived fingerprint directory", () => {
+  const fixture = migrationFixture();
+  const other = path.join(path.dirname(fixture.legacyTargetRoot), "other-fingerprint");
+  mkdirSync(other, { recursive: true });
+  symlinkSync(other, `${fixture.legacyRoot}-wrong`);
+  assert.throws(() => migrateLegacyCache({ ...fixture, legacyRoot: `${fixture.legacyRoot}-wrong`, dryRun: true }), /unexpected target link/i);
+  symlinkSync(path.join(other, "missing"), `${fixture.legacyRoot}-dangling`);
+  assert.throws(() => migrateLegacyCache({ ...fixture, legacyRoot: `${fixture.legacyRoot}-dangling`, dryRun: true }), /unexpected target link/i);
+});
+
+test("migration rolls back target, Cargo home, and src-tauri link after every injected post-move failure", () => {
+  for (const failureAt of ["after-target-move", "after-entry-marker", "after-cargo-home-move", "before-receipt", "receipt-write"]) {
+    const fixture = migrationFixture();
+    assert.throws(() => migrateLegacyCache({ ...fixture, dryRun: false, onPostMove: (step) => { if (step === failureAt) throw new Error(`injected ${step}`); }, writeMigrationReceipt: failureAt === "receipt-write" ? () => { throw new Error("injected receipt write"); } : undefined }), /injected/);
+    assert.equal(readFileSync(path.join(fixture.legacyTargetRoot, "artifact"), "utf8"), "legacy-target", failureAt);
+    assert.equal(realpathSync(fixture.legacyRoot), realpathSync(fixture.legacyTargetRoot), failureAt);
+    assert.equal(lstatSync(fixture.legacyRoot).isSymbolicLink(), true, failureAt);
+    assert.equal(readFileSync(path.join(fixture.legacyCargoHome, "registry"), "utf8"), "legacy-cargo-home", failureAt);
+    assert.equal(existsSync(fixture.layout.targetDir), false, failureAt);
+    assert.equal(existsSync(fixture.layout.cargoHome), false, failureAt);
+  }
+});
+
+test("a competing suite build slot blocks migration before it moves a legacy cache", () => {
+  const fixture = migrationFixture();
+  const slot = acquireSuiteBuildSlot({ layout: fixture.layout, pid: process.pid, argv: ["build"], waitMs: 0 });
+  try {
+    assert.throws(() => migrateLegacyCache({ ...fixture, dryRun: false, waitMs: 0 }), /suite build slot.*active|timed out/i);
+    assert.equal(realpathSync(fixture.legacyRoot), realpathSync(fixture.legacyTargetRoot));
+    assert.equal(existsSync(fixture.layout.targetDir), false);
+  } finally { slot.release(); }
+});
+
+test("a live shared build lease blocks migration during in-lock revalidation", () => {
+  const fixture = migrationFixture();
+  mkdirSync(fixture.layout.leasesDir, { recursive: true });
+  writeFileSync(path.join(fixture.layout.leasesDir, "another-build.json"), JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
+  assert.throws(() => migrateLegacyCache({ ...fixture, dryRun: false }), /shared entry lease is live/i);
+  assert.equal(realpathSync(fixture.legacyRoot), realpathSync(fixture.legacyTargetRoot));
+  assert.equal(existsSync(fixture.layout.targetDir), false);
+  assert.equal(existsSync(fixture.layout.gcLockPath), false);
+  assert.equal(existsSync(fixture.layout.suiteSlotPath), false);
+});
+
+test("a live legacy release lock blocks migration during in-lock revalidation", () => {
+  const fixture = migrationFixture();
+  mkdirSync(path.dirname(fixture.legacyReleaseLockPath), { recursive: true });
+  writeFileSync(fixture.legacyReleaseLockPath, JSON.stringify({ pid: process.pid }));
+  assert.throws(() => migrateLegacyCache({ ...fixture, dryRun: false }), /legacy release lock is live/i);
+  assert.equal(realpathSync(fixture.legacyRoot), realpathSync(fixture.legacyTargetRoot));
+  assert.equal(existsSync(fixture.layout.targetDir), false);
+  assert.equal(existsSync(fixture.layout.gcLockPath), false);
+  assert.equal(existsSync(fixture.layout.suiteSlotPath), false);
+});
+
+test("pruning is oldest successful use first and dry-run equals apply candidates", () => {
+  const base = root();
+  const older = layout(base, "1111111111111111");
+  const newer = layout(base, "2222222222222222");
+  for (const [entry, stamp] of [[older, "2026-01-01T00:00:00.000Z"], [newer, "2026-02-01T00:00:00.000Z"]]) {
+    ensureCacheEntry({ layout: entry, now: new Date(stamp) });
+    writeFileSync(path.join(entry.targetDir, "payload"), "x".repeat(32));
+    markCacheEntrySuccessful({ layout: entry, now: new Date(stamp) });
+  }
+  const snapshot = { cacheRoot: base, targetBytes: 64, entries: [
+    { id: newer.id, dir: newer.targetDir, bytes: 32, marker: JSON.parse(readFileSync(newer.markerPath)), leased: false },
+    { id: older.id, dir: older.targetDir, bytes: 32, marker: JSON.parse(readFileSync(older.markerPath)), leased: false },
+  ] };
+  const plan = planCachePrune({ snapshot, policy: { targetMaxBytes: 31, desiredFreeBytes: 0 }, protectedEntryIds: new Set() });
+  assert.deepEqual(plan.candidates.map((x) => x.id), [older.id, newer.id]);
+  assert.deepEqual(applyCachePrune({ plan, cacheRoot: base, dryRun: true }).candidateIds, applyCachePrune({ plan, cacheRoot: base, dryRun: false }).candidateIds);
+  assert.equal(existsSync(older.targetDir), false);
+  assert.equal(existsSync(newer.targetDir), false);
+});
+
+test("pruning fails closed for malformed markers, symlink escapes, and cache root", () => {
+  const base = root();
+  const safe = layout(base);
+  mkdirSync(safe.targetDir, { recursive: true });
+  writeFileSync(safe.markerPath, "not-json");
+  const outside = root(); mkdirSync(outside, { recursive: true });
+  const link = layout(base, "2222222222222222"); mkdirSync(path.dirname(link.targetDir), { recursive: true }); symlinkSync(outside, link.targetDir);
+  const plan = { candidates: [
+    { id: "bad", dir: safe.targetDir, bytes: 1 },
+    { id: "link", dir: link.targetDir, bytes: 1 },
+    { id: "root", dir: base, bytes: 1 },
+  ] };
+  const result = applyCachePrune({ plan, cacheRoot: base, dryRun: false });
+  assert.deepEqual(result.removedIds, []);
+  assert.equal(existsSync(safe.targetDir), true);
+  assert.equal(lstatSync(link.targetDir).isSymbolicLink(), true);
+});
+
+test("entry creation rejects a symlinked cache ancestor before writing outside the cache root", () => {
+  const parent = root(); const outside = root(); mkdirSync(parent, { recursive: true }); mkdirSync(outside, { recursive: true });
+  symlinkSync(outside, path.join(parent, "cache"));
+  const unsafe = resolveCacheLayout({ cacheRoot: path.join(parent, "cache"), platform: "mac", architecture: "aarch64", app: "fixture", fingerprint: "3333333333333333", kind: "release" });
+  assert.throws(() => ensureCacheEntry({ layout: unsafe }), /symlink|unsafe/i);
+  assert.equal(existsSync(path.join(outside, "targets")), false);
+});
+
+test("prune takes the global GC lock and blocks a racing lease before deletion", () => {
+  const base = root(); const entry = layout(base, "4444444444444444"); ensureCacheEntry({ layout: entry }); writeFileSync(path.join(entry.targetDir, "payload"), "x");
+  const plan = { cacheRoot: base, candidates: [{ id: entry.id, dir: entry.targetDir, bytes: 1 }] };
+  assert.throws(() => applyCachePrune({ plan, cacheRoot: base, dryRun: false, beforeDelete: () => acquireCacheLease({ layout: entry }) }), /global GC lock active/);
+  assert.equal(existsSync(entry.targetDir), true);
+  assert.equal(existsSync(path.join(base, "gc", "gc.lock.json")), false);
+});
+
+test("a real child-process lease acquired after planning excludes its entry from prune", async () => {
+  const base = root(); const entry = layout(base, "5555555555555555"); ensureCacheEntry({ layout: entry }); writeFileSync(path.join(entry.targetDir, "payload"), "x");
+  const plan = { cacheRoot: base, candidates: [{ id: entry.id, dir: entry.targetDir, bytes: 1 }] };
+  const moduleUrl = new URL("./cache-policy.mjs", import.meta.url).href;
+  const child = spawn(process.execPath, ["--input-type=module", "--eval", `import { resolveCacheLayout, acquireCacheLease } from ${JSON.stringify(moduleUrl)}; const l=resolveCacheLayout({cacheRoot:process.argv[1],platform:'mac',architecture:'aarch64',app:'fixture',fingerprint:'5555555555555555',kind:'release'}); const lease=acquireCacheLease({layout:l}); console.log('ready'); setTimeout(()=>lease.release(),500);`, base], { stdio: ["ignore", "pipe", "pipe"] });
+  await once(child.stdout, "data");
+  const result = applyCachePrune({ plan, cacheRoot: base, dryRun: false });
+  assert.deepEqual(result.removedIds, []);
+  assert.equal(existsSync(entry.targetDir), true);
+  await once(child, "exit");
+});
+
+test("write-volume inspection deduplicates same devices and enforces both hard floors", () => {
+  const statfs = (dir) => ({ bsize: 1024, bavail: dir.includes("cache") ? 20 : 30, dev: dir.includes("same") ? 1 : dir.includes("cache") ? 2 : 3 });
+  const same = inspectWriteVolumes({ repoRoot: "/same/repo", vaultRoot: "/same/vault", cacheRoot: "/same/cache", statfs });
+  assert.equal(same.length, 1);
+  const distinct = inspectWriteVolumes({ repoRoot: "/repo", vaultRoot: "/repo", cacheRoot: "/cache", statfs });
+  assert.equal(distinct.length, 2);
+  assert.throws(() => assertWriteVolumeFloors({ volumes: distinct, policy: { hardFreeBytes: 25 * 1024 }, configuredRepoMinimumBytes: 25 * 1024 }), /cache|repo/i);
+});

package/cargo-contract.mjs

@@ -8,6 +8,13 @@ const CRATES_IO_SOURCES = new Set([
   "registry+https://github.com/rust-lang/crates.io-index",
   "registry+https://index.crates.io/",
 ]);
+const CACHE_V2_ENVIRONMENT = ["CARGO_HOME", "CARGO_TARGET_DIR", "RUSTC_WRAPPER", "SCCACHE_DIR", "SCCACHE_BASEDIRS", "RIGHT_RELEASE_CACHE_OWNER"];
+
+export function isolatedCargoMetadataEnv(cargoHome, env = process.env) {
+  const metadataEnv = { ...env };
+  for (const name of CACHE_V2_ENVIRONMENT) delete metadataEnv[name];
+  return { ...metadataEnv, CARGO_HOME: cargoHome };
+}
 
 export function validateRightKitCargoContract(root, publishedVersions, label = path.basename(root)) {
   const scanRoot = path.resolve(root);
@@ -70,7 +77,7 @@ function readCargoManifestDependencies(manifestPath, cargoHome, label) {
     {
       cwd: path.dirname(manifestPath),
       encoding: "utf8",
-      env: { ...process.env, CARGO_HOME: cargoHome },
+      env: isolatedCargoMetadataEnv(cargoHome),
       windowsHide: true,
     },
   );

package/cli/right-release.mjs

@@ -42,6 +42,8 @@ if (first === "--version" || first === "-v") {
     ["--test", path.join(packageRoot, "right-suite-contract.test.mjs")],
     "[right-release] suite-doctor passed",
   );
+} else if (first === "cache") {
+  run("cache-command.mjs", args.slice(1));
 } else if (first === "publish") {
   const rest = args.slice(1);
   if (rest[0] === "cargo") {
@@ -133,6 +135,10 @@ Commands:
   doctor [--platform mac|win]                        Inspect one app's release config
   doctor --all                                       Verify all Right Suite app release contracts
   suite-doctor                                       Verify all local Right Suite repositories
+  cache status [--json]                              Inspect the shared local build cache
+  cache prune [--dry-run|--apply] [--json]           Plan or apply safe shared-target pruning
+  cache migrate --config <file> [--dry-run|--apply] [--json]
+                                                      Move a same-volume legacy target without copying
   deps --check|--audit|--update                      Shared dependency lane
   hardening <artifact...>                            Run the Right Suite hardening scan
   lsclean <AppName.app>                              Clear macOS LaunchServices duplicates

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/release",
-  "version": "0.2.38",
+  "version": "0.2.40",
   "description": "Portable Right Suite release CLI/SDK: signed installers, updater artifacts, patch/update routing, hardening, R2 publish, and RightApps registration.",
   "type": "module",
   "bin": {

package/release-invocation.mjs

@@ -21,6 +21,8 @@ export function assertPrimaryReleaseCheckout(repoRoot) {
   if (canonical(repoRoot) !== canonical(primary)) {
     throw new Error(`right-release must be invoked from the primary Git worktree: ${primary}`);
   }
+  const branch = spawnSync("git", ["symbolic-ref", "--quiet", "HEAD"], { cwd: repoRoot, encoding: "utf8", windowsHide: true });
+  if (branch.status !== 0) throw new Error("right-release requires a branch-attached primary Git checkout; detached HEAD is forbidden");
 }
 
 function pathspec(pattern, exclude = false) {
@@ -55,9 +57,25 @@ export function dirtyBuildInputs(repoRoot, inputs, baseline = "HEAD") {
   if (!Array.isArray(inputs?.include) || inputs.include.length === 0) {
     throw new Error("release config must declare non-empty buildInputs.include paths");
   }
+  const required = new Set(inputs.required ?? []);
+  const files = [
+    ...statusFiles(repoRoot, inputs.include, inputs.exclude),
+    ...statusFiles(repoRoot, [...required], []),
+  ];
+  return [...new Set(files)]
+    .filter((file) => required.has(file)
+      ? fileChangedFromBaseline(repoRoot, file, baseline)
+      : inputs.json?.[file]
+      ? jsonProjectionChanged(repoRoot, file, inputs.json[file], baseline)
+      : fileChangedFromBaseline(repoRoot, file, baseline))
+    .sort();
+}
+
+function statusFiles(repoRoot, include, exclude = []) {
+  if (!include.length) return [];
   const specs = [
-    ...inputs.include.map((pattern) => pathspec(pattern)),
-    ...(inputs.exclude ?? []).map((pattern) => pathspec(pattern, true)),
+    ...include.map((pattern) => pathspec(pattern)),
+    ...exclude.map((pattern) => pathspec(pattern, true)),
   ];
   const output = git(repoRoot, ["status", "--porcelain=v1", "-z", "--untracked-files=all", "--", ...specs]);
   const records = output.split("\0");
@@ -69,9 +87,5 @@ export function dirtyBuildInputs(repoRoot, inputs, baseline = "HEAD") {
     files.push(record.slice(3).replaceAll("\\", "/"));
     if (/[RC]/.test(status)) index += 1;
   }
-  return [...new Set(files)]
-    .filter((file) => inputs.json?.[file]
-      ? jsonProjectionChanged(repoRoot, file, inputs.json[file], baseline)
-      : fileChangedFromBaseline(repoRoot, file, baseline))
-    .sort();
+  return files;
 }

package/release-state.mjs

@@ -2,12 +2,14 @@ import { createHash } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, watch } from "node:fs";
 import path from "node:path";
+import { DEFAULT_SCCACHE_MAX_BYTES, resolveCacheLayout } from "./cache-policy.mjs";
 
-export function cacheFingerprint({ cargoLockSha256, rustc, target, features = [] }) {
+export function cacheFingerprint({ cargoLockSha256, rustc, target, architecture, features = [] }) {
   const payload = JSON.stringify({
     cargoLockSha256,
     rustc,
     target,
+    architecture,
     features: [...features].sort(),
   });
   return createHash("sha256").update(payload).digest("hex").slice(0, 16);
@@ -59,14 +61,29 @@ export function watchProgress(paths, onProgress) {
   };
 }
 
-export function releaseEnvironment({ root, platform, cacheKey, kind = "release" }) {
+export function releaseEnvironment({ root, cacheRoot, platform, architecture, app, cacheKey, kind = "release", appRoot, mode = "legacy" }) {
   if (kind !== "release" && kind !== "test") throw new Error(`invalid target kind: ${kind}`);
+  if (mode !== "legacy" && mode !== "shared") throw new Error(`invalid cache mode: ${mode}`);
+  if (mode === "shared") {
+    if (!cacheRoot || !platform || !architecture || !app || !cacheKey || !appRoot) throw new Error("shared release environment requires cacheRoot, platform, architecture, app, cacheKey, and appRoot");
+    const layout = resolveCacheLayout({ cacheRoot, platform, architecture, app, fingerprint: cacheKey, kind });
+    return {
+      CARGO_TARGET_DIR: layout.targetDir,
+      CARGO_HOME: layout.cargoHome,
+      SCCACHE_DIR: layout.sccacheDir,
+      SCCACHE_CACHE_SIZE: `${DEFAULT_SCCACHE_MAX_BYTES / 1024 ** 3}G`,
+      SCCACHE_BASEDIRS: [path.resolve(root), path.resolve(appRoot)].join(path.delimiter),
+      RUSTC_WRAPPER: "sccache",
+      RIGHT_RELEASE_CACHE_OWNER: "rightkit-v2",
+    };
+  }
   const targetKind = kind === "release" ? "cargo-target" : "test-target";
   return {
     CARGO_TARGET_DIR: path.resolve(root, "cache", targetKind, platform, cacheKey),
     CARGO_HOME: path.resolve(root, "cache", "cargo-home"),
     SCCACHE_DIR: path.resolve(root, "cache", "sccache"),
     RUSTC_WRAPPER: "sccache",
+    RIGHT_RELEASE_CACHE_OWNER: undefined,
   };
 }
 
@@ -94,6 +111,8 @@ export async function runBuildStateMachine({
   commit,
   platform,
   requiredInputs = [],
+  inputHashes,
+  cacheKey,
   ops,
 }) {
   const releaseId = `${app}-${version}-${commit.slice(0, 8)}`;
@@ -104,6 +123,11 @@ export async function runBuildStateMachine({
     if (sealed.manifest.app !== app || sealed.manifest.version !== version || sealed.manifest.commit !== commit) {
       throw new Error(`sealed release identity mismatch: ${releaseId}`);
     }
+    if (sealed.manifest.platform !== platform) throw new Error(`sealed release platform identity mismatch: ${releaseId}`);
+    if (inputHashes && JSON.stringify(sealed.manifest.inputs) !== JSON.stringify(inputHashes)) {
+      throw new Error(`sealed release input identity mismatch: ${releaseId}`);
+    }
+    if (cacheKey && sealed.manifest.cacheKey !== cacheKey) throw new Error(`sealed release cache identity mismatch: ${releaseId}`);
     return { status: "sealed", resumed: true, releaseId, sealedDir };
   }
   await ops.preflight?.({ root, app, version, commit, platform, requiredInputs, releaseId });

package/release-state.test.mjs

@@ -49,6 +49,22 @@ test("nested app configs keep the vault at repo root and build from the app root
   assert.equal(layout.targetLink, path.resolve("D:/suite/heardright/tauri-app-next/src-tauri/target"));
 });
 
+test("shared release environment is isolated from the app vault", () => {
+  const env = releaseEnvironment({
+    root: "/suite/.right-release",
+    cacheRoot: "/Users/test/Library/Caches/RightSuite/release",
+    platform: "mac",
+    architecture: "aarch64",
+    app: "fixture",
+    appRoot: "/suite/fixture",
+    cacheKey: "abcdef0123456789",
+    mode: "shared",
+  });
+  assert.match(env.CARGO_TARGET_DIR, /RightSuite\/release\/targets\/mac\/fixture\/abcdef0123456789$/);
+  assert.match(env.CARGO_HOME, /RightSuite\/release\/cargo-home$/);
+  assert.equal(env.RIGHT_RELEASE_CACHE_OWNER, "rightkit-v2");
+});
+
 function sha256(value) {
   return createHash("sha256").update(value).digest("hex");
 }
@@ -182,6 +198,40 @@ test("a valid sealed release resumes without rebuilding", async () => {
   assert.equal(builds, 0);
 });
 
+test("sealed build resume rejects changed input or cache identity", async () => {
+  const fx = fixture();
+  fx.manifest.inputs = { "src-tauri/Cargo.lock": "old-hash" };
+  fx.manifest.cacheKey = "old-cache";
+  writeFileSync(path.join(fx.sealedDir, "release-manifest.json"), `${JSON.stringify(fx.manifest, null, 2)}\n`);
+
+  await assert.rejects(
+    runBuildStateMachine({
+      root: fx.root,
+      app: fx.manifest.app,
+      version: fx.manifest.version,
+      commit: fx.manifest.commit,
+      platform: fx.manifest.platform,
+      inputHashes: { "src-tauri/Cargo.lock": "new-hash" },
+      cacheKey: fx.manifest.cacheKey,
+      ops: {},
+    }),
+    /sealed release input identity mismatch/i,
+  );
+  await assert.rejects(
+    runBuildStateMachine({
+      root: fx.root,
+      app: fx.manifest.app,
+      version: fx.manifest.version,
+      commit: fx.manifest.commit,
+      platform: fx.manifest.platform,
+      inputHashes: fx.manifest.inputs,
+      cacheKey: "new-cache",
+      ops: {},
+    }),
+    /sealed release cache identity mismatch/i,
+  );
+});
+
 test("manifest or file tampering blocks upload before any mutation", async () => {
   const fx = fixture();
   writeFileSync(fx.installer, "changed");

package/release.mjs

@@ -61,6 +61,7 @@ for (let i = 0; i < args.length; i++) {
 
 if (opts.upload) fail("combined build+upload was removed; run right-release build, then right-release upload --release <id> --tier patch|update");
 if (opts.tier && !TIERS.has(opts.tier)) usage(2, `invalid --tier: ${opts.tier} (expected patch|update)`);
+const sccacheVersion = assertSharedSccachePrerequisite();
 
 const configPath = path.resolve(opts.config);
 const config = (await import(pathToFileURL(configPath))).default;
@@ -92,6 +93,7 @@ if (opts.doctor) {
   console.log(`packageManager: ${config.packageManager}`);
   console.log(`workdir: ${workdir}`);
   console.log(`hardeningscan: ${HARDENING_SCAN}`);
+  if (sccacheVersion) console.log(`sccache: ${sccacheVersion}`);
   if (legalContract) {
     console.log(`legal: ${legalContract.manifestPath}`);
     console.log(`legalAcceptance: ${legalContract.acceptanceVersion}`);
@@ -156,7 +158,11 @@ if (opts.upload && !target.publish) {
   }
 }
 
-sweepStaleRustArtifacts();
+if (process.env.RIGHT_RELEASE_CACHE_MODE === "shared" && process.env.RIGHT_RELEASE_CACHE_OWNER === "rightkit-v2") {
+  console.log("right-release: shared cache prune delegated to RightKit Cache V2");
+} else {
+  sweepStaleRustArtifacts();
+}
 
 console.log(`right-release: done (${Date.now() - started}ms)`);
 releaseLock.release();
@@ -172,6 +178,26 @@ function fail(message) {
   process.exit(1);
 }
 
+function assertSharedSccachePrerequisite() {
+  if (process.env.RIGHT_RELEASE_CACHE_MODE !== "shared") return null;
+  const result = spawnSync("sccache", ["--version"], { encoding: "utf8", windowsHide: true });
+  const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
+  const version = output.match(/\b(\d+)\.(\d+)\.(\d+)\b/);
+  const valid = result.status === 0 && version && isAtLeastVersion(version.slice(1).map(Number), [0, 15, 0]);
+  if (!valid) {
+    const found = version ? ` (found ${version[0]})` : "";
+    fail(`shared cache mode requires sccache >= 0.15.0${found}. Install with: cargo install sccache --locked; then verify: sccache --version`);
+  }
+  return version[0];
+}
+
+function isAtLeastVersion(actual, minimum) {
+  for (let index = 0; index < minimum.length; index += 1) {
+    if (actual[index] !== minimum[index]) return actual[index] > minimum[index];
+  }
+  return true;
+}
+
 async function mustExist(file, message) {
   if (opts.dryRun) return;
   await access(file).catch(() => fail(message));