@intentius/chant 0.114.1 → 0.116.0

package/src/op/activity-registry.ts

@@ -24,12 +24,29 @@ export type { ActivityProfile } from "./activity-profiles";
  */
 export type ActivityFn = (args: Record<string, unknown>, signal?: AbortSignal) => Promise<unknown>;
 
-/** Add every exported function from an activity module to `into`, keyed by name. */
+/**
+ * The export an activity module lists its fallback activities under: names it
+ * provides only when no other configured lexicon does (#3657). The sql
+ * lexicon's `receiptRead` / `receiptWrite` / `receiptStaleness` are the case:
+ * a project that uses only sql keeps its `effect()` receipts on its database
+ * server, and one that also configures aws or k8s keeps them in that
+ * lexicon's receipt row, whichever order `lexicons` lists them in.
+ */
+export const ACTIVITY_FALLBACKS_EXPORT = "ACTIVITY_FALLBACKS";
+
+/**
+ * Add every exported function from an activity module to `into`, keyed by
+ * name. A name the module lists in {@link ACTIVITY_FALLBACKS_EXPORT} is added
+ * only when nothing provides it yet; any other export replaces what is there,
+ * a fallback included.
+ */
 function collectActivities(mod: Record<string, unknown>, into: Map<string, ActivityFn>): void {
+  const listed = mod[ACTIVITY_FALLBACKS_EXPORT];
+  const fallbacks = new Set(Array.isArray(listed) ? listed.filter((n): n is string => typeof n === "string") : []);
   for (const [name, value] of Object.entries(mod)) {
-    if (typeof value === "function") {
-      into.set(name, value as ActivityFn);
-    }
+    if (typeof value !== "function") continue;
+    if (fallbacks.has(name) && into.has(name)) continue;
+    into.set(name, value as ActivityFn);
   }
 }
 
