@intentius/chant 0.124.2 → 0.124.4

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

@@ -663,3 +663,232 @@ describe("apply-stage hooks run by the apply, under its lock (#3804)", () => {
     h.done();
   });
 });
+
+describe("a product's wave gate moved onto the waves (#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: "net", runs: [{ target: "vpc" }, { target: "dns" }, { target: "nat" }] }],
+  };
+  function harness(plans: Record<string, { planDigest: string; empty?: boolean }>, extra: Record<string, unknown> = {}, atBase: OpWavesSpec = tg) {
+    const cwd = mkdtempSync(join(tmpdir(), "op-waves-3821-"));
+    const calls: string[] = [];
+    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] })), ...extra }));
+      return 0;
+    };
+    const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: JSON.stringify(atBase) });
+    return { cwd, calls, exec, show, done: () => rmSync(cwd, { recursive: true, force: true }) };
+  }
+
+  test("the spec checks gateName, digest and neverOverMcp", () => {
+    expect(() => assertOpWavesSpec(tg)).not.toThrow();
+    expect(() => assertOpWavesSpec({ ...tg, gateName: "wave" })).toThrow(/pattern with \{k\}/);
+    expect(() => assertOpWavesSpec({ ...tg, gateName: "{op}-{k}" })).toThrow(/names \{op\}/);
+    expect(() => assertOpWavesSpec({ ...tg, digest: { over: "some" as "all" } })).toThrow(/digest.over/);
+    expect(() => assertOpWavesSpec({ ...tg, neverOverMcp: "yes" as unknown as boolean })).toThrow(/neverOverMcp/);
+  });
+
+  test("the gate keeps the product's name, and the digest covers only the runs that change something", async () => {
+    const plans = { vpc: { planDigest: digest("1") }, dns: { planDigest: digest("2"), empty: true }, nat: { planDigest: digest("3") } };
+    const h = harness(plans);
+    const gates = memoryGateLedgerPort();
+    const result = await runOpWave({ spec: tg, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates });
+    const changing = waveSetDigest([{ member: "vpc", planDigest: digest("1") }, { member: "nat", planDigest: digest("3") }]);
+    expect(result).toMatchObject({ exitCode: 3, decision: { gate: "wave-1", digest: changing, digestOver: "changing", status: "waiting" } });
+    expect(gates.appended[0]).toMatchObject({ op: "tf-apply", gate: "wave-1", planDigest: changing });
+    h.done();
+  });
+
+  test("an approval a product recorded for its gate and digest before the move lets the wave apply", async () => {
+    const plans = { vpc: { planDigest: digest("1") }, dns: { planDigest: digest("2"), empty: true }, nat: { planDigest: digest("3") } };
+    const h = harness(plans);
+    const changing = waveSetDigest([{ member: "vpc", planDigest: digest("1") }, { member: "nat", planDigest: digest("3") }]);
+    const gates = memoryGateLedgerPort({
+      pending: [{ version: 1, kind: "pending", op: "tf-apply", gate: "wave-1", timestamp: "2026-10-10T00:00:00Z", expiresAt: "2026-10-12T00:00:00Z", planDigest: changing, neverOverMcp: true }],
+      resolutions: [{ version: 1, op: "tf-apply", gate: "wave-1", resolvedBy: "alice", timestamp: "2026-10-10T01:00:00Z", planDigest: changing }],
+    });
+    const result = await runOpWave({ spec: tg, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates, now: "2026-10-10T02:00:00Z" });
+    expect(result).toMatchObject({ exitCode: 0, decision: { status: "approved", approvedBy: "alice" } });
+    expect(gates.appended).toEqual([]);
+    h.done();
+  });
+
+  test("a wave whose runs are all empty digests every run, as before", async () => {
+    const plans = { vpc: { planDigest: digest("1"), empty: true }, dns: { planDigest: digest("2"), empty: true }, nat: { planDigest: digest("3"), empty: true } };
+    const h = harness(plans);
+    const result = await runOpWave({ spec: tg, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort() });
+    const all = waveSetDigest(["vpc", "dns", "nat"].map((t, i) => ({ member: t, planDigest: digest(String(i + 1)) })));
+    expect(result).toMatchObject({ exitCode: 0, decision: { digest: all, status: "not-required" } });
+    h.done();
+  });
+
+  test("the plans file's pending fields and the spec's neverOverMcp land on the pending fact; chant's own fields are refused", async () => {
+    const plans = { vpc: { planDigest: digest("1") }, dns: { planDigest: digest("2") }, nat: { planDigest: digest("3") } };
+    const members = [{ member: "vpc", planDigest: digest("1") }];
+    const h = harness(plans, { pending: { commit: "c".repeat(40), members, description: "wave 1 of 3: vpc, dns, nat" } });
+    // neverOverMcp at base counts even when the change drops it.
+    const gates = memoryGateLedgerPort();
+    const result = await runOpWave({ spec: tg, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: () => ({ sha: "b".repeat(40), text: JSON.stringify({ ...tg, neverOverMcp: true }) }), gates });
+    expect(result.exitCode).toBe(3);
+    expect(gates.appended[0]).toMatchObject({ commit: "c".repeat(40), members, description: "wave 1 of 3: vpc, dns, nat", neverOverMcp: true, gate: "wave-1", op: "tf-apply" });
+    h.done();
+
+    const bad = harness(plans, { pending: { gate: "other" } });
+    await expect(runOpWave({ spec: tg, specFile: "waves.json", wave: 1, cwd: bad.cwd, exec: bad.exec, show: bad.show, gates: memoryGateLedgerPort() })).rejects.toThrow(/sets gate, which chant writes itself/);
+    bad.done();
+  });
+
+  test("a spec without the new fields names its gates and digests as before", async () => {
+    const plain: OpWavesSpec = { ...tg, gateName: undefined, digest: undefined, name: "roots" };
+    const plans = { vpc: { planDigest: digest("1") }, dns: { planDigest: digest("2"), empty: true }, nat: { planDigest: digest("3") } };
+    const h = harness(plans, {}, plain);
+    const gates = memoryGateLedgerPort();
+    const result = await runOpWave({ spec: plain, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates });
+    const all = waveSetDigest(["vpc", "dns", "nat"].map((t, i) => ({ member: t, planDigest: digest(String(i + 1)) })));
+    expect(result.decision).toMatchObject({ gate: "roots-wave-1", digest: all });
+    expect(result.decision).not.toHaveProperty("digestOver");
+    expect(gates.appended[0]).not.toHaveProperty("neverOverMcp");
+    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();
+  });
+});

