@rightkit/release 0.6.27 → 0.6.29

package/build-helper-trace.mjs

@@ -75,12 +75,12 @@ export function readHostList(file, { readFile = (f) => fs.readFileSync(f, "utf8"
 
 /** Record one trace verdict in the list (atomic write). */
 /** Tracers whose verdicts count: each follows the build's whole process tree. fs_usage (name-filtered) verdicts recorded before do not count. */
-export const TRUSTED_TRACERS = Object.freeze(["eslogger", "strace-ff", "etw"]);
-export const TRACER_OF = Object.freeze({ darwin: "eslogger", linux: "strace-ff", win32: "etw" });
+export const TRUSTED_TRACERS = Object.freeze(["eslogger", "etw"]);
+export const TRACER_OF = Object.freeze({ darwin: "eslogger", win32: "etw" });
 
 export function recordTrace(file, unit, verdict, { now = () => new Date().toISOString(), fsApi = fs, tracer = TRACER_OF[process.platform] } = {}) {
   const list = readHostList(file, { readFile: (f) => fsApi.readFileSync(f, "utf8"), exists: (f) => fsApi.existsSync(f) });
-  list.units[unit.key] = { crate: unit.crate, version: unit.version, checksum: unit.checksum, features: unit.features, target: unit.target, toolchain: unit.toolchain, role: unit.role, verdict: verdict.ok ? "pass" : "fail", outside: verdict.outside ?? [], tracer, tracedAt: now() };
+  list.units[unit.key] = { crate: unit.crate, version: unit.version, checksum: unit.checksum, features: unit.features, target: unit.target, toolchain: unit.toolchain, role: unit.role, verdict: verdict.ok ? "pass" : verdict.unbuildable ? "unbuildable" : "fail", outside: verdict.outside ?? [], tracer, tracedAt: now() };
   fsApi.mkdirSync(path.dirname(file), { recursive: true });
   const tmp = `${file}.tmp-${process.pid}`;
   fsApi.writeFileSync(tmp, `${JSON.stringify(list, null, 2)}\n`);
@@ -105,6 +105,8 @@ export function checkBuildHelpers(units, list) {
   for (const u of units) {
     const entry = byKey.get(u.key);
     if (!entry || !u.checksum || !TRUSTED_TRACERS.includes(entry.tracer)) untraced.push(u);
+    // Unbuildable on this host for its target: the gate builds nothing that runs it here, so it is neither refused nor traced again.
+    else if (entry.verdict === "unbuildable") continue;
     else if (entry.verdict !== "pass") failed.push({ unit: u, outside: entry.outside ?? [] });
   }
   return { ok: untraced.length === 0 && failed.length === 0, untraced, failed };
@@ -157,27 +159,6 @@ export function parseFsUsageWrites(text) {
   return [...out];
 }
 
-/**
- * The written paths of Linux `strace -f -e trace=<file calls>` output: successful calls that create, write, rename, link or remove a file.
- * An open counts when its flags include O_WRONLY, O_RDWR, O_CREAT, O_TRUNC or O_APPEND; every other listed call mutates by definition.
- * A failed call (`= -1`) wrote nothing. Every quoted path of a mutating call is taken (rename names both); a relative path resolves
- * against `cwd` (the traced cargo's directory; a build script that changes directory is resolved approximately, a recorded limit).
- */
-export function parseStraceWrites(text, { cwd = "/" } = {}) {
-  const OPEN = /\b(open|openat|openat2)\((?:[^"]*?)"((?:[^"\\]|\\.)*)"[^)]*?\b(O_[A-Z_|]+)/;
-  const MUTATING = /\b(creat|rename|renameat|renameat2|unlink|unlinkat|mkdir|mkdirat|rmdir|link|linkat|symlink|symlinkat|truncate|chmod|fchmodat|chown|fchownat|lchown|utimensat|utimes)\(/;
-  const out = new Set();
-  for (const line of String(text).split(/\r?\n/)) {
-    if (/=\s*-1\s/.test(line) || /<unfinished \.\.\.>/.test(line)) continue;
-    let paths = [];
-    const open = OPEN.exec(line);
-    if (open) { if (/O_WRONLY|O_RDWR|O_CREAT|O_TRUNC|O_APPEND/.test(open[3])) paths = [open[2]]; }
-    else if (MUTATING.test(line)) paths = [...line.matchAll(/"((?:[^"\\]|\\.)*)"/g)].map((m) => m[1]);
-    for (const p of paths) if (p) out.add(path.posix.isAbsolute(p) ? p : path.posix.resolve(cwd, p));
-  }
-  return [...out];
-}
-
 /** The repository's committed list (`.rightkit/build-helper-trace.json`, same schema): reviewed passes every host and CI reads. */
 export const repoListPath = (workspaceRoot) => path.join(workspaceRoot, ".rightkit", "build-helper-trace.json");
 
@@ -210,7 +191,7 @@ export function parseEtwWrites(xml, { rootPid, devices = {} }) {
       if (tree.has(parent)) tree.add(child);
     }
   }
-  const toDos = (p) => { if (!p) return null; for (const [dev, letter] of Object.entries(devices)) if (p.toLowerCase().startsWith(dev.toLowerCase())) return letter + p.slice(dev.length); return p; };
+  const toDos = (p) => { if (!p) return null; for (const [dev, letter] of Object.entries(devices)) if (p.toLowerCase().startsWith(`${dev.toLowerCase()}\\`)) return letter + p.slice(dev.length); return p; };
   const names = new Map(); const out = new Set();
   for (const ev of events) {
     if (provider(ev) !== "Microsoft-Windows-Kernel-File" || !tree.has(pidOf(ev))) continue;
@@ -266,13 +247,6 @@ export function parseEsloggerWrites(text, { rootPid }) {
   return [...out];
 }
 
-/** The strace -ff output files (`<prefix>.<pid>`, one per process: no call is ever split across lines). */
-export function readStraceFiles(prefix, { fsApi = fs } = {}) {
-  const dir = path.dirname(prefix); const base = path.basename(prefix);
-  return fsApi.readdirSync(dir).filter((n) => n.startsWith(`${base}.`)).map((n) => fsApi.readFileSync(path.join(dir, n), "utf8")).join("\n");
-}
-
-
 /** Calls `fn(record)` for every record of `file` separated by `sep`, reading 8 MiB at a time (a whole-run trace can pass Node's string limit). */
 export function forEachRecord(file, sep, fn, { fsApi = fs } = {}) {
   const fd = fsApi.openSync(file, "r"); const buf = Buffer.alloc(8 << 20); let rest = "";
@@ -325,22 +299,45 @@ export function etwWritesByRoot(file, roots, devices = {}) {
   const id = (ev) => Number(/<EventID>(\d+)<\/EventID>/.exec(ev)?.[1]);
   const pidOf = (ev) => Number(/ProcessID="(\d+)"/.exec(ev)?.[1]);
   const provider = (ev) => /Provider Name="([^"]+)"/.exec(ev)?.[1] ?? "";
-  const parent = new Map();
+  // Windows reuses a process id within seconds, so a pid belongs to a build only for one lifetime: from its ProcessStart (1) to its
+  // ProcessStop (2), in recording order. A build's root is the start of a root pid whose parent is the build runner: the parent most of
+  // the root pids were started by (a pid-only match took PowerShell, Pulse and sccache processes that later reused a build's pid).
+  const parentsOfRoots = new Map();
   forEachRecord(file, "</Event>", (ev) => {
-    if (provider(ev) === "Microsoft-Windows-Kernel-Process" && id(ev) === 1) parent.set(Number(field(ev, "ProcessID")), Number(field(ev, "ParentProcessID")));
+    if (provider(ev) !== "Microsoft-Windows-Kernel-Process" || id(ev) !== 1) return;
+    const pid = Number(field(ev, "ProcessID")); if (!roots.has(pid)) return;
+    const ppid = Number(field(ev, "ParentProcessID")); parentsOfRoots.set(ppid, (parentsOfRoots.get(ppid) ?? 0) + 1);
   });
-  const rootOf = rootFinder(parent, roots); const out = new Map([...roots].map((r) => [r, new Set()]));
-  const toDos = (p) => { if (!p) return null; for (const [dev, letter] of Object.entries(devices)) if (p.toLowerCase().startsWith(dev.toLowerCase())) return letter + p.slice(dev.length); return p; };
+  const runner = [...parentsOfRoots].sort((a, b) => b[1] - a[1])[0]?.[0];
+  const out = new Map([...roots].map((r) => [r, new Set()]));
+  const live = new Map();
+  const toDos = (p) => { if (!p) return null; for (const [dev, letter] of Object.entries(devices)) if (p.toLowerCase().startsWith(`${dev.toLowerCase()}\\`)) return letter + p.slice(dev.length); return p; };
+  // FileKey -> path for files open on the host. Every kept string is a copy: a regex match is a slice of its 8 MiB read chunk and keeps the
+  // whole chunk alive (holding names that way ran the Dell out of heap).
+  const own = (s) => (s == null ? s : Buffer.from(s, "utf8").toString("utf8"));
   const names = new Map();
   forEachRecord(file, "</Event>", (ev) => {
-    if (provider(ev) !== "Microsoft-Windows-Kernel-File") return;
-    const n = id(ev); const fileObject = field(ev, "FileObject");
-    if (n === 12) names.set(fileObject, field(ev, "FileName"));
-    const root = rootOf(pidOf(ev)); if (root === null) return;
-    const add = (p) => { const d = toDos(p); if (d) out.get(root).add(d); };
+    const prov = provider(ev); const n = id(ev);
+    if (prov === "Microsoft-Windows-Kernel-Process") {
+      const pid = Number(field(ev, "ProcessID"));
+      if (n === 1) {
+        const ppid = Number(field(ev, "ParentProcessID"));
+        if (roots.has(pid) && ppid === runner) live.set(pid, pid);
+        else if (live.has(ppid)) live.set(pid, live.get(ppid));
+        else live.delete(pid);
+      } else if (n === 2) live.delete(pid);
+      return;
+    }
+    if (prov !== "Microsoft-Windows-Kernel-File") return;
+    // A write names its file by FileKey, which NameCreate (10) maps to the path until NameDelete (11), from whatever process logs them. The
+    // session records no close, and FileObject addresses are reused, so mapping a write by FileObject named files the build only read.
+    if (n === 10) { names.set(own(field(ev, "FileKey")), own(field(ev, "FileName"))); return; }
+    if (n === 11) { names.delete(field(ev, "FileKey")); return; }
+    const root = live.get(pidOf(ev)); if (root === undefined) return;
+    const add = (p) => { const d = toDos(p); if (d) out.get(root).add(own(d)); };
     if (n === 12) { const disposition = (Number(field(ev, "CreateOptions") ?? 0) >>> 24) & 0xff; if (disposition !== 1) add(field(ev, "FileName")); }
     else if (n === 30) add(field(ev, "FileName"));
-    else if (n === 16) add(names.get(fileObject));
+    else if (n === 16) add(names.get(field(ev, "FileKey")));
     else if (n === 26 || n === 27) add(field(ev, "FilePath") ?? field(ev, "FileName"));
   });
   return new Map([...out].map(([r, s]) => [r, [...s]]));

package/build-helpers-command.mjs

@@ -1,19 +1,24 @@
 #!/usr/bin/env node
 // `right-release build-helpers check [--manifest-path <Cargo.toml>]` (Class A, rightkit#1450) and
-// `right-release build-helpers trace [--manifest-path <Cargo.toml>]` (the one-time trace: eslogger on macOS (sudo + Full Disk Access), strace -ff on Linux, ETW on Windows (Administrator)).
+// `right-release build-helpers trace [--manifest-path <Cargo.toml>]` (the one-time trace: eslogger on macOS (sudo + Full Disk Access), ETW on Windows (Administrator)).
+// Only broker hosts (Mac, Dell) vet build helpers (Adrian, 2026-11-03: "linux is the wrong target and it has to be only where we have brokers"):
+// a Linux host or CI runner is a throwaway container, so check and trace do nothing there.
 //
 // check: reads the workspace's resolved graph (`cargo metadata --format-version 1 --locked`, a non-compiling call run directly: GATE-CONTRACT
 // GC-A11), its Cargo.lock, the host triple and toolchain (`rustc -vV`), and the host list, and refuses (exit 1) when any build-helper unit is
 // untraced or traced as writing outside its build directories, naming each.
 // trace: for each untraced unit, builds the workspace's dependency alone (`cargo build -p <crate>@<version> --locked`) under the host's tracer, into a
 // scratch target, judges every write against OUT_DIR / target / CARGO_HOME / temp, and records the verdict in the host list.
-// check --trace-missing (Linux only, where strace needs no admin; CI and Linux hosts): untraced units are traced first, then judged.
+// Units are listed per target the host compiles: its own and the two cross-check targets (GC-A14), each from `cargo metadata --filter-platform`.
+// A unit that does not build on this host for its target is recorded once as unbuildable and skipped (Adrian, 2026-11-03: "if it's not compiling
+// on the OS, and doesn't generate output ... why not skip it?"): the gate's own scan cannot build it there either.
 import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { buildHelperRefusal, buildHelperUnits, checkBuildHelpers, hostListPath, esloggerWritesByRoot, etwWritesByRoot, judgeTrace, mergeLists, parseStraceWrites, readStraceFiles, readHostList, recordTrace, repoListPath } from "./build-helper-trace.mjs";
+import { buildHelperRefusal, buildHelperUnits, checkBuildHelpers, hostListPath, esloggerWritesByRoot, etwWritesByRoot, judgeTrace, mergeLists, readHostList, recordTrace, repoListPath } from "./build-helper-trace.mjs";
+import { crossCompileEnv, crossTargetsFor } from "./cross-targets.mjs";
 import { resolveManagedRoots } from "./managed-roots.mjs";
 import { directCargoPath } from "./managed-cargo.mjs";
 
@@ -43,13 +48,19 @@ const start = (i) => new Promise((resolve) => {
 const worker = async () => { while (next < jobs.length) { const i = next++; await start(i); } };
 Promise.all(Array.from({ length: Math.min(limit, jobs.length) }, worker)).then(() => fs.writeFileSync(process.argv[2], JSON.stringify(results)));`;
 
-export function inventory({ manifestPath, run = spawnSync, readFile = (f) => fs.readFileSync(f, "utf8") }) {
-  const args = ["metadata", "--format-version", "1", "--locked", ...(manifestPath ? ["--manifest-path", manifestPath] : [])];
-  const r = run("cargo", args, { encoding: "utf8", maxBuffer: 1 << 28 });
-  if (r.error || r.status !== 0) throw new Error(`cargo ${args.join(" ")} failed (${r.error?.message ?? `exit ${r.status}`}): ${String(r.stderr ?? "").trim().split(/\r?\n/).slice(-2).join(" | ")}`);
-  const metadata = JSON.parse(r.stdout);
-  const lockText = readFile(path.join(metadata.workspace_root, "Cargo.lock"));
-  return { metadata, units: buildHelperUnits(metadata, lockText, hostFacts(run)) };
+export function inventory({ manifestPath, run = spawnSync, readFile = (f) => fs.readFileSync(f, "utf8"), platform = process.platform }) {
+  const host = hostFacts(run);
+  // The host's own target plus the two targets every crate is cross-checked for: each target's resolved graph and features.
+  const targets = [host.target, ...crossTargetsFor({}, platform)];
+  let metadata = null; const units = [];
+  for (const target of targets) {
+    const args = ["metadata", "--format-version", "1", "--locked", "--filter-platform", target, ...(manifestPath ? ["--manifest-path", manifestPath] : [])];
+    const r = run("cargo", args, { encoding: "utf8", maxBuffer: 1 << 28 });
+    if (r.error || r.status !== 0) throw new Error(`cargo ${args.join(" ")} failed (${r.error?.message ?? `exit ${r.status}`}): ${String(r.stderr ?? "").trim().split(/\r?\n/).slice(-2).join(" | ")}`);
+    const m = JSON.parse(r.stdout); metadata ??= m;
+    units.push(...buildHelperUnits(m, readFile(path.join(m.workspace_root, "Cargo.lock")), { target, toolchain: host.toolchain }));
+  }
+  return { metadata, units, host: host.target };
 }
 
 // Every Cargo workspace (a directory holding Cargo.lock) under `root`, skipping build outputs, dependencies and vendored copies.
@@ -63,7 +74,8 @@ export function cargoWorkspaces(root, { depth = 4, fsApi = fs } = {}) {
   };
   walk(root, depth);
   // Only repositories the gate builds: the workspace's repository root (nearest .git) carries a .rightkit directory.
-  const gated = (dir) => { for (let d = dir; ; d = path.dirname(d)) { if (fsApi.existsSync(path.join(d, ".git"))) return fsApi.existsSync(path.join(d, ".rightkit")); if (path.dirname(d) === d) return false; } };
+  // A gate snapshot of a commit (<managed root>/snapshots/<key>) has .rightkit but no .git: the first ancestor with either decides.
+  const gated = (dir) => { for (let d = dir; ; d = path.dirname(d)) { if (fsApi.existsSync(path.join(d, ".rightkit"))) return true; if (fsApi.existsSync(path.join(d, ".git"))) return false; if (path.dirname(d) === d) return false; } };
   return found.filter(gated).sort();
 }
 
@@ -118,20 +130,15 @@ function mainWith(argv, { env, platform, run, log, err }) {
   const [sub, ...rest] = argv;
   const at = rest.indexOf("--manifest-path");
   const manifestPath = at >= 0 ? rest[at + 1] : undefined;
+  if (platform !== "darwin" && platform !== "win32") { log(`right-release build-helpers ${sub}: nothing to do on ${platform}; only broker hosts (Mac, Dell) vet build helpers`); return 0; }
   const listFile = hostListPath(resolveManagedRoots({ env, platform }).dataRoot, platform);
   let inv;
-  try { inv = inventory({ manifestPath, run }); } catch (e) { err(`right-release build-helpers: ${e.message}`); return 2; }
+  try { inv = inventory({ manifestPath, run, platform }); } catch (e) { err(`right-release build-helpers: ${e.message}`); return 2; }
   // The host's own list and the repository's committed list (.rightkit/build-helper-trace.json): CI and every host read the same reviewed
   // passes, and a host traces only what neither holds.
   const repoFile = repoListPath(inv.metadata.workspace_root);
   const list = mergeLists(readHostList(listFile), readHostList(repoFile));
   const verdict = checkBuildHelpers(inv.units, list);
-  if (sub === "check" && !verdict.ok && rest.includes("--trace-missing") && platform === "linux" && verdict.untraced.length) {
-    log(`right-release build-helpers: ${verdict.untraced.length} untraced unit(s) on this Linux host; tracing them now (strace -ff)`);
-    const traced = mainWith(["trace", ...(manifestPath ? ["--manifest-path", manifestPath] : [])], { env, platform, run, log, err });
-    if (traced !== 0) return traced;
-    return mainWith(["check", ...(manifestPath ? ["--manifest-path", manifestPath] : [])], { env, platform, run, log, err });
-  }
   if (sub === "check") {
     if (verdict.ok) { log(`right-release build-helpers: ${inv.units.length} build-helper unit(s), every one traced on this host (${listFile})`); return 0; }
     for (const line of buildHelperRefusal(verdict)) err(line);
@@ -143,18 +150,28 @@ function mainWith(argv, { env, platform, run, log, err }) {
       // ETW kernel sessions need an elevated shell; kernel paths are mapped back to drive letters once (QueryDosDevice).
       const admin = run("net", ["session"], { encoding: "utf8" });
       if (admin.status !== 0) { err("right-release build-helpers trace: run from an elevated (Administrator) shell; ETW kernel tracing needs it"); return 2; }
-      const map = run("powershell", ["-NoProfile", "-Command", "$s='[DllImport(\\\"kernel32.dll\\\")] public static extern uint QueryDosDevice(string d, System.Text.StringBuilder b, uint m);'; $k=Add-Type -MemberDefinition $s -Name K -Namespace W -PassThru; foreach($d in [IO.DriveInfo]::GetDrives()){ $l=$d.Name.Substring(0,2); $b=New-Object Text.StringBuilder 512; [void]$k::QueryDosDevice($l,$b,512); \"$l=$b\" }"], { encoding: "utf8" });
+      const map = run("powershell", ["-NoProfile", "-Command", "$s='[DllImport(\"kernel32.dll\")] public static extern uint QueryDosDevice(string d, System.Text.StringBuilder b, uint m);'; $k=Add-Type -MemberDefinition $s -Name K -Namespace W -PassThru; foreach($d in [IO.DriveInfo]::GetDrives()){ $l=$d.Name.Substring(0,2); $b=New-Object Text.StringBuilder 512; [void]$k::QueryDosDevice($l,$b,512); \"$l=$b\" }"], { encoding: "utf8" });
       for (const line of String(map.stdout ?? "").split(/\r?\n/)) { const m = /^([A-Z]:)=(\\Device\\\S+)$/.exec(line.trim()); if (m) devices[m[2]] = m[1]; }
+      // Without the map every kernel path would be judged outside the allowed folders: stop instead of recording false verdicts.
+      if (!Object.keys(devices).length) { err(`right-release build-helpers trace: could not map kernel device paths to drive letters (QueryDosDevice): ${String(map.stderr ?? "").trim().split(/\r?\n/)[0] ?? ""}`); return 2; }
     }
     const recordRepo = rest.includes("--record-repo");
     const cargoHome = env.CARGO_HOME ?? path.join(os.homedir(), ".cargo");
     // Parallel: `--jobs N` builds at once (default 4). Each build is its own process tree, rooted at its own cargo, in its own scratch
-    // target, and is judged only on the writes of that tree (eslogger and ETW events name their process; strace -ff writes one file per
-    // process of its own run). The cores are shared out so the builds do not fight over them.
+    // target, and is judged only on the writes of that tree (eslogger and ETW events name their process). The cores are shared out so the
+    // builds do not fight over them.
     const jobsAt = rest.indexOf("--jobs");
     const jobs = Math.max(1, Number.parseInt(jobsAt >= 0 ? rest[jobsAt + 1] : "4", 10) || 4);
     const perBuildJobs = String(Math.max(1, Math.floor(os.cpus().length / jobs)));
-    const pending = [...verdict.untraced, ...verdict.failed.map((f) => f.unit)];
+    // A cross target builds with the provisioned zig C toolchain; without it those units wait (never recorded as unbuildable).
+    const crossEnv = new Map(); const waiting = [];
+    const pending = [...verdict.untraced, ...verdict.failed.map((f) => f.unit)].filter((unit) => {
+      if (unit.target === inv.host) return true;
+      if (!crossEnv.has(unit.target)) crossEnv.set(unit.target, crossCompileEnv(unit.target, undefined, platform) ?? null);
+      if (crossEnv.get(unit.target)) return true;
+      waiting.push(unit); return false;
+    });
+    if (waiting.length) err(`right-release build-helpers trace: ${waiting.length} cross-target unit(s) not traced: the zig C toolchain is not provisioned (scripts/ci/provision-zig.mjs)`);
     log(`right-release build-helpers trace: ${pending.length} unit(s), ${jobs} at a time`);
     if (!pending.length) return 0;
     const prepared = pending.map((unit) => {
@@ -170,25 +187,49 @@ function mainWith(argv, { env, platform, run, log, err }) {
       fs.writeFileSync(path.join(probe, "src", "lib.rs"), "");
       try { fs.copyFileSync(path.join(inv.metadata.workspace_root, "Cargo.lock"), path.join(probe, "Cargo.lock")); } catch { /* the probe resolves on its own */ }
       // Release profile, like every other build (GATE-CONTRACT GC-A15): no dev or debug build anywhere, a throwaway probe included.
-      const buildArgs = ["build", "--profile", "release", "--manifest-path", path.join(probe, "Cargo.toml"), "--target-dir", target];
-      const buildEnv = { ...env, CARGO_TARGET_DIR: target, CARGO_BUILD_JOBS: perBuildJobs };
-      const straceOut = path.join(scratch, "strace");
-      const job = platform === "linux"
-        ? { cmd: "strace", args: ["-ff", "-qq", "-o", straceOut, "-e", "trace=open,openat,openat2,creat,rename,renameat,renameat2,unlink,unlinkat,mkdir,mkdirat,rmdir,link,linkat,symlink,symlinkat,truncate,chmod,fchmodat,chown,fchownat,lchown,utimensat", "cargo", ...buildArgs], env: buildEnv }
-        : { cmd: "cargo", args: buildArgs, env: buildEnv };
-      job.label = `${unit.crate} ${unit.version}`;
-      return { unit, scratch, target, straceOut, job };
+      // Built for the unit's own target, as the gate builds it: the host's, or a cross-check target with --target and zig.
+      const cross = unit.target !== inv.host;
+      const buildArgs = ["build", "--profile", "release", "--manifest-path", path.join(probe, "Cargo.toml"), "--target-dir", target, ...(cross ? ["--target", unit.target] : [])];
+      const buildEnv = { ...env, ...(cross ? crossEnv.get(unit.target) : {}), CARGO_TARGET_DIR: target, CARGO_BUILD_JOBS: perBuildJobs };
+      const job = { cmd: "cargo", args: buildArgs, env: buildEnv };
+      job.label = `${unit.crate} ${unit.version}${cross ? ` (${unit.target})` : ""}`;
+      return { unit, scratch, target, job };
     });
     const sessionDir = fs.mkdtempSync(path.join(os.tmpdir(), "rk-bht-session-"));
     const traceFile = path.join(sessionDir, "trace.txt");
-    // One tracer session for the whole run (macOS eslogger, Windows ETW); Linux traces per build through strace.
+    // One tracer session for the whole run (macOS eslogger, Windows ETW).
     let stopTracer = () => {};
     let etl = null;
     if (platform === "darwin") {
       const tracer = run("sh", ["-c", `sudo -n eslogger fork exec create rename unlink link truncate open close clone copyfile exchangedata > '${traceFile}' 2>'${traceFile}.err' & echo $!`], { encoding: "utf8" });
       const tracerPid = String(tracer.stdout ?? "").trim();
       run("sleep", ["2"]);
-      stopTracer = () => { run("sleep", ["1"]); if (tracerPid) { run("sudo", ["-n", "pkill", "-INT", "-P", tracerPid]); run("kill", [tracerPid]); run("sleep", ["1"]); } };
+      // Drain before stopping: eslogger writes a block-buffered file and Endpoint Security delivers late, so the last builds' events were
+      // still in flight when a fixed one-second wait ended (every "build was not observed" fail on the Mac was a build that finished last
+      // in its session). Marker files are created in the session folder, one a second, until the first appears in the recording: every
+      // event before it is then on disk. Two minutes without it leaves the verdicts to judgeTrace, which fails a build it did not see.
+      const drain = () => {
+        const tag = `rk-bht-drain-${process.pid}-`;
+        let from = 0; try { from = fs.statSync(traceFile).size; } catch { /* nothing yet */ }
+        for (let i = 0; i < 120; i += 1) {
+          fs.writeFileSync(path.join(sessionDir, `${tag}${i}`), "");
+          run("sleep", ["1"]);
+          let size = 0; try { size = fs.statSync(traceFile).size; } catch { continue; }
+          if (size <= from) continue;
+          const fd = fs.openSync(traceFile, "r");
+          try {
+            const chunk = Buffer.alloc(8 << 20);
+            for (let at = from; at < size; at += chunk.length - tag.length) {
+              const n = fs.readSync(fd, chunk, 0, chunk.length, at);
+              if (chunk.subarray(0, n).includes(tag)) return true;
+            }
+          } finally { fs.closeSync(fd); }
+          from = Math.max(from, size - tag.length);
+        }
+        err("right-release build-helpers trace: eslogger did not record the drain marker within 2 minutes; builds it did not see are judged unobserved");
+        return false;
+      };
+      stopTracer = () => { drain(); if (tracerPid) { run("sudo", ["-n", "pkill", "-INT", "-P", tracerPid]); run("kill", [tracerPid]); run("sleep", ["1"]); } };
     } else if (platform === "win32") {
       // One ETW session with both kernel providers, each with an explicit level (0x5): a separate process-only session without a level
       // recorded nothing on the Dell (proc.etl 0 MB), so no write could be tied to its build. Tested on the Dell: process starts (with
@@ -219,15 +260,21 @@ function mainWith(argv, { env, platform, run, log, err }) {
       if (exported.status !== 0) { err("right-release build-helpers trace: tracerpt could not export the ETW trace"); return 2; }
       try { recorded = fs.statSync(xml).size > 0; if (recorded) byRoot = etwWritesByRoot(xml, roots, devices); } catch { /* no output */ }
     }
-    if (platform !== "linux" && !recorded && roots.size) { err(`right-release build-helpers trace: the ${platform === "darwin" ? "eslogger" : "ETW"} session recorded nothing; nothing recorded`); return 2; }
+    if (!recorded && roots.size) { err(`right-release build-helpers trace: the ${platform === "darwin" ? "eslogger" : "ETW"} session recorded nothing; nothing recorded`); return 2; }
     prepared.forEach((b, k) => {
       const r = results[k] ?? {};
-      if (r.status !== 0 || !Number.isInteger(r.pid)) { err(`right-release build-helpers trace: ${b.unit.crate} ${b.unit.version} did not build (${r.error ?? `exit ${r.status}`}); not recorded`); return; }
-      let writes;
-      if (platform === "linux") { let text = ""; try { text = readStraceFiles(b.straceOut); } catch { /* none */ } writes = parseStraceWrites(text, { cwd: path.dirname(path.resolve(manifestPath ?? "Cargo.toml")) }); }
-      else writes = byRoot.get(r.pid) ?? [];
+      if (!Number.isInteger(r.status)) { err(`right-release build-helpers trace: ${b.unit.crate} ${b.unit.version} did not finish (${r.error ?? "no result"}); not recorded`); return; }
+      if (r.status !== 0) {
+        // It does not build here for this target, so nothing this host's gate runs builds it either: recorded once, skipped from then on.
+        const reason = String(r.error ?? `exit ${r.status}`);
+        recordTrace(listFile, b.unit, { ok: false, unbuildable: true, outside: [reason] });
+        if (recordRepo) recordTrace(repoFile, b.unit, { ok: false, unbuildable: true, outside: [reason] });
+        log(`skip ${b.unit.crate} ${b.unit.version} (${b.unit.target}): does not build on this host (${reason.slice(0, 160)})`);
+        return;
+      }
+      const writes = byRoot.get(r.pid) ?? [];
       const allowed = platform === "win32" ? [b.scratch, cargoHome, os.tmpdir(), env.LOCALAPPDATA ? path.join(env.LOCALAPPDATA, "Temp") : null]
-        : [b.scratch, cargoHome, os.tmpdir(), "/private/var/folders", "/dev", "/proc/self"];
+        : [b.scratch, cargoHome, os.tmpdir(), "/private/var/folders", "/dev"];
       // Allowed folders by their real path: a linked CARGO_HOME (~/.cargo -> /Volumes/D/...) or temp (/var -> /private/var) is reported by
       // the tracer under the real path, so comparing the link's path would fail every crate.
       const real = (d) => { try { return fs.realpathSync.native(d); } catch { return d; } };

package/cli/right-release.mjs

@@ -181,6 +181,9 @@ if (first === "--version" || first === "-v") {
   // Local qualification (default): both native hosts qualify the crates through the RustRight broker and a candidate is cut.
   // It uploads nothing; the approval commit and publish-reviewed.yml publish the pinned bytes (docs/CI.md "Local qualification").
   run("local-qualify.mjs", args.slice(1));
+} else if (first === "publish-local") {
+  // The local route (rightkit#1471): Class A on the exact pushed commit, then the Keychain token publishes that commit's bytes.
+  run("publish-local-npm.mjs", args.slice(1));
 } else if (first === "publish") {
   const rest = args.slice(1);
   // RightKit crates and @rightkit packages reach a registry from CI only: publish.yml qualification, the approval
@@ -352,6 +355,9 @@ Commands:
   release                                             Compatibility alias for build
   publish                                             Compatibility alias for upload
   check-release-dependencies [--platform mac|win|linux | --all-targets]  Check app-forbidden release crates
+  publish-local npm --package @rightkit/<name> --commit <sha>
+                                                      Mac: Class A on the pushed commit, pack it, publish with the
+                                                      Keychain token (npm-rightkit-publish), verify the registry shasum
   publish npm --package @rightkit/<name> [--dry-run]  Gate preflight for npm publish
   publish npm --package @rightkit/<name> --publish --tarball <gated.tgz>
                                                       Publish the gated tarball with the Keychain token

package/deterministic-scans.mjs

@@ -1071,7 +1071,9 @@ export function planScans({
   const wsOf = (n) => (rustMap ? rustMap.get(n).cargoDir : cargoWs);
   const crateOf = (n) => (rustMap?.get(n)?.crate ?? n);
   const featuresOf = (n) => crateFeatures?.[n] ?? crateFeatures?.[crateOf(n)] ?? {};
-  const workspaces = rustMap && rustMap.size ? [...new Set([...rustMap.values()].map((u) => u.cargoDir))].sort() : [cargoWs];
+  // With no Rust unit in play the default workspace counts only when it has a Cargo.toml: a root rust-toolchain.toml (or other Rust config)
+  // in a crate-per-workspace repository must not turn the repository root into a phantom workspace whose cargo scans have no manifest.
+  const workspaces = rustMap && rustMap.size ? [...new Set([...rustMap.values()].map((u) => u.cargoDir))].sort() : (exists(path.join(contentRoot, cargoWs === "." ? "Cargo.toml" : `${cargoWs}/Cargo.toml`)) ? [cargoWs] : []);
   const lockOf = (ws) => (rustLocks?.[ws] instanceof Map ? rustLocks[ws] : ws === cargoWs && rustLock instanceof Map ? rustLock : null);
   const rustDir = (n) => (rustMap ? rustMap.get(n).dir : `crates/${n}`);
   const npmDir = (n) => (npmMap ? npmMap.get(n).dir : `packages/${n}`);
@@ -1251,7 +1253,8 @@ export function planScans({
     // inside its build directories; an untraced or out-of-bounds unit refuses Class A, naming it. Runs the gate's own command, directly (GC-A11).
     // It runs in its workspace (cwd), so a unit's scope keeps it only for the Cargo workspaces of its own closure (app-closure CARGO_WORKSPACE_SCAN),
     // like metadata, deny and audit: an npm-only unit traces nothing.
-    for (const ws of touchedWs) add({ id: `build-helpers${wsIdSuffix(ws)}`, class: A, tool: "node", args: [BUILD_HELPERS_COMMAND, "check", "--manifest-path", "Cargo.toml", ...(platform === "linux" ? ["--trace-missing"] : [])], ...(ws !== "." ? { cwd: ws } : {}), root: "content" });
+    // Build helpers are vetted only on broker hosts (Mac, Dell); a Linux host or CI runner is a throwaway container (Adrian, 2026-11-03).
+    if (platform === "darwin" || platform === "win32") for (const ws of touchedWs) add({ id: `build-helpers${wsIdSuffix(ws)}`, class: A, tool: "node", args: [BUILD_HELPERS_COMMAND, "check", "--manifest-path", "Cargo.toml"], ...(ws !== "." ? { cwd: ws } : {}), root: "content" });
     // Locked package listings are observations in RustRight (#1216). They run through the selected executor
     // from the checked Cargo inputs, just like metadata; an executor refusal remains a failed scan.
     for (const name of crateNames.filter((n) => rustMap?.get(n).publish !== false)) add({ id: rustScanId.packageList(name), class: A, ...cargoReadIn(wsOf(name), "package", "-p", crateOf(name), "--list", "--allow-dirty", "--locked") });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/release",
-  "version": "0.6.27",
+  "version": "0.6.29",
   "description": "Portable release CLI/SDK with fail-closed public GitHub Releases and private R2 + RightApps distribution.",
   "license": "MIT OR Apache-2.0",
   "type": "module",

package/pipeline-receipts.mjs

@@ -1,302 +1,302 @@
-// Pipeline stage receipts and their verifier (architecture-v3 sections 4-5, "Receipts").
-//
-// A receipt records a fact about one stage of one request. It never authorizes execution alone: the
-// broker (RustRight) signs receipts and issues short-lived capabilities; this module only checks that
-// a chain of receipts is well formed, linked, fresh and complete. Signature checking is an injected
-// interface (`verifySignature`); this module does no cryptography beyond SHA-256 hashing and invents none.
-//
-// Chain: ADMISSION -> SCAN_A -> ROUTE -> SCAN_B -> BUILD -> SIGN -> QUALIFIED -> PUBLISH_INTENT -> PUBLISHED.
-// Each stage requires exactly its predecessor; `parents` carries that predecessor's receipt hash.
-import crypto from "node:crypto";
-import { canonicalJson, digestScanSet, scanClassOf } from "./deterministic-scans.mjs";
-
-export const RECEIPT_SCHEMA = "rightkit.pipeline-receipt/1";
-export const STAGES = Object.freeze(["ADMISSION", "SCAN_A", "ROUTE", "SCAN_B", "BUILD", "SIGN", "QUALIFIED", "PUBLISH_INTENT", "PUBLISHED"]);
-export const OPERATIONS = Object.freeze(["dev", "build", "qualify", "sign", "publish"]);
-/** The last stage each operation may reach. */
-export const OPERATION_LAST_STAGE = Object.freeze({ dev: "BUILD", build: "BUILD", sign: "SIGN", qualify: "QUALIFIED", publish: "PUBLISHED" });
-/** Each stage requires only these predecessors. */
-export const PREREQUISITES = Object.freeze({
-  ADMISSION: [], SCAN_A: ["ADMISSION"], ROUTE: ["SCAN_A"], SCAN_B: ["ROUTE"], BUILD: ["SCAN_B"],
-  SIGN: ["BUILD"], QUALIFIED: ["SIGN"], PUBLISH_INTENT: ["QUALIFIED"], PUBLISHED: ["PUBLISH_INTENT"],
-});
-const RELEASE_ID_STAGES = new Set(["SIGN", "QUALIFIED", "PUBLISH_INTENT", "PUBLISHED"]);
-/** Stages only a publishable request may reach: signing and everything after it. A dev or non-publishable chain stops at BUILD. */
-const PUBLISHABLE_ONLY_STAGES = new Set(RELEASE_ID_STAGES);
-
-/**
- * What ADMISSION's evidence allows for `stage`, as [{ code, message }]. ADMISSION is the sole authority:
- * a missing or malformed ADMISSION authorizes nothing, and `publishable` must be exactly true to reach SIGN or later.
- */
-function admissionProblems(admission, stage) {
-  const out = [];
-  if (!admission) return [{ code: "STAGE_NOT_AUTHORIZED", message: `no valid ADMISSION evidence authorizes ${stage}` }];
-  if (!Array.isArray(admission.authorizedStages) || !admission.authorizedStages.includes(stage)) out.push({ code: "STAGE_NOT_AUTHORIZED", message: `ADMISSION does not authorize ${stage}` });
-  if (admission.publishable !== true && PUBLISHABLE_ONLY_STAGES.has(stage)) out.push({ code: "NOT_PUBLISHABLE", message: `ADMISSION does not mark this request publishable:true; it cannot reach ${stage}` });
-  return out;
-}
-
-const ENVELOPE_STRINGS = ["receiptId", "jobId", "requestId", "repositoryId", "commit", "inputDigest", "configDigest", "policyDigest", "stagePlanDigest", "runtimeDigest", "executor", "issuedAt", "expiresAt", "keyId", "signature"];
-const HEX64 = /^[0-9a-f]{64}$/;
-const sha256 = (value) => crypto.createHash("sha256").update(value).digest("hex");
-
-/** Domain-separated bytes a signature covers: receipt type bound in, signature field excluded. */
-export function signingBytes(receipt) {
-  const { signature, ...rest } = receipt;
-  return Buffer.from(`${RECEIPT_SCHEMA}\0${receipt.type}\0${canonicalJson(rest)}`, "utf8");
-}
-
-/** The hash a child receipt records in `parents`: covers the whole receipt including its signature. */
-export function receiptHash(receipt) {
-  return sha256(Buffer.concat([Buffer.from(`${RECEIPT_SCHEMA}.hash\0`, "utf8"), Buffer.from(canonicalJson(receipt), "utf8")]));
-}
-
-/** In-memory request ledger for tests and single-process brokers: records which job owns a requestId. */
-export function createMemoryLedger() {
-  const owners = new Map(); const consumed = new Set();
-  return {
-    requestOwner: (requestId) => owners.get(requestId),
-    isConsumed: (receiptId) => consumed.has(receiptId),
-    record(chain) { for (const r of chain) { if (!owners.has(r.requestId)) owners.set(r.requestId, r.jobId); consumed.add(r.receiptId); } },
-  };
-}
-
-const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
-const nonEmptyString = (v) => typeof v === "string" && v.trim() !== "";
-const isHex = (v) => typeof v === "string" && HEX64.test(v);
-const nonEmptyArray = (v) => Array.isArray(v) && v.length > 0;
-
-/** Stage-specific evidence checks. Each returns a list of problem messages. */
-const STAGE_EVIDENCE = {
-  ADMISSION(e) {
-    const p = [];
-    for (const f of ["inputManifestDigest", "dependencyManifestDigest", "toolchainManifestDigest"]) if (!isHex(e[f])) p.push(`${f} must be a sha256 hex digest`);
-    if (!nonEmptyArray(e.authorizedStages) || e.authorizedStages.some((s) => !STAGES.includes(s))) p.push("authorizedStages must list known stages");
-    if (typeof e.publishable !== "boolean") p.push("publishable must be a boolean");
-    return p;
-  },
-  SCAN_A: (e, ctx) => scanEvidence(e, "A", ctx),
-  ROUTE(e, ctx) {
-    const p = [];
-    const d = e.decision;
-    if (!isObj(d)) return ["decision is required"];
-    if (!["local", "ci"].includes(d.executor)) p.push("decision.executor must be local or ci");
-    if (!["public", "private"].includes(d.visibility)) p.push("decision.visibility must be public or private (unknown visibility is rejected)");
-    if (d.visibility === "private" && d.executor !== "local") p.push("a private repository never routes to CI");
-    if (typeof d.localGrant !== "boolean") p.push("decision.localGrant must be a boolean");
-    if (d.executor === "local" && !nonEmptyString(String(e.leaseFence ?? ""))) p.push("a local route needs a leaseFence");
-    if (d.executor === "ci" && !isObj(e.dispatchBinding)) p.push("a CI route needs a dispatchBinding");
-    if (!nonEmptyString(d.policyVersion)) p.push("decision.policyVersion is required");
-    return p;
-  },
-  SCAN_B: (e, ctx) => scanEvidence(e, "B", ctx),
-  BUILD(e) {
-    const p = [];
-    if (!isHex(e.artifactManifestDigest)) p.push("artifactManifestDigest must be a sha256 hex digest");
-    if (!nonEmptyArray(e.artifacts) || e.artifacts.some((a) => !nonEmptyString(a?.path) || !isHex(a?.sha256))) p.push("artifacts must list path and sha256 for every output");
-    for (const f of ["generationEvidenceDigest", "provenanceDigest"]) if (!isHex(e[f])) p.push(`${f} must be a sha256 hex digest`);
-    if (!nonEmptyArray(e.targetMatrix)) p.push("targetMatrix must list the built targets");
-    return p;
-  },
-  SIGN(e, ctx) {
-    const p = [];
-    if (!["SIGN", "SEAL"].includes(e.mode)) p.push("mode must be SIGN or SEAL");
-    for (const f of ["inputManifestDigest", "outputManifestDigest", "signingEvidenceDigest"]) if (!isHex(e[f])) p.push(`${f} must be a sha256 hex digest`);
-    if (!nonEmptyString(e.signingProfile)) p.push("signingProfile is required");
-    const build = ctx.byStage.BUILD;
-    if (build && e.inputManifestDigest !== build.evidence?.artifactManifestDigest) p.push("inputManifestDigest does not equal the BUILD artifactManifestDigest");
-    return p;
-  },
-  QUALIFIED(e, ctx) {
-    const p = [];
-    if (!isHex(e.artifactManifestDigest)) p.push("artifactManifestDigest must be a sha256 hex digest");
-    if (!nonEmptyArray(e.testMatrix) || e.testMatrix.some((t) => !nonEmptyString(t?.name) || t?.status !== "pass")) p.push("testMatrix must be non-empty and every row must pass");
-    const sign = ctx.byStage.SIGN;
-    if (sign && e.artifactManifestDigest !== sign.evidence?.outputManifestDigest) p.push("artifactManifestDigest does not equal the SIGN outputManifestDigest (qualification covers the final signed bytes)");
-    return p;
-  },
-  PUBLISH_INTENT(e, ctx) {
-    const p = [];
-    if (!isHex(e.releaseManifestDigest)) p.push("releaseManifestDigest must be a sha256 hex digest");
-    if (!nonEmptyArray(e.destinations) || e.destinations.some((d) => !nonEmptyString(d?.id) || !nonEmptyString(d?.identity) || !nonEmptyString(d?.version) || !isHex(d?.expectedDigest) || !nonEmptyString(d?.idempotencyKey))) {
-      p.push("destinations must name id, identity, version, expectedDigest and idempotencyKey");
-    }
-    const q = ctx.byStage.QUALIFIED;
-    if (q && e.releaseManifestDigest !== q.evidence?.artifactManifestDigest) p.push("releaseManifestDigest does not equal the QUALIFIED artifactManifestDigest");
-    return p;
-  },
-  PUBLISHED(e, ctx) {
-    const p = [];
-    const intent = ctx.byStage.PUBLISH_INTENT;
-    if (!nonEmptyArray(e.entries)) return ["entries must list every destination outcome"];
-    for (const d of intent?.evidence?.destinations ?? []) {
-      const entry = e.entries.find((x) => x?.destinationId === d.id);
-      if (!entry) p.push(`no entry for destination ${d.id}`);
-      else if (entry.outcome !== "verified") p.push(`destination ${d.id} is ${entry.outcome}, not verified`);
-      else if (entry.remoteDigest !== d.expectedDigest) p.push(`destination ${d.id} readback digest differs from the intent`);
-    }
-    return p;
-  },
-};
-
-function scanEvidence(e, cls, ctx) {
-  const p = [];
-  const other = cls === "A" ? "B" : "A";
-  if (e.scanClass !== cls) p.push(`scanClass must be ${cls}`);
-  if (!nonEmptyArray(e.scans)) return [...p, "scans must list every required scan result"];
-  if (cls === "A" && !isHex(e.advisorySnapshotDigest)) p.push("advisorySnapshotDigest must be a sha256 hex digest");
-  if (cls === "A" && !nonEmptyString(e.advisorySnapshotTime)) p.push("advisorySnapshotTime is required");
-  for (const s of e.scans) {
-    const derived = scanClassOf(s?.id);
-    if (s?.class === other || derived === other) p.push(`${cls === "A" ? "SCAN_A claims" : "SCAN_B carries"} class ${other} scan ${s?.id}`);
-    else if (s?.class !== cls) p.push(`scan ${s?.id} has class ${s?.class}, expected ${cls}`);
-    if (s?.status !== "pass") p.push(`scan ${s?.id} is ${s?.status}, not pass`);
-  }
-  const ids = new Set(e.scans.map((s) => s?.id));
-  const required = ctx.requiredScans?.[cls];
-  const declared = Array.isArray(e.requiredScanIds) ? e.requiredScanIds : null;
-  if (!declared) p.push("requiredScanIds is required");
-  // The required set comes only from the injected policy matrix. A receipt's own declaration is never trusted:
-  // without the policy, verification fails closed.
-  if (!Array.isArray(required) || required.some((id) => typeof id !== "string")) {
-    p.push(`trusted required scan set for class ${cls} is not supplied by policy; verification fails closed`);
-    return p;
-  }
-  for (const id of required) if (!ids.has(id)) p.push(`required class ${cls} scan ${id} is missing`);
-  if (declared && canonicalJson([...required].sort()) !== canonicalJson([...declared].sort())) p.push(`requiredScanIds differ from the trusted class ${cls} set`);
-  if (e.scanSetDigest !== digestScanSet(e.scans)) p.push("scanSetDigest does not match the listed scans");
-  if (cls === "B" && !nonEmptyArray(required)) p.push("SCAN_B must require at least one class B scan");
-  return p;
-}
-
-/**
- * Verify a chain of receipts (ADMISSION first, ending at the stage being authorized).
- *
- * options:
- *   verifySignature({ receipt, keyId, signingBytes, signature }) -> boolean   REQUIRED (the broker supplies keys)
- *   now                 ISO string or Date, default current time
- *   expected            { requestId, operation, inputDigest, stage, repositoryId, commit, jobId, releaseId, targetSet } (each optional but checked when given)
- *   requiredScans       { A: [ids], B: [ids] } trusted required sets from the policy matrix: REQUIRED; absence rejects (NO_SCAN_POLICY)
- *   ledger              { requestOwner(requestId), isConsumed(receiptId) }   REQUIRED: without it verification fails (NO_LEDGER)
- *   keyAllowed          (keyId, receipt) -> boolean, for revocations
- * Returns { ok, problems: [{ code, stage, message }], head }. Never throws on a bad receipt.
- */
-export function verifyReceiptChain(chain, options = {}) {
-  const problems = [];
-  const bad = (code, stage, message) => problems.push({ code, stage: stage ?? null, message });
-  if (typeof options.verifySignature !== "function") return { ok: false, problems: [{ code: "NO_SIGNATURE_VERIFIER", stage: null, message: "a signature verifier must be supplied by the broker" }], head: null };
-  if (!Array.isArray(chain) || chain.length === 0) return { ok: false, problems: [{ code: "EMPTY_CHAIN", stage: null, message: "no receipts" }], head: null };
-  const now = new Date(options.now ?? Date.now()).getTime();
-  const expected = options.expected ?? {};
-  const byStage = {};
-  let previous = null;
-  // Replay protection is mandatory: without a ledger the chain cannot be proven fresh, so it fails closed.
-  if (typeof options.ledger?.requestOwner !== "function" || typeof options.ledger?.isConsumed !== "function") {
-    bad("NO_LEDGER", null, "a request ledger with requestOwner and isConsumed must be supplied; replay cannot be ruled out without it");
-  }
-  // One release id for the whole chain: the ADMISSION one when it has it, else the first release-stage one.
-  const releaseRef = chain.find((r) => isObj(r) && nonEmptyString(r.releaseId))?.releaseId;
-  // ADMISSION fixes which stages may run and whether the request may publish at all.
-  const admission = isObj(chain[0]) && chain[0].type === "ADMISSION" && isObj(chain[0].evidence) ? chain[0].evidence : null;
-
-  chain.forEach((receipt, index) => {
-    const stage = isObj(receipt) ? receipt.type : null;
-    if (!isObj(receipt)) { bad("MALFORMED", null, `receipt ${index} is not an object`); return; }
-    if (receipt.schema !== RECEIPT_SCHEMA) bad("SCHEMA", stage, `schema must be ${RECEIPT_SCHEMA}`);
-    if (!STAGES.includes(stage)) { bad("UNKNOWN_STAGE", stage, `unknown receipt type ${JSON.stringify(stage)}`); return; }
-    const wantStage = STAGES[index];
-    if (stage !== wantStage) bad("WRONG_STAGE", stage, `position ${index} requires ${wantStage}, got ${stage}`);
-    for (const f of ENVELOPE_STRINGS) if (!nonEmptyString(receipt[f])) bad("ENVELOPE", stage, `${f} is required`);
-    if (!Number.isInteger(receipt.attempt) || receipt.attempt < 1) bad("ENVELOPE", stage, "attempt must be an integer >= 1");
-    if (!Array.isArray(receipt.targetSet)) bad("ENVELOPE", stage, "targetSet must be an array");
-    if (!OPERATIONS.includes(receipt.operation)) bad("WRONG_OPERATION", stage, `unknown operation ${JSON.stringify(receipt.operation)}`);
-    if (RELEASE_ID_STAGES.has(stage) && !nonEmptyString(receipt.releaseId)) bad("ENVELOPE", stage, "releaseId is required");
-    if (!isObj(receipt.evidence)) bad("EVIDENCE", stage, "evidence is required");
-
-    // The operation bounds how far a request may go.
-    const last = OPERATION_LAST_STAGE[receipt.operation];
-    if (last && STAGES.indexOf(stage) > STAGES.indexOf(last)) bad("WRONG_OPERATION", stage, `operation ${receipt.operation} does not authorize ${stage}`);
-
-    // ADMISSION bounds the chain: only its authorized stages, and nothing from SIGN on unless publishable:true.
-    for (const x of admissionProblems(admission, stage)) bad(x.code, stage, x.message);
-
-    // Binding to the caller's expectations.
-    if (expected.requestId !== undefined && receipt.requestId !== expected.requestId) bad("WRONG_REQUEST_ID", stage, "requestId differs from the expected request");
-    if (expected.operation !== undefined && receipt.operation !== expected.operation) bad("WRONG_OPERATION", stage, `operation ${receipt.operation} differs from expected ${expected.operation}`);
-    if (expected.inputDigest !== undefined && receipt.inputDigest !== expected.inputDigest) bad("WRONG_INPUT_DIGEST", stage, "inputDigest differs from the expected input");
-    for (const f of ["repositoryId", "commit", "jobId", "releaseId"]) if (expected[f] !== undefined && receipt[f] !== expected[f]) bad("BINDING", stage, `${f} differs from the expected value`);
-    if (expected.targetSet !== undefined && canonicalJson(receipt.targetSet ?? null) !== canonicalJson(expected.targetSet)) bad("BINDING", stage, "targetSet differs from the expected value");
-    if (releaseRef !== undefined && receipt.releaseId !== undefined && receipt.releaseId !== releaseRef) bad("BINDING", stage, "releaseId differs from the chain's release");
-
-    // Consistency across the chain.
-    const first = chain[0];
-    if (index > 0 && isObj(first)) {
-      for (const f of ["requestId", "jobId", "repositoryId", "commit", "inputDigest", "configDigest", "policyDigest", "stagePlanDigest", "operation", "targetSet"]) {
-        if (f === "targetSet" ? canonicalJson(receipt[f] ?? null) !== canonicalJson(first[f] ?? null) : receipt[f] !== first[f]) bad(f === "requestId" ? "WRONG_REQUEST_ID" : f === "inputDigest" ? "WRONG_INPUT_DIGEST" : f === "operation" ? "WRONG_OPERATION" : "BINDING", stage, `${f} differs from the ADMISSION receipt`);
-      }
-    }
-
-    // Freshness.
-    const issued = Date.parse(receipt.issuedAt); const expires = Date.parse(receipt.expiresAt);
-    if (Number.isNaN(issued) || Number.isNaN(expires)) bad("ENVELOPE", stage, "issuedAt and expiresAt must be ISO timestamps");
-    else {
-      if (expires <= issued) bad("ENVELOPE", stage, "expiresAt must be after issuedAt");
-      if (expires <= now) bad("EXPIRED", stage, `expired at ${receipt.expiresAt}`);
-      if (issued > now + 60_000) bad("ENVELOPE", stage, "issuedAt is in the future");
-      if (previous && issued < Date.parse(previous.issuedAt)) bad("ORDER", stage, "issued before its parent receipt");
-    }
-
-    // Hash chain.
-    const wantParents = previous ? [receiptHash(previous)] : [];
-    if (!Array.isArray(receipt.parents) || canonicalJson(receipt.parents) !== canonicalJson(wantParents)) bad("BROKEN_CHAIN", stage, previous ? `parents must be exactly [hash of ${previous.type}]` : "ADMISSION has no parents");
-
-    // Replay (the ledger is required; see NO_LEDGER above).
-    if (typeof options.ledger?.requestOwner === "function" && typeof options.ledger?.isConsumed === "function") {
-      const owner = options.ledger.requestOwner(receipt.requestId);
-      if (owner !== undefined && owner !== receipt.jobId) bad("REPLAYED_REQUEST_ID", stage, "requestId already belongs to another job");
-      if (options.ledger.isConsumed(receipt.receiptId)) bad("REPLAYED_RECEIPT", stage, "receipt already consumed");
-    }
-
-    // Signature (injected).
-    if (options.keyAllowed && !options.keyAllowed(receipt.keyId, receipt)) bad("KEY_REVOKED", stage, `key ${receipt.keyId} is not allowed for this receipt`);
-    let signatureOk = false;
-    try { signatureOk = options.verifySignature({ receipt, keyId: receipt.keyId, signingBytes: signingBytes(receipt), signature: receipt.signature }) === true; } catch { signatureOk = false; }
-    if (!signatureOk) bad("BAD_SIGNATURE", stage, "signature did not verify");
-
-    byStage[stage] = receipt;
-    // Stage evidence last: it can look at the earlier stages collected so far.
-    if (isObj(receipt.evidence) && STAGE_EVIDENCE[stage]) {
-      for (const message of STAGE_EVIDENCE[stage](receipt.evidence, { byStage, requiredScans: options.requiredScans })) {
-        const code = /trusted required scan set/.test(message) ? "NO_SCAN_POLICY" : /missing|claims|carries/.test(message) && (stage === "SCAN_A" || stage === "SCAN_B") ? (/claims|carries/.test(message) ? "SCAN_CLASS_MIX" : "SCAN_INCOMPLETE") : "EVIDENCE";
-        bad(code, stage, message);
-      }
-    }
-    previous = receipt;
-  });
-
-  const head = chain[chain.length - 1];
-  if (expected.stage !== undefined) {
-    if (!STAGES.includes(expected.stage)) bad("WRONG_STAGE", null, `unknown expected stage ${expected.stage}`);
-    else if (head?.type !== expected.stage) bad("WRONG_STAGE", head?.type, `chain ends at ${head?.type}, expected ${expected.stage}`);
-  }
-  return { ok: problems.length === 0, problems, head: isObj(head) ? { type: head.type, hash: receiptHash(head) } : null };
-}
-
-/**
- * Verify that a new stage may start: the chain so far must verify and end at the stage `stage` requires.
- * Returns the same result shape; `authorizes` is the stage the chain authorizes next (or null).
- */
-export function authorizeNextStage(chain, stage, options = {}) {
-  const need = PREREQUISITES[stage];
-  if (!need) return { ok: false, problems: [{ code: "UNKNOWN_STAGE", stage, message: `unknown stage ${stage}` }], head: null, authorizes: null };
-  if (need.length === 0) return { ok: !chain?.length, problems: chain?.length ? [{ code: "WRONG_STAGE", stage, message: "ADMISSION starts a chain" }] : [], head: null, authorizes: chain?.length ? null : stage };
-  const result = verifyReceiptChain(chain, { ...options, expected: { ...(options.expected ?? {}), stage: need[0] } });
-  // The requested stage itself must sit inside the operation's boundary and ADMISSION's authorized stages.
-  const first = Array.isArray(chain) ? chain[0] : null;
-  const last = OPERATION_LAST_STAGE[first?.operation];
-  if (!last || STAGES.indexOf(stage) > STAGES.indexOf(last)) result.problems.push({ code: "WRONG_OPERATION", stage, message: `operation ${first?.operation} does not authorize ${stage}` });
-  const admission = first?.type === "ADMISSION" && isObj(first.evidence) ? first.evidence : null;
-  for (const x of admissionProblems(admission, stage)) result.problems.push({ code: x.code, stage, message: x.message });
-  result.ok = result.problems.length === 0;
-  return { ...result, authorizes: result.ok ? stage : null };
-}
+// Pipeline stage receipts and their verifier (architecture-v3 sections 4-5, "Receipts").
+//
+// A receipt records a fact about one stage of one request. It never authorizes execution alone: the
+// broker (RustRight) signs receipts and issues short-lived capabilities; this module only checks that
+// a chain of receipts is well formed, linked, fresh and complete. Signature checking is an injected
+// interface (`verifySignature`); this module does no cryptography beyond SHA-256 hashing and invents none.
+//
+// Chain: ADMISSION -> SCAN_A -> ROUTE -> SCAN_B -> BUILD -> SIGN -> QUALIFIED -> PUBLISH_INTENT -> PUBLISHED.
+// Each stage requires exactly its predecessor; `parents` carries that predecessor's receipt hash.
+import crypto from "node:crypto";
+import { canonicalJson, digestScanSet, scanClassOf } from "./deterministic-scans.mjs";
+
+export const RECEIPT_SCHEMA = "rightkit.pipeline-receipt/1";
+export const STAGES = Object.freeze(["ADMISSION", "SCAN_A", "ROUTE", "SCAN_B", "BUILD", "SIGN", "QUALIFIED", "PUBLISH_INTENT", "PUBLISHED"]);
+export const OPERATIONS = Object.freeze(["dev", "build", "qualify", "sign", "publish"]);
+/** The last stage each operation may reach. */
+export const OPERATION_LAST_STAGE = Object.freeze({ dev: "BUILD", build: "BUILD", sign: "SIGN", qualify: "QUALIFIED", publish: "PUBLISHED" });
+/** Each stage requires only these predecessors. */
+export const PREREQUISITES = Object.freeze({
+  ADMISSION: [], SCAN_A: ["ADMISSION"], ROUTE: ["SCAN_A"], SCAN_B: ["ROUTE"], BUILD: ["SCAN_B"],
+  SIGN: ["BUILD"], QUALIFIED: ["SIGN"], PUBLISH_INTENT: ["QUALIFIED"], PUBLISHED: ["PUBLISH_INTENT"],
+});
+const RELEASE_ID_STAGES = new Set(["SIGN", "QUALIFIED", "PUBLISH_INTENT", "PUBLISHED"]);
+/** Stages only a publishable request may reach: signing and everything after it. A dev or non-publishable chain stops at BUILD. */
+const PUBLISHABLE_ONLY_STAGES = new Set(RELEASE_ID_STAGES);
+
+/**
+ * What ADMISSION's evidence allows for `stage`, as [{ code, message }]. ADMISSION is the sole authority:
+ * a missing or malformed ADMISSION authorizes nothing, and `publishable` must be exactly true to reach SIGN or later.
+ */
+function admissionProblems(admission, stage) {
+  const out = [];
+  if (!admission) return [{ code: "STAGE_NOT_AUTHORIZED", message: `no valid ADMISSION evidence authorizes ${stage}` }];
+  if (!Array.isArray(admission.authorizedStages) || !admission.authorizedStages.includes(stage)) out.push({ code: "STAGE_NOT_AUTHORIZED", message: `ADMISSION does not authorize ${stage}` });
+  if (admission.publishable !== true && PUBLISHABLE_ONLY_STAGES.has(stage)) out.push({ code: "NOT_PUBLISHABLE", message: `ADMISSION does not mark this request publishable:true; it cannot reach ${stage}` });
+  return out;
+}
+
+const ENVELOPE_STRINGS = ["receiptId", "jobId", "requestId", "repositoryId", "commit", "inputDigest", "configDigest", "policyDigest", "stagePlanDigest", "runtimeDigest", "executor", "issuedAt", "expiresAt", "keyId", "signature"];
+const HEX64 = /^[0-9a-f]{64}$/;
+const sha256 = (value) => crypto.createHash("sha256").update(value).digest("hex");
+
+/** Domain-separated bytes a signature covers: receipt type bound in, signature field excluded. */
+export function signingBytes(receipt) {
+  const { signature, ...rest } = receipt;
+  return Buffer.from(`${RECEIPT_SCHEMA}\0${receipt.type}\0${canonicalJson(rest)}`, "utf8");
+}
+
+/** The hash a child receipt records in `parents`: covers the whole receipt including its signature. */
+export function receiptHash(receipt) {
+  return sha256(Buffer.concat([Buffer.from(`${RECEIPT_SCHEMA}.hash\0`, "utf8"), Buffer.from(canonicalJson(receipt), "utf8")]));
+}
+
+/** In-memory request ledger for tests and single-process brokers: records which job owns a requestId. */
+export function createMemoryLedger() {
+  const owners = new Map(); const consumed = new Set();
+  return {
+    requestOwner: (requestId) => owners.get(requestId),
+    isConsumed: (receiptId) => consumed.has(receiptId),
+    record(chain) { for (const r of chain) { if (!owners.has(r.requestId)) owners.set(r.requestId, r.jobId); consumed.add(r.receiptId); } },
+  };
+}
+
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const nonEmptyString = (v) => typeof v === "string" && v.trim() !== "";
+const isHex = (v) => typeof v === "string" && HEX64.test(v);
+const nonEmptyArray = (v) => Array.isArray(v) && v.length > 0;
+
+/** Stage-specific evidence checks. Each returns a list of problem messages. */
+const STAGE_EVIDENCE = {
+  ADMISSION(e) {
+    const p = [];
+    for (const f of ["inputManifestDigest", "dependencyManifestDigest", "toolchainManifestDigest"]) if (!isHex(e[f])) p.push(`${f} must be a sha256 hex digest`);
+    if (!nonEmptyArray(e.authorizedStages) || e.authorizedStages.some((s) => !STAGES.includes(s))) p.push("authorizedStages must list known stages");
+    if (typeof e.publishable !== "boolean") p.push("publishable must be a boolean");
+    return p;
+  },
+  SCAN_A: (e, ctx) => scanEvidence(e, "A", ctx),
+  ROUTE(e, ctx) {
+    const p = [];
+    const d = e.decision;
+    if (!isObj(d)) return ["decision is required"];
+    if (!["local", "ci"].includes(d.executor)) p.push("decision.executor must be local or ci");
+    if (!["public", "private"].includes(d.visibility)) p.push("decision.visibility must be public or private (unknown visibility is rejected)");
+    if (d.visibility === "private" && d.executor !== "local") p.push("a private repository never routes to CI");
+    if (typeof d.localGrant !== "boolean") p.push("decision.localGrant must be a boolean");
+    if (d.executor === "local" && !nonEmptyString(String(e.leaseFence ?? ""))) p.push("a local route needs a leaseFence");
+    if (d.executor === "ci" && !isObj(e.dispatchBinding)) p.push("a CI route needs a dispatchBinding");
+    if (!nonEmptyString(d.policyVersion)) p.push("decision.policyVersion is required");
+    return p;
+  },
+  SCAN_B: (e, ctx) => scanEvidence(e, "B", ctx),
+  BUILD(e) {
+    const p = [];
+    if (!isHex(e.artifactManifestDigest)) p.push("artifactManifestDigest must be a sha256 hex digest");
+    if (!nonEmptyArray(e.artifacts) || e.artifacts.some((a) => !nonEmptyString(a?.path) || !isHex(a?.sha256))) p.push("artifacts must list path and sha256 for every output");
+    for (const f of ["generationEvidenceDigest", "provenanceDigest"]) if (!isHex(e[f])) p.push(`${f} must be a sha256 hex digest`);
+    if (!nonEmptyArray(e.targetMatrix)) p.push("targetMatrix must list the built targets");
+    return p;
+  },
+  SIGN(e, ctx) {
+    const p = [];
+    if (!["SIGN", "SEAL"].includes(e.mode)) p.push("mode must be SIGN or SEAL");
+    for (const f of ["inputManifestDigest", "outputManifestDigest", "signingEvidenceDigest"]) if (!isHex(e[f])) p.push(`${f} must be a sha256 hex digest`);
+    if (!nonEmptyString(e.signingProfile)) p.push("signingProfile is required");
+    const build = ctx.byStage.BUILD;
+    if (build && e.inputManifestDigest !== build.evidence?.artifactManifestDigest) p.push("inputManifestDigest does not equal the BUILD artifactManifestDigest");
+    return p;
+  },
+  QUALIFIED(e, ctx) {
+    const p = [];
+    if (!isHex(e.artifactManifestDigest)) p.push("artifactManifestDigest must be a sha256 hex digest");
+    if (!nonEmptyArray(e.testMatrix) || e.testMatrix.some((t) => !nonEmptyString(t?.name) || t?.status !== "pass")) p.push("testMatrix must be non-empty and every row must pass");
+    const sign = ctx.byStage.SIGN;
+    if (sign && e.artifactManifestDigest !== sign.evidence?.outputManifestDigest) p.push("artifactManifestDigest does not equal the SIGN outputManifestDigest (qualification covers the final signed bytes)");
+    return p;
+  },
+  PUBLISH_INTENT(e, ctx) {
+    const p = [];
+    if (!isHex(e.releaseManifestDigest)) p.push("releaseManifestDigest must be a sha256 hex digest");
+    if (!nonEmptyArray(e.destinations) || e.destinations.some((d) => !nonEmptyString(d?.id) || !nonEmptyString(d?.identity) || !nonEmptyString(d?.version) || !isHex(d?.expectedDigest) || !nonEmptyString(d?.idempotencyKey))) {
+      p.push("destinations must name id, identity, version, expectedDigest and idempotencyKey");
+    }
+    const q = ctx.byStage.QUALIFIED;
+    if (q && e.releaseManifestDigest !== q.evidence?.artifactManifestDigest) p.push("releaseManifestDigest does not equal the QUALIFIED artifactManifestDigest");
+    return p;
+  },
+  PUBLISHED(e, ctx) {
+    const p = [];
+    const intent = ctx.byStage.PUBLISH_INTENT;
+    if (!nonEmptyArray(e.entries)) return ["entries must list every destination outcome"];
+    for (const d of intent?.evidence?.destinations ?? []) {
+      const entry = e.entries.find((x) => x?.destinationId === d.id);
+      if (!entry) p.push(`no entry for destination ${d.id}`);
+      else if (entry.outcome !== "verified") p.push(`destination ${d.id} is ${entry.outcome}, not verified`);
+      else if (entry.remoteDigest !== d.expectedDigest) p.push(`destination ${d.id} readback digest differs from the intent`);
+    }
+    return p;
+  },
+};
+
+function scanEvidence(e, cls, ctx) {
+  const p = [];
+  const other = cls === "A" ? "B" : "A";
+  if (e.scanClass !== cls) p.push(`scanClass must be ${cls}`);
+  if (!nonEmptyArray(e.scans)) return [...p, "scans must list every required scan result"];
+  if (cls === "A" && !isHex(e.advisorySnapshotDigest)) p.push("advisorySnapshotDigest must be a sha256 hex digest");
+  if (cls === "A" && !nonEmptyString(e.advisorySnapshotTime)) p.push("advisorySnapshotTime is required");
+  for (const s of e.scans) {
+    const derived = scanClassOf(s?.id);
+    if (s?.class === other || derived === other) p.push(`${cls === "A" ? "SCAN_A claims" : "SCAN_B carries"} class ${other} scan ${s?.id}`);
+    else if (s?.class !== cls) p.push(`scan ${s?.id} has class ${s?.class}, expected ${cls}`);
+    if (s?.status !== "pass") p.push(`scan ${s?.id} is ${s?.status}, not pass`);
+  }
+  const ids = new Set(e.scans.map((s) => s?.id));
+  const required = ctx.requiredScans?.[cls];
+  const declared = Array.isArray(e.requiredScanIds) ? e.requiredScanIds : null;
+  if (!declared) p.push("requiredScanIds is required");
+  // The required set comes only from the injected policy matrix. A receipt's own declaration is never trusted:
+  // without the policy, verification fails closed.
+  if (!Array.isArray(required) || required.some((id) => typeof id !== "string")) {
+    p.push(`trusted required scan set for class ${cls} is not supplied by policy; verification fails closed`);
+    return p;
+  }
+  for (const id of required) if (!ids.has(id)) p.push(`required class ${cls} scan ${id} is missing`);
+  if (declared && canonicalJson([...required].sort()) !== canonicalJson([...declared].sort())) p.push(`requiredScanIds differ from the trusted class ${cls} set`);
+  if (e.scanSetDigest !== digestScanSet(e.scans)) p.push("scanSetDigest does not match the listed scans");
+  if (cls === "B" && !nonEmptyArray(required)) p.push("SCAN_B must require at least one class B scan");
+  return p;
+}
+
+/**
+ * Verify a chain of receipts (ADMISSION first, ending at the stage being authorized).
+ *
+ * options:
+ *   verifySignature({ receipt, keyId, signingBytes, signature }) -> boolean   REQUIRED (the broker supplies keys)
+ *   now                 ISO string or Date, default current time
+ *   expected            { requestId, operation, inputDigest, stage, repositoryId, commit, jobId, releaseId, targetSet } (each optional but checked when given)
+ *   requiredScans       { A: [ids], B: [ids] } trusted required sets from the policy matrix: REQUIRED; absence rejects (NO_SCAN_POLICY)
+ *   ledger              { requestOwner(requestId), isConsumed(receiptId) }   REQUIRED: without it verification fails (NO_LEDGER)
+ *   keyAllowed          (keyId, receipt) -> boolean, for revocations
+ * Returns { ok, problems: [{ code, stage, message }], head }. Never throws on a bad receipt.
+ */
+export function verifyReceiptChain(chain, options = {}) {
+  const problems = [];
+  const bad = (code, stage, message) => problems.push({ code, stage: stage ?? null, message });
+  if (typeof options.verifySignature !== "function") return { ok: false, problems: [{ code: "NO_SIGNATURE_VERIFIER", stage: null, message: "a signature verifier must be supplied by the broker" }], head: null };
+  if (!Array.isArray(chain) || chain.length === 0) return { ok: false, problems: [{ code: "EMPTY_CHAIN", stage: null, message: "no receipts" }], head: null };
+  const now = new Date(options.now ?? Date.now()).getTime();
+  const expected = options.expected ?? {};
+  const byStage = {};
+  let previous = null;
+  // Replay protection is mandatory: without a ledger the chain cannot be proven fresh, so it fails closed.
+  if (typeof options.ledger?.requestOwner !== "function" || typeof options.ledger?.isConsumed !== "function") {
+    bad("NO_LEDGER", null, "a request ledger with requestOwner and isConsumed must be supplied; replay cannot be ruled out without it");
+  }
+  // One release id for the whole chain: the ADMISSION one when it has it, else the first release-stage one.
+  const releaseRef = chain.find((r) => isObj(r) && nonEmptyString(r.releaseId))?.releaseId;
+  // ADMISSION fixes which stages may run and whether the request may publish at all.
+  const admission = isObj(chain[0]) && chain[0].type === "ADMISSION" && isObj(chain[0].evidence) ? chain[0].evidence : null;
+
+  chain.forEach((receipt, index) => {
+    const stage = isObj(receipt) ? receipt.type : null;
+    if (!isObj(receipt)) { bad("MALFORMED", null, `receipt ${index} is not an object`); return; }
+    if (receipt.schema !== RECEIPT_SCHEMA) bad("SCHEMA", stage, `schema must be ${RECEIPT_SCHEMA}`);
+    if (!STAGES.includes(stage)) { bad("UNKNOWN_STAGE", stage, `unknown receipt type ${JSON.stringify(stage)}`); return; }
+    const wantStage = STAGES[index];
+    if (stage !== wantStage) bad("WRONG_STAGE", stage, `position ${index} requires ${wantStage}, got ${stage}`);
+    for (const f of ENVELOPE_STRINGS) if (!nonEmptyString(receipt[f])) bad("ENVELOPE", stage, `${f} is required`);
+    if (!Number.isInteger(receipt.attempt) || receipt.attempt < 1) bad("ENVELOPE", stage, "attempt must be an integer >= 1");
+    if (!Array.isArray(receipt.targetSet)) bad("ENVELOPE", stage, "targetSet must be an array");
+    if (!OPERATIONS.includes(receipt.operation)) bad("WRONG_OPERATION", stage, `unknown operation ${JSON.stringify(receipt.operation)}`);
+    if (RELEASE_ID_STAGES.has(stage) && !nonEmptyString(receipt.releaseId)) bad("ENVELOPE", stage, "releaseId is required");
+    if (!isObj(receipt.evidence)) bad("EVIDENCE", stage, "evidence is required");
+
+    // The operation bounds how far a request may go.
+    const last = OPERATION_LAST_STAGE[receipt.operation];
+    if (last && STAGES.indexOf(stage) > STAGES.indexOf(last)) bad("WRONG_OPERATION", stage, `operation ${receipt.operation} does not authorize ${stage}`);
+
+    // ADMISSION bounds the chain: only its authorized stages, and nothing from SIGN on unless publishable:true.
+    for (const x of admissionProblems(admission, stage)) bad(x.code, stage, x.message);
+
+    // Binding to the caller's expectations.
+    if (expected.requestId !== undefined && receipt.requestId !== expected.requestId) bad("WRONG_REQUEST_ID", stage, "requestId differs from the expected request");
+    if (expected.operation !== undefined && receipt.operation !== expected.operation) bad("WRONG_OPERATION", stage, `operation ${receipt.operation} differs from expected ${expected.operation}`);
+    if (expected.inputDigest !== undefined && receipt.inputDigest !== expected.inputDigest) bad("WRONG_INPUT_DIGEST", stage, "inputDigest differs from the expected input");
+    for (const f of ["repositoryId", "commit", "jobId", "releaseId"]) if (expected[f] !== undefined && receipt[f] !== expected[f]) bad("BINDING", stage, `${f} differs from the expected value`);
+    if (expected.targetSet !== undefined && canonicalJson(receipt.targetSet ?? null) !== canonicalJson(expected.targetSet)) bad("BINDING", stage, "targetSet differs from the expected value");
+    if (releaseRef !== undefined && receipt.releaseId !== undefined && receipt.releaseId !== releaseRef) bad("BINDING", stage, "releaseId differs from the chain's release");
+
+    // Consistency across the chain.
+    const first = chain[0];
+    if (index > 0 && isObj(first)) {
+      for (const f of ["requestId", "jobId", "repositoryId", "commit", "inputDigest", "configDigest", "policyDigest", "stagePlanDigest", "operation", "targetSet"]) {
+        if (f === "targetSet" ? canonicalJson(receipt[f] ?? null) !== canonicalJson(first[f] ?? null) : receipt[f] !== first[f]) bad(f === "requestId" ? "WRONG_REQUEST_ID" : f === "inputDigest" ? "WRONG_INPUT_DIGEST" : f === "operation" ? "WRONG_OPERATION" : "BINDING", stage, `${f} differs from the ADMISSION receipt`);
+      }
+    }
+
+    // Freshness.
+    const issued = Date.parse(receipt.issuedAt); const expires = Date.parse(receipt.expiresAt);
+    if (Number.isNaN(issued) || Number.isNaN(expires)) bad("ENVELOPE", stage, "issuedAt and expiresAt must be ISO timestamps");
+    else {
+      if (expires <= issued) bad("ENVELOPE", stage, "expiresAt must be after issuedAt");
+      if (expires <= now) bad("EXPIRED", stage, `expired at ${receipt.expiresAt}`);
+      if (issued > now + 60_000) bad("ENVELOPE", stage, "issuedAt is in the future");
+      if (previous && issued < Date.parse(previous.issuedAt)) bad("ORDER", stage, "issued before its parent receipt");
+    }
+
+    // Hash chain.
+    const wantParents = previous ? [receiptHash(previous)] : [];
+    if (!Array.isArray(receipt.parents) || canonicalJson(receipt.parents) !== canonicalJson(wantParents)) bad("BROKEN_CHAIN", stage, previous ? `parents must be exactly [hash of ${previous.type}]` : "ADMISSION has no parents");
+
+    // Replay (the ledger is required; see NO_LEDGER above).
+    if (typeof options.ledger?.requestOwner === "function" && typeof options.ledger?.isConsumed === "function") {
+      const owner = options.ledger.requestOwner(receipt.requestId);
+      if (owner !== undefined && owner !== receipt.jobId) bad("REPLAYED_REQUEST_ID", stage, "requestId already belongs to another job");
+      if (options.ledger.isConsumed(receipt.receiptId)) bad("REPLAYED_RECEIPT", stage, "receipt already consumed");
+    }
+
+    // Signature (injected).
+    if (options.keyAllowed && !options.keyAllowed(receipt.keyId, receipt)) bad("KEY_REVOKED", stage, `key ${receipt.keyId} is not allowed for this receipt`);
+    let signatureOk = false;
+    try { signatureOk = options.verifySignature({ receipt, keyId: receipt.keyId, signingBytes: signingBytes(receipt), signature: receipt.signature }) === true; } catch { signatureOk = false; }
+    if (!signatureOk) bad("BAD_SIGNATURE", stage, "signature did not verify");
+
+    byStage[stage] = receipt;
+    // Stage evidence last: it can look at the earlier stages collected so far.
+    if (isObj(receipt.evidence) && STAGE_EVIDENCE[stage]) {
+      for (const message of STAGE_EVIDENCE[stage](receipt.evidence, { byStage, requiredScans: options.requiredScans })) {
+        const code = /trusted required scan set/.test(message) ? "NO_SCAN_POLICY" : /missing|claims|carries/.test(message) && (stage === "SCAN_A" || stage === "SCAN_B") ? (/claims|carries/.test(message) ? "SCAN_CLASS_MIX" : "SCAN_INCOMPLETE") : "EVIDENCE";
+        bad(code, stage, message);
+      }
+    }
+    previous = receipt;
+  });
+
+  const head = chain[chain.length - 1];
+  if (expected.stage !== undefined) {
+    if (!STAGES.includes(expected.stage)) bad("WRONG_STAGE", null, `unknown expected stage ${expected.stage}`);
+    else if (head?.type !== expected.stage) bad("WRONG_STAGE", head?.type, `chain ends at ${head?.type}, expected ${expected.stage}`);
+  }
+  return { ok: problems.length === 0, problems, head: isObj(head) ? { type: head.type, hash: receiptHash(head) } : null };
+}
+
+/**
+ * Verify that a new stage may start: the chain so far must verify and end at the stage `stage` requires.
+ * Returns the same result shape; `authorizes` is the stage the chain authorizes next (or null).
+ */
+export function authorizeNextStage(chain, stage, options = {}) {
+  const need = PREREQUISITES[stage];
+  if (!need) return { ok: false, problems: [{ code: "UNKNOWN_STAGE", stage, message: `unknown stage ${stage}` }], head: null, authorizes: null };
+  if (need.length === 0) return { ok: !chain?.length, problems: chain?.length ? [{ code: "WRONG_STAGE", stage, message: "ADMISSION starts a chain" }] : [], head: null, authorizes: chain?.length ? null : stage };
+  const result = verifyReceiptChain(chain, { ...options, expected: { ...(options.expected ?? {}), stage: need[0] } });
+  // The requested stage itself must sit inside the operation's boundary and ADMISSION's authorized stages.
+  const first = Array.isArray(chain) ? chain[0] : null;
+  const last = OPERATION_LAST_STAGE[first?.operation];
+  if (!last || STAGES.indexOf(stage) > STAGES.indexOf(last)) result.problems.push({ code: "WRONG_OPERATION", stage, message: `operation ${first?.operation} does not authorize ${stage}` });
+  const admission = first?.type === "ADMISSION" && isObj(first.evidence) ? first.evidence : null;
+  for (const x of admissionProblems(admission, stage)) result.problems.push({ code: x.code, stage, message: x.message });
+  result.ok = result.problems.length === 0;
+  return { ...result, authorizes: result.ok ? stage : null };
+}

package/publication-gate.mjs

@@ -370,7 +370,7 @@ export function verifyNpmRegistryBytes({ name, version, sha1 }, deps = {}) {
   }
 }
 
-function readKeychainToken(run) {
+export function readKeychainToken(run = spawnSync) {
   if (process.platform !== "darwin") throw new Error(`npm publish token lookup is implemented for the macOS Keychain (${NPM_KEYCHAIN_SERVICE}) only`);
   const result = run("security", ["find-generic-password", "-s", NPM_KEYCHAIN_SERVICE, "-w"], { encoding: "utf8", windowsHide: true });
   const token = (result.stdout ?? "").trim();

package/publish-local-npm.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+// `right-release publish-local npm --package @rightkit/<name> --commit <sha>`: the local npm route (Adrian, 2026-11-03, rightkit#1471:
+// "i want you to publish it from local. the npm and crates are both local. we will do a provenance skip fuck your ci. feel free to push
+// but no ci"). Mac only: the token is the granular @rightkit token with 2FA bypass in the Keychain item npm-rightkit-publish, read inside
+// this process, never printed, never on a command line, never left on disk.
+//
+// It publishes exactly the bytes of one commit, and only after:
+//   1. the commit is on origin/main (pushed; [skip ci] is fine);
+//   2. the gate's Class A for the package passes on that commit (`rightkit-gate --to check --unit npm:<name> --commit <sha>`, this
+//      package's own gate, so a release publishes through the gate it ships);
+//   3. the version is not on npm yet.
+// The package folder is exported from the commit (git archive) and packed there; npm provenance is off (rightkit#1472). After publishing,
+// the registry's shasum must equal the packed tarball's, or the command fails.
+import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { NPM_KEYCHAIN_SERVICE, readKeychainToken } from "./publication-gate.mjs";
+
+const REGISTRY = "https://registry.npmjs.org/";
+const GATE = fileURLToPath(new URL("./bin/rightkit-gate.mjs", import.meta.url));
+
+function fail(message) { throw new Error(message); }
+
+export function parseArgs(argv) {
+  const out = { kind: argv[0], pkg: null, commit: null, repo: process.cwd() };
+  for (let i = 1; i < argv.length; i += 1) {
+    if (argv[i] === "--package") out.pkg = argv[++i];
+    else if (argv[i] === "--commit") out.commit = argv[++i];
+    else if (argv[i] === "--repo") out.repo = path.resolve(argv[++i]);
+    else fail(`unknown option ${argv[i]}`);
+  }
+  if (out.kind !== "npm") fail("publish-local supports npm; crates publish with publish-local cargo once it lands");
+  if (!/^@rightkit\/[a-z0-9-]+$/.test(out.pkg ?? "")) fail("--package @rightkit/<name> is required");
+  if (!/^[0-9a-f]{7,40}$/.test(out.commit ?? "")) fail("--commit <sha> is required");
+  return out;
+}
+
+export function publishLocalNpm(argv, { run = spawnSync, log = console.log, platform = process.platform, readToken = () => readKeychainToken(run) } = {}) {
+  const o = parseArgs(argv);
+  if (platform !== "darwin") fail(`publish-local npm runs on the Mac (the token is the Keychain item ${NPM_KEYCHAIN_SERVICE}); this host is ${platform}`);
+  const git = (args) => {
+    const r = run("git", args, { cwd: o.repo, encoding: "utf8", maxBuffer: 1 << 26 });
+    if (r.status !== 0) fail(`git ${args.join(" ")} failed: ${String(r.stderr ?? "").trim()}`);
+    return String(r.stdout ?? "").trim();
+  };
+  const commit = git(["rev-parse", "--verify", `${o.commit}^{commit}`]);
+  git(["fetch", "-q", "origin", "main"]);
+  if (run("git", ["merge-base", "--is-ancestor", commit, "origin/main"], { cwd: o.repo }).status !== 0) fail(`${commit} is not on origin/main: push it first ([skip ci])`);
+  const dir = `packages/${o.pkg.slice("@rightkit/".length)}`;
+  const manifest = JSON.parse(git(["show", `${commit}:${dir}/package.json`]));
+  if (manifest.name !== o.pkg) fail(`${dir}/package.json at ${commit} names ${manifest.name}, not ${o.pkg}`);
+  const version = manifest.version;
+
+  const already = run("npm", ["view", `${o.pkg}@${version}`, "version", "--prefer-online", "--registry", REGISTRY], { encoding: "utf8" });
+  if (String(already.stdout ?? "").trim() === version) fail(`${o.pkg}@${version} is already on npm; bump the version`);
+
+  log(`publish-local: Class A for npm:${o.pkg} on ${commit.slice(0, 12)}`);
+  const classA = run(process.execPath, [GATE, "--to", "check", "--unit", `npm:${o.pkg}`, "--commit", commit], { cwd: o.repo, stdio: ["ignore", "inherit", "inherit"] });
+  if (classA.status !== 0) fail(`Class A failed for npm:${o.pkg} on ${commit} (exit ${classA.status}); nothing published`);
+
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), "rk-publish-local-"));
+  try {
+    const archive = run("git", ["archive", "--format=tar", commit, dir], { cwd: o.repo, maxBuffer: 1 << 30 });
+    if (archive.status !== 0) fail(`git archive ${commit} ${dir} failed`);
+    const tarIn = run("tar", ["-x", "-C", work], { input: archive.stdout });
+    if (tarIn.status !== 0) fail("unpacking the commit's package folder failed");
+    const pkgDir = path.join(work, dir);
+    const packed = run("pnpm", ["pack", "--pack-destination", work], { cwd: pkgDir, encoding: "utf8" });
+    if (packed.status !== 0) fail(`pnpm pack failed: ${String(packed.stderr ?? packed.stdout ?? "").trim().split(/\r?\n/).slice(-3).join(" | ")}`);
+    const tgz = fs.readdirSync(work).find((f) => f.endsWith(".tgz"));
+    if (!tgz) fail("pnpm pack wrote no tarball");
+    const bytes = fs.readFileSync(path.join(work, tgz));
+    const sha1 = crypto.createHash("sha1").update(bytes).digest("hex");
+    log(`publish-local: packed ${tgz} sha1 ${sha1}`);
+
+    const token = readToken();
+    const userconfig = path.join(work, "npmrc");
+    fs.writeFileSync(userconfig, "//registry.npmjs.org/:_authToken=${RIGHTKIT_NPM_TOKEN}\n", { mode: 0o600 });
+    const redact = (text) => String(text ?? "").split(token).join("<redacted>");
+    const pub = run("npm", ["publish", path.join(work, tgz), "--access", "public", "--provenance=false", "--registry", REGISTRY, "--userconfig", userconfig],
+      { encoding: "utf8", env: { ...process.env, RIGHTKIT_NPM_TOKEN: token } });
+    if (pub.status !== 0) fail(`npm publish failed:\n${redact(`${pub.stdout ?? ""}${pub.stderr ?? ""}`).trim()}`);
+
+    // The registry may take a moment to serve a new version.
+    let shasum = "";
+    for (let i = 0; i < 20 && !shasum; i += 1) {
+      const view = run("npm", ["view", `${o.pkg}@${version}`, "dist.shasum", "--prefer-online", "--registry", REGISTRY], { encoding: "utf8" });
+      shasum = String(view.stdout ?? "").trim();
+      if (!shasum) run("sleep", ["15"]);
+    }
+    if (shasum !== sha1) fail(`registry shasum ${shasum || "(not served yet)"} != packed ${sha1} for ${o.pkg}@${version}`);
+    log(`publish-local: ${o.pkg}@${version} published from ${commit.slice(0, 12)}; registry shasum ${shasum} matches`);
+    return { name: o.pkg, version, commit, shasum };
+  } finally {
+    fs.rmSync(work, { recursive: true, force: true });
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try { publishLocalNpm(process.argv.slice(2)); } catch (e) { console.error(`right-release publish-local: ${e.message}`); process.exit(1); }
+}

package/rightkit-versions.json

@@ -49,7 +49,7 @@
     "@rightkit/qa": "0.6.2",
     "@rightkit/qa-chrome": "0.1.12",
     "@rightkit/react-shell": "0.7.2",
-    "@rightkit/release": "0.6.27",
+    "@rightkit/release": "0.6.29",
     "@rightkit/settings-ui": "0.7.0",
     "@rightkit/social-ui": "0.1.0",
     "@rightkit/system-ui": "0.1.0",

package/bin/darwin/rightkit-swap.sign.json

@@ -1,6 +0,0 @@
-{
-  "schema": 1,
-  "sha256": "a41ce13fd3bac31db0230d70bed20db0ed9bf554bdae2255bdf2064589b48f29",
-  "identity": "Developer ID Application: Adrian D'souza (6KLGD3LLKF)",
-  "codesign": "strict-valid"
-}