@intentius/chant 0.122.0 → 0.124.0

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

@@ -1,9 +1,20 @@
 import { describe, expect, test } from "vitest";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, 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 { assertOpWavesSpec, opWaveJobs, opWaveShare, type OpWavesSpec } from "./op-waves";
+import {
+  opWaveHooksAtBase,
+  readOpWaveHooksFile,
+  recordOpWaveHeadPlans,
+  runOpWave,
+  runOpWaveApplyHooks,
+  type OpWaveDecision,
+  type OpWaveExec,
+  type OpWaveHooksFile,
+  type OpWaveRunsFile,
+  type OpWaveShowAtBase,
+} from "./op-waves-run";
 import { memoryGateLedgerPort } from "./gate";
 import { waveSetDigest } from "../gated-waves";
 
@@ -93,3 +104,532 @@ describe("runOpWave", () => {
     h.done();
   });
 });
+
+describe("wave-level commands and hooks in the spec (#3762)", () => {
+  const base = { name: "w", op: "migrate", waves: [{ name: "dev", runs: [{ target: "a" }] }] };
+  test("a spec without them is unchanged, and the new fields are checked", () => {
+    expect(() => assertOpWavesSpec({ ...base, plan: ["p", "{plan}"] })).not.toThrow();
+    expect(() => assertOpWavesSpec({ ...base, planWave: ["p", "{runs}", "{plans}"], applyWave: ["a", "{runs}"] })).not.toThrow();
+    expect(() => assertOpWavesSpec({ ...base, plan: ["p", "{plan}"], planWave: ["p", "{plans}"] })).toThrow(/both `plan` and `planWave`/);
+    expect(() => assertOpWavesSpec({ ...base, planWave: ["p", "{runs}"] })).toThrow(/never names \{plans\}/);
+    expect(() => assertOpWavesSpec({ ...base, planWave: ["p", "{plans}"], apply: ["a"], applyWave: ["a", "{runs}"] })).toThrow(/both `apply` and `applyWave`/);
+    expect(() => assertOpWavesSpec(base as OpWavesSpec)).toThrow(/give `plan` or `planWave`/);
+    const hooked = (hooks: unknown): OpWavesSpec => ({ ...base, plan: ["p", "{plan}"], hooks: hooks as OpWavesSpec["hooks"] });
+    expect(() => assertOpWavesSpec(hooked({ before: { plan: [{ command: ["check", "{runs}"], onFailure: "approve" }] }, after: { apply: [{ command: ["smoke", "{target}"], perRun: true }] } }))).not.toThrow();
+    expect(() => assertOpWavesSpec(hooked({ after: { apply: [{ command: ["smoke"], onFailure: "approve" }] } }))).toThrow(/nothing left to hold/);
+    expect(() => assertOpWavesSpec(hooked({ before: { init: [{ command: ["x"] }] } }))).toThrow(/hooks.before.init is not a stage/);
+    expect(() => assertOpWavesSpec(hooked({ during: {} }))).toThrow(/hooks.during is not a moment/);
+    expect(() => assertOpWavesSpec(hooked({ after: { plan: [{ command: ["x", "{plan}"] }] } }))).toThrow(/runs once for the wave/);
+    expect(() => assertOpWavesSpec(hooked({ before: { plan: [{ command: ["x", "{plan}"], perRun: true }] } }))).toThrow(/no \{plan\} yet/);
+    expect(() => assertOpWavesSpec(hooked({ before: { plan: [{ command: ["x"], onFailure: "warn" }] } }))).toThrow(/onFailure "warn"/);
+    expect(() => assertOpWavesSpec({ ...base, plan: ["p", "{plan}"], waves: [{ name: "dev", runs: [{ target: "a" }], hooks: { before: { apply: [{ command: [] }] } } }] })).toThrow(/wave "dev".*argv/);
+  });
+});
+
+describe("runOpWave with wave-level commands (#3762)", () => {
+  const digest = (n: string) => `sha256:${n.repeat(64)}`;
+  const waveSpec: OpWavesSpec = {
+    name: "roots",
+    op: "tf",
+    planWave: ["tg", "plan", "{wave}", "{runs}", "{plans}"],
+    applyWave: ["tg", "apply", "{wave}", "{runs}", "{plans}"],
+    waves: [
+      { name: "net", runs: [{ target: "vpc" }, { target: "dns" }], gate: "on-destructive" },
+      { name: "apps", runs: [{ target: "a1" }, { target: "a2" }, { target: "a3" }], gate: "never", shares: 2 },
+    ],
+  };
+  function harness(plans: Record<string, { planDigest: string; destructive?: boolean; empty?: boolean }>, atBase: OpWavesSpec | null = waveSpec) {
+    const cwd = mkdtempSync(join(tmpdir(), "op-waves-wave-"));
+    const calls: string[] = [];
+    const applied: OpWaveRunsFile[] = [];
+    const exec: OpWaveExec = (argv, dir) => {
+      calls.push(argv.join(" "));
+      const runs = JSON.parse(readFileSync(join(dir, argv[3]!), "utf-8")) as OpWaveRunsFile;
+      if (argv[1] === "plan") writeFileSync(join(dir, argv[4]!), JSON.stringify({ runs: runs.runs.map((r) => ({ target: r.target, ...plans[r.target] })) }));
+      if (argv[1] === "apply") applied.push(runs);
+      return 0;
+    };
+    const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: atBase === null ? null : JSON.stringify(atBase) });
+    return { cwd, calls, applied, exec, show, done: () => rmSync(cwd, { recursive: true, force: true }) };
+  }
+
+  test("one call plans the wave; the digest and the gate are those of per-run plans; the apply gets the approved set", async () => {
+    const plans = { vpc: { planDigest: digest("1"), destructive: true }, dns: { planDigest: digest("2") } };
+    const h = harness(plans);
+    const set = waveSetDigest([{ member: "vpc", planDigest: digest("1") }, { member: "dns", planDigest: digest("2") }]);
+    const waiting = await runOpWave({ spec: waveSpec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort() });
+    expect(waiting).toMatchObject({ exitCode: 3, decision: { digest: set, status: "waiting", policy: "on-destructive" } });
+    expect(h.calls).toEqual([`tg plan net .chant/op-waves/roots/wave-1/runs.json .chant/op-waves/roots/wave-1/plans.json`]);
+    // Each run's plan file is written too, so a per-run apply or hook reads {plan} either way.
+    expect(JSON.parse(readFileSync(join(h.cwd, ".chant/op-waves/roots/wave-1/vpc.plan.json"), "utf-8"))).toEqual({ planDigest: digest("1"), destructive: true });
+
+    const gates = memoryGateLedgerPort({ resolutions: [{ version: 1, op: "roots", gate: "roots-wave-1", resolvedBy: "alice", timestamp: "2026-10-10T00:00:00Z", planDigest: set }] });
+    const approved = await runOpWave({ spec: waveSpec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates });
+    expect(approved).toMatchObject({ exitCode: 0, applied: ["vpc", "dns"], decision: { status: "approved", approvedBy: "alice" } });
+    expect(h.applied).toEqual([
+      {
+        wave: "net",
+        number: 1,
+        digest: set,
+        runs: [
+          { target: "vpc", op: "tf", planDigest: digest("1"), destructive: true },
+          { target: "dns", op: "tf", planDigest: digest("2") },
+        ],
+      },
+    ]);
+    h.done();
+  });
+
+  test("a plans file that misses a run, or plans one it was not asked to, is refused", async () => {
+    const h = harness({ vpc: { planDigest: digest("1") } });
+    await expect(runOpWave({ spec: waveSpec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort() })).rejects.toThrow(/no planDigest for dns|no plan for dns/);
+    h.done();
+    const extra = harness({});
+    const exec: OpWaveExec = (argv, dir) => (writeFileSync(join(dir, argv[4]!), JSON.stringify([{ target: "vpc", planDigest: digest("1") }, { target: "dns", planDigest: digest("2") }, { target: "zzz", planDigest: digest("3") }])), 0);
+    await expect(runOpWave({ spec: waveSpec, specFile: "waves.json", wave: 1, cwd: extra.cwd, exec, show: extra.show, gates: memoryGateLedgerPort() })).rejects.toThrow(/"zzz", which is not a run/);
+    extra.done();
+  });
+
+  test("shares keep working: each share plans its slice in one call and applies only the runs whose plan did not move", async () => {
+    const plans: Record<string, { planDigest: string }> = { a1: { planDigest: digest("1") }, a2: { planDigest: digest("2") }, a3: { planDigest: digest("3") } };
+    const h = harness(plans);
+    const decided = await runOpWave({ spec: waveSpec, specFile: "waves.json", wave: 2, decide: true, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort() });
+    expect(decided).toMatchObject({ exitCode: 0, applied: [], decision: { status: "not-required" } });
+    plans.a2 = { planDigest: digest("9") };
+    const share = await runOpWave({ spec: waveSpec, specFile: "waves.json", wave: 2, share: 1, cwd: h.cwd, exec: h.exec, show: h.show });
+    expect(share).toMatchObject({ exitCode: 4, applied: ["a1"], moved: ["a2"] });
+    expect(h.applied.at(-1)!.runs.map((r) => r.target)).toEqual(["a1"]);
+    h.done();
+  });
+
+  test("--record-plans plans each wave with one call", async () => {
+    const h = harness({ vpc: { planDigest: digest("1") }, dns: { planDigest: digest("2") }, a1: { planDigest: digest("1") }, a2: { planDigest: digest("2") }, a3: { planDigest: digest("3") } });
+    const plans = await recordOpWaveHeadPlans({ spec: waveSpec, cwd: h.cwd, exec: h.exec, head: "c".repeat(40), now: "t", write: async () => {} });
+    expect(plans.waves[0]!.digest).toBe(waveSetDigest([{ member: "vpc", planDigest: digest("1") }, { member: "dns", planDigest: digest("2") }]));
+    expect(h.calls.filter((c) => c.startsWith("tg plan"))).toHaveLength(2);
+    h.done();
+  });
+});
+
+describe("runOpWave hooks (#3762)", () => {
+  const digest = (n: string) => `sha256:${n.repeat(64)}`;
+  const hooked: OpWavesSpec = {
+    name: "migrations",
+    op: "migrate",
+    plan: ["tool", "plan", "{target}", "{plan}"],
+    apply: ["tool", "apply", "{target}", "{plan}"],
+    hooks: { before: { plan: [{ name: "lint", command: ["hook", "lint", "{runs}"] }] } },
+    waves: [
+      {
+        name: "prod",
+        runs: [{ target: "t1" }, { target: "t2" }],
+        gate: "never",
+        hooks: {
+          after: { plan: [{ name: "check", command: ["hook", "check", "{target}", "{plan}"], perRun: true, onFailure: "approve" }], apply: [{ name: "smoke", command: ["hook", "smoke", "{wave}"] }] },
+          before: { apply: [{ name: "backup", command: ["hook", "backup", "{runs}"] }] },
+        },
+      },
+    ],
+  };
+  function harness(atBase: OpWavesSpec | null, fails: string[] = []) {
+    const cwd = mkdtempSync(join(tmpdir(), "op-waves-hooks-"));
+    const calls: Array<{ argv: string; env?: Record<string, string> }> = [];
+    const exec: OpWaveExec = (argv, dir, env) => {
+      calls.push({ argv: argv.join(" "), ...(env ? { env } : {}) });
+      if (argv[1] === "plan") writeFileSync(join(dir, argv[3]!), JSON.stringify({ planDigest: digest(argv[2] === "t1" ? "1" : "2") }));
+      return fails.some((f) => argv.join(" ").startsWith(f)) ? 1 : 0;
+    };
+    const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: atBase === null ? null : JSON.stringify(atBase) });
+    return { cwd, calls, exec, show, argv: () => calls.map((c) => c.argv), done: () => rmSync(cwd, { recursive: true, force: true }) };
+  }
+  const set = waveSetDigest([{ member: "t1", planDigest: digest("1") }, { member: "t2", planDigest: digest("2") }]);
+
+  test("hooks run around the plan and the apply, per run with {target}, {plan} and the CHANT_ variables", async () => {
+    const h = harness(hooked);
+    const result = await runOpWave({ spec: hooked, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort() });
+    expect(result).toMatchObject({ exitCode: 0, applied: ["t1", "t2"], decision: { status: "not-required" } });
+    expect(h.argv()).toEqual([
+      "hook lint .chant/op-waves/migrations/wave-1/runs.json",
+      "tool plan t1 .chant/op-waves/migrations/wave-1/t1.plan.json",
+      "tool plan t2 .chant/op-waves/migrations/wave-1/t2.plan.json",
+      "hook check t1 .chant/op-waves/migrations/wave-1/t1.plan.json",
+      "hook check t2 .chant/op-waves/migrations/wave-1/t2.plan.json",
+      "hook backup .chant/op-waves/migrations/wave-1/runs.json",
+      "tool apply t1 .chant/op-waves/migrations/wave-1/t1.plan.json",
+      "tool apply t2 .chant/op-waves/migrations/wave-1/t2.plan.json",
+      "hook smoke prod",
+    ]);
+    expect(h.calls[3]!.env).toMatchObject({ CHANT_OP_WAVES: "migrations", CHANT_WAVE: "prod", CHANT_WAVE_NUMBER: "1", CHANT_HOOK: "after-plan", CHANT_TARGET: "t1", CHANT_PLAN: ".chant/op-waves/migrations/wave-1/t1.plan.json" });
+    expect(result.hooks.map((o) => `${o.moment} ${o.name}${o.target ? ` ${o.target}` : ""} ${o.outcome}`)).toEqual([
+      "before-plan lint passed",
+      "after-plan check t1 passed",
+      "after-plan check t2 passed",
+      "before-apply backup passed",
+      "after-apply smoke passed",
+    ]);
+    h.done();
+  });
+
+  test("hooks are read at base: a change cannot add a hook its own apply runs, nor remove one", async () => {
+    const added = harness({ ...hooked, hooks: undefined, waves: hooked.waves.map((w) => ({ ...w, hooks: undefined })) });
+    const logs: string[] = [];
+    await runOpWave({ spec: hooked, specFile: "waves.json", wave: 1, cwd: added.cwd, exec: added.exec, show: added.show, gates: memoryGateLedgerPort(), log: (l) => logs.push(l) });
+    expect(added.argv().filter((c) => c.startsWith("hook"))).toEqual([]);
+    expect(logs.some((l) => l.includes("this change's differ; the ones at base run"))).toBe(true);
+    added.done();
+
+    const removed = harness(hooked);
+    const bare = { ...hooked, hooks: undefined, waves: hooked.waves.map((w) => ({ ...w, hooks: undefined })) };
+    await runOpWave({ spec: bare, specFile: "waves.json", wave: 1, cwd: removed.cwd, exec: removed.exec, show: removed.show, gates: memoryGateLedgerPort() });
+    expect(removed.argv().filter((c) => c.startsWith("hook"))).toHaveLength(5);
+    removed.done();
+
+    const absent = harness(null);
+    await runOpWave({ spec: hooked, specFile: "waves.json", wave: 1, cwd: absent.cwd, exec: absent.exec, show: absent.show, gates: memoryGateLedgerPort() });
+    expect(absent.argv().filter((c) => c.startsWith("hook"))).toEqual([]);
+    absent.done();
+  });
+
+  test("an approve hook that fails holds a `never` wave until its set digest is approved", async () => {
+    const h = harness(hooked, ["hook check t2"]);
+    const gates = memoryGateLedgerPort();
+    const held = await runOpWave({ spec: hooked, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates });
+    expect(held).toMatchObject({ exitCode: 3, applied: [], decision: { policy: "never", status: "waiting", digest: set, heldBy: ["after-plan hook check (t2)"] } });
+    expect(gates.appended[0]!.planDigest).toBe(set);
+    expect(h.argv().some((c) => c.startsWith("tool apply") || c.startsWith("hook backup"))).toBe(false);
+    h.done();
+
+    const again = harness(hooked, ["hook check t2"]);
+    const approved = memoryGateLedgerPort({ resolutions: [{ version: 1, op: "migrations", gate: "migrations-wave-1", resolvedBy: "alice", timestamp: "2026-10-10T00:00:00Z", planDigest: set }] });
+    const applied = await runOpWave({ spec: hooked, specFile: "waves.json", wave: 1, cwd: again.cwd, exec: again.exec, show: again.show, gates: approved });
+    expect(applied).toMatchObject({ exitCode: 0, applied: ["t1", "t2"], decision: { status: "approved", approvedBy: "alice" } });
+    again.done();
+  });
+
+  test("a failing hook fails the wave: before the plan nothing is planned, after the apply the wave exits 1", async () => {
+    const early = harness(hooked, ["hook lint"]);
+    const r1 = await runOpWave({ spec: hooked, specFile: "waves.json", wave: 1, cwd: early.cwd, exec: early.exec, show: early.show, gates: memoryGateLedgerPort() });
+    expect(r1).toMatchObject({ exitCode: 1, applied: [] });
+    expect(early.argv()).toEqual(["hook lint .chant/op-waves/migrations/wave-1/runs.json"]);
+    early.done();
+
+    const late = harness(hooked, ["hook smoke"]);
+    const r2 = await runOpWave({ spec: hooked, specFile: "waves.json", wave: 1, cwd: late.cwd, exec: late.exec, show: late.show, gates: memoryGateLedgerPort() });
+    expect(r2).toMatchObject({ exitCode: 1, applied: ["t1", "t2"] });
+    late.done();
+  });
+
+  test("an approve hook before the apply holds a wave the policy let through", async () => {
+    const spec: OpWavesSpec = { ...hooked, hooks: undefined, waves: [{ ...hooked.waves[0]!, hooks: { before: { apply: [{ name: "drain", command: ["hook", "drain"], onFailure: "approve" }] } } }] };
+    const h = harness(spec, ["hook drain"]);
+    const gates = memoryGateLedgerPort();
+    const result = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates });
+    expect(result).toMatchObject({ exitCode: 3, applied: [], decision: { status: "waiting", heldBy: ["before-apply hook drain"] } });
+    expect(gates.appended[0]!.planDigest).toBe(set);
+    h.done();
+  });
+
+  test("hooks at base that no runner can run hold the wave and none run", async () => {
+    const broken = { ...hooked, hooks: { before: { plan: [{ command: "lint" }] } } } as unknown as OpWavesSpec;
+    const h = harness(broken);
+    const result = await runOpWave({ spec: hooked, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort() });
+    expect(result.exitCode).toBe(3);
+    expect(result.decision!.heldBy![0]).toMatch(/the hooks at base cannot be run/);
+    expect(h.argv().filter((c) => c.startsWith("hook"))).toEqual([]);
+    h.done();
+  });
+
+  test("a wide wave's shares run the hooks their deciding job read at base", async () => {
+    const wide: OpWavesSpec = { ...hooked, waves: [{ ...hooked.waves[0]!, shares: 2 }] };
+    const h = harness(wide);
+    await runOpWave({ spec: { ...wide, hooks: undefined }, specFile: "waves.json", wave: 1, decide: true, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort() });
+    const before = h.calls.length;
+    const share = await runOpWave({ spec: { ...wide, hooks: undefined }, specFile: "waves.json", wave: 1, share: 2, cwd: h.cwd, exec: h.exec, show: h.show });
+    expect(share).toMatchObject({ exitCode: 0, applied: ["t2"] });
+    expect(h.argv().slice(before)).toEqual([
+      "hook lint .chant/op-waves/migrations/wave-1/runs.json",
+      "tool plan t2 .chant/op-waves/migrations/wave-1/t2.plan.json",
+      "hook check t2 .chant/op-waves/migrations/wave-1/t2.plan.json",
+      "hook backup .chant/op-waves/migrations/wave-1/runs.json",
+      "tool apply t2 .chant/op-waves/migrations/wave-1/t2.plan.json",
+      "hook smoke prod",
+    ]);
+    h.done();
+  });
+
+  test("a hold in a share job waits unless the wave was approved", async () => {
+    const wide: OpWavesSpec = { ...hooked, waves: [{ ...hooked.waves[0]!, shares: 2 }] };
+    const h = harness(wide);
+    await runOpWave({ spec: wide, specFile: "waves.json", wave: 1, decide: true, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort() });
+    const failing: OpWaveExec = (argv, dir, env) => (h.exec(argv, dir, env), argv.join(" ").startsWith("hook check") ? 1 : 0);
+    const gates = memoryGateLedgerPort();
+    const share = await runOpWave({ spec: wide, specFile: "waves.json", wave: 1, share: 1, cwd: h.cwd, exec: failing, show: h.show, gates });
+    expect(share).toMatchObject({ exitCode: 3, applied: [] });
+    expect(gates.appended[0]!.planDigest).toBe(set);
+    h.done();
+  });
+});
+
+describe("spent approvals (#3784)", () => {
+  const spending: OpWavesSpec = { ...spec, approvals: { spend: true } };
+  const digest = (n: string) => `sha256:${n.repeat(64)}`;
+  const set = waveSetDigest([{ member: "staging", planDigest: digest("a") }]);
+  const approval = { version: 1 as const, op: "migrations", gate: "migrations-wave-2", resolvedBy: "alice", timestamp: "2026-10-10T00:00:00Z", planDigest: set };
+  function harness(atBase: OpWavesSpec | null) {
+    const cwd = mkdtempSync(join(tmpdir(), "op-waves-spend-"));
+    const calls: string[] = [];
+    const exec: OpWaveExec = (argv, dir) => {
+      calls.push(argv.join(" "));
+      if (argv[1] === "plan") writeFileSync(join(dir, argv[4]!), JSON.stringify({ planDigest: digest(argv[2] === "staging" ? "a" : "b"), destructive: true }));
+      return 0;
+    };
+    const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: atBase === null ? null : JSON.stringify(atBase) });
+    return { cwd, calls, exec, show, applies: () => calls.filter((c) => c.startsWith("tool apply")).length, done: () => rmSync(cwd, { recursive: true, force: true }) };
+  }
+
+  test("the spec checks approvals", () => {
+    expect(() => assertOpWavesSpec({ ...spec, approvals: { spend: "yes" } } as unknown as OpWavesSpec)).toThrow(/approvals.spend must be true or false/);
+    expect(() => assertOpWavesSpec({ ...spec, approvals: { burn: true } } as unknown as OpWavesSpec)).toThrow(/approvals.burn is not a setting/);
+    expect(() => assertOpWavesSpec(spending)).not.toThrow();
+  });
+
+  test("with spend at base, an approval passes the same wave once: the second run waits for a new approval", async () => {
+    const h = harness(spending);
+    const gates = memoryGateLedgerPort({ resolutions: [approval] });
+    const now = "2026-10-11T00:00:00Z";
+    const first = await runOpWave({ spec: spending, specFile: "waves.json", wave: 2, cwd: h.cwd, exec: h.exec, show: h.show, gates, now });
+    expect(first).toMatchObject({ exitCode: 0, applied: ["staging"], decision: { status: "approved", approvedBy: "alice", approvedAt: approval.timestamp, spend: "base", spentAt: now } });
+    expect(gates.applied).toEqual([
+      { version: 1, kind: "applied", op: "migrations", gate: "migrations-wave-2", planDigest: set, approvedAt: approval.timestamp, approvedBy: "alice", timestamp: now, wave: { number: 2, name: "staging" } },
+    ]);
+
+    const logs: string[] = [];
+    const second = await runOpWave({ spec: spending, specFile: "waves.json", wave: 2, cwd: h.cwd, exec: h.exec, show: h.show, gates, now: "2026-10-11T01:00:00Z", log: (l) => logs.push(l) });
+    expect(second).toMatchObject({ exitCode: 3, applied: [], decision: { status: "waiting" } });
+    expect(h.applies()).toBe(1);
+    expect(logs.some((l) => /the approval of .* by alice at 2026-10-10T00:00:00Z is spent/.test(l))).toBe(true);
+    expect(gates.appended.at(-1)!.planDigest).toBe(set);
+
+    // A new approval of the same digest passes it once more, and is spent in turn.
+    await gates.appendResolution!({ op: "migrations", gate: "migrations-wave-2", resolvedBy: "bob", timestamp: "2026-10-11T02:00:00Z", planDigest: set });
+    const third = await runOpWave({ spec: spending, specFile: "waves.json", wave: 2, cwd: h.cwd, exec: h.exec, show: h.show, gates, now: "2026-10-11T03:00:00Z" });
+    expect(third).toMatchObject({ exitCode: 0, decision: { approvedBy: "bob" } });
+    expect(gates.applied).toHaveLength(2);
+    h.done();
+  });
+
+  test("without spend at base, the approval passes the digest every time, and only a change that adds spend records it", async () => {
+    const off = harness(spec);
+    const gates = memoryGateLedgerPort({ resolutions: [approval] });
+    for (const now of ["2026-10-11T00:00:00Z", "2026-10-11T01:00:00Z"]) {
+      expect(await runOpWave({ spec, specFile: "waves.json", wave: 2, cwd: off.cwd, exec: off.exec, show: off.show, gates, now })).toMatchObject({ exitCode: 0 });
+    }
+    expect(gates.applied).toEqual([]);
+    off.done();
+
+    // The change turns spend on: this apply is recorded, and the rule holds from the next decision at base.
+    const adding = harness(spec);
+    const added = await runOpWave({ spec: spending, specFile: "waves.json", wave: 2, cwd: adding.cwd, exec: adding.exec, show: adding.show, gates, now: "2026-10-11T02:00:00Z" });
+    expect(added).toMatchObject({ exitCode: 0, decision: { spend: "change" } });
+    expect(gates.applied).toHaveLength(1);
+    adding.done();
+    const next = harness(spending);
+    expect(await runOpWave({ spec: spending, specFile: "waves.json", wave: 2, cwd: next.cwd, exec: next.exec, show: next.show, gates, now: "2026-10-11T03:00:00Z" })).toMatchObject({ exitCode: 3 });
+    next.done();
+  });
+
+  test("a change cannot turn spend off for its own apply", async () => {
+    const h = harness(spending);
+    const gates = memoryGateLedgerPort({ resolutions: [approval] });
+    await runOpWave({ spec: spending, specFile: "waves.json", wave: 2, cwd: h.cwd, exec: h.exec, show: h.show, gates, now: "2026-10-11T00:00:00Z" });
+    const again = await runOpWave({ spec, specFile: "waves.json", wave: 2, cwd: h.cwd, exec: h.exec, show: h.show, gates, now: "2026-10-11T01:00:00Z" });
+    expect(again.exitCode).toBe(3);
+    h.done();
+  });
+
+  test("a spent approval of another digest does not refuse; the wave waits for its own", async () => {
+    const h = harness(spending);
+    const other = { ...approval, planDigest: "sha256:" + "f".repeat(64) };
+    const gates = memoryGateLedgerPort({
+      resolutions: [other],
+      applied: [{ version: 1, kind: "applied", op: "migrations", gate: "migrations-wave-2", planDigest: other.planDigest, approvedAt: other.timestamp, approvedBy: "alice", timestamp: "2026-10-10T01:00:00Z" }],
+    });
+    const result = await runOpWave({ spec: spending, specFile: "waves.json", wave: 2, cwd: h.cwd, exec: h.exec, show: h.show, gates, now: "2026-10-11T00:00:00Z" });
+    expect(result).toMatchObject({ exitCode: 3, decision: { status: "waiting" } });
+    h.done();
+  });
+
+  test("a wide wave's deciding job spends the approval once, before its shares apply", async () => {
+    const wide: OpWavesSpec = { ...spending, waves: spending.waves.map((w) => (w.name === "prod" ? { ...w, gate: "always" as const } : w)) };
+    const h = harness(wide);
+    const prodSet = waveSetDigest(["t1", "t2", "t3"].map((t) => ({ member: t, planDigest: digest("b") })));
+    const gates = memoryGateLedgerPort({ resolutions: [{ ...approval, gate: "migrations-wave-3", planDigest: prodSet }] });
+    const decided = await runOpWave({ spec: wide, specFile: "waves.json", wave: 3, decide: true, cwd: h.cwd, exec: h.exec, show: h.show, gates, now: "2026-10-11T00:00:00Z" });
+    expect(decided).toMatchObject({ exitCode: 0, decision: { status: "approved", spentAt: "2026-10-11T00:00:00Z" } });
+    expect(gates.applied).toHaveLength(1);
+    for (const share of [1, 2]) {
+      expect(await runOpWave({ spec: wide, specFile: "waves.json", wave: 3, share, cwd: h.cwd, exec: h.exec, show: h.show, gates })).toMatchObject({ exitCode: 0 });
+    }
+    expect(gates.applied).toHaveLength(1);
+    expect(h.applies()).toBe(3);
+    h.done();
+  });
+
+  test("a wave that cannot record the approval applies nothing", async () => {
+    const h = harness(spending);
+    const gates = { ...memoryGateLedgerPort({ resolutions: [approval] }), appendApplied: undefined };
+    const result = await runOpWave({ spec: spending, specFile: "waves.json", wave: 2, cwd: h.cwd, exec: h.exec, show: h.show, gates });
+    expect(result).toMatchObject({ exitCode: 1, applied: [] });
+    expect(h.applies()).toBe(0);
+    h.done();
+  });
+});
+
+describe("apply-stage hooks run by the apply, under its lock (#3804)", () => {
+  const digest = (n: string) => `sha256:${n.repeat(64)}`;
+  const spec: OpWavesSpec = {
+    name: "migrations",
+    op: "migrate",
+    plan: ["tool", "plan", "{target}", "{plan}"],
+    apply: ["tool", "apply", "{target}", "{plan}"],
+    hooks: { apply: { runBy: "apply" }, before: { plan: [{ name: "lint", command: ["hook", "lint"] }] } },
+    waves: [
+      {
+        name: "prod",
+        runs: [{ target: "t1" }],
+        gate: "never",
+        hooks: {
+          before: { apply: [{ name: "lag", command: ["hook", "lag", "{target}"], perRun: true, onFailure: "approve" }] },
+          after: { apply: [{ name: "smoke", command: ["hook", "smoke", "{wave}"] }] },
+        },
+      },
+    ],
+  };
+
+  /**
+   * A job whose apply command is a product that takes its lock and runs the
+   * hooks it was handed, as SQL Yodeler's apply would. `obey: false` is an
+   * apply that ignores the hooks file.
+   */
+  function harness(atBase: OpWavesSpec | null, opts: { fails?: string[]; obey?: boolean } = {}) {
+    const cwd = mkdtempSync(join(tmpdir(), "op-waves-by-apply-"));
+    const calls: string[] = [];
+    const files: OpWaveHooksFile[] = [];
+    const inner: OpWaveExec = (argv) => {
+      calls.push(`  ${argv.join(" ")}`);
+      return (opts.fails ?? []).some((f) => argv.join(" ").startsWith(f)) ? 1 : 0;
+    };
+    const exec: OpWaveExec = (argv, dir, env) => {
+      calls.push(argv.join(" "));
+      if (argv[1] === "plan") writeFileSync(join(dir, argv[3]!), JSON.stringify({ planDigest: digest("1") }));
+      if (argv[1] === "apply") {
+        const file = readOpWaveHooksFile(env?.CHANT_HOOKS, dir)!;
+        files.push(file);
+        if (opts.obey === false) return 0;
+        calls.push("  lock");
+        const before = runOpWaveApplyHooks(file, "before-apply", { cwd: dir, exec: inner, log: () => {} });
+        if (!before.proceed) return before.held.length > 0 ? 3 : 4;
+        calls.push("  migrate");
+        const after = runOpWaveApplyHooks(file, "after-apply", { cwd: dir, exec: inner, log: () => {} });
+        return after.proceed ? 0 : 1;
+      }
+      return (opts.fails ?? []).some((f) => argv.join(" ").startsWith(f)) ? 1 : 0;
+    };
+    const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: atBase === null ? null : JSON.stringify(atBase) });
+    const record = () => JSON.parse(readFileSync(join(cwd, ".chant/op-waves/migrations/wave-1.json"), "utf-8")) as OpWaveDecision;
+    return { cwd, calls, files, exec, show, record, done: () => rmSync(cwd, { recursive: true, force: true }) };
+  }
+  const set = waveSetDigest([{ member: "t1", planDigest: digest("1") }]);
+
+  test("the spec checks hooks.apply.runBy and keeps the rest as it was", () => {
+    const base = { name: "w", op: "o", plan: ["p", "{plan}"], waves: [{ name: "dev", runs: [{ target: "a" }] }] };
+    expect(() => assertOpWavesSpec({ ...base, hooks: { apply: { runBy: "apply" } } })).not.toThrow();
+    expect(() => assertOpWavesSpec({ ...base, hooks: { apply: { runBy: "later" } } } as unknown as OpWavesSpec)).toThrow(/hooks.apply.runBy is "later"/);
+    expect(() => assertOpWavesSpec({ ...base, hooks: { apply: [{ command: ["x"] }] } } as unknown as OpWavesSpec)).toThrow(/hooks.apply must be/);
+  });
+
+  test("chant hands the apply-stage hooks to the apply, which runs them under its lock; the outcomes come back", async () => {
+    const h = harness(spec);
+    const result = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort() });
+    expect(result).toMatchObject({ exitCode: 0, applied: ["t1"], decision: { applyHooksRunBy: "apply" } });
+    expect(h.calls).toEqual([
+      "hook lint",
+      "tool plan t1 .chant/op-waves/migrations/wave-1/t1.plan.json",
+      "tool apply t1 .chant/op-waves/migrations/wave-1/t1.plan.json",
+      "  lock",
+      "  hook lag t1",
+      "  migrate",
+      "  hook smoke prod",
+    ]);
+    // The apply sees the outcomes of the hooks chant ran before it, and the hooks it runs itself.
+    expect(h.files[0]).toMatchObject({ runBy: "apply", approved: false, digest: set, outcomes: [{ moment: "before-plan", name: "lint", outcome: "passed" }] });
+    expect(Object.keys(h.files[0]!.hooks)).toEqual(["before-apply", "after-apply"]);
+    expect(result.hooks.map((o) => `${o.moment} ${o.name} ${o.outcome}`)).toEqual(["before-plan lint passed", "before-apply lag passed", "after-apply smoke passed"]);
+    expect(h.record().outcomes).toHaveLength(3);
+    h.done();
+  });
+
+  test("a hold inside the apply applies nothing and waits; with an approval of the digest the apply is called again and goes on", async () => {
+    const h = harness(spec, { fails: ["hook lag"] });
+    const waiting = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort() });
+    expect(waiting).toMatchObject({ exitCode: 3, applied: [], decision: { status: "waiting", heldBy: ["before-apply hook lag (t1)"] } });
+    expect(h.calls).not.toContain("  migrate");
+    h.done();
+
+    const again = harness(spec, { fails: ["hook lag"] });
+    const gates = memoryGateLedgerPort({ resolutions: [{ version: 1, op: "migrations", gate: "migrations-wave-1", resolvedBy: "alice", timestamp: "2026-10-10T00:00:00Z", planDigest: set }] });
+    const applied = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: again.cwd, exec: again.exec, show: again.show, gates });
+    expect(applied).toMatchObject({ exitCode: 0, applied: ["t1"], decision: { status: "approved", approvedBy: "alice" } });
+    expect(again.calls.filter((c) => c === "  lock")).toHaveLength(2);
+    expect(again.calls.filter((c) => c === "  migrate")).toHaveLength(1);
+    // The second call knows the approval stands, and which hook held the wave.
+    expect(again.files[1]).toMatchObject({ approved: true, heldBy: ["before-apply hook lag (t1)"] });
+    expect(applied.hooks.filter((o) => o.name === "lag").map((o) => o.outcome)).toEqual(["held", "held"]);
+    again.done();
+  });
+
+  test("an after-apply failure inside the apply counts the run applied and fails the wave", async () => {
+    const h = harness(spec, { fails: ["hook smoke"] });
+    const result = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort() });
+    expect(result).toMatchObject({ exitCode: 1, applied: ["t1"], failed: [] });
+    expect(result.hooks.at(-1)).toMatchObject({ moment: "after-apply", name: "smoke", outcome: "failed" });
+    h.done();
+  });
+
+  test("an apply that ignores the hooks it was handed fails the wave", async () => {
+    const h = harness(spec, { obey: false });
+    const logs: string[] = [];
+    const result = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort(), log: (l) => logs.push(l) });
+    expect(result).toMatchObject({ exitCode: 1, applied: ["t1"] });
+    expect(logs.join("\n")).toMatch(/without running its before-apply and after-apply hooks/);
+    h.done();
+  });
+
+  test("runBy is read at base: a change that sets it still has chant run the hooks, and the apply gets its outcomes", async () => {
+    const atBase: OpWavesSpec = { ...spec, hooks: { before: spec.hooks!.before } };
+    const h = harness(atBase);
+    const result = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort(), log: () => {} });
+    expect(result.exitCode).toBe(0);
+    expect(h.calls.slice(0, 4)).toEqual(["hook lint", "tool plan t1 .chant/op-waves/migrations/wave-1/t1.plan.json", "hook lag t1", "tool apply t1 .chant/op-waves/migrations/wave-1/t1.plan.json"]);
+    expect(h.files[0]).toMatchObject({ runBy: "chant", hooks: {} });
+    expect(h.files[0]!.outcomes.map((o) => o.name)).toEqual(["lint", "lag"]);
+    h.done();
+  });
+
+  test("an apply outside the waves reads the same hooks at base and runs them itself; a hold stops it", () => {
+    const h = harness(spec);
+    writeFileSync(join(h.cwd, "waves.json"), JSON.stringify({ ...spec, hooks: undefined, waves: [{ ...spec.waves[0]!, hooks: undefined }] }));
+    const file = opWaveHooksAtBase({ specFile: "waves.json", wave: "prod", cwd: h.cwd, show: h.show, base: "HEAD^1" });
+    expect(file).toMatchObject({ opWaves: "migrations", wave: "prod", number: 1, approved: false, runBy: "apply", runs: [{ target: "t1", op: "migrate" }] });
+    expect(Object.keys(file.hooks)).toEqual(["before-plan", "before-apply", "after-apply"]);
+    const ran: string[] = [];
+    const exec: OpWaveExec = (argv) => (ran.push(argv.join(" ")), argv[1] === "lag" ? 1 : 0);
+    const before = runOpWaveApplyHooks(file, "before-apply", { cwd: h.cwd, exec, log: () => {} });
+    expect(before).toMatchObject({ proceed: false, held: ["before-apply hook lag (t1)"], outcomes: [{ name: "lag", target: "t1", exit: 1, outcome: "held" }] });
+    expect(runOpWaveApplyHooks(file, "after-plan", { cwd: h.cwd, exec, log: () => {} })).toMatchObject({ proceed: true, outcomes: [] });
+    expect(ran).toEqual(["hook lag t1"]);
+    const absent = opWaveHooksAtBase({ specFile: "waves.json", wave: "prod", cwd: h.cwd, show: () => ({ sha: "c".repeat(40), text: null }) });
+    expect(absent.hooks).toEqual({});
+    h.done();
+  });
+});