@junghanacs/entwurf 0.24.0 → 0.25.1

package/scripts/lib/qualification-collection.ts

@@ -0,0 +1,384 @@
+/**
+ * qualification-collection — run several exact-argv groups in one process and record
+ * what was attempted (#124 step 1).
+ *
+ * `check-gate-qualification.ts --groups '<JSON array of argv>' --collect <dir>` runs the
+ * head once, then each requested group in order, each through runGroupReceipt on its
+ * own fresh snapshot. The collection is an inventory, NOT a verdict:
+ *
+ *   - a group that goes red (SURVIVED, WRONG-REASON, STALE, HANG, control-red, impure
+ *     snapshot) still writes its receipt, and the tail keeps running — the next group
+ *     gets a fresh snapshot, so that contamination stays inside the red group;
+ *   - a runner crash (an exception in the body), an origin seal that moved during a
+ *     group, or a receipt whose candidate differs from the one the collection started on
+ *     (bytes moved BETWEEN groups) STOPS the collection: the candidate is no longer the
+ *     one being measured, or the runner itself is broken. The rest are `not-attempted`;
+ *   - `collection.json` is rewritten atomically after every group, so a process that dies
+ *     mid-run leaves an honest, incomplete inventory behind rather than nothing.
+ *
+ * `complete` means only "every requested group wrote a receipt". Whether those receipts
+ * qualify anything is the ledger's question, never this file's.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { MutantSpec } from "./mutation-qualify.ts";
+import { type CurrentCandidate, checkReceipt, currentCandidate } from "./qualification-ledger.ts";
+import { canonicalJson, runGroupReceipt, sha256 } from "./qualification-receipt.ts";
+
+export const COLLECTION_SCHEMA = "entwurf.qualification-collection/v0";
+export const COLLECTION_LABEL = "collection — an inventory of attempted groups, not a verdict";
+export const COLLECTION_FILE = "collection.json";
+
+export type AttemptOutcome = "receipt-written" | "runner-crash" | "not-attempted";
+
+export interface Attempt {
+	argv: string[];
+	outcome: AttemptOutcome;
+	/** Receipt file name inside the collection dir, when one was written. */
+	file: string | null;
+	sha256: string | null;
+	detail: string | null;
+}
+
+export interface Collection {
+	schema: string;
+	label: string;
+	/** GITHUB_RUN_ID / GITHUB_RUN_ATTEMPT exactly as the environment gave them; null off CI. */
+	runId: string | null;
+	runAttempt: string | null;
+	startedAt: string;
+	finishedAt: string | null;
+	requested: string[][];
+	manifestClaimsSha256: string;
+	candidate: CurrentCandidate;
+	attempted: Attempt[];
+	stoppedBy: null | "runner-crash" | "seal-moved" | "candidate-drift";
+	complete: boolean;
+}
+
+/** `--groups all`: every exact gate argv of the committed set, once, in manifest order. */
+export function allGroupArgv(selected: MutantSpec[]): string[][] {
+	const seen = new Set<string>();
+	const out: string[][] = [];
+	for (const m of selected) {
+		const k = JSON.stringify(m.gate);
+		if (!seen.has(k)) {
+			seen.add(k);
+			out.push(m.gate);
+		}
+	}
+	return out;
+}
+
+/** Refuse, before any snapshot: an empty list, a duplicated argv, or one no committed group has. */
+export function checkRequestedGroups(requested: string[][], selected: MutantSpec[]): void {
+	if (requested.length === 0) throw new Error("--groups is empty — nothing to collect");
+	const known = new Set(selected.map((m) => JSON.stringify(m.gate)));
+	const seen = new Set<string>();
+	for (const argv of requested) {
+		const k = JSON.stringify(argv);
+		if (seen.has(k)) throw new Error(`--groups repeats ${k}`);
+		seen.add(k);
+		if (!known.has(k)) throw new Error(`--groups names ${k}, which is no exact gate argv of the committed manifests`);
+	}
+}
+
+/** `gNNN.json` for attempt index NNN — the ONLY file name a collection may declare. */
+export function receiptFileName(index: number): string {
+	return `g${String(index).padStart(3, "0")}.json`;
+}
+
+/**
+ * Every way a receipt differs from the candidate its collection started on, for its own
+ * group: head, surface, C0, manifest claim set, spec set, claims, declared inputs. Empty =
+ * this receipt measured the collection's candidate. Shared by the collector (stop) and
+ * checkCollection (re-read), so the two cannot disagree.
+ */
+export function candidateDrift(receiptText: string, c: Pick<Collection, "candidate">, argv: string[]): string[] {
+	const checked = checkReceipt(receiptText);
+	if (!checked.ok) return [`receipt ${checked.code}: ${checked.detail}`];
+	const r = checked.receipt;
+	const cur = c.candidate;
+	const g = cur.groups.find((x) => JSON.stringify(x.gate) === JSON.stringify(argv));
+	if (!g) return [`argv ${JSON.stringify(argv)} is not a group of the collection's candidate`];
+	const out: string[] = [];
+	if (JSON.stringify(r.group.gate) !== JSON.stringify(argv)) out.push("gate");
+	if (r.candidate.head !== cur.head) out.push("head");
+	if (r.candidate.workSurfaceSha256 !== cur.workSurfaceSha256) out.push("workSurface");
+	if (r.core.sha256 !== cur.coreSha256) out.push("core");
+	if (JSON.stringify([...r.manifestSet.claims].sort()) !== JSON.stringify(cur.manifestClaims)) out.push("manifestSet");
+	if (r.group.specSetSha256 !== g.specSetSha256) out.push("specSet");
+	if (JSON.stringify(r.group.claims) !== JSON.stringify(g.claims)) out.push("claims");
+	if (canonicalJson(r.group.declaredInputs) !== canonicalJson(g.declaredInputs)) out.push("declaredInputs");
+	return out;
+}
+
+const O_NOFOLLOW_FLAG = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
+const O_NONBLOCK_FLAG = typeof fs.constants.O_NONBLOCK === "number" ? fs.constants.O_NONBLOCK : 0;
+
+/**
+ * Read one entry of a collection dir by BASENAME only, deciding its kind on the very
+ * descriptor that is read (pattern of meta-session.ts readStoreRecordFile): a symlink at
+ * the name fails the open (ELOOP), a fifo does not block (O_NONBLOCK), and fstat refuses
+ * anything that is not a regular file. A name with a separator never reaches the fs.
+ */
+function readEntry(dir: string, name: string): { ok: true; bytes: Buffer } | { ok: false; why: string } {
+	if (name !== path.basename(name) || name === "." || name === "..") return { ok: false, why: "not a basename" };
+	if (O_NOFOLLOW_FLAG === 0) return { ok: false, why: "platform has no O_NOFOLLOW" };
+	let fd: number;
+	try {
+		fd = fs.openSync(path.join(dir, name), fs.constants.O_RDONLY | O_NOFOLLOW_FLAG | O_NONBLOCK_FLAG);
+	} catch (err) {
+		return { ok: false, why: (err as NodeJS.ErrnoException).code ?? String(err) };
+	}
+	try {
+		if (!fs.fstatSync(fd).isFile()) return { ok: false, why: "not a regular file" };
+		return { ok: true, bytes: fs.readFileSync(fd) };
+	} finally {
+		fs.closeSync(fd);
+	}
+}
+
+function writeCollection(dir: string, c: Collection): void {
+	const file = path.join(dir, COLLECTION_FILE);
+	const tmp = `${file}.tmp-${process.pid}`;
+	const fd = fs.openSync(tmp, "wx", 0o600);
+	try {
+		fs.writeFileSync(fd, `${JSON.stringify(c, null, "\t")}\n`);
+		fs.fsyncSync(fd);
+	} finally {
+		fs.closeSync(fd);
+	}
+	fs.renameSync(tmp, file);
+}
+
+export interface CollectOptions {
+	repoDir: string;
+	selected: MutantSpec[];
+	requested: string[][];
+	/** Must not exist yet; its parent must. Created 0700. */
+	collectDir: string;
+	log: (line: string) => void;
+	logError: (line: string) => void;
+	tmpRoot?: string;
+	coreGroupGate?: string[];
+	env?: NodeJS.ProcessEnv;
+	/** Test seam only: runs before group i starts (the self-test moves origin bytes here). */
+	beforeGroup?: (index: number) => void;
+}
+
+export async function collectGroups(opts: CollectOptions): Promise<Collection> {
+	checkRequestedGroups(opts.requested, opts.selected);
+	fs.mkdirSync(opts.collectDir, { mode: 0o700 });
+	const env = opts.env ?? process.env;
+	const c: Collection = {
+		schema: COLLECTION_SCHEMA,
+		label: COLLECTION_LABEL,
+		runId: env.GITHUB_RUN_ID ?? null,
+		runAttempt: env.GITHUB_RUN_ATTEMPT ?? null,
+		startedAt: new Date().toISOString(),
+		finishedAt: null,
+		requested: opts.requested,
+		manifestClaimsSha256: sha256(canonicalJson(opts.selected.map((m) => m.claim).sort())),
+		candidate: currentCandidate(opts.repoDir, opts.selected, opts.coreGroupGate),
+		attempted: opts.requested.map((argv) => ({
+			argv,
+			outcome: "not-attempted",
+			file: null,
+			sha256: null,
+			detail: null,
+		})),
+		stoppedBy: null,
+		complete: false,
+	};
+	writeCollection(opts.collectDir, c);
+
+	for (let i = 0; i < opts.requested.length; i++) {
+		opts.beforeGroup?.(i);
+		const argv = opts.requested[i];
+		const file = receiptFileName(i);
+		const receiptPath = path.join(opts.collectDir, file);
+		try {
+			const r = await runGroupReceipt({
+				repoDir: opts.repoDir,
+				selected: opts.selected,
+				gate: argv,
+				receiptPath,
+				log: opts.log,
+				logError: opts.logError,
+				tmpRoot: opts.tmpRoot,
+			});
+			c.attempted[i] = {
+				argv,
+				outcome: "receipt-written",
+				file,
+				sha256: sha256(fs.readFileSync(receiptPath)),
+				detail: r.passed ? "group-green" : "group-RED",
+			};
+			if (!r.sealStable) c.stoppedBy = "seal-moved";
+			else {
+				const drift = candidateDrift(fs.readFileSync(receiptPath, "utf8"), c, argv);
+				if (drift.length > 0) {
+					c.attempted[i].detail = `${c.attempted[i].detail}; candidate drift: ${drift.join(", ")}`;
+					c.stoppedBy = "candidate-drift";
+				}
+			}
+		} catch (err) {
+			c.attempted[i] = {
+				argv,
+				outcome: "runner-crash",
+				file: null,
+				sha256: null,
+				detail: err instanceof Error ? err.message : String(err),
+			};
+			c.stoppedBy = "runner-crash";
+		}
+		writeCollection(opts.collectDir, c);
+		if (c.stoppedBy) {
+			opts.logError(`[gate-qualification --groups] STOP after ${JSON.stringify(argv)}: ${c.stoppedBy}`);
+			break;
+		}
+	}
+	c.complete = c.stoppedBy === null && c.attempted.every((a) => a.outcome === "receipt-written");
+	c.finishedAt = new Date().toISOString();
+	writeCollection(opts.collectDir, c);
+	return c;
+}
+
+const isStringArray = (v: unknown): v is string[] => Array.isArray(v) && v.every((x) => typeof x === "string");
+const isStringRecord = (v: unknown): boolean =>
+	v !== null && typeof v === "object" && !Array.isArray(v) && Object.values(v).every((x) => typeof x === "string");
+
+/** Deep shape of a collection's `candidate` — every field candidateDrift reads, so a malformed one is reported, not thrown. */
+export function candidateShapeOk(v: unknown): boolean {
+	if (v === null || typeof v !== "object" || Array.isArray(v)) return false;
+	const c = v as Record<string, unknown>;
+	return (
+		typeof c.head === "string" &&
+		typeof c.workSurfaceSha256 === "string" &&
+		typeof c.coreSha256 === "string" &&
+		(c.coreFiles === undefined || isStringRecord(c.coreFiles)) &&
+		isStringArray(c.manifestClaims) &&
+		Array.isArray(c.groups) &&
+		c.groups.every((g) => {
+			if (g === null || typeof g !== "object" || Array.isArray(g)) return false;
+			const x = g as Record<string, unknown>;
+			return (
+				isStringArray(x.gate) &&
+				(x.gate as string[]).length > 0 &&
+				isStringArray(x.claims) &&
+				typeof x.specSetSha256 === "string" &&
+				isStringRecord(x.declaredInputs)
+			);
+		})
+	);
+}
+
+/**
+ * Read a collection dir back and name every way it is not a complete, intact inventory
+ * of ONE candidate. Nothing outside `dir` is ever opened: receipt names must be exactly
+ * `gNNN.json` for their own index, entries are read by basename with O_NOFOLLOW and
+ * checked regular on the descriptor, and a malformed collection.json is reported, never
+ * thrown. Empty result = intact AND complete.
+ */
+export function checkCollection(dir: string): string[] {
+	let dirStat: fs.Stats;
+	try {
+		dirStat = fs.lstatSync(dir);
+	} catch (err) {
+		return [`collection-unreadable: ${(err as NodeJS.ErrnoException).code ?? String(err)}`];
+	}
+	if (!dirStat.isDirectory()) return ["collection-unreadable: the collection path is not a real directory"];
+	return checkCollectionData((name) => readEntry(dir, name), fs.readdirSync(dir).sort()).errors;
+}
+
+export type EntryReader = (name: string) => { ok: true; bytes: Buffer } | { ok: false; why: string };
+
+/** A reader over an in-memory name→bytes map (e.g. an unpacked artifact): basenames only, no fs. */
+export function mapReader(files: Record<string, Buffer>): EntryReader {
+	return (name) => {
+		if (name !== path.basename(name) || name === "." || name === "..") return { ok: false, why: "not a basename" };
+		return Object.hasOwn(files, name) ? { ok: true, bytes: files[name] } : { ok: false, why: "ENOENT" };
+	};
+}
+
+/**
+ * The pure core of checkCollection: judge a collection from a reader and the list of
+ * entry names present. Returns the errors (empty = intact AND complete) and the parsed
+ * collection when its shape is sound.
+ */
+export function checkCollectionData(
+	read: EntryReader,
+	names: string[],
+): { errors: string[]; collection: Collection | null } {
+	const raw = read(COLLECTION_FILE);
+	if (!raw.ok) return { errors: [`collection-unreadable: ${COLLECTION_FILE} ${raw.why}`], collection: null };
+	let c: Collection;
+	try {
+		c = JSON.parse(raw.bytes.toString("utf8"));
+	} catch (err) {
+		return { errors: [`collection-unreadable: ${err instanceof Error ? err.message : String(err)}`], collection: null };
+	}
+	const isArgv = (a: unknown): a is string[] =>
+		Array.isArray(a) && a.length > 0 && a.every((x) => typeof x === "string");
+	const shapeOk =
+		c !== null &&
+		typeof c === "object" &&
+		Array.isArray(c.requested) &&
+		c.requested.every(isArgv) &&
+		Array.isArray(c.attempted) &&
+		c.attempted.every(
+			(a) =>
+				a !== null &&
+				typeof a === "object" &&
+				isArgv(a.argv) &&
+				["receipt-written", "runner-crash", "not-attempted"].includes(a.outcome) &&
+				(a.file === null || typeof a.file === "string") &&
+				(a.sha256 === null || typeof a.sha256 === "string"),
+		) &&
+		typeof c.complete === "boolean" &&
+		(c.stoppedBy === null || typeof c.stoppedBy === "string") &&
+		c.attempted.every((a) => a.detail === null || typeof a.detail === "string") &&
+		candidateShapeOk(c.candidate);
+	if (!shapeOk) {
+		return { errors: ["collection-shape: collection.json is missing or mistyping a required field"], collection: null };
+	}
+	const errors: string[] = [];
+	if (c.schema !== COLLECTION_SCHEMA) errors.push(`collection-schema: ${String(c.schema)}`);
+	if (
+		c.attempted.length !== c.requested.length ||
+		c.attempted.some((a, i) => JSON.stringify(a.argv) !== JSON.stringify(c.requested[i]))
+	) {
+		errors.push("collection-order: attempted does not follow requested");
+	}
+	c.attempted.forEach((a, i) => {
+		const label = JSON.stringify(a.argv);
+		if (a.outcome !== "receipt-written") {
+			errors.push(`collection-incomplete: ${label} ${a.outcome}${a.detail ? ` (${a.detail})` : ""}`);
+			return;
+		}
+		if (a.file !== receiptFileName(i)) {
+			errors.push(`collection-file-name: ${label} declares ${JSON.stringify(a.file)}, expected ${receiptFileName(i)}`);
+			return;
+		}
+		const got = read(a.file);
+		if (!got.ok) {
+			errors.push(
+				`${got.why === "ENOENT" ? "collection-missing" : "collection-not-regular"}: ${label} ${a.file} (${got.why})`,
+			);
+			return;
+		}
+		if (sha256(got.bytes) !== a.sha256) {
+			errors.push(`collection-altered: ${label} ${a.file}`);
+			return;
+		}
+		const drift = candidateDrift(got.bytes.toString("utf8"), c, a.argv);
+		if (drift.length > 0) errors.push(`collection-candidate-drift: ${label} ${a.file} differs in ${drift.join(", ")}`);
+	});
+	const declared = new Set([COLLECTION_FILE, ...c.attempted.flatMap((a) => (a.file ? [a.file] : []))]);
+	for (const f of names) if (!declared.has(f)) errors.push(`collection-extra: ${f}`);
+	if (c.stoppedBy) errors.push(`collection-stopped: ${c.stoppedBy}`);
+	if (!c.complete && errors.length === 0) errors.push("collection-incomplete: complete=false");
+	return { errors, collection: c };
+}

