@intentius/chant 0.124.27 → 0.124.28

package/dist/components/driver.js

@@ -52,6 +52,7 @@ import { gateName } from "../op/gate-name.js";
 import { GateNotRecordableError } from "../lifecycle/no-record.js";
 import { componentPlanDigest } from "./gate-plan.js";
 import { isPromotedArtifact } from "./auto-release.js";
+import { gateEventsOf, joinRunEventSinks, progressSinkOf } from "../run-event-stream.js";
 function isGateStep(step) {
     return step.kind === "gate";
 }
@@ -210,7 +211,7 @@ class GateStop extends Error {
         this.name = "GateStop";
     }
 }
-/** A result status as the progress stream spells it — the only difference is `fail` vs `failed`, which the two vocabularies have always disagreed on. */
+/** 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) {
     return status === "fail" ? "failed" : status;
 }
@@ -261,30 +262,44 @@ async function runCapabilityStep(step, phaseName, ctx, registry, phaseOutputs, c
  * 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, ctx, registry, phaseOutputs, componentOutputs, gates, onProgress) {
+async function runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs, gates, emit) {
+    /** Where a step of this phase sits, for its events. */
+    const stepAt = (entry, step) => ({
+        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 () => {
         const gateRecords = [];
         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;
             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 } : {}),
@@ -296,11 +311,18 @@ async function runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs,
                 if (!(err instanceof GateNotRecordableError))
                     throw err;
                 gateRecords.push({ ...base, status: "fail", 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) => !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", durationMs: Date.now() - start });
                 for (const skipped of phaseDef.steps.filter((s) => !isGateStep(s))) {
@@ -317,6 +339,8 @@ async function runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs,
                     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 } : {}),
                 },
             });
         }
@@ -326,7 +350,7 @@ async function runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs,
     const runEntry = async (entry) => {
         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) {
@@ -348,14 +372,14 @@ async function runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs,
                 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, ctx, registry, 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") {
@@ -372,13 +396,12 @@ async function runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs,
             failed: record.status === "fail",
         };
     };
