@intentius/chant 0.124.10 → 0.124.12

package/src/gate-resume-run.ts

@@ -0,0 +1,171 @@
+/**
+ * Resume the job that waits at a gate (#3683), bundle-safe (#3854).
+ *
+ * A CI job that reaches a gate nobody approved records a pending fact on
+ * `chant/lifecycle` and exits 3. Nothing re-runs it when the approval lands,
+ * because a push to the ledger branch starts no pipeline. This module closes
+ * that loop through the forge's API.
+ *
+ * When the job runs in CI, the pending fact it records carries a
+ * {@link GateRunLocator}, read from the job's environment by
+ * {@link resolveGateRunLocator}: which forge, the API base, the repository,
+ * the run, and what the forge needs to start it again. After an approval,
+ * {@link resumeGateRun} starts it again:
+ *
+ * | Forge | Call | Token |
+ * |---|---|---|
+ * | GitHub | `POST /repos/{repo}/actions/runs/{run}/rerun-failed-jobs` | `actions: write` (the job's `GITHUB_TOKEN` with that permission, or a fine-grained token with Actions read and write) |
+ * | GitLab | `POST /projects/{id}/jobs/{job}/retry` | a project or personal access token with the `api` scope and the Developer role; `CI_JOB_TOKEN` cannot retry jobs |
+ * | Forgejo | `POST /repos/{repo}/actions/workflows/{file}/dispatches` on the run's branch | a token with the `write:repository` scope; Forgejo has no API to re-run a run, so it starts a new run of the workflow |
+ *
+ * GitHub re-runs the failed job and the jobs that need it, at the same
+ * commit. GitLab retries the job, and the jobs it skipped run after it. A
+ * Forgejo dispatch runs the whole workflow again at the branch's head, so the
+ * jobs before the gate run again too; they must be safe to repeat (a wave
+ * whose runs already applied plans nothing and applies nothing new).
+ *
+ * Resuming approves nothing. The resumed job decides the gate again from the
+ * ledger, so resuming a run whose approval does not count only makes it wait
+ * again. {@link resumeGateRun} skips a run that is still going, that ended
+ * well, or that was already resumed (a later GitHub attempt, a newer GitLab
+ * job of the same name, a newer Forgejo run of the workflow), so a scheduled
+ * resume job can call it every few minutes without starting a run twice.
+ *
+ * This module imports no workspace, ledger, schema or git code, so a product
+ * that ships one bundled file (terragucci) can import it as
+ * `@intentius/chant/gate-resume-run` and resume a job in process. Which
+ * approval answers a pending fact is `./op/gate-resume.ts`'s
+ * `resolutionAnswering`, which reads the gate's quorum rules and does pull the
+ * workspace in; that module re-exports everything here.
+ */
+
+import { ForgeApiError, type ForgeFetch, type ForgeKind } from "./pr-forge";
+import type { GateRunLocator } from "./op/gate-run-locator";
+
+export { isGateRunLocator, resolveGateRunLocator, type GateRunLocator } from "./op/gate-run-locator";
+
+/** What {@link resumeGateRun} did. */
+export type GateResumeOutcome =
+  | { status: "resumed"; forge: ForgeKind; how: string; url?: string }
+  | { status: "skipped"; forge: ForgeKind; reason: string; url?: string }
+  /** Under `dryRun` (#3858): the run is gone and would be started again; nothing was started. */
+  | { status: "would-resume"; forge: ForgeKind; how: string; url?: string };
+
+export interface ResumeGateRunOptions {
+  token: string;
+  /** The approval's time. A Forgejo run of the workflow created after it means the run was already resumed. */
+  since?: string;
+  fetch?: ForgeFetch;
+  /**
+   * Read the run as a resume would, and start nothing (#3858): say
+   * `would-resume` where it would start it. The calls are reads, so a token
+   * with read access to the forge's runs is enough.
+   */
+  dryRun?: boolean;
+}
+
+const trimSlash = (s: string): string => s.replace(/\/+$/, "");
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+
+function client(base: string, headers: Record<string, string>, fetchImpl: ForgeFetch) {
+  return async (method: string, path: string, body?: unknown): Promise<unknown> => {
+    const url = `${trimSlash(base)}${path}`;
+    const res = await fetchImpl(url, {
+      method,
+      headers: { ...headers, ...(body !== undefined ? { "Content-Type": "application/json" } : {}) },
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    });
+    const text = await res.text();
+    if (!res.ok) throw new ForgeApiError(method, url, res.status, text);
+    if (!text) return null;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  };
+}
+
+/**
+ * Start the job a pending fact's locator names again, or say why not. Throws
+ * {@link ForgeApiError} when the forge refuses a call, such as a token
+ * without the access the table in the module doc lists.
+ */
+export async function resumeGateRun(loc: GateRunLocator, opts: ResumeGateRunOptions): Promise<GateResumeOutcome> {
+  const fetchImpl = opts.fetch ?? (globalThis.fetch as unknown as ForgeFetch);
+  const url = loc.url ? { url: loc.url } : {};
+  const skip = (reason: string): GateResumeOutcome => ({ status: "skipped", forge: loc.forge, reason, ...url });
+  const wouldResume = (how: string): GateResumeOutcome => ({ status: "would-resume", forge: loc.forge, how: `would ${how}`, ...url });
+
+  if (loc.forge === "github") {
+    const call = client(loc.api, { Authorization: `Bearer ${opts.token}`, Accept: "application/vnd.github+json" }, fetchImpl);
+    const path = `/repos/${loc.repo}/actions/runs/${loc.run}`;
+    const run = await call("GET", path);
+    if (!isObject(run)) throw new Error(`GET ${path} returned no run`);
+    if (run.status !== "completed") return skip(`run ${loc.run} is ${String(run.status)}, not finished`);
+    const attempt = typeof run.run_attempt === "number" ? run.run_attempt : undefined;
+    if (loc.attempt !== undefined && attempt !== undefined && attempt > loc.attempt) {
+      return skip(`run ${loc.run} was already re-run (attempt ${attempt}; attempt ${loc.attempt} waited)`);
+    }
+    if (run.conclusion === "success") return skip(`run ${loc.run} succeeded`);
+    if (opts.dryRun) return wouldResume(`re-run the failed jobs of run ${loc.run}`);
+    await call("POST", `${path}/rerun-failed-jobs`, {});
+    return { status: "resumed", forge: "github", how: `re-ran the failed jobs of run ${loc.run}`, ...url };
+  }
+
+  if (loc.forge === "gitlab") {
+    const call = client(loc.api, { "PRIVATE-TOKEN": opts.token }, fetchImpl);
+    const project = `/projects/${encodeURIComponent(decodeURIComponent(loc.repo))}`;
+    const job = await call("GET", `${project}/jobs/${loc.job}`);
+    if (!isObject(job)) throw new Error(`GET ${project}/jobs/${loc.job} returned no job`);
+    const status = String(job.status);
+    if (status === "success") return skip(`job ${loc.job} succeeded`);
+    if (!["failed", "canceled", "skipped"].includes(status)) return skip(`job ${loc.job} is ${status}, not finished`);
+    const name = loc.jobName ?? (typeof job.name === "string" ? job.name : undefined);
+    if (name) {
+      // The pipeline's jobs list leaves retried jobs out, so the job of this name is its newest try.
+      const jobs = await call("GET", `${project}/pipelines/${loc.run}/jobs?per_page=100`);
+      const newest = Array.isArray(jobs) ? jobs.find((j) => isObject(j) && j.name === name) : undefined;
+      if (isObject(newest) && String(newest.id) !== String(loc.job)) {
+        return skip(`job ${loc.job} (${name}) was already retried as job ${String(newest.id)}`);
+      }
+    }
+    if (opts.dryRun) return wouldResume(`retry job ${loc.job}`);
+    const retried = await call("POST", `${project}/jobs/${loc.job}/retry`);
+    const id = isObject(retried) && retried.id !== undefined ? ` as job ${String(retried.id)}` : "";
+    return { status: "resumed", forge: "gitlab", how: `retried job ${loc.job}${id}`, ...url };
+  }
+
+  const call = client(loc.api, { Authorization: `token ${opts.token}`, Accept: "application/json" }, fetchImpl);
+  const repo = `/repos/${loc.repo}`;
+  const run = await call("GET", `${repo}/actions/runs/${loc.run}`);
+  if (!isObject(run)) throw new Error(`GET ${repo}/actions/runs/${loc.run} returned no run`);
+  const status = String(run.status);
+  if (status === "success") return skip(`run ${loc.run} succeeded`);
+  if (["waiting", "running", "blocked", "unknown"].includes(status)) return skip(`run ${loc.run} is ${status}, not finished`);
+  const listed = await call("GET", `${repo}/actions/runs?workflow_id=${encodeURIComponent(loc.workflow!)}&limit=50`);
+  const runs = isObject(listed) && Array.isArray(listed.workflow_runs) ? listed.workflow_runs : Array.isArray(listed) ? listed : [];
+  // Forgejo reports `created` in whole seconds.
+  const since = opts.since ? Math.floor(new Date(opts.since).getTime() / 1000) * 1000 : undefined;
+  const later = runs.find(
+    (r) =>
+      isObject(r) && Number(r.id) > Number(loc.run) &&
+      (r.prettyref === undefined || r.prettyref === loc.ref) &&
+      (since === undefined || (typeof r.created === "string" && new Date(r.created).getTime() >= since)),
+  );
+  if (isObject(later)) return skip(`run ${String(later.id)} of ${loc.workflow} started after the approval`);
+  if (opts.dryRun) return wouldResume(`dispatch ${loc.workflow} on ${loc.ref}`);
+  await call("POST", `${repo}/actions/workflows/${encodeURIComponent(loc.workflow!)}/dispatches`, { ref: loc.ref });
+  return { status: "resumed", forge: "forgejo", how: `dispatched ${loc.workflow} on ${loc.ref}`, ...url };
+}
+
+/**
+ * The token a resume uses: `CHANT_FORGE_TOKEN`, else the forge's own
+ * (`GITHUB_TOKEN` or `GH_TOKEN` on GitHub and Forgejo, `GITLAB_TOKEN` on
+ * GitLab), the same order the pull-request loop reads (`../pr-forge.ts`).
+ */
+export function resumeTokenFromEnv(forge: ForgeKind, env: Record<string, string | undefined> = process.env): string | undefined {
+  if (env.CHANT_FORGE_TOKEN) return env.CHANT_FORGE_TOKEN;
+  return forge === "gitlab" ? env.GITLAB_TOKEN : env.GITHUB_TOKEN ?? env.GH_TOKEN;
+}