package/src/op/op-waves.ts

@@ -22,9 +22,11 @@
  *
  * ## The gate
  *
- * Wave k waits on `waveGateName(<gate>, k)`, recorded under the spec's name,
- * bound to {@link waveSetDigest} over its runs' plan digests (`../gated-waves.ts`,
- * the same digest a component fan-out's wave binds). Whether it waits at all
+ * Wave k waits on `waveGateName(<gate>, k)`, or the spec's `gateName` pattern
+ * ({@link opWaveGateName}, #3821), recorded under the spec's name, bound to
+ * {@link waveSetDigest} over its runs' plan digests (`../gated-waves.ts`, the
+ * same digest a component fan-out's wave binds), or with `digest.over:
+ * "changing"` over the runs whose plan changes something. Whether it waits at all
  * is the wave's gate policy, read from the base commit's copy of the spec
  * file, so a change cannot loosen the rule that gates its own merge.
  *
@@ -56,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. */
@@ -100,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
@@ -120,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 };
 }
@@ -170,12 +187,28 @@ export interface OpWave {
  * `{plan}` is replaced per run.
  */
 export interface OpWavesSpec {
-  /** The pipeline's name, and the op the wave gates are recorded under (`chant approve <name> <gate>-wave-<k>`). */
+  /** The pipeline's name, and the op the wave gates are recorded under (`chant approve <name> <gate>-wave-<k>`, or the `gateName` pattern). */
   name: string;
   /** The Op a run runs when it names none. */
   op: string;
   /** The base gate name. Default: `name`. */
   gate?: string;
+  /**
+   * The name of wave k's gate (#3821): `{gate}` is the base gate name and
+   * `{k}` the wave's number. Default `"{gate}-wave-{k}"`. A product moving
+   * its own wave gates onto these waves names its old pattern here (such as
+   * `"wave-{k}"`), so the approvals already on the ledger keep their gate.
+   */
+  gateName?: string;
+  /** Which runs the set digest covers (#3821). Default: every run. */
+  digest?: OpWavesDigest;
+  /**
+   * The waves' pending facts carry `neverOverMcp` (#3821, chant#3485): their
+   * gates are never resolved over MCP or ACP, whichever channel reached
+   * them. Read at the base commit too, and either one setting it is enough,
+   * so a change cannot drop the rule for its own gates.
+   */
+  neverOverMcp?: boolean;
   /** Branches whose pushes run the waves. Default `["main"]`. */
   branches?: string[];
   /**
@@ -210,6 +243,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
@@ -230,6 +270,38 @@ export interface OpWavesSpec {
   notify?: NotifyConfig;
 }
 
+/** Which runs a wave's set digest covers (#3821). */
+export interface OpWavesDigest {
+  /**
+   * `all` (the default): every run's plan. `changing`: only the runs whose
+   * plan is not `empty`, or every run when all of them are empty. A product
+   * whose plan note shows a digest over the plans that change something
+   * names `changing`, so the digest the wave asks approval for is the one
+   * the note showed.
+   */
+  over?: "all" | "changing";
+}
+
+export const OP_WAVES_DIGEST_OVER = ["all", "changing"] as const;
+
+/** The default gate name pattern. */
+export const OP_WAVE_DEFAULT_GATE_NAME = "{gate}-wave-{k}";
+
+/** The gate wave `k` waits on (#3821): the spec's `gateName` pattern, by default `<gate>-wave-<k>`. */
+export function opWaveGateName(spec: Pick<OpWavesSpec, "name" | "gate" | "gateName">, k: number): string {
+  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 {
   /**
@@ -331,6 +403,30 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
       if (typeof value !== "boolean") throw new Error(`${where}: approvals.spend must be true or false.`);
     }
   }
+  if (spec.gateName !== undefined) {
+    if (typeof spec.gateName !== "string" || !spec.gateName.includes("{k}") || /\s/.test(spec.gateName)) {
+      throw new Error(`${where}: gateName must be a pattern with {k}, the wave's number, and no spaces, such as "${OP_WAVE_DEFAULT_GATE_NAME}" or "wave-{k}".`);
+    }
+    const left = spec.gateName.replaceAll("{gate}", "").replaceAll("{k}", "").match(/\{[^}]*\}/);
+    if (left) throw new Error(`${where}: gateName names ${left[0]}; the pattern fills in {gate} and {k} only.`);
+  }
+  if (spec.digest !== undefined) {
+    const d = spec.digest as unknown;
+    if (d === null || typeof d !== "object" || Array.isArray(d)) throw new Error(`${where}: \`digest\` must be { "over"?: "all" | "changing" }.`);
+    for (const [key, value] of Object.entries(d as Record<string, unknown>)) {
+      if (key !== "over") throw new Error(`${where}: digest.${key} is not a setting; the one there is digest.over.`);
+      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");
     if (problem) throw new Error(`${where}: ${problem}`);
@@ -393,7 +489,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})` : ""}`;
@@ -405,6 +502,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}"));
@@ -422,7 +522,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[]>;
 }