package/scripts/lib/qualification-gh.ts

@@ -0,0 +1,231 @@
+/**
+ * qualification-gh — the thin GitHub API boundary of the composite release oracle
+ * (#124 stage 3b). Every GitHub read goes through an injected `GhApi` (json + raw
+ * bytes), so the whole contract is testable offline with fixtures; the only networked
+ * implementation is `ghCli`, a two-line `gh api` wrapper that no floor test calls.
+ *
+ * What it proves about ONE run, and how it refuses:
+ *   - the run is the NEWEST `.github/workflows/ci.yml` run at the SHA (by id) from this
+ *     repository (not a fork), via push or workflow_dispatch, completed — an older,
+ *     friendlier run is never selected, and another workflow's runs are not candidates;
+ *   - the run's CURRENT attempt is the one read: its jobs, and only an artifact named
+ *     for that attempt. An older attempt's artifact is refused by name, not fallen back to;
+ *   - the `check` job and its dispatch-only collect + upload steps succeeded — which
+ *     means only that the collection finished and was uploaded, never that anything
+ *     qualified;
+ *   - for the final SHA, the four required jobs succeeded too;
+ *   - the artifact's raw zip bytes (never a `gh run download` tree) pass admitArtifact.
+ *
+ * Unobserved, stated rather than assumed: this repository has never uploaded an
+ * artifact (coordinator's read-only receipt 2026-09-29: total_count 0), so the real
+ * GitHub zip layout is unmeasured. A layout the reader does not accept fails closed.
+ */
+
+import { spawnSync } from "node:child_process";
+import { type ApiArtifact, admitArtifact, artifactName } from "./qualification-artifact.ts";
+import type { Collection } from "./qualification-collection.ts";
+
+export interface GhApi {
+	json(path: string): unknown;
+	bytes(path: string): Buffer;
+}
+
+export const CI_WORKFLOW_PATH = ".github/workflows/ci.yml";
+export const REQUIRED_JOBS = ["check", "install-surface", "artifact-consumer", "macos-install-surface"];
+/**
+ * The collection runs INSIDE the existing Linux `check` job (after its pinned herdr
+ * install and the FULL floor), as dispatch-only steps — never a separate job, so the
+ * environment matches the serial body's and the herdr supply contract is untouched.
+ */
+export const COMPOSITE_JOB = "check";
+export const COMPOSITE_STEP = "collect qualification receipts (not a verdict)";
+export const COMPOSITE_UPLOAD_STEP = "upload qualification collection";
+
+interface ApiRun {
+	id: number;
+	run_attempt: number;
+	head_sha: string;
+	event: string;
+	status: string;
+	conclusion: string | null;
+	path: string;
+	head_repository: { full_name: string } | null;
+}
+
+interface ApiJob {
+	name: string;
+	conclusion: string | null;
+	steps?: { name: string; conclusion: string | null }[];
+}
+
+export interface RunEvidence {
+	errors: string[];
+	runId: string | null;
+	runAttempt: string | null;
+	files: Record<string, Buffer> | null;
+	collection: Collection | null;
+	witness: string | null;
+}
+
+const fail = (errors: string[], run?: ApiRun): RunEvidence => ({
+	errors,
+	runId: run ? String(run.id) : null,
+	runAttempt: run ? String(run.run_attempt) : null,
+	files: null,
+	collection: null,
+	witness: null,
+});
+
+function ciRunsAt(api: GhApi, repo: string, sha: string): ApiRun[] {
+	const body = api.json(`repos/${repo}/actions/runs?head_sha=${sha}&per_page=100`) as { workflow_runs?: ApiRun[] };
+	return (body.workflow_runs ?? []).filter((r) => r.path === CI_WORKFLOW_PATH && r.head_sha === sha);
+}
+
+function jobsOf(api: GhApi, repo: string, run: ApiRun): ApiJob[] {
+	const body = api.json(`repos/${repo}/actions/runs/${run.id}/attempts/${run.run_attempt}/jobs?per_page=100`) as {
+		jobs?: ApiJob[];
+	};
+	return body.jobs ?? [];
+}
+
+function compositeSucceeded(jobs: ApiJob[]): string[] {
+	const job = jobs.find((j) => j.name === COMPOSITE_JOB);
+	if (!job) return [`composite-job: no ${COMPOSITE_JOB} job in this attempt`];
+	const errors: string[] = [];
+	if (job.conclusion !== "success") errors.push(`composite-job: ${COMPOSITE_JOB} concluded ${String(job.conclusion)}`);
+	for (const name of [COMPOSITE_STEP, COMPOSITE_UPLOAD_STEP]) {
+		const step = (job.steps ?? []).find((s) => s.name === name);
+		if (!step) errors.push(`composite-step: no step named "${name}" in ${COMPOSITE_JOB}`);
+		else if (step.conclusion !== "success")
+			errors.push(`composite-step: "${name}" concluded ${String(step.conclusion)}`);
+	}
+	return errors;
+}
+
+function checkRunIdentity(run: ApiRun, repo: string, sha: string, final: boolean): string[] {
+	const errors: string[] = [];
+	if (run.head_repository?.full_name !== repo) {
+		errors.push(`run-repository: head repository ${String(run.head_repository?.full_name)} is not ${repo}`);
+	}
+	if (run.event !== "push" && run.event !== "workflow_dispatch") errors.push(`run-event: ${run.event}`);
+	if (run.head_sha !== sha) errors.push(`run-head: ${run.head_sha}`);
+	if (run.status !== "completed") errors.push(`run-status: ${run.status}`);
+	if (final && run.conclusion !== "success") errors.push(`run-conclusion: ${String(run.conclusion)}`);
+	return errors;
+}
+
+/** Artifact of the run's CURRENT attempt, raw zip bytes, admitted. */
+function admitRunArtifact(
+	api: GhApi,
+	repo: string,
+	run: ApiRun,
+	independentCoreFiles: Record<string, string> | undefined,
+): RunEvidence {
+	const listed = api.json(`repos/${repo}/actions/runs/${run.id}/artifacts?per_page=100`) as {
+		artifacts?: ApiArtifact[];
+	};
+	const artifacts = listed.artifacts ?? [];
+	const want = artifactName(String(run.id), String(run.run_attempt));
+	const hits = artifacts.filter((a) => a.name === want);
+	if (hits.length !== 1) {
+		const older = artifacts.filter((a) => a.name.startsWith(`qualification-collection-${run.id}-`) && a.name !== want);
+		return fail(
+			[
+				older.length > 0 && hits.length === 0
+					? `artifact-attempt: attempt ${run.run_attempt} has no artifact; ${older.map((a) => a.name).join(", ")} belongs to an older attempt and is refused`
+					: `artifact-select: ${hits.length} artifacts named ${want}, need exactly 1`,
+			],
+			run,
+		);
+	}
+	const zip = api.bytes(`repos/${repo}/actions/artifacts/${hits[0].id}/zip`);
+	const admitted = admitArtifact({
+		runId: String(run.id),
+		runAttempt: String(run.run_attempt),
+		headSha: run.head_sha,
+		artifact: hits[0],
+		zip,
+		independentCoreFiles,
+	});
+	return {
+		errors: admitted.errors,
+		runId: String(run.id),
+		runAttempt: String(run.run_attempt),
+		files: admitted.files,
+		collection: admitted.collection,
+		witness: admitted.witness,
+	};
+}
+
+/** The final SHA: newest ci.yml run, four required jobs, composite collection, artifact. */
+export function finalRunEvidence(
+	api: GhApi,
+	repo: string,
+	sha: string,
+	independentCoreFiles: Record<string, string>,
+): RunEvidence {
+	const runs = ciRunsAt(api, repo, sha);
+	if (runs.length === 0) return fail([`run-missing: no ${CI_WORKFLOW_PATH} run at ${sha}`]);
+	const run = runs.reduce((a, b) => (b.id > a.id ? b : a));
+	const identity = checkRunIdentity(run, repo, sha, true);
+	if (identity.length > 0) return fail(identity, run);
+	const jobs = jobsOf(api, repo, run);
+	const errors: string[] = [];
+	for (const name of REQUIRED_JOBS) {
+		const j = jobs.find((x) => x.name === name);
+		if (j?.conclusion !== "success")
+			errors.push(`required-job: ${name} concluded ${String(j?.conclusion ?? "absent")}`);
+	}
+	errors.push(...compositeSucceeded(jobs));
+	if (errors.length > 0) return fail(errors, run);
+	return admitRunArtifact(api, repo, run, independentCoreFiles);
+}
+
+/**
+ * An ancestor SHA: the operator names a run id; it must be a ci.yml run of this repo at
+ * that SHA whose current attempt collected successfully, AND no newer ci.yml run at the
+ * same SHA may also carry a successful collection (the newest evidence wins).
+ */
+export function ancestorRunEvidence(api: GhApi, repo: string, sha: string, runId: string): RunEvidence {
+	const runs = ciRunsAt(api, repo, sha);
+	const run = runs.find((r) => String(r.id) === runId);
+	if (!run) return fail([`run-missing: ${runId} is not a ${CI_WORKFLOW_PATH} run at ${sha}`]);
+	const identity = checkRunIdentity(run, repo, sha, false);
+	if (identity.length > 0) return fail(identity, run);
+	const own = compositeSucceeded(jobsOf(api, repo, run));
+	if (own.length > 0) return fail(own, run);
+	// Every newer ci.yml run at this SHA is classified on two separate axes: did it ATTEMPT
+	// a collection (its collect step ran, i.e. was not skipped/absent, or it uploaded a
+	// collection artifact), and did that attempt SUCCEED. A newer failed attempt rejects
+	// this older one — a new collection's failure is never papered over by an old green.
+	// A newer run that never attempted (push/schedule: step skipped or absent, no artifact)
+	// is not a collection and does not displace this one.
+	for (const r of runs.filter((x) => x.id > run.id).sort((x, y) => y.id - x.id)) {
+		const jobs = jobsOf(api, repo, r);
+		const step = jobs.find((j) => j.name === COMPOSITE_JOB)?.steps?.find((st) => st.name === COMPOSITE_STEP);
+		const listed = api.json(`repos/${repo}/actions/runs/${r.id}/artifacts?per_page=100`) as {
+			artifacts?: ApiArtifact[];
+		};
+		const uploaded = (listed.artifacts ?? []).some((a) => a.name.startsWith(`qualification-collection-${r.id}-`));
+		const attempted = (step !== undefined && step.conclusion !== "skipped") || uploaded;
+		if (!attempted) continue;
+		if (compositeSucceeded(jobs).length > 0 || r.conclusion !== "success") {
+			return fail(
+				[`run-newer-collection-failed: run ${r.id} at the same SHA attempted a collection and did not succeed`],
+				run,
+			);
+		}
+		return fail([`run-not-newest: run ${r.id} at the same SHA also collected`], run);
+	}
+	return admitRunArtifact(api, repo, run, undefined);
+}
+
+/** The only networked GhApi. Not called by any floor test. */
+export function ghCli(): GhApi {
+	const call = (path: string): Buffer => {
+		const r = spawnSync("gh", ["api", path], { encoding: "buffer", maxBuffer: 128 * 1024 * 1024 });
+		if (r.status !== 0) throw new Error(`gh api ${path} failed: ${r.stderr.toString("utf8").trim()}`);
+		return r.stdout;
+	};
+	return { json: (path) => JSON.parse(call(path).toString("utf8")), bytes: call };
+}