@rightkit/release 0.6.26 → 0.6.28

package/build-helper-trace.mjs

@@ -23,8 +23,9 @@ const CRATES_IO = new Set(["registry+https://github.com/rust-lang/crates.io-inde
 const sha256 = (text) => createHash("sha256").update(text).digest("hex");
 
 /** The unit key: sha256 of the canonical {crate, version, checksum, features (sorted), target, toolchain}. */
-export function buildHelperKey({ crate, version, checksum, features = [], target, toolchain }) {
-  return sha256(JSON.stringify({ crate, version, checksum, features: [...features].sort(), target, toolchain }));
+// No toolchain in the key (Adrian, 2026-11-03, rightkit#1473: "why would a rust upgrade void it"): a Rust upgrade never voids a trace list.
+export function buildHelperKey({ crate, version, checksum, features = [], target }) {
+  return sha256(JSON.stringify({ crate, version, checksum, features: [...features].sort(), target }));
 }
 
 /** Checksums of crates.io packages from a Cargo.lock text: Map "name version" -> checksum. */
@@ -93,8 +94,16 @@ export function recordTrace(file, unit, verdict, { now = () => new Date().toISOS
  */
 export function checkBuildHelpers(units, list) {
   const untraced = []; const failed = [];
+  // Entries recorded under the older key (which held the toolchain) are re-keyed from their own fields; a pass wins over a fail.
+  const byKey = new Map();
+  for (const entry of Object.values(list?.units ?? {})) {
+    if (!entry || typeof entry !== "object") continue;
+    const key = buildHelperKey(entry);
+    const had = byKey.get(key);
+    if (!had || (had.verdict !== "pass" && entry.verdict === "pass") || !TRUSTED_TRACERS.includes(had.tracer)) byKey.set(key, entry);
+  }
   for (const u of units) {
-    const entry = list?.units?.[u.key];
+    const entry = byKey.get(u.key);
     if (!entry || !u.checksum || !TRUSTED_TRACERS.includes(entry.tracer)) untraced.push(u);
     else if (entry.verdict !== "pass") failed.push({ unit: u, outside: entry.outside ?? [] });
   }
@@ -160,11 +169,15 @@ export function parseStraceWrites(text, { cwd = "/" } = {}) {
   const out = new Set();
   for (const line of String(text).split(/\r?\n/)) {
     if (/=\s*-1\s/.test(line) || /<unfinished \.\.\.>/.test(line)) continue;
+    // With `strace -y`, a directory fd prints its real path (`AT_FDCWD</abs/cwd>`, `5</abs/dir>`): a relative path resolves against that,
+    // never against a guessed folder (rustc writes `full.rmeta` relative to its own working directory).
+    const dirOf = new Map([...line.matchAll(/(?:AT_FDCWD|\d+)<([^>]+)>,\s*"((?:[^"\\]|\\.)*)"/g)].map((m) => [m[2], m[1]]));
+    const resolveIt = (p) => (path.posix.isAbsolute(p) ? p : path.posix.resolve(dirOf.get(p) ?? cwd, p));
     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));
+    for (const p of paths) if (p) out.add(resolveIt(p));
   }
   return [...out];
 }
@@ -201,7 +214,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;
@@ -262,3 +275,77 @@ 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 = "";
+  try {
+    for (let n = fsApi.readSync(fd, buf, 0, buf.length, null); n > 0; n = fsApi.readSync(fd, buf, 0, buf.length, null)) {
+      const parts = (rest + buf.toString("utf8", 0, n)).split(sep);
+      rest = parts.pop();
+      for (const part of parts) fn(part);
+    }
+    if (rest) fn(rest);
+  } finally { fsApi.closeSync(fd); }
+}
+
+/** The root (one of `roots`) a pid descends from, through `parent`, or null. */
+function rootFinder(parent, roots) {
+  const memo = new Map();
+  return (pid) => {
+    if (!Number.isInteger(pid)) return null;
+    if (memo.has(pid)) return memo.get(pid);
+    let found = null;
+    for (let p = pid, hops = 0; Number.isInteger(p) && hops < 64; p = parent.get(p), hops += 1) if (roots.has(p)) { found = p; break; }
+    memo.set(pid, found);
+    return found;
+  };
+}
+
+/** eslogger JSON lines from `file`, streamed: Map(root pid -> written paths) for every pid in `roots` (a Set), in two passes. */
+export function esloggerWritesByRoot(file, roots) {
+  const parent = new Map();
+  const parse = (line) => { if (!line.trim().startsWith("{")) return null; try { return JSON.parse(line); } catch { return null; } };
+  forEachRecord(file, "\n", (line) => {
+    const e = parse(line); if (!e) return;
+    const pid = e?.process?.audit_token?.pid; const ppid = e?.process?.ppid ?? e?.process?.original_ppid;
+    if (Number.isInteger(pid) && Number.isInteger(ppid) && !parent.has(pid)) parent.set(pid, ppid);
+    const child = e?.event?.fork?.child?.audit_token?.pid;
+    if (Number.isInteger(child) && Number.isInteger(pid)) parent.set(child, pid);
+  });
+  const rootOf = rootFinder(parent, roots); const out = new Map([...roots].map((r) => [r, new Set()]));
+  forEachRecord(file, "\n", (line) => {
+    const e = parse(line); if (!e) return;
+    const root = rootOf(e?.process?.audit_token?.pid); if (root === null) return;
+    for (const w of parseEsloggerWrites(line, { rootPid: e.process.audit_token.pid })) out.get(root).add(w);
+  });
+  return new Map([...out].map(([r, s]) => [r, [...s]]));
+}
+
+/** tracerpt XML from `file`, streamed by `</Event>`: Map(root pid -> written paths) for every pid in `roots`, kernel paths mapped by `devices`. */
+export function etwWritesByRoot(file, roots, devices = {}) {
+  const field = (ev, name) => new RegExp(`<Data Name="${name}">([^<]*)</Data>`).exec(ev)?.[1];
+  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();
+  forEachRecord(file, "</Event>", (ev) => {
+    if (provider(ev) === "Microsoft-Windows-Kernel-Process" && id(ev) === 1) parent.set(Number(field(ev, "ProcessID")), Number(field(ev, "ParentProcessID")));
+  });
+  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 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); };
+    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 === 26 || n === 27) add(field(ev, "FilePath") ?? field(ev, "FileName"));
+  });
+  return new Map([...out].map(([r, s]) => [r, [...s]]));
+}