@@ -41,7 +58,10 @@ function collectActivities(mod: Record<string, unknown>, into: Map<string, Activ
  * Cloud-specific appliers live in their own lexicon (aws → `flociUp`/`flociDown`,
  * gcp → `gcpApply`, azure → `azGroupEnsure`/`azGroupDelete`), so `lexicons` —
  * the project's configured lexicon list — is consulted to pull those in. A
- * lexicon that ships no `op/activities` module is skipped.
+ * lexicon that ships no `op/activities` module is skipped. A lexicon's
+ * fallback activities ({@link ACTIVITY_FALLBACKS_EXPORT}) give way to another
+ * lexicon's activity of the same name; otherwise a later lexicon's export
+ * replaces an earlier one's.
  *
  * Never throws: the base library is a static import, so there is no "no
  * activities registered" state to report.

package/src/op/builders.ts

@@ -177,7 +177,8 @@ export function gate(
  * A gate authored inside `steps` is reached only when the effect will fire
  * (the matched path never reaches it). The receipt-store activities
  * (`receiptRead`, `receiptWrite`) are provided by the receipt row's lexicon
- * (#1835, aws).
+ * (#1835 aws, #2074 k8s), or in a sql-only project by the sql lexicon's
+ * store on the database server (#3657).
  *
  * @example
  * ```ts

package/src/op/generate-pipeline.ts

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

package/src/op/index.ts

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

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

@@ -0,0 +1,325 @@
+/**
+ * What an Op waves job runs (#3679): `chant run wave --spec <file> --wave <k>`.
+ * `./op-waves.ts` holds the spec and the jobs; this plans a wave's runs,
+ * decides its gate and applies it.
+ *
+ * - Plan: each run's `plan` command writes a plan file; its `planDigest` is
+ *   the run's member digest, named by its target.
+ * - Decide: the wave's policy comes from the spec file at the base commit
+ *   (`git show <base>:<file>`), so a change cannot loosen its own gate. A
+ *   wave missing there, or a file missing there, is `always`. A wave that
+ *   needs an approval waits on `<gate>-wave-<k>` bound to
+ *   {@link waveSetDigest} over its members, and exits 3 when nobody approved
+ *   that digest.
+ * - Apply: each run's `apply` command. A share job (`--share i`) re-plans its
+ *   slice first and refuses, without applying it, a run whose plan digest is
+ *   not the one the deciding job recorded (exit 4).
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, posix } from "node:path";
+import { waveGateName, waveSetDigest, type WaveMember } from "../gated-waves";
+import { approveCommand, evaluateGate, gitGateLedgerPort, type GateLedgerPort } from "./gate";
+import {
+  OP_WAVE_DEFAULT_APPLY,
+  OP_WAVE_GATE_POLICIES,
+  assertOpWavesSpec,
+  opWaveRecordPath,
+  opWaveShare,
+  type OpWaveGatePolicy,
+  type OpWaveRun,
+  type OpWavesSpec,
+} from "./op-waves";
+
+/** What a run's plan command writes to `{plan}`. */
+export interface OpWavePlanFile {
+  planDigest: string;
+  /** The plan destroys, rewrites or otherwise needs a person under `on-destructive`. */
+  destructive?: boolean;
+  /** The plan changes nothing. */
+  empty?: boolean;
+}
+
+/** One run's plan, as the decision records it. */
+export interface OpWaveMember extends WaveMember {
+  op: string;
+  destructive?: boolean;
+  empty?: boolean;
+}
+
+/** Where a wave's policy came from. */
+export type OpWavePolicySource = "base" | "absent-at-base";
+
+/** A wave's decision: what was planned, the policy, and whether it may apply. */
+export interface OpWaveDecision {
+  wave: number;
+  name: string;
+  /** The op the gate is recorded under: the spec's name. */
+  op: string;
+  gate: string;
+  policy: OpWaveGatePolicy;
+  policySource: OpWavePolicySource;
+  /** The base commit the policy was read at. */
+  base: string;
+  digest: string;
+  members: OpWaveMember[];
+  /** `approved`: an approval of this digest stands. `not-required`: the policy lets it through. `waiting`: neither. */
+  status: "approved" | "not-required" | "waiting";
+  approvedBy?: string;
+  /** The command that approves this digest, when waiting. */
+  approve?: string;
+}
+
+/** Runs one argv; returns its exit code. Injected so tests run no processes. */
+export type OpWaveExec = (argv: string[], cwd: string) => number;
+
+const spawnExec: OpWaveExec = (argv, cwd) => {
+  const result = spawnSync(argv[0]!, argv.slice(1), { cwd, stdio: "inherit" });
+  if (result.error) throw result.error;
+  return result.status ?? 1;
+};
+
+/** Reads one file at one commit, or null when the commit has no such file. Injected for tests. */
+export type OpWaveShowAtBase = (base: string, path: string, cwd: string) => { sha: string; text: string | null };
+
+const gitShowAtBase: OpWaveShowAtBase = (base, path, cwd) => {
+  let sha: string;
+  try {
+    sha = execFileSync("git", ["rev-parse", "--verify", `${base}^{commit}`], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+  } catch {
+    throw new Error(
+      `the gate policy is read at ${base}, which this checkout does not have. ` +
+        `Check out the full history (fetch-depth: 0 on GitHub and Forgejo, GIT_DEPTH: "0" on GitLab), or set the spec's base.`,
+    );
+  }
+  try {
+    const text = execFileSync("git", ["show", `${sha}:./${path}`], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+    return { sha, text };
+  } catch {
+    return { sha, text: null };
+  }
+};
+
+/** Read a spec file, refusing anything that is not one. */
+export function parseOpWavesSpec(text: string, where: string): OpWavesSpec {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw new Error(`${where}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const waves = (parsed as { waves?: unknown } | null)?.waves;
+  const spec = (Array.isArray(waves) ? parsed : waves) as OpWavesSpec | undefined;
+  if (!spec || typeof spec !== "object" || !Array.isArray(spec.waves)) {
+    throw new Error(`${where} must hold an Op waves spec: { "name", "op", "plan", "waves": [...] }, or { "waves": <that>, "options": {...} }`);
+  }
+  return spec;
+}
+
+/**
+ * The policy of wave `name`, as the spec file at `base` declares it. The
+ * file or the wave missing there reads as `always`: a change that adds a
+ * wave, or the file, waits for a person the first time.
+ */
+export function readOpWavePolicy(
+  specFile: string,
+  name: string,
+  base: string,
+  cwd: string,
+  show: OpWaveShowAtBase = gitShowAtBase,
+): { policy: OpWaveGatePolicy; source: OpWavePolicySource; base: string } {
+  const { sha, text } = show(base, specFile.replace(/^\.\//, "").split("\\").join(posix.sep), cwd);
+  if (text === null) return { policy: "always", source: "absent-at-base", base: sha };
+  let spec: OpWavesSpec;
+  try {
+    spec = parseOpWavesSpec(text, `${specFile} at ${base}`);
+  } catch {
+    return { policy: "always", source: "absent-at-base", base: sha };
+  }
+  const wave = spec.waves.find((w) => w.name === name);
+  if (!wave) return { policy: "always", source: "absent-at-base", base: sha };
+  const policy = wave.gate ?? "always";
+  return { policy: OP_WAVE_GATE_POLICIES.includes(policy) ? policy : "always", source: "base", base: sha };
+}
+
+/** Fill one argv template for one run. */
+export function opWaveArgv(template: readonly string[], values: { op: string; target: string; wave: string; plan: string }): string[] {
+  return template.map((part) =>
+    part.replaceAll("{op}", values.op).replaceAll("{target}", values.target).replaceAll("{wave}", values.wave).replaceAll("{plan}", values.plan),
+  );
+}
+
+/** Where a run's plan file goes. */
+export function opWavePlanPath(spec: Pick<OpWavesSpec, "name">, wave: number, target: string): string {
+  return `.chant/op-waves/${spec.name}/wave-${wave}/${target.replace(/[^A-Za-z0-9._-]/g, "_")}.plan.json`;
+}
+
+export interface RunOpWaveOptions {
+  spec: OpWavesSpec;
+  specFile: string;
+  /** 1-based. */
+  wave: number;
+  /** Plan and decide only (a wide wave's deciding job). */
+  decide?: boolean;
+  /** Apply this 1-based share of a decided wave. */
+  share?: number;
+  /** Overrides the spec's base. */
+  base?: string;
+  cwd?: string;
+  gates?: GateLedgerPort;
+  exec?: OpWaveExec;
+  show?: OpWaveShowAtBase;
+  now?: string;
+  log?: (line: string) => void;
+}
+
+export interface RunOpWaveResult {
+  /** 0 applied (or decided), 1 a run failed, 3 waiting for an approval, 4 a plan moved since the decision. */
+  exitCode: number;
+  decision?: OpWaveDecision;
+  applied: string[];
+  failed: string[];
+  /** Runs a share job refused because their plan moved since the decision. */
+  moved: string[];
+}
+
+function planRun(
+  opts: Required<Pick<RunOpWaveOptions, "spec" | "wave">> & { cwd: string; exec: OpWaveExec },
+  waveName: string,
+  run: OpWaveRun,
+): OpWaveMember {
+  const op = run.op ?? opts.spec.op;
+  const plan = opWavePlanPath(opts.spec, opts.wave, run.target);
+  mkdirSync(dirname(join(opts.cwd, plan)), { recursive: true });
+  const code = opts.exec(opWaveArgv(opts.spec.plan, { op, target: run.target, wave: waveName, plan }), opts.cwd);
+  if (code !== 0) throw new Error(`planning ${run.target} exited ${code}`);
+  let file: OpWavePlanFile;
+  try {
+    file = JSON.parse(readFileSync(join(opts.cwd, plan), "utf-8")) as OpWavePlanFile;
+  } catch (err) {
+    throw new Error(`planning ${run.target} wrote no readable plan file at ${plan}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (typeof file.planDigest !== "string" || file.planDigest === "") {
+    throw new Error(`the plan file for ${run.target} (${plan}) has no planDigest`);
+  }
+  return {
+    member: run.target,
+    planDigest: file.planDigest,
+    op,
+    ...(file.destructive === true ? { destructive: true } : {}),
+    ...(file.empty === true ? { empty: true } : {}),
+  };
+}
+
+/** Whether `policy` lets a wave with these members through without an approval. */
+export function opWaveNeedsApproval(policy: OpWaveGatePolicy, members: readonly OpWaveMember[]): boolean {
+  if (policy === "never") return false;
+  if (members.every((m) => m.empty === true)) return false;
+  if (policy === "on-destructive") return members.some((m) => m.destructive === true);
+  return true;
+}
+
+/** Plan, decide and apply one wave, or one part of a wide wave. */
+export async function runOpWave(options: RunOpWaveOptions): Promise<RunOpWaveResult> {
+  const { spec, wave: k } = options;
+  assertOpWavesSpec(spec);
+  const cwd = options.cwd ?? process.cwd();
+  const exec = options.exec ?? spawnExec;
+  const log = options.log ?? ((line: string) => console.error(line));
+  const wave = spec.waves[k - 1];
+  if (!wave) throw new Error(`Op waves "${spec.name}" has ${spec.waves.length} waves; there is no wave ${k}.`);
+  const shares = wave.shares ?? 1;
+  if (options.share !== undefined && (options.share < 1 || options.share > shares)) {
+    throw new Error(`wave ${k} (${wave.name}) has ${shares} share${shares === 1 ? "" : "s"}; there is no share ${options.share}.`);
+  }
+  const ctx = { spec, wave: k, cwd, exec };
+  const recordPath = join(cwd, opWaveRecordPath(spec, k));
+  const result: RunOpWaveResult = { exitCode: 0, applied: [], failed: [], moved: [] };
+
+  if (options.share !== undefined) {
+    let decision: OpWaveDecision;
+    try {
+      decision = JSON.parse(readFileSync(recordPath, "utf-8")) as OpWaveDecision;
+    } catch {
+      throw new Error(`share ${options.share} of wave ${k} (${wave.name}) found no decision at ${opWaveRecordPath(spec, k)}. Run the deciding job first.`);
+    }
+    result.decision = decision;
+    if (decision.status === "waiting") {
+      log(`wave ${k} (${wave.name}) is waiting on ${decision.gate}; nothing applied. ${decision.approve ?? ""}`.trim());
+      return { ...result, exitCode: 3 };
+    }
+    const decided = new Map(decision.members.map((m) => [m.member, m.planDigest]));
+    for (const run of opWaveShare(wave.runs, options.share, shares)) {
+      const member = planRun(ctx, wave.name, run);
+      if (decided.get(run.target) !== member.planDigest) {
+        log(
+          `${run.target}: its plan moved since wave ${k} was decided, so it was not applied. ` +
+            `decided: ${decided.get(run.target) ?? "(not in the decision)"}; planned now: ${member.planDigest}`,
+        );
+        result.moved.push(run.target);
+        continue;
+      }
+      applyRun(spec, wave.name, k, run, cwd, exec, result, log);
+    }
+    result.exitCode = result.failed.length > 0 ? 1 : result.moved.length > 0 ? 4 : 0;
+    return result;
+  }
+
+  const members = wave.runs.map((run) => planRun(ctx, wave.name, run));
+  const digest = waveSetDigest(members);
+  const { policy, source, base } = readOpWavePolicy(options.specFile, wave.name, options.base ?? spec.base ?? "HEAD^1", cwd, options.show);
+  const gate = waveGateName(spec.gate ?? spec.name, k);
+  const decision: OpWaveDecision = { wave: k, name: wave.name, op: spec.name, gate, policy, policySource: source, base, digest, members, status: "not-required" };
+  if (opWaveNeedsApproval(policy, members)) {
+    const check = await evaluateGate(options.gates ?? gitGateLedgerPort({ cwd }), {
+      op: spec.name,
+      gate,
+      planDigest: digest,
+      description: `wave ${k} (${wave.name}): ${members.length} run${members.length === 1 ? "" : "s"}, gate ${policy}`,
+      ...(options.now ? { now: options.now } : {}),
+    });
+    if (check.satisfied) {
+      decision.status = "approved";
+      decision.approvedBy = check.resolution.resolvedBy;
+    } else {
+      decision.status = "waiting";
+      decision.approve = approveCommand(spec.name, gate, undefined, digest);
+    }
+  }
+  mkdirSync(dirname(recordPath), { recursive: true });
+  writeFileSync(recordPath, JSON.stringify(decision, null, 2) + "\n");
+  result.decision = decision;
+  log(
+    `wave ${k} (${wave.name}): gate ${policy} (read at ${base.slice(0, 12)}${source === "absent-at-base" ? ", where the wave is absent" : ""}), ` +
+      `digest ${digest}: ${decision.status}${decision.approvedBy ? ` by ${decision.approvedBy}` : ""}`,
+  );
+  if (decision.status === "waiting") {
+    log(`Nothing in wave ${k} or after it ran. Read the plans, then approve: ${decision.approve}`);
+    return { ...result, exitCode: 3 };
+  }
+  if (options.decide) return result;
+  for (const run of wave.runs) applyRun(spec, wave.name, k, run, cwd, exec, result, log);
+  result.exitCode = result.failed.length > 0 ? 1 : 0;
+  return result;
+}
+
+function applyRun(
+  spec: OpWavesSpec,
+  waveName: string,
+  k: number,
+  run: OpWaveRun,
+  cwd: string,
+  exec: OpWaveExec,
+  result: RunOpWaveResult,
+  log: (line: string) => void,
+): void {
+  const op = run.op ?? spec.op;
+  const plan = opWavePlanPath(spec, k, run.target);
+  const code = exec(opWaveArgv(spec.apply ?? OP_WAVE_DEFAULT_APPLY, { op, target: run.target, wave: waveName, plan }), cwd);
+  if (code === 0) result.applied.push(run.target);
+  else {
+    log(`${run.target}: apply exited ${code}`);
+    result.failed.push(run.target);
+  }
+}

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

@@ -0,0 +1,95 @@
+import { describe, expect, test } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { opWaveJobs, opWaveShare, type OpWavesSpec } from "./op-waves";
+import { runOpWave, type OpWaveExec, type OpWaveShowAtBase } from "./op-waves-run";
+import { memoryGateLedgerPort } from "./gate";
+import { waveSetDigest } from "../gated-waves";
+
+const spec: OpWavesSpec = {
+  name: "migrations",
+  op: "migrate",
+  plan: ["tool", "plan", "{target}", "--out", "{plan}"],
+  apply: ["tool", "apply", "{target}", "--plan", "{plan}"],
+  waves: [
+    { name: "dev", runs: [{ target: "dev" }], gate: "never" },
+    { name: "staging", runs: [{ target: "staging" }], gate: "on-destructive" },
+    { name: "prod", runs: [{ target: "t3" }, { target: "t1" }, { target: "t2" }], shares: 2 },
+  ],
+};
+
+describe("opWaveJobs", () => {
+  test("one job per wave, a deciding job and share jobs for a wide one, each wave needing the last", () => {
+    const jobs = opWaveJobs(spec, "waves.json");
+    expect(jobs.map((j) => [j.jobName, j.needs])).toEqual([
+      ["wave-1-dev", []],
+      ["wave-2-staging", ["wave-1-dev"]],
+      ["wave-3-prod-decide", ["wave-2-staging"]],
+      ["wave-3-prod-share-1", ["wave-3-prod-decide"]],
+      ["wave-3-prod-share-2", ["wave-3-prod-decide"]],
+    ]);
+    expect(jobs[2]!.command.join(" ")).toBe("chant run wave --spec waves.json --wave 3 --decide");
+    expect(jobs[4]!.command.join(" ")).toBe("chant run wave --spec waves.json --wave 3 --share 2");
+  });
+
+  test("shares slice the runs by target", () => {
+    const runs = spec.waves[2]!.runs;
+    expect(opWaveShare(runs, 1, 2).map((r) => r.target)).toEqual(["t1", "t2"]);
+    expect(opWaveShare(runs, 2, 2).map((r) => r.target)).toEqual(["t3"]);
+  });
+});
+
+describe("runOpWave", () => {
+  function harness(plans: Record<string, { planDigest: string; destructive?: boolean }>, policyAtBase: string | null) {
+    const cwd = mkdtempSync(join(tmpdir(), "op-waves-"));
+    const calls: string[] = [];
+    const exec: OpWaveExec = (argv, dir) => {
+      calls.push(argv.join(" "));
+      if (argv[1] === "plan") writeFileSync(join(dir, argv[4]!), JSON.stringify(plans[argv[2]!]));
+      return 0;
+    };
+    const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: policyAtBase });
+    return { cwd, calls, exec, show, done: () => rmSync(cwd, { recursive: true, force: true }) };
+  }
+  const digest = (n: string) => `sha256:${n.repeat(64)}`;
+
+  test("the policy comes from the base commit: a change that sets staging to never still waits", async () => {
+    const h = harness({ staging: { planDigest: digest("a"), destructive: true } }, JSON.stringify(spec));
+    const loosened = { ...spec, waves: spec.waves.map((w) => ({ ...w, gate: "never" as const })) };
+    const gates = memoryGateLedgerPort();
+    const result = await runOpWave({ spec: loosened, specFile: "waves.json", wave: 2, cwd: h.cwd, exec: h.exec, show: h.show, gates });
+    expect(result.exitCode).toBe(3);
+    expect(result.decision).toMatchObject({ policy: "on-destructive", policySource: "base", status: "waiting", gate: "migrations-wave-2" });
+    expect(gates.appended[0]!.planDigest).toBe(waveSetDigest([{ member: "staging", planDigest: digest("a") }]));
+    expect(h.calls.some((c) => c.startsWith("tool apply"))).toBe(false);
+    h.done();
+  });
+
+  test("an approval of the set digest lets the wave apply; a non-destructive plan needs none", async () => {
+    const h = harness({ staging: { planDigest: digest("a"), destructive: true } }, JSON.stringify(spec));
+    const set = waveSetDigest([{ member: "staging", planDigest: digest("a") }]);
+    const gates = memoryGateLedgerPort({
+      resolutions: [{ version: 1, op: "migrations", gate: "migrations-wave-2", resolvedBy: "alice", timestamp: "2026-10-10T00:00:00Z", planDigest: set }],
+    });
+    const approved = await runOpWave({ spec, specFile: "waves.json", wave: 2, cwd: h.cwd, exec: h.exec, show: h.show, gates });
+    expect(approved).toMatchObject({ exitCode: 0, applied: ["staging"], decision: { status: "approved", approvedBy: "alice" } });
+    h.done();
+
+    const quiet = harness({ staging: { planDigest: digest("c") } }, JSON.stringify(spec));
+    const free = await runOpWave({ spec, specFile: "waves.json", wave: 2, cwd: quiet.cwd, exec: quiet.exec, show: quiet.show, gates: memoryGateLedgerPort() });
+    expect(free).toMatchObject({ exitCode: 0, applied: ["staging"], decision: { status: "not-required" } });
+    quiet.done();
+  });
+
+  test("a share refuses a run whose plan moved since the decision", async () => {
+    const plans: Record<string, { planDigest: string }> = { t1: { planDigest: digest("1") }, t2: { planDigest: digest("2") }, t3: { planDigest: digest("3") } };
+    const h = harness(plans, JSON.stringify({ ...spec, waves: spec.waves.map((w) => ({ ...w, gate: "never" })) }));
+    const decided = await runOpWave({ spec, specFile: "waves.json", wave: 3, decide: true, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort() });
+    expect(decided).toMatchObject({ exitCode: 0, applied: [], decision: { status: "not-required" } });
+    plans.t2 = { planDigest: digest("9") };
+    const share = await runOpWave({ spec, specFile: "waves.json", wave: 3, share: 1, cwd: h.cwd, exec: h.exec, show: h.show });
+    expect(share).toMatchObject({ exitCode: 4, applied: ["t1"], moved: ["t2"] });
+    h.done();
+  });
+});