@intentius/chant 0.70.0 → 0.71.0

package/src/cli/registry.ts

@@ -183,6 +183,29 @@ export interface ParsedArgs {
   head?: string;
   /** `chant lifecycle affected --include-dependents` — add downstream consumers */
   includeDependents?: boolean;
+  /**
+   * `chant components fan-out --from-affected <file>` (#2420) — read the
+   * stack-level change signal from the JSON `chant lifecycle affected --json`
+   * wrote, instead of re-deriving it with `--base`. The composable half of the
+   * pair: a CI job that already ran the diff has no reason to build twice.
+   */
+  fromAffected?: string;
+  /**
+   * `chant components fan-out --gate <name>` (#2420) — the name of the single
+   * gate over the whole derived set, answered by `chant approve fan-out <name>
+   * --plan <digest>`. One approval covers the fan-out, bound to the plan's
+   * digest (#2300's mechanism, #2417's decision); omitted, the fan-out runs
+   * ungated. A component's own authored gates are unaffected either way.
+   */
+  gate?: string;
+  /**
+   * `chant components fan-out --resume <file>` (#2420) — the attempt record
+   * this fan-out reads before it starts and writes when it finishes. Repeating
+   * the identical command finishes what an interrupted attempt left, because
+   * the plan is narrowed by this file before the gate is decided and the
+   * digest is carried rather than recomputed, so the approval still stands.
+   */
+  resume?: string;
   /** `chant audit --tier merge-worthy|all` */
   tier?: string;
   /**

package/src/components/deploy-units.ts

@@ -14,7 +14,17 @@
  * The registry is data, not a rule about what steps look like — a kind not
  * listed here contributes no unit, exactly as before.
  */
-import type { Phase } from "./component";
+/**
+ * The only shape this walk reads: something with `steps`, whose entries may
+ * carry a `kind` and may themselves nest. Both `Phase` (./component.ts) and
+ * `DriverPhase` (./driver.ts) satisfy it — they differ on how a gate step is
+ * typed, which this module never looks at — so declaring the narrower of the
+ * two would force a cast on one caller for no gain in safety, given the walk
+ * discriminates structurally anyway.
+ */
+export interface UnitBearingPhase {
+  steps: readonly unknown[];
+}
 
 /** A deploy-family step kind that names a live unit, and who observes it. */
 export interface DeployUnitRule {
@@ -61,17 +71,17 @@ export interface DeployUnit {
  * order. A step may itself be a nested `Phase`, so the walk recurses; a
  * resolved component carries the unit as a concrete string. Pure.
  */
-export function deployUnits(deploy: Phase[]): DeployUnit[] {
+export function deployUnits(deploy: readonly UnitBearingPhase[]): DeployUnit[] {
   const byKind = new Map(DEPLOY_UNIT_RULES.map((r) => [r.kind, r]));
   const seen = new Set<string>();
   const units: DeployUnit[] = [];
-  const walkSteps = (steps: Phase["steps"]): void => {
+  const walkSteps = (steps: readonly unknown[]): void => {
     for (const step of steps) {
       // A step may itself be a nested Phase (it carries its own `steps`). Step
       // is open-typed (capability inputs), so discriminate structurally.
       const nested = (step as { steps?: unknown }).steps;
       if (Array.isArray(nested)) {
-        walkSteps(nested as Phase["steps"]);
+        walkSteps(nested as readonly unknown[]);
         continue;
       }
       const s = step as { kind?: string } & Record<string, unknown>;

package/src/components/fan-out-output.test.ts

@@ -0,0 +1,216 @@
+/**
+ * The printed derivation (#2420).
+ *
+ * #2417's eighth proof line is "the order was derived, with the derivation
+ * printed". These tests hold the render to what makes that claim checkable by
+ * a reader: the waves, a reason beside every component that is not running,
+ * the third outcome, the seeds, and the digest verbatim.
+ */
+
+import { describe, test, expect } from "vitest";
+import { planFanOut, type FanOutPlan } from "./fan-out";
+import { renderFanOutPlan, renderFanOutHuman, renderFanOutJson } from "./fan-out-output";
+import type { FanOutRunResult } from "./fan-out-run";
+import type { DriverComponent } from "./driver";
+
+const c = (name: string, dependsOn?: string[]): DriverComponent => ({
+  name,
+  deploy: [{ phase: "Deploy", steps: [{ kind: "ok-step" }] }],
+  ...(dependsOn ? { dependsOn } : {}),
+});
+
+/** net -> two clusters -> three apps, plus an unrelated branch. #2417's proof shape. */
+const ESTATE: DriverComponent[] = [
+  c("net"),
+  c("cluster-a", ["net"]),
+  c("cluster-b", ["net"]),
+  c("app-one", ["cluster-a"]),
+  c("app-two", ["cluster-a"]),
+  c("app-three", ["cluster-b"]),
+  c("billing"),
+  c("nightly-etl"),
+];
+
+function capture(): { lines: string[]; write: (line: string) => void } {
+  const lines: string[] = [];
+  return { lines, write: (line) => lines.push(line) };
+}
+
+function render(plan: FanOutPlan, gate?: { op: string; gate: string }): string {
+  const { lines, write } = capture();
+  renderFanOutPlan(plan, { write, ...(gate ? { gate } : {}) });
+  return lines.join("\n");
+}
+
+describe("the derivation", () => {
+  test("prints the waves, so the order reads as a graph rather than a list", () => {
+    const out = render(planFanOut({ components: ESTATE, changed: ["net"] }));
+    expect(out).toContain("wave 1: net");
+    expect(out).toContain("wave 2: cluster-a, cluster-b");
+    expect(out).toContain("wave 3: app-one, app-three, app-two");
+  });
+
+  test("counts all three outcomes, never two", () => {
+    const out = render(
+      planFanOut({ components: ESTATE, changed: ["cluster-b"], indeterminate: ["nightly-etl"] }),
+    );
+    expect(out).toMatch(/^fan-out: 2 selected, 5 unaffected, 1 indeterminate$/m);
+  });
+
+  test("every component that is not running carries its reason", () => {
+    const out = render(
+      planFanOut({ components: ESTATE, changed: ["cluster-b"], indeterminate: ["nightly-etl"] }),
+    );
+    expect(out).toContain("not running (6):");
+    expect(out).toMatch(/billing +unaffected/);
+    expect(out).toMatch(/nightly-etl +indeterminate/);
+  });
+
+  test("an indeterminate component the walk did not reach is named on its own line", () => {
+    const out = render(
+      planFanOut({ components: ESTATE, changed: ["cluster-b"], indeterminate: ["nightly-etl"] }),
+    );
+    expect(out).toContain("the walk did not reach them: nightly-etl");
+  });
+
+  test("an indeterminate component the walk did reach is selected, and is not reported as undecided", () => {
+    const out = render(
+      planFanOut({ components: ESTATE, changed: ["net"], indeterminate: ["app-two"] }),
+    );
+    expect(out).toContain("wave 3: app-one, app-three, app-two");
+    expect(out).not.toContain("the walk did not reach them");
+    expect(out).toMatch(/^fan-out: 6 selected, 2 unaffected, 0 indeterminate$/m);
+  });
+
+  test("names the dependencies whose outputs are taken on trust", () => {
+    const out = render(planFanOut({ components: ESTATE, changed: ["cluster-a"] }));
+    expect(out).toContain("seeded from an earlier run: net");
+  });
+
+  test("prints the digest verbatim, because it is what `chant approve --plan` takes", () => {
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    const out = render(plan, { op: "fan-out", gate: "release" });
+    expect(out).toContain(`plan: ${plan.digest}`);
+    expect(out).toContain(`chant approve fan-out release --plan ${plan.digest}`);
+    // Nothing abbreviates it: the whole 64-hex string is on the line.
+    expect(plan.digest).toMatch(/^sha256:[0-9a-f]{64}$/);
+  });
+
+  test("says so plainly when a change propagates to nothing", () => {
+    const plan: FanOutPlan = {
+      order: [],
+      waves: [],
+      skipped: [],
+      seeds: [],
+      indeterminate: [],
+      digest: "sha256:" + "0".repeat(64),
+    };
+    expect(render(plan)).toContain("nothing to run");
+  });
+});
+
+describe("a dispatched fan-out", () => {
+  const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+
+  const result = (over: Partial<FanOutRunResult>): FanOutRunResult => ({
+    plan,
+    status: "ok",
+    results: [],
+    completed: [],
+    failed: [],
+    blocked: [],
+    componentOutputs: {},
+    ...over,
+  });
+
+  test("a failure prints the blocked subtree naming the failure, not the nearest edge", () => {
+    const { lines, write } = capture();
+    renderFanOutHuman(
+      result({
+        status: "fail",
+        completed: ["cluster-b", "net", "app-three"],
+        failed: ["cluster-a"],
+        blocked: [
+          { component: "app-one", reason: "blocked", blockedBy: "cluster-a" },
+          { component: "app-two", reason: "blocked", blockedBy: "cluster-a" },
+        ],
+      }),
+      { write },
+    );
+    const out = lines.join("\n");
+    expect(out).toContain('app-one: blocked by "cluster-a", so it never ran');
+    expect(out).toContain('app-two: blocked by "cluster-a", so it never ran');
+    // The independent branch is still reported as applied.
+    expect(out).toContain("applied: cluster-b, net, app-three");
+    expect(out).toContain("fan-out failed: 3 applied, 1 failed, 2 blocked");
+  });
+
+  test("a gated run says nothing ran, and names the gate", () => {
+    const { lines, write } = capture();
+    renderFanOutHuman(
+      result({
+        status: "gated",
+        gate: {
+          version: 1,
+          kind: "pending",
+          op: "fan-out",
+          gate: "release",
+          timestamp: "2026-01-01T00:00:00Z",
+          expiresAt: "2026-01-03T00:00:00Z",
+          planDigest: plan.digest,
+        },
+      }),
+      { write },
+    );
+    const out = lines.join("\n");
+    expect(out).toContain("gated: nothing ran.");
+    expect(out).toContain('Waiting on "release" on "fan-out".');
+    expect(out).toContain("expires: 2026-01-03T00:00:00Z");
+  });
+
+  test("the plan printed is the one dispatched, so a resume shows what it is skipping", () => {
+    const { lines, write } = capture();
+    renderFanOutHuman(
+      result({
+        plan: {
+          ...plan,
+          order: ["app-one"],
+          waves: [["app-one"]],
+          skipped: [
+            { component: "billing", reason: "unaffected" },
+            { component: "cluster-a", reason: "already-applied" },
+            { component: "net", reason: "already-applied" },
+          ],
+        },
+        completed: ["app-one"],
+      }),
+      { write },
+    );
+    const out = lines.join("\n");
+    expect(out).toMatch(/net +already-applied/);
+    expect(out).toMatch(/cluster-a +already-applied/);
+    expect(out).toContain("fan-out completed: 1 applied, 0 failed, 0 blocked");
+  });
+});
+
+describe("the JSON render", () => {
+  test("emits one line, and the plan round-trips", () => {
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    const { lines, write } = capture();
+    renderFanOutJson(plan, write);
+    expect(lines).toHaveLength(1);
+    expect(JSON.parse(lines[0])).toEqual(plan);
+  });
+
+  test("a run result carries its plan, which is how a consumer tells the two apart", () => {
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    const { lines, write } = capture();
+    renderFanOutJson(
+      { plan, status: "ok", results: [], completed: [], failed: [], blocked: [], componentOutputs: {} },
+      write,
+    );
+    const parsed = JSON.parse(lines[0]) as FanOutRunResult;
+    expect(parsed.plan.digest).toBe(plan.digest);
+    expect(parsed.status).toBe("ok");
+  });
+});

package/src/components/fan-out-output.ts

@@ -0,0 +1,162 @@
+/**
+ * Renderers for a derived fan-out (#2420) — the printed derivation #2417's
+ * proof list asks for and nothing produced.
+ *
+ * `./driver-output.ts` is the precedent and the shape is deliberately the
+ * same: a human renderer that logs to stderr, a JSON renderer that owns
+ * stdout and writes nothing else, both over the types the model already
+ * returns (`./fan-out.ts`'s `FanOutPlan`, `./fan-out-run.ts`'s
+ * `FanOutRunResult`). No new fields are computed here. A renderer that had to
+ * derive something to print it would be deriving it twice.
+ *
+ * ## What gets printed, and why each line is not optional
+ *
+ * A fan-out that applies the right components without saying why it picked
+ * them reads exactly like one that fanned out to everything, which is the
+ * failure #2417's precision decision exists to prevent. So:
+ *
+ * - **the waves**, because the claim is that the order was derived from the
+ *   source rather than declared, and a flat list cannot show that
+ * - **every component that is not running, with its reason** — `unaffected`,
+ *   `indeterminate`, `already-applied`, `blocked` — because "absent from the
+ *   list" and "deliberately held back" look identical otherwise
+ * - **`indeterminate` on its own line**, because it is the third outcome and a
+ *   two-state render would quietly drop it into one of the other two
+ * - **`seeds`**, because those values are being taken on trust from a run that
+ *   happened earlier and somewhere else
+ * - **the `digest`, verbatim and unabbreviated**, because it is the string
+ *   `chant approve --plan` takes. Truncating it for width would make the line
+ *   unusable for the one job it has.
+ */
+
+import type { FanOutPlan, FanOutSkip } from "./fan-out";
+import type { FanOutRunResult } from "./fan-out-run";
+
+type Writer = (line: string) => void;
+
+const stderr: Writer = (line) => process.stderr.write(line + "\n");
+const stdout: Writer = (line) => process.stdout.write(line + "\n");
+
+/** The gate one fan-out is bound to, when the invocation asked for one. */
+export interface FanOutGateRef {
+  op: string;
+  gate: string;
+}
+
+export interface FanOutRenderOptions {
+  write?: Writer;
+  /** Present when a gate covers the set, so the render can print the exact approve line. */
+  gate?: FanOutGateRef;
+}
+
+/** `unaffected` → `unaffected`; `blocked` also names the failure it was reached from. */
+function reasonOf(skip: FanOutSkip): string {
+  return skip.reason === "blocked" && skip.blockedBy
+    ? `blocked by "${skip.blockedBy}"`
+    : skip.reason;
+}
+
+/** Longest component name in `skips`, for a column that lines up without padding every render. */
+function widestName(skips: readonly FanOutSkip[]): number {
+  return skips.reduce((w, s) => Math.max(w, s.component.length), 0);
+}
+
+/**
+ * The derivation itself: the waves, what is not running and why, what is
+ * seeded, and the digest an approval binds to.
+ *
+ * This is the whole output of a plan-only invocation and the header of a run,
+ * so it is one function rather than two nearly identical ones.
+ */
+export function renderFanOutPlan(plan: FanOutPlan, options: FanOutRenderOptions = {}): void {
+  const write = options.write ?? stderr;
+
+  // Three outcomes, never two (#2417). The counts come first because they are
+  // the claim the rest of the block substantiates.
+  const unaffected = plan.skipped.filter((s) => s.reason === "unaffected").length;
+  const held = plan.skipped.filter((s) => s.reason === "already-applied" || s.reason === "blocked").length;
+  write(
+    `fan-out: ${plan.order.length} selected, ${unaffected} unaffected, ` +
+      `${plan.indeterminate.length} indeterminate` +
+      (held > 0 ? `, ${held} held back` : ""),
+  );
+
+  if (plan.order.length === 0) {
+    write("  nothing to run");
+  } else {
+    for (const [index, wave] of plan.waves.entries()) {
+      write(`  wave ${index + 1}: ${wave.join(", ")}`);
+    }
+  }
+
+  if (plan.seeds.length > 0) {
+    write(`  seeded from an earlier run: ${plan.seeds.join(", ")}`);
+  }
+
+  if (plan.skipped.length > 0) {
+    write(`  not running (${plan.skipped.length}):`);
+    const width = widestName(plan.skipped);
+    for (const skip of plan.skipped) {
+      write(`    ${skip.component.padEnd(width)}  ${reasonOf(skip)}`);
+    }
+  }
+
+  if (plan.indeterminate.length > 0) {
+    // Named separately from the `indeterminate` rows above because the two say
+    // different things: those rows are "not selected", this line is "a source
+    // diff could not judge it and the walk never reached it either", which is
+    // the one outcome nobody should read as a decision.
+    write(
+      `  a source diff cannot judge these, and the walk did not reach them: ` +
+        plan.indeterminate.join(", "),
+    );
+  }
+
+  // Verbatim: this is the string `chant approve --plan` takes.
+  write(`  plan: ${plan.digest}`);
+  if (options.gate) {
+    write(`  approve: chant approve ${options.gate.op} ${options.gate.gate} --plan ${plan.digest}`);
+  }
+}
+
+/**
+ * A dispatched fan-out: the derivation that ran, then what it did.
+ *
+ * `result.plan` is the plan as dispatched, so on a resume this prints the
+ * narrowed one, with everything an earlier attempt finished listed as
+ * `already-applied`. That is the point of printing the plan off the result
+ * rather than off whatever the caller derived.
+ */
+export function renderFanOutHuman(result: FanOutRunResult, options: FanOutRenderOptions = {}): void {
+  const write = options.write ?? stderr;
+  renderFanOutPlan(result.plan, { ...options, write });
+
+  if (result.status === "gated") {
+    const gate = result.gate;
+    write(`gated: nothing ran. ${gate ? `Waiting on "${gate.gate}" on "${gate.op}".` : "Waiting on an approval."}`);
+    if (gate?.expiresAt) write(`  expires: ${gate.expiresAt}`);
+    return;
+  }
+
+  if (result.completed.length > 0) write(`applied: ${result.completed.join(", ")}`);
+  if (result.failed.length > 0) write(`failed: ${result.failed.join(", ")}`);
+  for (const blocked of result.blocked) {
+    write(`  ${blocked.component}: ${reasonOf(blocked)}, so it never ran`);
+  }
+
+  const counts =
+    `${result.completed.length} applied, ${result.failed.length} failed, ` +
+    `${result.blocked.length} blocked`;
+  write(result.status === "ok" ? `fan-out completed: ${counts}` : `fan-out failed: ${counts}`);
+}
+
+/**
+ * The plan or the run result as JSON on stdout, and nothing else on stdout.
+ *
+ * One function for both because the run result carries the plan under `plan`,
+ * so a consumer discriminates on that key rather than on a flag it was told
+ * about out of band.
+ */
+export function renderFanOutJson(payload: FanOutPlan | FanOutRunResult, write: Writer = stdout): void {
+  write(JSON.stringify(payload));
+}

package/src/components/fan-out-run.test.ts

@@ -0,0 +1,194 @@
+/**
+ * Dispatching a derived fan-out (#2417).
+ *
+ * The behaviours here are the ones the issue said should not be implicit: one
+ * approval over the whole set, a failure that skips its own subtree and leaves
+ * independent branches alone, and a re-run that finishes without hand repair.
+ */
+
+import { describe, test, expect } from "vitest";
+import { CapabilityRegistry, type DeployContext } from "./capability";
+import { memoryGateLedgerPort } from "../op/gate";
+import { planFanOut } from "./fan-out";
+import { runFanOut } from "./fan-out-run";
+import type { DriverComponent } from "./driver";
+
+/** A component whose single deploy step calls `kind`. */
+const c = (name: string, kind: string, dependsOn?: string[]): DriverComponent => ({
+  name,
+  deploy: [{ phase: "Deploy", steps: [{ kind }] }],
+  ...(dependsOn ? { dependsOn } : {}),
+});
+
+/** net → cluster-a, cluster-b → apps. The issue's proof shape. */
+const ESTATE: DriverComponent[] = [
+  c("net", "ok-step"),
+  c("cluster-a", "ok-step", ["net"]),
+  c("cluster-b", "ok-step", ["net"]),
+  c("app-one", "ok-step", ["cluster-a"]),
+  c("app-two", "ok-step", ["cluster-a"]),
+  c("app-three", "ok-step", ["cluster-b"]),
+];
+
+function registryWith(failing: string[] = []): { registry: CapabilityRegistry; ran: string[] } {
+  const ran: string[] = [];
+  const registry = new CapabilityRegistry();
+  registry.register({
+    kind: "ok-step",
+    async run(ctx: DeployContext) {
+      ran.push(ctx.component);
+      if (failing.includes(ctx.component)) throw new Error(`${ctx.component} failed`);
+      return { ok: true };
+    },
+  } as never);
+  return { registry, ran };
+}
+
+const opts = () => ({ env: "test", gates: memoryGateLedgerPort(), now: "2026-01-01T00:00:00Z" });
+
+describe("dispatching the plan", () => {
+  test("every downstream component runs, in derived order, and nothing else", async () => {
+    const estate = [...ESTATE, c("billing", "ok-step")];
+    const plan = planFanOut({ components: estate, changed: ["net"] });
+    const { registry, ran } = registryWith();
+
+    const result = await runFanOut(plan, estate, registry, opts());
+
+    expect(result.status).toBe("ok");
+    expect(ran).toContain("net");
+    expect(ran).not.toContain("billing");
+    // No apply preceded its dependency.
+    expect(ran.indexOf("net")).toBeLessThan(ran.indexOf("cluster-a"));
+    expect(ran.indexOf("cluster-a")).toBeLessThan(ran.indexOf("app-one"));
+    expect(result.completed).toEqual(["app-one", "app-three", "app-two", "cluster-a", "cluster-b", "net"]);
+  });
+
+  test("a change to a leaf propagates to nothing", async () => {
+    const plan = planFanOut({ components: ESTATE, changed: ["app-three"] });
+    const { registry, ran } = registryWith();
+    await runFanOut(plan, ESTATE, registry, opts());
+    expect(ran).toEqual(["app-three"]);
+  });
+});
+
+describe("partial failure", () => {
+  test("a failure skips its own subtree and leaves independent branches alone", async () => {
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    const { registry, ran } = registryWith(["cluster-a"]);
+
+    const result = await runFanOut(plan, ESTATE, registry, opts());
+
+    expect(result.status).toBe("fail");
+    expect(result.failed).toEqual(["cluster-a"]);
+    // cluster-a's two apps never ran; cluster-b's branch finished.
+    expect(ran).not.toContain("app-one");
+    expect(ran).not.toContain("app-two");
+    expect(ran).toContain("app-three");
+    expect(result.completed).toContain("app-three");
+  });
+
+  test("a blocked component is reported as blocked, naming the failure to fix", async () => {
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    const { registry } = registryWith(["cluster-a"]);
+    const result = await runFanOut(plan, ESTATE, registry, opts());
+    expect(result.blocked).toEqual([
+      { component: "app-one", reason: "blocked", blockedBy: "cluster-a" },
+      { component: "app-two", reason: "blocked", blockedBy: "cluster-a" },
+    ]);
+  });
+});
+
+describe("resuming", () => {
+  test("a re-run finishes without redoing what already applied", async () => {
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    const first = await runFanOut(plan, ESTATE, registryWith(["cluster-a"]).registry, opts());
+    expect(first.status).toBe("fail");
+
+    // Whatever was wrong with cluster-a is fixed; run the same plan again.
+    const { registry, ran } = registryWith();
+    const second = await runFanOut(plan, ESTATE, registry, {
+      ...opts(),
+      progress: { completed: first.completed, failed: [] },
+    });
+
+    expect(second.status).toBe("ok");
+    // Only the four that had not applied, and no hand repair.
+    expect(ran.sort()).toEqual(["app-one", "app-two", "cluster-a"]);
+    expect(second.plan.skipped).toContainEqual({ component: "net", reason: "already-applied" });
+  });
+});
+
+describe("one approval over the whole set", () => {
+  const gate = { op: "fan-out", gate: "approve-fan-out" };
+
+  test("an unapproved gate stops before anything runs", async () => {
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    const { registry, ran } = registryWith();
+
+    const result = await runFanOut(plan, ESTATE, registry, { ...opts(), gate });
+
+    expect(result.status).toBe("gated");
+    expect(result.gate?.gate).toBe("approve-fan-out");
+    // Nothing is half-applied, so there is nothing to compensate for.
+    expect(ran).toEqual([]);
+  });
+
+  /** A ledger that already holds the pending fact from a first run, plus an approval of `digest`. */
+  const approvedPort = (digest: string | undefined) =>
+    memoryGateLedgerPort({
+      pending: [{
+        version: 1, kind: "pending", op: "fan-out", gate: "approve-fan-out",
+        timestamp: "2026-01-01T00:00:00.000Z", expiresAt: "2026-01-03T00:00:00.000Z",
+        ...(digest ? { planDigest: digest } : {}),
+      }],
+      resolutions: [{
+        version: 1, op: "fan-out", gate: "approve-fan-out",
+        resolvedBy: "alex", timestamp: "2026-01-01T00:01:00.000Z",
+        ...(digest ? { planDigest: digest } : {}),
+      }],
+    });
+
+  test("one approval covers every component in the set", async () => {
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    const { registry, ran } = registryWith();
+
+    const result = await runFanOut(plan, ESTATE, registry, {
+      env: "test", now: "2026-01-01T00:02:00Z", gates: approvedPort(plan.digest), gate,
+    });
+
+    // Six components, one approval.
+    expect(result.status).toBe("ok");
+    expect(ran).toHaveLength(6);
+  });
+
+  test("the approval is bound to the fan-out that was derived, not to the next run", async () => {
+    const approved = planFanOut({ components: ESTATE, changed: ["net"] });
+    // A different change derives a different fan-out. The standing approval
+    // named the other one, so this stops rather than riding on it.
+    const different = planFanOut({ components: ESTATE, changed: ["cluster-b"] });
+    expect(different.digest).not.toBe(approved.digest);
+
+    const { registry, ran } = registryWith();
+    const result = await runFanOut(different, ESTATE, registry, {
+      env: "test", now: "2026-01-01T00:02:00Z", gates: approvedPort(approved.digest), gate,
+    });
+
+    expect(result.status).toBe("gated");
+    expect(ran).toEqual([]);
+  });
+
+  test("an approval survives a resume, because the digest is carried not recomputed", async () => {
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    const { registry, ran } = registryWith();
+
+    // Half of it already applied in an earlier attempt. The gate must still
+    // pass on the same approval.
+    const result = await runFanOut(plan, ESTATE, registry, {
+      env: "test", now: "2026-01-01T00:02:00Z", gates: approvedPort(plan.digest), gate,
+      progress: { completed: ["net", "cluster-a"] },
+    });
+
+    expect(result.status).toBe("ok");
+    expect(ran.sort()).toEqual(["app-one", "app-three", "app-two", "cluster-b"]);
+  });
+});