@intentius/chant 0.115.0 → 0.116.0

package/src/cli/handlers/run-generate.ts

@@ -26,7 +26,8 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { discoverOps } from "../../op/discover";
-import { generateOpsPipeline } from "../../op/generate-pipeline";
+import { generateOpsPipeline, generateOpWavesPipeline } from "../../op/generate-pipeline";
+import { parseOpWavesSpec } from "../../op/op-waves-run";
 import { GENERATED_MARKER } from "../../discovery/files";
 import { findWorkspaceRoot } from "../../project-root";
 import type { ComponentPipelineOptions, ScheduledOpSpec } from "../../lexicon";
@@ -71,10 +72,59 @@ export function readOpSpecFile(path: string): SpecFile {
   return { ops: ops as ScheduledOpSpec[], ...(options ? { options } : {}) };
 }
 
+/** True when a `--spec` file holds an Op waves spec (#3679) rather than a list of scheduled Ops. */
+function holdsOpWaves(path: string): boolean {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8")) as { waves?: unknown } | null;
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) && parsed.waves !== undefined;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * `chant run --generate <provider> --spec <waves.json>` (#3679): one pipeline
+ * file of ordered, gated waves of Op runs. Its jobs read the same file.
+ */
+async function runOpWavesGenerate(ctx: CommandContext, provider: string, specPath: string): Promise<number> {
+  const { args } = ctx;
+  let spec;
+  let options: Record<string, unknown> | undefined;
+  try {
+    const text = readFileSync(resolve(specPath), "utf-8");
+    spec = parseOpWavesSpec(text, `--spec ${specPath}`);
+    const parsed = JSON.parse(text) as { options?: Record<string, unknown> };
+    options = Array.isArray((parsed as { waves?: unknown }).waves) ? undefined : parsed.options;
+  } catch (err) {
+    console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    return 1;
+  }
+  const result = await generateOpWavesPipeline(spec, provider, { ...options, specFile: specPath.replace(/^\.\//, "") });
+  if (!result.success) {
+    console.error(formatError({ message: result.error ?? "Failed to generate the Op waves pipeline" }));
+    return 1;
+  }
+  const header = opPipelineHeader(provider, specPath);
+  const outDir = args.output ?? DEFAULT_OP_PIPELINE_DIRS[provider] ?? ".";
+  const files = (result.files ?? []).map((f) => ({ name: f.name, path: join(outDir, f.name), content: header + f.yaml }));
+  if (args.format === "json") {
+    console.log(JSON.stringify({ files, jobs: result.jobs ?? [] }, null, 2));
+    return 0;
+  }
+  for (const file of files) {
+    const target = resolve(file.path);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, file.content);
+    console.error(formatSuccess(`wrote ${formatBold(file.path)}`));
+  }
+  return 0;
+}
+
 export async function runOpGenerate(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
   const provider = args.generate as string;
   const specPath = args.opsSpec;
+  if (specPath && holdsOpWaves(resolve(specPath))) return runOpWavesGenerate(ctx, provider, specPath);
 
   let ops: ScheduledOpSpec[];
   let options: ComponentPipelineOptions | undefined;

package/src/cli/handlers/run-wave.ts

@@ -0,0 +1,43 @@
+/**
+ * `chant run wave --spec <file> --wave <k>` (#3679): the command each job of
+ * a generated Op waves pipeline runs. See `../../op/op-waves-run.ts`.
+ */
+
+import { readFileSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { parseOpWavesSpec, runOpWave } from "../../op/op-waves-run";
+import { formatError } from "../format";
+import type { CommandContext } from "../registry";
+
+export async function runOpWaveCommand(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const specFile = args.opsSpec;
+  if (!specFile || args.wave === undefined) {
+    console.error(formatError({
+      message: "`chant run wave` needs --spec <file> and --wave <k>",
+      hint: "Run it as a generated Op waves pipeline does: chant run wave --spec <file> --wave <k> [--decide | --share <i>]",
+    }));
+    return 1;
+  }
+  if (args.decide && args.share !== undefined) {
+    console.error(formatError({ message: "--decide and --share are two different jobs; pass one" }));
+    return 1;
+  }
+  try {
+    const path = resolve(specFile);
+    const spec = parseOpWavesSpec(readFileSync(path, "utf-8"), `--spec ${specFile}`);
+    const result = await runOpWave({
+      spec,
+      specFile: relative(process.cwd(), path),
+      wave: args.wave,
+      ...(args.decide ? { decide: true } : {}),
+      ...(args.share !== undefined ? { share: args.share } : {}),
+      ...(args.base ? { base: args.base } : {}),
+    });
+    if (args.json) console.log(JSON.stringify(result, null, 2));
+    return result.exitCode;
+  } catch (err) {
+    console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    return 1;
+  }
+}

package/src/cli/main.ts

@@ -36,6 +36,7 @@ import { runGraph } from "./handlers/graph";
 import { runExplain } from "./handlers/explain";
 import { runSearch } from "./handlers/search";
 import { runOp, runOpList, runOpStatus, runOpApprove, runOpSignalRenamed, runOpCancel, runOpLog } from "./handlers/run";
+import { runOpWaveCommand } from "./handlers/run-wave";
 import { runOperator, runOperatorStatus, runOperatorLog, runApprove } from "./handlers/operator";
 import { runEmulator } from "./handlers/emulator";
 import { splitJoinedFlags, dispatchCommandGroup, collectCommandGroups, formatCommandGroupsHelp, type CommandGroup } from "./command-group";
@@ -106,6 +107,7 @@ const BOOLEAN_FLAGS = new Set([
   "--allow-code",
   "--root-only",
   "--generated",
+  "--decide",
 ]);
 
 /**
@@ -355,6 +357,13 @@ export function parseArgs(args: string[]): ParsedArgs {
       const wave = Number(raw);
       if (!Number.isInteger(wave) || wave < 1) throw new Error(`--wave needs a wave number from 1: got "${raw ?? ""}"`);
       result.wave = wave;
+    } else if (arg === "--decide") {
+      result.decide = true;
+    } else if (arg === "--share") {
+      const raw = args[++i];
+      const share = Number(raw);
+      if (!Number.isInteger(share) || share < 1) throw new Error(`--share needs a share number from 1: got "${raw ?? ""}"`);
+      result.share = share;
     } else if (arg === "--canary") {
       const raw = args[++i];
       if (!raw || raw.startsWith("-")) throw new Error("--canary needs a component name: --canary <name>[,<name>...]");
@@ -909,6 +918,10 @@ Ops:
   run approve <op> <gate>  Record a gate's resolution and wake the runtime
   run cancel <name>     Cancel the active run (requires --force)
   run log <name>        Show run history for an Op
+  run wave --spec <file> --wave <k>  Plan, gate and apply wave k of an Op
+                        waves spec (#3679): the job a generated waves
+                        pipeline runs. --decide plans and decides only;
+                        --share <i> applies one share of a decided wave
   run --generate <provider>  Write one CI pipeline file per scheduled Op for
                         github, gitlab or forgejo (#2533), from every Op that
                         declares a schedule or from --spec <file.json>.
@@ -1815,6 +1828,7 @@ export const commandRegistry: CommandDef[] = [
   { name: "run signal", handler: runOpSignalRenamed },
   { name: "run cancel", handler: runOpCancel },
   { name: "run log", handler: runOpLog },
+  { name: "run wave", handler: runOpWaveCommand },
   { name: "run", handler: runOp },
 
   { name: "operator status", handler: runOperatorStatus },

package/src/cli/registry.ts

@@ -248,8 +248,12 @@ export interface ParsedArgs {
    * <name>`, which generates one CI job per wave.
    */
   waveGate?: string;
-  /** `chant components fan-out --wave <n>` (#3049) — run wave `n` of a `--wave-gate` fan-out and no other. */
+  /** `chant components fan-out --wave <n>` (#3049) — run wave `n` of a `--wave-gate` fan-out and no other. Also `chant run wave --wave <k>` (#3679). */
   wave?: number;
+  /** `chant run wave --decide` (#3679) — plan a wide wave and decide its gate, applying nothing. */
+  decide?: boolean;
+  /** `chant run wave --share <i>` (#3679) — apply share `i` of a decided wide wave. */
+  share?: number;
   /** `chant components fan-out --canary <component>` (#3049), repeatable — components that form wave 1. */
   canary?: string[];
   /**

package/src/lexicon.ts

@@ -10,6 +10,7 @@ import type { AgentConfigImporter } from "./agents/importer";
 import type { ArtifactIntegrity } from "./lexicon-integrity";
 import type { GatedWavePipelineOptions } from "./components/gated-wave-pipeline";
 import type { PrLoopPipelineOptions } from "./components/pr-pipeline";
+import type { OpWaveJob, OpWavesSpec } from "./op/op-waves";
 import type { OkfFile } from "./okf";
 import type { CompletionContext, CompletionItem, HoverContext, HoverInfo, CodeActionContext, CodeAction } from "./lsp/types";
 import type { McpToolContribution, McpResourceContribution } from "./mcp/types";
@@ -900,6 +901,23 @@ export interface OpPipelineResult {
   jobs: OpPipelineJob[];
 }
 
+/**
+ * Options for an Op waves pipeline (#3679): the generic knobs of
+ * {@link ComponentPipelineOptions} that apply to every wave job, and the path
+ * of the spec file the jobs read.
+ */
+export interface OpWavesPipelineOptions
+  extends Pick<ComponentPipelineOptions, "image" | "beforeScript" | "extraScript" | "variables" | "opsStage" | "opsFileName"> {
+  /** The spec's path from the repository root. Every job runs `chant run wave --spec <specFile>`. */
+  specFile: string;
+}
+
+/** An Op waves pipeline: one file, and its jobs in order. */
+export interface OpWavesPipelineResult {
+  files: OpPipelineFile[];
+  jobs: OpWaveJob[];
+}
+
 /**
  * Live status of a single deploy unit (a CloudFormation stack, a K8s release, …)
  * addressed by its deployed name — the per-component presence signal
@@ -1325,6 +1343,14 @@ export interface LexiconPlugin {
     options?: ComponentPipelineOptions,
   ): OpPipelineResult;
 
+  /**
+   * Render ordered waves of Op runs, each behind one gate (#3679,
+   * `./op/op-waves.ts`): one job per wave, or a deciding job and share jobs
+   * for a wide one, each wave needing the one before. Only CI-provider
+   * lexicons implement this.
+   */
+  generateOpWavesPipeline?(spec: OpWavesSpec, options: OpWavesPipelineOptions): OpWavesPipelineResult;
+
   /**
    * Host Op runs — the seam `chant run <op> --on <this lexicon>` dispatches to
    * (#2121, epic #2114). Core ships one provider of its own, `local`, and

package/src/op/generate-pipeline.ts

@@ -25,7 +25,9 @@ import {
   type ScheduledOpSpec,
   type OpPipelineFile,
   type OpPipelineJob,
+  type OpWavesPipelineOptions,
 } from "../lexicon";
+import { assertOpWavesSpec, type OpWaveJob, type OpWavesSpec } from "./op-waves";
 
 /**
  * Load a lexicon's plugin (`@intentius/chant-lexicon-<name>`) to reach its
@@ -115,3 +117,50 @@ export async function generateOpsPipeline(
   const { files, jobs } = plugin.generateOpPipeline(withOpSchedules(ops, discovered.ops), options);
   return { success: true, files, jobs };
 }
+
+/** Result of generating an Op waves pipeline (#3679). */
+export interface GenerateOpWavesPipelineResult {
+  success: boolean;
+  files?: OpPipelineFile[];
+  jobs?: OpWaveJob[];
+  error?: string;
+}
+
+/**
+ * Render ordered waves of Op runs for `lexicon` (#3679, `./op-waves.ts`):
+ * check the spec, check that every Op it names exists, then hand it to the
+ * lexicon's `generateOpWavesPipeline`.
+ */
+export async function generateOpWavesPipeline(
+  spec: OpWavesSpec,
+  lexicon: string,
+  options: OpWavesPipelineOptions,
+  cwd?: string,
+): Promise<GenerateOpWavesPipelineResult> {
+  const plugin = await loadLexiconPlugin(lexicon);
+  if (!plugin?.generateOpWavesPipeline) {
+    return {
+      success: false,
+      error: `Lexicon "${lexicon}" does not render Op waves (no generateOpWavesPipeline). GitLab, GitHub, and Forgejo do.`,
+    };
+  }
+  try {
+    assertOpWavesSpec(spec);
+  } catch (err) {
+    return { success: false, error: err instanceof Error ? err.message : String(err) };
+  }
+  const discovered = await discoverOps({ cwd });
+  if (discovered.errors.length > 0) return { success: false, error: discovered.errors.join("\n") };
+  const named = [...new Set([spec.op, ...spec.waves.flatMap((w) => w.runs.map((r) => r.op ?? spec.op))])];
+  const unknown = named.filter((name) => !discovered.ops.has(name));
+  if (unknown.length > 0) {
+    const known = [...discovered.ops.keys()].sort().join(", ");
+    return { success: false, error: `Unknown Op(s): ${unknown.join(", ")}.${known ? ` Known Ops: ${known}` : " No Ops discovered."}` };
+  }
+  try {
+    const { files, jobs } = plugin.generateOpWavesPipeline(spec, options);
+    return { success: true, files, jobs };
+  } catch (err) {
+    return { success: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}

package/src/op/index.ts

@@ -49,8 +49,19 @@ export type {
 } from "./receipt-store";
 export { discoverOps } from "./discover";
 export type { DiscoveredOp, OpDiscoveryResult } from "./discover";
-export { generateOpsPipeline, withOpSchedules } from "./generate-pipeline";
-export type { GenerateOpsPipelineResult } from "./generate-pipeline";
+export { generateOpsPipeline, generateOpWavesPipeline, withOpSchedules } from "./generate-pipeline";
+export type { GenerateOpsPipelineResult, GenerateOpWavesPipelineResult } from "./generate-pipeline";
+export {
+  OP_WAVE_DEFAULT_APPLY,
+  OP_WAVE_GATE_POLICIES,
+  assertOpWavesSpec,
+  opWaveJobs,
+  opWaveRecordPath,
+  opWaveShare,
+} from "./op-waves";
+export type { OpWave, OpWaveGatePolicy, OpWaveJob, OpWaveRun, OpWavesSpec } from "./op-waves";
+export { opWaveNeedsApproval, parseOpWavesSpec, readOpWavePolicy, runOpWave } from "./op-waves-run";
+export type { OpWaveDecision, OpWaveMember, OpWavePlanFile, RunOpWaveOptions, RunOpWaveResult } from "./op-waves-run";
 export { loadActivities, loadProfiles, resolveActivity } from "./activity-registry";
 export type { ActivityFn } from "./activity-registry";
 export { loadActivityContracts, mergeActivityContracts } from "./activity-contract-registry";

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}`);
+    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);
+  }
+}