@rightkit/release 0.6.10 → 0.6.11

package/snapshot-broker.mjs

@@ -0,0 +1,172 @@
+// The gate's production seam for a broker snapshot compile (item 7 rows 7.20 to 7.24; GATE-CONTRACT "Broker interface").
+//
+//   createSnapshotBroker   builds `deps.snapshotBroker` for runScans on a broker host (Mac, Dell): the commit, the snapshot, the
+//                          build-ownership handle, the declared inputs READ FROM THE SNAPSHOT, the host's enrolled pins (broker-pins.mjs,
+//                          never the receipt, an environment variable or a flag), the receipt reader and the managed output roots.
+//   runBrokerCargo         one cargo call reached by a test on the Mac, through the runtime wrapper's broker mode: its own fresh
+//                          nonce and carrier, `primaryCwd` from the gate's snapshot-to-checkout map, `callingGate` inherited and never
+//                          forged, the carrier removed after the call, the signed receipt verified, and a ledger record either way.
+//   verifyBrokerLedger     the gate's own re-verification of every ledgered call from the broker's signed receipt, with the gate's
+//                          own commit, snapshot, ownership handle and pins (never the wrapper's say-so), and one use per carrier.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "./background-process.mjs";
+import { loadBrokerPins } from "./broker-pins.mjs";
+import { resolveManagedRoots } from "./managed-roots.mjs";
+import {
+  SnapshotRequestError, argvSha256, observedEnvOf, readDeclaredInputs, readRequestRef, verifySnapshotReceipt, writeSnapshotRequest,
+} from "./snapshot-request.mjs";
+
+/** The status a refused or unverified call returns to its caller: cargo's own error status. */
+export const BROKER_REFUSAL_STATUS = 101;
+export const CALLING_GATE_ENV = "RIGHTKIT_CALLING_GATE";
+
+/** The managed `ws` roots a broker pins its generation targets under (BROKER-CONTRACT output pinning). */
+export const brokerOutputRoots = ({ dataRoot }) => [path.join(dataRoot, "rightkit-build-control", "ws")];
+
+/** The broker's receipt of one request, read through the RustRight client (`rustright status <id>`), synchronously. */
+export function receiptSync({ client, requestId, env, spawn = spawnSync }) {
+  const r = spawn(client, ["status", requestId], { encoding: "utf8", env, timeout: 60_000, maxBuffer: 64 * 1024 * 1024 });
+  if (r.error || r.status !== 0) throw new SnapshotRequestError("receipt", `rustright status ${requestId} failed (${r.error?.message ?? `exit ${r.status}`})`);
+  let doc;
+  try { doc = JSON.parse(String(r.stdout)); } catch { throw new SnapshotRequestError("receipt", `rustright status ${requestId} printed no JSON`); }
+  // The status envelope is `{type:"STATUS", id, state, ..., receipt}`: `receipt` is null while the job is live and full once it is
+  // terminal. Polling is not allowed, so a null receipt after the cargo process exited is a clear error, never a retry.
+  if (!doc || typeof doc !== "object" || !Object.hasOwn(doc, "receipt")) throw new SnapshotRequestError("receipt", `rustright status ${requestId} returned no receipt field (not a STATUS envelope)`);
+  if (doc.receipt === null) throw new SnapshotRequestError("receipt-not-ready", `rustright status ${requestId} reports the job ${doc.state ?? "state unknown"} with no receipt yet, although its cargo process exited; the gate does not poll, so this call is unverified`);
+  if (typeof doc.receipt !== "object" || Array.isArray(doc.receipt)) throw new SnapshotRequestError("receipt", `rustright status ${requestId} returned a receipt that is not an object`);
+  return doc.receipt;
+}
+
+/**
+ * `deps.snapshotBroker` for a production run on a broker host. Throws when anything the compile owes cannot be established:
+ * no build ownership, no RustRight client, no pins (an app repository without an enrollment), a malformed declared-inputs manifest.
+ * There is no way to hand it pins: tests build their own object and inject it as `deps.snapshotBroker`.
+ */
+export function createSnapshotBroker({ env = process.env, platform = process.platform, checkout, commit, snapshot, ownership, client, gateFile, dataRoot, spawn = spawnSync, loadPins = loadBrokerPins }) {
+  const need = (ok, why) => { if (!ok) throw new SnapshotRequestError("broker", why); };
+  need(checkout && path.isAbsolute(checkout), "the primary checkout must be an absolute path");
+  need(commit?.sha && commit?.tree, "the commit and its tree are required");
+  need(snapshot?.path && path.isAbsolute(snapshot.path) && snapshot.expectedTree === commit.tree, "the snapshot needs an absolute path and the commit's tree as expectedTree");
+  need(ownership && typeof ownership.handle === "string" && ownership.handle && typeof ownership.markBrokerSubmit === "function", "a broker snapshot compile needs the gate's build ownership (handle and submit hook)");
+  need(typeof client === "string" && path.isAbsolute(client), "a broker snapshot compile needs the RustRight client (`rustright`) by absolute path");
+  const roots = resolveManagedRoots({ env, platform });
+  const managedData = dataRoot ?? roots.dataRoot;
+  const pins = loadPins({ dataRoot: managedData, platform, gateFile, checkout, spawn });
+  return {
+    controlRoot: roots.controlRoot, commit: { sha: commit.sha, tree: commit.tree }, snapshot: { path: snapshot.path, expectedTree: snapshot.expectedTree },
+    declaredInputs: readDeclaredInputs(snapshot.path), handle: ownership.handle, markBrokerSubmit: () => ownership.markBrokerSubmit(),
+    pins: { host: pins.host, keyId: pins.keyId, publicKey: pins.publicKey, brokerDigest: pins.brokerDigest }, pinsSource: pins.source,
+    checkout: fs.realpathSync.native(checkout), outputRoots: brokerOutputRoots({ dataRoot: managedData }), platform, client,
+    receiptOf: async (requestId) => receiptSync({ client, requestId, env, spawn }),
+  };
+}
+
+/**
+ * What the production gate hands the door as `o.snapshotBroker`: the statement that this gate carries the RustRight snapshot carrier.
+ * The door only asks whether a broker host may take the snapshot route; the broker itself (pins, declared inputs, ownership, receipt
+ * reader) is built by `createSnapshotBroker` where the snapshot compile runs.
+ */
+export const PRODUCTION_SNAPSHOT_CARRIER = Object.freeze({ kind: "production", create: createSnapshotBroker });
+
+/** The part of a snapshot broker the wrapper process needs, as the map file carries it (public values only). */
+export const brokerSection = (sb, { sentinel = null } = {}) => ({
+  client: sb.client, controlRoot: sb.controlRoot, commit: sb.commit, snapshot: sb.snapshot, handle: sb.handle, checkout: sb.checkout,
+  pins: sb.pins, outputRoots: sb.outputRoots, platform: sb.platform, sentinel,
+});
+
+const escapes = (rel) => rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel);
+const inside = (child, parent) => { const rel = path.relative(parent, child); return rel === "" || !escapes(rel); };
+
+/**
+ * One cargo call of a test, carried through the broker. `workspace` is the real snapshot path of the cargo workspace the call
+ * resolved; `checkoutWorkspace` its counterpart in the primary checkout, from the gate's own map. Returns cargo's exit status.
+ * Every outcome is ledgered through `record` first or after, never skipped.
+ */
+export function runBrokerCargo({ words, cwd, env, section, workspace, checkoutWorkspace, record, spawn = spawnSync, err, tmp = os.tmpdir() }) {
+  const id = crypto.randomUUID();
+  const base = { id, mode: "broker", cwd, argv: [...words] };
+  const refuse = (code, message) => { record({ ...base, status: "refused", code, message }); err(`rightkit-gate: ${code}: ${message}`); return BROKER_REFUSAL_STATUS; };
+  const gate = env[CALLING_GATE_ENV];
+  if (typeof gate !== "string" || !gate.trim()) return refuse("RK_CARGO_BROKER_NO_GATE", `${CALLING_GATE_ENV} is not set: the call names no gate, and the wrapper never forges one`);
+  let realCwd; let checkoutCwd;
+  try {
+    realCwd = fs.realpathSync.native(cwd);
+    const rel = path.relative(workspace, realCwd);
+    if (escapes(rel)) throw new Error(`${realCwd} is not inside the workspace ${workspace}`);
+    checkoutCwd = fs.realpathSync.native(path.join(checkoutWorkspace, rel));
+    if (!fs.statSync(checkoutCwd).isDirectory()) throw new Error(`${checkoutCwd} is not a directory`);
+    if (!inside(checkoutCwd, section.checkout)) throw new Error(`${checkoutCwd} is outside the primary checkout ${section.checkout}`);
+  } catch (e) { return refuse("RK_CARGO_BROKER_CWD", `the call's working directory has no counterpart in the primary checkout (${e.message}); the broker runs it where the checkout has it`); }
+  let inputs;
+  try { inputs = readDeclaredInputs(section.snapshot.path); } catch (e) { return refuse("RK_CARGO_BROKER_DECLARED_INPUTS", e.message); }
+  // The environment the client sees: the caller's, without the gate's unbound-sentinel output directory (the broker pins the output).
+  const clientEnv = { ...env };
+  for (const key of Object.keys(clientEnv)) {
+    if (/^(CARGO_TARGET_DIR|CARGO_BUILD_TARGET_DIR)$/i.test(key) && section.sentinel && String(clientEnv[key]).startsWith(section.sentinel)) delete clientEnv[key];
+  }
+  const refDir = fs.mkdtempSync(path.join(tmp, "rk-snapreq-"));
+  let made = null;
+  try {
+    try {
+      made = writeSnapshotRequest({ controlRoot: section.controlRoot, commit: section.commit, snapshot: section.snapshot, declaredInputs: inputs, handle: section.handle, primaryCwd: checkoutCwd, argv: words, requestIdFile: path.join(refDir, "request.json") });
+    } catch (e) { return refuse("RK_CARGO_BROKER_CARRIER", e.message); }
+    try { record({ ...base, status: "pending", nonce: made.carrier.nonce, checkoutCwd }); } catch (e) { fs.rmSync(made.file, { force: true }); return refuse("RK_CARGO_LEDGER_ERROR", `the call cannot be recorded (${e.message}); it does not run`); }
+    const childEnv = { ...clientEnv, ...made.env };
+    const r = spawn(section.client, ["cargo", ...words], { cwd: checkoutCwd, env: childEnv, stdio: "inherit" });
+    fs.rmSync(made.file, { force: true });
+    let outcome;
+    let ref = null;
+    try {
+      if (r.error) throw new SnapshotRequestError("spawn", `the RustRight client did not start (${r.error.message})`);
+      ref = readRequestRef(path.join(refDir, "request.json"));
+      const receipt = receiptSync({ client: section.client, requestId: ref.requestId, env: clientEnv, spawn });
+      const observedEnv = observedEnvOf(clientEnv, section.platform);
+      const { evidence, attribution, toolchain } = verifySnapshotReceipt(receipt, { pins: section.pins, jobId: ref.requestId, carrier: made.carrier, argv: words, workspace: ref.workspace, observedEnv, checkout: section.checkout, outputRoots: section.outputRoots, platform: section.platform });
+      // attribution and toolchain are recorded as the broker signed them (a consumer that needs per-package attribution treats available:false as FAILED).
+      outcome = { status: "verified", requestId: ref.requestId, workspace: ref.workspace, observedEnv, outputDir: evidence.outputDir, treeAtStart: evidence.snapshot.treeAtStart, treeAtExit: evidence.snapshot.treeAtExit, attribution, toolchain };
+    } catch (e) {
+      outcome = { status: "unverified", code: e.code ?? "error", message: e.message, ...(ref ? { requestId: ref.requestId, workspace: ref.workspace } : {}) };
+    }
+    record({ ...base, ...outcome, nonce: made.carrier.nonce, checkoutCwd, clientExit: r.status ?? null });
+    if (outcome.status !== "verified") {
+      err(`rightkit-gate: RK_CARGO_BROKER_UNVERIFIED: \`cargo ${words.join(" ")}\` has no verified signed receipt (${outcome.code}: ${outcome.message}); the scan fails`);
+      return r.status ? r.status : BROKER_REFUSAL_STATUS;
+    }
+    return r.status ?? (r.signal ? 128 : BROKER_REFUSAL_STATUS);
+  } finally {
+    if (made) fs.rmSync(made.file, { force: true });
+    fs.rmSync(refDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * The gate's own check of every ledgered broker call of one scan. A call counts only when the broker's signed receipt, fetched
+ * again now, verifies against THIS gate's commit, snapshot, ownership handle and pins, and its carrier was used once: a nonce or a
+ * request id that appears twice in the run (`seen`) is a replay. Returns the problems; none means every call verified.
+ */
+export async function verifyBrokerLedger(entries, sb, { seen = { nonces: new Set(), ids: new Set() } } = {}) {
+  const problems = [];
+  for (const e of entries) {
+    if (e.mode !== "broker" || e.status !== "verified") continue;
+    const call = `cargo ${(e.argv ?? []).join(" ")}`.trim();
+    try {
+      if (typeof e.nonce !== "string" || typeof e.requestId !== "string" || !Array.isArray(e.argv) || !e.argv.every((a) => typeof a === "string") || typeof e.workspace !== "string" || typeof e.checkoutCwd !== "string") throw new SnapshotRequestError("ledger", "the record is incomplete");
+      if (seen.nonces.has(e.nonce) || seen.ids.has(e.requestId)) throw new SnapshotRequestError("replay", "a carrier or request was used twice; each call carries its own fresh nonce and is used once");
+      seen.nonces.add(e.nonce); seen.ids.add(e.requestId);
+      const workspace = fs.realpathSync.native(e.workspace);
+      if (!inside(workspace, sb.checkout)) throw new SnapshotRequestError("ledger", `the request ran in ${workspace}, outside the primary checkout`);
+      if (fs.realpathSync.native(e.checkoutCwd) !== workspace) throw new SnapshotRequestError("ledger", "the request's working directory is not the one the call recorded");
+      // The gate's own truth: its commit, snapshot, handle and declared inputs; only the call's own argv, nonce and cwd come from the ledger.
+      const carrier = {
+        schema: "rightkit.snapshot-request/1", commit: sb.commit, snapshot: sb.snapshot, declaredInputs: { inputs: readDeclaredInputs(sb.snapshot.path) },
+        ownership: { handle: sb.handle }, primaryCwd: workspace, argvSha256: argvSha256(e.argv), nonce: e.nonce,
+      };
+      const receipt = await sb.receiptOf(e.requestId);
+      verifySnapshotReceipt(receipt, { pins: sb.pins, jobId: e.requestId, carrier, argv: e.argv, workspace: e.workspace, observedEnv: e.observedEnv ?? {}, checkout: sb.checkout, outputRoots: sb.outputRoots, platform: sb.platform });
+    } catch (error) { problems.push(`${call} (from ${e.cwd}): the gate's own verification of the broker's receipt failed (${error.code ?? "error"}: ${error.message})`); }
+  }
+  return problems;
+}

package/snapshot-check.mjs

@@ -78,18 +78,24 @@ export function commitOf(checkout, rev, spawn = defaultSpawn) { // eslint-disabl
 /**
  * The snapshot holds exactly the commit (E6, GATE-CONTRACT §1): no path under it the commit's tree lacks (ignored ones included; the
  * only allowances are snapshot.mjs's named pnpm dependency directories and the gate's config-only .git/config), no link resolving out
- * of it or into the checkout, and the seeded tree id (the broker's method) equal to the commit's tree. Otherwise CheckError.
+ * of it or into the checkout, and the seeded tree id (the broker's method) equal to the commit's tree. Otherwise CheckError. Returns the tree id.
+ *
+ * Stage-output ledger (row 5.09d), the same walk as snapshot.mjs verifySnapshot (one implementation, snapshotProblem): given `ledger`
+ * (the entries an earlier verify returned) and/or `admitNew` (the END of a stage only), the stage's own ignored, untracked outputs
+ * are admitted and the ledger must still match exactly. Then the result is `{ tree, ledger: [{ path, type, size, sha256, execBit }] }`.
  */
-export function verifySnapshotDir({ checkout, dir, commit, tree, when }) {
-  let extra;
-  try { extra = snapshotProblem({ dir, entries: treeEntries(checkout, commit), checkout }); }
+export function verifySnapshotDir({ checkout, dir, commit, tree, when, ledger, admitNew }) {
+  const ledgerMode = ledger !== undefined || admitNew === true;
+  let inspected;
+  try { inspected = snapshotProblem({ dir, entries: treeEntries(checkout, commit), checkout, ledger, admitNew }); }
   catch (e) { throw new CheckError(`cannot list snapshot ${dir} ${when}: ${e.message}`); }
-  if (extra) throw new CheckError(`snapshot ${dir} is not exactly commit ${commit} ${when}: ${extra}`);
+  const extra = ledgerMode ? inspected.problem : inspected;
+  if (extra) throw new CheckError(`snapshot ${dir} is not exactly commit ${commit}${ledgerMode ? " plus its stage-output ledger" : ""} ${when}: ${extra}`);
   let actual;
   try { actual = snapshotTree({ checkout, dir, baseTree: tree }); }
   catch (e) { throw new CheckError(`cannot compute the tree of snapshot ${dir} ${when}: ${e.message}`); }
   if (actual !== tree) throw new CheckError(`snapshot ${dir} is tree ${actual} ${when}, not tree ${tree} of commit ${commit}`);
-  return actual;
+  return ledgerMode ? { tree: actual, ledger: inspected.admitted } : actual;
 }
 
 /** Every file of the commit with its blob id, from the checkout's object database: what the snapshot holds. */

package/snapshot-request.mjs

@@ -35,6 +35,36 @@ export const MANAGED_RUST_ENVIRONMENT_KEYS = Object.freeze([
 ]);
 /** The fields the broker copies onto the receipt and signs in payload.snapshotEvidence (attestation.rs). */
 export const SNAPSHOT_EVIDENCE_FIELDS = Object.freeze(["requestId", "brokerVersion", "executor", "commit", "snapshot", "declaredInputDigests", "ownership", "outputDir"]);
+/** The stage evidence the broker signs in payload.stageEvidence and copies onto the receipt (attestation.rs STAGE_EVIDENCE_FIELDS). */
+export const STAGE_EVIDENCE_FIELDS = Object.freeze(["freshness", "attribution", "toolchain"]);
+const SIGNED_TOP_LEVEL_FIELDS = Object.freeze(["verdict", "refreshed", "exit", "signal", "timingsMs", "diagnosticsPath"]);
+const TIMING_KEYS =Object.freeze(["admission", "queue", "bind", "cargo", "afterExitBind", "diagnostics"]);
+/** `<toolchain>|cargo:<sha256>|rustc:<sha256>` (rustright toolchain_identity). */
+const TOOLCHAIN_FORMAT = /^[^|\s][^|]*\|cargo:[0-9a-f]{64}\|rustc:[0-9a-f]{64}$/;
+
+/** The compile-class cargo commands (and their aliases): the ones whose receipt carries attribution and toolchain. */
+export const COMPILE_CLASS_COMMANDS = Object.freeze(["check", "clippy", "build", "doc", "rustc", "test", "b", "c", "t", "d"]);
+const GLOBAL_VALUE_OPTIONS = new Set(["--color", "--explain"]);
+
+/** The cargo subcommand of an argv (without `cargo`): after an optional `+toolchain` and the global options, before `--`; null when there is none. */
+export function cargoSubcommandOf(argv) {
+  const words = [...argv];
+  for (let i = words[0]?.startsWith("+") ? 1 : 0; i < words.length; i += 1) {
+    const w = words[i];
+    if (w === "--") return null;
+    if (GLOBAL_VALUE_OPTIONS.has(w)) { i += 1; continue; }
+    if (w.startsWith("-")) continue;
+    return w;
+  }
+  return null;
+}
+export const isCompileClass = (argv) => COMPILE_CLASS_COMMANDS.includes(cargoSubcommandOf(argv));
+
+/** Where the gate's declared compile inputs are listed, as read from the snapshot (GATE-CONTRACT "Request"; the broker's COMPILE_INPUTS). */
+export const COMPILE_INPUTS = ".rightkit/compile-inputs.json";
+export const MAX_DECLARATION_BYTES = 1024 * 1024;
+const MAX_INPUT_FILES = 200_000;
+const MAX_INPUT_BYTES = 4 * 1024 * 1024 * 1024;
 
 export class SnapshotRequestError extends Error {
   constructor(code, message) { super(message); this.name = "SnapshotRequestError"; this.code = code; }
@@ -125,11 +155,130 @@ export function readRequestRef(file) {
 
 const same = (a, b) => canonicalJson(a ?? null) === canonicalJson(b ?? null);
 
+// ---- declared compile inputs, read and digested the way the broker does (check_admission.rs declared_inputs / snapshot_inputs) ----
+
+const lstatOrNull = (p) => { try { return fs.lstatSync(p); } catch (e) { if (e.code === "ENOENT") return null; throw e; } };
+
+/**
+ * The declared inputs of a snapshot: `inputs` of `.rightkit/compile-inputs.json` read FROM THE SNAPSHOT, never the checkout. No
+ * manifest means an empty set; a link on its path, a file that is not regular, an oversized or malformed manifest, or an input that
+ * is not a plain relative path (absolute, `.`/`..`, inside `.git`, the manifest itself) is refused before any request is made.
+ */
+export function readDeclaredInputs(snapshotRoot) {
+  const parts = COMPILE_INPUTS.split("/");
+  let at = snapshotRoot; let meta = null;
+  for (const part of parts) {
+    at = path.join(at, part);
+    meta = lstatOrNull(at);
+    if (meta === null) return [];
+    if (meta.isSymbolicLink()) fail("declared-inputs", `${COMPILE_INPUTS} runs through a link at ${at}`);
+  }
+  if (!meta.isFile()) fail("declared-inputs", `${COMPILE_INPUTS} is not a regular file`);
+  if (meta.size > MAX_DECLARATION_BYTES) fail("declared-inputs", `${COMPILE_INPUTS} is larger than ${MAX_DECLARATION_BYTES} bytes`);
+  let value;
+  try { value = JSON.parse(fs.readFileSync(at, "utf8")); } catch (e) { fail("declared-inputs", `${COMPILE_INPUTS} is not JSON (${e.message})`); }
+  if (!value || typeof value !== "object" || !Array.isArray(value.inputs)) fail("declared-inputs", `${COMPILE_INPUTS}: \`inputs\` must be a list of paths`);
+  for (const input of value.inputs) {
+    if (typeof input !== "string" || !input) fail("declared-inputs", `${COMPILE_INPUTS}: every input is a non-empty relative path`);
+    const components = input.split(/[\\/]/);
+    if (path.isAbsolute(input) || path.posix.isAbsolute(input) || path.win32.isAbsolute(input) || components.some((c) => c === "" || c === "." || c === "..")) fail("declared-inputs", `${COMPILE_INPUTS}: ${input} is not a plain relative path inside the snapshot`);
+    if (components.some((c) => c.toLowerCase() === ".git")) fail("declared-inputs", `${COMPILE_INPUTS}: ${input} is inside .git; repository metadata is never a compile input`);
+    if (components.length <= parts.length && components.every((c, i) => c === parts[i])) fail("declared-inputs", `${COMPILE_INPUTS}: ${input} overlaps the declaration file itself`);
+  }
+  return [...value.inputs];
+}
+
+/**
+ * The `declaredInputDigests` the broker records for these inputs, computed here from the snapshot: per input, sha256 over, for each
+ * regular file in directory order (names sorted by their bytes), the file's relative name, a NUL, its bytes and a NUL. A link
+ * anywhere, a special file, or a limit breach is a refusal. Child names are joined with the platform's separator, as the broker's
+ * `Path::join` does.
+ */
+export function declaredInputDigestsOf(snapshotRoot, inputs, { platform = process.platform } = {}) {
+  const sep = platform === "win32" ? "\\" : "/";
+  let files = 0; let bytes = 0;
+  const walk = (full, name, hasher) => {
+    const meta = fs.lstatSync(full);
+    if (meta.isSymbolicLink()) fail("declared-inputs", `declared compile input holds a link at ${name}`);
+    if (meta.isDirectory()) {
+      const children = fs.readdirSync(full).sort((a, b) => Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8")));
+      for (const child of children) walk(path.join(full, child), name.endsWith("/") || name.endsWith("\\") ? `${name}${child}` : `${name}${sep}${child}`, hasher);
+      return;
+    }
+    if (!meta.isFile()) fail("declared-inputs", `declared compile input ${name} is not a regular file or directory`);
+    files += 1;
+    if (files > MAX_INPUT_FILES) fail("declared-inputs", `the declared compile inputs exceed ${MAX_INPUT_FILES} files`);
+    hasher.update(name); hasher.update(Buffer.from([0]));
+    const fd = fs.openSync(full, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+      const after = fs.fstatSync(fd);
+      if (!after.isFile() || (process.platform !== "win32" && (after.dev !== meta.dev || after.ino !== meta.ino))) fail("declared-inputs", `${name} changed while it was read`);
+      const chunk = Buffer.allocUnsafe(64 * 1024);
+      for (;;) {
+        const n = fs.readSync(fd, chunk, 0, chunk.length, null);
+        if (n === 0) break;
+        bytes += n;
+        if (bytes > MAX_INPUT_BYTES) fail("declared-inputs", `the declared compile inputs exceed ${MAX_INPUT_BYTES} bytes`);
+        hasher.update(chunk.subarray(0, n));
+      }
+    } finally { fs.closeSync(fd); }
+    hasher.update(Buffer.from([0]));
+  };
+  return inputs.map((input) => {
+    // Every component of the declared path is walked without following a link.
+    let at = snapshotRoot;
+    for (const part of input.split(/[\\/]/)) {
+      at = path.join(at, part);
+      let meta;
+      try { meta = fs.lstatSync(at); } catch (e) { fail("declared-inputs", `${input}: ${e.message}`); }
+      if (meta.isSymbolicLink()) fail("declared-inputs", `${input} runs through a link at ${at}`);
+    }
+    const hasher = crypto.createHash("sha256");
+    walk(at, input, hasher);
+    return { path: input, sha256: hasher.digest("hex") };
+  });
+}
+
+// ---- the receipt ----
+
+const inside = (child, parent, platform) => {
+  const norm = (p) => (platform === "win32" ? path.win32.resolve(p).toLowerCase() : path.resolve(p));
+  const rel = (platform === "win32" ? path.win32 : path).relative(norm(parent), norm(child));
+  return rel === "" || !(rel === ".." || /^\.\.[\\/]/.test(rel) || path.isAbsolute(rel) || path.win32.isAbsolute(rel));
+};
+
+/**
+ * The generation target the broker pins an app's outputs to: `<root>/<12 hex>/g/<NNN>/target` under one of the managed `ws` roots
+ * (`<external data root>/rightkit-build-control/ws`; BROKER-CONTRACT "Source identity", output pinning). The 12-hex key is
+ * rustright-state's workspace_key, which the gate never computes (the snapshot's own key is `snapshots/<sha256(repo path)[:16]>`, a
+ * different thing); it reads the receipt's outputDir and checks only this shape. The generation number (3+ digits) is the broker's.
+ */
+export function isGenerationTarget(outputDir, outputRoots, platform = process.platform) {
+  const mod = platform === "win32" ? path.win32 : path;
+  for (const root of outputRoots) {
+    const rel = mod.relative(platform === "win32" ? mod.resolve(root).toLowerCase() : mod.resolve(root), platform === "win32" ? mod.resolve(outputDir).toLowerCase() : mod.resolve(outputDir));
+    const segments = rel.split(/[\\/]/);
+    if (segments.length === 4 && segments[0] !== ".." && !mod.isAbsolute(rel) && /^[0-9a-f]{12}$/.test(segments[0]) && segments[1] === "g" && /^[0-9]{3,}$/.test(segments[2]) && segments[3] === "target") return true;
+  }
+  return false;
+}
+
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
 /**
  * Verifies the receipt of one snapshot cargo request. `pins` come from this host's enrollment, never from the receipt.
- * Returns `{ payload, evidence }`; throws ProvenanceError (signature, pins, job, nonce, request) or SnapshotRequestError (evidence).
+ * Returns `{ payload, evidence }`; throws ProvenanceError (legacy, signature, pins, job, nonce, request) or SnapshotRequestError (evidence).
+ *
+ * Beyond the signature, the job, the nonce and the request digest, the receipt must carry (item 7 row 7.22):
+ *   - signed SUCCEEDED with exit 0, and signed snapshotEvidence equal to the receipt's copies (commit, ownership handle, request id,
+ *     snapshot path, `treeAtStart` = `treeAtExit` = the expected tree);
+ *   - `declaredInputDigests` equal to the gate's own digest of the snapshot's declared inputs, read from the snapshot now;
+ *   - `outputDir` absolute, outside the snapshot and the checkout, and a managed generation target under one of `outputRoots`;
+ *   - signed stageEvidence (freshness, attribution, toolchain) equal to the receipt's;
+ *   - verdict, timingsMs, exit, diagnosticsPath, brokerVersion, executor and refreshed present with their types.
+ * `checkout` and `outputRoots` are required: without them nothing can be said about where the outputs went, so it refuses.
  */
-export function verifySnapshotReceipt(receipt, { pins, jobId, carrier, argv, workspace, observedEnv = {}, canonicalPath = (p) => fs.realpathSync.native(p) }) {
+export function verifySnapshotReceipt(receipt, { pins, jobId, carrier, argv, workspace, observedEnv = {}, checkout, outputRoots, platform = process.platform, canonicalPath = (p) => fs.realpathSync.native(p), digestInputs = declaredInputDigestsOf, readInputs = readDeclaredInputs }) {
   const requestDigest = requestDigestOf(snapshotRequestCore({ argv, workspace, observedEnv, carrier }));
   const payload = verifyProvenance(receipt, pins, { jobId, nonce: carrier.nonce, requestDigest });
   // The signed outcome, not the client's exit code: a passing row needs the broker to have signed SUCCEEDED with exit 0 and no
@@ -152,10 +301,63 @@ export function verifySnapshotReceipt(receipt, { pins, jobId, carrier, argv, wor
   try { samePath = canonicalPath(snap.path) === canonicalPath(carrier.snapshot.path); } catch { samePath = false; }
   if (!samePath) fail("evidence", `the signed snapshot ${snap.path} is not ${carrier.snapshot.path}`);
   if (snap.treeAtStart !== carrier.snapshot.expectedTree || snap.treeAtExit !== carrier.snapshot.expectedTree) {
-    fail("evidence", `the snapshot was tree ${snap.treeAtStart} at START and ${snap.treeAtExit} at exit, not ${carrier.snapshot.expectedTree} throughout`);
+    fail("evidence", `the snapshot was tree ${snap.treeAtStart} at START and ${snap.treeAtExit} at exit, not ${carrier.snapshot.expectedTree} throughout: the build changed a tracked file (or added or removed one) in the commit's snapshot, so the result is discarded; that is the app owner's defect to fix (write generated output to an ignored path or an output directory, or generate before commit)`);
+  }
+  // Declared inputs: what the broker digested in place must be what the gate digests in the snapshot, from the same manifest.
+  let gateInputs; let gateDigests;
+  try {
+    gateInputs = readInputs(carrier.snapshot.path);
+    gateDigests = digestInputs(carrier.snapshot.path, gateInputs, { platform });
+  } catch (e) { fail("evidence", `the gate cannot digest the snapshot's declared inputs (${e.message})`); }
+  if (!same(gateInputs, carrier.declaredInputs?.inputs)) fail("evidence", "the snapshot's declared inputs are not the ones this request carried");
+  if (!same(evidence.declaredInputDigests, gateDigests)) fail("evidence", "the signed declaredInputDigests are not the gate's own digest of the snapshot's declared inputs");
+  // Output directory: where the outputs went must be the broker's managed generation target, never under the snapshot or the checkout.
+  const out = evidence.outputDir;
+  if (typeof out !== "string" || !path.isAbsolute(out) && !path.win32.isAbsolute(out)) fail("evidence", "the signed evidence names no absolute output directory");
+  if (!checkout || !path.isAbsolute(checkout) || !Array.isArray(outputRoots) || outputRoots.length === 0) fail("evidence", "the gate has no checkout or managed output root to judge the output directory against");
+  const canon = (p) => { try { return canonicalPath(p); } catch { return p; } };
+  if (inside(out, carrier.snapshot.path, platform) || inside(out, canon(carrier.snapshot.path), platform)) fail("evidence", `the output directory ${out} is inside the snapshot`);
+  if (inside(out, checkout, platform) || inside(out, canon(checkout), platform)) fail("evidence", `the output directory ${out} is inside the checkout`);
+  if (!isGenerationTarget(out, outputRoots, platform)) fail("evidence", `the output directory ${out} is not a managed generation target (<ws root>/<repo-key>/g/<generation>/target) under ${outputRoots.join(", ")}`);
+  // Stage evidence is signed with the rest and must equal the receipt's copy. `freshness` is required for every carried command;
+  // `attribution` and `toolchain` only for a compile-class command (check, clippy, build, doc, rustc, test: the broker emits them
+  // for compiles only), so metadata, fetch --locked, fmt --check or tree --locked pass without them. When either side carries one
+  // anyway, both must carry the same value.
+  const stage = payload.stageEvidence;
+  if (!isObject(stage)) fail("evidence", "the signed payload carries no stageEvidence");
+  const compile = isCompileClass(argv);
+  for (const name of STAGE_EVIDENCE_FIELDS) {
+    const signed = stage[name] ?? null; const copy = receipt[name] ?? null;
+    const required = name === "freshness" || compile;
+    if (required && (signed === null || copy === null)) fail("evidence", `${name} is missing from the signed stage evidence or the receipt${name === "freshness" ? "" : ` (a compile-class command, cargo ${cargoSubcommandOf(argv)}, carries it)`}`);
+    if (!same(copy, signed)) fail("evidence", `receipt ${name} differs from the signed stage evidence`);
+  }
+  // Shapes RustRight emits (item 4 row 4.18): attribution is `{available, ...}`, and an unavailable one names its reason
+  // (`cargo-json-message-format-not-requested` without a JSON message stream; a consumer that needs per-package attribution treats
+  // `available:false` as FAILED, not partial); toolchain is `<toolchain>|cargo:<sha256>|rustc:<sha256>`.
+  const attribution = receipt.attribution ?? null; const toolchain = receipt.toolchain ?? null;
+  if (attribution !== null) {
+    if (!isObject(attribution) || typeof attribution.available !== "boolean") fail("evidence", "receipt attribution is not {available, ...}");
+    if (attribution.available === false && !(typeof attribution.reason === "string" && attribution.reason !== "")) fail("evidence", "receipt attribution is unavailable and names no reason");
+  }
+  if (toolchain !== null && !(typeof toolchain === "string" && TOOLCHAIN_FORMAT.test(toolchain))) fail("evidence", "receipt toolchain is not <toolchain>|cargo:<sha256>|rustc:<sha256>");
+  // Fields the signature does not cover must still be present with their types (the consumer reads them). Every carried command:
+  // verdict, refreshed, exit (an integer, or null with a signal) and signal, timingsMs{admission, queue, bind, cargo, afterExitBind,
+  // diagnostics} (each a number or null) and diagnosticsPath (a path, or null). Success needs exit 0 and no signal, as signed.
+  const timingsOk = isObject(receipt.timingsMs) && TIMING_KEYS.every((k) => Object.hasOwn(receipt.timingsMs, k) && (receipt.timingsMs[k] === null || Number.isFinite(receipt.timingsMs[k])));
+  const typed = [
+    ["verdict", isObject(receipt.verdict)], ["timingsMs", timingsOk], ["exit", receipt.exit === null || Number.isSafeInteger(receipt.exit)],
+    ["signal", receipt.signal === null || typeof receipt.signal === "string" || Number.isSafeInteger(receipt.signal)],
+    ["diagnosticsPath", receipt.diagnosticsPath === null || (typeof receipt.diagnosticsPath === "string" && receipt.diagnosticsPath !== "")], ["brokerVersion", typeof receipt.brokerVersion === "string" && receipt.brokerVersion !== ""],
+    ["executor", typeof receipt.executor === "string" && receipt.executor !== ""], ["refreshed", Array.isArray(receipt.refreshed)],
+  ];
+  for (const [name, ok] of typed) if (!ok) fail("evidence", `receipt ${name} is missing or has the wrong type`);
+  if (receipt.exit !== 0 || receipt.signal !== null) fail("evidence", `receipt exit ${receipt.exit} and signal ${receipt.signal} are not a success (exit 0, no signal)`);
+  // RustRight signs these top-level fields in the payload (item 4 row 4.18): when the signed payload carries one, the receipt's copy must equal it.
+  for (const name of SIGNED_TOP_LEVEL_FIELDS) {
+    if (payload[name] !== undefined && !same(receipt[name], payload[name])) fail("evidence", `receipt ${name} differs from the signed payload`);
   }
-  if (typeof evidence.outputDir !== "string" || !path.isAbsolute(evidence.outputDir)) fail("evidence", "the signed evidence names no absolute output directory");
-  return { payload, evidence };
+  return { payload, evidence, attribution, toolchain };
 }
 
 export { ProvenanceError };