@rightkit/release 0.6.7 → 0.6.10

package/snapshot-check.mjs

@@ -0,0 +1,306 @@
+// Snapshot-aware Class A (joint plan step 2; docs/GATE-CONTRACT.md §1 "Broker interface", E17, E18; rightkit#1257).
+//
+// `rightkit-gate check --commit <sha> --full-a --snapshot <dir>` judges the gate-owned snapshot of a selected commit: the checkout
+// is only where the commit and its objects come from (cwd), never what is checked. Its HEAD and status are not read. The snapshot is
+// verified to be exactly the commit's tree (seeded identity, snapshot.mjs) before and after the check; a mismatch or an error is
+// RK_CHECK_ERROR, exit 2.
+//
+// Dependencies for the checks that execute repository code (tests, typecheck, lint) are installed INTO the snapshot from the commit's
+// lockfile (coordinator decision A, recorded in decisions.md with rightkit#1257): the pinned pnpm, `--offline --frozen-lockfile
+// --ignore-scripts --ignore-pnpmfile`, and the store the primary checkout's own install recorded (its node_modules/.modules.yaml
+// storeDir), resolved before any cwd change. No new store, no network, no code of the live checkout. A store miss is RK_CHECK_ERROR
+// naming the package and root, never a skipped check. The next exact sync prunes this install.
+//
+// `rightkit-gate live-scans --repo <root>` re-runs only the live remote scans (pnpm-audit, per pnpm root) and answers the broker's
+// parser (rustright verdict_reuse.rs parse_live_scans): one JSON line, exit 0 when every scan passed, 1 otherwise.
+//
+// A red full Class A whose every failure is deterministic prints `rightkit-gate: verdict deterministic failed=<ids> env=<digest>`;
+// a timeout, a missing tool, a fetch or lease problem, a cancellation, a deferral, or any live scan among the failures prints none.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { LIVE_SCAN_IDS, defaultSpawn, isLiveScan, isRegistryScan, launchGuardEnv, planScans, runScans } from "./deterministic-scans.mjs";
+import { compileLaunch } from "./class-a-launch-guard.mjs";
+import { SnapshotError, isInside, snapshotProblem, snapshotTree, treeEntries } from "./snapshot.mjs";
+import { discoveryRun, sealedRun } from "./snapshot-git.mjs";
+
+export const CHECK_ERROR = "RK_CHECK_ERROR";
+export const LIVE_SCANS_SCHEMA = "rightkit.live-scans/1";
+export const DETERMINISTIC_MARKER = "rightkit-gate: verdict deterministic";
+
+/** Failure codes a re-run of the same inputs reproduces: an exit of the check itself, its own findings, a test summary problem. */
+const DETERMINISTIC_CODES = new Set(["EXIT", "RUN_SCRIPT_TOO_LARGE", "NO_TESTS", "ALL_SKIPPED", "SUMMARY_FAILED", "NO_TEST_SUMMARY"]);
+
+export class CheckError extends Error {
+  constructor(message) { super(message); this.code = CHECK_ERROR; }
+}
+
+const text = (r) => String(r?.stdout ?? "");
+const failed = (r) => !r || Boolean(r.error) || r.status !== 0;
+const tail = (r) => `${r?.stderr ?? ""}\n${r?.stdout ?? ""}`.trim().split(/\r?\n/).slice(-6).join(" | ").slice(-600);
+// A path is outside only as `..`, `..<sep>…` or absolute: a sibling named `..x` is inside (snapshot.mjs isInside; review item5-r2 #4).
+const inside = (child, parent) => isInside(child, parent, path);
+
+/** The `--snapshot <dir>` of a check: absolute, an existing real directory, not inside the checkout and not holding it. */
+export function snapshotOption(args, { checkout }) {
+  const i = args.indexOf("--snapshot");
+  if (i < 0) return null;
+  const dir = args[i + 1];
+  if (!dir || dir.startsWith("--")) throw new CheckError("check --snapshot needs a directory");
+  if (!path.isAbsolute(dir)) throw new CheckError(`check --snapshot needs an absolute directory, not ${JSON.stringify(dir)}`);
+  if (!args.includes("--full-a") || !args.includes("--commit")) throw new CheckError("check --snapshot is full class A of a selected commit: it needs --commit <sha> and --full-a");
+  if (args.includes("--worktree")) throw new CheckError("check --snapshot never checks the working tree: drop --worktree");
+  let st;
+  try { st = fs.lstatSync(dir); } catch { throw new CheckError(`snapshot ${dir} does not exist`); }
+  if (!st.isDirectory()) throw new CheckError(`snapshot ${dir} is not a directory (a link is never followed)`);
+  const real = fs.realpathSync.native(dir);
+  if (inside(real, checkout) || inside(checkout, real)) throw new CheckError(`snapshot ${real} and checkout ${checkout} overlap`);
+  return real;
+}
+
+/**
+ * `{ commit, tree }` of a revision in the checkout's object database. The sealed invocation (snapshot-git.mjs, item 5 D3): the
+ * revision is resolved under the sealed environment with replace refs off, so a replace ref cannot change what <sha>^{tree} means.
+ * `spawn` is accepted for the callers that still pass one and is not used: the gate's identity git never goes through an injected runner.
+ */
+export function commitOf(checkout, rev, spawn = defaultSpawn) { // eslint-disable-line no-unused-vars
+  const name = String(rev ?? "");
+  if (!name || name.startsWith("-") || name.includes("\0")) throw new CheckError(`commit ${name} does not resolve in ${checkout}`);
+  const c = discoveryRun(checkout, ["rev-parse", "--verify", "--quiet", `${name}^{commit}`]);
+  if (failed(c)) throw new CheckError(`commit ${name} does not resolve in ${checkout}`);
+  const commit = text(c).trim();
+  const t = discoveryRun(checkout, ["rev-parse", "--verify", "--quiet", `${commit}^{tree}`]);
+  if (failed(t)) throw new CheckError(`commit ${commit} has no tree`);
+  return { commit, tree: text(t).trim() };
+}
+
+/**
+ * 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.
+ */
+export function verifySnapshotDir({ checkout, dir, commit, tree, when }) {
+  let extra;
+  try { extra = snapshotProblem({ dir, entries: treeEntries(checkout, commit), checkout }); }
+  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}`);
+  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;
+}
+
+/** Every file of the commit with its blob id, from the checkout's object database: what the snapshot holds. */
+export function commitFiles(checkout, commit, spawn = defaultSpawn) { // eslint-disable-line no-unused-vars
+  const r = sealedRun(checkout, ["ls-tree", "-r", "-z", "--full-tree", commit]);
+  if (failed(r)) throw new CheckError(`cannot list commit ${commit}: ${tail(r)}`);
+  const ids = new Map();
+  for (const record of text(r).split("\0").filter(Boolean)) {
+    const tab = record.indexOf("\t");
+    ids.set(record.slice(tab + 1), record.slice(0, tab).split(" ")[2]);
+  }
+  const files = [...ids.keys()].sort();
+  const digestOf = (list) => crypto.createHash("sha256").update(list.map((f) => `${f}\t${ids.get(f)}\n`).join("")).digest("hex");
+  return { files, ids, digestOf, digest: digestOf(files) };
+}
+
+/** `storeDir` from a node_modules/.modules.yaml: pnpm writes `"storeDir": "<JSON string>"` (Windows paths escaped, `D:\\x`) or `storeDir: <abs>`. */
+export function modulesStoreDir(yamlText) {
+  const src = String(yamlText ?? "");
+  const quoted = /^\s*"?storeDir"?\s*:\s*("(?:[^"\\\n]|\\.)*")\s*,?\s*$/m.exec(src);
+  if (quoted) { try { return JSON.parse(quoted[1]); } catch { return null; } }
+  const bare = /^\s*storeDir\s*:\s*([^"'\s][^\n]*?)\s*$/m.exec(src);
+  return bare ? bare[1].trim() : null;
+}
+
+/**
+ * The existing warm store a pnpm root of the PRIMARY checkout installs from: the storeDir its own install recorded (the root's
+ * node_modules/.modules.yaml, else the repository root's), else what `pnpm store path` answers in that root with the primary
+ * environment. It must be an absolute directory that exists; nothing is created.
+ */
+export function resolvePrimaryStore({ checkout, root = ".", env = process.env, spawn = defaultSpawn, readFile = (f) => fs.readFileSync(f, "utf8"), exists = fs.existsSync }) {
+  const candidates = [...new Set([path.join(checkout, root, "node_modules", ".modules.yaml"), path.join(checkout, "node_modules", ".modules.yaml")])];
+  for (const file of candidates) {
+    let dir = null;
+    try { dir = modulesStoreDir(readFile(file)); } catch { dir = null; }
+    if (dir && path.isAbsolute(dir) && exists(dir)) return { storeDir: dir, source: path.relative(checkout, file).split(path.sep).join("/") };
+  }
+  const r = spawn("pnpm", ["store", "path"], { cwd: path.join(checkout, root), env: { ...env, COREPACK_ENABLE_AUTO_PIN: "0" } });
+  const dir = failed(r) ? null : text(r).trim().split(/\r?\n/).pop();
+  if (dir && path.isAbsolute(dir) && exists(dir)) return { storeDir: dir, source: "pnpm store path (primary checkout)" };
+  throw new CheckError(`no existing pnpm store for root ${root} of ${checkout}: its install recorded none and \`pnpm store path\` answered ${dir ? JSON.stringify(dir) : tail(r) || "nothing"}; install the checkout's dependencies once, then run the check again`);
+}
+
+/** The pnpm version a root pins (`packageManager: pnpm@x.y.z`, its own package.json or the repository root's), or null. */
+export function pinnedPnpm(dir, { readFile = (f) => fs.readFileSync(f, "utf8") } = {}) {
+  try { const pm = JSON.parse(readFile(path.join(dir, "package.json"))).packageManager; const m = /^pnpm@(\d+\.\d+\.\d+)/.exec(String(pm ?? "")); return m ? m[1] : null; } catch { return null; }
+}
+
+/** Dependencies whose install scripts the repository allows (pnpm-workspace.yaml `allowBuilds: { name: true }`, `onlyBuiltDependencies`). */
+export function allowedBuilds(dir, { readFile = (f) => fs.readFileSync(f, "utf8") } = {}) {
+  const names = new Set();
+  let ws = "";
+  try { ws = readFile(path.join(dir, "pnpm-workspace.yaml")); } catch { ws = ""; }
+  const block = (key) => { const m = new RegExp(`^${key}:\\s*\\n((?:[ \\t]+.*\\n?|\\s*#.*\\n?|\\s*\\n)*)`, "m").exec(ws); return m ? m[1] : ""; };
+  for (const line of block("allowBuilds").split("\n")) { const m = /^\s+['"]?([^'":#\s]+)['"]?\s*:\s*true\b/.exec(line); if (m) names.add(m[1]); }
+  for (const line of block("onlyBuiltDependencies").split("\n")) { const m = /^\s+-\s+['"]?([^'"#\s]+)['"]?/.exec(line); if (m) names.add(m[1]); }
+  try { for (const n of JSON.parse(readFile(path.join(dir, "package.json"))).pnpm?.onlyBuiltDependencies ?? []) names.add(n); } catch { /* none */ }
+  return [...names].sort();
+}
+
+/**
+ * A dependency whose install script the repository allows but `--ignore-scripts` skipped must be shown usable without it, never
+ * assumed: its own bin runs with `--version`, or, with no bin, the package loads in a fresh node. The probe runs before class A is
+ * green, so it runs under the class A launch guard (launchGuardEnv): it can never start a compile; a refused launch fails the probe.
+ * A package that is itself a compile tool the guard lists (esbuild) is never launched here: class A cannot launch it either, so its
+ * usability is proven where it is launched, after class A, and it is recorded as such. A package the root does not have installed is
+ * not required. Returns [{ name, version, probe, result }]; throws CheckError naming the package and root when one is installed but
+ * not usable.
+ */
+export function probeSkippedBuilds({ dir, root, names, spawn = defaultSpawn, env = process.env, node = process.execPath }) {
+  const results = [];
+  const store = path.join(dir, "node_modules", ".pnpm");
+  let entries = [];
+  try { entries = fs.readdirSync(store); } catch { entries = []; }
+  for (const name of names) {
+    const flat = name.replace("/", "+");
+    for (const entry of entries.filter((e) => e.startsWith(`${flat}@`)).sort()) {
+      const pkgDir = path.join(store, entry, "node_modules", ...name.split("/"));
+      let manifest;
+      try { manifest = JSON.parse(fs.readFileSync(path.join(pkgDir, "package.json"), "utf8")); } catch { continue; }
+      const bins = typeof manifest.bin === "string" ? { [name.split("/").pop()]: manifest.bin } : (manifest.bin ?? {});
+      const binName = Object.keys(bins).find((b) => b === name.split("/").pop()) ?? Object.keys(bins)[0];
+      const compiler = compileLaunch(name.split("/").pop()) ?? (binName ? compileLaunch(binName) : null);
+      if (compiler) { results.push({ name, version: manifest.version, probe: "none", result: `compile tool (${compiler}): class A never launches it; its usability is proven where it is launched, after class A` }); continue; }
+      const probe = binName ? [path.join(pkgDir, bins[binName]), "--version"] : ["-e", `require(${JSON.stringify(pkgDir)})`];
+      const r = spawn(node, probe, { cwd: dir, env: { ...env, ...launchGuardEnv(env) }, boundedMs: 60_000 });
+      const out = text(r).trim().split(/\r?\n/).pop() ?? "";
+      if (failed(r)) {
+        const refused = `${r?.stderr ?? ""}\n${r?.stdout ?? ""}`.split(/\r?\n/).find((l) => l.includes("class A refuses a compile/emit launch"));
+        const why = refused ? `it launched a compile, which the class A launch guard refused: ${refused.replace(/^rightkit-gate: /, "").trim()}` : (tail(r) || r?.error?.message || `exit ${r?.status}`);
+        throw new CheckError(`root ${root}: ${name}@${manifest.version} needs its install script (allowed by the repository, not run under --ignore-scripts) and is not usable without it: ${binName ? `${binName} --version` : "require"} failed: ${why}`);
+      }
+      results.push({ name, version: manifest.version, probe: binName ? `${binName} --version` : "require", result: out || "loaded" });
+    }
+  }
+  return results;
+}
+
+/**
+ * Installs each pnpm root's dependencies into the snapshot from the commit's lockfile and the primary checkout's existing store.
+ * Returns one record per root ({ root, storeDir, storeSource, pnpm, lockfileSha256, ms, allowedBuildsNotRun }); throws CheckError on a
+ * store miss, a pnpm that is not the pinned one, or any install failure.
+ */
+export function installSnapshotDependencies({ checkout, snapshot, roots, env = process.env, spawn = defaultSpawn, now = () => Date.now(), readFile, exists, probe = probeSkippedBuilds }) {
+  const records = [];
+  const versionOf = (cwd) => { const r = spawn("pnpm", ["--version"], { cwd, env: { ...env, COREPACK_ENABLE_AUTO_PIN: "0" } }); return failed(r) ? null : text(r).trim().split(/\r?\n/).pop(); };
+  for (const root of roots) {
+    const dir = path.join(snapshot, root);
+    // No lockfile: nothing to install from. Not an error here: the pnpm-lockfile scan judges it, and checks that need dependencies fail.
+    if (!fs.existsSync(path.join(dir, "pnpm-lock.yaml"))) { records.push({ root, skipped: "no pnpm-lock.yaml in the commit: nothing to install from (the pnpm-lockfile scan judges it)" }); continue; }
+    const { storeDir, source } = resolvePrimaryStore({ checkout, root, env, spawn, ...(readFile ? { readFile } : {}), ...(exists ? { exists } : {}) });
+    const pin = pinnedPnpm(dir) ?? pinnedPnpm(snapshot);
+    // Asked where the install runs: pnpm switches itself to the root's packageManager version there (Dell 2026-10-29: an installed
+    // 11.24.0 answers 11.24.0 in a neutral directory and runs 11.25.0 in the root), so that is the pnpm that will install.
+    const version = versionOf(dir);
+    if (!version) throw new CheckError("pnpm is not runnable on this host; the snapshot's dependencies cannot be installed");
+    if (pin && version !== pin) throw new CheckError(`pnpm ${version} is on PATH, but root ${root} of the commit pins pnpm@${pin} (packageManager); install the pinned pnpm`);
+    const started = now();
+    // The virtual store is pinned inside the snapshot and the global virtual store off, whatever the host's pnpm config says: the
+    // install writes nowhere but the snapshot (links to the existing store's content are the only reads outside it).
+    const r = spawn("pnpm", ["install", "--offline", "--frozen-lockfile", "--ignore-scripts", "--ignore-pnpmfile", "--store-dir", storeDir, "--virtual-store-dir", "node_modules/.pnpm", "--config.enable-global-virtual-store=false", "--reporter", "append-only"], {
+      cwd: dir, env: { ...env, COREPACK_ENABLE_AUTO_PIN: "0", CI: "true" }, maxBuffer: 1 << 28,
+    });
+    const ms = now() - started;
+    if (failed(r)) {
+      const out = `${r?.stdout ?? ""}\n${r?.stderr ?? ""}`;
+      const miss = /ERR_PNPM_NO_OFFLINE_TARBALL[^\n]*?(https?:\/\/\S+?\/-\/(\S+?)\.tgz)/.exec(out);
+      if (miss) throw new CheckError(`root ${root}: ${miss[2]} is missing from the store ${storeDir} (offline install, no network fallback); install the checkout's dependencies so the store holds it, then run the check again`);
+      throw new CheckError(`root ${root}: offline dependency install failed (store ${storeDir}): ${tail(r) || r?.error?.message || `exit ${r?.status}`}`);
+    }
+    const lockfileSha256 = crypto.createHash("sha256").update(fs.readFileSync(path.join(dir, "pnpm-lock.yaml"))).digest("hex");
+    const skipped = probe ? probe({ dir, root, names: allowedBuilds(dir), spawn, env }) : [];
+    records.push({ root, storeDir, storeSource: source, pnpm: version, pinned: pin, lockfileSha256, ms, allowedBuildsNotRun: skipped });
+  }
+  return records;
+}
+
+/** One line per installed root, for the check's output and evidence. */
+export function describeInstall(record) {
+  if (record.skipped) return `snapshot dependencies root=${record.root} not installed: ${record.skipped}`;
+  return `snapshot dependencies root=${record.root} pnpm=${record.pnpm}${record.pinned ? ` (pinned ${record.pinned})` : ""} store=${record.storeDir} (from ${record.storeSource}) lockfile=sha256:${record.lockfileSha256} ms=${record.ms}${record.allowedBuildsNotRun.length ? ` build-scripts-not-run=${record.allowedBuildsNotRun.map((b) => (b.probe === "none" ? `${b.name}@${b.version}(deferred, not proven here: ${b.result})` : `${b.name}@${b.version}(usable: ${b.probe} -> ${b.result})`)).join(",")}` : ""}`;
+}
+
+/** The deterministic-red marker for a failed run, or null when any failure is not one a re-run of the same inputs reproduces. */
+export function deterministicMarker(scanResult, env) {
+  const failing = scanResult.scans.filter((r) => r.status !== "pass");
+  if (!failing.length || !env) return null;
+  // A fail row with no code is a scan's own findings (an internal check's list); every other code names why it could not judge.
+  const eligible = failing.every((r) => r.status === "fail" && !isLiveScan(r.id) && !isRegistryScan(r.id) && (r.code === undefined || r.code === null || DETERMINISTIC_CODES.has(r.code)));
+  return eligible ? `${DETERMINISTIC_MARKER} failed=${failing.map((r) => r.id).join(",")} env=${env}` : null;
+}
+
+/** Repository-relative files under `root`: git's view when `root` is a work tree's top level, else a walk (no node_modules, no .git). */
+export function rootFiles(root, spawn = defaultSpawn) {
+  const top = spawn("git", ["rev-parse", "--show-toplevel"], { cwd: root });
+  if (!failed(top) && path.resolve(text(top).trim()) === path.resolve(root)) {
+    const r = spawn("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], { cwd: root, maxBuffer: 1 << 30 });
+    if (!failed(r)) return text(r).split("\0").filter(Boolean).map((f) => f.split(path.sep).join("/"));
+  }
+  // No git (a gate-owned snapshot): list what git would, a link as one entry (never followed into), and only real directories
+  // entered. A link must land, physically, inside the root on a file; one that leaves it (or dangles) stops the listing rather than
+  // silently dropping what it names (a committed apps/web/package.json -> ../../data/web.json is a manifest the audit must see).
+  const realRoot = fs.realpathSync.native(root);
+  const out = [];
+  const walk = (d, rel) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      if (e.name === "node_modules" || e.name === ".git") continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      const p = path.join(d, e.name);
+      if (e.isSymbolicLink()) {
+        let real = null;
+        try { real = fs.realpathSync.native(p); } catch { real = null; }
+        if (!real || !inside(real, realRoot)) throw new CheckError(`${r} is a link that does not land inside ${root}; the live scans cannot list the tree safely`);
+        if (fs.statSync(real).isFile()) out.push(r);
+      } else if (e.isDirectory()) walk(p, r);
+      else if (e.isFile()) out.push(r);
+    }
+  };
+  walk(root, "");
+  return out.sort();
+}
+
+/**
+ * `rightkit-gate live-scans --repo <root>`: the live remote scans of the tree at <root>, planned exactly as the full check plans them
+ * (planScans, all files changed) and run through the same runner. `deps` supplies the gate's unit discovery.
+ */
+export async function liveScansCommand(o, args, { discoverPnpmRoots, discoverNpmUnits, plan = planScans, run = runScans }) {
+  const i = args.indexOf("--repo");
+  if (i < 0 || !args[i + 1] || args[i + 1].startsWith("--") || args.length !== 2) { o.err("rightkit-gate: live-scans takes exactly --repo <checked tree root>"); return 2; }
+  const root = path.resolve(o.cwd, args[i + 1]);
+  let scans;
+  try {
+    const files = rootFiles(root, o.spawn);
+    const tracked = (name) => files.filter((f) => f === name || f.endsWith(`/${name}`));
+    const readFile = (f) => o.readFile(f);
+    const npmRoots = discoverPnpmRoots({ root, tracked, exists: o.exists });
+    const npmUnits = discoverNpmUnits({ root, tracked, readFile, exists: o.exists });
+    const full = plan({ changed: files, contentRoot: root, liveRoot: root, trustedRoot: root, includeTests: false, rustUnits: [], npmUnits, npmRoots, tier: "release", exists: o.exists, readFile: o.readFile, platform: o.platform });
+    const live = { ...full, scans: full.scans.filter((s) => isLiveScan(s.id)), deferred: [] };
+    // A tree with a pnpm lockfile always owes a live audit: planning none there is a listing or planning failure, never an empty pass.
+    const lockfiles = files.filter((f) => /(^|\/)pnpm-lock\.yaml$/.test(f));
+    if (lockfiles.length && !live.scans.length) throw new Error(`the tree holds ${lockfiles.join(", ")} but no live scan was planned; refusing to answer an empty refresh`);
+    const result = await run(live, { classes: ["A"], jobs: 2 });
+    scans = result.scans.map((r) => ({ id: r.id, status: r.status === "pass" ? "passed" : "failed", ...(r.status === "pass" ? {} : { detail: String(r.detail ?? r.status).slice(0, 300) }) }));
+  } catch (e) {
+    o.err(`rightkit-gate: live-scans could not run: ${e.message}`);
+    return 2;
+  }
+  o.out(JSON.stringify({ schema: LIVE_SCANS_SCHEMA, scans: scans.map(({ id, status }) => ({ id, status })) }));
+  for (const s of scans) if (s.status === "failed") o.err(`rightkit-gate: live scan ${s.id} failed: ${s.detail}`);
+  return scans.every((s) => s.status === "passed") ? 0 : 1;
+}
+
+export { LIVE_SCAN_IDS, SnapshotError };

