@intentius/chant 0.124.2 → 0.124.3

package/src/op/index.ts

@@ -54,23 +54,27 @@ export type { GenerateOpsPipelineResult, GenerateOpWavesPipelineResult } from ".
 export {
   OP_WAVE_APPLY_HOOKS_RUNNERS,
   OP_WAVE_DEFAULT_APPLY,
+  OP_WAVE_DEFAULT_GATE_NAME,
   OP_WAVE_GATE_POLICIES,
   OP_WAVE_HOOK_MOMENTS,
   assertOpWaveHooks,
   assertOpWavesSpec,
   opWaveApplyHooksRunBy,
+  opWaveGateName,
   opWaveHooksAt,
   opWaveJobs,
   opWaveRecordPath,
   opWaveShare,
 } from "./op-waves";
-export type { OpWave, OpWaveApplyHooksRunner, OpWaveGatePolicy, OpWaveHook, OpWaveHookFailure, OpWaveHookMoment, OpWaveHooks, OpWaveJob, OpWaveRun, OpWavesSpec } from "./op-waves";
+export type { OpWave, OpWaveApplyHooksRunner, OpWaveGatePolicy, OpWaveHook, OpWaveHookFailure, OpWaveHookMoment, OpWaveHooks, OpWaveJob, OpWaveRun, OpWavesDigest, OpWavesSpec } from "./op-waves";
 export {
   opWaveHooksAtBase,
   opWaveNeedsApproval,
   opWavePlansPath,
   opWaveRunsPath,
+  opWaveSetDigest,
   parseOpWavesSpec,
+  recordOpWaveHeadPlans,
   readOpWaveHooksFile,
   readOpWavePolicy,
   runOpWave,
@@ -80,6 +84,7 @@ export type {
   OpWaveBaseRules,
   OpWaveDecision,
   OpWaveApplyHooksRun,
+  OpWaveExec,
   OpWaveHookOutcome,
   OpWaveHookRun,
   OpWaveHooksFile,
@@ -87,7 +92,11 @@ export type {
   OpWaveMember,
   OpWavePlanFile,
   OpWavePlansFile,
+  OpWavePolicySource,
   OpWaveRunsFile,
+  OpWaveShowAtBase,
+  RecordHeadPlansOptions,
+  RunOpWaveApplyHooksOptions,
   RunOpWaveOptions,
   RunOpWaveResult,
 } from "./op-waves-run";

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

@@ -42,7 +42,7 @@
 import { execFileSync, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, posix } from "node:path";
-import { waveGateName, waveSetDigest, type WaveMember } from "../gated-waves";
+import { waveSetDigest, type WaveMember } from "../gated-waves";
 import type { ReviewApproval } from "../gate-decision";
 import { approveCommand, evaluateGate, gitGateLedgerPort, type GateLedgerPort } from "./gate";
 import { isApprovalSpent, type AppliedGateRecord } from "../lifecycle/gate-applied";
@@ -56,6 +56,7 @@ import {
   assertOpWaveHooks,
   assertOpWavesSpec,
   opWaveApplyHooksRunBy,
+  opWaveGateName,
   opWaveHooksAt,
   opWaveRecordPath,
   opWaveShare,
@@ -81,8 +82,21 @@ export interface OpWavePlanFile {
 /** What a wave-level plan command writes to `{plans}` (#3762): one plan per run, by target. The array alone is read too. */
 export interface OpWavePlansFile {
   runs: Array<OpWavePlanFile & { target: string }>;
+  /**
+   * Fields the product adds to the wave's pending fact (#3821), such as the
+   * commit it planned or the members its own readers expect. chant's own
+   * fields win: a key chant writes (`op`, `gate`, `planDigest`, `timestamp`,
+   * ...) is refused, except `description`.
+   */
+  pending?: Record<string, unknown>;
 }
 
+/** Pending-fact keys chant writes itself, which a plans file's `pending` may not set (#3821). */
+export const OP_WAVE_PENDING_RESERVED = [
+  "version", "kind", "op", "gate", "timestamp", "expiresAt", "planDigest", "runId", "url", "resume",
+  "environment", "origin", "neverOverMcp", "approval", "answer",
+] as const;
+
 /** What chant writes to `{runs}` for a wave-level command or a hook (#3762). */
 export interface OpWaveRunsFile {
   /** The wave's name. */
@@ -148,6 +162,12 @@ export interface OpWaveDecision {
   applyHooksRunBy?: "apply";
   /** Every hook's outcome so far in the job that wrote the record (#3804). */
   outcomes?: OpWaveHookOutcome[];
+  /** `changing`: the digest covers only the runs whose plan is not empty, as the spec's `digest.over` says (#3821). Absent: every run. */
+  digestOver?: "changing";
+  /** The fields the plans file added to the pending fact (#3821). */
+  pending?: Record<string, unknown>;
+  /** The pending fact carries `neverOverMcp`, set by the spec here or at base (#3821). */
+  neverOverMcp?: true;
 }
 
 /** One hook's run (#3762). */
@@ -216,6 +236,18 @@ export interface OpWaveHooksResult {
   outcomes: OpWaveHookOutcome[];
 }
 
+/** The options of {@link runOpWaveApplyHooks} (#3825). */
+export interface RunOpWaveApplyHooksOptions {
+  /** Where the hooks run. Default `process.cwd()`. */
+  cwd?: string;
+  /** Runs one hook. Default: spawn it with the job's environment. */
+  exec?: OpWaveExec;
+  /** Default: stderr. */
+  log?: (line: string) => void;
+  /** Run nothing and record the moment as skipped, with this reason (#3811). */
+  skip?: string;
+}
+
 /** One call of {@link runOpWaveApplyHooks}. */
 export interface OpWaveApplyHooksRun {
   moment: OpWaveHookMoment;
@@ -293,6 +325,8 @@ export interface OpWaveBaseRules {
   spend: boolean;
   /** Who runs the apply-stage hooks, as read at base (#3804). `chant` when the file, the wave or the hooks are missing there. */
   applyHooksRunBy: OpWaveApplyHooksRunner;
+  /** The spec at base sets `neverOverMcp` (#3821). */
+  neverOverMcp: boolean;
 }
 
 const noHooks = (): Record<OpWaveHookMoment, OpWaveHook[]> =>
@@ -313,7 +347,7 @@ export function readOpWavePolicy(
   show: OpWaveShowAtBase = gitShowAtBase,
 ): OpWaveBaseRules {
   const { sha, text } = show(base, specFile.replace(/^\.\//, "").split("\\").join(posix.sep), cwd);
-  const absent = { policy: "always" as const, approval: "ledger" as const, source: "absent-at-base" as const, base: sha, hooks: noHooks(), spend: false, applyHooksRunBy: "chant" as const };
+  const absent = { policy: "always" as const, approval: "ledger" as const, source: "absent-at-base" as const, base: sha, hooks: noHooks(), spend: false, applyHooksRunBy: "chant" as const, neverOverMcp: false };
   if (text === null) return absent;
   let spec: OpWavesSpec;
   try {
@@ -323,12 +357,13 @@ export function readOpWavePolicy(
   }
   // The spend rule is the spec's, so it holds for a wave the base does not have yet.
   const spend = (spec as { approvals?: { spend?: unknown } }).approvals?.spend === true;
+  const neverOverMcp = (spec as { neverOverMcp?: unknown }).neverOverMcp === true;
   const wave = spec.waves.find((w) => w.name === name);
-  if (!wave) return { ...absent, spend };
+  if (!wave) return { ...absent, spend, neverOverMcp };
   const policy = wave.gate ?? "always";
   // An approval mode this chant does not know reads as sealed: the strictest, so an unknown rule never loosens a gate.
   const approval = wave.approval === undefined ? "ledger" : GATE_APPROVAL_SOURCES.includes(wave.approval) ? wave.approval : "sealed";
-  const rules: OpWaveBaseRules = { policy: OP_WAVE_GATE_POLICIES.includes(policy) ? policy : "always", approval, source: "base", base: sha, hooks: noHooks(), spend, applyHooksRunBy: "chant" };
+  const rules: OpWaveBaseRules = { policy: OP_WAVE_GATE_POLICIES.includes(policy) ? policy : "always", approval, source: "base", base: sha, hooks: noHooks(), spend, applyHooksRunBy: "chant", neverOverMcp };
   try {
     assertOpWaveHooks(`${specFile} at ${sha.slice(0, 12)}`, spec.hooks);
     assertOpWaveHooks(`${specFile} at ${sha.slice(0, 12)}, wave "${name}"`, wave.hooks);
@@ -481,9 +516,9 @@ function writeRunsFile(
  * for all of them (#3762). A wave plan is written out as each run's plan file
  * too, so a per-run `apply` or hook reads `{plan}` either way.
  */
-function planRuns(at: { spec: OpWavesSpec; k: number; wave: OpWave; cwd: string; exec: OpWaveExec }, runs: readonly OpWaveRun[]): OpWaveMember[] {
+function planRuns(at: { spec: OpWavesSpec; k: number; wave: OpWave; cwd: string; exec: OpWaveExec }, runs: readonly OpWaveRun[]): PlannedRuns {
   const { spec, k, wave, cwd, exec } = at;
-  if (!spec.planWave) return runs.map((run) => planRun({ spec, wave: k, cwd, exec }, wave.name, run));
+  if (!spec.planWave) return { members: runs.map((run) => planRun({ spec, wave: k, cwd, exec }, wave.name, run)) };
   const runsPath = writeRunsFile(at, runs);
   const plans = opWavePlansPath(spec, k);
   rmSync(join(cwd, plans), { force: true });
@@ -510,12 +545,40 @@ function planRuns(at: { spec: OpWavesSpec; k: number; wave: OpWave; cwd: string;
   }
   const missing = runs.filter((r) => !byTarget.has(r.target)).map((r) => r.target);
   if (missing.length > 0) throw new Error(`the plans file of wave ${k} (${plans}) has no plan for ${missing.join(", ")}`);
-  return runs.map((run) => {
+  const pending = Array.isArray(parsed) ? undefined : pendingFields((parsed as { pending?: unknown }).pending, `the plans file of wave ${k} (${plans})`);
+  const members = runs.map((run) => {
     const m = member(run.target, run.op ?? spec.op, byTarget.get(run.target)!);
     const path = join(cwd, opWavePlanPath(spec, k, run.target));
     writeFileSync(path, JSON.stringify({ planDigest: m.planDigest, ...(m.destructive ? { destructive: true } : {}), ...(m.empty ? { empty: true } : {}) }) + "\n");
     return m;
   });
+  return { members, ...(pending ? { pending } : {}) };
+}
+
+/** What planning a wave's runs gave: each run's plan, and the product's pending-fact fields (#3821). */
+interface PlannedRuns {
+  members: OpWaveMember[];
+  pending?: Record<string, unknown>;
+}
+
+/** A plans file's `pending` (#3821): an object whose keys chant does not write itself, `description` aside. Undefined when absent or empty. */
+function pendingFields(value: unknown, where: string): Record<string, unknown> | undefined {
+  if (value === undefined) return undefined;
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${where}: \`pending\` must be an object of fields for the pending fact`);
+  const reserved = Object.keys(value).filter((key) => (OP_WAVE_PENDING_RESERVED as readonly string[]).includes(key));
+  if (reserved.length > 0) throw new Error(`${where}: \`pending\` sets ${reserved.join(", ")}, which chant writes itself`);
+  if ("description" in value && typeof (value as { description?: unknown }).description !== "string") throw new Error(`${where}: pending.description must be a string`);
+  return Object.keys(value).length > 0 ? (value as Record<string, unknown>) : undefined;
+}
+
+/**
+ * A wave's set digest (#3821): {@link waveSetDigest} over its runs' plans,
+ * or under `digest.over: "changing"` over the runs whose plan is not empty,
+ * falling back to every run when all of them are empty.
+ */
+export function opWaveSetDigest(spec: Pick<OpWavesSpec, "digest">, members: ReadonlyArray<WaveMember & { empty?: boolean }>): string {
+  const changing = spec.digest?.over === "changing" ? members.filter((m) => m.empty !== true) : [];
+  return waveSetDigest(changing.length > 0 ? changing : members);
 }
 
 /** What one moment's hooks came to. */
@@ -647,11 +710,7 @@ export function readOpWaveHooksFile(path: string | undefined = process.env.CHANT
  * chant counts the moment as handled. A skip without a reason throws. `exec` runs one hook; inject it to run a hook
  * in process or to keep its output.
  */
-export function runOpWaveApplyHooks(
-  file: OpWaveHooksFile,
-  moment: OpWaveHookMoment,
-  options: { cwd?: string; exec?: OpWaveExec; log?: (line: string) => void; skip?: string } = {},
-): OpWaveApplyHooksRun {
+export function runOpWaveApplyHooks(file: OpWaveHooksFile, moment: OpWaveHookMoment, options: RunOpWaveApplyHooksOptions = {}): OpWaveApplyHooksRun {
   const cwd = options.cwd ?? process.cwd();
   const log = options.log ?? ((line: string) => console.error(line));
   let run: OpWaveApplyHooksRun;
@@ -786,7 +845,7 @@ export async function runOpWave(options: RunOpWaveOptions): Promise<RunOpWaveRes
     const slice = opWaveShare(wave.runs, options.share, shares);
     const before = runHooks(ctx, "before-plan", decision.hooks?.["before-plan"], slice);
     if (before.failed) return failed(ctx, `a hook before the plan failed, so nothing in share ${options.share} of wave ${k} was planned or applied`);
-    const members = planRuns(ctx, slice);
+    const { members } = planRuns(ctx, slice);
     const planned = new Map(members.map((m) => [m.member, m]));
     const after = runHooks(ctx, "after-plan", decision.hooks?.["after-plan"], slice, planned);
     if (after.failed) return failed(ctx, `a hook after the plan failed, so nothing in share ${options.share} of wave ${k} was applied`);
@@ -820,13 +879,14 @@ export async function runOpWave(options: RunOpWaveOptions): Promise<RunOpWaveRes
   }
   const before = runHooks(ctx, "before-plan", rules.hooks["before-plan"], wave.runs);
   if (before.failed) return failed(ctx, `a hook before the plan failed, so nothing in wave ${k} was planned or applied`);
-  const members = planRuns(ctx, wave.runs);
+  const { members, pending } = planRuns(ctx, wave.runs);
   const planned = new Map(members.map((m) => [m.member, m]));
-  const digest = waveSetDigest(members);
+  const digest = opWaveSetDigest(spec, members);
+  const neverOverMcp = rules.neverOverMcp || spec.neverOverMcp === true;
   const after = runHooks(ctx, "after-plan", rules.hooks["after-plan"], wave.runs, planned, digest);
   if (after.failed) return failed(ctx, `a hook after the plan failed, so nothing in wave ${k} was applied`);
   holds.push(...before.holds, ...after.holds);
-  const gate = waveGateName(spec.gate ?? spec.name, k);
+  const gate = opWaveGateName(spec, k);
   const hooks = Object.fromEntries(Object.entries(rules.hooks).filter(([, list]) => list.length > 0));
   const decision: OpWaveDecision = {
     wave: k,
@@ -844,6 +904,9 @@ export async function runOpWave(options: RunOpWaveOptions): Promise<RunOpWaveRes
     ...(holds.length > 0 ? { heldBy: holds } : {}),
     ...(rules.spend ? { spend: "base" as const } : spec.approvals?.spend === true ? { spend: "change" as const } : {}),
     ...(rules.applyHooksRunBy === "apply" ? { applyHooksRunBy: "apply" as const } : {}),
+    ...(spec.digest?.over === "changing" ? { digestOver: "changing" as const } : {}),
+    ...(pending ? { pending } : {}),
+    ...(neverOverMcp ? { neverOverMcp: true as const } : {}),
   };
   if (opWaveNeedsApproval(policy, members) || holds.length > 0) await settleGate(options, ctx, decision);
   // A wide wave's shares apply under the deciding job's approval, so it is spent here, once.
@@ -905,9 +968,11 @@ async function settleGate(options: RunOpWaveOptions, ctx: WaveContext, decision:
     op: spec.name,
     gate,
     planDigest: digest,
-    description: `wave ${k} (${wave.name}): ${members.length} run${members.length === 1 ? "" : "s"}, gate ${policy}, approval ${approval}${held}`,
+    description: (typeof decision.pending?.description === "string" ? decision.pending.description : undefined) ?? `wave ${k} (${wave.name}): ${members.length} run${members.length === 1 ? "" : "s"}, gate ${policy}, approval ${approval}${held}`,
     now,
     ...(spent ? { spent } : {}),
+    ...(decision.pending ? { fields: decision.pending } : {}),
+    ...(decision.neverOverMcp ? { neverOverMcp: true } : {}),
   });
   if (check.satisfied) {
     decision.status = "approved";
@@ -1279,8 +1344,8 @@ export async function recordOpWaveHeadPlans(options: RecordHeadPlansOptions): Pr
     head,
     timestamp: options.now ?? new Date().toISOString(),
     waves: spec.waves.map((wave, i) => {
-      const members = planRuns({ spec, k: i + 1, wave, cwd, exec }, wave.runs);
-      return { wave: i + 1, name: wave.name, digest: waveSetDigest(members) };
+      const { members } = planRuns({ spec, k: i + 1, wave, cwd, exec }, wave.runs);
+      return { wave: i + 1, name: wave.name, digest: opWaveSetDigest(spec, members) };
     }),
   };
   await (options.write ?? ((p) => writeHeadPlans(p, cwd)))(plans);

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

@@ -663,3 +663,99 @@ 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();
+  });
+});

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.
  *
@@ -170,12 +172,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[];
   /**
@@ -230,6 +248,28 @@ 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));
+}
+
 /** What happens to an approval once a wave applies under it (#3784). */
 export interface OpWavesApprovals {
   /**
@@ -331,6 +371,22 @@ 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.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}`);

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