@rightkit/release 0.6.10 → 0.6.11

package/cargo-target-shim.mjs

@@ -1,11 +1,21 @@
 #!/usr/bin/env node
-// The runtime cargo wrapper of a commit-snapshot compile (item 7, GATE-CONTRACT §1 "Broker interface", output directory). Scope: the
-// DIRECT POSIX (Linux) host only. On Mac and Dell the positive snapshot-compile path is the RustRight broker's snapshot carrier alone
-// (the gate refuses a snapshot compile on a broker host until it is wired); on a direct Windows host the static walk
-// (deterministic-scans.mjs cargoReachOf) is the fail-closed baseline, because a child started without a shell finds only an .exe.
+// 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. Real cargo honours CARGO as its own path and hands
-// it to build scripts and tests (env!("CARGO"), $CARGO), so those come back here too. Each invocation resolves its Cargo workspace
+// 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
@@ -13,17 +23,20 @@
 // 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). An absolute cargo that also passes its own --target-dir is deliberate evasion of the gate,
-// out of scope under the standing rule (the gate binds what a test does, not what a test sets out to hide).
+// 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 "node:child_process";
+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/2";
+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 = 101;
+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.
@@ -77,6 +90,11 @@ export function decideCargoInvocation({ args, cwd, env, map, locate, realpath =
     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);
@@ -88,6 +106,8 @@ export function decideCargoInvocation({ args, cwd, env, map, locate, realpath =
   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 } };
@@ -99,45 +119,79 @@ export function decideCargoInvocation({ args, cwd, env, map, locate, realpath =
  * 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, realCargo, node = process.execPath, platform = process.platform, realpath = (p) => fs.realpathSync.native(p), onDir = () => {}, write = (file, text, mode) => fs.writeFileSync(file, text, { mode }) }) {
+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" });
-  if (typeof realCargo !== "string" || !path.isAbsolute(realCargo)) throw Object.assign(new Error(`no absolute cargo to wrap (${JSON.stringify(realCargo)})`), { 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(targetDirs ?? {})) workspaces[realpath(path.join(snapshotRoot, ...(cargoDir === "." ? [] : cargoDir.split("/"))))] = targetDir;
+  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 identity = createHash("sha256").update(JSON.stringify({ realCargo, node, workspaces: sorted })).update(fs.readFileSync(self)).digest("hex");
+  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); };
-    put(mapFile, `${JSON.stringify({ schema: SHIM_MAP_SCHEMA, identity, realCargo, shim, workspaces: sorted }, null, 2)}\n`, 0o644);
+    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;
   }
-  return { dir, bin, shim, mapFile, workspaces: sorted, identity, sentinel: Object.keys(sorted).length > 1 ? path.join(dir, "unbound") : null };
 }
 
 /**
  * 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, 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. With several workspaces runScans gives each scan its own
+ * 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, ...(targets.length === 1 ? { CARGO_TARGET_DIR: targets[0] } : {}) };
+  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. */
@@ -148,18 +202,36 @@ export function runShim(argv, { env = process.env, cwd = process.cwd(), spawn =
   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; }
-  // locate-project runs the real cargo with CARGO pointing at it, never at the wrapper.
+  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 = (manifestPath, from, toolchain) => {
+  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();
   };
-  const decision = decideCargoInvocation({ args: argv.slice(sep + 1), cwd, env, map, locate });
-  if (decision.refuse) { err(`rightkit-gate: ${decision.refuse.code}: ${decision.refuse.message}`); return SHIM_REFUSAL_STATUS; }
-  const r = spawn(map.realCargo, decision.exec.args, { cwd, env: decision.exec.env, stdio: "inherit" });
-  if (r.error) { err(`rightkit-gate: RK_CARGO_SHIM_ERROR: ${map.realCargo} did not start (${r.error.message})`); return SHIM_REFUSAL_STATUS; }
+  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);
 }
 

package/cli/right-release.mjs

@@ -59,8 +59,31 @@ const first = args[0];
 // The commands that compile, package, sign, ship or inspect a release run the app check (../app-check.mjs, CHECKED_COMMANDS) in this
 // process before they start a child. A red check prints its findings and exits 1; there is no flag that skips it.
 const WORKTREE_COMPILES = new Set(["dev", "test", "stage-sidecar"]);
