@intentius/chant 0.124.11 → 0.124.13

package/src/lifecycle/gate-ledger.ts

@@ -45,6 +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 { GateApprovalSource } from "../op/op-waves";
 import type { GateRunLocator } from "../op/gate-run-locator";
 import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git";
 
@@ -288,6 +289,13 @@ export interface PendingGateRecord {
    * the run produced, and `chant operator status` to show quorum progress.
    */
   approval?: ResolvedGateApproval;
+  /**
+   * The approval mode an Op wave asked under (#3861): `ledger`, `pr-review` or
+   * `sealed`, as read at base. It says which approvals count for the gate, so a
+   * reader (behold, gate-audit) decides under the mode the wave used rather
+   * than inferring it from config. Not the quorum block in `approval`.
+   */
+  approvalMode?: GateApprovalSource;
   /**
    * The open question this gate waits on, on a gate that asks a decision
    * point (#3170). It is answered with `chant workspace points answer <id>`,

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([]);
+  });
+});

package/src/lifecycle/release-ledger.ts

@@ -29,8 +29,13 @@
  */
 
 import { sortedJsonReplacer } from "../utils";
-import { flagLegacyDigest, warnOnLegacyDigests, withoutReadFlags, type LegacyDigestFlag } from "./legacy-digest";
-import { appendReleaseRecordLine, readReleaseLedgerLines, listLedgerEnvironments as gitListLedgerEnvironments } from "./git";
+import { warnOnLegacyDigests, withoutReadFlags, type LegacyDigestFlag } from "./legacy-digest";
+import { appendReleaseRecordLine, readReleaseLedgerLines, listLedgerEnvironments as gitListLedgerEnvironments, type LedgerLocation } from "./git";
+import { parseReleaseLedger, validateReleaseRecord } from "./release-read";
+
+// The pure readers live apart, so a bundle can import them without git (#3865).
+export { validateReleaseRecord, parseReleaseLedger, releaseLedgerLines, readReleaseRecords, listReleaseEnvironmentsOn } from "./release-read";
+export type { LedgerReadPort } from "./ledger-port";
 
 /**
  * The id space a `ReleaseRecord.runId` lives in, and how to reach the run
@@ -172,17 +177,6 @@ export interface ReleaseRecord {
   redeploys?: ReleaseRef;
 }
 
-/** Required, non-empty-string fields every `ReleaseRecord` must carry. */
-const REQUIRED_STRING_FIELDS: Array<keyof ReleaseRecord> = [
-  "component",
-  "env",
-  "digest",
-  "gitSha",
-  "runId",
-  "timestamp",
-  "actor",
-];
-
 /** Thrown by `appendReleaseRecord` when the record is missing a required field — a release record can never be recorded partially, since it is never editable afterward. */
 export class InvalidReleaseRecordError extends Error {
   constructor(public readonly missing: string[]) {
@@ -191,16 +185,6 @@ export class InvalidReleaseRecordError extends Error {
   }
 }
 
-/** Validate that a release record carries every required field as a non-empty string. */
-export function validateReleaseRecord(record: Partial<ReleaseRecord>): string[] {
-  const missing: string[] = [];
-  for (const field of REQUIRED_STRING_FIELDS) {
-    const value = record[field];
-    if (typeof value !== "string" || value.length === 0) missing.push(field);
-  }
-  return missing;
-}
-
 /** Input a caller supplies to record one deploy — `version` is filled in, everything else is required (see `ReleaseRecord`). */
 export type ReleaseRecordInput = Omit<ReleaseRecord, "version" | "flags">;
 
@@ -284,24 +268,9 @@ export async function appendReleaseRecord(
  */
 export async function readReleaseLedger(
   environment: string,
-  opts?: { cwd?: string },
+  opts?: LedgerLocation,
 ): Promise<{ records: ReleaseRecord[]; malformed: number }> {
-  const lines = await readReleaseLedgerLines(environment, opts);
-  const records: ReleaseRecord[] = [];
-  let malformed = 0;
-  for (const line of lines) {
-    try {
-      const parsed = JSON.parse(line) as ReleaseRecord;
-      if (validateReleaseRecord(parsed).length > 0) {
-        malformed++;
-        continue;
-      }
-      // chant #2514 — a digest from before real SHA-256 is flagged, never re-keyed.
-      records.push(flagLegacyDigest(parsed, [parsed.digest, parsed.manifestDigest, parsed.inputDigest]));
-    } catch {
-      malformed++;
-    }
-  }
+  const { records, malformed } = parseReleaseLedger(await readReleaseLedgerLines(environment, opts));
   // chant #2514 — say once that this ledger holds values in the old form.
   warnOnLegacyDigests(
     records.flatMap((r) => [r.digest, r.manifestDigest, r.inputDigest]),
@@ -311,8 +280,12 @@ export async function readReleaseLedger(
   return { records, malformed };
 }
 
-/** List every environment that has release records on the orphan branch. */
-export async function listReleaseEnvironments(opts?: { cwd?: string }): Promise<string[]> {
+/**
+ * List every environment that has release records on the orphan branch. With
+ * `member` or `ledgerPrefix` (#3865) it lists that workspace member's, from
+ * wherever `cwd` is; without either, the member `cwd` resolves to.
+ */
+export async function listReleaseEnvironments(opts?: LedgerLocation): Promise<string[]> {
   return gitListLedgerEnvironments(opts);
 }
 

package/src/lifecycle/release-read.ts

@@ -0,0 +1,69 @@
+/**
+ * Reading release records without git (#3865). The parsing and the
+ * environment listing of `release-ledger.ts`, over a {@link LedgerReadPort}
+ * instead of a checkout, so a product bundles them in one file
+ * (`release-read-bundle.test.ts` holds the import graph). Pass
+ * `gitLedgerReadPort({ member })` from `./git.ts` to read a workspace member's
+ * ledger from a checkout, or a port of your own.
+ *
+ * `release-ledger.ts` reads through these too; its `readReleaseLedger` and
+ * `listReleaseEnvironments` also take `member` or `ledgerPrefix`.
+ */
+import { flagLegacyDigest } from "./legacy-digest";
+import type { LedgerReadPort } from "./ledger-port";
+import type { ReleaseRecord } from "./release-ledger";
+
+/** Required, non-empty-string fields every `ReleaseRecord` must carry. */
+const REQUIRED_STRING_FIELDS: Array<keyof ReleaseRecord> = ["component", "env", "digest", "gitSha", "runId", "timestamp", "actor"];
+
+/** The required fields a release record lacks as non-empty strings. */
+export function validateReleaseRecord(record: Partial<ReleaseRecord>): string[] {
+  const missing: string[] = [];
+  for (const field of REQUIRED_STRING_FIELDS) {
+    const value = record[field];
+    if (typeof value !== "string" || value.length === 0) missing.push(field);
+  }
+  return missing;
+}
+
+/** The lines of a `releases.jsonl` file: trimmed, blanks dropped. */
+export function releaseLedgerLines(text: string | null): string[] {
+  return text ? text.split("\n").map((line) => line.trim()).filter(Boolean) : [];
+}
+
+/**
+ * Parse release ledger lines, oldest first. A malformed line is counted and
+ * skipped; a digest recorded by the old 32-bit hash reads back flagged
+ * (#2514), never re-keyed.
+ */
+export function parseReleaseLedger(lines: readonly string[]): { records: ReleaseRecord[]; malformed: number } {
+  const records: ReleaseRecord[] = [];
+  let malformed = 0;
+  for (const line of lines) {
+    try {
+      const parsed = JSON.parse(line) as ReleaseRecord;
+      if (parsed === null || typeof parsed !== "object" || validateReleaseRecord(parsed).length > 0) {
+        malformed++;
+        continue;
+      }
+      records.push(flagLegacyDigest(parsed, [parsed.digest, parsed.manifestDigest, parsed.inputDigest]));
+    } catch {
+      malformed++;
+    }
+  }
+  return { records, malformed };
+}
+
+/** Every release record of `environment` the port holds, oldest first. */
+export async function readReleaseRecords(port: LedgerReadPort, environment: string): Promise<{ records: ReleaseRecord[]; malformed: number }> {
+  return parseReleaseLedger(releaseLedgerLines(await port.read(environment, "releases.jsonl")));
+}
+
+/** The environments with a `releases.jsonl`, sorted: the port's root directories that hold one. */
+export async function listReleaseEnvironmentsOn(port: LedgerReadPort): Promise<string[]> {
+  const envs: string[] = [];
+  for (const name of await port.trees()) {
+    if (await port.read(name, "releases.jsonl")) envs.push(name);
+  }
+  return envs.sort();
+}

package/src/lifecycle/wave-plans.ts

@@ -0,0 +1,93 @@
+/**
+ * The plans an op-waves `pr-review` wave records for a pull request's head
+ * (#3684, #3865): `_wave-plans/<name>/<head>.json` on `chant/lifecycle`,
+ * written by `chant run wave --record-plans` (`../op/op-waves-run.ts`) and read
+ * after the merge, where the review of that head approves the digests it
+ * planned and only those (`../op/gate-review.ts`).
+ *
+ * The parser and the readers here touch no git, no clock and no file: they
+ * take a {@link LedgerReadPort}, so a product that shows or checks the
+ * records bundles them in one file (`wave-plans-bundle.test.ts` holds the
+ * import graph). `gitLedgerReadPort({ member })` from `./git.ts` reads a
+ * workspace member's records (`_members/<member>/_wave-plans/...`) from a
+ * checkout.
+ */
+import type { LedgerReadPort } from "./ledger-port";
+
+/** The digests each wave planned at one commit, recorded for a review of it to approve. */
+export interface HeadPlans {
+  version: 1;
+  /** The Op waves spec's name. */
+  name: string;
+  /** The commit the waves were planned at: a pull request's head. */
+  head: string;
+  timestamp: string;
+  waves: Array<{ wave: number; name: string; digest: string }>;
+}
+
+/** Where {@link HeadPlans} for `head` live on `chant/lifecycle`: `_wave-plans/<name>/<head>.json`. */
+export const HEAD_PLANS_DIR = "_wave-plans";
+
+export function headPlansPath(name: string, head: string): { dir: string; file: string } {
+  return { dir: `${HEAD_PLANS_DIR}/${name}`, file: `${head}.json` };
+}
+
+/**
+ * Parse one record. Null when the text is not JSON or not a version 1 plans
+ * record: a record that cannot be read approves nothing.
+ */
+export function parseHeadPlans(text: string | null): HeadPlans | null {
+  if (!text) return null;
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (value === null || typeof value !== "object") return null;
+  const r = value as Record<string, unknown>;
+  if (r.version !== 1 || typeof r.name !== "string" || typeof r.head !== "string" || typeof r.timestamp !== "string" || !Array.isArray(r.waves)) return null;
+  const waves: HeadPlans["waves"] = [];
+  for (const w of r.waves) {
+    if (w === null || typeof w !== "object") return null;
+    const { wave, name, digest } = w as Record<string, unknown>;
+    if (typeof wave !== "number" || typeof name !== "string" || typeof digest !== "string") return null;
+    waves.push({ wave, name, digest });
+  }
+  return { version: 1, name: r.name, head: r.head, timestamp: r.timestamp, waves };
+}
+
+/** The record for `head` of the spec `name`, or null when none was recorded or it cannot be read. */
+export async function readHeadPlans(port: LedgerReadPort, name: string, head: string): Promise<HeadPlans | null> {
+  const { dir, file } = headPlansPath(name, head);
+  return parseHeadPlans(await port.read(dir, file));
+}
+
+/** Every record of the spec `name` by head. A file that is not a record is left out. */
+export async function readAllHeadPlans(port: LedgerReadPort, name: string): Promise<Map<string, HeadPlans>> {
+  const out = new Map<string, HeadPlans>();
+  const { dir } = headPlansPath(name, "");
+  for (const file of (await port.list(dir)).sort()) {
+    if (!file.endsWith(".json")) continue;
+    const plans = parseHeadPlans(await port.read(dir, file));
+    if (plans) out.set(file.slice(0, -".json".length), plans);
+  }
+  return out;
+}
+
+/** The digests a record holds by wave number. */
+export function waveDigests(plans: HeadPlans): Map<number, string> {
+  return new Map(plans.waves.map((w) => [w.wave, w.digest]));
+}
+
+/** The digests recorded for each head of the spec `name`: head, then wave number, to digest. */
+export async function readHeadPlanDigests(port: LedgerReadPort, name: string): Promise<Map<string, Map<number, string>>> {
+  const out = new Map<string, Map<number, string>>();
+  for (const [head, plans] of await readAllHeadPlans(port, name)) out.set(head, waveDigests(plans));
+  return out;
+}
+
+/** The names of the specs that have records: the directories under `_wave-plans/`. */
+export async function listWavePlanSpecs(port: LedgerReadPort): Promise<string[]> {
+  return (await port.list(HEAD_PLANS_DIR)).sort();
+}

package/src/lint/typescript.ts

@@ -0,0 +1,18 @@
+/**
+ * The TypeScript compiler API chant parses with, for lexicon lint rules and
+ * language services (#3864).
+ *
+ * Core parses every source file with its own `typescript` dependency, which
+ * stays on 5.x. A lexicon that imported `typescript` itself got the project's
+ * copy instead, and a project on TypeScript 7 has no JS compiler API there:
+ * `ts.isImportDeclaration` is undefined and every rule threw. Even when two
+ * 5.x copies load, their `SyntaxKind` numbers can differ between minors, so a
+ * rule must test nodes with the same module that built them.
+ *
+ * Lexicons import `ts` from here, never from "typescript":
+ *
+ *     import { ts } from "@intentius/chant/lint/typescript";
+ */
+import * as ts from "typescript";
+
+export { ts };