@intentius/chant 0.102.0 → 0.104.0

package/src/components/driver.ts

@@ -47,11 +47,14 @@
  */
 
 import { topoSort } from "../codegen/topo-sort";
+import { kahnLayers } from "./layers";
 import { evaluateGate, gitGateLedgerPort, type GateDigestMismatch, type GateLedgerPort } from "../op/gate";
 import { gateName } from "../op/gate-name";
 import { componentPlanDigest } from "./gate-plan";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import type { CapabilityRegistry, DeployContext } from "./capability";
+import { isPromotedArtifact } from "./auto-release";
+import type { ReleaseIdentity } from "../telemetry-attribution";
 import type { RunProgressEvent, RunProgressStatus } from "./run-progress";
 
 export type { RunProgressEvent } from "./run-progress";
@@ -237,18 +240,9 @@ export function resolveComponentGraph(components: DriverComponent[]): ComponentG
   const deps = new Map<string, Set<string>>();
   for (const c of components) deps.set(c.name, new Set(c.dependsOn ?? []));
 
-  const remaining = new Set(deps.keys());
-  const waves: string[][] = [];
-  while (remaining.size > 0) {
-    const wave = [...remaining]
-      .filter((n) => [...deps.get(n)!].every((d) => !remaining.has(d)))
-      .sort();
-    if (wave.length === 0) {
-      throw new DependencyCycleError([...remaining].sort());
-    }
-    for (const n of wave) remaining.delete(n);
-    waves.push(wave);
-  }
+  const layered = kahnLayers(deps);
+  if (layered.cycle) throw new DependencyCycleError(layered.cycle);
+  const waves = layered.waves;
 
   const order = topoSort(
     components,
@@ -566,6 +560,11 @@ async function runPhase(
     });
     if (record.status === "ok") {
       phaseOutputs[phaseDef.phase] = { ...(phaseOutputs[phaseDef.phase] ?? {}), ...(output as object) };
+      // The release's service.version is the digest a later deploy step stamps (#3061): the
+      // last artifact this component promoted, the same one auto-release records.
+      if (ctx.release && isPromotedArtifact(output) && typeof output.digest === "string" && output.digest !== "") {
+        ctx.release.version = output.digest;
+      }
     }
     return {
       records: [record],
@@ -715,11 +714,15 @@ export async function runComponentDeploy(
   onProgress?: (event: RunProgressEvent) => void,
   gateContext: GateContext = { port: gitGateLedgerPort() },
 ): Promise<DriverComponentResult> {
+  // Each component tracks its own release: a digest one component promoted never stamps another's deploy.
+  if (ctx.release) ctx = { ...ctx, release: { ...ctx.release } };
   const phaseOutputs: Record<string, Record<string, unknown>> = {};
   // #2574: every gate this component reaches binds its approval to this
   // environment and this composition, so an approval for staging or for last
   // week's deploy cannot pass it.
   const release = gateContext.releases?.get(component.name);
+  // A promote or rollback deploys a recorded digest without publishing one (#2574); that digest is the release's version.
+  if (ctx.release && release !== undefined && ctx.release.version === undefined) ctx.release.version = release;
   const gates: GateContext = {
     ...gateContext,
     planDigest: componentPlanDigest({
@@ -909,6 +912,12 @@ export interface InterpretRunOptions {
   now?: string;
   /** The recorded digest a promote or rollback deploys, per component (#2574). Part of the plan a gate approval is bound to. */
   releases?: ReadonlyMap<string, string>;
+  /**
+   * The release each component deploys (#3061, ws-081), threaded into its
+   * `DeployContext.release`. The driver fills in `version` when a publish
+   * step promotes an artifact. Absent: no deploy step sees a release.
+   */
+  releaseIdentity?: (component: string) => ReleaseIdentity | undefined;
 }
 
 /**
@@ -930,6 +939,15 @@ export interface InterpretRunOptions {
  * purely on the generic `Component`/`Phase`/`Step` shapes and the registry —
  * no branch anywhere names a specific component or capability.
  */
+/** A component's `DeployContext` for a run: its env, vars and, when the caller knows it, its release. */
+export function deployContext(
+  options: { env: string; vars?: Record<string, unknown>; releaseIdentity?: (component: string) => ReleaseIdentity | undefined },
+  component: string,
+): DeployContext {
+  const release = options.releaseIdentity?.(component);
+  return { env: options.env, component, ...(options.vars ? { vars: options.vars } : {}), ...(release ? { release: { ...release } } : {}) };
+}
+
 export async function runInterpretDriver(
   components: DriverComponent[],
   registry: CapabilityRegistry,
@@ -960,7 +978,7 @@ export async function runInterpretDriver(
         onProgress?.({ type: "component-start", wave: waveNum, component: component.name });
         const result = await runComponentDeploy(
           component,
-          { env: options.env, component: component.name, vars: options.vars },
+          deployContext(options, component.name),
           registry,
           componentOutputs,
           onProgress,

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

@@ -31,6 +31,7 @@
 
 import type { FanOutPlan, FanOutSkip } from "./fan-out";
 import type { FanOutRunResult } from "./fan-out-run";
+import { waveGateName, type WaveRecord } from "../gated-waves";
 
 type Writer = (line: string) => void;
 
@@ -47,6 +48,12 @@ export interface FanOutRenderOptions {
   write?: Writer;
   /** Present when a gate covers the set, so the render can print the exact approve line. */
   gate?: FanOutGateRef;
+  /**
+   * Present when each wave has its own gate (#3049). A wave's digest is known
+   * only once it is planned, so a plan-only render names each wave's gate and
+   * no digest.
+   */
+  waveGate?: FanOutGateRef;
 }
 
 /** `unaffected` → `unaffected`; `blocked` also names the failure it was reached from. */
@@ -85,7 +92,8 @@ export function renderFanOutPlan(plan: FanOutPlan, options: FanOutRenderOptions
     write("  nothing to run");
   } else {
     for (const [index, wave] of plan.waves.entries()) {
-      write(`  wave ${index + 1}: ${wave.join(", ")}`);
+      const gated = options.waveGate ? `  (gate ${waveGateName(options.waveGate.gate, index + 1)})` : "";
+      write(`  wave ${index + 1}: ${wave.join(", ")}${gated}`);
     }
   }
 
@@ -117,6 +125,28 @@ export function renderFanOutPlan(plan: FanOutPlan, options: FanOutRenderOptions
   if (options.gate) {
     write(`  approve: chant approve ${options.gate.op} ${options.gate.gate} --plan ${plan.digest}`);
   }
+  if (options.waveGate) {
+    write(`  each wave is planned when it is reached, and its gate binds that wave's set digest`);
+  }
+}
+
+/** One line per wave a gated-wave run reached (#3049): its digest, members and where it got to. */
+function renderWaves(waves: readonly WaveRecord[], write: Writer): void {
+  for (const wave of waves) {
+    const state =
+      wave.status === "applied"
+        ? `applied, approved by ${wave.approvedBy ?? "unknown"}`
+        : wave.status === "gated"
+          ? wave.approved
+            ? "stopped: the set changed after it was approved"
+            : "waiting for approval"
+          : "failed";
+    write(`wave ${wave.wave} (${wave.gate}): ${state}`);
+    if (wave.digest) write(`  set digest: ${wave.digest}`);
+    for (const member of wave.members) write(`    ${member.member}  ${member.planDigest}`);
+    if (wave.approved) write(`  approved digest: ${wave.approved}`);
+    for (const f of wave.failed ?? []) write(`  ${f.component} failed${f.error ? `: ${f.error}` : ""}`);
+  }
 }
 
 /**
@@ -130,6 +160,17 @@ export function renderFanOutPlan(plan: FanOutPlan, options: FanOutRenderOptions
 export function renderFanOutHuman(result: FanOutRunResult, options: FanOutRenderOptions = {}): void {
   const write = options.write ?? stderr;
   renderFanOutPlan(result.plan, { ...options, write });
+  if (result.waves) renderWaves(result.waves, write);
+
+  if (result.status === "gated" && result.waves) {
+    const at = result.waves[result.waves.length - 1];
+    write(
+      `gated at wave ${at?.wave ?? "?"}: ${result.completed.length} applied before it, ` +
+        `nothing in it or after it ran.`,
+    );
+    if (result.gate?.expiresAt) write(`  expires: ${result.gate.expiresAt}`);
+    return;
+  }
 
   if (result.status === "gated") {
     const gate = result.gate;

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

@@ -0,0 +1,69 @@
+/**
+ * The fan-out attempt record (`--resume`, #2420, #2417, #3049): what an
+ * attempt left behind and what the next one reads.
+ *
+ * It lives here rather than in the CLI handler so a caller that runs a wave
+ * per CI job (#3183) reads and writes the same file without importing the
+ * command.
+ *
+ * The digest is stored alongside the progress because progress is only
+ * meaningful for the plan it was made against. A fan-out derived from different
+ * source is a different fan-out, and carrying "cluster-a already applied" into
+ * it would be a claim about work nobody did.
+ *
+ * `outputs` holds what each completed component exposed. A component left to
+ * run may read one of them through `stackOutput()`, and without the record the
+ * re-run would resolve that reference to nothing unless somebody supplied the
+ * value by hand with `--seed-outputs`.
+ *
+ * `waves`, for a gated-wave fan-out, holds one entry per wave reached: its set
+ * digest, its members, its gate and where it got to. A resumed attempt plans
+ * a wave afresh rather than trusting this, since the point of the gate is the
+ * plan now. The entries are for whoever reads the record, the plan report
+ * (#3349) among them.
+ */
+
+import { dirname } from "node:path";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { readWaveRecords, type WaveRecord } from "../gated-waves";
+
+export interface FanOutAttempt {
+  digest: string;
+  completed: string[];
+  failed: string[];
+  outputs: Record<string, Record<string, unknown>>;
+  /** Gated-wave fan-outs only (#3049). */
+  waves?: WaveRecord[];
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** Read an attempt record, or `undefined` when there is none yet. Throws on a file that is not JSON. */
+export function readFanOutAttempt(path: string): FanOutAttempt | undefined {
+  if (!existsSync(path)) return undefined;
+  const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<FanOutAttempt>;
+  const outputs: Record<string, Record<string, unknown>> = {};
+  if (isRecord(parsed.outputs)) {
+    for (const [name, value] of Object.entries(parsed.outputs)) if (isRecord(value)) outputs[name] = value;
+  }
+  const waves = readWaveRecords(parsed.waves);
+  return {
+    digest: typeof parsed.digest === "string" ? parsed.digest : "",
+    completed: Array.isArray(parsed.completed) ? parsed.completed.filter((n): n is string => typeof n === "string") : [],
+    failed: Array.isArray(parsed.failed) ? parsed.failed.filter((n): n is string => typeof n === "string") : [],
+    outputs,
+    ...(waves.length > 0 ? { waves } : {}),
+  };
+}
+
+/**
+ * Written through a temporary file and a rename, so a process killed during the
+ * write leaves the previous record whole rather than half a JSON document.
+ */
+export function writeFanOutAttempt(path: string, attempt: FanOutAttempt): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, JSON.stringify(attempt, null, 2) + "\n");
+  renameSync(temporary, path);
+}

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

@@ -116,6 +116,23 @@ describe("resuming", () => {
     expect(ran.sort()).toEqual(["app-one", "app-two", "cluster-a"]);
     expect(second.plan.skipped).toContainEqual({ component: "net", reason: "already-applied" });
   });
+
+  test("each component is reported as it settles, so progress survives a run that never returns", async () => {
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    const settled: string[] = [];
+    const { registry, ran } = registryWith(["cluster-a"]);
+    const result = await runFanOut(plan, ESTATE, registry, {
+      ...opts(),
+      onComponentSettled: (r) => {
+        settled.push(`${r.component}:${r.status}`);
+        // Every report lands before any later wave starts.
+        if (r.component === "net") expect(ran).toEqual(["net"]);
+      },
+    });
+
+    expect(result.status).toBe("fail");
+    expect(settled.sort()).toEqual(["app-three:ok", "cluster-a:fail", "cluster-b:ok", "net:ok"]);
+  });
 });
 
 describe("one approval over the whole set", () => {

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

@@ -27,19 +27,75 @@
  * behind one fan-out is one approval, and re-deriving the same fan-out does not
  * expire it. A component's *own* authored gates still decide per component —
  * this adds a gate over the set, it does not remove the ones inside it.
+ *
+ * ## Or one approval per wave
+ *
+ * `waveGate` (#3049) is the other mode. Each wave is planned once the waves
+ * before it applied, and its gate binds that wave's set digest
+ * (`../gated-waves.ts`). See {@link runGatedWaves}.
  */
 
 import {
+  deployContext,
   runComponentDeploy,
   type DriverComponent,
   type DriverComponentResult,
   type GateContext,
 } from "./driver";
+import type { ReleaseIdentity } from "../telemetry-attribution";
 import { downstreamWithin, remainingFanOut, type FanOutPlan, type FanOutProgress, type FanOutSkip } from "./fan-out";
 import { evaluateGate, gitGateLedgerPort, type GateLedgerPort } from "../op/gate";
 import type { RunProgressEvent } from "./run-progress";
 import type { CapabilityRegistry } from "./capability";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
+import type { DeployContext } from "./capability";
+import { planWaveComponent, type WaveComponentPlan } from "./wave-plan";
+import { waveGateName, waveSetDigest, type WaveMember, type WaveRecord } from "../gated-waves";
+
+/**
+ * One gate per wave (#3049), each bound to its wave's set digest. The other
+ * mode beside {@link FanOutGate}: that one approves the whole set once, this
+ * one approves each wave after the waves before it applied.
+ */
+export interface FanOutWaveGate {
+  /** The op the gates are recorded under, `fan-out` from the CLI. */
+  op: string;
+  /** The base gate name. Wave `n` waits on `waveGateName(gate, n)`. */
+  gate: string;
+  description?: string;
+  timeout?: string;
+  /**
+   * Plan one wave's components. Called once per wave, after every earlier
+   * wave settled, with the outputs they left. Defaults to
+   * `planWaveComponent` over the run's registry.
+   */
+  planComponent?: (
+    component: DriverComponent,
+    ctx: DeployContext,
+    componentOutputs: Record<string, Record<string, unknown>>,
+  ) => Promise<WaveComponentPlan>;
+  /**
+   * Run this wave and no other: CI's one job per wave. An earlier wave with
+   * work left refuses the run, since this wave's plan would read outputs that
+   * do not exist yet. A later wave is left for its own job.
+   */
+  only?: number;
+}
+
+/** Thrown when `FanOutWaveGate.only` names a wave whose predecessors have not all applied. */
+export class EarlierWaveNotAppliedError extends Error {
+  constructor(
+    readonly wave: number,
+    readonly earlier: number,
+    readonly components: string[],
+  ) {
+    super(
+      `wave ${wave} cannot run yet: wave ${earlier} has not applied (${components.join(", ")}). ` +
+        `Run wave ${earlier} first, with the same --resume record.`,
+    );
+    this.name = "EarlierWaveNotAppliedError";
+  }
+}
 
 /** The single gate over a whole fan-out. Omit it to run without one. */
 export interface FanOutGate {
@@ -60,8 +116,29 @@ export interface FanOutRunOptions {
   now?: string;
   /** One approval over the ordered set, bound to `plan.digest`. */
   gate?: FanOutGate;
+  /** One approval per wave, each bound to its wave's set digest (#3049). Not with `gate`. */
+  waveGate?: FanOutWaveGate;
+  /**
+   * Plans made before the run, per component and then per member, handed to
+   * each component's steps as `DeployContext.plans` (#3183). A pull request's
+   * apply plans every member, decides its gate against the set, and passes
+   * the plans here so each step applies the plan that was approved. Not
+   * with `waveGate`, which plans each wave itself.
+   */
+  plans?: Record<string, Record<string, unknown>>;
+  /** Called as each wave settles or stops at its gate, so a record survives a kill. */
+  onWaveSettled?: (record: WaveRecord) => void;
   /** What an earlier attempt at this same plan already did. */
   progress?: FanOutProgress;
+  /** The release each component deploys (#3061), as `InterpretRunOptions.releaseIdentity`. */
+  releaseIdentity?: (component: string) => ReleaseIdentity | undefined;
+  /**
+   * Called as each component settles, with the outputs it exposed, before the
+   * rest of its wave finishes. A caller that records progress here keeps what
+   * already applied when the process is killed mid-fan-out, which waiting for
+   * the returned result cannot do.
+   */
+  onComponentSettled?: (result: DriverComponentResult, outputs: Record<string, unknown> | undefined) => void;
 }
 
 export interface FanOutRunResult {
@@ -78,6 +155,8 @@ export interface FanOutRunResult {
   componentOutputs: Record<string, Record<string, unknown>>;
   /** Present when `status === "gated"`: the pending fact to approve. */
   gate?: PendingGateRecord;
+  /** With `waveGate`: each wave this attempt planned, in order, the one it stopped at included. */
+  waves?: WaveRecord[];
 }
 
 /**
@@ -103,6 +182,16 @@ export async function runFanOut(
   // and a re-run does not re-approve. The digest is carried, not recomputed.
   const active = options.progress ? remainingFanOut(plan, components, options.progress) : plan;
 
+  if (options.gate && options.waveGate) {
+    throw new Error("a fan-out takes one gate over the set or one gate per wave, not both");
+  }
+  if (options.waveGate && options.plans) {
+    throw new Error("a gated-wave fan-out plans each wave itself, so it takes no plans made beforehand");
+  }
+  if (options.waveGate) {
+    return runGatedWaves(plan, active, components, registry, options, options.waveGate, gates, componentOutputs);
+  }
+
   if (options.gate) {
     const check = await evaluateGate(gates.port, {
       op: options.gate.op,
@@ -155,9 +244,10 @@ export async function runFanOut(
     const waveResults = await Promise.all(
       runnable.map(async (name) => {
         options.onProgress?.({ type: "component-start", wave: waveNum, component: name });
+        const planned = options.plans?.[name];
         const result = await runComponentDeploy(
           byName.get(name)!,
-          { env: options.env, component: name, vars: options.vars },
+          { ...deployContext(options, name), ...(planned && Object.keys(planned).length > 0 ? { plans: planned } : {}) },
           registry,
           componentOutputs,
           options.onProgress,
@@ -169,6 +259,7 @@ export async function runFanOut(
           component: name,
           status: result.status === "fail" ? "failed" : result.status,
         });
+        options.onComponentSettled?.(result, componentOutputs[name]);
         return result;
       }),
     );
@@ -219,3 +310,215 @@ export async function runFanOut(
     ...(gatedFact ? { gate: gatedFact } : {}),
   };
 }
+
+/** A plan failure as a component result, so it reads like any other failed component. */
+function planFailure(component: string, error: string): DriverComponentResult {
+  return {
+    component,
+    ok: false,
+    status: "fail",
+    records: [{ component, phase: "Plan", kind: "plan", status: "fail", durationMs: 0, error }],
+  };
+}
+
+/**
+ * The per-wave mode (#3049). Waves keep the numbers the derivation gave them,
+ * so on a resumed attempt wave 3 is still wave 3 and its gate, and the
+ * approval recorded for it, are the same ones.
+ *
+ * For each wave with work left: plan its components against the outputs
+ * earlier waves wrote, take the set digest of what was planned, and decide
+ * `waveGateName(gate, n)` against it. Approved, the wave runs, each
+ * component applying the plans its steps just made. Not approved, the run
+ * stops there with nothing in that wave or after it applied. An approval
+ * that stands for another digest (the set changed since someone approved
+ * it) is the same stop, and the record names both digests.
+ *
+ * A component that fails to plan or to apply blocks its own dependents and
+ * nothing else, as in the whole-set mode.
+ */
+async function runGatedWaves(
+  plan: FanOutPlan,
+  active: FanOutPlan,
+  components: DriverComponent[],
+  registry: CapabilityRegistry,
+  options: FanOutRunOptions,
+  waveGate: FanOutWaveGate,
+  gates: GateContext,
+  componentOutputs: Record<string, Record<string, unknown>>,
+): Promise<FanOutRunResult> {
+  const byName = new Map(components.map((c) => [c.name, c]));
+  const left = new Set(active.order);
+  const planComponent =
+    waveGate.planComponent ??
+    ((component: DriverComponent, ctx: DeployContext, outputs: Record<string, Record<string, unknown>>) =>
+      planWaveComponent(component, registry, ctx, outputs));
+
+  const results: DriverComponentResult[] = [];
+  const completed: string[] = [];
+  const failed: string[] = [];
+  const blockedBy = new Map<string, string>();
+  const waves: WaveRecord[] = [];
+  let gatedFact: PendingGateRecord | undefined;
+
+  const markBlocked = (root: string): void => {
+    for (const [component, by] of downstreamWithin(components, left, [root])) {
+      if (blockedBy.has(component) || failed.includes(component)) continue;
+      blockedBy.set(component, by);
+    }
+  };
+
+  options.onProgress?.({ type: "run-start", waves: plan.waves });
+
+  for (const [waveIndex, wave] of plan.waves.entries()) {
+    const waveNum = waveIndex + 1;
+    const runnable = wave.filter((name) => left.has(name) && !blockedBy.has(name));
+    if (waveGate.only !== undefined && waveNum < waveGate.only) {
+      if (runnable.length > 0) throw new EarlierWaveNotAppliedError(waveGate.only, waveNum, runnable);
+      continue;
+    }
+    if (waveGate.only !== undefined && waveNum > waveGate.only) break;
+    if (runnable.length === 0) continue;
+
+    const gateName = waveGateName(waveGate.gate, waveNum);
+    const contexts = new Map(runnable.map((name) => [name, deployContext(options, name)]));
+    const planned = await Promise.all(
+      runnable.map((name) => planComponent(byName.get(name)!, contexts.get(name)!, componentOutputs)),
+    );
+
+    const members: WaveMember[] = [];
+    const plansFor = new Map<string, Record<string, unknown>>();
+    const waveFailures: Array<{ component: string; error?: string }> = [];
+    for (const p of planned) {
+      if ("error" in p) {
+        waveFailures.push({ component: p.component, error: p.error });
+        continue;
+      }
+      members.push(...p.members);
+      plansFor.set(p.component, p.plans);
+    }
+
+    let digest: string;
+    try {
+      // A wave where nothing planned has no set, and so no digest.
+      digest = members.length > 0 ? waveSetDigest(members) : "";
+    } catch (err) {
+      // Two components planning the same root: there is no one plan for it.
+      const error = err instanceof Error ? err.message : String(err);
+      for (const name of plansFor.keys()) waveFailures.push({ component: name, error });
+      plansFor.clear();
+      digest = "";
+    }
+    for (const f of waveFailures) {
+      failed.push(f.component);
+      results.push(planFailure(f.component, f.error ?? "plan failed"));
+      markBlocked(f.component);
+    }
+
+    const toRun = runnable.filter((name) => plansFor.has(name));
+    const record: WaveRecord = {
+      wave: waveNum,
+      op: waveGate.op,
+      gate: gateName,
+      components: [...runnable].sort(),
+      digest,
+      members: [...members].sort((a, b) => a.member.localeCompare(b.member)),
+      status: "failed",
+      ...(waveFailures.length > 0 ? { failed: waveFailures } : {}),
+    };
+    if (toRun.length === 0) {
+      waves.push(record);
+      options.onWaveSettled?.(record);
+      continue;
+    }
+
+    const check = await evaluateGate(gates.port, {
+      op: waveGate.op,
+      gate: gateName,
+      planDigest: digest,
+      description: waveGate.description ?? `wave ${waveNum} of ${plan.waves.length}: ${toRun.join(", ")}`,
+      ...(waveGate.timeout ? { timeout: waveGate.timeout } : {}),
+      ...(options.now ? { now: options.now } : {}),
+    });
+    if (!check.satisfied) {
+      // Nothing in this wave ran, and no later wave is planned: its plan
+      // would read outputs this wave has not written.
+      const stopped: WaveRecord = {
+        ...record,
+        status: "gated",
+        ...(check.mismatch?.approved ? { approved: check.mismatch.approved } : {}),
+      };
+      waves.push(stopped);
+      options.onWaveSettled?.(stopped);
+      gatedFact = check.pending;
+      break;
+    }
+
+    options.onProgress?.({ type: "wave-start", wave: waveNum, components: toRun });
+    const waveResults = await Promise.all(
+      toRun.map(async (name) => {
+        options.onProgress?.({ type: "component-start", wave: waveNum, component: name });
+        const plans = plansFor.get(name)!;
+        const ctx = { ...contexts.get(name)!, ...(Object.keys(plans).length > 0 ? { plans } : {}) };
+        const result = await runComponentDeploy(byName.get(name)!, ctx, registry, componentOutputs, options.onProgress, gates);
+        options.onProgress?.({
+          type: "component-done",
+          wave: waveNum,
+          component: name,
+          status: result.status === "fail" ? "failed" : result.status,
+        });
+        options.onComponentSettled?.(result, componentOutputs[name]);
+        return result;
+      }),
+    );
+    results.push(...waveResults);
+
+    for (const result of waveResults) {
+      if (result.status === "ok") {
+        completed.push(result.component);
+        continue;
+      }
+      if (result.status === "fail") {
+        failed.push(result.component);
+        waveFailures.push({ component: result.component });
+      } else {
+        gatedFact ??= result.gate;
+      }
+      markBlocked(result.component);
+    }
+
+    const settled: WaveRecord = {
+      ...record,
+      status: waveFailures.length > 0 ? "failed" : "applied",
+      approvedBy: check.resolution.resolvedBy,
+      ...(waveFailures.length > 0 ? { failed: waveFailures } : {}),
+    };
+    waves.push(settled);
+    options.onWaveSettled?.(settled);
+    options.onProgress?.({
+      type: "wave-done",
+      wave: waveNum,
+      status: waveFailures.length > 0 ? "failed" : waveResults.some((r) => r.status === "gated") ? "gated" : "ok",
+    });
+  }
+
+  const blocked: FanOutSkip[] = [...blockedBy.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([component, by]) => ({ component, reason: "blocked" as const, blockedBy: by }));
+
+  const status: FanOutRunResult["status"] = failed.length > 0 ? "fail" : gatedFact ? "gated" : "ok";
+  options.onProgress?.({ type: "run-done", status: status === "fail" ? "failed" : status });
+
+  return {
+    // The derivation's waves, not the narrowed re-layering: their numbers name the gates.
+    plan: { ...active, waves: plan.waves },
+    status,
+    results,
+    completed: [...completed].sort(),
+    failed: [...failed].sort(),
+    blocked,
+    componentOutputs,
+    ...(gatedFact ? { gate: gatedFact } : {}),
+    waves,
+  };
+}

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

@@ -33,6 +33,8 @@ export interface DeriveFanOutOptions {
   buildParams?: BuildParamProvenance[];
   /** Already-loaded project config, when the caller read it for its own reasons. */
   config?: ChantConfig;
+  /** Components that form wave 1 (#3049). See `FanOutRequest.canary`. */
+  canary?: string[];
 }
 
 export interface DerivedFanOut {
@@ -80,6 +82,7 @@ export async function deriveFanOut(options: DeriveFanOutOptions): Promise<Derive
     components,
     changed: signal.changed,
     ...(signal.indeterminate.length > 0 ? { indeterminate: signal.indeterminate } : {}),
+    ...(options.canary?.length ? { canary: options.canary } : {}),
   });
 
   return { success: true, components, signal, plan };