package/src/op/steward-points.ts

@@ -121,6 +121,13 @@ export interface AskPointInRunOptions {
   on?: string;
   /** The steward turn, when the caller has it. Default: this process's (`currentStewardTurn`). */
   turn?: StewardTurn | null;
+  /**
+   * Where a new question goes (#3815): the working tree, or `chant/lifecycle`.
+   * Default: the ledger in a steward's turn and the tree otherwise
+   * (`askPoint`'s rule). A run whose checkout does not outlive it, such as a
+   * CI job, passes `"ledger"` so a person can answer after the job ends.
+   */
+  store?: "tree" | "ledger";
 }
 
 /** What a steward reaches through its broker, read from its declaration when the turn named only the steward. */
@@ -178,6 +185,7 @@ export async function askPointInRun(opts: AskPointInRunOptions): Promise<{ answe
     ...(opts.kind !== undefined ? { kind: opts.kind } : {}),
     ...(ask ? { ask } : {}),
     ...(opts.on !== undefined ? { on: opts.on } : {}),
+    ...(opts.store !== undefined ? { store: opts.store } : {}),
     ...(turn ? { steward: { name: turn.steward, ...(turn.run ? { run: turn.run } : {}) } } : {}),
   });
   if ("error" in doc) throw new Error(`decision point ${opts.point}: ${doc.error.code}: ${doc.error.message}`);

package/src/override-gate.test.ts

