@intentius/chant 0.124.3 → 0.124.5

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

@@ -759,3 +759,271 @@ describe("a product's wave gate moved onto the waves (#3821)", () => {
     h.done();
   });
 });
+
+describe("gates and holds a product's wave needs (#3821)", () => {
+  const digest = (n: string) => `sha256:${n.repeat(64)}`;
+  const tg: OpWavesSpec = {
+    name: "tf-apply",
+    op: "tf-apply",
+    gateName: "wave-{k}",
+    planWave: ["tg", "plan", "{wave}", "{runs}", "{plans}"],
+    applyWave: ["tg", "apply", "{wave}", "{runs}", "{plans}"],
+    hooks: { after: { gate: [{ name: "report", command: ["tg", "report", "{runs}"] }] } },
+    waves: [{ name: "net", runs: [{ target: "vpc" }, { target: "dns" }], gate: "always" }],
+  };
+  type Plan = { planDigest: string; empty?: boolean; denied?: { rules: string[] } };
+  function harness(plans: Record<string, Plan>, opts: { extra?: Record<string, unknown>; atBase?: OpWavesSpec; hook?: (argv: string[], env: Record<string, string>, dir: string) => number } = {}) {
+    const cwd = mkdtempSync(join(tmpdir(), "op-waves-3821b-"));
+    const calls: string[] = [];
+    const envs: Array<Record<string, string>> = [];
+    const exec: OpWaveExec = (argv, dir, env = {}) => {
+      calls.push(argv.join(" "));
+      envs.push(env);
+      if (argv[0] !== "tg") return opts.hook?.(argv, env, dir) ?? 0;
+      if (argv[1] === "report") return opts.hook?.(argv, env, dir) ?? 0;
+      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] })), ...(opts.extra ?? {}) }));
+      return 0;
+    };
+    const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: JSON.stringify(opts.atBase ?? tg) });
+    return { cwd, calls, envs, exec, show, done: () => rmSync(cwd, { recursive: true, force: true }) };
+  }
+  const run = (h: ReturnType<typeof harness>, gates = memoryGateLedgerPort(), spec: OpWavesSpec = tg) =>
+    runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates, now: "2026-10-11T00:00:00.000Z", log: () => {} });
+
+  test("the spec checks after.gate hooks and override", () => {
+    expect(() => assertOpWavesSpec(tg)).not.toThrow();
+    expect(() => assertOpWavesSpec({ ...tg, hooks: { before: { gate: [{ command: ["x"] }] } } as OpWavesSpec["hooks"] })).toThrow(/runs after the gate/);
+    expect(() => assertOpWavesSpec({ ...tg, hooks: { after: { gate: [{ command: ["x"], onFailure: "approve" }] } } })).toThrow(/already decided/);
+    expect(() => assertOpWavesSpec({ ...tg, override: { overriders: "" } })).toThrow(/override.overriders/);
+    expect(() => assertOpWavesSpec({ ...tg, override: { who: "x" } as OpWavesSpec["override"] })).toThrow(/override.who/);
+  });
+
+  test("the after-gate hook runs when the wave waits, with the decision in its environment", async () => {
+    const h = harness({ vpc: { planDigest: digest("1") }, dns: { planDigest: digest("2") } });
+    const result = await run(h);
+    expect(result.exitCode).toBe(3);
+    const at = h.calls.indexOf(`tg report .chant/op-waves/tf-apply/wave-1/runs.json`);
+    expect(at).toBeGreaterThan(0);
+    const env = h.envs[at]!;
+    expect(env).toMatchObject({ CHANT_HOOK: "after-gate", CHANT_GATE_STATUS: "waiting", CHANT_GATE_OP: "tf-apply", CHANT_GATE: "wave-1", CHANT_GATE_DIGEST: result.decision!.digest, CHANT_GATE_RECORDED: "true", CHANT_GATE_WAITING_SINCE: "2026-10-11T00:00:00.000Z" });
+    expect(env.CHANT_GATE_APPROVE).toBe(`chant approve tf-apply wave-1 --plan ${result.decision!.digest}`);
+    const record = JSON.parse(readFileSync(join(h.cwd, env.CHANT_DECISION!), "utf-8")) as OpWaveDecision;
+    expect(record).toMatchObject({ status: "waiting", recorded: true, pendingFact: { gate: "wave-1", planDigest: result.decision!.digest } });
+    expect(h.calls.some((c) => c.startsWith("tg apply"))).toBe(false);
+    h.done();
+  });
+
+  test("the after-gate hook names the approval of another digest; a failing one stops a wave that would apply, and not a waiting one", async () => {
+    const h = harness({ vpc: { planDigest: digest("1") }, dns: { planDigest: digest("2") } }, { hook: () => 1 });
+    const gates = memoryGateLedgerPort({ resolutions: [{ version: 1, op: "tf-apply", gate: "wave-1", resolvedBy: "alice", timestamp: "2026-10-10T00:00:00Z", planDigest: digest("9") }] });
+    const waiting = await run(h, gates);
+    expect(waiting.exitCode).toBe(3);
+    expect(waiting.decision).toMatchObject({ mismatch: { approved: digest("9"), resolvedBy: "alice" } });
+    h.done();
+
+    const open = harness({ vpc: { planDigest: digest("1"), empty: true }, dns: { planDigest: digest("2"), empty: true } }, { hook: () => 1 });
+    const stopped = await run(open);
+    expect(stopped).toMatchObject({ exitCode: 1, decision: { status: "not-required" } });
+    expect(open.calls.some((c) => c.startsWith("tg apply"))).toBe(false);
+    open.done();
+  });
+
+  test("a run the policy denied refuses the wave (exit 7) and records a denial an override answers", async () => {
+    const h = harness({ vpc: { planDigest: digest("1"), denied: { rules: ["no-public-s3"] } }, dns: { planDigest: digest("2") } });
+    const gates = memoryGateLedgerPort();
+    const result = await run(h, gates);
+    expect(result).toMatchObject({ exitCode: 7, decision: { status: "refused", refused: { reason: "policy", runs: ["vpc"] } } });
+    expect(gates.appended).toHaveLength(1);
+    expect(gates.appended[0]).toMatchObject({ op: "policy-override", gate: "vpc", plan: digest("1"), rules: ["no-public-s3"], members: [{ member: "vpc", planDigest: digest("1") }] });
+    expect(h.envs.find((e) => e.CHANT_HOOK === "after-gate")).toMatchObject({ CHANT_GATE_STATUS: "refused" });
+    expect(h.calls.some((c) => c.startsWith("tg apply"))).toBe(false);
+    const { opWaveNotifyFields } = await import("./op-waves-notify");
+    expect(opWaveNotifyFields(tg, 1, { result })).toMatchObject({ event: "refused", status: "denied", targets: ["vpc"] });
+    h.done();
+  });
+
+  test("an override by a listed overrider lets the denied run through, and is spent before the apply", async () => {
+    const { overrideDigest } = await import("../override-gate");
+    const od = overrideDigest("vpc", digest("1"), ["no-public-s3"]);
+    const h = harness({ vpc: { planDigest: digest("1"), denied: { rules: ["no-public-s3"] } }, dns: { planDigest: digest("2"), empty: true } }, { extra: { overriders: ["github:carol"] }, atBase: { ...tg, waves: [{ ...tg.waves[0]!, gate: "never" }] } });
+    const gates = memoryGateLedgerPort({
+      resolutions: [{ version: 1, op: "policy-override", gate: "vpc", resolvedBy: "github:carol", timestamp: "2026-10-10T00:00:00Z", planDigest: od, note: "the bucket is the public docs site" }],
+    });
+    const result = await run(h, gates);
+    expect(result).toMatchObject({ exitCode: 0, applied: ["vpc", "dns"] });
+    expect(result.decision!.members.find((m) => m.member === "vpc")).toMatchObject({ override: { by: "github:carol", digest: od } });
+    expect(gates.applied).toEqual([expect.objectContaining({ op: "policy-override", gate: "vpc", planDigest: od, approvedBy: "github:carol" })]);
+    h.done();
+
+    // Somebody the list does not name does not count.
+    const other = harness({ vpc: { planDigest: digest("1"), denied: { rules: ["no-public-s3"] } }, dns: { planDigest: digest("2") } }, { extra: { overriders: ["github:dave"] } });
+    expect((await run(other, memoryGateLedgerPort({ resolutions: [{ version: 1, op: "policy-override", gate: "vpc", resolvedBy: "github:carol", timestamp: "2026-10-10T00:00:00Z", planDigest: od, note: "ok" }] }))).exitCode).toBe(7);
+    other.done();
+  });
+
+  test("a hook holds the wave on another gate: it waits on that gate's digest, then runs again once approved", async () => {
+    const migrate = { name: "migrate", command: ["migrate", "{runs}"], onFailure: "approve" as const };
+    const spec: OpWavesSpec = { ...tg, hooks: { before: { plan: [migrate] }, after: tg.hooks!.after } };
+    const hook = (argv: string[], env: Record<string, string>, dir: string) => {
+      if (argv[0] !== "migrate") return 0;
+      if (env.CHANT_HOLD_APPROVED) return 0;
+      writeFileSync(join(dir, env.CHANT_HOLD!), JSON.stringify({ op: "tf-migrate", gate: "split-queues", digest: digest("m"), pending: { members: [] } }));
+      return 3;
+    };
+    const h = harness({ vpc: { planDigest: digest("1") }, dns: { planDigest: digest("2") } }, { hook, atBase: spec });
+    const gates = memoryGateLedgerPort();
+    const waiting = await run(h, gates, spec);
+    expect(waiting).toMatchObject({ exitCode: 3, decision: { status: "waiting", heldOn: { op: "tf-migrate", gate: "split-queues", digest: digest("m"), status: "waiting" } } });
+    expect(waiting.decision!.approve).toBe(`chant approve tf-migrate split-queues --plan ${digest("m")}`);
+    expect(gates.appended[0]).toMatchObject({ op: "tf-migrate", gate: "split-queues", planDigest: digest("m"), members: [] });
+    expect(h.calls.some((c) => c.startsWith("tg plan"))).toBe(false);
+    expect(h.envs.find((e) => e.CHANT_HOOK === "after-gate")).toMatchObject({ CHANT_GATE_STATUS: "waiting", CHANT_GATE_OP: "tf-migrate", CHANT_GATE: "split-queues" });
+    h.done();
+
+    const again = harness({ vpc: { planDigest: digest("1"), empty: true }, dns: { planDigest: digest("2"), empty: true } }, { hook, atBase: spec });
+    const approved = memoryGateLedgerPort({ resolutions: [{ version: 1, op: "tf-migrate", gate: "split-queues", resolvedBy: "alice", timestamp: "2026-10-10T00:00:00Z", planDigest: digest("m") }] });
+    const result = await run(again, approved, spec);
+    expect(result.exitCode).toBe(0);
+    const reruns = again.envs.filter((e, i) => again.calls[i]!.startsWith("migrate"));
+    expect(reruns).toHaveLength(2);
+    expect(JSON.parse(reruns[1]!.CHANT_HOLD_APPROVED!)).toMatchObject({ op: "tf-migrate", gate: "split-queues", approvedBy: "alice" });
+    expect(result.hooks.filter((o) => o.name === "migrate").map((o) => o.outcome)).toEqual(["held", "passed"]);
+    again.done();
+  });
+});
+
+describe("discovered waves, a cost member and applies that apply nothing (#3821)", () => {
+  const digest = (n: string) => `sha256:${n.repeat(64)}`;
+  const tg: OpWavesSpec = {
+    name: "tf-apply",
+    op: "tf-apply",
+    gateName: "wave-{k}",
+    digest: { over: "changing" },
+    planWave: ["tg", "plan", "{wave}", "{runs}", "{plans}"],
+    applyWave: ["tg", "apply", "{wave}", "{runs}", "{plans}"],
+    waves: [
+      { name: "layer", runs: [], discover: true, gate: "never" },
+      { name: "rest", runs: [], discover: true, rest: true, gate: "never" },
+    ],
+  };
+  /** `layers[k-1]` is what wave k's plan finds; `apply` says what each apply call writes to CHANT_APPLY_OUTCOME. */
+  function harness(layers: Array<Record<string, { planDigest: string; empty?: boolean }>>, opts: { extra?: (k: number) => Record<string, unknown>; apply?: (k: number, n: number) => unknown; atBase?: OpWavesSpec } = {}) {
+    const cwd = mkdtempSync(join(tmpdir(), "op-waves-3821c-"));
+    const calls: string[] = [];
+    const runsFiles: OpWaveRunsFile[] = [];
+    const applies = new Map<number, number>();
+    const exec: OpWaveExec = (argv, dir, env = {}) => {
+      calls.push(argv.join(" "));
+      const runs = JSON.parse(readFileSync(join(dir, argv[3]!), "utf-8")) as OpWaveRunsFile;
+      runsFiles.push(runs);
+      if (argv[1] === "plan") {
+        const found = layers[runs.number - 1] ?? {};
+        const entries = runs.discover ? Object.entries(found).map(([target, p]) => ({ target, ...p })) : runs.runs.map((r) => ({ target: r.target, ...found[r.target] }));
+        writeFileSync(join(dir, argv[4]!), JSON.stringify({ runs: entries, waves: layers.length, ...(opts.extra?.(runs.number) ?? {}) }));
+      }
+      if (argv[1] === "apply") {
+        const n = (applies.get(runs.number) ?? 0) + 1;
+        applies.set(runs.number, n);
+        const said = opts.apply?.(runs.number, n);
+        if (said) writeFileSync(join(dir, env.CHANT_APPLY_OUTCOME!), JSON.stringify(said));
+      }
+      return 0;
+    };
+    const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: JSON.stringify(opts.atBase ?? tg) });
+    return { cwd, calls, runsFiles, exec, show, done: () => rmSync(cwd, { recursive: true, force: true }) };
+  }
+  const run = (h: ReturnType<typeof harness>, wave: number, gates = memoryGateLedgerPort(), spec: OpWavesSpec = tg) =>
+    runOpWave({ spec, specFile: "waves.json", wave, cwd: h.cwd, exec: h.exec, show: h.show, gates, now: "2026-10-11T00:00:00.000Z", log: () => {} });
+
+  test("the spec checks discover and rest", () => {
+    expect(() => assertOpWavesSpec(tg)).not.toThrow();
+    expect(() => assertOpWavesSpec({ ...tg, planWave: undefined, plan: ["p", "{plan}"] })).toThrow(/only `planWave` can report/);
+    expect(() => assertOpWavesSpec({ ...tg, waves: [{ name: "a", runs: [{ target: "x" }], discover: true }] })).toThrow(/lists none/);
+    expect(() => assertOpWavesSpec({ ...tg, waves: [{ name: "a", runs: [], rest: true, discover: true }, { name: "b", runs: [], discover: true }] })).toThrow(/only the last wave/);
+    expect(() => assertOpWavesSpec({ ...tg, waves: [{ name: "a", runs: [], rest: true }] })).toThrow(/set discover too/);
+    expect(() => assertOpWavesSpec({ ...tg, waves: [{ name: "a", runs: [], discover: true, rest: true, shares: 2 }] })).toThrow(/cannot be split/);
+  });
+
+  test("a wave plans the runs its plan command finds, and the rest wave walks on to the last wave it found", async () => {
+    const layers: Array<Record<string, { planDigest: string }>> = [{ "a/vpc": { planDigest: digest("1") } }, { "b/db": { planDigest: digest("2") } }, { "c/app": { planDigest: digest("3") } }, { "d/dns": { planDigest: digest("4") } }];
+    const h = harness(layers);
+    const first = await run(h, 1);
+    expect(first).toMatchObject({ exitCode: 0, applied: ["a/vpc"], decision: { gate: "wave-1", discovered: { waves: 4 } } });
+    expect(h.runsFiles[0]).toMatchObject({ discover: true, runs: [] });
+    const rest = await run(h, 2);
+    expect(rest).toMatchObject({ exitCode: 0, applied: ["b/db", "c/app", "d/dns"], decision: { wave: 4, gate: "wave-4", name: "rest" } });
+    expect(rest.rest!.map((r) => [r.wave, r.exitCode])).toEqual([[2, 0], [3, 0], [4, 0]]);
+    h.done();
+
+    // A repo with fewer waves than jobs: the later job finds nothing to apply.
+    const short = harness([{ "a/vpc": { planDigest: digest("1") } }]);
+    expect(await run(short, 2)).toMatchObject({ exitCode: 0, applied: [] });
+    short.done();
+  });
+
+  test("a wide discovering wave hands its found runs to its shares", async () => {
+    const spec: OpWavesSpec = { ...tg, waves: [{ name: "layer", runs: [], discover: true, gate: "never", shares: 2 }] };
+    const layers = [{ "a/1": { planDigest: digest("1") }, "a/2": { planDigest: digest("2") }, "a/3": { planDigest: digest("3") } }];
+    const h = harness(layers, { atBase: spec });
+    expect(await runOpWave({ spec, specFile: "waves.json", wave: 1, decide: true, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort(), log: () => {} })).toMatchObject({ exitCode: 0, applied: [] });
+    const share = await runOpWave({ spec, specFile: "waves.json", wave: 1, share: 2, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort(), log: () => {} });
+    expect(share).toMatchObject({ exitCode: 0, applied: ["a/3"] });
+    h.done();
+  });
+
+  test("a cost member joins the digest, so an approval at one cost does not apply at another", async () => {
+    const spec: OpWavesSpec = { ...tg, waves: [{ name: "layer", runs: [], discover: true, gate: "always" }] };
+    const layers = [{ "a/vpc": { planDigest: digest("1") }, "a/idle": { planDigest: digest("2"), empty: true } }];
+    const cost = (usd: string) => ({ members: [{ member: "cost", planDigest: `usd:${usd}` }] });
+    const h = harness(layers, { extra: () => cost("120.00"), atBase: spec });
+    const gates = memoryGateLedgerPort();
+    const result = await run(h, 1, gates, spec);
+    const priced = waveSetDigest([{ member: "a/vpc", planDigest: digest("1") }, { member: "cost", planDigest: "usd:120.00" }]);
+    expect(result).toMatchObject({ exitCode: 3, decision: { digest: priced, extras: [{ member: "cost", planDigest: "usd:120.00" }] } });
+    h.done();
+
+    const dearer = harness(layers, { extra: () => cost("900.00"), atBase: spec });
+    const approved = memoryGateLedgerPort({ resolutions: [{ version: 1, op: "tf-apply", gate: "wave-1", resolvedBy: "alice", timestamp: "2026-10-10T00:00:00Z", planDigest: priced }] });
+    expect(await run(dearer, 1, approved, spec)).toMatchObject({ exitCode: 3, decision: { mismatch: { approved: priced } } });
+    dearer.done();
+
+    const clash = harness([{ cost: { planDigest: digest("1") } }], { extra: () => cost("1"), atBase: spec });
+    await expect(run(clash, 1, memoryGateLedgerPort(), spec)).rejects.toThrow(/also a run's target/);
+    clash.done();
+  });
+
+  test("an apply that stood down or was held applies nothing and fails nothing; one that asks plans again", async () => {
+    const layers = [{ "a/vpc": { planDigest: digest("1") } }];
+    const down = harness(layers, { apply: () => ({ outcome: "stood-down", reason: "a newer push is on main" }) });
+    const stood = await run(down, 1);
+    expect(stood).toMatchObject({ exitCode: 6, applied: [], failed: [], outcome: { outcome: "stood-down", reason: "a newer push is on main" } });
+    const { opWaveNotifyFields } = await import("./op-waves-notify");
+    expect(opWaveNotifyFields(tg, 1, { result: stood })).toBeUndefined();
+    down.done();
+
+    const busy = harness(layers, { apply: () => ({ outcome: "held", holder: { run: "github:123", url: "https://example.test/run/123" } }) });
+    const held = await run(busy, 1);
+    expect(held).toMatchObject({ exitCode: 5, applied: [], failed: [], outcome: { outcome: "held", holder: { run: "github:123" } } });
+    expect(opWaveNotifyFields(tg, 1, { result: held })).toMatchObject({ event: "refused", status: "held", targets: ["a/vpc"] });
+    busy.done();
+
+    const again = harness(layers, { apply: (_k, n) => (n === 1 ? { outcome: "replan", reason: "run 123 let go" } : undefined) });
+    const replanned = await run(again, 1);
+    expect(replanned).toMatchObject({ exitCode: 0, applied: ["a/vpc"] });
+    expect(again.calls.filter((c) => c.startsWith("tg plan"))).toHaveLength(2);
+    again.done();
+  });
+
+  test("planned again to the same digest, the approval the job found still holds and is not spent twice", async () => {
+    const spec: OpWavesSpec = { ...tg, approvals: { spend: true }, waves: [{ name: "layer", runs: [], discover: true, gate: "always" }] };
+    const layers = [{ "a/vpc": { planDigest: digest("1") } }];
+    const set = waveSetDigest([{ member: "a/vpc", planDigest: digest("1") }]);
+    const h = harness(layers, { apply: (_k, n) => (n === 1 ? { outcome: "replan" } : undefined), atBase: spec });
+    const gates = memoryGateLedgerPort({ resolutions: [{ version: 1, op: "tf-apply", gate: "wave-1", resolvedBy: "alice", timestamp: "2026-10-10T00:00:00Z", planDigest: set }] });
+    const result = await run(h, 1, gates, spec);
+    expect(result).toMatchObject({ exitCode: 0, applied: ["a/vpc"], decision: { status: "approved", approvedBy: "alice" } });
+    expect(gates.applied).toHaveLength(1);
+    h.done();
+  });
+});