package/src/lifecycle/gate-applied.ts

@@ -19,6 +19,7 @@
 
 import { samePlanDigest } from "./plan-digest";
 import type { GateAuditApply } from "./gate-audit";
+import type { GateRunLocator } from "../op/gate-run-locator";
 
 /** One approval a wave applied under: the approval of `planDigest` made at `approvedAt` was used. */
 export interface AppliedGateRecord {
@@ -38,6 +39,37 @@ export interface AppliedGateRecord {
   review?: { pr?: number; head?: string };
   runId?: string;
   commit?: string;
+  /**
+   * Where the run applying runs (#3858), as a pending fact's `resume` names
+   * it. A line that carries one and has no {@link FinishedGateRecord} is an
+   * apply that may have stopped: `chant run resume` starts that run again
+   * once it is gone, and the wave applies the rest under the same approval.
+   */
+  resume?: GateRunLocator;
+}
+
+/**
+ * A line of `applied.jsonl` that a wave applying under an approval writes
+ * (#3858): chant's own `applied` line, or a product's `changes` line beside
+ * it (terragucci's, which names the changes the approved plans make). Both
+ * name the approval the apply ran under.
+ */
+export type AppliedGateLine = Omit<AppliedGateRecord, "kind"> & { kind: "applied" | "changes" };
+
+/**
+ * How the apply an applied line names ended, in the same file (#3858). A
+ * product writes it when the apply finishes; an apply that was killed writes
+ * none. `applied` is that line's `timestamp`.
+ */
+export interface FinishedGateRecord {
+  version: 1;
+  kind: "finished";
+  op: string;
+  gate: string;
+  planDigest: string;
+  applied: string;
+  result: "applied" | "failed";
+  timestamp: string;
 }
 
 /** Where the applied lines of `op` live on `chant/lifecycle`: the directory and the file, as `writeBlobToPath` takes them. */
@@ -67,6 +99,36 @@ export function parseAppliedGateLines(text: string): AppliedGateRecord[] {
 
 const time = (iso: string): number => new Date(iso).getTime();
 
+/**
+ * Every line of an `applied.jsonl` file a resume reads (#3858): the
+ * `applied` and `changes` lines, and the `finished` lines that say how an
+ * apply ended. Oldest first; a line that is none of them is skipped.
+ */
+export function parseAppliedGateFile(text: string): { applied: AppliedGateLine[]; finished: FinishedGateRecord[] } {
+  const applied: AppliedGateLine[] = [];
+  const finished: FinishedGateRecord[] = [];
+  for (const line of text.split("\n").map((l) => l.trim()).filter(Boolean)) {
+    let r: Record<string, unknown>;
+    try {
+      r = JSON.parse(line) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+    if (r?.version !== 1 || typeof r.gate !== "string" || typeof r.planDigest !== "string" || typeof r.timestamp !== "string") continue;
+    if ((r.kind === "applied" || r.kind === "changes") && typeof r.approvedAt === "string") {
+      applied.push({ op: "", approvedBy: "", ...r } as unknown as AppliedGateLine);
+    } else if (r.kind === "finished" && typeof r.applied === "string" && (r.result === "applied" || r.result === "failed")) {
+      finished.push({ op: "", ...r } as unknown as FinishedGateRecord);
+    }
+  }
+  return { applied, finished };
+}
+
+/** The finished line for the apply `line` names, or undefined while it has none. */
+export function finishedApply(finished: readonly FinishedGateRecord[], line: Pick<AppliedGateLine, "gate" | "planDigest" | "timestamp">): FinishedGateRecord | undefined {
+  return finished.find((f) => f.gate === line.gate && samePlanDigest(f.planDigest, line.planDigest) && time(f.applied) === time(line.timestamp));
+}
+
 /**
  * Whether an approval is spent: a wave applied under an approval of the same
  * gate and digest made at or after it. One that names no digest is never
@@ -76,7 +138,7 @@ const time = (iso: string): number => new Date(iso).getTime();
  * review not yet recorded has no `timestamp`.
  */
 export function isApprovalSpent(
-  applied: readonly AppliedGateRecord[],
+  applied: readonly Pick<AppliedGateRecord, "gate" | "planDigest" | "approvedAt" | "review">[],
   approval: { gate: string; planDigest?: string; timestamp?: string; review?: { pr?: number; head?: string } },
 ): boolean {
   const digest = approval.planDigest;

package/src/lifecycle/gate-ledger.test.ts

@@ -446,7 +446,13 @@ describe("gate ledger newline termination (#3849)", () => {
   test("every append ends the file in a newline, with no blank or merged lines", async () => {
     await withTestDir(async (dir) => {
       await initRepo(dir);
-      await appendPendingGate({ op: "nl-op", gate: "g1", planDigest: "sha256:" + "a".repeat(64) } as never, { cwd: dir });
+      await appendPendingGate(
+        {
+          op: "nl-op", gate: "g1", planDigest: "sha256:" + "a".repeat(64),
+          timestamp: "2026-01-01T00:00:00.000Z", expiresAt: "2026-01-08T00:00:00.000Z",
+        },
+        { cwd: dir },
+      );
       const one = await readBlobFromPath("_gates", "nl-op.jsonl", { cwd: dir });
       expect(one!.endsWith("\n")).toBe(true);
       await appendGateResolution(

package/src/lifecycle/gate-ledger.ts

@@ -45,7 +45,7 @@ import { isNeverOverMcpGateOp } from "../op/gate-name";
 import { sortedJsonReplacer } from "../utils";
 import { currentGateOrigin, type GateOrigin } from "./gate-origin";
 import type { GateApprover, GatePolicyDecision, ResolvedGateApproval } from "../op/gate-approval";
-import type { GateRunLocator } from "../op/gate-resume";
+import type { GateRunLocator } from "../op/gate-run-locator";
 import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git";
 
 // The facts a pending record is written with live apart, so a bundle can import them without git (#3816).

package/src/lifecycle/git.ts

@@ -5,8 +5,9 @@
  * no working tree changes.
  */
 import { getRuntime } from "../runtime-adapter";
-import { resolveMemberLedger } from "./member-ledger";
+import { memberLedgerPrefix, resolveMemberLedger } from "./member-ledger";
 import { LIFECYCLE_LOCAL_NOTE } from "./local-note";
+import type { LedgerReadPort } from "./ledger-port";
 
 const STATE_BRANCH = "chant/lifecycle";
 
@@ -18,9 +19,29 @@ const STATE_BRANCH = "chant/lifecycle";
  * build records) goes through here, so none of them names the prefix itself.
  * See ./member-ledger.ts for who counts as a member.
  */
-export async function ledgerDir(dir: string, opts?: { cwd?: string }): Promise<string> {
-  const { prefix } = await resolveMemberLedger(opts?.cwd ?? process.cwd());
-  return `${prefix}${dir}`;
+export async function ledgerDir(dir: string, opts?: LedgerLocation): Promise<string> {
+  return `${await ledgerPrefixOf(opts)}${dir}`;
+}
+
+/**
+ * Where to read, when the caller is not standing in the member it reads
+ * (#3865): a reader such as behold's lists many members from one checkout. Both
+ * fields override what `cwd` resolves to; `ledgerPrefix` wins over `member`.
+ */
+export interface LedgerLocation {
+  cwd?: string;
+  /** A member's name, or its path of names in a nested workspace, outermost first. `"."` and `[]` name the flat layout. */
+  member?: string | readonly string[];
+  /** The prefix `resolveMemberLedger` returns: `""`, or `_members/<member>/` per level. */
+  ledgerPrefix?: string;
+}
+
+async function ledgerPrefixOf(opts?: LedgerLocation): Promise<string> {
+  if (opts?.ledgerPrefix !== undefined) return opts.ledgerPrefix;
+  if (opts?.member !== undefined) {
+    return memberLedgerPrefix((typeof opts.member === "string" ? [opts.member] : [...opts.member]).filter((m) => m !== "."));
+  }
+  return (await resolveMemberLedger(opts?.cwd ?? process.cwd())).prefix;
 }
 
 /**
@@ -348,7 +369,7 @@ export async function writeLedgerFiles(
 export async function readBlobFromPath(
   environment: string,
   filename: string,
-  opts?: { cwd?: string },
+  opts?: LedgerLocation,
 ): Promise<string | null> {
   const rt = getRuntime();
   const dir = await ledgerDir(environment, opts);
@@ -507,7 +528,7 @@ export async function appendReleaseRecordLine(
  */
 export async function readReleaseLedgerLines(
   environment: string,
-  opts?: { cwd?: string },
+  opts?: LedgerLocation,
 ): Promise<string[]> {
   const content = await readBlobFromPath(environment, "releases.jsonl", opts);
   if (!content) return [];
@@ -520,7 +541,21 @@ export async function readReleaseLedgerLines(
  * `releases.jsonl` entry. Used by `chant components status` (no env arg) to
  * discover which environments to report on.
  */
-export async function listLedgerEnvironments(opts?: { cwd?: string }): Promise<string[]> {
+export async function listLedgerEnvironments(opts?: LedgerLocation): Promise<string[]> {
+  const envs: string[] = [];
+  for (const name of await listLedgerTrees(opts)) {
+    const hasLedger = await readBlobFromPath(name, "releases.jsonl", opts);
+    if (hasLedger) envs.push(name);
+  }
+  return envs.sort();
+}
+
+/**
+ * The directories directly under the ledger's base: the root for the flat
+ * layout, `_members/<member>/` for a member. `[]` when the branch, or the
+ * base, is absent.
+ */
+export async function listLedgerTrees(opts?: LedgerLocation): Promise<string[]> {
   const tip = await getStateBranchTip(opts?.cwd);
   if (!tip) return [];
   const rt = getRuntime();
@@ -535,18 +570,12 @@ export async function listLedgerEnvironments(opts?: { cwd?: string }): Promise<s
     { cwd: opts?.cwd },
   );
   if (rootResult.exitCode !== 0) return [];
-
-  const envs: string[] = [];
-  const lines = rootResult.stdout.trim().split("\n").filter(Boolean);
-  for (const line of lines) {
+  const trees: string[] = [];
+  for (const line of rootResult.stdout.trim().split("\n").filter(Boolean)) {
     const match = line.match(/^(\d+)\s+(\w+)\s+([0-9a-f]+)\t(.+)$/);
-    if (!match) continue;
-    const [, , type, , name] = match;
-    if (type !== "tree") continue;
-    const hasLedger = await readBlobFromPath(name, "releases.jsonl", opts);
-    if (hasLedger) envs.push(name);
+    if (match && match[2] === "tree") trees.push(match[4]);
   }
-  return envs.sort();
+  return trees;
 }
 
 /**
@@ -557,7 +586,7 @@ export async function listLedgerEnvironments(opts?: { cwd?: string }): Promise<s
  * manifest (`_builds/<digest>.json`) without duplicating this `git ls-tree
  * --name-only` call.
  */
-export async function listFilesInDir(dir: string, opts?: { cwd?: string }): Promise<string[]> {
+export async function listFilesInDir(dir: string, opts?: LedgerLocation): Promise<string[]> {
   const tip = await getStateBranchTip(opts?.cwd);
   if (!tip) return [];
   const rt = getRuntime();
@@ -1405,3 +1434,17 @@ function baseName(dir: string): string {
 function depth(dir: string): number {
   return dir === "" ? 0 : dir.split("/").length;
 }
+
+/**
+ * The branch's read side as a {@link LedgerReadPort} for the member `opts`
+ * names (#3865): what the bundle-safe readers (`./release-read.ts`,
+ * `./wave-plans.ts`) are handed. A product with its own way to read the
+ * branch passes its own port instead and never loads this module.
+ */
+export function gitLedgerReadPort(opts?: LedgerLocation): LedgerReadPort {
+  return {
+    read: (dir, file) => readBlobFromPath(dir, file, opts),
+    list: (dir) => listFilesInDir(dir, opts),
+    trees: () => listLedgerTrees(opts),
+  };
+}

package/src/lifecycle/ledger-port.ts

@@ -0,0 +1,17 @@
+/**
+ * The read side of `chant/lifecycle` that the bundle-safe readers take
+ * (#3865). Paths are relative to one project's ledger: the flat root, or a
+ * workspace member's `_members/<member>/`. Which of those a port reads is the
+ * port's business; `gitLedgerReadPort` (`./git.ts`) takes a member or a
+ * prefix, and a product that reads the branch its own way supplies its own.
+ *
+ * Types only, so a bundle that imports a reader loads no git code.
+ */
+export interface LedgerReadPort {
+  /** The file at `<dir>/<file>`, or null when the branch, the directory or the file is absent. */
+  read(dir: string, file: string): Promise<string | null>;
+  /** The names directly under `<dir>/`, or `[]` when absent. */
+  list(dir: string): Promise<string[]>;
+  /** The directories directly under the ledger's root: every environment, and `_gates`, `_wave-plans` and the rest. */
+  trees(): Promise<string[]>;
+}

package/src/lifecycle/ledger-readers-bundle.test.ts

@@ -0,0 +1,47 @@
+/**
+ * The release and wave-plan readers bundle small (#3865, as #3764 did for the
+ * gate audit). A product that shows a workspace member's environments or the
+ * recorded wave plans bundles one file with no TypeScript toolchain, so
+ * `@intentius/chant/lifecycle/release-read` and
+ * `@intentius/chant/lifecycle/wave-plans` must not reach `typescript`, esbuild,
+ * zod, git, or chant's fold, lint, codegen, workspace and op modules.
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { describe, expect, test } from "vitest";
+import { REPO } from "../workspace/__fixtures__/contract-repo";
+
+const BUDGET_BYTES = 16 * 1024;
+
+const FORBIDDEN = [/node_modules\//, /\/src\/fold\//, /\/src\/lint\//, /\/src\/codegen\//, /\/src\/workspace\//, /\/lifecycle\/git\.ts$/, /\/lifecycle\/member-ledger\.ts$/, /\/lifecycle\/release-ledger\.ts$/, /\/op\//];
+
+async function bundle(entry: string) {
+  const result = await build({
+    entryPoints: [join(REPO, "packages", "core", "src", "lifecycle", entry)],
+    bundle: true,
+    platform: "node",
+    format: "esm",
+    write: false,
+    metafile: true,
+    outdir: "out",
+    logLevel: "silent",
+  });
+  const inputs = Object.keys(result.metafile.inputs);
+  for (const pattern of FORBIDDEN) {
+    expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
+  }
+  const bytes = result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0);
+  expect(bytes).toBeLessThan(BUDGET_BYTES);
+  return inputs.map((i) => i.replace(/^.*?packages\//, "packages/")).sort();
+}
+
+describe("the ledger readers bundles", () => {
+  test("the wave plans reader holds itself and nothing else", async () => {
+    expect(await bundle("wave-plans.ts")).toEqual(["packages/core/src/lifecycle/wave-plans.ts"]);
+  });
+
+  test("the release reader holds itself and the legacy digest flag", async () => {
+    expect(await bundle("release-read.ts")).toEqual(["packages/core/src/lifecycle/legacy-digest.ts", "packages/core/src/lifecycle/release-read.ts"]);
+  });
+});

package/src/lifecycle/ledger-readers.test.ts

@@ -0,0 +1,139 @@
+/**
+ * #3865 — the readers a product uses for a workspace member's release
+ * environments and op-waves `_wave-plans` records: pure over a port, and the
+ * git port over a member's prefix.
+ */
+import { afterAll, describe, expect, test } from "vitest";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { LedgerReadPort } from "./ledger-port";
+import { gitLedgerReadPort, listLedgerEnvironments, writeLedgerFiles } from "./git";
+import { listReleaseEnvironmentsOn, parseReleaseLedger, readReleaseRecords } from "./release-read";
+import { listReleaseEnvironments, readReleaseLedger } from "./release-ledger";
+import { listWavePlanSpecs, parseHeadPlans, readAllHeadPlans, readHeadPlanDigests, readHeadPlans } from "./wave-plans";
+
+/** A port over a flat map of `<dir>/<file>` to text. */
+function memoryPort(files: Record<string, string>): LedgerReadPort {
+  return {
+    read: async (dir, file) => files[`${dir}/${file}`] ?? null,
+    list: async (dir) => [...new Set(Object.keys(files).filter((p) => p.startsWith(`${dir}/`)).map((p) => p.slice(dir.length + 1).split("/")[0]))],
+    trees: async () => [...new Set(Object.keys(files).map((p) => p.split("/")[0]))],
+  };
+}
+
+const record = (env: string, digest = "sha256:" + "a".repeat(64)) =>
+  JSON.stringify({ version: 1, component: "svc", env, digest, gitSha: "abc", runId: "r1", timestamp: "2026-01-01T00:00:00.000Z", actor: "ci" });
+
+const plans = (head: string, digests: string[]) =>
+  JSON.stringify({ version: 1, name: "ship", head, timestamp: "2026-01-01T00:00:00.000Z", waves: digests.map((digest, i) => ({ wave: i + 1, name: `w${i + 1}`, digest })) });
+
+describe("release readers over a port", () => {
+  test("list the environments that hold a ledger, sorted, and parse their records", async () => {
+    const port = memoryPort({
+      "staging/releases.jsonl": record("staging") + "\n",
+      "prod/releases.jsonl": record("prod") + "\nnot json\n" + JSON.stringify({ version: 1 }) + "\n",
+      "prod/snapshot.json": "{}",
+      "_gates/deploy.jsonl": "",
+    });
+    expect(await listReleaseEnvironmentsOn(port)).toEqual(["prod", "staging"]);
+    const { records, malformed } = await readReleaseRecords(port, "prod");
+    expect(records.map((r) => r.env)).toEqual(["prod"]);
+    expect(malformed).toBe(2);
+    expect(await readReleaseRecords(port, "nope")).toEqual({ records: [], malformed: 0 });
+  });
+
+  test("parseReleaseLedger skips a non-object line", () => {
+    expect(parseReleaseLedger(["null", "3"]).malformed).toBe(2);
+  });
+});
+
+describe("wave plans readers", () => {
+  const files = {
+    "_wave-plans/ship/aaa.json": plans("aaa", ["sha256:one", "sha256:two"]),
+    "_wave-plans/ship/bbb.json": plans("bbb", ["sha256:three"]),
+    "_wave-plans/ship/broken.json": "{",
+    "_wave-plans/other/ccc.json": plans("ccc", ["sha256:four"]),
+  };
+
+  test("read one head, and null for a missing or unreadable one", async () => {
+    const port = memoryPort(files);
+    expect((await readHeadPlans(port, "ship", "aaa"))?.waves.map((w) => w.digest)).toEqual(["sha256:one", "sha256:two"]);
+    expect(await readHeadPlans(port, "ship", "zzz")).toBeNull();
+    expect(await readHeadPlans(port, "ship", "broken")).toBeNull();
+  });
+
+  test("read every head of a spec, by head, with the digests by wave", async () => {
+    const port = memoryPort(files);
+    expect([...(await readAllHeadPlans(port, "ship")).keys()]).toEqual(["aaa", "bbb"]);
+    const digests = await readHeadPlanDigests(port, "ship");
+    expect(digests.get("aaa")!.get(2)).toBe("sha256:two");
+    expect(digests.get("bbb")!.get(1)).toBe("sha256:three");
+    expect(await listWavePlanSpecs(port)).toEqual(["other", "ship"]);
+  });
+
+  test("the parser refuses a record of another shape", () => {
+    expect(parseHeadPlans(null)).toBeNull();
+    expect(parseHeadPlans("[]")).toBeNull();
+    expect(parseHeadPlans(JSON.stringify({ version: 2, name: "a", head: "b", timestamp: "t", waves: [] }))).toBeNull();
+    expect(parseHeadPlans(JSON.stringify({ version: 1, name: "a", head: "b", timestamp: "t", waves: [{ wave: "1", name: "x", digest: "d" }] }))).toBeNull();
+  });
+});
+
+describe("a member's records on chant/lifecycle", () => {
+  const scratch: string[] = [];
+  afterAll(() => {
+    for (const d of scratch) rmSync(d, { recursive: true, force: true });
+  });
+
+  async function fixture(): Promise<string> {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-ledger-readers-")));
+    scratch.push(root);
+    const git = (...args: string[]) => {
+      const r = spawnSync("git", args, { cwd: root, encoding: "utf-8" });
+      if (r.status !== 0) throw new Error(r.stderr);
+    };
+    git("init", "-q", "-b", "main");
+    git("config", "user.email", "t@chant.dev");
+    git("config", "user.name", "T");
+    writeFileSync(join(root, "f"), "");
+    git("add", "-A");
+    git("commit", "-q", "-m", "init");
+    await writeLedgerFiles(
+      [
+        { path: "_members/api/prod/releases.jsonl", content: record("prod") + "\n" },
+        { path: "_members/api/staging/releases.jsonl", content: record("staging") + "\n" },
+        { path: "_members/web/edge/releases.jsonl", content: record("edge") + "\n" },
+        { path: "_members/api/_wave-plans/ship/aaa.json", content: plans("aaa", ["sha256:one"]) },
+        { path: "_members/web/_wave-plans/ship/bbb.json", content: plans("bbb", ["sha256:two"]) },
+        { path: "legacy/releases.jsonl", content: record("legacy") + "\n" },
+      ],
+      "seed",
+      { cwd: root },
+    );
+    return root;
+  }
+
+  test("listReleaseEnvironments and readReleaseLedger take a member or its prefix, from outside it", async () => {
+    const cwd = await fixture();
+    expect(await listReleaseEnvironments({ cwd, member: "api" })).toEqual(["prod", "staging"]);
+    expect(await listReleaseEnvironments({ cwd, ledgerPrefix: "_members/web/" })).toEqual(["edge"]);
+    expect(await listReleaseEnvironments({ cwd, member: "." })).toEqual(["legacy"]);
+    expect(await listLedgerEnvironments({ cwd })).toEqual(["legacy"]);
+    expect((await readReleaseLedger("prod", { cwd, member: "api" })).records).toHaveLength(1);
+    expect((await readReleaseLedger("prod", { cwd, member: "web" })).records).toHaveLength(0);
+    expect((await readReleaseLedger("prod", { cwd, ledgerPrefix: "_members/api/" })).records).toHaveLength(1);
+  });
+
+  test("the git port reads each member's wave plans and nothing of another's", async () => {
+    const cwd = await fixture();
+    const api = gitLedgerReadPort({ cwd, member: "api" });
+    const web = gitLedgerReadPort({ cwd, member: ["web"] });
+    expect([...(await readHeadPlanDigests(api, "ship")).entries()].map(([h, m]) => [h, [...m]])).toEqual([["aaa", [[1, "sha256:one"]]]]);
+    expect([...(await readAllHeadPlans(web, "ship")).keys()]).toEqual(["bbb"]);
+    expect(await listWavePlanSpecs(api)).toEqual(["ship"]);
+    expect(await listReleaseEnvironmentsOn(api)).toEqual(["prod", "staging"]);
+    expect(await listWavePlanSpecs(gitLedgerReadPort({ cwd, member: "." }))).toEqual([]);
+  });
+});