@intentius/chant 0.124.10 → 0.124.12

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 };

package/src/meta/lexicon-typescript-import.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "vitest";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Lexicon source takes the TypeScript compiler API from
+ * `@intentius/chant/lint/typescript`, never from `typescript` (chant #3864).
+ *
+ * A bare `typescript` import in a published lexicon resolves to the project's
+ * copy. On TypeScript 7 that copy has no JS compiler API, so every sql lint
+ * rule threw `ts.isImportDeclaration is not a function` and `chant graph`
+ * refused the project. Core parses with its own 5.x, and a rule has to test
+ * nodes with that same module. Tests are exempt: they run in this repo, where
+ * `typescript` is 5.x.
+ */
+const repoRoot = fileURLToPath(new URL("../../../../", import.meta.url));
+const lexiconsDir = join(repoRoot, "lexicons");
+
+function sourceFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) out.push(...sourceFiles(path));
+    else if (/\.(ts|mts|js|mjs)$/.test(name) && !/\.test\.ts$/.test(name)) out.push(path);
+  }
+  return out;
+}
+
+const BARE_TYPESCRIPT = /^\s*(import|export)\b[^;]*?\bfrom\s+["']typescript["']|\b(require|import)\(\s*["']typescript["']\s*\)/m;
+
+describe("lexicon source imports TypeScript through chant (#3864)", () => {
+  test("no lexicon src file imports `typescript` directly", () => {
+    const offenders = readdirSync(lexiconsDir)
+      .map((name) => join(lexiconsDir, name, "src"))
+      .filter((dir) => statSync(dir, { throwIfNoEntry: false })?.isDirectory())
+      .flatMap(sourceFiles)
+      .filter((file) => BARE_TYPESCRIPT.test(readFileSync(file, "utf-8")))
+      .map((file) => relative(repoRoot, file));
+    expect(offenders, 'import { ts } from "@intentius/chant/lint/typescript" instead').toEqual([]);
+  });
+});

package/src/op/gate-resume-plan-bundle.test.ts

@@ -0,0 +1,49 @@
+/**
+ * The resume plan bundles small (#3858).
+ *
+ * A product that resumes in its own job, such as terragucci's, decides what
+ * to resume with `@intentius/chant/op/gate-resume-plan` and ships as one
+ * bundled file. This bundles it the way such a product would and reads
+ * esbuild's own list of what went in: no git ledger, no gate evaluation, no
+ * workspace, CLI or Ajv code.
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { describe, expect, test } from "vitest";
+import { REPO } from "../workspace/__fixtures__/contract-repo";
+
+const FORBIDDEN = [
+  /node_modules\//,
+  /\/src\/cli\//,
+  /\/src\/workspace\//,
+  /\/src\/fold\//,
+  /\/src\/lint\//,
+  /\/src\/codegen\//,
+  /\/src\/op\/activities\//,
+  /\/src\/op\/gate\.ts$/,
+  /\/src\/op\/gate-resume\.ts$/,
+  /\/src\/lifecycle\/git\.ts$/,
+  /\/src\/lifecycle\/gate-ledger\.ts$/,
+];
+
+describe("the gate-resume-plan bundle", () => {
+  test("holds the resume decision and its pure helpers only", async () => {
+    const result = await build({
+      entryPoints: [join(REPO, "packages", "core", "src", "op", "gate-resume-plan.ts")],
+      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(32 * 1024);
+  });
+});

package/src/op/gate-resume-plan.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, test } from "vitest";
+import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
+import { parseAppliedGateFile } from "../lifecycle/gate-applied";
+import { planGateResumes } from "./gate-resume-plan";
+import type { GateRunLocator } from "./gate-run-locator";
+
+const DIGEST = `sha256:${"a".repeat(64)}`;
+const OTHER = `sha256:${"b".repeat(64)}`;
+const NOW = "2026-10-01T06:00:00Z";
+const waited: GateRunLocator = { forge: "github", api: "https://api.github.com", repo: "acme/infra", run: "42", attempt: 1 };
+const applying: GateRunLocator = { forge: "github", api: "https://api.github.com", repo: "acme/infra", run: "57", attempt: 1 };
+
+const pending = (gate: string, timestamp: string, extra: Partial<PendingGateRecord> = {}): PendingGateRecord => ({
+  version: 1,
+  kind: "pending",
+  op: "tf-apply",
+  gate,
+  timestamp,
+  expiresAt: "2026-10-03T00:00:00Z",
+  planDigest: DIGEST,
+  resume: waited,
+  ...extra,
+});
+const approval = (gate: string, timestamp: string, by = "alice"): GateResolutionRecord => ({ version: 1, op: "tf-apply", gate, resolvedBy: by, timestamp, planDigest: DIGEST });
+
+const file = (...lines: object[]) => parseAppliedGateFile(lines.map((l) => JSON.stringify(l)).join("\n"));
+const appliedLine = (gate: string, approvedAt: string, timestamp: string, extra: Record<string, unknown> = {}) => ({
+  version: 1, kind: "applied", op: "tf-apply", gate, planDigest: DIGEST, approvedAt, approvedBy: "alice", timestamp, ...extra,
+});
+
+describe("planGateResumes (#3858)", () => {
+  test("an approval that answers a standing fact and is not spent: resumable, approved", () => {
+    const [c] = planGateResumes({ op: "tf-apply", pending: [pending("wave-1", "2026-10-01T00:00:00Z")], resolutions: [approval("wave-1", "2026-10-01T01:00:00Z")], now: NOW });
+    expect(c).toMatchObject({ source: "pending", gate: "wave-1", resumable: true, reason: "approved", approvedBy: "alice", approvedAt: "2026-10-01T01:00:00Z", run: waited });
+  });
+
+  test("nothing answers it: not resumable", () => {
+    expect(planGateResumes({ op: "tf-apply", pending: [pending("wave-1", "2026-10-01T00:00:00Z")], resolutions: [], now: NOW })).toMatchObject([
+      { resumable: false, reason: "not-approved" },
+    ]);
+  });
+
+  test("an approval a wave already applied under is spent: not resumable, and the report names the apply", () => {
+    const lines = file(appliedLine("wave-1", "2026-10-01T01:00:00Z", "2026-10-01T02:00:00Z", { wave: { number: 1, name: "network" } }));
+    const [c] = planGateResumes({ op: "tf-apply", pending: [pending("wave-1", "2026-10-01T00:00:00Z")], resolutions: [approval("wave-1", "2026-10-01T01:00:00Z")], ...lines, now: NOW });
+    expect(c).toMatchObject({ resumable: false, reason: "spent", spent: { appliedAt: "2026-10-01T02:00:00Z", approvedAt: "2026-10-01T01:00:00Z", wave: { number: 1 } } });
+    expect(c!.message).toContain("spent");
+  });
+
+  test("a spent approval of another digest, or an older one, spends nothing here", () => {
+    const lines = file(appliedLine("wave-1", "2026-10-01T01:00:00Z", "2026-10-01T02:00:00Z", { planDigest: OTHER }), appliedLine("wave-1", "2026-09-30T00:00:00Z", "2026-09-30T01:00:00Z"));
+    const [c] = planGateResumes({ op: "tf-apply", pending: [pending("wave-1", "2026-10-01T00:00:00Z")], resolutions: [approval("wave-1", "2026-10-01T01:00:00Z")], ...lines, now: NOW });
+    expect(c).toMatchObject({ resumable: true, reason: "approved" });
+  });
+
+  test("a decision point's answer the gate passes on: answered, unless the resolution citing it is spent", () => {
+    const answer = { point: "prod-apply", id: "q-1", path: "points/q-1.json" };
+    const fact = pending("wave-1", "2026-10-01T00:00:00Z", { answer });
+    const questions = new Map([["q-1", { id: "q-1", state: "answered" as const, answer: true, answeredBy: ["alice"], answeredOn: "2026-10-01T01:00:00Z" }]]);
+    expect(planGateResumes({ op: "tf-apply", pending: [fact], resolutions: [], questions, now: NOW })).toMatchObject([{ resumable: true, reason: "answered", approvedBy: "alice" }]);
+
+    const cited: GateResolutionRecord = { ...approval("wave-1", "2026-10-01T03:00:00Z", "alice"), answer };
+    const lines = file(appliedLine("wave-1", "2026-10-01T03:00:00Z", "2026-10-01T03:00:01Z"));
+    expect(planGateResumes({ op: "tf-apply", pending: [fact], resolutions: [cited], ...lines, questions, now: NOW })).toMatchObject([{ resumable: false, reason: "spent" }]);
+  });
+
+  test("an apply that recorded its run and never finished is a stopped apply", () => {
+    // terragucci's shape: chant's `applied` line, then the product's `changes` line with the run.
+    const lines = file(
+      appliedLine("wave-2", "2026-10-01T01:00:00Z", "2026-10-01T02:00:00Z"),
+      appliedLine("wave-2", "2026-10-01T01:00:00Z", "2026-10-01T02:00:01Z", { kind: "changes", resume: applying, changes: [{ address: "aws_s3_bucket.a" }] }),
+    );
+    const out = planGateResumes({ op: "tf-apply", pending: [pending("wave-2", "2026-10-01T00:00:00Z")], resolutions: [approval("wave-2", "2026-10-01T01:00:00Z")], ...lines, now: NOW });
+    expect(out).toMatchObject([
+      { source: "pending", reason: "spent", resumable: false },
+      { source: "stopped", gate: "wave-2", reason: "stopped", resumable: true, run: applying, approvedBy: "alice", stopped: { appliedAt: "2026-10-01T02:00:01Z", approvedAt: "2026-10-01T01:00:00Z", kind: "changes" } },
+    ]);
+  });
+
+  test("a finished line, a newer pending fact, or no run locator: not a stopped apply", () => {
+    const changes = appliedLine("wave-2", "2026-10-01T01:00:00Z", "2026-10-01T02:00:01Z", { kind: "changes", resume: applying });
+    const finished = { version: 1, kind: "finished", op: "tf-apply", gate: "wave-2", planDigest: DIGEST, applied: "2026-10-01T02:00:01Z", result: "failed", timestamp: "2026-10-01T02:30:00Z" };
+    const stopped = (lines: ReturnType<typeof file>, p: PendingGateRecord[] = []) =>
+      planGateResumes({ op: "tf-apply", pending: p, resolutions: [], ...lines, now: NOW }).filter((c) => c.source === "stopped");
+    expect(stopped(file(changes))).toHaveLength(1);
+    expect(stopped(file(changes, finished))).toEqual([]);
+    expect(stopped(file(changes), [pending("wave-2", "2026-10-01T03:00:00Z")])).toEqual([]);
+    expect(stopped(file(appliedLine("wave-2", "2026-10-01T01:00:00Z", "2026-10-01T02:00:00Z")))).toEqual([]);
+    // A newer apply under another approval, with no run, supersedes the stopped one.
+    expect(stopped(file(changes, appliedLine("wave-2", "2026-10-01T04:00:00Z", "2026-10-01T05:00:00Z")))).toEqual([]);
+  });
+
+  test("a gate filter, and an expired fact, leave facts out", () => {
+    const facts = [pending("wave-1", "2026-10-01T00:00:00Z"), pending("wave-2", "2026-10-01T00:00:00Z", { expiresAt: "2026-10-01T05:00:00Z" })];
+    expect(planGateResumes({ op: "tf-apply", pending: facts, resolutions: [], now: NOW }).map((c) => c.gate)).toEqual(["wave-1"]);
+    expect(planGateResumes({ op: "tf-apply", pending: facts, resolutions: [], now: NOW, gate: "wave-2" })).toEqual([]);
+  });
+
+  test("a fact with an approval block needs the tally to be answered", () => {
+    const fact = pending("wave-1", "2026-10-01T00:00:00Z", { approval: { mode: "off" } as unknown as PendingGateRecord["approval"] });
+    expect(planGateResumes({ op: "tf-apply", pending: [fact], resolutions: [approval("wave-1", "2026-10-01T01:00:00Z")], now: NOW })).toMatchObject([
+      { resumable: false, reason: "not-approved", message: expect.stringContaining("tally") },
+    ]);
+    const answering = () => approval("wave-1", "2026-10-01T01:00:00Z");
+    expect(planGateResumes({ op: "tf-apply", pending: [fact], resolutions: [], now: NOW, answering })).toMatchObject([{ resumable: true, reason: "approved" }]);
+  });
+});