package/build-helpers-command.mjs

@@ -13,7 +13,7 @@ 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, judgeTrace, mergeLists, parseEsloggerWrites, parseEtwWrites, parseStraceWrites, readStraceFiles, readHostList, recordTrace, repoListPath } from "./build-helper-trace.mjs";
+import { buildHelperRefusal, buildHelperUnits, checkBuildHelpers, hostListPath, esloggerWritesByRoot, etwWritesByRoot, judgeTrace, mergeLists, parseStraceWrites, readStraceFiles, readHostList, recordTrace, repoListPath } from "./build-helper-trace.mjs";
 import { resolveManagedRoots } from "./managed-roots.mjs";
 import { directCargoPath } from "./managed-cargo.mjs";
 
@@ -27,6 +27,22 @@ function hostFacts(run = spawnSync) {
   return { target: host, toolchain: `rustc ${release}${commit ? ` (${commit.slice(0, 9)})` : ""}` };
 }
 
+// Runs the trace builds, `argv[3]` at a time, starting the next whenever one finishes: argv[1] = jobs JSON [{cmd, args, env}], argv[2] = results
+// file [{pid, status, error}] in job order.
+const BATCH_RUNNER = `const fs = require("node:fs"); const { spawn } = require("node:child_process");
+const jobs = JSON.parse(fs.readFileSync(process.argv[1], "utf8")); const limit = Math.max(1, Number(process.argv[3]) || 4);
+const results = new Array(jobs.length); let next = 0; let done = 0;
+const start = (i) => new Promise((resolve) => {
+  const j = jobs[i]; let child;
+  try { child = spawn(j.cmd, j.args, { env: j.env, stdio: ["ignore", "ignore", "pipe"] }); } catch (e) { results[i] = { status: -1, error: e.message }; resolve(); return; }
+  let tail = ""; child.stderr.on("data", (d) => { tail = (tail + d).slice(-2000); });
+  const finish = (r) => { if (results[i]) return; results[i] = r; done += 1; process.stdout.write("  [" + done + "/" + jobs.length + "] " + j.label + (r.status === 0 ? " built" : " failed") + "\\n"); resolve(); };
+  child.on("error", (e) => finish({ pid: child.pid, status: -1, error: e.message }));
+  child.on("close", (status) => finish({ pid: child.pid, status, ...(status ? { error: tail.trim().split("\\n").slice(-2).join(" | ") } : {}) }));
+});
+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 });
@@ -47,7 +63,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();
 }
 
@@ -72,12 +89,15 @@ function traceAll(argv, { env, platform, log, err }) {
   try {
     for (const ws of workspaces) {
       log(`--- ${ws}`);
-      const code = main(["trace", "--manifest-path", path.join(ws, "Cargo.toml"), "--record-repo"], { env, platform, log, err });
+      const jobsAt = argv.indexOf("--jobs");
+      // The host list is what Class A reads on this host; a repository's committed list is written only on request (--record-repo), so
+      // tracing never edits a checkout another owner holds.
+      const code = main(["trace", "--manifest-path", path.join(ws, "Cargo.toml"), ...(argv.includes("--record-repo") ? ["--record-repo"] : []), ...(jobsAt >= 0 ? ["--jobs", argv[jobsAt + 1]] : [])], { env, platform, log, err });
       if (code !== 0) err(`right-release build-helpers trace-all: ${ws} ended with ${code}`);
       worst = Math.max(worst, code);
     }
   } finally { try { keepAlive?.kill(); } catch { /* already gone */ } }
-  log(`right-release build-helpers trace-all: done; commit each workspace's .rightkit/build-helper-trace.json`);
+  log(`right-release build-helpers trace-all: done${argv.includes("--record-repo") ? "; commit each workspace's .rightkit/build-helper-trace.json" : ""}`);
   return worst;
 }
 
