@rightkit/release 0.6.8 → 0.6.11

package/build-release.mjs

@@ -20,13 +20,16 @@ import {
 import path from "node:path";
 import { preflightOwnershipScope } from "./ownership-scope.mjs";
 import { spawn, spawnSync } from "./background-process.mjs";
+import { spawnUnderOwnership } from "./build-ownership.mjs";
 import { RightKitRegistryError, SNAPSHOT_ENV, SNAPSHOT_FILE, assertManifestRegistryEvidence, loadAdmittedSnapshot, prepareRightKitResolution, registryManifestFields, rightKitLockInventory, writeAdmissionRecord, writeSnapshot } from "./rightkit-registry-resolver.mjs";
 import { formatAdmission, formatNotRun, runAdmission } from "./admission.mjs";
 import { sccacheRefusal } from "./admission-host.mjs";
 import { defaultReleaseConfigFile, importReleaseConfig } from "./release-config.mjs";
 import { fileURLToPath } from "node:url";
-import { assertPrimaryReleaseCheckout, dirtyBuildInputs, resolveReleaseBuildInputs } from "./release-invocation.mjs";
+import { dirtyBuildInputs, resolveReleaseBuildInputs } from "./release-invocation.mjs";
+import { assertInsideSource, assertReleaseSource, gitRootOf, isSnapshotSource, qaAdmissionSourceOptions, resolveReleaseSource, sourceRootOf } from "./release-source-identity.mjs";
 import { resolveNativeCargoLayout } from "./native-cargo-layout.mjs";
+import { ArtifactPathError, assertSplitCommandPaths, boundTargetsEvidence, releaseCommandSteps, resolveArtifactPath as resolveSplitArtifactPath, splitArtifactContext } from "./release-artifact-path.mjs";
 import { admitSourceQa } from "./release-qa-audit.mjs";
 import { devtoolsEvidence, resolveDevtoolsAllowance } from "./devtools-policy.mjs";
 import { commandOutputPortable, releaseEnvironment, resolveReleaseLayout, runBuildStateMachine, verifySealedRelease, watchProgress } from "./release-state.mjs";
@@ -43,7 +46,6 @@ import { collectSwiftToolVersions, planSwiftBuild } from "./swift-build-context.
 import { planIosNativeBuild, resolveIosBuildContext } from "./ios-build-context.mjs";
 import { packageCommandOptional, requiredBuildExecutables, resolveProjectType, targetUsesMsix } from "./project-type.mjs";
 import { buildPathPrefix, collectPreflight, formatPreflight, preflightFailures } from "./preflight.mjs";
-import { assertCleanSource } from "./source-gate.mjs";
 import { acquireHeavyWorkSlot, heavyCommandEnvironment, summarizePreBrokerWaits, terminateProcessTree } from "./heavy-command.mjs";
 import { processGroupCpuSeconds } from "./process-liveness.mjs";
 import { cancelAndReapManagedRequest, firstManagedRequestId, releaseProgressLimits } from "./progress-control.mjs";
@@ -79,7 +81,7 @@ const ANDROID_PIPELINE_FINGERPRINT = createHash("sha256")
   .slice(0, 16);
 
 /** Assemble preflight inputs from the app's own files (mirrors release.mjs). */
-function buildPreflight({ config, configPath, appRoot, repoRoot, platform, nativeLayout, target, pinnedCargoLocks = [] }) {
+function buildPreflight({ config, configPath, appRoot, repoRoot, platform, nativeLayout, target, pinnedCargoLocks = [], releaseSource = null, sourceRoot = repoRoot, artifactPaths = null }) {
   let version;
   try {
     version = JSON.parse(readFileSync(path.join(appRoot, "package.json"), "utf8")).version;
@@ -87,12 +89,15 @@ function buildPreflight({ config, configPath, appRoot, repoRoot, platform, nativ
     version = undefined;
   }
   // An iOS target is built from its Xcode project and local packages only; the ownership scan covers just those roots.
-  const ownershipScope = preflightOwnershipScope({ repoRoot, appRoot, platform, target, nativeAssembly: config?.nativeAssembly });
+  // In a split the scope is the snapshot's (the commit's layout); the preflight reads the checkout for git, the sealed vault and the evidence.
+  const ownershipScope = preflightOwnershipScope({ repoRoot: sourceRoot, appRoot, platform, target, nativeAssembly: config?.nativeAssembly });
   return collectPreflight({
     platform,
     ownershipScope,
     appRoot,
     repoRoot,
+    releaseSource,
+    splitTargets: artifactPaths,
     app: config.app,
     configPath,
     // The version check is the doctor's job: by the time `build` runs, seal
@@ -139,10 +144,24 @@ if (resumeFrom && !["prepackage", "sign", "package", "post-sign", "harden"].incl
 const nativeReal = (file) => { try { return realpathSync.native(file); } catch { return file; } };
 const configPath = nativeReal(path.resolve(configName));
 const invocationRoot = path.dirname(configPath);
-const repoRoot = git(invocationRoot, ["rev-parse", "--show-toplevel"]);
-assertPrimaryReleaseCheckout(repoRoot);
-const relativeConfig = path.relative(nativeReal(repoRoot), nativeReal(configPath)).replaceAll("\\", "/");
-if (relativeConfig.startsWith("../")) fail("release config must live inside the Git repository");
+// Source identity (release-source-identity.mjs, item 7 row 7.04, decision 2 Q2). Without RK_GATE_CHECKOUT the source is the checkout's HEAD,
+// proven exactly as before (primary worktree, branch-attached HEAD, clean status). Inside a door run it is the SELECTED COMMIT's objects
+// plus the gate's verified snapshot: the checkout may be dirty, ahead or detached, and no HEAD, status or branch of it is read.
+// A split that cannot be proven is refused (never a fallback to the checkout checks).
+let releaseSource;
+try { releaseSource = resolveReleaseSource({ cwd: process.env.RK_GATE_CHECKOUT ? process.cwd() : invocationRoot }); }
+catch (error) { fail(error.code === "RK_SOURCE_NO_REPOSITORY" ? `git rev-parse --show-toplevel failed: ${error.message}` : `${error.code ?? "RK_SOURCE_IDENTITY"}: ${error.message}`); }
+const splitSource = isSnapshotSource(releaseSource);
+// The checkout: every object read and every output (`.right-release`: vault, state, locks, sealed) belongs to it (GC:31, GC:65). The
+// source root is where the config, the build inputs and the QA plan are read: the snapshot in a split, else the checkout itself.
+const repoRoot = gitRootOf(releaseSource);
+const sourceRoot = sourceRootOf(releaseSource);
+try { assertReleaseSource(releaseSource, { commandId: "right-release build", skipCleanCheck: true }); } catch (error) { fail(error.message); }
+try { assertInsideSource(releaseSource, configPath, "the release config"); } catch (error) { fail(error.message); }
+const relativeConfig = path.relative(nativeReal(sourceRoot), nativeReal(configPath)).replaceAll("\\", "/");
+if (relativeConfig.startsWith("../")) fail(splitSource ? "release config must live inside the snapshot" : "release config must live inside the Git repository");
+// A split reads no dirty-checkout condition: the snapshot is the commit's bytes, proven by the door at the start and end of the stage.
+const sourceProblems = (inputs, commitId) => (splitSource ? [] : dirtyBuildInputs(repoRoot, inputs, commitId));
 const appRoot = path.dirname(configPath);
 const layout = resolveReleaseLayout({ repoRoot, configPath });
 const vaultRoot = layout.vaultRoot;
@@ -181,20 +200,17 @@ for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
 
 try {
   throwIfInterrupted();
-  const commit = git(repoRoot, ["rev-parse", "HEAD"]);
+  const commit = releaseSource.commit;
   // A phase-resume never reads unrelated source. Its later build-input gate
   // remains strict, but requiring a globally clean mono-workspace here would
   // turn an already-built, signed installer into a needless full rebuild.
-  if (!resumeFrom) {
-    assertCleanSource({
-      status: git(repoRoot, ["status", "--porcelain=v1", "-z", "--untracked-files=all"], { trim: false }), // untrimmed: a leading space is the first record's X column (#782)
-      commandId: "right-release build",
-    });
-  }
+  // The checkout route runs the clean-source gate here (R1, byte for byte as before); a split re-proves its door run instead and reads
+  // no status (R2: a split that is no longer proven refuses, it never falls back).
+  try { assertReleaseSource(releaseSource, { commandId: "right-release build", skipPrimaryCheckout: true, skipCleanCheck: Boolean(resumeFrom) }); } catch (error) { fail(error.message); }
   mkdirSync(path.join(vaultRoot, "locks"), { recursive: true });
   lock = acquireLock(path.join(vaultRoot, "locks", `${platform}.lock.json`));
   const shortCommit = commit.slice(0, 8);
-  const dirtyConfig = dirtyBuildInputs(repoRoot, { include: [relativeConfig], required: [relativeConfig] }, commit);
+  const dirtyConfig = sourceProblems({ include: [relativeConfig], required: [relativeConfig] }, commit);
   if (dirtyConfig.length > 0) fail(`dirty release config cannot be executed:\n${dirtyConfig.map((file) => `- ${file}`).join("\n")}`);
   const config = await importReleaseConfig(configPath, { query: `commit=${commit}` });
   if (!config?.app || !config?.version) fail("release config must expose app and version");
@@ -223,11 +239,25 @@ try {
     : null;
   const nativeIos = iosContext?.nativeIos ?? false;
   const nativeLayout = iosContext ? iosContext.nativeLayout : resolveNativeCargoLayout({ appRoot, config });
+  // Row 7.04c. In a door split the snapshot has no target directory: (R-T4) no step the app owns may name a target-relative path, refused here, before
+  // anything builds; (R-T1) each Cargo manifest's target is bound once, now, through the published resolver. Checkout mode does neither.
+  let artifactPaths = null;
+  if (splitSource) {
+    try {
+      assertSplitCommandPaths(releaseCommandSteps({ target, config, root: appRoot }), splitArtifactContext({ cwd: appRoot, env: process.env, nativeLayout, config, target, snapshotRoot: sourceRoot, resolve: false }));
+      artifactPaths = splitArtifactContext({
+        cwd: appRoot, nativeLayout, config, target, snapshotRoot: sourceRoot,
+        env: { ...process.env, RIGHT_RELEASE_ARTIFACT_DIR: resolveArtifactDir({ app: config.app, version: config.version, managedRoot: resolveManagedRoot({ env: process.env }) }) },
+      });
+    } catch (error) { if (error instanceof ArtifactPathError) fail(error.message); throw error; }
+  }
   if (platform === "win" && target.signingContract === "windows-raw-exe-authenticode-before-nsis-v1") {
     assertNsisInPlaceUpgradeContract(appRoot, target.nsisUpgradeContract);
   }
-  const { requiredInputs, buildInputs, cargoLockPaths: pinnedCargoLocks } = resolveReleaseBuildInputs({ repoRoot, appRoot, configPath, config, target });
-  const dirtyInputs = dirtyBuildInputs(repoRoot, buildInputs, commit);
+  const { requiredInputs, buildInputs, cargoLockPaths: pinnedCargoLocks } = resolveReleaseBuildInputs({ repoRoot: sourceRoot, appRoot, configPath, config, target });
+  // R5: in a split every input resolves inside the snapshot (`hashInputs` below hashes the snapshot's files); the dirty-input gate is the checkout route's.
+  for (const file of requiredInputs) try { assertInsideSource(releaseSource, file, "a release build input"); } catch (error) { fail(error.message); }
+  const dirtyInputs = sourceProblems(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")}`);
   const hasPackageJson = existsSync(path.join(appRoot, "package.json"));
   // iOS records the Xcode toolchain (and xcodegen when a project.yml is named) beside the Node and Rust tools.
@@ -315,7 +345,7 @@ try {
   // Preflight BEFORE any compile. These preconditions used to be discovered one
   // per build cycle, minutes deep, with errors that named a symptom instead of a
   // cause. Blocking problems stop here, in seconds, naming the fix.
-  const preflight = buildPreflight({ config, configPath, appRoot, repoRoot: layout.repoRoot, platform, nativeLayout, target, pinnedCargoLocks });
+  const preflight = buildPreflight({ config, configPath, appRoot, repoRoot: layout.repoRoot, platform, nativeLayout, target, pinnedCargoLocks, releaseSource, sourceRoot, artifactPaths });
   const preflightBlockers = preflightFailures(preflight);
   if (preflightBlockers.length > 0) {
     fail(`preflight found ${preflightBlockers.length} blocking problem(s):\n${formatPreflight(preflightBlockers)}`);
@@ -330,7 +360,8 @@ try {
   }
   // Hardening step 4: source QA is recorded, not enforced. A missing or rejected receipt warns loudly and the outcome
   // is sealed into the manifest (`qa.status`) for `right-release qa audit`. Dev lanes (install-app --dev) never reach this file.
-  const qaAdmission = admitSourceQa({ repoRoot: layout.repoRoot, releaseId, platform, configName: path.relative(process.cwd(), configPath) || path.basename(configPath), releaseConfigSha256: hashFile(configPath) });
+  // A split compares the source QA receipt with the SELECTED commit (its tree, repository identity and lockfile closure from its objects), not HEAD.
+  const qaAdmission = admitSourceQa({ repoRoot: layout.repoRoot, releaseId, platform, configName: path.relative(process.cwd(), configPath) || path.basename(configPath), releaseConfigSha256: hashFile(configPath), ...qaAdmissionSourceOptions(releaseSource) });
 
   // A tool being INSTALLED is not the same as it being the one PATH picks. The
   // vendored-OpenSSL build shells out to `perl`, and under Git Bash/MSYS that
@@ -342,6 +373,7 @@ try {
     ...releaseEnvironment({ root: vaultRoot, cacheRoot: sharedCacheRoot, platform, architecture: cacheIdentity.architecture, app: config.app, cacheKey, kind: "release", appRoot, mode: cacheMode }),
     ...(pathPrefix ? { PATH: `${pathPrefix}${path.delimiter}${process.env.PATH ?? ""}` } : {}),
     RIGHT_RELEASE_REPO_ROOT: layout.repoRoot,
+    ...(splitSource ? { RIGHT_RELEASE_SOURCE_ROOT: sourceRoot } : {}),
     RIGHT_RELEASE_APP_ROOT: layout.appRoot,
     RIGHTKIT_MANAGED_ROOT: resolveManagedRoot({ env: process.env }),
     RIGHT_RELEASE_ARTIFACT_DIR: resolveArtifactDir({ app: config.app, version: config.version, managedRoot: resolveManagedRoot({ env: process.env }) }),
@@ -352,6 +384,9 @@ try {
       delete env[name];
     }
   }
+  // A split's Cargo target is the one the gate bound and handed this process (row 7.09, R-T1): Cache V2's shared target does not replace it, or
+  // the bound target the seal reads would not be the one Cargo wrote.
+  if (splitSource && !managedCargoTarget && typeof process.env.CARGO_TARGET_DIR === "string" && path.isAbsolute(process.env.CARGO_TARGET_DIR)) env.CARGO_TARGET_DIR = process.env.CARGO_TARGET_DIR;
   if (cacheMode !== "shared") 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 !== "shared" && !commandExists("sccache")) delete env.RUSTC_WRAPPER;
@@ -494,6 +529,9 @@ try {
         // cost ~5.9 GB of warm broker intermediates. The bridge's brokerManaged
         // flag already knows to leave a real directory untouched instead.
         if (swiftPlan) { /* SwiftPM: no Rust target link */ }
+        // A split writes no link into the snapshot (a link is never a ledger entry, decision 2 Q1 rule 2): Cargo writes the cache target
+        // directly (CARGO_TARGET_DIR) and the seal resolves `src-tauri/target/...` paths against it (sealRelease managedCargoTarget).
+        else if (splitSource) { /* no target link in the snapshot */ }
         else if (cacheMode === "shared" || managedCargoTarget) targetBridge.ensure();
         else {
           const linked = ensureLegacyTargetLink({ targetLink, cacheTarget, fs: { existsSync, realpathSync, renameSync, symlinkSync } });
@@ -537,7 +575,7 @@ try {
         });
       },
       seal: async ({ sealedDir }) => {
-        sealRelease({ configRoot: appRoot, managedCargoTarget, androidTarget, iosSpec, nativeLayout, sealedDir, releaseId, config, target, platform, commit, inputHashes, toolVersions, cacheKey, signingIdentity, ownershipEvidence, qaAdmission, managedRoot, stateRoot, rightkitRegistryFields: rightKitResolution ? registryManifestFields(rightKitResolution.snapshot, RELEASE_TOOL_VERSION) : undefined });
+        sealRelease({ configRoot: appRoot, managedCargoTarget, artifactPaths, androidTarget, iosSpec, nativeLayout, sealedDir, releaseId, config, target, platform, commit, inputHashes, toolVersions, cacheKey, signingIdentity, ownershipEvidence, qaAdmission, managedRoot, stateRoot, rightkitRegistryFields: rightKitResolution ? registryManifestFields(rightKitResolution.snapshot, RELEASE_TOOL_VERSION) : undefined, splitSealSource: splitSource ? { commit: releaseSource.commit, tree: releaseSource.tree, snapshotAppRoot: appRoot, checkoutAppRoot: releaseSource.checkoutAppRoot } : null });
         verifySealedRelease(sealedDir);
         if (cacheMode === "shared") markCacheEntrySuccessful({ layout: sharedLayout });
         checkpoint(stateRoot, "sealed");
@@ -564,8 +602,8 @@ async function admit() {
   let commit;
   let config;
   try {
-    commit = git(invocationRoot, ["rev-parse", "HEAD"]);
-    const dirtyConfig = dirtyBuildInputs(repoRoot, { include: [relativeConfig], required: [relativeConfig] }, commit);
+    commit = releaseSource.commit;
+    const dirtyConfig = sourceProblems({ include: [relativeConfig], required: [relativeConfig] }, commit);
     if (dirtyConfig.length > 0) fail(`dirty release config cannot be executed:\n${dirtyConfig.map((file) => `- ${file}`).join("\n")}`);
     try { config = await importReleaseConfig(configPath, { query: `commit=${commit}` }); } catch (error) { fail(`release config could not be loaded (${configPath}): ${error instanceof Error ? error.message : String(error)}`); }
   } catch (error) {
@@ -578,7 +616,7 @@ async function admit() {
     && existsSync(path.join(repoRoot, ".right-release", "sealed", `${config.app}-${config.version}-${commit.slice(0, 8)}`, platformName, "release-manifest.json"));
   const reuse = Boolean(resumeFrom) || Boolean(sealed);
   const result = await runAdmission({
-    root: appRoot, repoRoot, configPath, config: config ?? {}, platform, commit, skipChecks,
+    root: appRoot, repoRoot: sourceRoot, releaseSource, configPath, config: config ?? {}, platform, commit, skipChecks,
     tiers: reuse ? ["files", "host"] : ["files", "host", "network"],
     registry: async (ctx) => {
       const inputs = ctx.buildInputs();
@@ -630,7 +668,7 @@ function sqlCipherFeatures(text) {
     .filter((value) => /sqlcipher|openssl/i.test(value));
 }
 
-function sealRelease({ configRoot, managedCargoTarget, androidTarget, iosSpec, nativeLayout, sealedDir, releaseId, config, target, platform, commit, inputHashes, toolVersions, cacheKey, signingIdentity, ownershipEvidence, qaAdmission, managedRoot, stateRoot, rightkitRegistryFields }) {
+function sealRelease({ configRoot, managedCargoTarget, artifactPaths = null, androidTarget, iosSpec, nativeLayout, sealedDir, releaseId, config, target, platform, commit, inputHashes, toolVersions, cacheKey, signingIdentity, ownershipEvidence, qaAdmission, managedRoot, stateRoot, rightkitRegistryFields, splitSealSource = null }) {
   // Every app's release config names installer/updater artifacts
   // relative to its resolved native target. On a broker-managed host that
   // directory is never populated (the broker owns CARGO_TARGET_DIR and
@@ -641,7 +679,11 @@ function sealRelease({ configRoot, managedCargoTarget, androidTarget, iosSpec, n
   const targetPrefix = "src-tauri/target/";
   // A Cargo-less iOS app has no native layout and no managed cargo target: only the default prefix is ever compared.
   const effectiveTargetPrefix = nativeLayout?.targetPrefix ?? targetPrefix;
-  const resolveArtifactPath = (file) => {
+  const resolveArtifactPath = artifactPaths?.mode === "split" ? (file) => {
+    // Row 7.04c (R-T2): a split's declared artifact is read in place in the bound target (or the snapshot, or the managed artifact directory),
+    // through the one resolver; the prefix remap below is the checkout route's.
+    try { return resolveSplitArtifactPath(file, artifactPaths); } catch (error) { if (error instanceof ArtifactPathError) fail(error.message); throw error; }
+  } : (file) => {
     const normalized = file.replaceAll(path.win32.sep, "/");
     if (managedCargoTarget && normalized.startsWith(targetPrefix)) {
       return path.join(managedCargoTarget, normalized.slice(targetPrefix.length));
@@ -792,6 +834,10 @@ function sealRelease({ configRoot, managedCargoTarget, androidTarget, iosSpec, n
     app: config.app,
     version: config.version,
     commit,
+    // A split seal names the selected commit AND its tree and says its bytes came from the door's snapshot (decision 2 Q2 item 5).
+    ...(splitSealSource ? { tree: splitSealSource.tree, source: "snapshot" } : {}),
+    // The Cargo targets this split bound (R-T1); the door cross-checks them against its own resolution (RK_SPLIT_TARGET_DRIFT).
+    ...(artifactPaths?.mode === "split" ? { boundTargets: boundTargetsEvidence(artifactPaths) } : {}),
     ownershipEvidence,
     // The exact registry resolution (identities, digests, registries, policy revision, observation time, observed latest)
     // this release was built against. Upload and resume consume it; neither resolves again.
@@ -813,7 +859,15 @@ function sealRelease({ configRoot, managedCargoTarget, androidTarget, iosSpec, n
         if (present.length !== signingIdentity.receiptInputs.length) fail("missing current-build macOS signing or notarization receipt");
         validateNotarizationReceipt({ receiptPath: signingIdentity.receiptInputs[1], archive: resolveArtifactPath(target.notarize.file) });
       }
-      return present.map((file) => ({ file, sha256: hashFile(file) }));
+      // A split records each receipt relative to a base the checkout reproduces (its app root), never the snapshot's: the snapshot's bytes are
+      // replaced at the next sync. A receipt written INSIDE the snapshot cannot be re-read later, so it is refused (configure sign.receipt under the state root).
+      const recorded = (file) => {
+        if (!splitSealSource) return file;
+        const rel = (base) => path.relative(base, file).replaceAll("\\", "/");
+        if (!rel(splitSealSource.snapshotAppRoot).startsWith("../") && rel(splitSealSource.snapshotAppRoot) !== "..") fail(`signing receipt ${file} is inside the snapshot, which the next sync replaces; write it under the state root (${stateRoot}) so the seal can name it`);
+        return rel(splitSealSource.checkoutAppRoot);
+      };
+      return present.map((file) => ({ file: recorded(file), sha256: hashFile(file) }));
     })() } : null,
     files,
     routes,
@@ -875,7 +929,7 @@ async function runProgress(cmd, runArgs, cwd, env, watchDir, diagnosticPath = nu
     const settleResolve = () => { if (!settled) { settled = true; resolve(); } };
     const settleReject = (error) => { if (!settled) { settled = true; reject(error); } };
     const useShell = process.platform === "win32" && !/\.(?:exe|com)$/i.test(cmd);
-    child = spawn(cmd, runArgs, { cwd, env, stdio: ["inherit", "pipe", "pipe"], windowsHide: true, shell: useShell, detached: process.platform !== "win32" });
+    child = spawnUnderOwnership(spawn, cmd, runArgs, { cwd, env, stdio: ["inherit", "pipe", "pipe"], windowsHide: true, shell: useShell, detached: process.platform !== "win32" });
     try {
       if (child.pid && heavySlot) heavySlot.trackChild(child.pid, cmd);
     } catch (error) {

package/cargo-contract.mjs

@@ -2,7 +2,7 @@ import { existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { spawnSync } from "./background-process.mjs";
-import { managedRuntimeClient, runCargoSync } from "./managed-cargo.mjs";
+import { directPlatform, managedRuntimeClient, runCargoSync } from "./managed-cargo.mjs";
 
 const SKIP_DIRECTORIES = new Set([".audit", ".cache", ".git", ".claude", ".right-release", ".worktrees", "node_modules", "target", "vendor"]);
 const CRATES_IO_SOURCES = new Set([
@@ -12,6 +12,7 @@ const CRATES_IO_SOURCES = new Set([
 const CACHE_V2_ENVIRONMENT = ["CARGO_HOME", "CARGO_TARGET_DIR", "RUSTC_WRAPPER", "SCCACHE_DIR", "SCCACHE_BASEDIRS", "RIGHT_RELEASE_CACHE_OWNER"];
 
 export function managedCargoShimOnPath(env = process.env, platform = process.platform, exists = existsSync) {
+  if (directPlatform(platform)) return false; // Linux never uses a RustRight shim (managed-cargo directPlatform)
   const pathApi = platform === "win32" ? path.win32 : path.posix;
   const delimiter = platform === "win32" ? ";" : ":";
   const extensions = platform === "win32"
@@ -29,6 +30,7 @@ export function managedCargoShimOnPath(env = process.env, platform = process.pla
 }
 
 export function brokerManagedHost(env = process.env, platform = process.platform, exists = existsSync) {
+  if (directPlatform(platform)) return false; // Linux is never broker-managed, whatever socket or control root the env names
   return Boolean(managedRuntimeClient(env, platform, exists)) || Boolean(env.RIGHTKIT_BUILD_BROKER_SOCKET) || managedCargoShimOnPath(env, platform, exists);
 }
 

package/cargo-ledger.mjs

@@ -0,0 +1,62 @@
+// The gate-owned ledger of every call the runtime cargo wrapper decides (item 7 rows 7.10 and 7.24, Sage decision C).
+//
+// The wrapper (cargo-target-shim.mjs) appends one record BEFORE it acts (`pending`) and one after (`ran`, `verified`, `unverified` or
+// `refused`), to `<ledger dir>/<scan token>.jsonl`. The gate (runScans) reads the file of each scan after it ended and fails the scan
+// on anything but a completed, successful call: a refused call fails its unit even when the test swallowed cargo's exit status, and a
+// call that never completed (the wrapper was killed, or the record was never finished) is unverified, never skipped. Records the gate
+// cannot attribute to a scan (the scan token was cleared) fail the run as a row of their own.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export const LEDGER_SCHEMA = "rightkit.cargo-ledger/1";
+export const SCAN_TOKEN_ENV = "RIGHTKIT_CARGO_SCAN";
+export const UNSCOPED = "unscoped";
+/** Statuses that are a completed success: a direct call that ran, a broker call whose signed receipt verified. */
+export const OK_STATUSES = Object.freeze(["ran", "verified"]);
+
+/** The token a scan's calls are filed under: stable per scan id, never the id itself. */
+export const scanTokenOf = (scanId) => crypto.createHash("sha256").update(String(scanId)).digest("hex").slice(0, 16);
+
+const tokenFile = (dir, token) => path.join(dir, `${token}.jsonl`);
+const validToken = (token) => (typeof token === "string" && /^[0-9a-f]{16}$/.test(token) ? token : UNSCOPED);
+
+/** Appends one record. Throws when it cannot be written: a call that cannot be recorded does not run. */
+export function appendLedger(dir, token, entry) {
+  if (!dir || !path.isAbsolute(dir)) throw new Error("the cargo ledger directory is not set");
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const fd = fs.openSync(tokenFile(dir, validToken(token)), fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+  try { fs.writeSync(fd, `${JSON.stringify({ schema: LEDGER_SCHEMA, at: new Date().toISOString(), ...entry })}\n`); } finally { fs.closeSync(fd); }
+}
+
+/**
+ * The calls filed under `token`, one per call id (a later record replaces an earlier one), and the problems found: an unreadable
+ * line, and every call that is not a completed success.
+ */
+export function readLedger(dir, token) {
+  const file = tokenFile(dir, validToken(token));
+  let text = "";
+  try { text = fs.readFileSync(file, "utf8"); } catch (e) { if (e.code === "ENOENT") return { entries: [], problems: [] }; throw e; }
+  const byId = new Map(); const problems = [];
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    let entry;
+    try { entry = JSON.parse(line); } catch { problems.push(`an unreadable ledger record in ${path.basename(file)}`); continue; }
+    if (entry?.schema !== LEDGER_SCHEMA || typeof entry.id !== "string") { problems.push(`a malformed ledger record in ${path.basename(file)}`); continue; }
+    byId.set(entry.id, { ...(byId.get(entry.id) ?? {}), ...entry });
+  }
+  const entries = [...byId.values()];
+  for (const e of entries) {
+    if (OK_STATUSES.includes(e.status)) continue;
+    const call = `cargo ${(e.argv ?? []).join(" ")}`.trim();
+    problems.push(e.status === "pending" ? `${call} (from ${e.cwd}) never completed: the wrapper recorded it and no outcome, so it is unverified` : `${call} (from ${e.cwd}) was ${e.status}${e.code ? ` (${e.code})` : ""}${e.message ? `: ${e.message}` : ""}`);
+  }
+  return { entries, problems };
+}
+
+/** Ledger files nobody claimed: the scan token was cleared or invented by the code under test. */
+export function unclaimedLedgers(dir, claimedTokens) {
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch (e) { if (e.code === "ENOENT") return []; throw e; }
+  return names.filter((n) => n.endsWith(".jsonl")).map((n) => n.slice(0, -".jsonl".length)).filter((t) => !claimedTokens.has(t));
+}

package/cargo-target-shim.mjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+// The runtime cargo wrapper of a commit-snapshot compile (item 7, GATE-CONTRACT §1 "Broker interface", output directory). Two modes:
+//   direct  the DIRECT POSIX (Linux) host: each call runs the real cargo bound to its workspace's checkout target directory.
+//   broker  the Mac (decision C, rows 7.10 and 7.24): each call goes through the RustRight client as its own snapshot request with a
+//           fresh carrier (snapshot-broker.mjs runBrokerCargo); no cargo ever runs outside the broker, and its signed receipt must verify.
+// Both modes append every call to the gate-owned ledger (cargo-ledger.mjs) before and after it acts, and the gate fails the scan on any
+// refused, unverified or unfinished call even when the test ignored the exit status. On a Windows host there is no wrapper: a child
+// started without a shell finds only an .exe, so the static walk (deterministic-scans.mjs cargoReachOf) is the fail-closed baseline
+// there (a refused unit is FAIL or BLOCKED with a code, never skipped).
+//
+// The gate puts this `cargo` first on PATH and names it in CARGO for every scan. A test, script or build tool that runs `cargo` or
+// $CARGO comes back here, with one accepted exception (lead re-decision F7, row 7.10). MEASURED, cargo 1.98.0 on WSL2
+// (/Volumes/D/scratch/rk-l7b/wsl-debug1.sh, wsl-debug3.sh): a real cargo hands a build script its OWN path in CARGO, not the file
+// the CARGO variable names, and `--config env.CARGO` does not change that. A cargo a build script starts through $CARGO therefore
+// bypasses this wrapper. It is accepted as follows: it inherits the parent's bound CARGO_TARGET_DIR (the same as a primary-checkout
+// build), so its outputs land in the bound checkout target; the per-scan sentinel and the after-compile snapshot verify stay as
+// backstops; and it is UNOBSERVED: never in the ledger, and every scan result of a wrapped compile carries a note that says so
+// (deterministic-scans.mjs UNOBSERVED_NESTED_CARGO_NOTE). Each invocation resolves its Cargo workspace
+// (`cargo locate-project --workspace`, from its working directory or --manifest-path) and runs with that workspace's ORIGINAL checkout
+// target directory as CARGO_TARGET_DIR. Refused with an RK_* code (the unit fails): a workspace the compile did not resolve (outside
+// the snapshot, a fixture, a temporary project), an option that moves the workspace, configuration or output, a command that writes
+// no bound output or rewrites the commit (clean, install, publish, update, an alias or plugin), a command that reads a workspace
+// outside the bound ones or may write its Cargo.lock (tree, fetch, pkgid... without --locked/--frozen; fmt only as --check). A cargo
+// that bypasses PATH and CARGO (an absolute path, `rustup run`, a reset PATH) inherits the scan-wide CARGO_TARGET_DIR: the one
+// workspace's checkout target, or with several workspaces a per-scan sentinel directory that must stay empty (runScans fails the
+// scan with RK_CARGO_UNBOUND otherwise). In broker mode the sentinel is always set: there is no checkout target to inherit, so any
+// write into it is a cargo that skipped the wrapper. An absolute cargo that also passes its own absolute target directory has
+// overridden the value the gate passed: a residual of the trusted per-user model, not refused (map 7.12).
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { spawnSync } from "./background-process.mjs";
+import { fileURLToPath } from "node:url";
+import { SCAN_TOKEN_ENV, appendLedger } from "./cargo-ledger.mjs";
+import { BROKER_REFUSAL_STATUS, runBrokerCargo } from "./snapshot-broker.mjs";
+
+export const SHIM_MAP_SCHEMA = "rightkit.cargo-target-shim/3";
+// Exit status of a refusal: cargo's own error status, so every caller reads it as a failed cargo.
+export const SHIM_REFUSAL_STATUS = BROKER_REFUSAL_STATUS;
+// Cargo commands that compile or report on a workspace: run bound to its checkout target directory.
+const COMPILE = new Set(["build", "b", "check", "c", "test", "t", "bench", "run", "r", "doc", "d", "rustc", "rustdoc", "clippy", "metadata", "package"]);
+// Commands that only read a workspace but may resolve and write its Cargo.lock: bound, and only with --locked or --frozen.
+const LOCKED = new Set(["fetch", "tree", "pkgid", "verify-project", "read-manifest", "locate-project", "deny"]);
+// Commands with no lock flag (cargo fmt, cargo-audit): bound, and only where the workspace's committed Cargo.lock already exists.
+const LOCKFILE = new Set(["fmt", "audit"]);
+// Plugins whose options are their own, not cargo's (cargo-deny's --config is its config file, not a cargo redirect).
+const PLUGIN = new Set(["deny", "audit"]);
+const BOUND = new Set([...COMPILE, ...LOCKED, ...LOCKFILE]);
+// Commands that read no workspace at all: run unchanged.
+const PASSTHROUGH = new Set(["version", "help"]);
+// Global options that take a value (`--color always`, `--explain E0001`); the subcommand is the first word after them.
+const GLOBAL_VALUE = new Set(["--color", "--explain"]);
+// Options that move the working directory, the configuration or the output (a short cluster holding C or Z too).
+const REDIRECT = /^(--config|-Z|-C)(=|$)|^-[A-Za-z]*[CZ]/;
+
+const refusal = (code, message) => ({ refuse: { code, message } });
+
+/**
+ * What one cargo invocation may do: `{ exec: { args, env, workspace, targetDir } }` (bound), `{ exec: { args, env } }` (a command
+ * that writes nothing), or `{ refuse: { code, message } }`. `locate(manifestPath | null, cwd, toolchain | null)` returns the absolute
+ * path of the workspace root's Cargo.toml or throws; `realpath` resolves a directory. `map.shim` (the wrapper's own path) is set as
+ * CARGO for the real cargo, so its build scripts and tests reach the wrapper again.
+ */
+export function decideCargoInvocation({ args, cwd, env, map, locate, realpath = (p) => fs.realpathSync.native(p), exists = fs.existsSync }) {
+  const words = [...args];
+  const toolchain = words[0]?.startsWith("+") ? words[0] : null;
+  const withCargo = (e) => (map.shim ? { ...e, CARGO: map.shim } : e);
+  let i = toolchain ? 1 : 0;
+  let sub = null;
+  for (; i < words.length; i += 1) {
+    const w = words[i];
+    if (w === "--") break;
+    if (REDIRECT.test(w)) return refusal("RK_CARGO_REDIRECT", `\`cargo ${words.join(" ")}\` passes ${w}, which moves its working directory, configuration or output; a snapshot compile's outputs must be the checkout's`);
+    if (GLOBAL_VALUE.has(w)) { i += 1; continue; }
+    if (w.startsWith("-")) continue;
+    sub = w;
+    break;
+  }
+  const end = sub === null ? -1 : words.indexOf("--", i + 1);
+  const own = sub === null ? [] : words.slice(i + 1, end < 0 ? undefined : end);
+  const globals = words.slice(toolchain ? 1 : 0, sub === null ? undefined : i);
+  if (sub === "fmt" && !own.includes("--check")) return refusal("RK_CARGO_UNBOUND_COMMAND", "`cargo fmt` without --check rewrites tracked files; a snapshot compile changes no file of the commit");
+  if (sub === null || PASSTHROUGH.has(sub)) return { exec: { args: words, env: withCargo({ ...env }) } };
+  if (!BOUND.has(sub)) return refusal("RK_CARGO_UNBOUND_COMMAND", `\`cargo ${sub}\` is not a command a snapshot compile binds (${[...BOUND].join(", ")}; or ${[...PASSTHROUGH].join(", ")}, which read no workspace): an alias, plugin, clean, install, publish or lock rewrite is refused`);
+  if (LOCKED.has(sub) && ![...globals, ...own].some((w) => w === "--locked" || w === "--frozen")) return refusal("RK_CARGO_UNBOUND_COMMAND", `\`cargo ${sub}\` without --locked or --frozen may write a Cargo.lock; a snapshot compile changes no file of the commit and writes nothing outside its bound outputs`);
+  if (!PLUGIN.has(sub)) for (const w of own) if (REDIRECT.test(w)) return refusal("RK_CARGO_REDIRECT", `\`cargo ${sub}\` passes ${w}, which moves its working directory, configuration or output; a snapshot compile's outputs must be the checkout's`);
+  const valueOf = (name) => {
+    const at = own.findIndex((w) => w === name || w.startsWith(`${name}=`));
+    if (at < 0) return undefined;
+    return own[at].includes("=") ? own[at].slice(name.length + 1) : (own[at + 1] ?? "");
+  };
+  const manifestPath = valueOf("--manifest-path");
+  const broker = map.mode === "broker";
+  // The RustRight client submits the call from the working directory and refuses to rewrite it (attestation), and the broker pins the
+  // output: a manifest path or a target directory of the caller's has no place in a broker call.
+  if (broker && manifestPath !== undefined) return refusal("RK_CARGO_BROKER_MANIFEST_PATH", `\`cargo ${sub}\` passes --manifest-path; a broker call runs from the workspace's own directory (the client refuses to rewrite the invocation), so run it there`);
+  if (broker && valueOf("--target-dir") !== undefined) return refusal("RK_CARGO_REDIRECT", `\`cargo ${sub}\` passes --target-dir; the broker pins a snapshot compile's output directory`);
+  let workspace;
+  try {
+    const manifest = locate(manifestPath === undefined ? null : path.resolve(cwd, manifestPath), cwd, toolchain);
+    if (typeof manifest !== "string" || !path.isAbsolute(manifest)) throw new Error(`locate-project reported ${JSON.stringify(manifest)}`);
+    workspace = realpath(path.dirname(manifest));
+  } catch (error) {
+    return refusal("RK_CARGO_UNBOUND_WORKSPACE", `\`cargo ${sub}\` from ${cwd}${manifestPath === undefined ? "" : ` (--manifest-path ${manifestPath})`}: its Cargo workspace cannot be resolved (${error.message}); a snapshot compile's outputs must be the checkout's`);
+  }
+  const targetDir = Object.hasOwn(map.workspaces ?? {}, workspace) ? map.workspaces[workspace] : null;
+  if (!targetDir) return refusal("RK_CARGO_UNBOUND_WORKSPACE", `\`cargo ${sub}\` builds the Cargo workspace ${workspace}, which is not one this snapshot compile resolved (${Object.keys(map.workspaces ?? {}).join(", ") || "none"}); its outputs would not be the checkout's`);
+  if (LOCKFILE.has(sub) && !exists(path.join(workspace, "Cargo.lock"))) return refusal("RK_CARGO_UNBOUND_COMMAND", `\`cargo ${sub}\` has no --locked, and workspace ${workspace} has no committed Cargo.lock it would only read; it may write one`);
+  // Broker mode: `targetDir` is the workspace's counterpart in the primary checkout (the gate's snapshot-to-checkout map).
+  if (broker) return { exec: { args: words, env: { ...env }, workspace, checkoutWorkspace: targetDir } };
+  const explicit = valueOf("--target-dir");
+  if (explicit !== undefined && path.resolve(cwd, explicit) !== targetDir) return refusal("RK_CARGO_REDIRECT", `\`cargo ${sub}\` passes --target-dir ${explicit}; workspace ${workspace} writes only to the checkout's ${targetDir}`);
+  return { exec: { args: words, env: withCargo({ ...env, CARGO_TARGET_DIR: targetDir, CARGO_BUILD_TARGET_DIR: targetDir }), workspace, targetDir } };
+}
+
+/**
+ * Writes the wrapper for one snapshot compile under `base`: the map file and `bin/cargo`, which runs this module with node. The
+ * directory is named by the sha256 of the map and this module's bytes (`identity`), so the same workspaces, targets and wrapper give
+ * the same path (and the same CARGO in a scan's cache key) and any change gives another. `targetDirs` is the gate's { [cargoDir]:
+ * absolute checkout target directory }; each workspace is keyed by its real path in the snapshot. `realCargo` is the absolute cargo
+ * the wrapper runs (never itself). POSIX hosts only: a Windows child started without a shell finds only an .exe on PATH.
+ *
+ * Broker mode (`broker: { checkoutDirs, section }`, the Mac): `checkoutDirs` is the gate's { [cargoDir]: absolute path of that
+ * workspace in the primary checkout } (the snapshot-to-checkout map, the only source of a request's primaryCwd) and `section` the
+ * public part of the gate's snapshot broker (brokerSection). `realCargo` then only runs `version` and `help`; it may be null.
+ */
+export function installCargoShim({ base, snapshotRoot, targetDirs, broker = null, realCargo, node = process.execPath, platform = process.platform, realpath = (p) => fs.realpathSync.native(p), onDir = () => {}, write = (file, text, mode) => fs.writeFileSync(file, text, { mode }) }) {
+  if (platform === "win32") throw Object.assign(new Error("the runtime cargo wrapper needs a POSIX host: a Windows child finds only an .exe on PATH"), { code: "RK_CARGO_SHIM_UNSUPPORTED" });
+  const mode = broker ? "broker" : "direct";
+  if (mode === "direct" && (typeof realCargo !== "string" || !path.isAbsolute(realCargo))) throw Object.assign(new Error(`no absolute cargo to wrap (${JSON.stringify(realCargo)})`), { code: "RK_CARGO_SHIM_UNSUPPORTED" });
+  if (mode === "broker" && ((realCargo !== null && realCargo !== undefined && !path.isAbsolute(realCargo)) || !broker.section || !broker.checkoutDirs)) throw Object.assign(new Error("a broker wrapper needs the gate's checkout map and broker section"), { code: "RK_CARGO_SHIM_UNSUPPORTED" });
+  const workspaces = {};
+  for (const [cargoDir, targetDir] of Object.entries(broker ? broker.checkoutDirs : targetDirs ?? {})) workspaces[realpath(path.join(snapshotRoot, ...(cargoDir === "." ? [] : cargoDir.split("/"))))] = targetDir;
+  const self = fileURLToPath(import.meta.url);
+  const sorted = Object.fromEntries(Object.entries(workspaces).sort(([a], [b]) => (a < b ? -1 : 1)));
+  const identityHash = createHash("sha256").update(JSON.stringify({ realCargo: realCargo ?? null, node, workspaces: sorted, ...(broker ? { mode, section: broker.section } : {}) })).update(fs.readFileSync(self));
+  // The broker half of the wrapper is part of its identity: any change to the code that carries and verifies a call is another wrapper.
+  if (broker) for (const name of ["snapshot-broker.mjs", "snapshot-request.mjs", "provenance-verify.mjs", "cargo-ledger.mjs"]) identityHash.update(fs.readFileSync(new URL(`./${name}`, import.meta.url)));
+  const identity = identityHash.digest("hex");
+  const dir = path.join(base, `rk-cargo-shim-${identity.slice(0, 16)}`);
+  const bin = path.join(dir, "bin");
+  const shim = path.join(bin, "cargo");
+  const mapFile = path.join(dir, "cargo-target-map.json");
+  const ledgerDir = path.join(dir, "ledger");
+  // The caller learns the directory before anything is written into it (its cleanup owns it from here), and a failed install removes
+  // what it wrote before it throws.
+  onDir(dir);
+  try {
+    fs.mkdirSync(bin, { recursive: true });
+    fs.mkdirSync(ledgerDir, { recursive: true, mode: 0o700 });
+    const quote = (s) => `'${String(s).replaceAll("'", "'\\''")}'`;
+    const put = (file, text, mode) => { const tmp = `${file}.${process.pid}.tmp`; write(tmp, text, mode); fs.renameSync(tmp, file); };
+    const sentinel = mode === "broker" || Object.keys(sorted).length > 1 ? path.join(dir, "unbound") : null;
+    const section = broker ? { ...broker.section, sentinel } : null;
+    put(mapFile, `${JSON.stringify({ schema: SHIM_MAP_SCHEMA, mode, identity, realCargo: realCargo ?? null, shim, ledgerDir, workspaces: sorted, ...(section ? { broker: section } : {}) }, null, 2)}\n`, 0o644);
+    put(shim, `#!/bin/sh\nexec ${quote(node)} ${quote(self)} --map ${quote(mapFile)} -- "$@"\n`, 0o755);
+    return { dir, bin, shim, mapFile, ledgerDir, mode, workspaces: sorted, identity, sentinel };
+  } catch (error) {
+    fs.rmSync(dir, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+/**
+ * The environment every scan of a wrapped snapshot compile starts from: the wrapper first on PATH and named in CARGO, and, when the
+ * snapshot has exactly one Cargo workspace (direct mode), its checkout target as the scan-wide CARGO_TARGET_DIR, so a cargo that
+ * bypasses the wrapper (an absolute path, `rustup run`, a reset PATH) still writes there. Otherwise runScans gives each scan its own
+ * empty sentinel as CARGO_TARGET_DIR instead (installed.sentinel; options.cargoSentinel), which must still be empty afterwards.
+ * Broker mode has no checkout target to inherit and always uses the sentinel.
+ */
+export function shimScanEnv(env, installed) {
+  const targets = Object.values(installed.workspaces);
+  const pathKey = Object.keys(env).find((k) => k.toUpperCase() === "PATH") ?? "PATH";
+  return { ...env, [pathKey]: `${installed.bin}${path.delimiter}${env[pathKey] ?? ""}`, CARGO: installed.shim, ...(installed.mode !== "broker" && targets.length === 1 ? { CARGO_TARGET_DIR: targets[0] } : {}) };
+}
+
+/**
+ * The workspace root Cargo resolves for a manifest or a directory, from the files alone (broker mode: no cargo runs outside the
+ * broker, not even `locate-project`): the nearest enclosing Cargo.toml that declares `[workspace]`, else the nearest Cargo.toml.
+ */
+export function locateWorkspaceByWalk(manifestPath, cwd, { read = (f) => fs.readFileSync(f, "utf8"), exists = fs.existsSync } = {}) {
+  let nearest = null;
+  for (let dir = manifestPath ? path.dirname(manifestPath) : cwd; ; dir = path.dirname(dir)) {
+    const manifest = path.join(dir, "Cargo.toml");
+    if (exists(manifest)) {
+      nearest ??= manifest;
+      let text = "";
+      try { text = read(manifest); } catch { text = ""; }
+      if (/^\s*\[workspace(?:\.[^\]]*)?\]/m.test(text)) return manifest;
+    }
+    if (path.dirname(dir) === dir) break;
+  }
+  if (nearest) return nearest;
+  throw new Error("could not find `Cargo.toml` in the working directory or any parent");
+}
+
+/** The wrapper itself: `cargo-target-shim.mjs --map <file> -- <cargo args>`. Returns the exit status. */
+export function runShim(argv, { env = process.env, cwd = process.cwd(), spawn = spawnSync, err = (m) => process.stderr.write(`${m}\n`) } = {}) {
+  const sep = argv.indexOf("--");
+  const mapAt = argv.indexOf("--map");
+  if (mapAt < 0 || sep < 0 || mapAt > sep) { err("rightkit-gate: RK_CARGO_SHIM_ERROR: usage: cargo-target-shim.mjs --map <file> -- <cargo args>"); return SHIM_REFUSAL_STATUS; }
+  let map;
+  try { map = JSON.parse(fs.readFileSync(argv[mapAt + 1], "utf8")); if (map?.schema !== SHIM_MAP_SCHEMA) throw new Error(`schema ${JSON.stringify(map?.schema)}`); }
+  catch (error) { err(`rightkit-gate: RK_CARGO_SHIM_ERROR: the cargo target map cannot be read (${error.message}); nothing ran`); return SHIM_REFUSAL_STATUS; }
+  const words = argv.slice(sep + 1);
+  const token = env[SCAN_TOKEN_ENV];
+  const id = `${process.pid}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+  const broker = map.mode === "broker";
+  const base = { id, mode: broker ? "broker" : "direct", cwd, argv: words };
+  // A call that cannot be recorded does not run: the ledger is how the gate learns what a test did, whatever the test does with the status.
+  const record = (entry) => appendLedger(map.ledgerDir, token, entry);
+  try { record({ ...base, status: "pending" }); } catch (error) { err(`rightkit-gate: RK_CARGO_LEDGER_ERROR: the call cannot be recorded (${error.message}); it does not run`); return SHIM_REFUSAL_STATUS; }
+  const refuse = (why) => { record({ ...base, status: "refused", code: why.code, message: why.message }); err(`rightkit-gate: ${why.code}: ${why.message}`); return SHIM_REFUSAL_STATUS; };
+  // locate-project runs the real cargo with CARGO pointing at it, never at the wrapper (direct mode). Broker mode reads the files only.
+  const locateEnv = { ...env, CARGO: map.realCargo };
+  const locate = broker ? (manifestPath, from) => locateWorkspaceByWalk(manifestPath, from) : (manifestPath, from, toolchain) => {
+    const r = spawn(map.realCargo, [...(toolchain ? [toolchain] : []), "locate-project", "--workspace", "--message-format", "plain", ...(manifestPath ? ["--manifest-path", manifestPath] : [])], { cwd: from, env: locateEnv, encoding: "utf8" });
+    if (r.error) throw r.error;
+    if (r.status !== 0) throw new Error(String(r.stderr || `exit ${r.status}`).trim().split(/\r?\n/).at(-1));
+    return String(r.stdout).trim();
+  };
+  let decision;
+  try { decision = decideCargoInvocation({ args: words, cwd, env, map, locate }); } catch (error) { return refuse({ code: "RK_CARGO_SHIM_ERROR", message: error.message }); }
+  if (decision.refuse) return refuse(decision.refuse);
+  if (broker && decision.exec.workspace) {
+    // The `pending` record above stays this call's until the broker call finishes: its records carry the same call id.
+    return runBrokerCargo({ words: decision.exec.args, cwd, env, section: map.broker, workspace: decision.exec.workspace, checkoutWorkspace: decision.exec.checkoutWorkspace, record: (entry) => record({ ...entry, id }), spawn, err });
+  }
+  // A call that reads no workspace (version, help) runs as it is: the real cargo in direct mode, the host's cargo or the client in broker mode.
+  const viaClient = broker && !map.realCargo;
+  const command = viaClient ? map.broker.client : map.realCargo;
+  const r = spawn(command, viaClient ? ["cargo", ...decision.exec.args] : decision.exec.args, { cwd, env: decision.exec.env, stdio: "inherit" });
+  if (r.error) return refuse({ code: "RK_CARGO_SHIM_ERROR", message: `${command} did not start (${r.error.message})` });
+  record({ ...base, status: "ran", exit: r.status ?? null });
+  return r.status ?? (r.signal ? 128 : SHIM_REFUSAL_STATUS);
+}
+
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) process.exit(runShim(process.argv.slice(2)));