@intentius/chant 0.124.27 → 0.124.28

package/src/components/driver.ts

@@ -56,7 +56,9 @@ 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";
+import type { RunProgressEvent } from "./run-progress";
+import type { RunEventSettleStatus } from "../run-event";
+import { gateEventsOf, joinRunEventSinks, progressSinkOf, type RunEventSink } from "../run-event-stream";
 
 export type { RunProgressEvent } from "./run-progress";
 
@@ -153,7 +155,16 @@ export interface DriverStepRecord {
   output?: unknown;
   error?: string;
   /** Set on a `gate` step that passed (#2119): who resolved it, when, and at what address. */
-  approval?: { gate: string; resolvedBy: string; timestamp: string; url?: string };
+  approval?: {
+    gate: string;
+    resolvedBy: string;
+    timestamp: string;
+    url?: string;
+    /** The gate ledger the approval is in, when it isn't the component's own: a release gate's (#4045). */
+    op?: string;
+    /** Set when the gate passed over an empty change set (#4045) rather than on a person's approval. */
+    empty?: true;
+  };
 }
 
 export interface DriverComponentResult {
@@ -378,8 +389,8 @@ class GateStop extends Error {
   }
 }
 
-/** A result status as the progress stream spells it — the only difference is `fail` vs `failed`, which the two vocabularies have always disagreed on. */
-function progressStatus(status: DriverComponentResult["status"]): RunProgressStatus {
+/** A result status as the event stream spells it — the only difference is `fail` vs `failed`, which the two vocabularies have always disagreed on. */
+function progressStatus(status: DriverComponentResult["status"]): RunEventSettleStatus {
   return status === "fail" ? "failed" : status;
 }
 
@@ -395,6 +406,27 @@ export interface GateContext {
   releases?: ReadonlyMap<string, string>;
   /** This component's plan digest. Set by {@link runComponentDeploy}, never by a caller. */
   planDigest?: string;
+  /**
+   * The release gate binding (#4045): set by a promote under a release.
+   * Every gate the run reaches is then decided in `op`'s ledger against the
+   * change-set document's digest, the release and the environment, in place
+   * of the component's own ledger and composition digest.
+   */
+  releaseGate?: ReleaseGateBinding;
+}
+
+/**
+ * What a release gate binds (#4045, ws-104 question 2): the change-set
+ * document's digest, the release, and (from the run) the environment.
+ */
+export interface ReleaseGateBinding {
+  /** The gate ledger the release gate is recorded in, for every component of the promote. */
+  op: string;
+  /** The digest of the change-set document planned for this release and environment. */
+  planDigest: string;
+  releaseDigest: string;
+  /** Reads the document stored under a digest and says whether it is empty (`evaluateGate`'s `verifyEmpty`). */
+  verifyEmpty?: (planDigest: string) => Promise<boolean>;
 }
 
 /** Run a single capability step. Never throws for a capability-run failure; returns a fail record instead. */
@@ -451,14 +483,16 @@ async function runCapabilityStep(
  * gate is a read of the ledger rather than work, and starting activities a
  * pending gate is about to strand defeats the point of stopping at it.
  *
- * `onProgress`, when supplied, is called with a `phase-start` event before any
- * step runs, a `step` event around each capability invocation (`"running"`
- * then `"ok"`/`"failed"`), and a `phase-done` event once the phase settles —
- * purely additive observation, never consulted for control flow. Recursion
- * into a nested fan-out phase passes the same callback through, so a nested
- * phase's events use its own name. Left `undefined` by every caller that
- * doesn't opt into `--progress-json` (see ./run-progress.ts), in which case
- * every `onProgress?.(...)` call below is a no-op and behavior is unchanged.
+ * `emit`, when supplied, gets the phase's run events (#4041): `phase-start`
+ * before any step runs, a `step-start` and a `step-settle` around each gate
+ * and each capability invocation, the gate's `gate-resolved` or
+ * `gate-waiting`, a `skipped` settle with `skip: "not-run"` for each step a
+ * failure or a gate stopped, and `phase-settle` once the phase settles. It
+ * is observation only, never consulted for control flow. Recursion into a
+ * nested fan-out phase passes the same sink through, so a nested phase's
+ * events use its own name. `--progress-json` reads the same events through
+ * `progressOfRunEvent` (../run-event-stream.ts), which keeps the older
+ * stream's shape.
  */
 async function runPhase(
   phaseDef: DriverPhase,
@@ -467,22 +501,34 @@ async function runPhase(
   phaseOutputs: Record<string, Record<string, unknown>>,
   componentOutputs: Record<string, Record<string, unknown>>,
   gates: GateContext,
-  onProgress?: (event: RunProgressEvent) => void,
+  emit?: RunEventSink,
 ): Promise<{ records: DriverStepRecord[]; executed: ExecutedStep[] }> {
+  /** Where a step of this phase sits, for its events. */
+  const stepAt = (entry: DriverStep | DriverGate | DriverPhase, step: string) => ({
+    component: ctx.component,
+    phase: phaseDef.phase,
+    step,
+    index: phaseDef.steps.indexOf(entry),
+  });
   /** Decide this phase's gates against the ledger, in authored order, before any of its work starts. Throws `GateStop` at the first one nobody has approved. */
   const decideGates = async (): Promise<DriverStepRecord[]> => {
     const gateRecords: DriverStepRecord[] = [];
     for (const gate of phaseDef.steps.filter(isGateStep)) {
       const start = Date.now();
       const base = { component: ctx.component, phase: phaseDef.phase, kind: `gate:${gateName(gate)}` };
+      const at = stepAt(gate, base.kind);
+      emit?.({ type: "step-start", ...at });
       let check: Awaited<ReturnType<typeof evaluateGate>>;
       try {
         check = await evaluateGate(gates.port, {
-          op: ctx.component,
+          op: gates.releaseGate?.op ?? ctx.component,
           gate: gateName(gate),
           // #2574: an approval counts only for this environment and this plan.
           environment: ctx.env,
           ...(gates.planDigest !== undefined ? { planDigest: gates.planDigest } : {}),
+          // #4045: and under a release, only for that release.
+          ...(gates.releaseGate ? { releaseDigest: gates.releaseGate.releaseDigest } : {}),
+          ...(gates.releaseGate?.verifyEmpty ? { verifyEmpty: gates.releaseGate.verifyEmpty } : {}),
           ...(gate.description ? { description: gate.description } : {}),
           ...(gate.timeout ? { timeout: gate.timeout } : {}),
           ...(gates.now ? { now: gates.now } : {}),
@@ -492,11 +538,22 @@ async function runPhase(
         // executor's gate step does, and the component unwinds like any failure.
         if (!(err instanceof GateNotRecordableError)) throw err;
         gateRecords.push({ ...base, status: "fail" as const, durationMs: Date.now() - start, error: err.message });
+        emit?.({ type: "step-settle", ...at, status: "failed", durationMs: Date.now() - start, error: err.message });
         for (const skipped of phaseDef.steps.filter((s): s is DriverStep | DriverPhase => !isGateStep(s))) {
           gateRecords.push(skippedRecord(skipped));
         }
         throw new StepFailure(gateRecords, []);
       }
+      for (const body of gateEventsOf(
+        check,
+        { ...at, op: gates.releaseGate?.op ?? ctx.component, gate: gateName(gate) },
+        {
+          durationMs: Date.now() - start,
+          ...(!check.satisfied && check.mismatch ? { message: "an approval stands for this gate, but for another environment or plan" } : {}),
+        },
+      )) {
+        emit?.(body);
+      }
       if (!check.satisfied) {
         gateRecords.push({ ...base, status: "skipped" as const, durationMs: Date.now() - start });
         for (const skipped of phaseDef.steps.filter((s): s is DriverStep | DriverPhase => !isGateStep(s))) {
@@ -513,6 +570,8 @@ async function runPhase(
           resolvedBy: check.resolution.resolvedBy,
           timestamp: check.resolution.timestamp,
           ...(check.resolution.url ? { url: check.resolution.url } : {}),
+          ...(gates.releaseGate ? { op: gates.releaseGate.op } : {}),
+          ...(check.via === "empty" ? { empty: true as const } : {}),
         },
       });
     }
@@ -534,7 +593,7 @@ async function runPhase(
   }> => {
     if (isPhaseStep(entry)) {
       try {
-        const nested = await runPhase(entry, ctx, registry, phaseOutputs, componentOutputs, gates, onProgress);
+        const nested = await runPhase(entry, ctx, registry, phaseOutputs, componentOutputs, gates, emit);
         return { ...nested, failed: false };
       } catch (err) {
         if (err instanceof StepFailure) return { records: err.records, executed: err.executed, failed: true };
@@ -554,7 +613,8 @@ async function runPhase(
         throw err;
       }
     }
-    onProgress?.({ type: "step", component: ctx.component, phase: phaseDef.phase, step: entry.kind, status: "running" });
+    const at = stepAt(entry, entry.kind);
+    emit?.({ type: "step-start", ...at });
     const { record, resolvedInput, output } = await runCapabilityStep(
       entry,
       phaseDef.phase,
@@ -563,12 +623,11 @@ async function runPhase(
       phaseOutputs,
       componentOutputs,
     );
-    onProgress?.({
-      type: "step",
-      component: ctx.component,
-      phase: phaseDef.phase,
-      step: entry.kind,
+    emit?.({
+      type: "step-settle",
+      ...at,
       status: record.status === "ok" ? "ok" : "failed",
+      durationMs: record.durationMs,
       ...(record.error !== undefined ? { error: record.error } : {}),
     });
     if (record.status === "ok") {
@@ -586,13 +645,12 @@ async function runPhase(
     };
   };
 
-  const skippedRecord = (entry: DriverStep | DriverPhase): DriverStepRecord => ({
-    component: ctx.component,
-    phase: phaseDef.phase,
-    kind: isPhaseStep(entry) ? entry.phase : (entry as DriverStep).kind,
-    status: "skipped",
-    durationMs: 0,
-  });
+  /** A step a failure or a gate stopped before it started: recorded, and settled `skipped` with `skip: "not-run"`. */
+  const skippedRecord = (entry: DriverStep | DriverPhase): DriverStepRecord => {
+    const kind = isPhaseStep(entry) ? entry.phase : (entry as DriverStep).kind;
+    emit?.({ type: "step-settle", ...stepAt(entry, kind), status: "skipped", skip: "not-run", durationMs: null });
+    return { component: ctx.component, phase: phaseDef.phase, kind, status: "skipped", durationMs: 0 };
+  };
 
   const runEntries = async (): Promise<{ records: DriverStepRecord[]; executed: ExecutedStep[] }> => {
     const gateRecords = await decideGates();
@@ -626,16 +684,16 @@ async function runPhase(
     return { records, executed };
   };
 
-  onProgress?.({ type: "phase-start", component: ctx.component, phase: phaseDef.phase });
+  emit?.({ type: "phase-start", component: ctx.component, phase: phaseDef.phase });
   try {
     const result = await runEntries();
-    onProgress?.({ type: "phase-done", component: ctx.component, phase: phaseDef.phase, status: "ok" });
+    emit?.({ type: "phase-settle", component: ctx.component, phase: phaseDef.phase, status: "ok" });
     return result;
   } catch (err) {
     if (err instanceof GateStop) {
-      onProgress?.({ type: "phase-done", component: ctx.component, phase: phaseDef.phase, status: "gated" });
+      emit?.({ type: "phase-settle", component: ctx.component, phase: phaseDef.phase, status: "gated" });
     } else if (err instanceof StepFailure) {
-      onProgress?.({ type: "phase-done", component: ctx.component, phase: phaseDef.phase, status: "failed" });
+      emit?.({ type: "phase-settle", component: ctx.component, phase: phaseDef.phase, status: "failed" });
     }
     throw err;
   }
@@ -710,14 +768,14 @@ async function rollbackExecuted(
  * any) are recorded into `componentOutputs` under its own name so downstream
  * components can reference `@<name>.publish.*`.
  *
- * `onProgress`, when supplied, is forwarded to every `runPhase` call (both the
- * forward `deploy` phases and, on failure, the component's own authored
- * `rollback` phases) so a `--progress-json` consumer sees `phase-start`/
- * `step`/`phase-done` events for whichever phases actually ran. The saga
- * unwind step-by-step compensation (`rollbackExecuted` below) is not part of
- * the `RunProgressEvent` contract and stays silent — it isn't a `deploy`
- * phase, and its record statuses (`rolled-back`/`rollback-opted-out`) don't
- * map onto the `step` event's `running`/`ok`/`failed` shape.
+ * `onProgress` (the older `RunProgressEvent` stream) and `onRunEvent` (run
+ * events, #4041), when supplied, are forwarded to every `runPhase` call (both
+ * the forward `deploy` phases and, on failure, the component's own authored
+ * `rollback` phases), so a consumer sees the phase and step events of
+ * whichever phases actually ran. The saga unwind step-by-step compensation
+ * (`rollbackExecuted` below) stays silent: it isn't a `deploy` phase, and
+ * its record statuses (`rolled-back`/`rollback-opted-out`) are not step
+ * statuses either stream has.
  */
 export async function runComponentDeploy(
   component: DriverComponent,
@@ -726,7 +784,9 @@ export async function runComponentDeploy(
   componentOutputs: Record<string, Record<string, unknown>>,
   onProgress?: (event: RunProgressEvent) => void,
   gateContext: GateContext = { port: gitGateLedgerPort() },
+  onRunEvent?: RunEventSink,
 ): Promise<DriverComponentResult> {
+  const emit = joinRunEventSinks(onRunEvent, progressSinkOf(onProgress));
   // 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>> = {};
@@ -738,19 +798,22 @@ export async function runComponentDeploy(
   if (ctx.release && release !== undefined && ctx.release.version === undefined) ctx.release.version = release;
   const gates: GateContext = {
     ...gateContext,
-    planDigest: componentPlanDigest({
-      environment: ctx.env,
-      component,
-      ...(ctx.vars ? { vars: ctx.vars } : {}),
-      ...(release !== undefined ? { release } : {}),
-    }),
+    // #4045: a release gate binds the release's change set, not this composition.
+    planDigest:
+      gateContext.releaseGate?.planDigest ??
+      componentPlanDigest({
+        environment: ctx.env,
+        component,
+        ...(ctx.vars ? { vars: ctx.vars } : {}),
+        ...(release !== undefined ? { release } : {}),
+      }),
   };
   const records: DriverStepRecord[] = [];
   const allExecuted: ExecutedStep[] = [];
 
   try {
     for (const phaseDef of component.deploy) {
-      const result = await runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs, gates, onProgress);
+      const result = await runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs, gates, emit);
       records.push(...result.records);
       allExecuted.push(...result.executed);
     }
@@ -784,7 +847,7 @@ export async function runComponentDeploy(
 
     for (const phaseDef of [...(component.rollback ?? [])].reverse()) {
       try {
-        const result = await runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs, gates, onProgress);
+        const result = await runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs, gates, emit);
         records.push(...result.records);
       } catch (compErr) {
         if (compErr instanceof StepFailure || compErr instanceof GateStop) records.push(...compErr.records);
@@ -919,12 +982,20 @@ export interface InterpretRunOptions {
    * byte-for-byte the same as before this option existed.
    */
   onProgress?: (event: RunProgressEvent) => void;
+  /**
+   * Where the run's events go (#4041, `chant run --components --events-json`):
+   * the run-event bodies the stream in ../run-event-stream.ts stamps. Like
+   * `onProgress`, never consulted for control flow.
+   */
+  onRunEvent?: RunEventSink;
   /** Where a `gate` step's facts are read and written (#2119). Defaults to the `chant/lifecycle` orphan branch; a test passes `memoryGateLedgerPort()` from `../op/gate.ts`. */
   gates?: GateLedgerPort;
   /** ISO-8601 "now" for gate decisions, so a test is deterministic. */
   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>;
+  /** A promote under a release (#4045): what every gate the run reaches binds. See {@link GateContext.releaseGate}. */
+  releaseGate?: ReleaseGateBinding;
   /**
    * The release each component deploys (#3061, ws-081), threaded into its
    * `DeployContext.release`. The driver fills in `version` when a publish
@@ -969,14 +1040,15 @@ export async function runInterpretDriver(
   const { order, waves } = resolveComponentGraph(components);
   const byName = new Map(components.map((c) => [c.name, c]));
   const componentOutputs: Record<string, Record<string, unknown>> = { ...(options.componentOutputs ?? {}) };
-  const { onProgress } = options;
+  const emit = joinRunEventSinks(options.onRunEvent, progressSinkOf(options.onProgress));
   const gates: GateContext = {
     port: options.gates ?? gitGateLedgerPort(),
     ...(options.now ? { now: options.now } : {}),
     ...(options.releases ? { releases: options.releases } : {}),
+    ...(options.releaseGate ? { releaseGate: options.releaseGate } : {}),
   };
 
-  onProgress?.({ type: "run-start", waves });
+  emit?.({ type: "run-start", waves });
 
   const results: DriverComponentResult[] = [];
   let failedComponent: string | undefined;
@@ -984,26 +1056,27 @@ export async function runInterpretDriver(
 
   waveLoop: for (const [waveIndex, wave] of waves.entries()) {
     const waveNum = waveIndex + 1;
-    onProgress?.({ type: "wave-start", wave: waveNum, components: wave });
+    emit?.({ type: "wave-start", wave: waveNum, components: wave });
     const waveComponents = wave.map((name) => byName.get(name)!);
     const waveResults = await Promise.all(
       waveComponents.map(async (component) => {
-        onProgress?.({ type: "component-start", wave: waveNum, component: component.name });
+        emit?.({ type: "component-start", wave: waveNum, component: component.name });
         const result = await runComponentDeploy(
           component,
           deployContext(options, component.name),
           registry,
           componentOutputs,
-          onProgress,
+          undefined,
           gates,
+          emit,
         );
-        onProgress?.({ type: "component-done", wave: waveNum, component: component.name, status: progressStatus(result.status) });
+        emit?.({ type: "component-settle", wave: waveNum, component: component.name, status: progressStatus(result.status) });
         return result;
       }),
     );
     results.push(...waveResults);
     const stopped = waveResults.find((r) => r.status !== "ok");
-    onProgress?.({ type: "wave-done", wave: waveNum, status: progressStatus(stopped?.status ?? "ok") });
+    emit?.({ type: "wave-settle", wave: waveNum, status: progressStatus(stopped?.status ?? "ok") });
     if (stopped) {
       // A failure in the same wave outranks a gate: something is actually
       // broken, and reporting the run as "waiting on a human" would hide it.
@@ -1016,7 +1089,7 @@ export async function runInterpretDriver(
 
   const status: DriverRunResult["status"] = failedComponent ? "fail" : gated ? "gated" : "ok";
   const ok = status === "ok";
-  onProgress?.({ type: "run-done", status: progressStatus(status) });
+  emit?.({ type: "run-settle", status: progressStatus(status), durationMs: null });
   const result: DriverRunResult = {
     order, waves, results, ok, status, failedComponent, componentOutputs,
     ...(gated

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

@@ -49,12 +49,18 @@ import type { ReleaseIdentity } from "../telemetry-attribution";
 import { downstreamWithin, remainingFanOut, type FanOutPlan, type FanOutProgress, type FanOutSkip } from "./fan-out";
 import { evaluateGate, gitGateLedgerPort, type GateCheck, type GateLedgerPort } from "../op/gate";
 import type { RunProgressEvent } from "./run-progress";
+import { emitGateStep, joinRunEventSinks, progressSinkOf, type RunEventSink } from "../run-event-stream";
 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 { decideWaveGate, runWaveLoop, waveGateName, waveSetDigest, type WaveMember, type WaveRecord } from "../wave-engine";
 
+/** The sink a fan-out emits to: run events, and the older stream through them. */
+function fanOutSink(options: FanOutRunOptions): RunEventSink | undefined {
+  return joinRunEventSinks(options.onRunEvent, progressSinkOf(options.onProgress));
+}
+
 /**
  * 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
@@ -115,6 +121,12 @@ export interface FanOutRunOptions {
   /** Outputs of components this run is not running: the ones the plan lists in `seeds`. */
   componentOutputs?: Record<string, Record<string, unknown>>;
   onProgress?: (event: RunProgressEvent) => void;
+  /**
+   * Where the run's events go (#4041, `--events-json`). A gate over the set
+   * or over a wave is a `gate:<name>` step of a `gate` phase with no
+   * component, settled before the components it lets through start.
+   */
+  onRunEvent?: RunEventSink;
   gates?: GateLedgerPort;
   now?: string;
   /** One approval over the ordered set, bound to `plan.digest`. */
@@ -206,18 +218,25 @@ export async function runFanOut(
     return runGatedWaves(plan, active, components, registry, options, options.waveGate, gates, componentOutputs);
   }
 
+  const emit = fanOutSink(options);
+  emit?.({ type: "run-start", waves: active.waves });
+
   if (options.gate) {
-    const check = await evaluateGate(gates.port, {
-      op: options.gate.op,
-      gate: options.gate.gate,
-      planDigest: active.digest,
-      ...(options.gate.description ? { description: options.gate.description } : {}),
-      ...(options.gate.timeout ? { timeout: options.gate.timeout } : {}),
-      ...(options.now ? { now: options.now } : {}),
-    });
+    const gate = options.gate;
+    const check = await emitGateStep(emit, gate, () =>
+      evaluateGate(gates.port, {
+        op: gate.op,
+        gate: gate.gate,
+        planDigest: active.digest,
+        ...(gate.description ? { description: gate.description } : {}),
+        ...(gate.timeout ? { timeout: gate.timeout } : {}),
+        ...(options.now ? { now: options.now } : {}),
+      }),
+    );
     if (!check.satisfied) {
       // Nothing ran, so nothing is half-applied and there is nothing to
       // compensate. A gate is a fact, not a failure.
+      emit?.({ type: "run-settle", status: "gated", durationMs: null });
       return {
         plan: active,
         status: "gated",
@@ -246,29 +265,28 @@ export async function runFanOut(
     }
   };
 
-  options.onProgress?.({ type: "run-start", waves: active.waves });
-
   for (const [waveIndex, wave] of active.waves.entries()) {
     const waveNum = waveIndex + 1;
     // A component whose upstream failed in an earlier wave is not dispatched.
     const runnable = wave.filter((name) => inPlan.has(name) && !blockedBy.has(name));
     if (runnable.length === 0) continue;
 
-    options.onProgress?.({ type: "wave-start", wave: waveNum, components: runnable });
+    emit?.({ type: "wave-start", wave: waveNum, components: runnable });
     const waveResults = await Promise.all(
       runnable.map(async (name) => {
-        options.onProgress?.({ type: "component-start", wave: waveNum, component: name });
+        emit?.({ type: "component-start", wave: waveNum, component: name });
         const planned = options.plans?.[name];
         const result = await runComponentDeploy(
           byName.get(name)!,
           { ...fanOutContext(options, name), ...(planned && Object.keys(planned).length > 0 ? { plans: planned } : {}) },
           registry,
           componentOutputs,
-          options.onProgress,
+          undefined,
           gates,
+          emit,
         );
-        options.onProgress?.({
-          type: "component-done",
+        emit?.({
+          type: "component-settle",
           wave: waveNum,
           component: name,
           status: result.status === "fail" ? "failed" : result.status,
@@ -297,8 +315,8 @@ export async function runFanOut(
     }
 
     const waveFailed = waveResults.some((r) => r.status === "fail");
-    options.onProgress?.({
-      type: "wave-done",
+    emit?.({
+      type: "wave-settle",
       wave: waveNum,
       status: waveFailed ? "failed" : waveResults.some((r) => r.status === "gated") ? "gated" : "ok",
     });
@@ -311,7 +329,7 @@ export async function runFanOut(
   // A failure outranks a gate: something is actually broken, and reporting the
   // run as "waiting on a human" would hide it. Same precedence the driver uses.
   const status: FanOutRunResult["status"] = failed.length > 0 ? "fail" : gatedFact ? "gated" : "ok";
-  options.onProgress?.({ type: "run-done", status: status === "fail" ? "failed" : status });
+  emit?.({ type: "run-settle", status: status === "fail" ? "failed" : status, durationMs: null });
 
   return {
     plan: active,
@@ -391,7 +409,8 @@ async function runGatedWaves(
     }
   };
 
-  options.onProgress?.({ type: "run-start", waves: plan.waves });
+  const emit = fanOutSink(options);
+  emit?.({ type: "run-start", waves: plan.waves });
 
   /** What planning one wave gave. */
   interface Planned {
@@ -477,14 +496,16 @@ async function runGatedWaves(
         return { end: "next" };
       }
 
-      const check = await decideWaveGate(gates.port, {
-        op: waveGate.op,
-        gate: gateName,
-        digest,
-        description: waveGate.description ?? `wave ${waveNum} of ${plan.waves.length}: ${toRun.join(", ")}`,
-        ...(waveGate.timeout ? { timeout: waveGate.timeout } : {}),
-        ...(options.now ? { now: options.now } : {}),
-      });
+      const check = await emitGateStep(emit, { op: waveGate.op, gate: gateName }, () =>
+        decideWaveGate(gates.port, {
+          op: waveGate.op,
+          gate: gateName,
+          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.
@@ -502,15 +523,15 @@ async function runGatedWaves(
     },
 
     async apply({ k: waveNum }, { contexts, plansFor, waveFailures }, { check, record, toRun }) {
-      options.onProgress?.({ type: "wave-start", wave: waveNum, components: toRun });
+      emit?.({ 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 });
+          emit?.({ 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",
+          const result = await runComponentDeploy(byName.get(name)!, ctx, registry, componentOutputs, undefined, gates, emit);
+          emit?.({
+            type: "component-settle",
             wave: waveNum,
             component: name,
             status: result.status === "fail" ? "failed" : result.status,
@@ -543,8 +564,8 @@ async function runGatedWaves(
       };
       waves.push(settled);
       options.onWaveSettled?.(settled);
-      options.onProgress?.({
-        type: "wave-done",
+      emit?.({
+        type: "wave-settle",
         wave: waveNum,
         status: waveFailures.length > 0 ? "failed" : waveResults.some((r) => r.status === "gated") ? "gated" : "ok",
       });
@@ -557,7 +578,7 @@ async function runGatedWaves(
     .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 });
+  emit?.({ type: "run-settle", status: status === "fail" ? "failed" : status, durationMs: null });
 
   return {
     // The derivation's waves, not the narrowed re-layering: their numbers name the gates.