@intentius/chant 0.115.0 → 0.117.0

package/src/op/op-waves-run.ts

@@ -0,0 +1,325 @@
+/**
+ * What an Op waves job runs (#3679): `chant run wave --spec <file> --wave <k>`.
+ * `./op-waves.ts` holds the spec and the jobs; this plans a wave's runs,
+ * decides its gate and applies it.
+ *
+ * - Plan: each run's `plan` command writes a plan file; its `planDigest` is
+ *   the run's member digest, named by its target.
+ * - Decide: the wave's policy comes from the spec file at the base commit
+ *   (`git show <base>:<file>`), so a change cannot loosen its own gate. A
+ *   wave missing there, or a file missing there, is `always`. A wave that
+ *   needs an approval waits on `<gate>-wave-<k>` bound to
+ *   {@link waveSetDigest} over its members, and exits 3 when nobody approved
+ *   that digest.
+ * - Apply: each run's `apply` command. A share job (`--share i`) re-plans its
+ *   slice first and refuses, without applying it, a run whose plan digest is
+ *   not the one the deciding job recorded (exit 4).
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, posix } from "node:path";
+import { waveGateName, waveSetDigest, type WaveMember } from "../gated-waves";
+import { approveCommand, evaluateGate, gitGateLedgerPort, type GateLedgerPort } from "./gate";
+import {
+  OP_WAVE_DEFAULT_APPLY,
+  OP_WAVE_GATE_POLICIES,
+  assertOpWavesSpec,
+  opWaveRecordPath,
+  opWaveShare,
+  type OpWaveGatePolicy,
+  type OpWaveRun,
+  type OpWavesSpec,
+} from "./op-waves";
+
+/** What a run's plan command writes to `{plan}`. */
+export interface OpWavePlanFile {
+  planDigest: string;
+  /** The plan destroys, rewrites or otherwise needs a person under `on-destructive`. */
+  destructive?: boolean;
+  /** The plan changes nothing. */
+  empty?: boolean;
+}
+
+/** One run's plan, as the decision records it. */
+export interface OpWaveMember extends WaveMember {
+  op: string;
+  destructive?: boolean;
+  empty?: boolean;
+}
+
+/** Where a wave's policy came from. */
+export type OpWavePolicySource = "base" | "absent-at-base";
+
+/** A wave's decision: what was planned, the policy, and whether it may apply. */
+export interface OpWaveDecision {
+  wave: number;
+  name: string;
+  /** The op the gate is recorded under: the spec's name. */
+  op: string;
+  gate: string;
+  policy: OpWaveGatePolicy;
+  policySource: OpWavePolicySource;
+  /** The base commit the policy was read at. */
+  base: string;
+  digest: string;
+  members: OpWaveMember[];
+  /** `approved`: an approval of this digest stands. `not-required`: the policy lets it through. `waiting`: neither. */
+  status: "approved" | "not-required" | "waiting";
+  approvedBy?: string;
+  /** The command that approves this digest, when waiting. */
+  approve?: string;
+}
+
+/** Runs one argv; returns its exit code. Injected so tests run no processes. */
+export type OpWaveExec = (argv: string[], cwd: string) => number;
+
+const spawnExec: OpWaveExec = (argv, cwd) => {
+  const result = spawnSync(argv[0]!, argv.slice(1), { cwd, stdio: "inherit" });
+  if (result.error) throw result.error;
+  return result.status ?? 1;
+};
+
+/** Reads one file at one commit, or null when the commit has no such file. Injected for tests. */
+export type OpWaveShowAtBase = (base: string, path: string, cwd: string) => { sha: string; text: string | null };
+
+const gitShowAtBase: OpWaveShowAtBase = (base, path, cwd) => {
+  let sha: string;
+  try {
+    sha = execFileSync("git", ["rev-parse", "--verify", `${base}^{commit}`], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+  } catch {
+    throw new Error(
+      `the gate policy is read at ${base}, which this checkout does not have. ` +
+        `Check out the full history (fetch-depth: 0 on GitHub and Forgejo, GIT_DEPTH: "0" on GitLab), or set the spec's base.`,
+    );
+  }
+  try {
+    const text = execFileSync("git", ["show", `${sha}:./${path}`], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+    return { sha, text };
+  } catch {
+    return { sha, text: null };
+  }
+};
+
+/** Read a spec file, refusing anything that is not one. */
+export function parseOpWavesSpec(text: string, where: string): OpWavesSpec {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw new Error(`${where}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const waves = (parsed as { waves?: unknown } | null)?.waves;
+  const spec = (Array.isArray(waves) ? parsed : waves) as OpWavesSpec | undefined;
+  if (!spec || typeof spec !== "object" || !Array.isArray(spec.waves)) {
+    throw new Error(`${where} must hold an Op waves spec: { "name", "op", "plan", "waves": [...] }, or { "waves": <that>, "options": {...} }`);
+  }
+  return spec;
+}
+
+/**
+ * The policy of wave `name`, as the spec file at `base` declares it. The
+ * file or the wave missing there reads as `always`: a change that adds a
+ * wave, or the file, waits for a person the first time.
+ */
+export function readOpWavePolicy(
+  specFile: string,
+  name: string,
+  base: string,
+  cwd: string,
+  show: OpWaveShowAtBase = gitShowAtBase,
+): { policy: OpWaveGatePolicy; source: OpWavePolicySource; base: string } {
+  const { sha, text } = show(base, specFile.replace(/^\.\//, "").split("\\").join(posix.sep), cwd);
+  if (text === null) return { policy: "always", source: "absent-at-base", base: sha };
+  let spec: OpWavesSpec;
+  try {
+    spec = parseOpWavesSpec(text, `${specFile} at ${base}`);
+  } catch {
+    return { policy: "always", source: "absent-at-base", base: sha };
+  }
+  const wave = spec.waves.find((w) => w.name === name);
+  if (!wave) return { policy: "always", source: "absent-at-base", base: sha };
+  const policy = wave.gate ?? "always";
+  return { policy: OP_WAVE_GATE_POLICIES.includes(policy) ? policy : "always", source: "base", base: sha };
+}
+
+/** Fill one argv template for one run. */
+export function opWaveArgv(template: readonly string[], values: { op: string; target: string; wave: string; plan: string }): string[] {
+  return template.map((part) =>
+    part.replaceAll("{op}", values.op).replaceAll("{target}", values.target).replaceAll("{wave}", values.wave).replaceAll("{plan}", values.plan),
+  );
+}
+
+/** Where a run's plan file goes. */
+export function opWavePlanPath(spec: Pick<OpWavesSpec, "name">, wave: number, target: string): string {
+  return `.chant/op-waves/${spec.name}/wave-${wave}/${target.replace(/[^A-Za-z0-9._-]/g, "_")}.plan.json`;
+}
+
+export interface RunOpWaveOptions {
+  spec: OpWavesSpec;
+  specFile: string;
+  /** 1-based. */
+  wave: number;
+  /** Plan and decide only (a wide wave's deciding job). */
+  decide?: boolean;
+  /** Apply this 1-based share of a decided wave. */
+  share?: number;
+  /** Overrides the spec's base. */
+  base?: string;
+  cwd?: string;
+  gates?: GateLedgerPort;
+  exec?: OpWaveExec;
+  show?: OpWaveShowAtBase;
+  now?: string;
+  log?: (line: string) => void;
+}
+
+export interface RunOpWaveResult {
+  /** 0 applied (or decided), 1 a run failed, 3 waiting for an approval, 4 a plan moved since the decision. */
+  exitCode: number;
+  decision?: OpWaveDecision;
+  applied: string[];
+  failed: string[];
+  /** Runs a share job refused because their plan moved since the decision. */
+  moved: string[];
+}
+
+function planRun(
+  opts: Required<Pick<RunOpWaveOptions, "spec" | "wave">> & { cwd: string; exec: OpWaveExec },
+  waveName: string,
+  run: OpWaveRun,
+): OpWaveMember {
+  const op = run.op ?? opts.spec.op;
+  const plan = opWavePlanPath(opts.spec, opts.wave, run.target);
+  mkdirSync(dirname(join(opts.cwd, plan)), { recursive: true });
+  const code = opts.exec(opWaveArgv(opts.spec.plan, { op, target: run.target, wave: waveName, plan }), opts.cwd);
+  if (code !== 0) throw new Error(`planning ${run.target} exited ${code}`);
+  let file: OpWavePlanFile;
+  try {
+    file = JSON.parse(readFileSync(join(opts.cwd, plan), "utf-8")) as OpWavePlanFile;
+  } catch (err) {
+    throw new Error(`planning ${run.target} wrote no readable plan file at ${plan}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (typeof file.planDigest !== "string" || file.planDigest === "") {
+    throw new Error(`the plan file for ${run.target} (${plan}) has no planDigest`);
+  }
+  return {
+    member: run.target,
+    planDigest: file.planDigest,
+    op,
+    ...(file.destructive === true ? { destructive: true } : {}),
+    ...(file.empty === true ? { empty: true } : {}),
+  };
+}
+
+/** Whether `policy` lets a wave with these members through without an approval. */
+export function opWaveNeedsApproval(policy: OpWaveGatePolicy, members: readonly OpWaveMember[]): boolean {
+  if (policy === "never") return false;
+  if (members.every((m) => m.empty === true)) return false;
+  if (policy === "on-destructive") return members.some((m) => m.destructive === true);
+  return true;
+}
+
+/** Plan, decide and apply one wave, or one part of a wide wave. */
+export async function runOpWave(options: RunOpWaveOptions): Promise<RunOpWaveResult> {
+  const { spec, wave: k } = options;
+  assertOpWavesSpec(spec);
+  const cwd = options.cwd ?? process.cwd();
+  const exec = options.exec ?? spawnExec;
+  const log = options.log ?? ((line: string) => console.error(line));
+  const wave = spec.waves[k - 1];
+  if (!wave) throw new Error(`Op waves "${spec.name}" has ${spec.waves.length} waves; there is no wave ${k}.`);
+  const shares = wave.shares ?? 1;
+  if (options.share !== undefined && (options.share < 1 || options.share > shares)) {
+    throw new Error(`wave ${k} (${wave.name}) has ${shares} share${shares === 1 ? "" : "s"}; there is no share ${options.share}.`);
+  }
+  const ctx = { spec, wave: k, cwd, exec };
+  const recordPath = join(cwd, opWaveRecordPath(spec, k));
+  const result: RunOpWaveResult = { exitCode: 0, applied: [], failed: [], moved: [] };
+
+  if (options.share !== undefined) {
+    let decision: OpWaveDecision;
+    try {
+      decision = JSON.parse(readFileSync(recordPath, "utf-8")) as OpWaveDecision;
+    } catch {
+      throw new Error(`share ${options.share} of wave ${k} (${wave.name}) found no decision at ${opWaveRecordPath(spec, k)}. Run the deciding job first.`);
+    }
+    result.decision = decision;
+    if (decision.status === "waiting") {
+      log(`wave ${k} (${wave.name}) is waiting on ${decision.gate}; nothing applied. ${decision.approve ?? ""}`.trim());
+      return { ...result, exitCode: 3 };
+    }
+    const decided = new Map(decision.members.map((m) => [m.member, m.planDigest]));
+    for (const run of opWaveShare(wave.runs, options.share, shares)) {
+      const member = planRun(ctx, wave.name, run);
+      if (decided.get(run.target) !== member.planDigest) {
+        log(
+          `${run.target}: its plan moved since wave ${k} was decided, so it was not applied. ` +
+            `decided: ${decided.get(run.target) ?? "(not in the decision)"}; planned now: ${member.planDigest}`,
+        );
+        result.moved.push(run.target);
+        continue;
+      }
+      applyRun(spec, wave.name, k, run, cwd, exec, result, log);
+    }
+    result.exitCode = result.failed.length > 0 ? 1 : result.moved.length > 0 ? 4 : 0;
+    return result;
+  }
+
+  const members = wave.runs.map((run) => planRun(ctx, wave.name, run));
+  const digest = waveSetDigest(members);
+  const { policy, source, base } = readOpWavePolicy(options.specFile, wave.name, options.base ?? spec.base ?? "HEAD^1", cwd, options.show);
+  const gate = waveGateName(spec.gate ?? spec.name, k);
+  const decision: OpWaveDecision = { wave: k, name: wave.name, op: spec.name, gate, policy, policySource: source, base, digest, members, status: "not-required" };
+  if (opWaveNeedsApproval(policy, members)) {
+    const check = await evaluateGate(options.gates ?? gitGateLedgerPort({ cwd }), {
+      op: spec.name,
+      gate,
+      planDigest: digest,
+      description: `wave ${k} (${wave.name}): ${members.length} run${members.length === 1 ? "" : "s"}, gate ${policy}`,
+      ...(options.now ? { now: options.now } : {}),
+    });
+    if (check.satisfied) {
+      decision.status = "approved";
+      decision.approvedBy = check.resolution.resolvedBy;
+    } else {
+      decision.status = "waiting";
+      decision.approve = approveCommand(spec.name, gate, undefined, digest);
+    }
+  }
+  mkdirSync(dirname(recordPath), { recursive: true });
+  writeFileSync(recordPath, JSON.stringify(decision, null, 2) + "\n");
+  result.decision = decision;
+  log(
+    `wave ${k} (${wave.name}): gate ${policy} (read at ${base.slice(0, 12)}${source === "absent-at-base" ? ", where the wave is absent" : ""}), ` +
+      `digest ${digest}: ${decision.status}${decision.approvedBy ? ` by ${decision.approvedBy}` : ""}`,
+  );
+  if (decision.status === "waiting") {
+    log(`Nothing in wave ${k} or after it ran. Read the plans, then approve: ${decision.approve} (with --resume, the approval also starts this job again)`);
+    return { ...result, exitCode: 3 };
+  }
+  if (options.decide) return result;
+  for (const run of wave.runs) applyRun(spec, wave.name, k, run, cwd, exec, result, log);
+  result.exitCode = result.failed.length > 0 ? 1 : 0;
+  return result;
+}
+
+function applyRun(
+  spec: OpWavesSpec,
+  waveName: string,
+  k: number,
+  run: OpWaveRun,
+  cwd: string,
+  exec: OpWaveExec,
+  result: RunOpWaveResult,
+  log: (line: string) => void,
+): void {
+  const op = run.op ?? spec.op;
+  const plan = opWavePlanPath(spec, k, run.target);
+  const code = exec(opWaveArgv(spec.apply ?? OP_WAVE_DEFAULT_APPLY, { op, target: run.target, wave: waveName, plan }), cwd);
+  if (code === 0) result.applied.push(run.target);
+  else {
+    log(`${run.target}: apply exited ${code}`);
+    result.failed.push(run.target);
+  }
+}

package/src/op/op-waves.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { opWaveJobs, opWaveShare, type OpWavesSpec } from "./op-waves";
+import { runOpWave, type OpWaveExec, type OpWaveShowAtBase } from "./op-waves-run";
+import { memoryGateLedgerPort } from "./gate";
+import { waveSetDigest } from "../gated-waves";
+
+const spec: OpWavesSpec = {
+  name: "migrations",
+  op: "migrate",
+  plan: ["tool", "plan", "{target}", "--out", "{plan}"],
+  apply: ["tool", "apply", "{target}", "--plan", "{plan}"],
+  waves: [
+    { name: "dev", runs: [{ target: "dev" }], gate: "never" },
+    { name: "staging", runs: [{ target: "staging" }], gate: "on-destructive" },
+    { name: "prod", runs: [{ target: "t3" }, { target: "t1" }, { target: "t2" }], shares: 2 },
+  ],
+};
+
+describe("opWaveJobs", () => {
+  test("one job per wave, a deciding job and share jobs for a wide one, each wave needing the last", () => {
+    const jobs = opWaveJobs(spec, "waves.json");
+    expect(jobs.map((j) => [j.jobName, j.needs])).toEqual([
+      ["wave-1-dev", []],
+      ["wave-2-staging", ["wave-1-dev"]],
+      ["wave-3-prod-decide", ["wave-2-staging"]],
+      ["wave-3-prod-share-1", ["wave-3-prod-decide"]],
+      ["wave-3-prod-share-2", ["wave-3-prod-decide"]],
+    ]);
+    expect(jobs[2]!.command.join(" ")).toBe("chant run wave --spec waves.json --wave 3 --decide");
+    expect(jobs[4]!.command.join(" ")).toBe("chant run wave --spec waves.json --wave 3 --share 2");
+  });
+
+  test("shares slice the runs by target", () => {
+    const runs = spec.waves[2]!.runs;
+    expect(opWaveShare(runs, 1, 2).map((r) => r.target)).toEqual(["t1", "t2"]);
+    expect(opWaveShare(runs, 2, 2).map((r) => r.target)).toEqual(["t3"]);
+  });
+});
+
+describe("runOpWave", () => {
+  function harness(plans: Record<string, { planDigest: string; destructive?: boolean }>, policyAtBase: string | null) {
+    const cwd = mkdtempSync(join(tmpdir(), "op-waves-"));
+    const calls: string[] = [];
+    const exec: OpWaveExec = (argv, dir) => {
+      calls.push(argv.join(" "));
+      if (argv[1] === "plan") writeFileSync(join(dir, argv[4]!), JSON.stringify(plans[argv[2]!]));
+      return 0;
+    };
+    const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: policyAtBase });
+    return { cwd, calls, exec, show, done: () => rmSync(cwd, { recursive: true, force: true }) };
+  }
+  const digest = (n: string) => `sha256:${n.repeat(64)}`;
+
+  test("the policy comes from the base commit: a change that sets staging to never still waits", async () => {
+    const h = harness({ staging: { planDigest: digest("a"), destructive: true } }, JSON.stringify(spec));
+    const loosened = { ...spec, waves: spec.waves.map((w) => ({ ...w, gate: "never" as const })) };
+    const gates = memoryGateLedgerPort();
+    const result = await runOpWave({ spec: loosened, specFile: "waves.json", wave: 2, cwd: h.cwd, exec: h.exec, show: h.show, gates });
+    expect(result.exitCode).toBe(3);
+    expect(result.decision).toMatchObject({ policy: "on-destructive", policySource: "base", status: "waiting", gate: "migrations-wave-2" });
+    expect(gates.appended[0]!.planDigest).toBe(waveSetDigest([{ member: "staging", planDigest: digest("a") }]));
+    expect(h.calls.some((c) => c.startsWith("tool apply"))).toBe(false);
+    h.done();
+  });
+
+  test("an approval of the set digest lets the wave apply; a non-destructive plan needs none", async () => {
+    const h = harness({ staging: { planDigest: digest("a"), destructive: true } }, JSON.stringify(spec));
+    const set = waveSetDigest([{ member: "staging", planDigest: digest("a") }]);
+    const gates = memoryGateLedgerPort({
+      resolutions: [{ version: 1, op: "migrations", gate: "migrations-wave-2", resolvedBy: "alice", timestamp: "2026-10-10T00:00:00Z", planDigest: set }],
+    });
+    const approved = await runOpWave({ spec, specFile: "waves.json", wave: 2, cwd: h.cwd, exec: h.exec, show: h.show, gates });
+    expect(approved).toMatchObject({ exitCode: 0, applied: ["staging"], decision: { status: "approved", approvedBy: "alice" } });
+    h.done();
+
+    const quiet = harness({ staging: { planDigest: digest("c") } }, JSON.stringify(spec));
+    const free = await runOpWave({ spec, specFile: "waves.json", wave: 2, cwd: quiet.cwd, exec: quiet.exec, show: quiet.show, gates: memoryGateLedgerPort() });
+    expect(free).toMatchObject({ exitCode: 0, applied: ["staging"], decision: { status: "not-required" } });
+    quiet.done();
+  });
+
+  test("a share refuses a run whose plan moved since the decision", async () => {
+    const plans: Record<string, { planDigest: string }> = { t1: { planDigest: digest("1") }, t2: { planDigest: digest("2") }, t3: { planDigest: digest("3") } };
+    const h = harness(plans, JSON.stringify({ ...spec, waves: spec.waves.map((w) => ({ ...w, gate: "never" })) }));
+    const decided = await runOpWave({ spec, specFile: "waves.json", wave: 3, decide: true, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort() });
+    expect(decided).toMatchObject({ exitCode: 0, applied: [], decision: { status: "not-required" } });
+    plans.t2 = { planDigest: digest("9") };
+    const share = await runOpWave({ spec, specFile: "waves.json", wave: 3, share: 1, cwd: h.cwd, exec: h.exec, show: h.show });
+    expect(share).toMatchObject({ exitCode: 4, applied: ["t1"], moved: ["t2"] });
+    h.done();
+  });
+});

package/src/op/op-waves.ts

@@ -0,0 +1,250 @@
+/**
+ * Gated waves of Op runs (#3679): a pipeline that applies one Op per
+ * environment, or per target in a set, in order, each wave behind one gate.
+ *
+ * A product built on chant that applies a migration to dev, then staging, then
+ * prod, or the same change to every tenant database of an environment, used to
+ * render that ordering itself, once per forge, and compute each wave's set
+ * digest itself. This module holds the forge-neutral part: the spec, the jobs
+ * it becomes and the commands they run. Each forge lexicon (github, gitlab,
+ * forgejo) renders these jobs with its own transport, so the three cannot
+ * disagree about order or commands. `./op-waves-run.ts` is what the jobs run.
+ *
+ * ## Jobs
+ *
+ * A wave is one job, `wave-<k>-<name>`, running `chant run wave --spec <file>
+ * --wave <k>`: plan every run, decide the wave's gate, apply. A wide wave
+ * (`shares` > 1) is a deciding job that plans every run and decides the gate,
+ * plus `shares` jobs that each apply a slice of the runs and refuse a run
+ * whose plan moved since the decision. Each wave's jobs need the previous
+ * wave's last jobs, so a wave that waits (exit 3) or fails stops every later
+ * wave.
+ *
+ * ## The gate
+ *
+ * Wave k waits on `waveGateName(<gate>, k)`, recorded under the spec's name,
+ * bound to {@link waveSetDigest} over its runs' plan digests (`../gated-waves.ts`,
+ * the same digest a component fan-out's wave binds). Whether it waits at all
+ * is the wave's gate policy, read from the base commit's copy of the spec
+ * file, so a change cannot loosen the rule that gates its own merge.
+ */
+
+import type { OpEnvironment, OpSetupStep } from "../lexicon";
+
+/** When a wave waits for an approval. */
+export type OpWaveGatePolicy =
+  /** Whenever the wave changes something. */
+  | "always"
+  /** When a run's plan says it is destructive. */
+  | "on-destructive"
+  /** Never: only review and branch protection stand in front of the wave. */
+  | "never";
+
+export const OP_WAVE_GATE_POLICIES: readonly OpWaveGatePolicy[] = ["always", "on-destructive", "never"];
+
+/** One Op run in a wave: an Op applied to one target (an environment, a database, a tenant). */
+export interface OpWaveRun {
+  /** What the run applies to. Unique within its wave; it names the run in the set digest. */
+  target: string;
+  /** The Op to run. Default: the spec's `op`. */
+  op?: string;
+}
+
+/** One wave: runs that apply together, behind one gate. */
+export interface OpWave {
+  /** The wave's name, usually its environment. Lowercase letters, digits, `-` and `_`. */
+  name: string;
+  runs: OpWaveRun[];
+  /**
+   * When the wave waits. Default `"always"`. The runner reads this from the
+   * spec file at the base commit, never from the change being applied.
+   */
+  gate?: OpWaveGatePolicy;
+  /**
+   * Split the wave into a deciding job and this many share jobs, each
+   * applying a slice of the runs. Default 1: one job plans, decides and
+   * applies.
+   */
+  shares?: number;
+  /** The forge deployment environment the wave's jobs run in (GitHub and GitLab; Forgejo has none). */
+  environment?: OpEnvironment;
+  /** Variables for this wave's jobs alone. */
+  variables?: Record<string, string>;
+  /** Steps this wave's jobs run after the checkout, as `ScheduledOpSpec.setup`. */
+  setup?: OpSetupStep[];
+}
+
+/**
+ * An ordered list of waves of Op runs, as a pipeline and as the file its jobs
+ * read. Commands are argv templates; each `{op}`, `{target}`, `{wave}` and
+ * `{plan}` is replaced per run.
+ */
+export interface OpWavesSpec {
+  /** The pipeline's name, and the op the wave gates are recorded under (`chant approve <name> <gate>-wave-<k>`). */
+  name: string;
+  /** The Op a run runs when it names none. */
+  op: string;
+  /** The base gate name. Default: `name`. */
+  gate?: string;
+  /** Branches whose pushes run the waves. Default `["main"]`. */
+  branches?: string[];
+  /**
+   * The commit the gate policy is read from. Default `HEAD^1`, the first
+   * parent: on a merge or squash onto the branch, the branch before the change.
+   */
+  base?: string;
+  /**
+   * Plan one run and write its plan file to `{plan}`: JSON `{ "planDigest":
+   * string, "destructive"?: boolean, "empty"?: boolean }`. `destructive` is
+   * what `on-destructive` waits on; a wave whose runs are all `empty` never
+   * waits.
+   */
+  plan: string[];
+  /** Apply one run whose plan is at `{plan}`. Default `chant run {op} --env {target}`. */
+  apply?: string[];
+  waves: OpWave[];
+  /**
+   * A scheduled job that starts again a wave job whose approval has arrived
+   * (#3683): it runs `chant run resume --op <name>`, which re-runs the
+   * GitHub run, retries the GitLab job or dispatches the Forgejo workflow.
+   * It approves nothing. Absent, no such job is rendered and an approval is
+   * followed by `chant approve --resume` or a re-run by hand.
+   */
+  resume?: OpWavesResume;
+}
+
+/** The scheduled resume job of an Op waves pipeline (#3683). */
+export interface OpWavesResume {
+  /**
+   * Five-field cron, such as `"*\/10 * * * *"`. GitHub and Forgejo put it
+   * in the workflow; GitLab runs the job in a pipeline schedule you create,
+   * which sets the cron.
+   */
+  schedule: string;
+}
+
+/** The command a resume job runs. */
+export function opWavesResumeCommand(spec: Pick<OpWavesSpec, "name">): string[] {
+  return ["chant", "run", "resume", "--op", spec.name];
+}
+
+/** The default apply command. */
+export const OP_WAVE_DEFAULT_APPLY = ["chant", "run", "{op}", "--env", "{target}"];
+
+/** Where the runner keeps a wave's decision; a wide wave's deciding job hands it to its share jobs. */
+export function opWaveRecordPath(spec: Pick<OpWavesSpec, "name">, wave: number): string {
+  return `.chant/op-waves/${spec.name}/wave-${wave}.json`;
+}
+
+/** One generated job. */
+export interface OpWaveJob {
+  jobName: string;
+  /** 1-based wave number. */
+  wave: number;
+  /** The wave's name. */
+  waveName: string;
+  /** `wave`: plan, decide and apply. `decide`: plan and decide. `share`: apply one slice. */
+  kind: "wave" | "decide" | "share";
+  /** 1-based, on a share job. */
+  share?: number;
+  /** Jobs this one waits on. */
+  needs: string[];
+  /** The job's command, as argv. */
+  command: string[];
+  /** On a share job: the decision record to download. On a deciding job: the one to upload. */
+  record?: string;
+}
+
+const NAME = /^[a-z0-9][a-z0-9_-]*$/;
+
+/** Refuse a spec no job could run, naming what is wrong. */
+export function assertOpWavesSpec(spec: OpWavesSpec): void {
+  const where = `Op waves "${spec.name}"`;
+  if (!NAME.test(spec.name)) throw new Error(`${where}: the name must be lowercase letters, digits, "-" and "_"`);
+  if (!spec.op) throw new Error(`${where} names no \`op\`. Name the Op a run runs when it names none.`);
+  if (!Array.isArray(spec.plan) || spec.plan.length === 0) {
+    throw new Error(`${where} has no \`plan\` command. Each wave plans its runs to bind its gate to their plan digests.`);
+  }
+  if (!spec.plan.some((part) => part.includes("{plan}"))) {
+    throw new Error(`${where}: the \`plan\` command never names {plan}, the file it writes the plan digest to.`);
+  }
+  if (spec.waves.length === 0) throw new Error(`${where} has no waves.`);
+  if (spec.resume !== undefined && (typeof spec.resume.schedule !== "string" || spec.resume.schedule.trim().split(/\s+/).length !== 5)) {
+    throw new Error(`${where}: resume.schedule must be a five-field cron expression, such as "*/10 * * * *".`);
+  }
+  const names = new Set<string>();
+  for (const wave of spec.waves) {
+    if (!NAME.test(wave.name)) {
+      throw new Error(`${where}: wave "${wave.name}" must be named with lowercase letters, digits, "-" and "_"`);
+    }
+    if (names.has(wave.name)) throw new Error(`${where} names wave "${wave.name}" twice.`);
+    names.add(wave.name);
+    if (wave.gate !== undefined && !OP_WAVE_GATE_POLICIES.includes(wave.gate)) {
+      throw new Error(`${where}: wave "${wave.name}" has gate "${wave.gate}"; use ${OP_WAVE_GATE_POLICIES.join(", ")}.`);
+    }
+    if (wave.runs.length === 0) throw new Error(`${where}: wave "${wave.name}" has no runs.`);
+    const targets = new Set<string>();
+    for (const run of wave.runs) {
+      if (!run.target) throw new Error(`${where}: wave "${wave.name}" has a run with no target.`);
+      if (targets.has(run.target)) throw new Error(`${where}: wave "${wave.name}" names target "${run.target}" twice.`);
+      targets.add(run.target);
+    }
+    const shares = wave.shares ?? 1;
+    if (!Number.isInteger(shares) || shares < 1) {
+      throw new Error(`${where}: wave "${wave.name}" has shares ${wave.shares}; use a whole number from 1.`);
+    }
+    if (shares > wave.runs.length) {
+      throw new Error(`${where}: wave "${wave.name}" has ${shares} shares for ${wave.runs.length} runs, so a share would apply nothing.`);
+    }
+  }
+}
+
+/**
+ * The runs share `share` (1-based) of `shares` applies: the wave's runs sorted
+ * by target, cut into contiguous slices whose sizes differ by at most one.
+ */
+export function opWaveShare<T extends { target: string }>(runs: readonly T[], share: number, shares: number): T[] {
+  const sorted = [...runs].sort((a, b) => (a.target < b.target ? -1 : a.target > b.target ? 1 : 0));
+  const base = Math.floor(sorted.length / shares);
+  const extra = sorted.length % shares;
+  const start = (share - 1) * base + Math.min(share - 1, extra);
+  const size = base + (share <= extra ? 1 : 0);
+  return sorted.slice(start, start + size);
+}
+
+/**
+ * The jobs of an Op waves pipeline, in order. `specFile` is the spec's path
+ * from the job's working directory, which every command names.
+ */
+export function opWaveJobs(spec: OpWavesSpec, specFile: string): OpWaveJob[] {
+  assertOpWavesSpec(spec);
+  const jobs: OpWaveJob[] = [];
+  let previous: string[] = [];
+  spec.waves.forEach((wave, index) => {
+    const k = index + 1;
+    const command = ["chant", "run", "wave", "--spec", specFile, "--wave", String(k), ...(spec.base ? ["--base", spec.base] : [])];
+    const prefix = `wave-${k}-${wave.name}`;
+    const shares = wave.shares ?? 1;
+    if (shares === 1) {
+      jobs.push({ jobName: prefix, wave: k, waveName: wave.name, kind: "wave", needs: previous, command });
+      previous = [prefix];
+      return;
+    }
+    const record = opWaveRecordPath(spec, k);
+    const decide = `${prefix}-decide`;
+    jobs.push({ jobName: decide, wave: k, waveName: wave.name, kind: "decide", needs: previous, command: [...command, "--decide"], record });
+    const shareJobs: string[] = [];
+    for (let share = 1; share <= shares; share++) {
+      const jobName = `${prefix}-share-${share}`;
+      shareJobs.push(jobName);
+      jobs.push({ jobName, wave: k, waveName: wave.name, kind: "share", share, needs: [decide], command: [...command, "--share", String(share)], record });
+    }
+    previous = shareJobs;
+  });
+  return jobs;
+}
+
+/** The wave a job belongs to. */
+export function opWaveOf(spec: OpWavesSpec, job: Pick<OpWaveJob, "wave">): OpWave {
+  return spec.waves[job.wave - 1]!;
+}