+// The commands that run inside a source split (source-split.mjs): the door's snapshot of a commit, with the checkout kept for the git
+// context and every output. build, package, release and qa take their identity from release-source-identity.mjs (row 7.04): the selected
+// commit's objects plus the door's verified snapshot, never the checkout's HEAD, status or branch (each re-proves it through
+// assertReleaseSource). `upload` does so for the mobile platforms (the host's store upload); a desktop upload, publish and the signing
+// commands still read the checkout's HEAD and refuse under a split rather than run on the wrong bytes.
+const SPLIT_COMMANDS = new Set(["dev", "test", "stage-sidecar", "web-build", "build", "package", "release", "qa"]);
+const MOBILE_UPLOAD = (argv) => argv.some((a, i) => (a === "--platform" && ["ios", "android"].includes(argv[i + 1])) || a === "--platform=ios" || a === "--platform=android");
 async function requireGreenCheck() {
   const { guardCommand, checkedCommandOf, checkModeFor, appDirectory } = await import("../app-check.mjs");
+  const { readSourceSplit, SOURCE_SPLIT_UNSUPPORTED } = await import("../source-split.mjs");
+  let split = null;
+  try { split = readSourceSplit(); } catch (error) { console.error(`right-release: ${error.code ?? "RK_SOURCE_SPLIT"}: ${error.message}; nothing was started`); process.exit(2); }
+  if (split) {
+    // A flag-first call (`right-release --platform mac`) is a build with no command word.
+    const key = checkedCommandOf(args) ?? (args[0]?.startsWith("-") ? "build" : null);
+    if (checkModeFor(args) && !SPLIT_COMMANDS.has(key) && !(key === "upload" && MOBILE_UPLOAD(args))) {
+      console.error(`right-release: ${SOURCE_SPLIT_UNSUPPORTED}: right-release ${key ?? args.join(" ")} cannot run from the snapshot of ${split.commit.slice(0, 12)} yet: it reads the checkout's clean HEAD (ownership evidence, source QA identity, the clean-source and dirty-input gates), and a dirty checkout or another commit must never reach it; nothing was started`);
+      process.exit(2);
+    }
+    // The door run itself was proven by readSourceSplit (live, this checkout, this commit); the app rules read the commit from the checkout.
+    const refusedSplit = guardCommand({ args, source: { repo: split.checkout, commit: split.commit } });
+    if (!refusedSplit) return;
+    for (const line of refusedSplit.lines) console.error(line);
+    process.exit(refusedSplit.exitCode);
+  }
   // One door (Adrian, 2026-10-25): a commit-bound command (build, package, release, qa, upload, publish, signing) runs only when
   // rightkit-gate --to launched it for HEAD, after class A and the compile stage passed.
   const checked = checkedCommandOf(args);
@@ -129,13 +152,14 @@ if (first === "--version" || first === "-v") {
   const { main } = await import("../bin/rightkit-gate.mjs");
   process.exit(await main(["check", ...args.slice(1)], { cwd: appDirectory(args, process.cwd()) }));
 } else if (first === "hooks" && args[1] === "install") {
-  // One installer: `hooks install` is `rightkit-gate install-hook` (pre-push check and gate, ownership pre-commit step) run in the app.
+  // One installer: `hooks install` is `rightkit-gate install-hook` run in the app. It writes no git hook: it retires the pre-push gate, the
+  // forwarders and the ownership pre-commit hook an earlier release wrote (docs/GATE-CONTRACT.md: commit and push run no gate).
   const app = args.indexOf("--app");
   if (app >= 0 && (!args[app + 1] || args[app + 1].startsWith("-"))) {
     console.error("right-release hooks install: --app needs a directory");
     process.exit(2);
   }
-  run("bin/rightkit-gate.mjs", ["install-hook", ...(args.includes("--force") ? ["--force"] : [])], { cwd: app >= 0 ? path.resolve(args[app + 1]) : process.cwd() });
+  run("bin/rightkit-gate.mjs", ["install-hook"], { cwd: app >= 0 ? path.resolve(args[app + 1]) : process.cwd() });
 } else if (first === "hooks") {
   run("ownership-hooks.mjs", args.slice(1));
 } else if (first === "suite-doctor") {
@@ -373,8 +397,8 @@ Commands:
   doctor --all                                       Verify all Right Suite app release contracts
   suite-doctor                                       Verify all local Right Suite repositories
   ownership [--app <dir>] [--json]                   Fail on app copies of RightKit-owned capabilities
-  ownership --staged [--app <dir>] [--json]          Pre-commit gate: scan the staged index for block-tier findings
-  hooks install [--app <dir>] [--force]              Alias of rightkit-gate install-hook: the pre-push check and gate, and the advisory pre-commit ownership gate (pinned @rightkit/release)
+  ownership --staged [--app <dir>] [--json]          Manual check: scan the staged index for block-tier findings (no git hook runs it)
+  hooks install [--app <dir>]                        Alias of rightkit-gate install-hook: retires the pre-push gate and the pre-commit ownership hook an earlier release wrote; writes no git hook
   ownership enroll [--root] [--name <device>] [--root-fingerprint <sha256>] [--app <dir>]
                                                       Enroll one native key or create a signed-device request
   ownership approve-key <fingerprint|request.json>    Approve one pending device key from an active host

package/clippy-equivalence.mjs

@@ -0,0 +1,202 @@
+// Batch equivalence for the Clippy route (GATE-CONTRACT §1 "Batching", E14; item 8 rows 8.7 and 8.16). A batched Clippy invocation
+// replaces the per-crate ones only when it is shown to say the same thing: the same diagnostics (package, target, code, span), the
+// same resolved features for what it compiled (feature unification across the selected packages can change what compiles), and the
+// same engine and toolchain. This module is the comparison; `run` below drives real cargo over a checkout (a gate-owned export, a
+// Linux host) and writes the recorded comparison.
+//
+//   node clippy-equivalence.mjs --repo <dir> --out <dir> [--units a,b,...] [--target-dir <dir>] [--cargo cargo]
+//
+// Exit 0 when every batch is equivalent to its per-crate runs (after any unified crate was split out and the split re-run), 1 when not.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "./background-process.mjs";
+import { fileURLToPath } from "node:url";
+import { clippyArgs, clippyBatchPlan, sidecarBoundCrate } from "./deterministic-scans.mjs";
+import { rustCratePlan } from "./scan-digest.mjs";
+import { parseCargoMessages, summarizeMessages, toolchainIdentity } from "./clippy-route.mjs";
+
+export const EQUIVALENCE_SCHEMA = "rightkit.clippy-batch-equivalence/1";
+const sha256 = (v) => crypto.createHash("sha256").update(v).digest("hex");
+
+/** One diagnostic's identity for the comparison: package, target, level, code (else its first line) and primary span. */
+export const diagnosticKey = (d) => JSON.stringify([d.package, d.kind, d.target, d.level, d.code ?? String(d.message).split("\n")[0], d.span ? [d.span.file, d.span.line, d.span.column, d.span.lineEnd, d.span.columnEnd] : null]);
+const artifactKey = (a) => JSON.stringify([a.package, a.kind, a.target, a.test === true]);
+const multiset = (keys) => { const m = new Map(); for (const k of keys) m.set(k, (m.get(k) ?? 0) + 1); return m; };
+const diff = (a, b) => { const out = []; for (const [k, n] of a) { const d = n - (b.get(k) ?? 0); for (let i = 0; i < d; i += 1) out.push(k); } return out.sort(); };
+
+/**
+ * Compares each batch with the per-crate runs of its members. `groups`: `[{ id, units, batch: { messages, toolchain }, perCrate:
+ * [{ unit, crate, messages, toolchain }] }]` (`messages` are parsed cargo JSON objects; `units` the batch's unit names, which
+ * `perCrate` covers one for one). Returns `{ equivalent, groups, separate, failures }`: `separate` maps each unit whose batched
+ * compile differed (a different feature set for itself, or a dependency built with features no per-crate run built it with) to the
+ * reason, for the planner to keep it as its own invocation; any difference in diagnostics, or a missing or unequal toolchain
+ * identity, is a failure of the run (row 8.16).
+ */
+export function compareEquivalence({ groups }) {
+  const failures = []; const separate = new Map(); const rows = [];
+  for (const g of groups) {
+    const members = new Set(g.perCrate.map((p) => p.crate));
+    const batch = summarizeMessages(g.batch.messages);
+    const per = g.perCrate.map((p) => ({ ...p, run: summarizeMessages(p.messages) }));
+    const row = { id: g.id, units: g.units, crates: [...members].sort() };
+    // A member the batch never built (no artifact, no diagnostic) while another member of the batch failed is BLOCKED in the batch: with
+    // `-D warnings` a lint is a build failure, so a dependent of a failing member builds nothing under --keep-going where its own per-crate
+    // run (which lints only itself) would have run. That is the route's reported `blocked` state (row 8.4), not a clean result, and it is
+    // excluded from the comparison; a member the batch did not build while nothing in it failed is a difference.
+    const failedInBatch = new Set(batch.diagnostics.filter((d) => members.has(d.package) && d.level.startsWith("error")).map((d) => d.package));
+    const builtInBatch = new Set([...batch.artifacts.map((a) => a.package), ...batch.diagnostics.map((d) => d.package)]);
+    const blocked = [...members].filter((m) => !builtInBatch.has(m)).sort();
+    // Not built in the batch, nothing in it failed, and the member's own per-crate run did build it: a difference. A member neither run
+    // builds (a build script that fails on this host, a missing system library) is the same in both.
+    const builtOnItsOwn = (m) => per.some((p) => p.crate === m && p.run.artifacts.some((a) => a.package === m));
+    const unbuilt = failedInBatch.size === 0 ? blocked.filter(builtOnItsOwn) : [];
+    row.blockedInBatch = failedInBatch.size ? blocked : [];
+    const compared = (pkg) => members.has(pkg) && !row.blockedInBatch.includes(pkg);
+    // Diagnostics: the batch's, for its members, against each per-crate run's, for that crate.
+    const batchKeys = multiset(batch.diagnostics.filter((d) => compared(d.package)).map(diagnosticKey));
+    const perKeys = multiset(per.flatMap((p) => p.run.diagnostics.filter((d) => d.package === p.crate && compared(p.crate)).map(diagnosticKey)));
+    row.diagnostics = { batch: [...batchKeys.values()].reduce((a, n) => a + n, 0), perCrate: [...perKeys.values()].reduce((a, n) => a + n, 0), onlyInBatch: diff(batchKeys, perKeys), onlyInPerCrate: diff(perKeys, batchKeys) };
+    row.diagnosticsOfBlockedMembers = per.filter((p) => row.blockedInBatch.includes(p.crate)).reduce((n, p) => n + p.run.diagnostics.filter((d) => d.package === p.crate).length, 0);
+    if (row.diagnostics.onlyInBatch.length || row.diagnostics.onlyInPerCrate.length) failures.push(`${g.id}: the batch's diagnostics differ from its per-crate runs (${row.diagnostics.onlyInBatch.length} only in the batch, ${row.diagnostics.onlyInPerCrate.length} only per crate)`);
+    const unitOf = new Map(per.map((p) => [p.crate, p.unit]));
+    const byDiagnostics = new Set([...row.diagnostics.onlyInBatch, ...row.diagnostics.onlyInPerCrate].map((k) => JSON.parse(k)[0]));
+    for (const pkg of byDiagnostics) if (unitOf.has(pkg)) separate.set(unitOf.get(pkg), `batching changed the diagnostics of ${pkg} (item 8 row 8.7): kept as its own invocation`);
+    for (const pkg of unbuilt) if (unitOf.has(pkg)) separate.set(unitOf.get(pkg), `the batch never built ${pkg} although nothing in it failed (item 8 row 8.7)`);
+    // Resolved features: what each member was built with, in the batch against its own per-crate run, for every unit both built.
+    const unified = [];
+    for (const p of per) {
+      if (!compared(p.crate)) continue;
+      const own = (a) => a.package === p.crate;
+      const batchOf = new Map(); for (const a of batch.artifacts.filter(own)) batchOf.set(artifactKey(a), a.features);
+      const ownOf = new Map(); for (const a of p.run.artifacts.filter(own)) ownOf.set(artifactKey(a), a.features);
+      for (const [key, w] of ownOf) {
+        const b = batchOf.get(key);
+        if (b !== undefined && JSON.stringify(b) !== JSON.stringify(w)) unified.push({ unit: p.unit, crate: p.crate, unitKey: JSON.parse(key), batchFeatures: b, perCrateFeatures: w });
+      }
+    }
+    const seen = new Map();
+    for (const p of per) for (const a of p.run.artifacts.filter((x) => !members.has(x.package))) { const k = `${a.packageId}\0${artifactKey(a)}`; if (!seen.has(k)) seen.set(k, new Set()); seen.get(k).add(JSON.stringify(a.features)); }
+    const dependencies = [];
+    for (const a of batch.artifacts.filter((x) => !members.has(x.package))) {
+      const k = `${a.packageId}\0${artifactKey(a)}`;
+      const known = seen.get(k);
+      if (known && !known.has(JSON.stringify(a.features))) dependencies.push({ package: a.package, packageId: a.packageId, batchFeatures: a.features, perCrateFeatures: [...known].map((s) => JSON.parse(s)) });
+    }
+    // Third-party packages built with a union of the batch's features are recorded, not judged: cargo's features are additive, and the
+    // linted code is the members'. A member built with other features than its own run is what changes what compiles.
+    row.features = { unified, dependenciesBuiltWithOtherFeatures: dependencies.length };
+    row.dependenciesBuiltWithOtherFeatures = dependencies.map((d) => d.packageId).sort();
+    for (const u of unified) separate.set(u.unit, `batching changed the features ${u.crate} compiles with (${u.batchFeatures.join(",") || "none"} in the batch, ${u.perCrateFeatures.join(",") || "none"} on its own): feature unification (item 8 row 8.7)`);
+    // A batch that fails to build where every per-crate run builds, and whose failure no diagnostic of a member explains (a build script, a
+    // feature conflict): the unified features cannot all be on together (mutually exclusive ones). A failure a member's diagnostic explains
+    // is judged by the diagnostics and the unified-feature comparison above.
+    const exits = { batch: g.batch.exit ?? null, perCrate: per.map((p) => p.exit ?? null) };
+    row.exits = exits;
+    const exitDiffers = exits.batch !== null && exits.batch !== 0 && per.length > 0 && per.every((p) => p.exit === 0) && failedInBatch.size === 0;
+    if (exitDiffers) for (const p of per) separate.set(p.unit, "the batch fails to build where every per-crate run builds: its features cannot all be on together (item 8 row 8.7)");
+    // Toolchain identity (row 8.16): present and equal for the batch and every per-crate run.
+    const toolchains = [g.batch.toolchain, ...per.map((p) => p.toolchain)];
+    const equal = toolchains.every((t) => typeof t === "string" && t.trim() !== "") && new Set(toolchains).size === 1;
+    row.toolchain = { equal, batch: g.batch.toolchain ?? null, perCrate: [...new Set(per.map((p) => p.toolchain ?? null))] };
+    if (!equal) failures.push(`${g.id}: the toolchain identity of the batch and its per-crate runs is not one equal, present string (batch ${g.batch.toolchain ?? "missing"}; per crate ${row.toolchain.perCrate.join(", ")})`);
+    row.equivalent = !row.diagnostics.onlyInBatch.length && !row.diagnostics.onlyInPerCrate.length && !unified.length && !exitDiffers && !unbuilt.length && equal;
+    rows.push(row);
+  }
+  if (separate.size) failures.push(`${separate.size} unit(s) are kept separate: ${[...separate.keys()].sort().join(", ")}`);
+  return { schema: EQUIVALENCE_SCHEMA, equivalent: failures.length === 0, groups: rows, separate, failures };
+}
+
+// ---- the run over a checkout (real cargo) ---------------------------------------------------------------------------------------------
+
+function cargoRun({ cargo, args, cwd, env, messagesFile, clean = [] }) {
+  // Each run lints its packages afresh: cargo replays the cached diagnostics of a fresh unit, and what it cached depends on which run
+  // compiled the unit first, so a comparison over a shared target directory would compare cache history. Cleaning only the packages
+  // the run selects keeps the dependencies' compiled outputs warm.
+  if (clean.length) {
+    const c = spawnSync(cargo, ["clean", ...clean.flatMap((n) => ["-p", n])], { cwd, env, encoding: "utf8" });
+    if (c.status !== 0) throw new Error(`clean of ${clean.join(", ")} failed: ${String(c.stderr).slice(-300)}`);
+  }
+  const fd = fs.openSync(messagesFile, "w");
+  const t = Date.now();
+  let r;
+  try { r = spawnSync(cargo, args, { cwd, env, stdio: ["ignore", fd, "pipe"], encoding: "utf8", maxBuffer: 256 * 1024 * 1024 }); } finally { fs.closeSync(fd); }
+  const body = fs.readFileSync(messagesFile, "utf8");
+  return { status: r.status, signal: r.signal, stderr: String(r.stderr ?? "").slice(-4000), messages: parseCargoMessages(body).messages, ms: Date.now() - t, bytes: Buffer.byteLength(body), error: r.error?.message ?? null };
+}
+const withKeepGoing = (args) => { const i = args.indexOf("--"); return [...args.slice(0, i < 0 ? undefined : i), "--keep-going", ...(i < 0 ? [] : args.slice(i))]; };
+
+/**
+ * Runs the per-crate and the batched Clippy invocations of `units` (default: every workspace member) over `repo` with the same
+ * toolchain and one shared target directory, compares them, and when a batch is not equivalent because of feature unification
+ * splits the affected units out and runs and compares again. Writes `<out>/equivalence.json` (without raw messages) and returns it.
+ */
+export function run({ repo, out, units = null, targetDir = path.join(out, "target"), cargo = "cargo", env = process.env, log = (m) => process.stderr.write(`${m}\n`) }) {
+  fs.mkdirSync(out, { recursive: true });
+  const runEnv = { ...env, CARGO_TARGET_DIR: targetDir };
+  const meta = spawnSync(cargo, ["metadata", "--no-deps", "--format-version", "1", "--locked"], { cwd: repo, env: runEnv, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+  if (meta.status !== 0) throw new Error(`cargo metadata failed: ${String(meta.stderr).slice(-400)}`);
+  const metadata = JSON.parse(meta.stdout);
+  const byId = new Map(metadata.packages.map((p) => [p.id, p]));
+  const members = metadata.workspace_members.map((id) => byId.get(id)).filter(Boolean).sort((a, b) => (a.name < b.name ? -1 : 1));
+  const config = JSON.parse(fs.readFileSync(path.join(repo, "ci", "gate.config.json"), "utf8")).rust ?? {};
+  let solo = []; try { solo = JSON.parse(fs.readFileSync(path.join(repo, "ci", "shards.json"), "utf8")).solo ?? []; } catch { solo = []; }
+  const wanted = units ? new Set(units) : null;
+  const entries = [];
+  for (const p of members) {
+    if (wanted && !wanted.has(p.name)) continue;
+    const { lintSets } = rustCratePlan(config[p.name] ?? {});
+    for (const set of lintSets) entries.push({ name: p.name, crate: p.name, ws: ".", set, count: lintSets.length, env: null });
+  }
+  const sidecarBound = new Set(entries.filter((e) => sidecarBoundCrate({ dir: path.dirname(byId.get(members.find((m) => m.name === e.name).id).manifest_path) }).bound).map((e) => e.name));
+  const toolchainNow = () => toolchainIdentity({ spawn: (c, a, o) => spawnSync(c, a, { ...o, encoding: "utf8" }), env: runEnv, cwd: repo });
+  const toolchain = toolchainNow();
+  log(`equivalence: ${entries.length} crate configuration(s) of ${members.length} workspace member(s); toolchain ${toolchain}`);
+
+  const perCrateRuns = new Map();
+  const perCrate = (entry) => {
+    const key = `${entry.name}\0${entry.set.join(" ")}`;
+    if (!perCrateRuns.has(key)) {
+      const args = withKeepGoing(clippyArgs(entry.crate, { features: entry.set, messageFormat: "json", locked: true }));
+      const r = { toolchain: toolchainNow(), ...cargoRun({ cargo, args, cwd: repo, env: runEnv, clean: [entry.crate], messagesFile: path.join(out, `percrate-${sha256(key).slice(0, 10)}.jsonl`) }) };
+      log(`per-crate ${entry.name} [${entry.set.join(" ") || "default"}]: exit ${r.status} ${r.ms} ms ${r.bytes} bytes`);
+      perCrateRuns.set(key, { ...r, argv: args });
+    }
+    return perCrateRuns.get(key);
+  };
+  const runPass = (separate) => {
+    const plan = clippyBatchPlan(entries, { solo, separate, sidecarBound, toolchain: cargo });
+    const groups = [];
+    for (const b of plan.batches) {
+      const args = withKeepGoing(clippyArgs(b.crates, { features: b.set, messageFormat: "json", locked: true }));
+      const r = { toolchain: toolchainNow(), ...cargoRun({ cargo, args, cwd: repo, env: runEnv, clean: b.crates, messagesFile: path.join(out, `batch-${sha256(b.key).slice(0, 10)}.jsonl`) }) };
+      log(`batch ${b.id} (${b.crates.length} crate(s), ${b.set.join(" ") || "default"}): exit ${r.status} ${r.ms} ms ${r.bytes} bytes`);
+      const own = entries.filter((e) => b.units.includes(e.name) && e.set.join(" ") === b.set.join(" "));
+      groups.push({ id: b.id, units: b.units, reason: b.reason, argv: args, exit: r.status, batch: { messages: r.messages, toolchain: r.toolchain, exit: r.status }, perCrate: own.map((e) => { const p = perCrate(e); return { unit: e.name, crate: e.crate, messages: p.messages, toolchain: p.toolchain, exit: p.status, argv: p.argv }; }) });
+    }
+    return { plan, groups, result: compareEquivalence({ groups }) };
+  };
+  const strip = (pass) => ({ batches: pass.plan.batches.map((b) => ({ id: b.id, crates: b.crates, set: b.set, reason: b.reason, order: b.order })), notes: pass.plan.notes, groups: pass.result.groups, failures: pass.result.failures, exits: pass.groups.map((g) => ({ id: g.id, batchExit: g.exit, perCrateExits: g.perCrate.map((p) => [p.unit, p.exit]) })) });
+  const first = runPass(new Map());
+  let final = first; let second = null;
+  if (first.result.separate.size) { second = runPass(first.result.separate); final = second; }
+  const report = {
+    schema: EQUIVALENCE_SCHEMA, at: new Date().toISOString(), repo, toolchain, cargo,
+    coverage: { workspaceMembers: members.length, crateConfigurations: entries.length, units: [...new Set(entries.map((e) => e.name))].sort(), sidecarBound: [...sidecarBound], perCrateRuns: perCrateRuns.size, firstPassBatches: first.plan.batches.length },
+    equivalent: final.result.failures.filter((f) => !/are kept separate/.test(f)).length === 0 && final.result.separate.size === 0,
+    firstPass: strip(first), firstPassSeparate: Object.fromEntries(first.result.separate),
+    afterSplit: second ? strip(second) : null,
+  };
+  fs.writeFileSync(path.join(out, "equivalence.json"), `${JSON.stringify(report, null, 2)}\n`);
+  return report;
+}
+
+const invokedDirectly = (() => { try { return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })();
+if (invokedDirectly) {
+  const args = process.argv.slice(2);
+  const opt = (name) => { const i = args.indexOf(name); return i < 0 ? null : args[i + 1]; };
+  if (!opt("--repo") || !opt("--out")) { process.stderr.write("usage: clippy-equivalence.mjs --repo <dir> --out <dir> [--units a,b] [--target-dir <dir>] [--cargo cargo]\n"); process.exit(2); }
+  const report = run({ repo: path.resolve(opt("--repo")), out: path.resolve(opt("--out")), units: opt("--units") ? opt("--units").split(",") : null, ...(opt("--target-dir") ? { targetDir: path.resolve(opt("--target-dir")) } : {}), ...(opt("--cargo") ? { cargo: opt("--cargo") } : {}) });
+  process.stdout.write(`${JSON.stringify({ equivalent: report.equivalent, coverage: report.coverage, firstPassFailures: report.firstPass.failures, afterSplitFailures: report.afterSplit?.failures ?? null })}\n`);
+  process.exit(report.equivalent ? 0 : 1);
+}