@@ -148,6 +148,11 @@ describe("decideOverride", () => {
       expect(parseAppliedOverrides(`${JSON.stringify(applied)}\nnot json\n{"version":1,"kind":"finished"}\n`)).toEqual([applied]);
     });
 
+    test("takes just the subject, digest, time and approver (#3823)", () => {
+      const slim = appliedOverride({ subject: ROOT, digest: DIGEST, at: first.timestamp, by: "github:alice" }, { timestamp: "2026-10-11T11:05:00.000Z", runId: "42", commit: "c".repeat(40) });
+      expect(slim).toEqual(applied);
+    });
+
     test("a spent override does not count for the same plan again", () => {
       const d = decideOverride(input([first], { applied: [applied] }));
       expect(d.status === "none" && d.refusals).toEqual([expect.stringMatching(/is spent: a run applied under it at 2026-10-11T11:05:00/)]);

package/src/override-gate.ts

@@ -359,8 +359,14 @@ export function decideOverride(input: OverrideInput): OverrideDecision {
   };
 }
 
-/** The applied record a run appends before it applies under `override`, which spends it. Appending it is the caller's. */
-export function appliedOverride(override: StandingOverride, at: { timestamp: string; runId?: string; commit?: string }): AppliedOverrideRecord {
+/**
+ * The applied record a run appends before it applies under `override`, which
+ * spends it. Appending it is the caller's. It reads only the subject, the
+ * override digest and the override's time and approver, so a product that
+ * carries those through its own record can pass them without the ledger line
+ * (#3823); a whole {@link StandingOverride} still works.
+ */
+export function appliedOverride(override: Pick<StandingOverride, "subject" | "digest" | "at" | "by">, at: { timestamp: string; runId?: string; commit?: string }): AppliedOverrideRecord {
   return {
     version: 1,
     kind: "applied",

package/src/point-decision-bundle.test.ts

@@ -0,0 +1,62 @@
+/**
+ * The gate-point decision bundles small (#3816).
+ *
+ * terragucci's wave gate asks a decision point, and terragucci ships as one
+ * bundled file with no TypeScript compiler, chant CLI, lint or codegen code
+ * in it. `@intentius/chant/op/gate-point-run` reached all of those through
+ * the workspace asker and the decide activity. `@intentius/chant/point-decision`
+ * holds the decision with the asker and the ledger port injected. This
+ * bundles it the way terragucci would and reads esbuild's own list of what
+ * went in.
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { describe, expect, test } from "vitest";
+import { REPO } from "./workspace/__fixtures__/contract-repo";
+
+const FORBIDDEN = [
+  /node_modules\//,
+  /\/src\/cli\//,
+  /\/src\/workspace\//,
+  /\/src\/fold\//,
+  /\/src\/lint\//,
+  /\/src\/codegen\//,
+  /\/src\/op\/activities\//,
+  /\/src\/lifecycle\/git\.ts$/,
+  /\/src\/lifecycle\/gate-ledger\.ts$/,
+];
+
+describe("the point-decision bundle", () => {
+  test("holds the gate-point decision and its pure helpers, and no workspace, CLI, package or git code", async () => {
+    const result = await build({
+      entryPoints: [join(REPO, "packages", "core", "src", "point-decision.ts")],
+      bundle: true,
+      platform: "node",
+      format: "esm",
+      write: false,
+      metafile: true,
+      outdir: "out",
+      logLevel: "silent",
+    });
+    const inputs = Object.keys(result.metafile.inputs);
+    for (const pattern of FORBIDDEN) {
+      expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
+    }
+    // The plan digest is the one chant computes, which brings its canonical JSON with it, as in gate-decision.
+    expect(inputs.map((i) => i.replace(/^.*?packages\//, "packages/")).sort()).toEqual([
+      "packages/core/src/content-digest.ts",
+      "packages/core/src/declarable.ts",
+      "packages/core/src/effect-receipt.ts",
+      "packages/core/src/intrinsic.ts",
+      "packages/core/src/lifecycle/gate-ledger-select.ts",
+      "packages/core/src/lifecycle/gate-pending.ts",
+      "packages/core/src/lifecycle/plan-digest.ts",
+      "packages/core/src/op/duration.ts",
+      "packages/core/src/op/gate-point.ts",
+      "packages/core/src/point-decision.ts",
+    ]);
+    const bytes = result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0);
+    expect(bytes).toBeLessThan(24 * 1024);
+  });
+});