@rightkit/release 0.2.38 → 0.2.39

package/build-release.mjs

@@ -21,7 +21,8 @@ import path from "node:path";
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { assertPrimaryReleaseCheckout, dirtyBuildInputs } from "./release-invocation.mjs";
-import { cacheFingerprint, commandOutputPortable, releaseEnvironment, resolveReleaseLayout, runBuildStateMachine, watchProgress } from "./release-state.mjs";
+import { commandOutputPortable, releaseEnvironment, resolveReleaseLayout, runBuildStateMachine, verifySealedRelease, watchProgress } from "./release-state.mjs";
+import { acquireCacheLease, acquireSuiteBuildSlot, applyCachePrune, assertWriteVolumeFloors, inspectCache, inspectWriteVolumes, markCacheEntrySuccessful, planCachePrune, readCachePolicy, resolveCacheLayout, resolveSharedCacheIdentity, resolveSharedCacheRoot } from "./cache-policy.mjs";
 
 const TOOL_ROOT = path.dirname(fileURLToPath(import.meta.url));
 const WORKER = path.join(TOOL_ROOT, "release.mjs");
@@ -50,16 +51,20 @@ const vaultRoot = resolveReleaseLayout({ repoRoot, configPath: path.resolve(conf
 mkdirSync(path.join(vaultRoot, "locks"), { recursive: true });
 const lock = acquireLock(path.join(vaultRoot, "locks", `${platform}.lock.json`));
 let child = null;
+let suiteSlot;
+let cacheLease;
+let interrupted;
 
 for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
   process.once(signal, () => {
     if (child?.pid) killTree(child.pid);
-    lock.release();
-    process.exit(signal === "SIGINT" ? 130 : 143);
+    interrupted = new Error(`release interrupted by ${signal}`);
+    process.exitCode = signal === "SIGINT" ? 130 : 143;
   });
 }
 
 try {
+  throwIfInterrupted();
   if (!dryRun) git(repoRoot, ["fetch", "origin", "main"]);
   const commit = git(repoRoot, ["rev-parse", dryRun ? "HEAD" : "origin/main"]);
   const shortCommit = commit.slice(0, 8);
@@ -83,27 +88,35 @@ try {
   const target = config.targets?.[platform];
   if (!target?.package) fail(`${config.app} has no ${platform} package command`);
   const dirtyInputs = dirtyBuildInputs(repoRoot, repoBuildInputs(repoRoot, invocationRoot, relativeConfig, target.buildInputs ?? config.buildInputs), commit);
-  if (dirtyInputs.length > 0) {
-    fail(`dirty files can change the packaged app; resolve them before release:\n${dirtyInputs.map((file) => `- ${file}`).join("\n")}`);
-  }
+  if (dirtyInputs.length > 0) fail(`dirty files can change the packaged app; resolve them before release:\n${dirtyInputs.map((file) => `- ${file}`).join("\n")}`);
   const requiredInputs = inputPaths(appRoot, worktreeConfigPath, target);
   const toolVersions = collectToolVersions(config.packageManager ?? "pnpm");
   const inputHashes = hashInputs(requiredInputs);
   const cargoLock = requiredInputs.find((file) => /Cargo\.lock$/i.test(file));
   const cargoToml = requiredInputs.find((file) => /Cargo\.toml$/i.test(file));
-  const cacheKey = cacheFingerprint({
-    cargoLockSha256: cargoLock ? inputHashes[path.relative(worktree, cargoLock)] : "none",
-    rustc: toolVersions.rustc,
-    target: toolVersions.rustHost,
-    features: cargoToml ? sqlCipherFeatures(readFileSync(cargoToml, "utf8")) : [],
-  });
+  const cacheIdentity = resolveSharedCacheIdentity({ cargoLockPath: cargoLock, cargoTomlPath: cargoToml, rustcVerbose: toolVersions.rustc, targetTriple: target.cargoTarget ?? target.targetTriple ?? target.rustTarget ?? toolVersions.rustHost, profile: target.profile ?? "release" });
+  const cacheKey = cacheIdentity.fingerprint;
+  const cacheMode = process.env.RIGHT_RELEASE_CACHE_MODE ?? (platform === "mac" ? "shared" : "legacy");
+  if (cacheMode !== "legacy" && cacheMode !== "shared") fail("RIGHT_RELEASE_CACHE_MODE must be legacy or shared");
+  const sharedCacheRoot = cacheMode === "shared" ? resolveSharedCacheRoot({ platform, env: process.env }) : undefined;
+  const sharedLayout = cacheMode === "shared"
+    ? resolveCacheLayout({ cacheRoot: sharedCacheRoot, platform, architecture: cacheIdentity.architecture, app: config.app, fingerprint: cacheKey, kind: "release" })
+    : undefined;
+  if (cacheMode === "shared") assertSccacheVersion(toolVersions.sccache);
   const env = {
     ...process.env,
-    ...releaseEnvironment({ root: vaultRoot, platform, cacheKey, kind: "release" }),
+    ...releaseEnvironment({ root: vaultRoot, cacheRoot: sharedCacheRoot, platform, architecture: cacheIdentity.architecture, app: config.app, cacheKey, kind: "release", appRoot, mode: cacheMode }),
     RIGHT_RELEASE_REPO_ROOT: layout.repoRoot,
     RIGHT_RELEASE_APP_ROOT: layout.appRoot,
   };
-  if (!commandExists("sccache")) delete env.RUSTC_WRAPPER;
+  if (cacheMode === "legacy") delete env.RIGHT_RELEASE_CACHE_OWNER;
+  if (cacheMode === "shared" && env.RIGHT_RELEASE_CACHE_OWNER !== "rightkit-v2") fail("shared cache ownership token was not configured");
+  if (cacheMode === "legacy" && !commandExists("sccache")) delete env.RUSTC_WRAPPER;
+  if (cacheMode === "shared") {
+    suiteSlot = acquireSuiteBuildSlot({ layout: sharedLayout, pid: process.pid, argv: process.argv, waitMs: Number(process.env.BUILD_GUARD_WAIT_SECS ?? 900) * 1000 });
+    cacheLease = acquireCacheLease({ layout: sharedLayout, pid: process.pid, argv: process.argv });
+  }
+  throwIfInterrupted();
   const releaseId = `${config.app}-${config.version}-${shortCommit}`;
   const platformDir = platform === "win" ? "windows" : "mac";
   const buildRoot = path.join(vaultRoot, "build", config.app, config.version, shortCommit, platformDir);
@@ -130,7 +143,15 @@ try {
     requiredInputs,
     ops: {
       preflight: async () => {
-        assertDiskSpace(repoRoot, target.preflight?.minFreeGb ?? 20);
+        throwIfInterrupted();
+        if (cacheMode === "shared") {
+          const policy = readCachePolicy(process.env);
+          const snapshot = inspectCache({ cacheRoot: sharedCacheRoot });
+          const plan = planCachePrune({ snapshot, policy, protectedEntryIds: new Set([sharedLayout.id]) });
+          applyCachePrune({ plan, cacheRoot: sharedCacheRoot, dryRun: false });
+          const volumes = inspectWriteVolumes({ repoRoot, vaultRoot, cacheRoot: sharedCacheRoot });
+          assertWriteVolumeFloors({ volumes, policy, configuredRepoMinimumBytes: Math.max(Number(target.preflight?.minFreeGb ?? 25), 25) * 1024 ** 3 });
+        } else assertDiskSpace(repoRoot, target.preflight?.minFreeGb ?? 20);
         assertExecutables(["git", config.packageManager ?? "pnpm", "cargo", "rustc", ...(target.preflight?.executables ?? [])]);
         for (const name of target.preflight?.env ?? []) if (!process.env[name]) fail(`missing required environment variable: ${name}`);
         for (const command of target.preflight?.commands ?? []) runChecked(command.cmd, command.args ?? [], path.resolve(appRoot, command.cwd ?? "."), env);
@@ -141,6 +162,7 @@ try {
         checkpoint(stateRoot, "preflight_complete");
       },
       prepare: async () => {
+        throwIfInterrupted();
         const cacheTarget = env.CARGO_TARGET_DIR;
         const targetLink = path.join(appRoot, "src-tauri", "target");
         mkdirSync(cacheTarget, { recursive: true });
@@ -151,6 +173,7 @@ try {
         await runProgress(config.packageManager ?? "pnpm", ["install", "--frozen-lockfile"], appRoot, env, cacheTarget);
       },
       build: async () => {
+        throwIfInterrupted();
         await runProgress(
           process.execPath,
           [WORKER, "--config", worktreeConfigPath, "--platform", platform, "--no-upload"],
@@ -164,13 +187,22 @@ try {
       },
       seal: async ({ sealedDir }) => {
         sealRelease({ configRoot: path.dirname(worktreeConfigPath), sealedDir, releaseId, config, target, platform, commit, inputHashes, toolVersions, cacheKey });
+        verifySealedRelease(sealedDir);
+        if (cacheMode === "shared") markCacheEntrySuccessful({ layout: sharedLayout });
         checkpoint(stateRoot, "sealed");
       },
     },
   });
+  if (cacheMode === "shared") {
+    const snapshot = inspectCache({ cacheRoot: sharedCacheRoot });
+    const plan = planCachePrune({ snapshot, policy: readCachePolicy(process.env), protectedEntryIds: new Set([sharedLayout.id]) });
+    applyCachePrune({ plan, cacheRoot: sharedCacheRoot, dryRun: false });
+  }
   console.log(`right-release build: ${result.resumed ? "resumed" : "sealed"} ${result.releaseId}`);
   console.log(`sealed: ${result.sealedDir}`);
 } finally {
+  cacheLease?.release();
+  suiteSlot?.release();
   lock.release();
 }
 
@@ -374,6 +406,11 @@ function commandExists(name) {
   return probe.status === 0;
 }
 
+function assertSccacheVersion(version) {
+  const match = String(version ?? "").match(/sccache\s+(\d+)\.(\d+)\.(\d+)/i);
+  if (!match || Number(match[1]) === 0 && Number(match[2]) < 15) fail("shared cache requires sccache >= 0.15.0; install with: cargo install sccache --locked; then verify: sccache --version");
+}
+
 function commandOutput(cmd, runArgs) {
   try {
     return commandOutputPortable(cmd, runArgs);
@@ -419,5 +456,7 @@ function usage(code) {
 
 function fail(message) {
   console.error(`right-release build: ${message}`);
-  process.exit(1);
+  throw new Error(message);
 }
+
+function throwIfInterrupted() { if (interrupted) throw interrupted; }

package/build-release.test.mjs

@@ -0,0 +1,24 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import test from "node:test";
+
+const source = readFileSync(path.join(path.dirname(new URL(import.meta.url).pathname), "build-release.mjs"), "utf8");
+
+test("macOS builds default to Cache V2 while explicit legacy mode remains available", () => {
+  assert.match(source, /RIGHT_RELEASE_CACHE_MODE/);
+  assert.match(source, /platform === "mac" \? "shared" : "legacy"/);
+  assert.match(source, /cacheMode !== "legacy" && cacheMode !== "shared"/);
+  assert.match(source, /resolveSharedCacheRoot/);
+  assert.match(source, /acquireSuiteBuildSlot/);
+  assert.match(source, /acquireCacheLease/);
+  assert.match(source, /markCacheEntrySuccessful/);
+  assert.match(source, /RIGHT_RELEASE_CACHE_OWNER/);
+  assert.match(source, /suiteSlot\?\.release\(\)/);
+  assert.match(source, /cacheLease\?\.release\(\)/);
+  assert.doesNotMatch(source, /process\.exit\(signal/);
+  assert.match(source, /throwIfInterrupted/);
+  assert.match(source, /delete env\.RIGHT_RELEASE_CACHE_OWNER/);
+  assert.match(source, /assertPrimaryReleaseCheckout\(repoRoot\)/);
+  assert.match(source, /dirtyBuildInputs\(repoRoot/);
+});

package/cache-command.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  applyCachePrune,
+  inspectCache,
+  migrateLegacyCache,
+  planCachePrune,
+  readCachePolicy,
+  resolveCacheLayout,
+  resolveSharedCacheIdentity,
+  resolveSharedCacheRoot,
+} from "./cache-policy.mjs";
+import { resolveReleaseLayout } from "./release-state.mjs";
+
+export async function runCacheCommand(args = process.argv.slice(2), { env = process.env, stdout = console.log, stderr = console.error } = {}) {
+  const [command, ...rest] = args;
+  const json = rest.includes("--json");
+  const platform = platformFrom(env);
+  const cacheRoot = resolveSharedCacheRoot({ platform, env });
+  if (command === "status") {
+    rejectUnknown(rest, new Set(["--json"]));
+    const snapshot = inspectCache({ cacheRoot });
+    return output({ schema: 1, command, ...snapshot, policy: readCachePolicy(env) }, json, stdout);
+  }
+  if (command === "prune") {
+    rejectUnknown(rest, new Set(["--json", "--dry-run", "--apply"]));
+    if (rest.includes("--dry-run") && rest.includes("--apply")) throw new Error("cache prune accepts either --dry-run or --apply");
+    const dryRun = !rest.includes("--apply");
+    const snapshot = inspectCache({ cacheRoot });
+    const plan = planCachePrune({ snapshot, policy: readCachePolicy(env), protectedEntryIds: new Set(snapshot.entries.filter((entry) => entry.leased).map((entry) => entry.id)) });
+    const result = dryRun ? { candidateIds: plan.candidateIds, removedIds: [], reclaimedBytes: 0, dryRun: true } : applyCachePrune({ plan, cacheRoot, dryRun: false });
+    return output({ schema: 1, command, cacheRoot, dryRun, plan, ...result }, json, stdout);
+  }
+  if (command === "migrate") {
+    const configPath = option(rest, "--config");
+    if (!configPath) throw new Error("cache migrate requires --config <right-release.config.mjs>");
+    rejectUnknown(rest.filter((value) => value !== "--config" && value !== configPath), new Set(["--json", "--dry-run", "--apply"]));
+    if (rest.includes("--dry-run") && rest.includes("--apply")) throw new Error("cache migrate accepts either --dry-run or --apply");
+    const configFile = path.resolve(configPath);
+    const config = (await import(pathToFileURL(configFile).href)).default;
+    if (!config?.app) throw new Error("cache migrate config must expose app");
+    const appRoot = path.dirname(configFile);
+    const configuredTarget = config.targets?.[platform] ?? {};
+    const lockPath = path.join(appRoot, "src-tauri", "Cargo.lock");
+    const identity = resolveSharedCacheIdentity({ cargoLockPath: lockPath, cargoTomlPath: path.join(appRoot, "src-tauri", "Cargo.toml"), rustcVerbose: env.RIGHT_RELEASE_RUSTC_VERBOSE, targetTriple: configuredTarget.cargoTarget ?? configuredTarget.targetTriple ?? configuredTarget.rustTarget ?? env.TAURI_ENV_TARGET_TRIPLE, profile: configuredTarget.profile ?? "release" });
+    const fingerprint = env.RIGHT_RELEASE_CACHE_KEY || identity.fingerprint;
+    const layout = resolveCacheLayout({ cacheRoot, platform, architecture: identity.architecture, app: config.app, fingerprint, kind: "release" });
+    const dryRun = !rest.includes("--apply");
+    const legacy = resolveReleaseLayout({ repoRoot: findRepoRoot(appRoot), configPath: configFile });
+    const legacyTargetRoot = path.join(legacy.vaultRoot, "cache", "cargo-target", platform, fingerprint);
+    const result = migrateLegacyCache({ legacyRoot: path.join(appRoot, "src-tauri", "target"), legacyTargetRoot, legacyCargoHome: path.join(legacy.vaultRoot, "cache", "cargo-home"), legacyReleaseLockPath: path.join(legacy.vaultRoot, "locks", `${platform}.lock.json`), layout, app: config.app, dryRun });
+    return output({ schema: 1, command, cacheRoot, ...result }, json, stdout);
+  }
+  throw new Error("right-release cache: expected status, prune, or migrate");
+}
+
+function output(value, json, stdout) {
+  if (json) stdout(JSON.stringify(value));
+  else if (value.command === "status") stdout(`RightKit cache root: ${value.cacheRoot}\nTargets: ${value.targetBytes} bytes\nFree: ${(value.cacheFreeBytes / 1024 ** 3).toFixed(1)} GiB\nLeases: ${value.entries.filter((entry) => entry.leased).length}`);
+  else stdout(`RightKit cache ${value.command}: ${value.dryRun ? "dry-run" : "applied"}\nRoot: ${value.cacheRoot}\nCandidates: ${(value.candidateIds ?? value.plan?.candidateIds ?? []).join(", ") || "none"}\nReclaimed: ${value.reclaimedBytes ?? 0} bytes`);
+  return value;
+}
+
+function option(args, name) { const index = args.indexOf(name); return index >= 0 ? args[index + 1] : undefined; }
+function rejectUnknown(args, allowed) { for (const arg of args) if (!allowed.has(arg)) throw new Error(`unknown cache argument: ${arg}`); }
+function platformFrom(env) { return env.RIGHT_RELEASE_PLATFORM || (process.platform === "win32" ? "win" : process.platform === "darwin" ? "mac" : process.platform); }
+function findRepoRoot(start) { let current = path.resolve(start); for (;;) { if (existsSync(path.join(current, ".git"))) return current; const parent = path.dirname(current); if (parent === current) throw new Error(`cache migrate could not find Git repository for ${start}`); current = parent; } }
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runCacheCommand().catch((error) => { console.error(error.message); process.exitCode = 2; });
+}

package/cache-command.test.mjs

@@ -0,0 +1,73 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import test from "node:test";
+
+const root = path.dirname(new URL(import.meta.url).pathname);
+const cli = path.join(root, "cli", "right-release.mjs");
+
+function run(args, cacheRoot, env = {}) {
+  return spawnSync(process.execPath, [cli, "cache", ...args], { encoding: "utf8", env: { ...process.env, RIGHT_RELEASE_CACHE_ROOT: cacheRoot, ...env } });
+}
+
+test("cache status has human and schema-stable JSON output", () => {
+  const cacheRoot = mkdtempSync(path.join(os.tmpdir(), "rightkit-cache-command-"));
+  const human = run(["status"], cacheRoot);
+  const json = run(["status", "--json"], cacheRoot);
+  assert.equal(human.status, 0, human.stderr);
+  assert.match(human.stdout, /RightKit cache root:/);
+  assert.equal(json.status, 0, json.stderr);
+  assert.equal(JSON.parse(json.stdout).schema, 1);
+});
+
+test("cache prune defaults to dry-run and only apply can mutate an admitted temporary entry", () => {
+  const cacheRoot = mkdtempSync(path.join(os.tmpdir(), "rightkit-cache-command-"));
+  const target = path.join(cacheRoot, "targets", "mac", "fixture", "1111111111111111");
+  mkdirSync(target, { recursive: true });
+  writeFileSync(path.join(target, "payload"), "payload");
+  writeFileSync(path.join(target, ".rightkit-cache-entry.json"), JSON.stringify({ schema: 1, id: "target:mac:fixture:1111111111111111", kind: "release", platform: "mac", architecture: "aarch64", app: "fixture", fingerprint: "1111111111111111", createdAt: "2020-01-01T00:00:00.000Z", lastUsedAt: "2020-01-01T00:00:00.000Z", lastSuccessfulBuildAt: "2020-01-01T00:00:00.000Z", toolchain: {} }));
+  const dry = run(["prune", "--dry-run", "--json"], cacheRoot);
+  assert.equal(dry.status, 0, dry.stderr);
+  assert.equal(JSON.parse(dry.stdout).dryRun, true);
+  assert.equal(run(["prune", "--apply", "--json"], cacheRoot).status, 0);
+});
+
+test("cache rejects unknown commands and migration requires a config", () => {
+  const cacheRoot = mkdtempSync(path.join(os.tmpdir(), "rightkit-cache-command-"));
+  assert.notEqual(run(["unknown"], cacheRoot).status, 0);
+  assert.notEqual(run(["migrate"], cacheRoot).status, 0);
+});
+
+test("status and prune dry-run do not create a cache root or lock file", () => {
+  const parent = mkdtempSync(path.join(os.tmpdir(), "rightkit-cache-command-"));
+  const cacheRoot = path.join(parent, "never-created");
+  assert.equal(run(["status", "--json"], cacheRoot).status, 0);
+  assert.equal(run(["prune", "--dry-run", "--json"], cacheRoot).status, 0);
+  assert.equal(existsSync(cacheRoot), false);
+});
+
+test("cache migrate uses the repository vault Cargo home, not an app-local lookalike", () => {
+  const sandbox = mkdtempSync(path.join(os.tmpdir(), "rightkit-cache-command-"));
+  const repo = path.join(sandbox, "repo"); const app = path.join(repo, "app"); const cacheRoot = path.join(sandbox, "shared-cache");
+  const config = path.join(app, "right-release.config.mjs"); const fingerprint = "abcdef0123456789";
+  const target = path.join(repo, ".right-release", "cache", "cargo-target", "mac", fingerprint);
+  const vaultCargoHome = path.join(repo, ".right-release", "cache", "cargo-home");
+  const appCargoHome = path.join(app, ".right-release", "cache", "cargo-home");
+  mkdirSync(path.join(repo, ".git"), { recursive: true });
+  mkdirSync(path.dirname(config), { recursive: true });
+  writeFileSync(config, "export default { app: 'fixture', targets: { mac: { targetTriple: 'aarch64-apple-darwin' } } };\n");
+  mkdirSync(path.join(app, "src-tauri"), { recursive: true });
+  writeFileSync(path.join(app, "src-tauri", "Cargo.lock"), "fixture-lock\n");
+  writeFileSync(path.join(app, "src-tauri", "Cargo.toml"), "[package]\nname = 'fixture'\n");
+  mkdirSync(target, { recursive: true }); writeFileSync(path.join(target, "artifact"), "target");
+  symlinkSync(target, path.join(app, "src-tauri", "target"));
+  mkdirSync(vaultCargoHome, { recursive: true }); writeFileSync(path.join(vaultCargoHome, "registry"), "vault");
+  mkdirSync(appCargoHome, { recursive: true }); writeFileSync(path.join(appCargoHome, "registry"), "app-local");
+  const result = run(["migrate", "--config", config, "--apply", "--json"], cacheRoot, { RIGHT_RELEASE_PLATFORM: "mac", RIGHT_RELEASE_RUSTC_VERBOSE: "rustc 1.91.0\nhost: aarch64-apple-darwin", RIGHT_RELEASE_CACHE_KEY: fingerprint });
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(JSON.parse(result.stdout).cargoHomeMoved, true);
+  assert.equal(readFileSync(path.join(cacheRoot, "cargo-home", "registry"), "utf8"), "vault");
+  assert.equal(readFileSync(path.join(appCargoHome, "registry"), "utf8"), "app-local");
+});

package/cache-policy.mjs

@@ -0,0 +1,423 @@
+import {
+  closeSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  statfsSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+
+export const CACHE_SCHEMA = 1;
+export const DEFAULT_TARGET_MAX_BYTES = 12 * 1024 ** 3;
+export const DEFAULT_SCCACHE_MAX_BYTES = 8 * 1024 ** 3;
+export const DEFAULT_DESIRED_FREE_BYTES = 60 * 1024 ** 3;
+export const DEFAULT_HARD_FREE_BYTES = 25 * 1024 ** 3;
+// Any build holds release -> suite slot -> GC -> entry lease; prune holds only GC.
+export const CACHE_LOCK_ORDER = ["release", "suite-build-slot", "gc", "entry-lease"];
+
+const MARKER = ".rightkit-cache-entry.json";
+
+export function resolveSharedCacheRoot({ platform = process.platform, env = process.env, home = os.homedir(), xdgCacheHome } = {}) {
+  const override = env.RIGHT_RELEASE_CACHE_ROOT;
+  if (override) {
+    if (!isAbsoluteForPlatform(override, platform)) throw new Error("RIGHT_RELEASE_CACHE_ROOT must be an absolute path");
+    return resolveForPlatform(override, platform);
+  }
+  if (platform === "darwin" || platform === "mac") return path.join(home, "Library", "Caches", "RightSuite", "release");
+  if (platform === "win32" || platform === "win") {
+    const local = env.LOCALAPPDATA;
+    if (!local || !isAbsoluteForPlatform(local, platform)) throw new Error("LOCALAPPDATA must be an absolute path for the RightSuite cache");
+    return path.win32.resolve(local, "RightSuite", "Cache", "release");
+  }
+  return path.resolve(xdgCacheHome || env.XDG_CACHE_HOME || path.join(home, ".cache"), "rightsuite", "release");
+}
+
+export function resolveCacheLayout({ cacheRoot, platform, architecture, app, fingerprint, kind = "release" } = {}) {
+  if (!cacheRoot || !path.isAbsolute(cacheRoot)) throw new Error("cacheRoot must be an absolute path");
+  if (kind !== "release" && kind !== "test") throw new Error(`invalid cache target kind: ${kind}`);
+  for (const [name, value] of Object.entries({ platform, architecture, app, fingerprint })) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(String(value || ""))) throw new Error(`invalid cache ${name}`);
+  }
+  const root = path.resolve(cacheRoot);
+  const targetRoot = path.join(root, kind === "release" ? "targets" : "test-targets");
+  const targetDir = path.join(targetRoot, platform, app, fingerprint);
+  assertLexicalInside(targetRoot, targetDir);
+  const id = `${kind === "release" ? "target" : "test-target"}:${platform}:${app}:${fingerprint}`;
+  return {
+    cacheRoot: root,
+    targetRoot,
+    targetDir,
+    markerPath: path.join(targetDir, MARKER),
+    cargoHome: path.join(root, "cargo-home"),
+    sccacheDir: path.join(root, "sccache"),
+    leasesDir: path.join(root, "leases"),
+    leasePath: path.join(root, "leases", `${encodeURIComponent(id)}.json`),
+    suiteSlotPath: path.join(root, "leases", "suite-build-slot.json"),
+    gcLockPath: path.join(root, "gc", "gc.lock.json"),
+    migrationDir: path.join(root, "migration"),
+    platform,
+    architecture,
+    app,
+    fingerprint,
+    kind,
+    id,
+  };
+}
+
+export function readCachePolicy(env = process.env) {
+  return {
+    targetMaxBytes: readPositive(env.RIGHT_RELEASE_TARGET_MAX_BYTES, DEFAULT_TARGET_MAX_BYTES),
+    sccacheMaxBytes: readPositive(env.RIGHT_RELEASE_SCCACHE_MAX_BYTES, DEFAULT_SCCACHE_MAX_BYTES),
+    desiredFreeBytes: readPositive(env.RIGHT_RELEASE_DESIRED_FREE_BYTES, DEFAULT_DESIRED_FREE_BYTES),
+    hardFreeBytes: readPositive(env.RIGHT_RELEASE_HARD_FREE_BYTES, DEFAULT_HARD_FREE_BYTES),
+  };
+}
+
+export function resolveSharedCacheIdentity({ cargoLockPath, cargoTomlPath, rustcVerbose, targetTriple, profile = "release", features } = {}) {
+  const rustc = rustcVerbose ?? readRustcVerbose();
+  const host = rustc.match(/^host:\s*(.+)$/m)?.[1];
+  if (!host) throw new Error("rustc -vV did not report a host target triple");
+  const target = targetTriple || host;
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(target)) throw new Error("invalid Cargo target triple");
+  const architecture = target.split("-")[0];
+  const cargoLockSha256 = cargoLockPath && existsSync(cargoLockPath) ? createHash("sha256").update(readFileSync(cargoLockPath)).digest("hex") : "none";
+  const nativeFeatures = features ?? cargoNativeFeatures(cargoTomlPath);
+  const payload = JSON.stringify({ cargoLockSha256, rustc, target, architecture, profile, features: [...nativeFeatures].sort() });
+  return { cargoLockSha256, rustc, target, architecture, profile, features: [...nativeFeatures].sort(), fingerprint: createHash("sha256").update(payload).digest("hex").slice(0, 16) };
+}
+
+export function ensureCacheEntry({ layout, metadata = {}, now = new Date() } = {}) {
+  requireLayout(layout);
+  const root = resolvedRoot(layout.cacheRoot);
+  const targetDir = safeEntryDirectory(root, layout);
+  mkdirSafeDescendant(root, targetDir);
+  assertPhysicalInside(path.join(root, layout.kind === "release" ? "targets" : "test-targets"), targetDir);
+  const markerPath = path.join(targetDir, MARKER);
+  let entry = readJson(markerPath);
+  if (entry && !validEntry(entry, layout)) throw new Error(`invalid cache entry marker: ${markerPath}`);
+  if (!entry) {
+    const at = iso(now);
+    entry = {
+      schema: CACHE_SCHEMA, id: layout.id, kind: layout.kind, platform: layout.platform,
+      architecture: layout.architecture, app: layout.app, fingerprint: layout.fingerprint,
+      createdAt: at, lastUsedAt: at, lastSuccessfulBuildAt: null,
+      toolchain: metadata.toolchain ?? { cargo: "unknown", rustc: "unknown", host: "unknown" },
+    };
+    atomicJson(markerPath, entry);
+  }
+  return entry;
+}
+
+export function acquireCacheLease({ layout, pid = process.pid, argv = process.argv, now = new Date() } = {}) {
+  requireLayout(layout);
+  const payload = { schema: CACHE_SCHEMA, id: layout.id, pid: Number(pid), argv: [...argv], createdAt: iso(now) };
+  const root = resolvedRoot(layout.cacheRoot);
+  const gcPayload = { schema: CACHE_SCHEMA, pid: Number(pid), argv: [...argv], createdAt: iso(now), order: CACHE_LOCK_ORDER };
+  acquireAtomicLock(path.join(root, "gc", "gc.lock.json"), gcPayload, "global GC lock", now);
+  try {
+    ensureCacheEntry({ layout, now });
+    acquireAtomicLock(layout.leasePath, payload, "cache entry lease", now);
+    touchEntry(layout, now);
+    return releaseFor(layout.leasePath, payload);
+  } finally {
+    releaseFor(path.join(root, "gc", "gc.lock.json"), gcPayload).release();
+  }
+}
+
+export function acquireSuiteBuildSlot({ layout, pid = process.pid, argv = process.argv, waitMs = 900_000, now = new Date(), sleep = defaultSleep } = {}) {
+  requireLayout(layout);
+  const started = Date.now();
+  const payload = { schema: CACHE_SCHEMA, pid: Number(pid), argv: [...argv], createdAt: iso(now) };
+  for (;;) {
+    try {
+      acquireAtomicLock(layout.suiteSlotPath, payload, "suite build slot", new Date());
+      return releaseFor(layout.suiteSlotPath, payload);
+    } catch (error) {
+      if (!/active/i.test(error.message)) throw error;
+      if (Date.now() - started >= waitMs) throw new Error(`${error.message}; suite build slot timed out after ${waitMs}ms without alternate-target fallback`);
+      sleep(Math.min(250, Math.max(1, waitMs - (Date.now() - started))));
+    }
+  }
+}
+
+export function markCacheEntrySuccessful({ layout, now = new Date() } = {}) {
+  requireLayout(layout);
+  const entry = readJson(layout.markerPath);
+  if (!validEntry(entry, layout)) throw new Error(`invalid cache entry marker: ${layout.markerPath}`);
+  entry.lastUsedAt = iso(now);
+  entry.lastSuccessfulBuildAt = iso(now);
+  atomicJson(layout.markerPath, entry);
+  return entry;
+}
+
+export function inspectCache({ cacheRoot, statfs = statfsSync, now = new Date() } = {}) {
+  const root = readonlyRoot(cacheRoot);
+  if (!root) return { cacheRoot: path.resolve(cacheRoot), entries: [], targetBytes: 0, cacheFreeBytes: 0, device: undefined, inspectedAt: iso(now) };
+  const entries = [];
+  for (const kind of ["targets", "test-targets"]) {
+    const kindRoot = path.join(root, kind);
+    if (!existsSync(kindRoot) || lstatSync(kindRoot).isSymbolicLink()) continue;
+    for (const platformEntry of safeDirEntries(kindRoot)) for (const appEntry of safeDirEntries(platformEntry.path)) for (const fingerprintEntry of safeDirEntries(appEntry.path)) {
+      const dir = fingerprintEntry.path;
+      const markerPath = path.join(dir, MARKER);
+      const marker = readJson(markerPath);
+      const expectedKind = kind === "targets" ? "release" : "test";
+      const layout = marker ? resolveCacheLayout({ cacheRoot: root, platform: marker.platform, architecture: marker.architecture, app: marker.app, fingerprint: marker.fingerprint, kind: expectedKind }) : null;
+      if (!layout || layout.targetDir !== dir || !validEntry(marker, layout)) continue;
+      const leasePath = path.join(root, "leases", `${encodeURIComponent(marker.id)}.json`);
+      const lease = readJson(leasePath);
+      const live = isLiveLease(lease, now);
+      entries.push({ id: marker.id, dir, marker, bytes: directoryBytes(dir), leased: live, lease: live ? lease : null });
+    }
+  }
+  const fs = statfs(root, { bigint: false });
+  return { cacheRoot: root, entries, targetBytes: entries.filter((x) => x.marker.kind === "release").reduce((sum, x) => sum + x.bytes, 0), cacheFreeBytes: freeBytes(fs), device: fs.dev ?? safeDevice(root), inspectedAt: iso(now) };
+}
+
+export function inspectWriteVolumes({ repoRoot, vaultRoot, cacheRoot, statfs = statfsSync } = {}) {
+  const paths = [
+    { role: "repo", path: path.resolve(repoRoot || vaultRoot) },
+    { role: "cache", path: path.resolve(cacheRoot) },
+  ];
+  const volumes = [];
+  for (const item of paths) {
+    const fs = statfs(item.path, { bigint: false });
+    const device = fs.dev ?? safeDevice(item.path) ?? `${fs.type}:${item.path}`;
+    const existing = volumes.find((volume) => String(volume.device) === String(device));
+    if (existing) { existing.roles.push(item.role); existing.paths.push(item.path); continue; }
+    volumes.push({ device, roles: [item.role], paths: [item.path], freeBytes: freeBytes(fs) });
+  }
+  return volumes;
+}
+
+export function assertWriteVolumeFloors({ volumes, policy = readCachePolicy(), configuredRepoMinimumBytes = DEFAULT_HARD_FREE_BYTES } = {}) {
+  for (const volume of volumes ?? []) {
+    const repoRequired = volume.roles.includes("repo") ? Math.max(configuredRepoMinimumBytes, DEFAULT_HARD_FREE_BYTES) : 0;
+    const cacheRequired = volume.roles.includes("cache") ? policy.hardFreeBytes : 0;
+    const required = Math.max(repoRequired, cacheRequired);
+    if (volume.freeBytes < required) throw new Error(`insufficient free space on ${volume.roles.join("+")} volume ${volume.device}: ${(volume.freeBytes / 1024 ** 3).toFixed(1)} GiB free, ${(required / 1024 ** 3).toFixed(1)} GiB required`);
+  }
+  return true;
+}
+
+export function planCachePrune({ snapshot, policy = readCachePolicy(), protectedEntryIds = new Set() } = {}) {
+  const protectedIds = new Set(protectedEntryIds);
+  const candidates = (snapshot.entries ?? [])
+    .filter((entry) => entry.marker?.kind === "release" && !entry.leased && !protectedIds.has(entry.id))
+    .sort((a, b) => String(a.marker.lastSuccessfulBuildAt ?? a.marker.lastUsedAt ?? a.marker.createdAt).localeCompare(String(b.marker.lastSuccessfulBuildAt ?? b.marker.lastUsedAt ?? b.marker.createdAt)) || a.id.localeCompare(b.id));
+  let bytes = snapshot.targetBytes ?? 0;
+  let free = snapshot.cacheFreeBytes ?? Infinity;
+  const selected = [];
+  for (const entry of candidates) {
+    if (bytes <= policy.targetMaxBytes && free >= policy.desiredFreeBytes) break;
+    selected.push({ id: entry.id, dir: entry.dir, bytes: entry.bytes, reason: bytes > policy.targetMaxBytes ? "target-cap" : "free-space" });
+    bytes -= entry.bytes; free += entry.bytes;
+  }
+  return { schema: CACHE_SCHEMA, cacheRoot: snapshot.cacheRoot, candidateIds: selected.map((entry) => entry.id), candidates: selected, estimatedReclaimedBytes: selected.reduce((sum, entry) => sum + entry.bytes, 0), targetBytesAfter: bytes, cacheFreeBytesAfter: free };
+}
+
+export function applyCachePrune({ plan, cacheRoot, dryRun = true, beforeDelete } = {}) {
+  const result = { candidateIds: (plan?.candidates ?? []).map((entry) => entry.id), removedIds: [], reclaimedBytes: 0, dryRun };
+  if (dryRun) return result;
+  const root = resolvedRoot(cacheRoot || plan?.cacheRoot);
+  const lockPath = path.join(root, "gc", "gc.lock.json");
+  const lockPayload = { schema: CACHE_SCHEMA, pid: process.pid, argv: process.argv, createdAt: iso(new Date()), order: CACHE_LOCK_ORDER };
+  acquireAtomicLock(lockPath, lockPayload, "global GC lock", new Date());
+  try {
+    for (const candidate of plan?.candidates ?? []) {
+      if (!safePruneCandidate(root, candidate)) continue;
+      beforeDelete?.(candidate);
+      if (!safePruneCandidate(root, candidate)) continue;
+      if (!dryRun) {
+        rmSync(realpathSync(candidate.dir), { recursive: true, force: false, maxRetries: 2 });
+        result.removedIds.push(candidate.id); result.reclaimedBytes += candidate.bytes ?? 0;
+      }
+    }
+  } finally {
+    releaseFor(lockPath, lockPayload).release();
+  }
+  return result;
+}
+
+export function migrateLegacyCache({ legacyRoot, legacyTargetRoot, legacyCargoHome, legacyReleaseLockPath, layout, app, dryRun = true, waitMs = 0, onPostMove, writeMigrationReceipt = atomicJson } = {}) {
+  requireLayout(layout);
+  if (app !== layout.app) throw new Error("legacy cache app must match cache layout");
+  const root = dryRun ? path.resolve(layout.cacheRoot) : resolvedRoot(layout.cacheRoot);
+  const receipt = path.join(root, "migration", `${app}.json`);
+  const existing = readJson(receipt);
+  if (existing) return { ...existing, resumed: true, dryRun };
+  const linkPath = path.resolve(legacyRoot);
+  const target = layout.targetDir;
+  const initial = resolveLegacyMigrationSource({ linkPath, legacyTargetRoot, layout });
+  const outcome = { schema: CACHE_SCHEMA, app, legacyRoot: initial.source, target, dryRun, moved: false, coldCache: false, cargoHomeMoved: false, deferredLegacyCargoHome: null, createdAt: iso(new Date()) };
+  if (initial.coldCache) return persistMigrationOutcome({ outcome: { ...outcome, coldCache: true }, receipt, root, dryRun });
+  if (pathEntryExists(target)) throw new Error(`cache migration target already exists: ${target}`);
+  if (dryRun) return outcome;
+
+  let suiteSlot;
+  let gcExclusion;
+  try {
+    suiteSlot = acquireSuiteBuildSlot({ layout, pid: process.pid, argv: process.argv, waitMs });
+    gcExclusion = acquireMigrationGcExclusion({ layout });
+    assertMigrationIdle({ legacyReleaseLockPath, layout });
+    const { source } = resolveLegacyMigrationSource({ linkPath, legacyTargetRoot, layout });
+    const actualTarget = safeEntryDirectory(root, layout);
+    const targetParent = path.dirname(actualTarget);
+    mkdirSafeDescendant(root, targetParent);
+    const sourceDevice = safeDevice(source);
+    if (sourceDevice !== undefined && sourceDevice !== safeDevice(targetParent)) return persistMigrationOutcome({ outcome: { ...outcome, coldCache: true }, receipt, root, dryRun });
+
+    let movedTarget = false;
+    let createdMarker = false;
+    let movedCargoHome = false;
+    let replacedEmptyCargoHome = false;
+    const sharedCargoHome = path.join(root, "cargo-home");
+    try {
+      renameSync(source, actualTarget); movedTarget = true;
+      onPostMove?.("after-target-move");
+      createdMarker = !existsSync(path.join(actualTarget, MARKER));
+      ensureCacheEntry({ layout });
+      onPostMove?.("after-entry-marker");
+      if (legacyCargoHome && existsSync(legacyCargoHome)) {
+        if (lstatSync(legacyCargoHome).isSymbolicLink()) throw new Error(`legacy Cargo home migration refuses symlink source: ${legacyCargoHome}`);
+        if (!existsSync(sharedCargoHome)) {
+          renameSync(legacyCargoHome, sharedCargoHome); outcome.cargoHomeMoved = movedCargoHome = true;
+        } else if (isEmptyDirectory(sharedCargoHome)) {
+          rmSync(sharedCargoHome, { recursive: true, force: false }); replacedEmptyCargoHome = true;
+          renameSync(legacyCargoHome, sharedCargoHome); outcome.cargoHomeMoved = movedCargoHome = true;
+        } else outcome.deferredLegacyCargoHome = path.resolve(legacyCargoHome);
+      }
+      onPostMove?.("after-cargo-home-move");
+      mkdirSafeDescendant(root, path.join(root, "migration"));
+      onPostMove?.("before-receipt");
+      writeMigrationReceipt(receipt, { ...outcome, moved: true, dryRun: false, completedAt: iso(new Date()) });
+      outcome.moved = true;
+      if (linkPath !== source) { try { if (lstatSync(linkPath).isSymbolicLink()) unlinkSync(linkPath); } catch { /* already absent */ } }
+    } catch (error) {
+      if (movedCargoHome && existsSync(sharedCargoHome) && !existsSync(legacyCargoHome)) renameSync(sharedCargoHome, legacyCargoHome);
+      if (replacedEmptyCargoHome && !existsSync(sharedCargoHome)) mkdirSafeDescendant(root, sharedCargoHome);
+      if (movedTarget && existsSync(actualTarget) && !existsSync(source)) {
+        if (createdMarker) safeUnlink(path.join(actualTarget, MARKER));
+        renameSync(actualTarget, source);
+      }
+      throw error;
+    }
+    return outcome;
+  } finally {
+    gcExclusion?.release();
+    suiteSlot?.release();
+  }
+}
+
+function persistMigrationOutcome({ outcome, receipt, root, dryRun }) { if (!dryRun) { mkdirSafeDescendant(root, path.join(root, "migration")); atomicJson(receipt, { ...outcome, dryRun: false, completedAt: iso(new Date()) }); } return outcome; }
+
+function resolveLegacyMigrationSource({ linkPath, legacyTargetRoot, layout }) {
+  if (!pathEntryExists(linkPath)) return { source: linkPath, coldCache: true };
+  if (!lstatSync(linkPath).isSymbolicLink()) return { source: linkPath, coldCache: false };
+  if (!legacyTargetRoot) throw new Error(`legacy cache migration refuses unexpected target link: ${linkPath}`);
+  const declared = path.resolve(legacyTargetRoot);
+  const legacyCargoTargetRoot = path.resolve(declared, "..", "..");
+  const exactFingerprintDir = path.join(legacyCargoTargetRoot, layout.platform, layout.fingerprint);
+  if (declared !== exactFingerprintDir) throw new Error(`legacy cache migration refuses unexpected target link: ${linkPath}`);
+  let physical;
+  let expected;
+  let legacyRoot;
+  try {
+    physical = realpathSync(linkPath);
+    expected = realpathSync(exactFingerprintDir);
+    legacyRoot = realpathSync(legacyCargoTargetRoot);
+  } catch { throw new Error(`legacy cache migration refuses unexpected target link: ${linkPath}`); }
+  try { assertLexicalInside(legacyRoot, expected); } catch { throw new Error(`legacy cache migration refuses unexpected target link: ${linkPath}`); }
+  if (physical !== expected) throw new Error(`legacy cache migration refuses unexpected target link: ${linkPath}`);
+  return { source: physical, coldCache: false };
+}
+
+function acquireMigrationGcExclusion({ layout }) {
+  const payload = { schema: CACHE_SCHEMA, pid: process.pid, argv: process.argv, createdAt: iso(new Date()), order: CACHE_LOCK_ORDER };
+  acquireAtomicLock(layout.gcLockPath, payload, "global GC lock", new Date());
+  return releaseFor(layout.gcLockPath, payload);
+}
+
+function assertMigrationIdle({ legacyReleaseLockPath, layout }) {
+  if (legacyReleaseLockPath && pathEntryExists(legacyReleaseLockPath)) throw new Error(`cache migrate refused: legacy release lock is live: ${legacyReleaseLockPath}`);
+  for (const entry of safeLeaseEntries(layout.leasesDir)) {
+    if (entry.name === path.basename(layout.suiteSlotPath)) continue;
+    if (entry.symbolicLink) throw new Error(`cache migrate refused: unsafe shared lease path: ${entry.path}`);
+    if (!entry.file) continue;
+    const lease = readJson(entry.path);
+    if (isLiveLease(lease)) throw new Error(`cache migrate refused: shared entry lease is live: pid ${lease.pid}`);
+  }
+}
+
+function requireLayout(layout) { if (!layout?.targetDir || !layout?.cacheRoot) throw new Error("cache layout is required"); }
+function readPositive(value, fallback) { if (value === undefined || value === "") return fallback; const number = Number(value); if (!Number.isFinite(number) || number <= 0) throw new Error("cache policy values must be positive byte counts"); return number; }
+function iso(value) { return new Date(value).toISOString(); }
+function pathEntryExists(file) { try { lstatSync(file); return true; } catch (error) { if (error?.code === "ENOENT") return false; throw error; } }
+function resolvedRoot(cacheRoot) { if (!cacheRoot || !path.isAbsolute(cacheRoot)) throw new Error("cacheRoot must be an absolute path"); if (existsSync(cacheRoot) && lstatSync(cacheRoot).isSymbolicLink()) throw new Error(`unsafe symlink cache root: ${cacheRoot}`); mkdirSync(cacheRoot, { recursive: true }); if (lstatSync(cacheRoot).isSymbolicLink()) throw new Error(`unsafe symlink cache root: ${cacheRoot}`); return realpathSync(cacheRoot); }
+function readonlyRoot(cacheRoot) { if (!cacheRoot || !path.isAbsolute(cacheRoot)) throw new Error("cacheRoot must be an absolute path"); if (!existsSync(cacheRoot)) return null; if (lstatSync(cacheRoot).isSymbolicLink()) throw new Error(`unsafe symlink cache root: ${cacheRoot}`); return realpathSync(cacheRoot); }
+function atomicJson(file, value) { mkdirSync(path.dirname(file), { recursive: true }); const temp = `${file}.tmp-${process.pid}-${Math.random().toString(16).slice(2)}`; writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 }); renameSync(temp, file); }
+function readJson(file) { try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; } }
+function validEntry(entry, layout) { return Boolean(entry && entry.schema === CACHE_SCHEMA && entry.id === layout.id && entry.kind === layout.kind && entry.platform === layout.platform && entry.architecture === layout.architecture && entry.app === layout.app && entry.fingerprint === layout.fingerprint && typeof entry.createdAt === "string" && typeof entry.lastUsedAt === "string" && Object.prototype.hasOwnProperty.call(entry, "lastSuccessfulBuildAt") && entry.toolchain && typeof entry.toolchain === "object"); }
+function assertLexicalInside(parent, child) { const relative = path.relative(path.resolve(parent), path.resolve(child)); if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw new Error("cache path escapes its root"); }
+function assertPhysicalInside(parent, child) { const parentReal = realpathSync(parent); const childReal = realpathSync(child); assertLexicalInside(parentReal, childReal); }
+function safeDirEntries(dir) { try { return readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.isSymbolicLink()).map((entry) => ({ name: entry.name, path: path.join(dir, entry.name) })); } catch { return []; } }
+function safeLeaseEntries(dir) { try { return readdirSync(dir, { withFileTypes: true }).map((entry) => ({ name: entry.name, path: path.join(dir, entry.name), file: entry.isFile(), symbolicLink: entry.isSymbolicLink() })); } catch (error) { if (error?.code === "ENOENT") return []; throw error; } }
+function directoryBytes(dir) { let bytes = 0; const walk = (item) => { const stat = lstatSync(item); if (stat.isSymbolicLink()) return; if (stat.isDirectory()) for (const child of readdirSync(item)) walk(path.join(item, child)); else bytes += stat.size; }; try { walk(dir); } catch { return 0; } return bytes; }
+function freeBytes(fs) { return Number(fs.bavail) * Number(fs.bsize); }
+function safeDevice(dir) { try { return statSync(dir).dev; } catch { return undefined; } }
+function isEmptyDirectory(dir) { try { return readdirSync(dir).length === 0; } catch { return false; } }
+function isLiveLease(lease) { return Boolean(lease && Number.isInteger(Number(lease.pid)) && Number(lease.pid) > 0 && processIsAlive(lease.pid)); }
+function processIsAlive(pid) { try { process.kill(Number(pid), 0); return true; } catch (error) { return error?.code === "EPERM"; } }
+function safeUnlink(file) { try { unlinkSync(file); } catch { /* already gone */ } }
+function acquireAtomicLock(file, payload, label, now) {
+  mkdirSync(path.dirname(file), { recursive: true });
+  try { const fd = openSync(file, "wx", 0o600); writeFileSync(fd, `${JSON.stringify(payload)}\n`); closeSync(fd); return; } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    const holder = readJson(file);
+    if (!isLiveLease(holder, now)) { safeUnlink(file); return acquireAtomicLock(file, payload, label, now); }
+    throw new Error(`${label} active: pid ${holder.pid}`);
+  }
+}
+function releaseFor(file, payload) { let released = false; return { release() { if (released) return; released = true; const current = readJson(file); if (current?.pid === payload.pid && current?.createdAt === payload.createdAt) safeUnlink(file); } }; }
+function touchEntry(layout, now) { const entry = readJson(layout.markerPath); if (!validEntry(entry, layout)) throw new Error(`invalid cache entry marker: ${layout.markerPath}`); entry.lastUsedAt = iso(now); atomicJson(layout.markerPath, entry); }
+function defaultSleep(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
+function safePruneCandidate(root, candidate) {
+  if (!candidate?.dir || path.resolve(candidate.dir) === root) return false;
+  if (!existsSync(candidate.dir) || lstatSync(candidate.dir).isSymbolicLink()) return false;
+  const dir = realpathSync(candidate.dir); const targets = [path.join(root, "targets"), path.join(root, "test-targets")];
+  const targetRoot = targets.find((item) => { try { assertLexicalInside(item, dir); return true; } catch { return false; } });
+  if (!targetRoot) return false;
+  try {
+    assertPhysicalInside(targetRoot, dir);
+    const marker = readJson(path.join(dir, MARKER));
+    const kind = targetRoot.endsWith(`${path.sep}targets`) ? "release" : "test";
+    const layout = marker && resolveCacheLayout({ cacheRoot: root, platform: marker.platform, architecture: marker.architecture, app: marker.app, fingerprint: marker.fingerprint, kind });
+    return Boolean(layout && layout.targetDir === dir && marker.id === candidate.id && validEntry(marker, layout) && !isLiveLease(readJson(layout.leasePath), new Date()));
+  } catch { return false; }
+}
+function safeEntryDirectory(root, layout) { return path.join(root, layout.kind === "release" ? "targets" : "test-targets", layout.platform, layout.app, layout.fingerprint); }
+function mkdirSafeDescendant(root, dir) {
+  assertLexicalInside(root, dir);
+  let current = root;
+  for (const part of path.relative(root, dir).split(path.sep)) {
+    current = path.join(current, part);
+    if (existsSync(current)) { if (lstatSync(current).isSymbolicLink()) throw new Error(`unsafe symlink cache ancestor: ${current}`); }
+    else mkdirSync(current);
+  }
+}
+function isAbsoluteForPlatform(value, platform) { return platform === "win" || platform === "win32" ? path.win32.isAbsolute(value) : path.isAbsolute(value); }
+function resolveForPlatform(value, platform) { return platform === "win" || platform === "win32" ? path.win32.resolve(value) : path.resolve(value); }
+function readRustcVerbose() { const result = spawnSync("rustc", ["-vV"], { encoding: "utf8", windowsHide: true }); if (result.status !== 0) throw new Error(`rustc -vV failed: ${(result.stderr || result.error?.message || `exit ${result.status}`).trim()}`); return result.stdout.trim(); }
+function cargoNativeFeatures(cargoTomlPath) { if (!cargoTomlPath || !existsSync(cargoTomlPath)) return []; return [...readFileSync(cargoTomlPath, "utf8").matchAll(/features\s*=\s*\[([^\]]+)\]/g)].flatMap((match) => match[1].match(/"([^"]+)"/g) ?? []).map((value) => value.slice(1, -1)).filter((value) => /sqlcipher|openssl/i.test(value)); }

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.39",
   "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-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,
   };
 }
 

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");
 }

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));

package/right-suite-contract.test.mjs

@@ -317,7 +317,7 @@ test("Cargo version contract rejects staged versions that mismatch canonical man
 test("RightKit exposes one current version manifest", () => {
   assert.equal(existsSync(versionsPath), true, "rightkit-versions.json must be the single current-version source");
   assert.match(versions.packageManager, /^pnpm@\d+\.\d+\.\d+$/);
-  assert.equal(versions.npm["@rightkit/release"], "0.2.38");
+  assert.equal(versions.npm["@rightkit/release"], "0.2.39");
   assert.equal(versions.npm["@rightkit/legal"], "0.2.0");
   assert.equal(versions.npm["@rightkit/license"], "0.1.5");
   assert.equal(versions.npm["@rightkit/logs"], "0.1.3");

package/rightkit-versions.json

@@ -7,7 +7,7 @@
     "@rightkit/logs": "0.1.3",
     "@rightkit/platform-ui": "0.1.0",
     "@rightkit/qa": "0.1.0",
-    "@rightkit/release": "0.2.38",
+    "@rightkit/release": "0.2.39",
     "@rightkit/tauri": "0.1.0",
     "@rightkit/updates": "0.2.3"
   },