@intentius/chant 0.124.32 → 0.124.34

package/src/workspace/ci-builds.test.ts

@@ -0,0 +1,174 @@
+/**
+ * #4169 — which commits get built: supersession, retries, requests and
+ * bisection over judged commits, and the records each commit gets.
+ */
+
+import { describe, expect, test } from "vitest";
+import { agedOut, BUILD_REQUEST_TTL_MS, planBuilds, recordOf, RETRY_TTL_MS, sameRecord, type BuildRequest, type CiRecord } from "./ci-builds";
+import { evaluateCommit, type TickCommit } from "./ci-green";
+import type { CheckRun } from "./ci-green-forge";
+import type { CiGreen } from "./declaration";
+
+const NOW = new Date("2026-10-20T12:00:00Z");
+const ago = (ms: number) => new Date(NOW.getTime() - ms).toISOString().replace(/\.\d{3}Z$/, "Z");
+
+const GREEN: CiGreen = {
+  branch: "main",
+  window: "24h",
+  phases: [
+    { name: "check", runs: ["check"], skipped: "fail", build: "every", pointer: "/ci/green/phases/check" },
+    { name: "suites", runs: ["suites"], skipped: "fail", build: "newest", pointer: "/ci/green/phases/suites" },
+  ],
+  require: ["check", "suites"],
+  signedSince: null,
+  source: "checks",
+  pointer: "/ci/green",
+};
+
+let nextId = 1;
+const run = (name: string, conclusion: string | null, status = "completed"): CheckRun => ({ id: nextId++, name, status, conclusion: status === "completed" ? conclusion : null, completedAt: null, url: null });
+const sha = (n: number) => String(n).padStart(40, "0");
+
+/** Commits newest first, each with its runs, judged as the tick judges them. */
+function judged(runsPerCommit: CheckRun[][], before: TickCommit["before"][] = []): { commits: TickCommit[]; runs: Map<string, CheckRun[]> } {
+  const runs = new Map<string, CheckRun[]>();
+  const commits = runsPerCommit.map((r, i) => {
+    const s = sha(runsPerCommit.length - i);
+    runs.set(s, r);
+    return { sha: s, committed: NOW.toISOString(), before: before[i] ?? "none", verdict: evaluateCommit(GREEN, r), made: null } as TickCommit;
+  });
+  return { commits, runs };
+}
+
+const plan = (commits: TickCommit[], runs: Map<string, CheckRun[]>, extra: Partial<Parameters<typeof planBuilds>[0]> = {}) =>
+  planBuilds({ green: GREEN, commits, runs, requests: new Map(), records: new Map(), now: NOW, retryVia: null, ...extra });
+
+const suites = (c: TickCommit) => c.verdict!.phases.find((p) => p.phase === "suites")!;
+
+describe("supersession (#4169)", () => {
+  test("a newest phase with no run below a commit that has one is unbuilt, covered by it; the newest commit stays pending", () => {
+    const { commits, runs } = judged([[run("check", "success")], [run("check", "success"), run("suites", "success")], [run("check", "success")]]);
+    plan(commits, runs);
+    expect(commits.map((c) => c.verdict!.verdict)).toEqual(["pending", "pass", "unbuilt"]);
+    expect(suites(commits[2])).toMatchObject({ verdict: "unbuilt", reason: "superseded", coveredBy: commits[1].sha });
+    expect(suites(commits[0])).toMatchObject({ verdict: "pending" });
+  });
+
+  test("an every phase is never superseded, and a cancelled run is unbuilt under either", () => {
+    const { commits, runs } = judged([[run("check", "success"), run("suites", "success")], [run("suites", "success")], [run("check", "cancelled"), run("suites", "success")]]);
+    plan(commits, runs);
+    expect(commits.map((c) => c.verdict!.verdict)).toEqual(["pass", "pending", "unbuilt"]);
+    expect(commits[2].verdict!.phases[0]).toMatchObject({ phase: "check", verdict: "unbuilt", reason: "cancelled" });
+  });
+});
+
+describe("bisect (#4169)", () => {
+  const green = () => [run("check", "success"), run("suites", "success")];
+  const red = () => [run("check", "success"), run("suites", "failure")];
+  const none = () => [run("check", "success")];
+
+  test("a red newest commit asks for the one just below it when four or fewer are unbuilt", () => {
+    const { commits, runs } = judged([red(), none(), none(), green()]);
+    const p = plan(commits, runs);
+    expect(p.requests).toEqual([expect.objectContaining({ commit: commits[1].sha, phases: ["suites"], reason: "bisect", tag: `ci/build/${commits[1].sha}` })]);
+    expect(suites(commits[1])).toMatchObject({ verdict: "pending", reason: "requested" });
+  });
+
+  test("halves the range above four, and asks for nothing while a request in it waits", () => {
+    const { commits, runs } = judged([red(), none(), none(), none(), none(), none(), none(), green()]);
+    const p = plan(commits, runs);
+    expect(p.requests.map((r) => r.commit)).toEqual([commits[4].sha]);
+    const waiting: BuildRequest = { ...p.requests[0], at: ago(60_000) };
+    const again = judged([red(), none(), none(), none(), none(), none(), none(), green()]);
+    expect(plan(again.commits, again.runs, { requests: new Map([[waiting.commit, waiting]]) }).requests).toEqual([]);
+  });
+
+  test("names the culprit on it and every commit after it once the red sits on a green", () => {
+    const { commits, runs } = judged([red(), none(), red(), green()]);
+    // The commit below the newest red is unbuilt between two reds: the culprit is at or below the older red.
+    plan(commits, runs);
+    expect(commits.map((c) => suites(c).culprit)).toEqual([commits[2].sha, commits[2].sha, commits[2].sha, undefined]);
+  });
+
+  test("names no culprit without a green below, and an every phase gets one too", () => {
+    const noGreen = judged([red(), red()]);
+    plan(noGreen.commits, noGreen.runs);
+    expect(noGreen.commits.map((c) => suites(c).culprit)).toEqual([undefined, undefined]);
+    const every = judged([[run("check", "failure")], [run("check", "failure")], [run("check", "success")]]);
+    plan(every.commits, every.runs);
+    expect(every.commits.map((c) => c.verdict!.phases[0].culprit)).toEqual([every.commits[1].sha, every.commits[1].sha, undefined]);
+  });
+});
+
+describe("requests (#4169)", () => {
+  const req = (commit: string, at: string): BuildRequest => ({ schema: 1, tag: `ci/build/${commit}`, commit, branch: "main", phases: ["suites"], reason: "requested", at });
+
+  test("a request holds its phase pending; once decided, or too old, or out of the window, it is done", () => {
+    const { commits, runs } = judged([[run("check", "success"), run("suites", "success")], [run("check", "success")]]);
+    const waiting = req(commits[1].sha, ago(60_000));
+    const p = plan(commits, runs, { requests: new Map([[waiting.commit, waiting]]) });
+    expect(suites(commits[1])).toMatchObject({ verdict: "pending", reason: "requested" });
+    expect(p.resolved).toEqual([]);
+
+    const old = judged([[run("check", "success"), run("suites", "success")], [run("check", "success")]]);
+    const stale = req(old.commits[1].sha, ago(BUILD_REQUEST_TTL_MS + 1));
+    expect(plan(old.commits, old.runs, { requests: new Map([[stale.commit, stale]]) }).resolved).toEqual([stale.tag]);
+    expect(suites(old.commits[1])).toMatchObject({ verdict: "unbuilt", reason: "request-unserved" });
+
+    const done = judged([[run("check", "success"), run("suites", "success")]]);
+    const served = req(done.commits[0].sha, ago(60_000));
+    const gone = req(sha(99), ago(60_000));
+    expect(plan(done.commits, done.runs, { requests: new Map([[served.commit, served], [gone.commit, gone]]) }).resolved.sort()).toEqual([served.tag, gone.tag].sort());
+  });
+});
+
+describe("retry (#4169)", () => {
+  test("a failed run with one attempt is run again and holds the commit pending; a second attempt decides", () => {
+    const failed = run("check", "failure");
+    const { commits, runs } = judged([[failed, run("suites", "success")]]);
+    const p = plan(commits, runs, { retryVia: "forge" });
+    expect(p.retries).toEqual([{ sha: commits[0].sha, run: failed }]);
+    expect(commits[0].verdict!.verdict).toBe("pending");
+    expect(commits[0].verdict!.phases[0]).toMatchObject({ verdict: "pending", reason: "retrying" });
+
+    const twice = judged([[failed, run("check", "failure"), run("suites", "success")]]);
+    expect(plan(twice.commits, twice.runs, { retryVia: "forge" }).retries).toEqual([]);
+    expect(twice.commits[0].verdict!.verdict).toBe("fail");
+  });
+
+  test("a retry asked for waits an hour for its attempt, then the failure counts; chant runs ask by request; a green commit is never retried", () => {
+    const failed = run("check", "failure");
+    const asked = (at: string): CiRecord => ({ schema: 1, commit: sha(1), branch: "main", state: "pending", at, phases: {}, retried: { check: { run: failed.id, at } } });
+    const waiting = judged([[failed, run("suites", "success")]]);
+    expect(plan(waiting.commits, waiting.runs, { retryVia: "forge", records: new Map([[sha(1), asked(ago(60_000))]]) }).retries).toEqual([]);
+    expect(waiting.commits[0].verdict!.verdict).toBe("pending");
+    const late = judged([[failed, run("suites", "success")]]);
+    plan(late.commits, late.runs, { retryVia: "forge", records: new Map([[sha(1), asked(ago(RETRY_TTL_MS + 1))]]) });
+    expect(late.commits[0].verdict!.verdict).toBe("fail");
+
+    const viaRequest = judged([[failed, run("suites", "success")]]);
+    expect(plan(viaRequest.commits, viaRequest.runs, { retryVia: "request" }).requests).toEqual([expect.objectContaining({ commit: sha(1), phases: ["check"], reason: "retry" })]);
+
+    const tagged = judged([[failed, run("suites", "success")]], ["green"]);
+    expect(plan(tagged.commits, tagged.runs, { retryVia: "forge" }).retries).toEqual([]);
+  });
+});
+
+describe("records (#4169)", () => {
+  test("say green, red, unbuilt or pending with each phase's verdict, reason and covering commit, and skip the time when compared", () => {
+    const { commits, runs } = judged([[run("check", "success"), run("suites", "success")], [run("check", "success")]]);
+    plan(commits, runs);
+    commits[0].made = { tag: `ci/green/${commits[0].sha}`, message: "" };
+    const top = recordOf({ green: GREEN, commit: commits[0], retries: [], requests: new Map(), now: NOW });
+    expect(top).toMatchObject({ state: "green", commit: commits[0].sha, phases: { check: { verdict: "pass", build: "every" }, suites: { verdict: "pass", build: "newest" } } });
+    const below = recordOf({ green: GREEN, commit: commits[1], retries: [], requests: new Map(), now: NOW });
+    expect(below).toMatchObject({ state: "unbuilt", phases: { suites: { verdict: "unbuilt", reason: "superseded", coveredBy: commits[0].sha } } });
+    expect(sameRecord({ ...below, at: "2020-01-01T00:00:00Z" }, below)).toBe(true);
+    expect(sameRecord({ ...below, state: "pending" }, below)).toBe(false);
+  });
+
+  test("a pending record that left the window is rewritten unbuilt, aged out", () => {
+    const pending: CiRecord = { schema: 1, commit: sha(1), branch: "main", state: "pending", at: ago(1), phases: { suites: { verdict: "pending", build: "newest", runs: [] } } };
+    expect(agedOut(pending, NOW)).toMatchObject({ state: "unbuilt", phases: { suites: { verdict: "unbuilt", reason: "aged-out" } } });
+  });
+});

