@rightkit/release 0.6.27 → 0.6.28

package/build-helper-trace.mjs

@@ -169,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];
 }
@@ -210,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;
@@ -330,7 +334,7 @@ export function etwWritesByRoot(file, roots, devices = {}) {
     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 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;

package/build-helpers-command.mjs

@@ -63,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();
 }
 
@@ -143,8 +144,10 @@ 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");
@@ -174,7 +177,7 @@ function mainWith(argv, { env, platform, run, log, err }) {
       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: "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 };
@@ -188,7 +191,32 @@ function mainWith(argv, { env, platform, run, log, err }) {
       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

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.27",
+  "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.27",
+    "@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"
-}