package/snapshot-git.mjs

@@ -0,0 +1,166 @@
+// The sealed git invocation of the gate (item 5 D3, signed/item5-sage-decisions-2.md; docs/GATE-CONTRACT.md §1 "exact snapshot",
+// rightkit#1255). The snapshot's identity and every object read the gate makes depend on the commit's objects and the snapshot's
+// bytes ONLY. The checkout's git configuration cannot reach them: no `filter.*` clean or smudge driver, no core.autocrlf or eol
+// conversion, no attributes from the checkout's `.git/info/attributes` or any attributes file, no hooks, no system, global or user
+// configuration, no replace refs, no inherited GIT_* variable. (Probes P3a to P3d of the decision: today's unsealed invocation ran a
+// checkout filter and hid a byte tamper and a line-ending tamper behind the commit's own id.)
+//
+// ONE runner serves every identity operation: `<sha>^{tree}`, `ls-tree`, `cat-file --batch`, `read-tree`, `add -A`, `write-tree` and
+// the 5.09d ignore oracle (`check-ignore`). Only resolving a revision NAME to a commit runs against the checkout's own git directory
+// (it needs the refs), under the same environment plus GIT_NO_REPLACE_OBJECTS (`discoveryGit`).
+//
+// The private git directory T (mkdtemp, mode 0700, outside the checkout and the snapshot, removed afterwards) holds:
+//   HEAD `ref: refs/heads/none`; an empty refs/; objects/info/alternates naming `<checkout git common dir>/objects` (so every read is
+//   still against the checkout's object database, and every object `add` and `write-tree` writes lands in T, never in the
+//   checkout); `config` with only core.repositoryformatversion and core.bare (plus extensions.objectFormat for SHA-256);
+//   info/attributes SEALED_ATTRIBUTES (the highest-precedence attribute source); an empty info/exclude (so the only ignore rules are
+//   the commit's own `.gitignore` files); an empty hooks/; an empty file `empty`.
+// The environment is built from nothing (sealedEnv). The `-c` flags are SEALED_CONFIG, in this order (sealedConfigArgs).
+//
+// The exact flags live in SEALED_GIT, one frozen constant: the broker (rustright check_admission.rs `sealed_git()`) implements the
+// identical invocation, and the three-way compare of row 5.11 cites this constant.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "./background-process.mjs";
+
+/** info/attributes of T, the highest-precedence attribute source: nothing converts, rewrites, identifies or re-encodes a byte. */
+export const SEALED_ATTRIBUTES = "* -text -ident -filter -working-tree-encoding !eol\n";
+
+/** The `-c key=value` list, in order. `@FILEMODE` is true on darwin and linux and false on win32 (NTFS has no exec bit: a 100755 lives in the seeded index, signed 5.04); `@T/x` is T/x. */
+export const SEALED_CONFIG = Object.freeze([
+  ["core.autocrlf", "false"], ["core.safecrlf", "false"], ["core.eol", "lf"],
+  ["core.fileMode", "@FILEMODE"], ["core.symlinks", "true"],
+  ["core.ignoreCase", "false"], ["core.precomposeUnicode", "false"],
+  ["core.attributesFile", "@T/empty"], ["core.excludesFile", "@T/empty"], ["core.hooksPath", "@T/hooks"],
+  ["core.fsmonitor", "false"], ["core.untrackedCache", "false"], ["core.splitIndex", "false"],
+  ["core.sparseCheckout", "false"], ["index.sparse", "false"], ["core.useReplaceRefs", "false"],
+].map((pair) => Object.freeze(pair)));
+
+/** Environment variables the invocation sets to a fixed value; the others (PATH, HOME, XDG_CONFIG_HOME, LC_ALL, GIT_CONFIG_GLOBAL, GIT_INDEX_FILE, GIT_DIR, GIT_WORK_TREE, and on Windows SystemRoot, WINDIR, PATHEXT, TEMP, TMP) are built by sealedEnv. */
+export const SEALED_ENV_FIXED = Object.freeze({
+  GIT_CONFIG_NOSYSTEM: "1", GIT_ATTR_NOSYSTEM: "1", GIT_NO_REPLACE_OBJECTS: "1", GIT_NO_LAZY_FETCH: "1", GIT_TERMINAL_PROMPT: "0", GIT_OPTIONAL_LOCKS: "0",
+});
+
+/** The sealed invocation, whole: what the three-way compare (5.11) and the broker's `sealed_git()` cite. */
+export const SEALED_GIT = Object.freeze({
+  attributes: SEALED_ATTRIBUTES,
+  config: SEALED_CONFIG,
+  envFixed: SEALED_ENV_FIXED,
+  envBuilt: Object.freeze(["PATH", "HOME", "XDG_CONFIG_HOME", "LC_ALL", "GIT_CONFIG_GLOBAL", "GIT_INDEX_FILE", "GIT_DIR", "GIT_WORK_TREE", "SystemRoot", "WINDIR", "PATHEXT", "TEMP", "TMP"]),
+  layout: Object.freeze({ head: "ref: refs/heads/none\n", alternates: "<git common dir>/objects", excludeIsEmpty: true, hooksIsEmpty: true, workingDirectory: "the snapshot" }),
+  gitVersionNote: "GIT_NO_LAZY_FETCH needs git 2.45 or later; older git ignores it",
+});
+
+const MAX_BUFFER = 1 << 30;
+const WINDOWS_ENV = ["SystemRoot", "WINDIR", "PATHEXT"];
+
+/** `-c k=v ...` for T and `platform`, in SEALED_CONFIG's order. */
+export function sealedConfigArgs(T, platform = process.platform) {
+  const out = [];
+  for (const [key, value] of SEALED_CONFIG) {
+    const v = value === "@FILEMODE" ? (platform === "win32" ? "false" : "true") : value.startsWith("@T/") ? path.join(T, value.slice(3)) : value;
+    out.push("-c", `${key}=${v}`);
+  }
+  return out;
+}
+
+const fromEnv = (base, name) => { const k = Object.keys(base).find((x) => x.toLowerCase() === name.toLowerCase()); return k === undefined ? undefined : base[k]; };
+
+/** The environment for git: built from nothing, never inherited. `T` is the private git directory (or the discovery home), `snapshot` the work tree. */
+export function sealedEnv(T, { snapshot, platform = process.platform, base = process.env, gitDir = T, index = true } = {}) {
+  const env = {};
+  const p = fromEnv(base, "PATH");
+  if (p !== undefined) env.PATH = p;
+  if (platform === "win32") {
+    for (const name of WINDOWS_ENV) { const v = fromEnv(base, name); if (v !== undefined) env[name] = v; }
+    env.TEMP = T; env.TMP = T;
+  }
+  env.HOME = T; env.XDG_CONFIG_HOME = T; env.LC_ALL = "C";
+  env.GIT_CONFIG_GLOBAL = path.join(T, "empty");
+  Object.assign(env, SEALED_ENV_FIXED);
+  if (index) env.GIT_INDEX_FILE = path.join(T, "index");
+  if (gitDir) env.GIT_DIR = gitDir;
+  if (snapshot) env.GIT_WORK_TREE = snapshot;
+  return env;
+}
+
+/** Creates T. `commonDir` (the checkout's git common directory) wires the object database; `objectFormat` is "sha1" or "sha256". */
+export function createSealedGitDir({ commonDir, objectFormat = "sha1" } = {}) {
+  const T = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "rk-sealed-git-")));
+  try {
+    for (const d of ["refs", path.join("objects", "info"), "info", "hooks"]) fs.mkdirSync(path.join(T, d), { recursive: true });
+    fs.writeFileSync(path.join(T, "HEAD"), SEALED_GIT.layout.head);
+    fs.writeFileSync(path.join(T, "config"), `[core]\n\trepositoryformatversion = ${objectFormat === "sha256" ? 1 : 0}\n\tbare = false\n${objectFormat === "sha256" ? "[extensions]\n\tobjectFormat = sha256\n" : ""}`);
+    fs.writeFileSync(path.join(T, "info", "attributes"), SEALED_ATTRIBUTES);
+    fs.writeFileSync(path.join(T, "info", "exclude"), "");
+    fs.writeFileSync(path.join(T, "empty"), "");
+    if (commonDir) fs.writeFileSync(path.join(T, "objects", "info", "alternates"), `${commonDir}/objects\n`);
+  } catch (error) {
+    fs.rmSync(T, { recursive: true, force: true });
+    throw error;
+  }
+  return T;
+}
+
+const why = (r, args) => `git ${args.filter((a) => a !== "-c" && !/^(core|index)\./.test(a)).join(" ")}: ${r.error ? r.error.message : String(r.stderr ?? "").trim() || `exit ${r.status}`}`;
+
+/**
+ * Runs `fn(git)` with a fresh T; `git.run(args, { input, binary, cwd })` returns the spawn result, `git.ok(...)` its stdout or throws an
+ * Error naming the command. The working directory is `snapshot` when given, else T. T is removed afterwards.
+ */
+export function withSealedGit({ commonDir, objectFormat, snapshot, platform = process.platform } = {}, fn) {
+  const T = createSealedGitDir({ commonDir, objectFormat });
+  const env = sealedEnv(T, { snapshot, platform });
+  const prefix = sealedConfigArgs(T, platform);
+  const run = (args, { input, binary = false, cwd } = {}) => spawnSync("git", [...prefix, ...args], { cwd: cwd ?? snapshot ?? T, env, input, maxBuffer: MAX_BUFFER, ...(binary ? {} : { encoding: "utf8" }) });
+  const ok = (args, options) => { const r = run(args, options); if (r.error || r.status !== 0) throw new Error(why(r, args)); return r.stdout; };
+  try { return fn({ run, ok, T, env }); } finally { fs.rmSync(T, { recursive: true, force: true }); }
+}
+
+// --- discovery: finding a repository and resolving a revision NAME, the only reads that need the checkout's own git directory -------------
+
+let home = null;
+/** One empty home directory per process for discovery runs, removed at exit. */
+function discoveryHome() {
+  if (home && fs.existsSync(home)) return home;
+  home = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "rk-git-home-")));
+  fs.writeFileSync(path.join(home, "empty"), "");
+  const mine = home;
+  process.once("exit", () => { try { fs.rmSync(mine, { recursive: true, force: true }); } catch { /* best effort */ } });
+  return home;
+}
+
+/** git run in `cwd` against the checkout's own repository (found from `cwd`), under the sealed environment (no GIT_DIR, no index) plus GIT_NO_REPLACE_OBJECTS. Returns the spawn result. */
+export function discoveryRun(cwd, args, { platform = process.platform, input } = {}) {
+  const env = sealedEnv(discoveryHome(), { platform, gitDir: null, index: false });
+  return spawnSync("git", args, { cwd, env, input, encoding: "utf8", maxBuffer: MAX_BUFFER });
+}
+/** As discoveryRun, returning trimmed-by-caller stdout or throwing an Error naming the command. */
+export function discoveryGit(cwd, args, options) {
+  const r = discoveryRun(cwd, args, options);
+  if (r.error || r.status !== 0) throw new Error(why(r, args));
+  return r.stdout;
+}
+
+const infoCache = new Map();
+/** `{ commonDir, objectFormat }` of the repository `checkout` belongs to, found by discovery and cached per canonical path. */
+export function sealedRepoInfo(checkout) {
+  let key;
+  try { key = fs.realpathSync.native(checkout); } catch { key = path.resolve(checkout); }
+  const cached = infoCache.get(key);
+  if (cached && fs.existsSync(path.join(cached.commonDir, "objects"))) return cached;
+  let common;
+  try { common = discoveryGit(key, ["rev-parse", "--path-format=absolute", "--git-common-dir"]).trim(); }
+  catch { common = path.resolve(key, discoveryGit(key, ["rev-parse", "--git-common-dir"]).trim()); }
+  const info = { commonDir: common, objectFormat: discoveryGit(key, ["rev-parse", "--show-object-format"]).trim() || "sha1" };
+  infoCache.set(key, info);
+  return info;
+}
+
+/** A single sealed git command against `checkout`'s object database (T is made and removed around it). Returns the spawn result. */
+export function sealedRun(checkout, args, options = {}) {
+  const info = options.repo ?? sealedRepoInfo(checkout);
+  return withSealedGit({ ...info, snapshot: options.snapshot }, (git) => git.run(args, options));
+}