@rightkit/release 0.6.8 → 0.6.11

package/class-a-launch-guard.mjs

@@ -0,0 +1,126 @@
+// Class A launch guard: class A runs before any compile, so a class A test row may not launch a compiler or an emitting build.
+//
+// The gate runs every class A test row with NODE_OPTIONS carrying `--import=<this file>`. In every Node process of the row (the
+// test runner, pnpm, workers, any Node child they launch, including one given a replacement environment) the child_process launchers are wrapped, and a launch is
+// refused (it throws, so the row fails) when the program, or a command line it hands to a shell, is a compile or an emitting
+// build: cargo, rustc, rustright, rightkit (broker client), tauri / cargo-tauri, tsc without --noEmit, tsup, esbuild, swc, rollup,
+// webpack, `vite build`, `next build`, or a package-manager run of a build / build:* script.
+//
+// Scope, exactly: launches from Node processes of the row. Not covered: a compiler API called inside a process
+// (typescript.createProgram().emit(), vite.build() / the rollup JS API), and launches by a non-Node program that does not load
+// this hook (rightkit#1240). esbuild's JS API is covered: it launches the esbuild service binary.
+//
+// A Node child handed a replacement environment keeps the guard (withGuard restores it). There is no exemption: a unit whose tests
+// launch stand-ins named like compilers (stub scripts can run anything) runs after class A instead (npm.<unit>.afterClassA).
+import childProcess from "node:child_process";
+import path from "node:path";
+import { syncBuiltinESMExports } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const INSTALLED = Symbol.for("rightkit.classA.launchGuard");
+export const LAUNCH_GUARD_IMPORT = `--import=${pathToFileURL(fileURLToPath(import.meta.url)).href}`;
+export const REFUSAL_CODE = "RK_CLASS_A_COMPILE_LAUNCH";
+const COMPILERS = new Set(["cargo", "rustc", "rustright", "rightkit", "tauri", "cargo-tauri", "tsup", "esbuild", "swc", "rollup", "webpack"]);
+const PACKAGE_MANAGERS = new Set(["pnpm", "npm", "yarn", "bun"]);
+const SHELLS = new Set(["sh", "bash", "zsh", "dash", "cmd", "powershell", "pwsh"]);
+const WRAPPERS = new Set(["env", "npx", "pnpx", "exec", "time", "nice"]);
+// Options that take a value, per package manager: pnpm's `-w` is `--workspace-root` (a flag), npm's `-w` is `--workspace <name>`.
+const OPTIONS_WITH_VALUES = Object.freeze({
+  pnpm: new Set(["--filter", "-F", "--dir", "-C"]),
+  npm: new Set(["--workspace", "-w", "--prefix"]),
+  yarn: new Set(["--cwd"]),
+  bun: new Set(["--cwd", "--filter"]),
+});
+
+const base = (p) => path.basename(String(p ?? "").replaceAll("\\", "/")).replace(/\.(exe|cmd|bat|ps1|js|mjs|cjs)$/i, "").toLowerCase();
+
+/** A shell command line split into commands (on && || ; |) and words, quotes removed: enough to read what a `sh -c` text launches. */
+export function shellWords(text) {
+  const commands = []; let words = []; let word = ""; let quote = null;
+  const end = () => { if (word) { words.push(word); word = ""; } };
+  const s = String(text);
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (quote) { if (c === quote) quote = null; else word += c; continue; }
+    if (c === "'" || c === "\"") { quote = c; continue; }
+    if (/\s/.test(c)) { end(); continue; }
+    if (c === ";" || c === "|" || c === "&") { end(); if (words.length) commands.push(words); words = []; continue; }
+    word += c;
+  }
+  end(); if (words.length) commands.push(words);
+  return commands;
+}
+
+/** Why `[program, ...args]` is a compile or an emitting build, or null. */
+export function compileLaunch(program, args = []) {
+  let words = [String(program), ...args.map(String)];
+  for (let guard = 0; guard < 8 && words.length; guard++) {
+    const name = base(words[0]);
+    if (name === "node" && words[1] && !String(words[1]).startsWith("-")) { words = words.slice(1); continue; }
+    if (WRAPPERS.has(name)) { words = words.slice(1).filter((w, i, a) => !(i === 0 && /^[A-Z_][A-Z0-9_]*=/.test(w))); continue; }
+    if (SHELLS.has(name)) {
+      const at = words.findIndex((w, i) => i > 0 && /^(-c|\/c|\/s|-Command|-command)$/i.test(w));
+      if (at < 0 || !words[at + 1]) return null;
+      for (const cmd of shellWords(words.slice(at + 1).join(" "))) { const why = compileLaunch(cmd[0], cmd.slice(1)); if (why) return why; }
+      return null;
+    }
+    const rest = words.slice(1);
+    if (COMPILERS.has(name)) return name;
+    if (name === "tsc") return rest.some((w) => /^--?noEmit(=true)?$/i.test(w)) ? null : "tsc (emits)";
+    if (name === "vite" || name === "next") return rest.find((w) => !w.startsWith("-")) === "build" ? `${name} build` : null;
+    if (PACKAGE_MANAGERS.has(name)) {
+      let next = null;
+      for (let j = 0; j < rest.length; j++) {
+        if (OPTIONS_WITH_VALUES[name].has(rest[j])) { j++; continue; }
+        if (rest[j].startsWith("-") || rest[j] === "run" || rest[j] === "run-script") continue;
+        if (/^build(:|$)/.test(rest[j])) return `${name} ${rest[j]}`;
+        if (rest[j] === "exec" || rest[j] === "dlx" || rest[j] === "x") next = rest.slice(j + 1);
+        break;
+      }
+      if (!next || !next.length) return null;
+      words = next; continue;
+    }
+    return null;
+  }
+  return null;
+}
+
+function refuse(why, program, args) {
+  const error = new Error(`class A refuses a compile/emit launch (${why}): ${[program, ...args].join(" ").slice(0, 300)}. Class A runs before any compile; this test row belongs after class A.`);
+  error.code = REFUSAL_CODE;
+  try { process.stderr.write(`rightkit-gate: ${error.message}\n`); } catch { /* stderr closed */ }
+  throw error;
+}
+
+function check(program, args, options) {
+  const argv = Array.isArray(args) ? args : [];
+  if (options?.shell) { for (const cmd of shellWords([program, ...argv].join(" "))) { const why = compileLaunch(cmd[0], cmd.slice(1)); if (why) refuse(why, program, argv); } return; }
+  const why = compileLaunch(program, argv);
+  if (why) refuse(why, program, argv);
+}
+
+/** `env` with the guard switched on and loaded (NODE_OPTIONS appended, never replaced). */
+export function withGuard(env) {
+  const current = String(env.NODE_OPTIONS ?? "");
+  return { ...env, RIGHTKIT_CLASS_A_LAUNCH_GUARD: "1", NODE_OPTIONS: current.includes(LAUNCH_GUARD_IMPORT) ? current : `${current} ${LAUNCH_GUARD_IMPORT}`.trim() };
+}
+
+export function installLaunchGuard() {
+  if (globalThis[INSTALLED]) return;
+  globalThis[INSTALLED] = true;
+  const o = { ...childProcess };
+  const split = (args) => (Array.isArray(args[1]) ? [args[0], args[1], args[2]] : [args[0], [], args[1]]);
+  // A child handed a replacement environment keeps the guard: its NODE_OPTIONS (and the switch) are restored into that env.
+  // The caller's options object is never modified: the launch gets a copy carrying the restored env.
+  const keep = (a) => a.map((x) => (x && typeof x === "object" && !Array.isArray(x) && x.env && typeof x.env === "object" ? { ...x, env: withGuard(x.env) } : x));
+  childProcess.spawn = function (...a) { const [p, v, opt] = split(a); check(p, v, opt); return o.spawn.apply(this, keep(a)); };
+  childProcess.spawnSync = function (...a) { const [p, v, opt] = split(a); check(p, v, opt); return o.spawnSync.apply(this, keep(a)); };
+  childProcess.execFile = function (...a) { const [p, v, opt] = split(a); check(p, v, opt); return o.execFile.apply(this, keep(a)); };
+  childProcess.execFileSync = function (...a) { const [p, v, opt] = split(a); check(p, v, opt); return o.execFileSync.apply(this, keep(a)); };
+  childProcess.exec = function (cmd, ...a) { for (const c of shellWords(cmd)) { const why = compileLaunch(c[0], c.slice(1)); if (why) refuse(why, cmd, []); } return o.exec.call(this, cmd, ...keep(a)); };
+  childProcess.execSync = function (cmd, ...a) { for (const c of shellWords(cmd)) { const why = compileLaunch(c[0], c.slice(1)); if (why) refuse(why, cmd, []); } return o.execSync.call(this, cmd, ...keep(a)); };
+  childProcess.fork = function (modulePath, ...a) { const v = Array.isArray(a[0]) ? a[0] : []; check(modulePath, v, {}); return o.fork.call(this, modulePath, ...keep(a)); };
+  syncBuiltinESMExports();
+}
+
+if (process.env.RIGHTKIT_CLASS_A_LAUNCH_GUARD === "1") installLaunchGuard();