package/src/op/op-waves.ts

@@ -58,6 +58,15 @@
 import type { OpEnvironment, OpSetupStep } from "../lexicon";
 import { notifyConfigProblem, type NotifyConfig } from "../notify";
 
+/**
+ * The variables a wave job reads its notify secrets from, for the lexicons
+ * that generate wave pipelines. Re-exported here because a lexicon's source
+ * in this repository cannot import `@intentius/chant/notify`: under any
+ * loader that entry resolves its `import` condition to the compiled
+ * `dist/notify.js` (#3803), which only a packed release carries.
+ */
+export { notifyVariables } from "../notify";
+
 /** When a wave waits for an approval. */
 export type OpWaveGatePolicy =
   /** Whenever the wave changes something. */
@@ -102,12 +111,17 @@ export interface OpWaveHook {
 }
 
 /** The stages a hook runs around. */
-export type OpWaveHookStage = "plan" | "apply";
+export type OpWaveHookStage = "plan" | "apply" | "gate";
 
 /** When a hook runs. */
-export type OpWaveHookMoment = "before-plan" | "after-plan" | "before-apply" | "after-apply";
+export type OpWaveHookMoment = "before-plan" | "after-plan" | "after-gate" | "before-apply" | "after-apply";
 
-export const OP_WAVE_HOOK_MOMENTS: readonly OpWaveHookMoment[] = ["before-plan", "after-plan", "before-apply", "after-apply"];
+/**
+ * Every moment, in the order a wave reaches them. `after-gate` (#3821) runs
+ * once the gate decided, whatever it decided: approved, let through,
+ * waiting, or refused by a policy denial.
+ */
+export const OP_WAVE_HOOK_MOMENTS: readonly OpWaveHookMoment[] = ["before-plan", "after-plan", "after-gate", "before-apply", "after-apply"];
 
 /**
  * Who runs the `before.apply` and `after.apply` hooks (#3804). `chant`: the
@@ -122,7 +136,8 @@ export const OP_WAVE_APPLY_HOOKS_RUNNERS: readonly OpWaveApplyHooksRunner[] = ["
 /** Stage hooks (#3762), read from the spec at the base commit like the gate policy. */
 export interface OpWaveHooks {
   before?: { plan?: OpWaveHook[]; apply?: OpWaveHook[] };
-  after?: { plan?: OpWaveHook[]; apply?: OpWaveHook[] };
+  /** `after.gate` (#3821) runs once the gate decided, whatever it decided, with the decision in its environment. */
+  after?: { plan?: OpWaveHook[]; gate?: OpWaveHook[]; apply?: OpWaveHook[] };
   /** Who runs the apply-stage hooks (#3804). Default `{ runBy: "chant" }`. A wave's own setting wins over the spec's. */
   apply?: { runBy?: OpWaveApplyHooksRunner };
 }