@@ -89,7 +109,10 @@ export function main(argv = process.argv.slice(2), { env = process.env, platform
   const directPath = directCargoPath({ env: { ...env, PATH: env[pathKey] }, platform, gateWrappers: true }).path;
   const scratchTarget = fs.mkdtempSync(path.join(os.tmpdir(), "rk-bh-target-"));
   const run = runRaw ?? ((cmd, args, opts = {}) => spawnSync(cmd, args, { ...opts, env: { ...env, ...(opts.env ?? {}), [pathKey]: directPath, CARGO_TARGET_DIR: opts.env?.CARGO_TARGET_DIR ?? scratchTarget } }));
-  try { return mainWith(argv, { env, platform, run, log, err }); } finally { fs.rmSync(scratchTarget, { recursive: true, force: true }); }
+  // The parallel trace builds are spawned by the batch runner with the job's own env: that env carries the direct PATH too, so no build
+  // ever goes through the RustRight shim (which refuses a build that redirects its output folder).
+  const directEnv = { ...env, [pathKey]: directPath };
+  try { return mainWith(argv, { env: directEnv, platform, run, log, err }); } finally { fs.rmSync(scratchTarget, { recursive: true, force: true }); }
 }
 
 function mainWith(argv, { env, platform, run, log, err }) {
@@ -121,62 +144,133 @@ 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");
-    for (const unit of [...verdict.untraced, ...verdict.failed.map((f) => f.unit)]) {
+    // 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.
+    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)];
+    log(`right-release build-helpers trace: ${pending.length} unit(s), ${jobs} at a time`);
+    if (!pending.length) return 0;
+    const prepared = pending.map((unit) => {
       const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "rk-bht-"));
-      const traceFile = path.join(scratch, "trace.txt");
-      const buildArgs = ["build", "-p", `${unit.crate}@${unit.version}`, "--locked", "--target-dir", path.join(scratch, "target"), ...(manifestPath ? ["--manifest-path", manifestPath] : [])];
-      const buildEnv = { ...env, CARGO_TARGET_DIR: path.join(scratch, "target") };
-      let build;
-      if (platform === "win32") {
-        const etlFile = path.join(scratch, "file.etl"); const etlProc = path.join(scratch, "proc.etl");
-        run("logman", ["stop", "rk-bht-file", "-ets"]); run("logman", ["stop", "rk-bht-proc", "-ets"]);
-        const startProc = run("logman", ["start", "rk-bht-proc", "-p", "Microsoft-Windows-Kernel-Process", "0x10", "-o", etlProc, "-ets"], { encoding: "utf8" });
-        const startFile = run("logman", ["start", "rk-bht-file", "-p", "Microsoft-Windows-Kernel-File", "0x1E90", "-o", etlFile, "-ets"], { encoding: "utf8" });
-        if (startProc.status !== 0 || startFile.status !== 0) { err(`right-release build-helpers trace: logman could not start the ETW sessions: ${String(startFile.stdout ?? startProc.stdout ?? "").trim()}`); return 2; }
-        try { build = run("cargo", buildArgs, { encoding: "utf8", env: buildEnv }); }
-        finally { run("logman", ["stop", "rk-bht-file", "-ets"]); run("logman", ["stop", "rk-bht-proc", "-ets"]); }
-        const xml = path.join(scratch, "trace.xml");
-        const exported = run("tracerpt", [etlProc, etlFile, "-o", xml, "-of", "XML", "-y"], { encoding: "utf8" });
-        if (exported.status !== 0) { err("right-release build-helpers trace: tracerpt could not export the ETW trace"); return 2; }
-        fs.writeFileSync(traceFile, fs.readFileSync(xml, "utf8"));
-      } else if (platform === "linux") {
-        // strace follows every child (-f) and records the file calls; it needs no root for the agent's own processes.
-        // -ff: one output file per process, so no system call is split across <unfinished>/<resumed> lines.
-        build = run("strace", ["-ff", "-qq", "-o", traceFile, "-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], { encoding: "utf8", env: buildEnv });
-        if (build.error?.code === "ENOENT") { err("right-release build-helpers trace: strace is not installed on this host"); return 2; }
-      } else {
-        // Endpoint Security (eslogger) names every event's process and its parent, so the whole tree under this process is traced: build
-        // scripts and everything they start (sh, cc, cmake, perl), whatever the name. Only the logger is root (`sudo -n`: the credential
-        // `trace-all` cached with one `sudo -v`); the build runs as the user. eslogger needs Full Disk Access for the terminal running it.
-        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"]);
-        build = run("cargo", buildArgs, { encoding: "utf8", env: buildEnv });
-        run("sleep", ["1"]);
-        if (tracerPid) { run("sudo", ["-n", "pkill", "-INT", "-P", tracerPid]); run("kill", [tracerPid]); run("sleep", ["1"]); }
-      }
-      if (build.error || build.status !== 0) { err(`right-release build-helpers trace: ${unit.crate} ${unit.version} did not build (${build.error?.message ?? `exit ${build.status}`}); not recorded`); continue; }
-      let text = ""; try { text = platform === "linux" ? readStraceFiles(traceFile) : fs.readFileSync(traceFile, "utf8"); } catch { /* no trace output */ }
-      if (!text.trim()) { err(`right-release build-helpers trace: ${platform === "linux" ? "strace" : platform === "darwin" ? "eslogger (it needs sudo and Full Disk Access for this terminal)" : "ETW"} recorded nothing; nothing recorded`); return 2; }
-      const writes = platform === "win32" ? parseEtwWrites(text, { rootPid: process.pid, devices })
-        : platform === "linux" ? parseStraceWrites(text, { cwd: path.dirname(path.resolve(manifestPath ?? "Cargo.toml")) }) : parseEsloggerWrites(text, { rootPid: process.pid });
-      const allowed = platform === "win32" ? [path.join(scratch, "target"), cargoHome, os.tmpdir(), env.LOCALAPPDATA ? path.join(env.LOCALAPPDATA, "Temp") : null]
-        : [path.join(scratch, "target"), cargoHome, os.tmpdir(), "/private/var/folders", "/dev", "/proc/self"];
-      const judged = judgeTrace(writes, { allowed, platform, mustSee: path.join(scratch, "target") });
-      recordTrace(listFile, unit, judged);
-      // --record-repo also writes the verdict into the repository's committed list, for review and commit by the repository's owner.
-      if (recordRepo) recordTrace(repoFile, unit, judged);
-      log(`${judged.ok ? "pass" : "FAIL"} ${unit.crate} ${unit.version}${judged.ok ? "" : `: wrote ${judged.outside.slice(0, 5).join(", ")}`}`);
-      fs.rmSync(scratch, { recursive: true, force: true });
+      const target = path.join(scratch, "target");
+      // The unit is built on its own: a throwaway probe package in the scratch folder depends on exactly this version with exactly its
+      // resolved features (`cargo build -p <crate>@<ver>` panics for a crate the workspace uses only as a build dependency, which most
+      // build helpers are). The workspace's Cargo.lock seeds the probe so its other crates resolve to the same versions.
+      const probe = path.join(scratch, "probe");
+      fs.mkdirSync(path.join(probe, "src"), { recursive: true });
+      const features = unit.features.filter((f) => f !== "default");
+      fs.writeFileSync(path.join(probe, "Cargo.toml"), `[package]\nname = "rk-build-helper-probe"\nversion = "0.0.0"\nedition = "2021"\npublish = false\n\n[dependencies]\n${JSON.stringify(unit.crate)} = { version = "=${unit.version}", default-features = ${unit.features.includes("default")}, features = ${JSON.stringify(features)} }\n\n[workspace]\n`);
+      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", "-y", "-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 };
+    });
+    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.
+    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"]);
+      // 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
+      // ParentProcessID) and file writes both recorded.
+      etl = { file: path.join(sessionDir, "trace.etl") };
+      const providers = path.join(sessionDir, "providers.txt");
+      fs.writeFileSync(providers, '"Microsoft-Windows-Kernel-Process" 0x10 0x5\r\n"Microsoft-Windows-Kernel-File" 0x1E90 0x5\r\n');
+      run("logman", ["stop", "rk-bht", "-ets"]);
+      const started = run("logman", ["start", "rk-bht", "-pf", providers, "-o", etl.file, "-ets"], { encoding: "utf8" });
+      if (started.status !== 0) { err(`right-release build-helpers trace: logman could not start the ETW session: ${String(started.stdout ?? "").trim()}`); return 2; }
+      stopTracer = () => { run("logman", ["stop", "rk-bht", "-ets"]); };
     }