package/cli/right-release.mjs

@@ -25,6 +25,7 @@ const commands = new Map([
   ["sign-candidate", "sign-candidate.mjs"],
   ["engine-locate", "engine-locator.mjs"],
   ["stage-sidecar", "stage-sidecar-command.mjs"],
+  ["assemble-app", "assemble-app-command.mjs"],
   ["init", "init-command.mjs"],
   ["pe", "pe-content.mjs"],
   ["icons", "icon-pack.mjs"],
@@ -58,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);
@@ -128,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") {
@@ -269,6 +294,7 @@ Commands:
   icons ico|icns --out <file> --frame <PNG>... [--dir <folder>]  Pack hand-tuned per-size PNG frames into an ICO or ICNS
   init --name <Product Name> --id <reverse.dns.bundle.id> [--slug <lowercase>] [--dir <root>] [--dry-run]  Rename the desktop app template into a real app, in place
   stage-sidecar [--config <file>] [--target <triple>] [--json]  Stage declarative sidecars into src-tauri/binaries (Tauri externalBin naming)
+  assemble-app --platform mac|win [--profile release|dev] [--build] [--out <dir>] | --verify-staged [--signed] | --package  Assemble the declared composite app (assembly.<platform>) for production packaging; the same definition installs through dev
   recipe-build --plan <json> | --plan-file <path> [--app-root <dir>]  Run a package recipe: prepare steps, the Tauri build, postBuild steps (argv, no shell, fail closed)
   dmg build --app <.app> --out <dmg> --volname <name> [--background <png>] [--spec <appdmg.json>]
             [--icon-size N] [--app-position x,y] [--applications-position x,y] [--window w,h] [--window-position x,y]
@@ -360,7 +386,7 @@ Commands:
   signing-agent install|uninstall|status              Manage invisible Aqua-session signing service
   check [--repo <dir>] [--config <file>] [--commit <rev> | --worktree] [--only <rule,...>] [--list] [--print-baseline] [--baseline <file>]
                                                       The offline app check, same as rightkit-gate check: committed files only, every finding in one run (exit 0 pass, 1 findings, 2 could not run).
-                                                      Build, package, dev, test, web-build, swift-package, recipe-build, stage-sidecar, qa, upload, publish, publish-update, github, doctor,
+                                                      Build, package, dev, test, web-build, swift-package, recipe-build, assemble-app, stage-sidecar, qa, upload, publish, publish-update, github, doctor,
                                                       sign-windows, sign-updater, sign-candidate, sign-dev-artifact, addon build and create-mac-updater run it first and start nothing when it is red; there is no flag that skips it.
                                                       Baseline: .rightkit/app-check-baseline.json (entries carry issue, added and sunset; the sunset is at most 90 days after added)
   doctor [--platform mac|win] [--gates] [--inspect] [--strict]
@@ -371,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);
+}