package/src/workspace/ci-builds.ts

@@ -0,0 +1,385 @@
+/**
+ * Which commits get built, and what each one ends with (#4169).
+ *
+ * A `ci.green` phase declares `build: "every"` (the default) or
+ * `build: "newest"`. Under `newest` the phase's workflow keeps one run
+ * waiting and drops the rest, so only the newest commit is built when a
+ * runner frees. This module does the tick's part of that, given the
+ * verdicts {@link planTick} (./ci-green.ts) judged:
+ *
+ * - Superseded. A commit with no run of a `newest` phase, below a newer
+ *   commit that has one, is `unbuilt` for that phase, covered by the newer
+ *   commit. A cancelled run makes any phase `unbuilt` (`phaseVerdictOf`).
+ * - Retry. A failed run with one attempt is run again once before the
+ *   commit counts red: through the forge's re-run (`CiForge.rerun`) for
+ *   check runs, or a build request for chant runs. A retry that has not
+ *   started an hour on counts as the failure it was.
+ * - Bisect. When the newest built commit of a `newest` phase is red, the
+ *   unbuilt commits back to the last one the phase passed on are built, one
+ *   request per tick: the commit halfway when more than four are left, else
+ *   the one just below the red. The first red commit found is the culprit,
+ *   and it and every commit after it name it.
+ * - Requests. A build is asked for with an annotated tag,
+ *   `ci/build/<sha>`, whose record names the phases and why. The tick
+ *   starts a workflow at that tag on GitHub (`CiForge.dispatch`), and `ci
+ *   serve --build-command` serves it for chant runs. A phase a request
+ *   waits on is `pending`. A request no runner served in six hours leaves
+ *   the phase `unbuilt`, and once its phases are decided the tick deletes
+ *   the tag.
+ * - Records. Every first-parent commit the tick judged gets
+ *   `_ci/<sha>.json` on `chant/lifecycle`, rewritten only when what it says
+ *   changes: `green`, `red`, `unbuilt` or `pending`, with each required
+ *   phase's verdict, runs, reason, the commit that covers it and the culprit.
+ *   A commit that leaves the window still `pending` is rewritten `unbuilt`,
+ *   for the reason `aged-out`. The `ci/green` and `ci/revoked` tags stay
+ *   what decides a release; the records say what happened to the rest.
+ */
+
+import { execFileSync } from "node:child_process";
+import type { CiBuild, CiGreen } from "./declaration";
+import type { CheckRun } from "./ci-green-forge";
+import { commitVerdictOf, phaseVerdictOf, type PhaseReason, type PhaseVerdict, type TickCommit, type Verdict } from "./ci-green";
+
+export const CI_BUILD_TAG_PREFIX = "ci/build/";
+/** The directory on `chant/lifecycle` holding one record per commit. */
+export const CI_RECORDS_DIR = "_ci";
+const LEDGER_REF = "refs/heads/chant/lifecycle";
+
+/** How long a build request may wait for a runner before its phases count as unbuilt. */
+export const BUILD_REQUEST_TTL_MS = 6 * 3_600_000;
+/** How long a retry may take to start before the failure it was counts. */
+export const RETRY_TTL_MS = 3_600_000;
+/** Above this many unbuilt commits a bisect halves the range; at or below it, it steps back one commit at a time. */
+export const BISECT_HALVE_ABOVE = 4;
+
+export type BuildRequestReason = "bisect" | "retry" | "requested";
+
+/** A `ci/build/<sha>` tag's record: the phases to build at the commit, and why. */
+export interface BuildRequest {
+  schema: 1;
+  tag: string;
+  commit: string;
+  branch: string;
+  phases: string[];
+  reason: BuildRequestReason;
+  /** When it was asked for, ISO 8601. */
+  at: string;
+}
+
+/** One record, `_ci/<sha>.json` on `chant/lifecycle`. */
+export interface CiRecord {
+  schema: 1;
+  commit: string;
+  branch: string;
+  /** `green` and `red` follow the tags: a green tag, or a failed phase or a revoked tag. */
+  state: "green" | "red" | "unbuilt" | "pending";
+  /** When this content was written, ISO 8601. Not compared when deciding whether to write again. */
+  at: string;
+  /** Set when the commit has a revoked tag. */
+  revoked?: true;
+  phases: Record<string, CiRecordPhase>;
+  /** The first required phase that failed, and its run, when the state is red. */
+  failure?: { phase: string; run: CiRecordRun };
+  /** The retries asked for, by run name: the run that failed and when. */
+  retried?: Record<string, { run: number; at: string }>;
+  /** The build request waiting on this commit, when there is one. */
+  request?: { tag: string; reason: BuildRequestReason; phases: string[]; at: string; dispatched?: true };
+}
+
+export interface CiRecordRun {
+  name: string;
+  id: number | null;
+  conclusion: string | null;
+  url: string | null;
+}
+
+export interface CiRecordPhase {
+  verdict: Verdict;
+  build: CiBuild;
+  runs: CiRecordRun[];
+  reason?: PhaseReason | "aged-out";
+  coveredBy?: string;
+  culprit?: string;
+}
+
+const iso = (d: Date) => d.toISOString().replace(/\.\d{3}Z$/, "Z");
+
+/** How a tick can run a failed job again: the forge's re-run, a build request, or not at all. */
+export type RetryVia = "forge" | "request" | null;
+
+export interface BuildsInput {
+  green: CiGreen;
+  /** Newest first, as {@link planTick} returns them. */
+  commits: TickCommit[];
+  /** Every attempt of every run, by commit. */
+  runs: ReadonlyMap<string, readonly CheckRun[]>;
+  requests: ReadonlyMap<string, BuildRequest>;
+  records: ReadonlyMap<string, CiRecord>;
+  now: Date;
+  retryVia: RetryVia;
+}
+
+export interface BuildsPlan {
+  /** Requests to make: bisect steps, and retries of chant runs. */
+  requests: BuildRequest[];
+  /** Failed check runs to run again through the forge, by commit. */
+  retries: { sha: string; run: CheckRun }[];
+  /** Request tags whose phases are decided, or that waited too long, or whose commit left the window. */
+  resolved: string[];
+}
+
+const phaseOf = (green: CiGreen, name: string) => green.phases.find((p) => p.name === name)!;
+const buildOf = (green: CiGreen, name: string): CiBuild => phaseOf(green, name).build ?? "every";
+const decided = (v: Verdict | undefined) => v === "pass" || v === "fail";
+const age = (at: string, now: Date) => now.getTime() - Date.parse(at);
+
+function setPhase(c: TickCommit, phase: string, fn: (p: PhaseVerdict) => PhaseVerdict): void {
+  const v = c.verdict;
+  if (!v) return;
+  c.verdict = commitVerdictOf(v.phases.map((p) => (p.phase === phase ? fn(p) : p)));
+}
+
+const phaseIn = (c: TickCommit, phase: string) => c.verdict?.phases.find((p) => p.phase === phase);
+
+/**
+ * Apply supersession, retries, requests and bisection to the judged commits,
+ * in place, and say what the tick has to ask for. Pure: it reads and writes
+ * nothing but its input.
+ */
+export function planBuilds(input: BuildsInput): BuildsPlan {
+  const { green, commits, now } = input;
+  const plan: BuildsPlan = { requests: [], retries: [], resolved: [] };
+  const inWindow = new Set(commits.map((c) => c.sha));
+  const live = (sha: string, phase: string): BuildRequest | undefined => {
+    const r = input.requests.get(sha);
+    return r && r.phases.includes(phase) && age(r.at, now) < BUILD_REQUEST_TTL_MS ? r : undefined;
+  };
+
+  // A request waits on a phase with no run yet; one no runner served in time leaves it unbuilt.
+  for (const c of commits) {
+    const r = input.requests.get(c.sha);
+    if (!r || !c.verdict) continue;
+    for (const name of r.phases) {
+      const p = phaseIn(c, name);
+      if (!p || p.runs.length > 0) continue;
+      setPhase(c, name, (q) => (live(c.sha, name) ? { ...q, verdict: "pending", reason: "requested" } : { ...q, verdict: "unbuilt", reason: "request-unserved" }));
+    }
+  }
+
+  // Superseded: newest first, a newest phase with no run below a commit with one.
+  for (const name of green.require) {
+    if (buildOf(green, name) !== "newest") continue;
+    let cover: string | undefined;
+    for (const c of commits) {
+      const p = phaseIn(c, name);
+      if (!p) continue;
+      if (p.runs.length > 0) {
+        cover = c.sha;
+        continue;
+      }
+      if (cover && p.reason !== "requested" && p.reason !== "request-unserved") setPhase(c, name, (q) => ({ ...q, verdict: "unbuilt", reason: "superseded", coveredBy: cover }));
+    }
+  }
+
+  // Retry once: a commit with no tag whose failed run has one attempt.
+  if (input.retryVia) {
+    for (const c of commits) {
+      if (c.before !== "none" || c.verdict?.verdict !== "fail") continue;
+      const all = input.runs.get(c.sha) ?? [];
+      const retried = input.records.get(c.sha)?.retried ?? {};
+      for (const p of c.verdict.phases) {
+        for (const run of p.runs.filter((r) => r.verdict === "fail")) {
+          if (all.filter((r) => r.name === run.name).length > 1) continue;
+          const asked = retried[run.name];
+          if (asked && asked.run === run.id && age(asked.at, now) >= RETRY_TTL_MS) continue;
+          if (!asked || asked.run !== run.id) {
+            const checkRun = all.find((r) => r.name === run.name && r.id === run.id)!;
+            if (input.retryVia === "forge") plan.retries.push({ sha: c.sha, run: checkRun });
+            else if (!input.requests.has(c.sha) && !plan.requests.some((q) => q.commit === c.sha)) plan.requests.push(request(green, c.sha, [p.phase], "retry", now));
+          }
+          setPhase(c, p.phase, (q) => {
+            const runs = q.runs.map((r) => (r.name === run.name && r.id === run.id ? { ...r, verdict: "pending" as const } : r));
+            return { ...q, runs, ...phaseVerdictOf(runs, q.unmatched), reason: "retrying" };
+          });
+        }
+      }
+    }
+  }
+
+  // Culprits for every phase, and a bisect request for a newest one.
+  for (const name of green.require) {
+    const verdicts = commits.map((c) => phaseIn(c, name));
+    const top = verdicts.findIndex((p) => decided(p?.verdict));
+    if (top < 0 || verdicts[top]!.verdict !== "fail") continue;
+    let oldestRed = top;
+    let between: number[] = [];
+    let passed = -1;
+    for (let i = top + 1; i < commits.length; i++) {
+      const v = verdicts[i]?.verdict;
+      if (v === "fail") {
+        oldestRed = i;
+        between = [];
+      } else if (v === "pass") {
+        passed = i;
+        break;
+      } else if (v !== undefined) between.push(i);
+    }
+    if (between.length === 0) {
+      if (passed < 0) continue;
+      const culprit = commits[oldestRed].sha;
+      for (let i = oldestRed; i >= 0; i--) {
+        if (verdicts[i]?.verdict === "pass") break;
+        if (verdicts[i]) setPhase(commits[i], name, (q) => ({ ...q, culprit }));
+      }
+      continue;
+    }
+    if (buildOf(green, name) !== "newest") continue;
+    if (between.some((i) => live(commits[i].sha, name))) continue;
+    const pick = between.length > BISECT_HALVE_ABOVE ? between[Math.floor(between.length / 2)] : between[0];
+    const sha = commits[pick].sha;
+    if (input.requests.has(sha) || plan.requests.some((q) => q.commit === sha)) continue;
+    plan.requests.push(request(green, sha, [name], "bisect", now));
+    setPhase(commits[pick], name, (q) => ({ ...q, verdict: "pending", reason: "requested", coveredBy: undefined }));
+  }
+
+  // A request is done once its phases are decided, it has waited too long, or its commit left the window.
+  for (const [sha, r] of input.requests) {
+    const c = commits.find((x) => x.sha === sha);
+    const done = !inWindow.has(sha) || age(r.at, now) >= BUILD_REQUEST_TTL_MS || (c !== undefined && (c.before === "revoked" || r.phases.every((name) => decided(phaseIn(c, name)?.verdict))));
+    if (done) plan.resolved.push(r.tag);
+  }
+  return plan;
+}
+
+function request(green: CiGreen, commit: string, phases: string[], reason: BuildRequestReason, now: Date): BuildRequest {
+  return { schema: 1, tag: `${CI_BUILD_TAG_PREFIX}${commit}`, commit, branch: green.branch, phases, reason, at: iso(now) };
+}
+
+// ── Records ──────────────────────────────────────────────────────────────────
+
+const recordRun = (r: { name: string; id: number; conclusion: string | null; url: string | null; opRun?: unknown }): CiRecordRun => ({ name: r.name, id: r.opRun ? null : r.id, conclusion: r.conclusion, url: r.url });
+
+/** The record a judged commit gets, carrying the retries asked for before and now. */
+export function recordOf(input: { green: CiGreen; commit: TickCommit; previous?: CiRecord; retries: readonly { sha: string; run: CheckRun }[]; requests: ReadonlyMap<string, BuildRequest>; now: Date }): CiRecord {
+  const { green, commit: c, previous, now } = input;
+  const retried = { ...(previous?.retried ?? {}) };
+  for (const r of input.retries) if (r.sha === c.sha) retried[r.run.name] = { run: r.run.id, at: iso(now) };
+  const req = input.requests.get(c.sha);
+  const extras = {
+    ...(Object.keys(retried).length > 0 ? { retried } : {}),
+    ...(req ? { request: { tag: req.tag, reason: req.reason, phases: req.phases, at: req.at } } : {}),
+  };
+  if (c.before === "revoked" || !c.verdict) {
+    return { schema: 1, commit: c.sha, branch: green.branch, state: "red", at: iso(now), revoked: true, phases: previous?.phases ?? {}, ...(previous?.failure ? { failure: previous.failure } : {}), ...extras };
+  }
+  const v = c.verdict;
+  // A pass whose tag an ignored tag blocks (#4031) is not green until a person clears the name.
+  const state: CiRecord["state"] =
+    c.before === "green" ? (v.verdict === "fail" ? "red" : "green") : v.verdict === "pass" ? (c.made ? "green" : "pending") : v.verdict === "fail" ? "red" : v.verdict;
+  const phases: Record<string, CiRecordPhase> = {};
+  for (const p of v.phases) {
+    phases[p.phase] = {
+      verdict: p.verdict,
+      build: buildOf(green, p.phase),
+      runs: p.runs.map(recordRun),
+      ...(p.reason ? { reason: p.reason } : {}),
+      ...(p.coveredBy ? { coveredBy: p.coveredBy } : {}),
+      ...(p.culprit ? { culprit: p.culprit } : {}),
+    };
+  }
+  return {
+    schema: 1,
+    commit: c.sha,
+    branch: green.branch,
+    state,
+    at: iso(now),
+    phases,
+    ...(v.failure ? { failure: { phase: v.failure.phase, run: recordRun(v.failure.run) } } : {}),
+    ...extras,
+  };
+}
+
+/** The record a commit that left the window still pending gets: each pending phase `unbuilt`, `aged-out`. */
+export function agedOut(record: CiRecord, now: Date): CiRecord {
+  const phases = Object.fromEntries(Object.entries(record.phases).map(([k, p]) => [k, p.verdict === "pending" ? { ...p, verdict: "unbuilt" as const, reason: "aged-out" as const } : p]));
+  const { request: _request, ...rest } = record;
+  return { ...rest, state: "unbuilt", at: iso(now), phases };
+}
+
+/** Whether two records say the same thing, the time each was written aside. */
+export function sameRecord(a: CiRecord | undefined, b: CiRecord): boolean {
+  if (!a) return false;
+  const { at: _a, ...x } = a;
+  const { at: _b, ...y } = b;
+  return JSON.stringify(x) === JSON.stringify(y);
+}
+
+export const recordPath = (sha: string) => `${CI_RECORDS_DIR}/${sha}.json`;
+
+function tryGit(top: string, args: string[]): string | null {
+  try {
+    return execFileSync("git", args, { cwd: top, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024 }).trimEnd();
+  } catch {
+    return null;
+  }
+}
+
+function parseRecord(text: string | null): CiRecord | undefined {
+  if (!text) return undefined;
+  try {
+    const r = JSON.parse(text) as CiRecord;
+    return r && r.schema === 1 && typeof r.commit === "string" && typeof r.state === "string" ? r : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** One commit's record, from the local `chant/lifecycle`. */
+export function readCiRecord(top: string, sha: string): CiRecord | undefined {
+  return parseRecord(tryGit(top, ["show", `${LEDGER_REF}:${recordPath(sha)}`]));
+}
+
+/** Every record on the local `chant/lifecycle`, by commit. Empty when the branch or the directory is missing. */
+export function readCiRecords(top: string): Map<string, CiRecord> {
+  const out = new Map<string, CiRecord>();
+  const names = tryGit(top, ["ls-tree", "--name-only", `${LEDGER_REF}:${CI_RECORDS_DIR}`]);
+  if (!names) return out;
+  for (const name of names.split("\n")) {
+    const m = /^([0-9a-f]{40,64})\.json$/.exec(name);
+    if (!m) continue;
+    const r = readCiRecord(top, m[1]);
+    if (r) out.set(m[1], r);
+  }
+  return out;
+}
+
+// ── Requests ─────────────────────────────────────────────────────────────────
+
+/** Every `ci/build/<sha>` tag with a record this reads, from local refs, by commit. */
+export function readBuildRequests(top: string): Map<string, BuildRequest> {
+  const out = new Map<string, BuildRequest>();
+  const raw = tryGit(top, ["for-each-ref", "--format=%(refname:lstrip=2)%00%(objecttype)%00%(contents)%01", `refs/tags/${CI_BUILD_TAG_PREFIX}`]);
+  if (!raw) return out;
+  for (const entry of raw.split("\u0001")) {
+    const [tag, type, contents] = entry.replace(/^\n/, "").split("\u0000");
+    if (!tag || type !== "tag" || !contents?.includes("{")) continue;
+    try {
+      const r = JSON.parse(contents.slice(contents.indexOf("{"))) as BuildRequest;
+      const sha = tag.slice(CI_BUILD_TAG_PREFIX.length);
+      if (r.schema === 1 && r.commit === sha && Array.isArray(r.phases) && typeof r.at === "string") out.set(sha, { ...r, tag });
+    } catch {
+      // A tag whose record does not parse asks for nothing.
+    }
+  }
+  return out;
+}
+
+/** The annotation of a request tag: a subject line, then the record. */
+export function buildRequestAnnotation(r: BuildRequest): string {
+  return `ci: build ${r.phases.join(", ")} at this commit (${r.reason})\n\n${JSON.stringify(r, null, 2)}\n`;
+}
+
+/** A request for `ci run --at <sha>`: every required phase, asked for by a person. */
+export function requestedBuild(green: CiGreen, commit: string, phases: readonly string[], now: Date): BuildRequest {
+  return request(green, commit, [...phases], "requested", now);
+}