+    // The runner keeps `jobs` builds running and starts the next whenever one finishes; each build's pid is its tree's root.
+    const jobsFile = path.join(sessionDir, "jobs.json"); const resultFile = path.join(sessionDir, "results.json");
+    fs.writeFileSync(jobsFile, JSON.stringify(prepared.map((b) => b.job)));
+    let runner;
+    try { runner = run(process.execPath, ["-e", BATCH_RUNNER, jobsFile, resultFile, String(jobs)], { encoding: "utf8", env, stdio: ["ignore", "inherit", "inherit"] }); }
+    finally { stopTracer(); }
+    let results = [];
+    try { results = JSON.parse(fs.readFileSync(resultFile, "utf8")); } catch { err(`right-release build-helpers trace: the build runner wrote no results (${runner?.error?.message ?? `exit ${runner?.status}`}); nothing recorded`); return 2; }
+    // The whole-run recording is streamed, never read into one string, and attributed to every build's tree in one pass.
+    const roots = new Set(results.filter((r) => r?.status === 0 && Number.isInteger(r.pid)).map((r) => r.pid));
+    let byRoot = new Map(); let recorded = false;
+    if (platform === "darwin") { try { recorded = fs.statSync(traceFile).size > 0; if (recorded) byRoot = esloggerWritesByRoot(traceFile, roots); } catch { /* no output */ } }
+    if (platform === "win32") {
+      const xml = path.join(sessionDir, "trace.xml");
+      const exported = run("tracerpt", [etl.file, "-o", xml, "-of", "XML", "-y"], { encoding: "utf8" });
+      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; }
+    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) ?? [];
+      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"];
+      // 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; } };
+      const roots = allowed.filter(Boolean).flatMap((d) => [d, real(d)]);
+      const judged = judgeTrace(writes, { allowed: roots, platform, mustSee: real(b.target) });
+      recordTrace(listFile, b.unit, judged);
+      // --record-repo also writes the verdict into the repository's committed list, for review and commit by the repository's owner.
+      if (recordRepo) recordTrace(repoFile, b.unit, judged);
+      log(`${judged.ok ? "pass" : "FAIL"} ${b.unit.crate} ${b.unit.version}${judged.ok ? "" : `: wrote ${judged.outside.slice(0, 5).join(", ")}`}`);
+    });
+    for (const b of prepared) fs.rmSync(b.scratch, { recursive: true, force: true });
+    fs.rmSync(sessionDir, { recursive: true, force: true });
     return 0;
   }
-  err("usage: right-release build-helpers check|trace [--manifest-path <Cargo.toml>] [--record-repo] | trace-all [--root <dir>]...");
+  err("usage: right-release build-helpers check|trace [--manifest-path <Cargo.toml>] [--record-repo] [--jobs N] | trace-all [--root <dir>]... [--jobs N]");
   return 2;
 }
 

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/release",
-  "version": "0.6.26",
+  "version": "0.6.28",
   "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/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.26",
+    "@rightkit/release": "0.6.28",
     "@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"
-}