-    const skippedRecord = (entry) => ({
-        component: ctx.component,
-        phase: phaseDef.phase,
-        kind: isPhaseStep(entry) ? entry.phase : entry.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) => {
+        const kind = isPhaseStep(entry) ? entry.phase : entry.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 () => {
         const gateRecords = await decideGates();
         if (phaseDef.parallel) {
@@ -412,18 +435,18 @@ async function runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs,
         }
         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;
     }
@@ -492,16 +515,17 @@ async function rollbackExecuted(executed, ctx, registry) {
  * 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, ctx, registry, componentOutputs, onProgress, gateContext = { port: gitGateLedgerPort() }) {
+export async function runComponentDeploy(component, ctx, registry, componentOutputs, onProgress, gateContext = { port: gitGateLedgerPort() }, onRunEvent) {
+    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 } };
@@ -515,18 +539,20 @@ export async function runComponentDeploy(component, ctx, registry, componentOutp
         ctx.release.version = release;
     const gates = {
         ...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 = [];
     const allExecuted = [];
     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);
         }
@@ -559,7 +585,7 @@ export async function runComponentDeploy(component, ctx, registry, componentOutp
         records.push(...(await rollbackExecuted(allExecuted, ctx, registry)));
         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) {
@@ -688,29 +714,30 @@ export async function runInterpretDriver(components, registry, options) {
     const { order, waves } = resolveComponentGraph(components);
     const byName = new Map(components.map((c) => [c.name, c]));
     const componentOutputs = { ...(options.componentOutputs ?? {}) };
-    const { onProgress } = options;
+    const emit = joinRunEventSinks(options.onRunEvent, progressSinkOf(options.onProgress));
     const gates = {
         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 = [];
     let failedComponent;
     let gated;
     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 });
-            const result = await runComponentDeploy(component, deployContext(options, component.name), registry, componentOutputs, onProgress, gates);
-            onProgress?.({ type: "component-done", wave: waveNum, component: component.name, status: progressStatus(result.status) });
+            emit?.({ type: "component-start", wave: waveNum, component: component.name });
+            const result = await runComponentDeploy(component, deployContext(options, component.name), registry, componentOutputs, undefined, gates, emit);
+            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.
@@ -724,7 +751,7 @@ export async function runInterpretDriver(components, registry, options) {
     }
     const 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 = {
         order, waves, results, ok, status, failedComponent, componentOutputs,
         ...(gated

package/dist/components/fan-out-run.d.ts

@@ -42,6 +42,7 @@ import type { ReleaseIdentity } from "../telemetry-attribution.js";
 import { type FanOutPlan, type FanOutProgress, type FanOutSkip } from "./fan-out.js";
 import { type GateLedgerPort } from "../op/gate.js";
 import type { RunProgressEvent } from "./run-progress.js";
+import { type RunEventSink } from "../run-event-stream.js";
 import type { CapabilityRegistry } from "./capability.js";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger.js";
 import type { DeployContext } from "./capability.js";
@@ -93,6 +94,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`. */

package/dist/components/fan-out-run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fan-out-run.d.ts","sourceRoot":"","sources":["../../src/components/fan-out-run.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fan-out-run.d.ts","sourceRoot":"","sources":["../../src/components/fan-out-run.ts"],"names":[],"mappings":"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"}

package/dist/components/fan-out-run.js

@@ -40,8 +40,13 @@
 import { deployContext, runComponentDeploy, } from "./driver.js";
 import { downstreamWithin, remainingFanOut } from "./fan-out.js";
 import { evaluateGate, gitGateLedgerPort } from "../op/gate.js";
+import { emitGateStep, joinRunEventSinks, progressSinkOf } from "../run-event-stream.js";
 import { planWaveComponent } from "./wave-plan.js";
 import { decideWaveGate, runWaveLoop, waveGateName, waveSetDigest } from "../wave-engine.js";
+/** The sink a fan-out emits to: run events, and the older stream through them. */
+function fanOutSink(options) {
+    return joinRunEventSinks(options.onRunEvent, progressSinkOf(options.onProgress));
+}
 /** Thrown when `FanOutWaveGate.only` names a wave whose predecessors have not all applied. */
 export class EarlierWaveNotAppliedError extends Error {
     constructor(wave, earlier, components) {
@@ -78,18 +83,22 @@ export async function runFanOut(plan, components, registry, options) {
     if (options.waveGate) {
         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,
+        const gate = options.gate;
+        const check = await emitGateStep(emit, gate, () => evaluateGate(gates.port, {
+            op: gate.op,
+            gate: gate.gate,
             planDigest: active.digest,
-            ...(options.gate.description ? { description: options.gate.description } : {}),
-            ...(options.gate.timeout ? { timeout: options.gate.timeout } : {}),
+            ...(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",
@@ -116,20 +125,19 @@ export async function runFanOut(plan, components, registry, options) {
             blockedBy.set(component, by);
         }
     };
-    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, gates);
-            options.onProgress?.({
-                type: "component-done",
+            const result = await runComponentDeploy(byName.get(name), { ...fanOutContext(options, name), ...(planned && Object.keys(planned).length > 0 ? { plans: planned } : {}) }, registry, componentOutputs, undefined, gates, emit);
+            emit?.({
+                type: "component-settle",
                 wave: waveNum,
                 component: name,
                 status: result.status === "fail" ? "failed" : result.status,
@@ -155,8 +163,8 @@ export async function runFanOut(plan, components, registry, options) {
             markBlocked(result.component);
         }
         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",
         });
@@ -167,7 +175,7 @@ export async function runFanOut(plan, components, registry, options) {
     // 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 = 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,
         status,
@@ -230,7 +238,8 @@ async function runGatedWaves(plan, active, components, registry, options, waveGa
             blockedBy.set(component, by);
         }
     };
-    options.onProgress?.({ type: "run-start", waves: plan.waves });
+    const emit = fanOutSink(options);
+    emit?.({ type: "run-start", waves: plan.waves });
     await runWaveLoop({
         first: 1,
         onward: (_k, outcome) => outcome === "next",
@@ -300,14 +309,14 @@ async function runGatedWaves(plan, active, components, registry, options, waveGa
                 options.onWaveSettled?.(record);
                 return { end: "next" };
             }
-            const check = await decideWaveGate(gates.port, {
+            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.
@@ -324,14 +333,14 @@ async function runGatedWaves(plan, active, components, registry, options, waveGa
             return { go: { check, record, toRun } };
         },
         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,
@@ -362,8 +371,8 @@ async function runGatedWaves(plan, active, components, registry, options, waveGa
             };
             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",
             });
@@ -374,7 +383,7 @@ async function runGatedWaves(plan, active, components, registry, options, waveGa
         .sort(([a], [b]) => a.localeCompare(b))
         .map(([component, by]) => ({ component, reason: "blocked", blockedBy: by }));
     const 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.
         plan: { ...active, waves: plan.waves },

package/dist/components/pr-run.d.ts

@@ -41,6 +41,7 @@ import { type ComponentChangeSignal, type FanOutPlan } from "./fan-out.js";
 import type { PrApplyRecord } from "./fan-out-record.js";
 import type { CapabilityRegistry } from "./capability.js";
 import type { RunProgressEvent } from "./run-progress.js";
+import type { RunEventSink } from "../run-event-stream.js";
 export interface PrPlanSetOptions {
     /** Every component in the project. */
     components: DriverComponent[];
@@ -51,7 +52,15 @@ export interface PrPlanSetOptions {
     vars?: Record<string, unknown>;
     /** Outputs supplied by the caller (`--seed-outputs`). They win over outputs read here. */
     seededOutputs?: Record<string, Record<string, unknown>>;
+    /**
+     * Where the planning's events go (#4041): a `plan` phase with no
+     * component, and in it one `plan` step per component, started as its wave
+     * is planned and settled `ok` or `failed`.
+     */
+    onRunEvent?: RunEventSink;
 }
+/** The phase a pull request's planning is, in its run's events. */
+export declare const PR_PLAN_PHASE = "plan";
 /** Every member of a pull request, planned. */
 export interface PrPlanSet {
     /** The change-set document over every member. Its digest is what the gate binds. */
@@ -101,6 +110,8 @@ export interface PrApplyOptions {
     /** The set {@link planPrSet} planned and the gate approved, or {@link resumePrSet}'s set. */
     set: PrPlanSet;
     onProgress?: (event: RunProgressEvent) => void;
+    /** Where the apply's events go (#4041): the fan-out's run events. */
+    onRunEvent?: RunEventSink;
     /**
      * What an earlier attempt at this approved set applied (#3464): its
      * components, which are reported applied and not run again, and the

package/dist/components/pr-run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pr-run.d.ts","sourceRoot":"","sources":["../../src/components/pr-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAA2C,KAAK,iBAAiB,EAA2C,MAAM,eAAe,CAAC;AACzI,OAAO,EAAgB,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,QAAQ,EACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAiB,KAAK,eAAe,EAAE,KAAK,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAE3F,OAAO,EAAa,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,EAAmB,KAAK,qBAAqB,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AACzF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGvD,MAAM,WAAW,gBAAgB;IAC/B,sCAAsC;IACtC,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,qFAAqF;IACrF,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,0FAA0F;IAC1F,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACzD;AAED,+CAA+C;AAC/C,MAAM,WAAW,SAAS;IACxB,oFAAoF;IACpF,GAAG,EAAE,iBAAiB,CAAC;IACvB,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC/C,0FAA0F;IAC1F,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjD,4CAA4C;IAC5C,MAAM,EAAE,OAAO,CAAC;CACjB;AAWD;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CAoD7E;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,CAQnE;AAED,wDAAwD;AACxD,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CAOvD;AAED,uDAAuD;AACvD,wBAAsB,YAAY,CAChC,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtF,OAAO,CAAC,SAAS,CAAC,CAQpB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAI5G;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,6FAA6F;IAC7F,GAAG,EAAE,SAAS,CAAC;IACf,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC/C;;;;OAIG;IACH,OAAO,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;KAAE,CAAC;IACpF,4FAA4F;IAC5F,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,KAAK,IAAI,CAAC;CAC5G;AAID;;;GAGG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;IAAC,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAC;IAAC,GAAG,EAAE,eAAe,CAAA;CAAE,CAAC,CAyC9I;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAqDvH;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,yGAAyG;IACzG,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,iDAAiD;IACjD,MAAM,EAAE,aAAa,CAAC;IACtB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,MAAM,QAAQ,GAChB;IACE,EAAE,EAAE,IAAI,CAAC;IACT,+CAA+C;IAC/C,IAAI,EAAE,UAAU,CAAC;IACjB,mGAAmG;IACnG,GAAG,EAAE,SAAS,CAAC;IACf,wDAAwD;IACxD,KAAK,EAAE,SAAS,CAAC;CAClB,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,6EAA6E;IAC7E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB,CAAC;AAEN;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CA8B7E;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACxB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,qBAAqB,CAAC;IAC9B,GAAG,EAAE,SAAS,CAAC;IACf,QAAQ,EAAE,UAAU,CAAC;IACrB,MAAM,EAAE,QAAQ,CAAC;IACjB,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC;IACrB,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,iCAAiC;AACjC,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,QAAQ,CA6BvD"}
+{"version":3,"file":"pr-run.d.ts","sourceRoot":"","sources":["../../src/components/pr-run.ts"],"names":[],"mappings":"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"}

package/dist/components/pr-run.js

@@ -40,6 +40,8 @@ import { deployUnits } from "./deploy-units.js";
 import { runFanOut } from "./fan-out-run.js";
 import { remainingFanOut } from "./fan-out.js";
 import { planWaveComponent, readComponentOutputs } from "./wave-plan.js";
+/** The phase a pull request's planning is, in its run's events. */
+export const PR_PLAN_PHASE = "plan";
 /** A failed component's members: the units its steps target, else the component itself. */
 function failedParts(component, error) {
     const units = deployUnits(component.deploy).map((u) => u.unit);
@@ -61,6 +63,8 @@ export async function planPrSet(options) {
     const componentOf = new Map();
     const plans = {};
     let failed = false;
+    const emit = options.onRunEvent;
+    emit?.({ type: "phase-start", component: null, phase: PR_PLAN_PHASE });
     for (const wave of options.plan.waves) {
         // The dependencies' outputs first, each read once. A dependency that
         // cannot say leaves its references unresolved, which its dependent's
@@ -75,7 +79,20 @@ export async function planPrSet(options) {
                     outputs[dep] = found;
             }
         }
-        const planned = await Promise.all(wave.map((name) => planWaveComponent(byName.get(name), options.registry, deployContext(options, name), outputs)));
+        const planned = await Promise.all(wave.map(async (name) => {
+            const at = { component: name, phase: PR_PLAN_PHASE, step: "plan" };
+            emit?.({ type: "step-start", ...at });
+            const start = Date.now();
+            const p = await planWaveComponent(byName.get(name), options.registry, deployContext(options, name), outputs);
+            emit?.({
+                type: "step-settle",
+                ...at,
+                status: "error" in p ? "failed" : "ok",
+                durationMs: Date.now() - start,
+                ...("error" in p ? { error: p.error } : {}),
+            });
+            return p;
+        }));
         for (const p of planned) {
             const component = byName.get(p.component);
             if ("error" in p) {
@@ -93,6 +110,7 @@ export async function planPrSet(options) {
             }
         }
     }
+    emit?.({ type: "phase-settle", component: null, phase: PR_PLAN_PHASE, status: failed ? "failed" : "ok" });
     const doc = composeChangeSet(parts);
     const members = doc.members.map((m) => ({
         member: m.member,
@@ -161,6 +179,7 @@ export async function applyPrSet(options) {
         plans: options.set.plans,
         componentOutputs: { ...before },
         ...(options.onProgress ? { onProgress: options.onProgress } : {}),
+        ...(options.onRunEvent ? { onRunEvent: options.onRunEvent } : {}),
         ...(options.onComponentSettled ? { onComponentSettled: options.onComponentSettled } : {}),
     });
     const completed = new Set(run.completed);

package/dist/components/promote-order.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The environment `chant components promote` reads from, given the member's
+ * promotion order (#4030, see `../workspace/promotion-order.ts`). These
+ * refusals are promote's own and are not codes of the workspace read contract.
+ */
+import type { PromotionStep } from "../workspace/promotion-order.js";
+/** The refusals `components promote` gives for the declared order. Stable: scripts may match on them. */
+export declare const PROMOTE_ORDER_CODES: readonly [
+/** `--from` is more than one step behind `--to` in the declared order, and `--allow-skip` was not given. */
+"promote-skips-environment", 
+/** `--to` is the first step of the declared order, so no environment comes before it to default `--from` to. */
+"promote-no-previous-environment", 
+/** `--from` was left out and `--to` is not a step of the declared order, so there is nothing to default it from. */
+"promote-to-not-in-order"];
+export type PromoteOrderCode = (typeof PROMOTE_ORDER_CODES)[number];
+export interface PromotionRefusal {
+    error: {
+        code: PromoteOrderCode;
+        message: string;
+        fix: string;
+    };
+}
+/**
+ * The environment a promote reads from. With an order declared, `--from`
+ * defaults to the step before `to`, and a `--from` that skips a step is
+ * refused unless `allowSkip`. Without an order, or when `to` or `from` is not
+ * a step of it, the order has nothing to say and `from` is returned as given
+ * (`undefined` is the caller's to refuse, as before).
+ */
+export declare function resolvePromotionSource(opts: {
+    order: readonly PromotionStep[];
+    to: string;
+    from?: string;
+    allowSkip?: boolean;
+}): {
+    from: string | undefined;
+} | PromotionRefusal;
+//# sourceMappingURL=promote-order.d.ts.map

package/dist/components/promote-order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promote-order.d.ts","sourceRoot":"","sources":["../../src/components/promote-order.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElE,yGAAyG;AACzG,eAAO,MAAM,mBAAmB;AAC9B,4GAA4G;AAC5G,2BAA2B;AAC3B,gHAAgH;AAChH,iCAAiC;AACjC,oHAAoH;AACpH,yBAAyB,CACjB,CAAC;AACX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE;QAAE,IAAI,EAAE,gBAAgB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,GAAG;IAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAAG,gBAAgB,CAuClD"}