@@ -139,7 +154,23 @@ export interface OpWaveRun {
 export interface OpWave {
   /** The wave's name, usually its environment. Lowercase letters, digits, `-` and `_`. */
   name: string;
+  /** The wave's runs. Empty or absent on a `discover` wave. */
   runs: OpWaveRun[];
+  /**
+   * The runs come from the product at plan time (#3821): `planWave` gets a
+   * runs file with no runs and `discover: true`, and plans the runs it finds
+   * for wave k (a Terragrunt repo's dependency layer from `terragrunt find`).
+   * Needs `planWave`.
+   */
+  discover?: boolean;
+  /**
+   * The last wave only, with `discover` (#3821): once it applies, the job
+   * goes on to wave k+1, k+2, ... while `planWave` reports more waves
+   * (`waves` in its plans file), each behind its own gate and read at base
+   * by this wave's name. For a pipeline whose wave count is not known up
+   * front.
+   */
+  rest?: boolean;
   /**
    * When the wave waits. Default `"always"`. The runner reads this from the
    * spec file at the base commit, never from the change being applied.
@@ -228,6 +259,13 @@ export interface OpWavesSpec {
   hooks?: OpWaveHooks;
   /** What happens to an approval once a wave applies under it (#3784). Read at the base commit. */
   approvals?: OpWavesApprovals;
+  /**
+   * Who may override a run the product's policy denied at plan time (#3821).
+   * A plan entry with `denied` refuses the wave unless an override on
+   * `_gates/policy-override.jsonl` counts for that run, its plan digest and
+   * the rules (`@intentius/chant/override-gate`).
+   */
+  override?: OpWavesOverride;
   waves: OpWave[];
   /**
    * A scheduled job that starts again a wave job whose approval has arrived
@@ -270,6 +308,16 @@ export function opWaveGateName(spec: Pick<OpWavesSpec, "name" | "gate" | "gateNa
   return (spec.gateName ?? OP_WAVE_DEFAULT_GATE_NAME).replaceAll("{gate}", spec.gate ?? spec.name).replaceAll("{k}", String(k));
 }
 
+/** Where a wave reads who may override a policy denial (#3821). */
+export interface OpWavesOverride {
+  /**
+   * The overriders file, read at the base commit. Default
+   * `.chant/overriders`. A plans file that names `overriders` (a product
+   * that keeps its list in its own config at base) wins over it.
+   */
+  overriders?: string;
+}
+
 /** What happens to an approval once a wave applies under it (#3784). */
 export interface OpWavesApprovals {
   /**
@@ -386,6 +434,14 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
       if (!OP_WAVES_DIGEST_OVER.includes(value as "all")) throw new Error(`${where}: digest.over is ${JSON.stringify(value)}; use "all" or "changing".`);
     }
   }
+  if (spec.override !== undefined) {
+    const o = spec.override as unknown;
+    if (o === null || typeof o !== "object" || Array.isArray(o)) throw new Error(`${where}: \`override\` must be { "overriders"?: "<file at base>" }.`);
+    for (const [key, value] of Object.entries(o as Record<string, unknown>)) {
+      if (key !== "overriders") throw new Error(`${where}: override.${key} is not a setting; the one there is override.overriders.`);
+      if (typeof value !== "string" || value.trim() === "") throw new Error(`${where}: override.overriders must be a path, such as ".chant/overriders".`);
+    }
+  }
   if (spec.neverOverMcp !== undefined && typeof spec.neverOverMcp !== "boolean") throw new Error(`${where}: neverOverMcp must be true or false.`);
   if (spec.notify !== undefined) {
     const problem = notifyConfigProblem(spec.notify, "notify");
@@ -405,7 +461,23 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
       throw new Error(`${where}: wave "${wave.name}" has approval "${wave.approval}"; use ${GATE_APPROVAL_SOURCES.join(", ")}.`);
     }
     assertOpWaveHooks(`${where}, wave "${wave.name}"`, wave.hooks);
-    if (wave.runs.length === 0) throw new Error(`${where}: wave "${wave.name}" has no runs.`);
+    if (wave.discover !== undefined && typeof wave.discover !== "boolean") throw new Error(`${where}: wave "${wave.name}" has discover ${JSON.stringify(wave.discover)}; use true or false.`);
+    if (wave.rest !== undefined && typeof wave.rest !== "boolean") throw new Error(`${where}: wave "${wave.name}" has rest ${JSON.stringify(wave.rest)}; use true or false.`);
+    if (wave.discover) {
+      if (spec.planWave === undefined) throw new Error(`${where}: wave "${wave.name}" discovers its runs, which only \`planWave\` can report. Give planWave.`);
+      if ((wave.runs ?? []).length > 0) throw new Error(`${where}: wave "${wave.name}" discovers its runs, so it lists none.`);
+    }
+    if (wave.rest) {
+      if (!wave.discover) throw new Error(`${where}: wave "${wave.name}" has rest, which follows the waves planWave discovers; set discover too.`);
+      if (wave !== spec.waves[spec.waves.length - 1]) throw new Error(`${where}: wave "${wave.name}" has rest, which only the last wave can have.`);
+      if ((wave.shares ?? 1) > 1) throw new Error(`${where}: wave "${wave.name}" has rest and shares; the waves after it run in its one job, so it cannot be split.`);
+    }
+    if (wave.discover) {
+      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.`);
+      continue;
+    }
+    if (!Array.isArray(wave.runs) || 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.`);
@@ -449,7 +521,8 @@ export function assertOpWaveHooks(where: string, hooks: OpWaveHooks | undefined)
     if (stages === null || typeof stages !== "object" || Array.isArray(stages)) throw new Error(`${where}: hooks.${side} must be { "plan"?: [...], "apply"?: [...] }.`);
     for (const [stage, list] of Object.entries(stages as Record<string, unknown>)) {
       const at = `hooks.${side}.${stage}`;
-      if (stage !== "plan" && stage !== "apply") throw new Error(`${where}: ${at} is not a stage; a hook runs before or after plan or apply.`);
+      if (stage === "gate" && side === "before") throw new Error(`${where}: ${at} is not a moment; a hook runs after the gate (hooks.after.gate), or before the plan or the apply.`);
+      if (stage !== "plan" && stage !== "apply" && stage !== "gate") throw new Error(`${where}: ${at} is not a stage; a hook runs before or after plan or apply, or after the gate.`);
       if (!Array.isArray(list)) throw new Error(`${where}: ${at} must be a list of hooks.`);
       list.forEach((hook: OpWaveHook, i: number) => {
         const which = `${at}[${i}]${hook && typeof hook === "object" && typeof hook.name === "string" ? ` (${hook.name})` : ""}`;
@@ -461,6 +534,9 @@ export function assertOpWaveHooks(where: string, hooks: OpWaveHooks | undefined)
         if (hook.onFailure === "approve" && side === "after" && stage === "apply") {
           throw new Error(`${where}: ${which} has onFailure "approve", but after the apply there is nothing left to hold. Use "fail".`);
         }
+        if (hook.onFailure === "approve" && stage === "gate") {
+          throw new Error(`${where}: ${which} has onFailure "approve", but the gate has already decided when it runs. Use "fail", or hold the wave from an after.plan hook.`);
+        }
         if (hook.perRun !== undefined && typeof hook.perRun !== "boolean") throw new Error(`${where}: ${which}.perRun must be true or false.`);
         if (!hook.perRun) {
           const named = hook.command.find((part) => part.includes("{target}") || part.includes("{plan}"));
@@ -478,7 +554,7 @@ export function opWaveHooksAt(spec: Pick<OpWavesSpec, "hooks" | "waves">, name:
   const wave = spec.waves.find((w) => w.name === name);
   const at = (hooks: OpWaveHooks | undefined, moment: OpWaveHookMoment): OpWaveHook[] => {
     const [side, stage] = moment.split("-") as ["before" | "after", OpWaveHookStage];
-    return hooks?.[side]?.[stage] ?? [];
+    return (hooks?.[side] as Partial<Record<OpWaveHookStage, OpWaveHook[]>> | undefined)?.[stage] ?? [];
   };
   return Object.fromEntries(OP_WAVE_HOOK_MOMENTS.map((m) => [m, [...at(spec.hooks, m), ...at(wave?.hooks, m)]])) as Record<OpWaveHookMoment, OpWaveHook[]>;
 }