@intentius/chant 0.18.29 → 0.18.30

package/dist/cli/handlers/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/run.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AA0ClD,wBAAsB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,EAAE,WAAW,EAAE,MAAM;;;;GAO5F;AA8BD,wBAAsB,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAgEpE;AAoFD,wBAAsB,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAuCtE;AA0CD,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA6CnE;AA2DD;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAwBtE;AAID,2LAA2L;AAC3L,wBAAsB,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA8BtE;AAmCD;;;;;;;;;;;;GAYG;AACH,wBAAsB,KAAK,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAchE;AA6ED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA+D1E;AAkOD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAiFrE;AAuLD,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAMjE"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/run.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AA2ClD,wBAAsB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,EAAE,WAAW,EAAE,MAAM;;;;GAO5F;AA8BD,wBAAsB,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAgEpE;AAoFD,wBAAsB,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAuCtE;AA0CD,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA6CnE;AA2DD;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAwBtE;AAID,2LAA2L;AAC3L,wBAAsB,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA8BtE;AAmCD;;;;;;;;;;;;GAYG;AACH,wBAAsB,KAAK,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAchE;AA6ED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAsE1E;AAkOD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAiFrE;AAuLD,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAMjE"}

package/dist/cli/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AAMA,OAAO,EAAmC,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAkB9E;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA2LpD;AAsVD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAuB5E"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AAMA,OAAO,EAAmC,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAkB9E;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA6LpD;AA2VD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAuB5E"}

package/dist/cli/registry.d.ts

@@ -25,6 +25,8 @@ export interface ParsedArgs {
     temporal?: boolean;
     /** `chant run` — emit the structured OpRunResult as JSON on stdout. */
     json?: boolean;
+    /** `chant run --components <name|all> --progress-json` — stream one NDJSON `RunProgressEvent` (../../components/run-progress.ts) per line to stdout while the run executes (local executor only), so a consumer can render live wave/component/phase/step progress instead of tailing raw logs. Purely additive: run semantics, ordering, and exit code are unchanged; omitted (undefined, not false) when the flag isn't passed. */
+    progressJson?: boolean;
     live: boolean;
     /** `chant migrate --from <name>` (default "github") */
     migrateFrom?: string;

package/dist/cli/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/cli/registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/cli/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,uEAAuE;IACvE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,qaAAqa;IACra,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,IAAI,EAAE,OAAO,CAAC;IACd,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+DAA+D;IAC/D,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mFAAmF;IACnF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;mFAC+E;IAC/E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;8DAC0D;IAC1D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;oFACgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;2EAGuE;IACvE,aAAa,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAClC;iFAC6E;IAC7E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;6DAEyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,+EAA+E;IAC/E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;uFACmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gGAAgG;IAChG,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mFAAmF;IACnF,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kHAAkH;IAClH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sJAAsJ;IACtJ,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,uKAAuK;IACvK,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,0HAA0H;IAC1H,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oJAAoJ;IACpJ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uGAAuG;IACvG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oJAAoJ;IACpJ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8RAA8R;IAC9R,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,8NAA8N;IAC9N,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uTAAuT;IACvT,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,0CAA0C;IAC1C,OAAO,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACnD;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,UAAU,CAAC;IAChB,4FAA4F;IAC5F,QAAQ,EAAE,OAAO,CAAC;CACnB;AAWD,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,eAAe,GAAG,IAAI,CAiB/F"}

package/dist/components/cli-support.d.ts

@@ -24,6 +24,7 @@
 import { type Archetype } from "./component.js";
 import { type DriverComponent, type DriverRunResult } from "./driver.js";
 import { type ComponentPipelineOptions } from "../lexicon.js";
+import type { RunProgressEvent } from "./run-progress.js";
 import type { CapabilityRegistry } from "./capability.js";
 import { type ChantConfig } from "../config.js";
 /** One component in `chant list --components` output. */
@@ -147,6 +148,18 @@ export interface RunComponentsOptions {
      * ran elsewhere. Merged with, and overridden by, outputs this run produces.
      */
     componentOutputs?: Record<string, Record<string, unknown>>;
+    /**
+     * Opt-in structured progress observer (`chant run --components <name|all>
+     * --progress-json`, see ./run-progress.ts). Threaded straight through to
+     * `runInterpretDriver` for `selector === "all"`; for a single-component
+     * selector (which bypasses `runInterpretDriver` — see the docstring above),
+     * this function emits the same `run-start`/`wave-start`/`component-start`/
+     * …/`run-done` envelope itself, treating the one component as a run with a
+     * single wave, so `--progress-json` produces a well-formed event stream
+     * regardless of selector. Left `undefined` by every caller that didn't pass
+     * `--progress-json`, in which case nothing changes.
+     */
+    onProgress?: (event: RunProgressEvent) => void;
 }
 /** Result of `chant run --components <name|all>`. */
 export interface RunComponentsResult {

package/dist/components/cli-support.d.ts.map

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

package/dist/components/driver.d.ts

@@ -41,6 +41,8 @@
  * `CapabilityRegistry` the caller supplies.
  */
 import type { CapabilityRegistry, DeployContext } from "./capability.js";
+import type { RunProgressEvent } from "./run-progress.js";
+export type { RunProgressEvent } from "./run-progress.js";
 /** A wiring reference or literal value, as it appears in a step's fields (schema `WiringValue`). */
 export type WiringValue = string | {
     stackOutput: {
@@ -181,8 +183,17 @@ export declare function resolveStepInput(input: Record<string, unknown>, phaseOu
  * handling. Cross-component artifact outputs this component published (if
  * 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.
  */
-export declare function runComponentDeploy(component: DriverComponent, ctx: DeployContext, registry: CapabilityRegistry, componentOutputs: Record<string, Record<string, unknown>>): Promise<DriverComponentResult>;
+export declare function runComponentDeploy(component: DriverComponent, ctx: DeployContext, registry: CapabilityRegistry, componentOutputs: Record<string, Record<string, unknown>>, onProgress?: (event: RunProgressEvent) => void): Promise<DriverComponentResult>;
 export interface InterpretRunOptions {
     /** Target environment name, threaded into every capability's `DeployContext`. */
     env: string;
@@ -190,6 +201,16 @@ export interface InterpretRunOptions {
     vars?: Record<string, unknown>;
     /** Pre-seeded cross-component/cross-stack outputs (e.g. from a prior run, or a caller resolving `stackOutput` externally). Merged with outputs this run produces. */
     componentOutputs?: Record<string, Record<string, unknown>>;
+    /**
+     * Opt-in structured progress observer (`chant run --components all
+     * --progress-json`, see ./run-progress.ts). Called with `run-start`/
+     * `wave-start`/`component-start`/…/`run-done` events as the run executes;
+     * never consulted for control flow, so leaving it `undefined` (the default
+     * for every caller that didn't pass `--progress-json`) makes every
+     * `onProgress?.(...)` call below a no-op and this function's behavior is
+     * byte-for-byte the same as before this option existed.
+     */
+    onProgress?: (event: RunProgressEvent) => void;
 }
 /**
  * Run a set of components to completion on the local in-process executor:

package/dist/components/driver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/components/driver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/components/driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAIvD,oGAAoG;AACpG,MAAM,MAAM,WAAW,GACnB,MAAM,GACN;IAAE,WAAW,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAChD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5B,uFAAuF;AACvF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,sGAAsG;AACtG,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,iHAAiH;AACjH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,KAAK,CAAC,UAAU,GAAG,UAAU,GAAG,WAAW,CAAC,CAAC;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,WAAW,EAAE,CAAC;CAC3B;AAED,wHAAwH;AACxH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,uGAAuG;IACvG,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;CAC1B;AAYD,kIAAkI;AAClI,qBAAa,0BAA2B,SAAQ,KAAK;aAEjC,SAAS,EAAE,MAAM;aACjB,UAAU,EAAE,MAAM;gBADlB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM;CAQrC;AAED,uEAAuE;AACvE,qBAAa,oBAAqB,SAAQ,KAAK;aACjB,KAAK,EAAE,MAAM,EAAE;gBAAf,KAAK,EAAE,MAAM,EAAE;CAI5C;AAED,0FAA0F;AAC1F,qBAAa,sBAAuB,SAAQ,KAAK;aAE7B,SAAS,EAAE,MAAM;aACjB,UAAU,EAAE,MAAM;gBADlB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM;CAKrC;AAED,+FAA+F;AAC/F,qBAAa,gBAAiB,SAAQ,KAAK;aACb,MAAM,EAAE,eAAe;gBAAvB,MAAM,EAAE,eAAe;CAIpD;AAID,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,GAAG,aAAa,GAAG,oBAAoB,CAAC;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,kFAAkF;IAClF,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC;IAClB,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,6DAA6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;OAQG;IACH,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC3D;AAID,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,uFAAuF;IACvF,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,cAAc,CAmCnF;AAcD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,WAAW,EAClB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACrD,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxD,OAAO,CAmBT;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACrD,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAazB;AA4OD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,eAAe,EAC1B,GAAG,EAAE,aAAa,EAClB,QAAQ,EAAE,kBAAkB,EAC5B,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzD,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAC7C,OAAO,CAAC,qBAAqB,CAAC,CAwDhC;AAiDD,MAAM,WAAW,mBAAmB;IAClC,iFAAiF;IACjF,GAAG,EAAE,MAAM,CAAC;IACZ,iIAAiI;IACjI,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,qKAAqK;IACrK,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3D;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAChD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,eAAe,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,eAAe,CAAC,CA2C1B"}

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

@@ -0,0 +1,94 @@
+/**
+ * Structured progress events for `chant run --components <sel> --progress-json`
+ * (behold roadmap M3: a consumer that renders live wave/phase/step progress
+ * instead of tailing raw logs).
+ *
+ * This is purely additive observation over the interpret driver's existing
+ * wave -> component -> phase -> step execution loop (./driver.ts): an
+ * optional `onProgress` callback, threaded through
+ * `runInterpretDriver`/`runComponentDeploy`/`runPhase` (and the CLI's
+ * single-component path, ./cli-support.ts's `runComponents`), that never
+ * changes run ordering, gating, `onFailure`, rollback, or exit codes — it
+ * only reports what already happened, as it happens. See ./driver.ts's
+ * module doc for what actually executes; streaming progress on the *durable*
+ * (Temporal) path is a separate, later concern (Temporal already exposes
+ * durable run state via `chant run status`/`log`).
+ *
+ * `RunProgressEvent` is a discriminated union on `type`, one JSON object per
+ * NDJSON line (see `ndjsonProgressSink` below and
+ * ../cli/handlers/run.ts's `--progress-json` wiring).
+ */
+/** Terminal status for a wave/component/phase/run — mirrors DriverStepRecord's ok/fail split, collapsed to the two outcomes a consumer renders progress against. */
+export type RunProgressStatus = "ok" | "failed";
+/** The run is about to start. `waves` are the parallel-safe waves the run will attempt, in order (see resolveComponentGraph) — 1-based wave numbers in every other event index into this array. */
+export interface RunStartEvent {
+    type: "run-start";
+    waves: string[][];
+}
+/** A wave is about to start; its components may run concurrently (independent components share a wave). */
+export interface WaveStartEvent {
+    type: "wave-start";
+    /** 1-based wave number. */
+    wave: number;
+    components: string[];
+}
+/** A component within a wave is about to start its `deploy` composition. */
+export interface ComponentStartEvent {
+    type: "component-start";
+    wave: number;
+    component: string;
+}
+/** A named phase of a component's composition is about to run its steps. Emitted for nested (fan-out) phases too, keyed by the nested phase's own name. */
+export interface PhaseStartEvent {
+    type: "phase-start";
+    component: string;
+    phase: string;
+}
+/** A single capability step within a phase — one event when it starts, one when it settles. */
+export interface StepEvent {
+    type: "step";
+    component: string;
+    phase: string;
+    step: string;
+    status: "running" | "ok" | "failed";
+    /** Present only alongside `status: "failed"`, when the capability threw. */
+    error?: string;
+}
+/** A phase finished — `ok` if every step in it succeeded, `failed` if any step failed (the phase's remaining steps were skipped, per the driver's fail-fast-within-a-phase semantics). */
+export interface PhaseDoneEvent {
+    type: "phase-done";
+    component: string;
+    phase: string;
+    status: RunProgressStatus;
+}
+/** A component's `deploy` composition finished (after any saga rollback + component-level `rollback` phases the driver ran on failure). */
+export interface ComponentDoneEvent {
+    type: "component-done";
+    wave: number;
+    component: string;
+    status: RunProgressStatus;
+}
+/** A wave finished — `failed` if any component in it failed, which also stops the run before any later wave starts. */
+export interface WaveDoneEvent {
+    type: "wave-done";
+    wave: number;
+    status: RunProgressStatus;
+}
+/** The run finished. Mirrors the driver's own terminal `DriverRunResult.ok` / exit code. */
+export interface RunDoneEvent {
+    type: "run-done";
+    status: RunProgressStatus;
+}
+export type RunProgressEvent = RunStartEvent | WaveStartEvent | ComponentStartEvent | PhaseStartEvent | StepEvent | PhaseDoneEvent | ComponentDoneEvent | WaveDoneEvent | RunDoneEvent;
+/** A sink that receives progress events as they occur. The driver only ever calls this — it never writes to a stream directly, so it stays testable without stdout. */
+export type RunProgressSink = (event: RunProgressEvent) => void;
+/**
+ * Build a sink that writes `JSON.stringify(event) + "\n"` to `write` (default:
+ * `process.stdout.write`), one line per event, as they happen — the
+ * `--progress-json` CLI wiring's sink (../cli/handlers/run.ts). Kept separate
+ * from `driver-output.ts`'s end-of-run renderers: this emits *during* the
+ * run, one line at a time; `renderDriverJson`/`renderDriverHuman` render the
+ * completed `DriverRunResult` once, after the run finishes.
+ */
+export declare function ndjsonProgressSink(write?: (chunk: string) => void): RunProgressSink;
+//# sourceMappingURL=run-progress.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run-progress.d.ts","sourceRoot":"","sources":["../../src/components/run-progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,oKAAoK;AACpK,MAAM,MAAM,iBAAiB,GAAG,IAAI,GAAG,QAAQ,CAAC;AAEhD,mMAAmM;AACnM,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC;CACnB;AAED,2GAA2G;AAC3G,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,2JAA2J;AAC3J,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,aAAa,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,+FAA+F;AAC/F,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,IAAI,GAAG,QAAQ,CAAC;IACpC,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,0LAA0L;AAC1L,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAED,2IAA2I;AAC3I,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAED,uHAAuH;AACvH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAED,4FAA4F;AAC5F,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAED,MAAM,MAAM,gBAAgB,GACxB,aAAa,GACb,cAAc,GACd,mBAAmB,GACnB,eAAe,GACf,SAAS,GACT,cAAc,GACd,kBAAkB,GAClB,aAAa,GACb,YAAY,CAAC;AAEjB,uKAAuK;AACvK,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;AAEhE;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,GAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAA0C,GAAG,eAAe,CAExH"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.18.29",
+  "version": "0.18.30",
   "description": "Declarative infrastructure-as-code toolkit \u2014 TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/cli/handlers/run.test.ts

@@ -945,6 +945,60 @@ describe("runOpComponents", () => {
     vi.restoreAllMocks();
   });
 
+  // ── --progress-json (M3, behold roadmap) ──────────────────────────────────
+
+  test("--progress-json streams NDJSON progress events to stdout as runComponents emits them", async () => {
+    runComponentsMock.mockImplementation(
+      async (_path: string, _selector: string, options: { onProgress?: (e: unknown) => void }) => {
+        options.onProgress?.({ type: "run-start", waves: [["svc"]] });
+        options.onProgress?.({ type: "run-done", status: "ok" });
+        return {
+          success: true,
+          selected: ["svc"],
+          run: { order: ["svc"], waves: [["svc"]], results: [{ component: "svc", ok: true, records: [] }], ok: true },
+        };
+      },
+    );
+    const stdoutWrite = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+    vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+
+    const exit = await runOpComponents({
+      args: makeArgs({ path: "svc", progressJson: true, temporal: false }),
+      plugins: [],
+      serializers: [],
+    });
+
+    expect(exit).toBe(0);
+    const lines = stdoutWrite.mock.calls.map((c) => String(c[0])).filter((s) => s.trim().length > 0);
+    expect(lines.map((l) => JSON.parse(l))).toEqual([
+      { type: "run-start", waves: [["svc"]] },
+      { type: "run-done", status: "ok" },
+    ]);
+    // Every line is a single, complete JSON object — real NDJSON, not one big blob.
+    for (const line of lines) expect(() => JSON.parse(line)).not.toThrow();
+    vi.restoreAllMocks();
+  });
+
+  test("without --progress-json, runComponents receives onProgress: undefined and nothing streams", async () => {
+    runComponentsMock.mockResolvedValue({
+      success: true,
+      selected: ["svc"],
+      run: { order: ["svc"], waves: [["svc"]], results: [{ component: "svc", ok: true, records: [] }], ok: true },
+    });
+    const stdoutWrite = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+    vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+
+    await runOpComponents({ args: makeArgs({ path: "svc", temporal: false }), plugins: [], serializers: [] });
+
+    expect(runComponentsMock).toHaveBeenCalledWith(expect.any(String), "svc", {
+      env: undefined,
+      componentOutputs: {},
+      onProgress: undefined,
+    });
+    expect(stdoutWrite).not.toHaveBeenCalled();
+    vi.restoreAllMocks();
+  });
+
   test("all: dispatches the 'all' selector and renders every component", async () => {
     runComponentsMock.mockResolvedValue({
       success: true,

package/src/cli/handlers/run.ts

@@ -21,6 +21,7 @@ import {
 import { generateReport, writeReport } from "./run-report";
 import { runComponents, resolveComponentTargets, findComponentGate, listComponents } from "../../components/cli-support";
 import { renderDriverHuman, renderDriverJson } from "../../components/driver-output";
+import { ndjsonProgressSink } from "../../components/run-progress";
 import { loadComponentTemporalCodegen } from "../../components/temporal-codegen-loader";
 import { applyConfigDefaults } from "../../components/config-defaults";
 import { maybeRecordAutoRelease, extractRunDigestFromPhaseOutputs } from "../../components/auto-release";
@@ -686,7 +687,14 @@ export async function runOpComponents(ctx: CommandContext): Promise<number> {
       return 1;
     }
   }
-  const result = await runComponents(resolve("."), selector, { env: ctx.args.env, componentOutputs: seededOutputs });
+  // `--progress-json` (#M3, behold roadmap): stream one NDJSON RunProgressEvent
+  // per line to stdout while the run executes, so a consumer (e.g. behold) can
+  // render live wave/component/phase/step progress instead of tailing raw
+  // logs. Purely additive: when the flag is absent, `onProgress` stays
+  // `undefined` and every `onProgress?.(...)` call in the driver is a no-op —
+  // behavior is byte-for-byte unchanged from before this flag existed.
+  const onProgress = ctx.args.progressJson ? ndjsonProgressSink() : undefined;
+  const result = await runComponents(resolve("."), selector, { env: ctx.args.env, componentOutputs: seededOutputs, onProgress });
 
   // Dump the accumulated outputs for a downstream job to seed from. Written
   // even on failure (partial outputs) so a resumed run still has what completed.

package/src/cli/main.test.ts

@@ -234,6 +234,20 @@ describe("parseArgs", () => {
     const result = parseArgs(["run", "--components", "search-service"]);
     expect(result.noReleaseRecord).toBeUndefined();
   });
+
+  // ── --progress-json (M3, behold roadmap) ─────────────────────────────────
+
+  test("parses --progress-json for run --components", () => {
+    const result = parseArgs(["run", "--components", "search-service", "--env", "staging", "--progress-json"]);
+    expect(result.components).toBe(true);
+    expect(result.env).toBe("staging");
+    expect(result.progressJson).toBe(true);
+  });
+
+  test("--progress-json is undefined (not false) when omitted", () => {
+    const result = parseArgs(["run", "--components", "search-service"]);
+    expect(result.progressJson).toBeUndefined();
+  });
 });
 
 // ── resolveCommand tests ──────────────────────────────────────────

package/src/cli/main.ts

@@ -172,6 +172,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.temporal = true;
     } else if (arg === "--json") {
       result.json = true;
+    } else if (arg === "--progress-json") {
+      result.progressJson = true;
     } else if (arg === "--update-snapshot") {
       result.updateSnapshot = true;
     } else if (arg === "--run-examples") {
@@ -262,6 +264,11 @@ Ops:
                         On success, auto-emits a release-ledger record per
                         component that published a digest (default: on;
                         --no-release-record to opt out; #597)
+                        --progress-json: stream one NDJSON RunProgressEvent
+                        per line to stdout while the run executes, for a
+                        consumer to render live wave/component/phase/step
+                        progress instead of tailing raw logs (additive; run
+                        semantics/exit code unchanged)
 
   graph                 Show Op dependency graph (--stacks for cross-stack order,
                         --format ir|mermaid|dot|layout for the lint-gated graph IR,

package/src/cli/registry.ts

@@ -26,6 +26,8 @@ export interface ParsedArgs {
   temporal?: boolean;
   /** `chant run` — emit the structured OpRunResult as JSON on stdout. */
   json?: boolean;
+  /** `chant run --components <name|all> --progress-json` — stream one NDJSON `RunProgressEvent` (../../components/run-progress.ts) per line to stdout while the run executes (local executor only), so a consumer can render live wave/component/phase/step progress instead of tailing raw logs. Purely additive: run semantics, ordering, and exit code are unchanged; omitted (undefined, not false) when the flag isn't passed. */
+  progressJson?: boolean;
   live: boolean;
   /** `chant migrate --from <name>` (default "github") */
   migrateFrom?: string;

package/src/components/cli-support.test.ts

@@ -16,7 +16,7 @@ import Ajv2020 from "ajv/dist/2020";
 import componentSchema from "./component.schema.json";
 import { listComponents, describeComponent, computeComponentGraph, runComponents, findComponentGate } from "./cli-support";
 import { CapabilityRegistry, type DeployContext } from "./capability";
-import type { DriverComponent } from "./driver";
+import type { DriverComponent, RunProgressEvent } from "./driver";
 
 describe("listComponents", () => {
   let testDir: string;
@@ -577,3 +577,94 @@ describe("runComponents", () => {
     expect(capability.calls[0]?.input).toMatchObject({ format: "cyclonedx" });
   });
 });
+
+describe("runComponents — onProgress (--progress-json wiring, M3)", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-run-components-progress-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  test("selector 'all': onProgress sees the same run-start/wave-*/component-*/run-done envelope runInterpretDriver emits", async () => {
+    await writeFile(
+      join(testDir, "alb.component.ts"),
+      `export const alb = { name: "shared-alb", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "deploy-thing" }] }] };`,
+    );
+    await writeFile(
+      join(testDir, "svc.component.ts"),
+      `export const svc = { name: "search-service", dependsOn: ["shared-alb"], deploy: [{ phase: "Apply", steps: [{ kind: "deploy-thing" }] }] };`,
+    );
+
+    const registry = fakeRegistry();
+    const events: RunProgressEvent[] = [];
+    const result = await runComponents(testDir, "all", { registry, onProgress: (e) => events.push(e) });
+
+    expect(result.success).toBe(true);
+    expect(events[0]).toEqual({ type: "run-start", waves: [["shared-alb"], ["search-service"]] });
+    expect(events.at(-1)).toEqual({ type: "run-done", status: "ok" });
+    expect(events.filter((e) => e.type === "component-start")).toEqual([
+      { type: "component-start", wave: 1, component: "shared-alb" },
+      { type: "component-start", wave: 2, component: "search-service" },
+    ]);
+  });
+
+  test("single-component selector: onProgress still gets a well-formed single-wave envelope (bypasses runInterpretDriver)", async () => {
+    await writeFile(
+      join(testDir, "svc.component.ts"),
+      `export const svc = { name: "svc", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "deploy-thing" }] }] };`,
+    );
+
+    const registry = fakeRegistry();
+    const events: RunProgressEvent[] = [];
+    const result = await runComponents(testDir, "svc", { registry, onProgress: (e) => events.push(e) });
+
+    expect(result.success).toBe(true);
+    expect(events.map((e) => e.type)).toEqual([
+      "run-start",
+      "wave-start",
+      "component-start",
+      "phase-start",
+      "step",
+      "step",
+      "phase-done",
+      "component-done",
+      "wave-done",
+      "run-done",
+    ]);
+    expect(events[0]).toEqual({ type: "run-start", waves: [["svc"]] });
+    expect(events[2]).toEqual({ type: "component-start", wave: 1, component: "svc" });
+    expect(events.at(-1)).toEqual({ type: "run-done", status: "ok" });
+  });
+
+  test("single-component selector: a failing step still yields component-done/wave-done/run-done status:\"failed\"", async () => {
+    await writeFile(
+      join(testDir, "svc.component.ts"),
+      `export const svc = { name: "svc", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "deploy-thing" }] }] };`,
+    );
+
+    const registry = fakeRegistry({ failRun: true });
+    const events: RunProgressEvent[] = [];
+    const result = await runComponents(testDir, "svc", { registry, onProgress: (e) => events.push(e) });
+
+    expect(result.success).toBe(false);
+    expect(events.at(-3)).toEqual({ type: "component-done", wave: 1, component: "svc", status: "failed" });
+    expect(events.at(-2)).toEqual({ type: "wave-done", wave: 1, status: "failed" });
+    expect(events.at(-1)).toEqual({ type: "run-done", status: "failed" });
+  });
+
+  test("no onProgress passed → no behavior change (result identical, and it's simply never called)", async () => {
+    await writeFile(
+      join(testDir, "svc.component.ts"),
+      `export const svc = { name: "svc", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "deploy-thing" }] }] };`,
+    );
+
+    const result = await runComponents(testDir, "svc", { registry: fakeRegistry() });
+    expect(result.success).toBe(true);
+    expect(result.run?.ok).toBe(true);
+  });
+});

package/src/components/cli-support.ts

@@ -37,6 +37,7 @@ import {
   type DriverRunResult,
 } from "./driver";
 import { isLexiconPlugin, type LexiconPlugin, type ComponentPipelineOptions } from "../lexicon";
+import type { RunProgressEvent } from "./run-progress";
 import { relative } from "node:path";
 import { buildCapabilityRegistry } from "./capability-plugin-loader";
 import type { CapabilityRegistry } from "./capability";
@@ -323,6 +324,18 @@ export interface RunComponentsOptions {
    * ran elsewhere. Merged with, and overridden by, outputs this run produces.
    */
   componentOutputs?: Record<string, Record<string, unknown>>;
+  /**
+   * Opt-in structured progress observer (`chant run --components <name|all>
+   * --progress-json`, see ./run-progress.ts). Threaded straight through to
+   * `runInterpretDriver` for `selector === "all"`; for a single-component
+   * selector (which bypasses `runInterpretDriver` — see the docstring above),
+   * this function emits the same `run-start`/`wave-start`/`component-start`/
+   * …/`run-done` envelope itself, treating the one component as a run with a
+   * single wave, so `--progress-json` produces a well-formed event stream
+   * regardless of selector. Left `undefined` by every caller that didn't pass
+   * `--progress-json`, in which case nothing changes.
+   */
+  onProgress?: (event: RunProgressEvent) => void;
 }
 
 /** Result of `chant run --components <name|all>`. */
@@ -449,10 +462,11 @@ export async function runComponents(
   // from a caller (a downstream CI job passing an upstream job's dumped
   // outputs via `--seed-outputs`); grows as this run's components complete.
   const seedOutputs = options.componentOutputs ?? {};
+  const { onProgress } = options;
 
   try {
     if (selector === "all") {
-      const run = await runInterpretDriver(resolvedTargets, registry, { env, componentOutputs: seedOutputs });
+      const run = await runInterpretDriver(resolvedTargets, registry, { env, componentOutputs: seedOutputs, onProgress });
       return { success: true, run, selected };
     }
 
@@ -462,8 +476,28 @@ export async function runComponents(
     // so a single-component run still resolves their `stackOutput()`/publish
     // references. `runComponentDeploy` mutates this map with this component's
     // own outputs, which `run.componentOutputs` then exposes for `--dump-outputs`.
+    //
+    // There's no `runInterpretDriver` call here to thread progress through
+    // (that's the whole point of the single-component bypass), so the
+    // run-start/wave-start/component-start/…/run-done envelope is emitted by
+    // hand, treating this one component as a single-wave run — the same shape
+    // `run.waves`/`run.order` below already give it.
     const componentOutputs = { ...seedOutputs };
-    const componentResult = await runComponentDeploy(resolvedTargets[0], { env, component: resolvedTargets[0].name }, registry, componentOutputs);
+    const componentName = resolvedTargets[0].name;
+    onProgress?.({ type: "run-start", waves: [selected] });
+    onProgress?.({ type: "wave-start", wave: 1, components: selected });
+    onProgress?.({ type: "component-start", wave: 1, component: componentName });
+    const componentResult = await runComponentDeploy(
+      resolvedTargets[0],
+      { env, component: componentName },
+      registry,
+      componentOutputs,
+      onProgress,
+    );
+    const status: "ok" | "failed" = componentResult.ok ? "ok" : "failed";
+    onProgress?.({ type: "component-done", wave: 1, component: componentName, status });
+    onProgress?.({ type: "wave-done", wave: 1, status });
+    onProgress?.({ type: "run-done", status });
     const run: DriverRunResult = {
       order: selected,
       waves: [selected],

package/src/components/driver.test.ts

@@ -23,6 +23,8 @@ import {
   runComponentDeploy,
   runInterpretDriver,
   type DriverComponent,
+  type DriverStepRecord,
+  type RunProgressEvent,
 } from "./driver";
 import { neo4jCluster } from "./pilots/neo4j-fanout.pilot";
 import { ordersTable } from "./pilots/dynamodb.pilot";
@@ -618,6 +620,194 @@ describe("runInterpretDriver — end to end", () => {
   });
 });
 
+describe("onProgress — --progress-json event stream (M3, additive over the wave/component/phase/step loop)", () => {
+  /** Drop the nondeterministic `durationMs` field so a run's records can be compared for equality across two invocations. */
+  function stripTiming(records: DriverStepRecord[]): Omit<DriverStepRecord, "durationMs">[] {
+    return records.map(({ durationMs: _durationMs, ...rest }) => rest);
+  }
+
+  it("emits run-start -> wave-start -> component-start -> phase-start -> step(running/ok) -> phase-done -> component-done -> wave-done, once per wave, then run-done", async () => {
+    const registry = new CapabilityRegistry();
+    registry.register(fakeCapability("step-a", { run: () => ({ ok: true }) }).capability);
+    registry.register(fakeCapability("step-b", { run: () => ({ ok: true }) }).capability);
+
+    const a: DriverComponent = { name: "a", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "step-a" }] }] };
+    const b: DriverComponent = { name: "b", dependsOn: ["a"], deploy: [{ phase: "Apply", steps: [{ kind: "step-b" }] }] };
+
+    const events: RunProgressEvent[] = [];
+    const result = await runInterpretDriver([a, b], registry, { env: "dev", onProgress: (e) => events.push(e) });
+
+    expect(result.ok).toBe(true);
+    expect(events.map((e) => e.type)).toEqual([
+      "run-start",
+      "wave-start",
+      "component-start",
+      "phase-start",
+      "step",
+      "step",
+      "phase-done",
+      "component-done",
+      "wave-done",
+      "wave-start",
+      "component-start",
+      "phase-start",
+      "step",
+      "step",
+      "phase-done",
+      "component-done",
+      "wave-done",
+      "run-done",
+    ]);
+
+    // Wave 1: component "a".
+    expect(events[0]).toEqual({ type: "run-start", waves: [["a"], ["b"]] });
+    expect(events[1]).toEqual({ type: "wave-start", wave: 1, components: ["a"] });
+    expect(events[2]).toEqual({ type: "component-start", wave: 1, component: "a" });
+    expect(events[3]).toEqual({ type: "phase-start", component: "a", phase: "Apply" });
+    expect(events[4]).toEqual({ type: "step", component: "a", phase: "Apply", step: "step-a", status: "running" });
+    expect(events[5]).toEqual({ type: "step", component: "a", phase: "Apply", step: "step-a", status: "ok" });
+    expect(events[6]).toEqual({ type: "phase-done", component: "a", phase: "Apply", status: "ok" });
+    expect(events[7]).toEqual({ type: "component-done", wave: 1, component: "a", status: "ok" });
+    expect(events[8]).toEqual({ type: "wave-done", wave: 1, status: "ok" });
+
+    // Wave 2: component "b" (1-based wave numbering).
+    expect(events[9]).toEqual({ type: "wave-start", wave: 2, components: ["b"] });
+    expect(events[10]).toEqual({ type: "component-start", wave: 2, component: "b" });
+    expect(events[15]).toEqual({ type: "component-done", wave: 2, component: "b", status: "ok" });
+    expect(events[16]).toEqual({ type: "wave-done", wave: 2, status: "ok" });
+
+    expect(events[17]).toEqual({ type: "run-done", status: "ok" });
+  });
+
+  it("a failing step yields step:failed (with error), phase-done:failed, component-done:failed, wave-done:failed, run-done:failed — and a later wave never starts", async () => {
+    const registry = new CapabilityRegistry();
+    registry.register(fakeCapability("bad-step", { failRun: true }).capability);
+    registry.register(fakeCapability("step-b", { run: () => ({ ok: true }) }).capability);
+
+    const a: DriverComponent = { name: "a", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "bad-step" }] }] };
+    const b: DriverComponent = { name: "b", dependsOn: ["a"], deploy: [{ phase: "Apply", steps: [{ kind: "step-b" }] }] };
+
+    const events: RunProgressEvent[] = [];
+    await expect(
+      runInterpretDriver([a, b], registry, { env: "dev", onProgress: (e) => events.push(e) }),
+    ).rejects.toThrow(DriverRunFailure);
+
+    expect(events.map((e) => e.type)).toEqual([
+      "run-start",
+      "wave-start",
+      "component-start",
+      "phase-start",
+      "step",
+      "step",
+      "phase-done",
+      "component-done",
+      "wave-done",
+      "run-done",
+    ]);
+    // Only wave 1 ever starts — the driver stops at the first failed
+    // component, so wave 2 (containing "b") never runs.
+    expect(events.filter((e) => e.type === "wave-start")).toHaveLength(1);
+    expect(events.filter((e) => e.type === "component-start")).toEqual([{ type: "component-start", wave: 1, component: "a" }]);
+
+    expect(events[4]).toEqual({ type: "step", component: "a", phase: "Apply", step: "bad-step", status: "running" });
+    expect(events[5]).toEqual({
+      type: "step",
+      component: "a",
+      phase: "Apply",
+      step: "bad-step",
+      status: "failed",
+      error: "bad-step failed",
+    });
+    expect(events[6]).toEqual({ type: "phase-done", component: "a", phase: "Apply", status: "failed" });
+    expect(events[7]).toEqual({ type: "component-done", wave: 1, component: "a", status: "failed" });
+    expect(events[8]).toEqual({ type: "wave-done", wave: 1, status: "failed" });
+    expect(events[9]).toEqual({ type: "run-done", status: "failed" });
+  });
+
+  it("produces the identical DriverRunResult (minus timing) whether or not onProgress is passed", async () => {
+    function buildRegistry(): CapabilityRegistry {
+      const registry = new CapabilityRegistry();
+      registry.register(fakeCapability("step-a", { run: () => ({ ok: true }) }).capability);
+      registry.register(fakeCapability("step-b", { run: () => ({ ok: true }) }).capability);
+      return registry;
+    }
+    const a: DriverComponent = { name: "a", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "step-a" }] }] };
+    const b: DriverComponent = { name: "b", dependsOn: ["a"], deploy: [{ phase: "Apply", steps: [{ kind: "step-b" }] }] };
+
+    const withoutProgress = await runInterpretDriver([a, b], buildRegistry(), { env: "dev" });
+    const events: RunProgressEvent[] = [];
+    const withProgress = await runInterpretDriver([a, b], buildRegistry(), {
+      env: "dev",
+      onProgress: (e) => events.push(e),
+    });
+
+    // onProgress was actually exercised — otherwise this comparison would be vacuous.
+    expect(events.length).toBeGreaterThan(0);
+
+    const normalize = (r: typeof withoutProgress) => ({
+      ...r,
+      results: r.results.map((cr) => ({ ...cr, records: stripTiming(cr.records) })),
+    });
+    expect(normalize(withProgress)).toEqual(normalize(withoutProgress));
+  });
+
+  it("runComponentDeploy behaves identically with onProgress omitted (undefined-safe, no-op)", async () => {
+    const registry = new CapabilityRegistry();
+    registry.register(fakeCapability("step-a", { run: () => ({ ok: true }) }).capability);
+    const component: DriverComponent = { name: "c", deploy: [{ phase: "Apply", steps: [{ kind: "step-a" }] }] };
+
+    const result = await runComponentDeploy(component, { env: "dev", component: "c" }, registry, {});
+
+    expect(result.ok).toBe(true);
+    expect(stripTiming(result.records)).toEqual([
+      { component: "c", phase: "Apply", kind: "step-a", status: "ok", output: { ok: true } },
+    ]);
+  });
+
+  it("onFailure saga rollback: rollback-unwind steps are not reported as `step` progress events (only the forward failing step and the component's own authored rollback phase are)", async () => {
+    const registry = new CapabilityRegistry();
+    registry.register(
+      fakeCapability("provision", { run: () => ({ id: "res-1" }), rollback: () => {} }).capability,
+    );
+    registry.register(fakeCapability("apply-final", { failRun: true }).capability);
+    registry.register(fakeCapability("compensate", { run: () => ({ restored: true }) }).capability);
+
+    const component: DriverComponent = {
+      name: "c",
+      deploy: [
+        { phase: "Provision", steps: [{ kind: "provision" }] },
+        { phase: "Apply", steps: [{ kind: "apply-final" }] },
+      ],
+      rollback: [{ phase: "Rollback", steps: [{ kind: "compensate" }] }],
+    };
+
+    const events: RunProgressEvent[] = [];
+    const result = await runComponentDeploy(component, { env: "dev", component: "c" }, registry, {}, (e) =>
+      events.push(e),
+    );
+
+    expect(result.ok).toBe(false);
+    const stepEvents = events.filter((e): e is Extract<RunProgressEvent, { type: "step" }> => e.type === "step");
+    // "provision" (forward, ok), "apply-final" (forward, failed), "compensate"
+    // (the component's own authored rollback phase) — never the saga unwind's
+    // reverse-order capability.rollback() call for "provision", which the
+    // driver still performs but doesn't surface as a `step` event.
+    expect(stepEvents.map((e) => `${e.step}:${e.status}`)).toEqual([
+      "provision:running",
+      "provision:ok",
+      "apply-final:running",
+      "apply-final:failed",
+      "compensate:running",
+      "compensate:ok",
+    ]);
+    expect(events.filter((e) => e.type === "phase-start").map((e) => (e as { phase: string }).phase)).toEqual([
+      "Provision",
+      "Apply",
+      "Rollback",
+    ]);
+  });
+});
+
 describe("capabilities are consumed exactly as the registry provides them", () => {
   // No starter verb is a stub any more, but the stub *mechanism*
   // (./verbs/stub.ts) stays for third-party plugins / future verbs. A stub

package/src/components/driver.ts

@@ -43,6 +43,9 @@
 
 import { topoSort } from "../codegen/topo-sort";
 import type { CapabilityRegistry, DeployContext } from "./capability";
+import type { RunProgressEvent } from "./run-progress";
+
+export type { RunProgressEvent } from "./run-progress";
 
 // ── Component-shaped input (mirrors component.schema.json / ./component.ts) ──
 
@@ -375,6 +378,15 @@ async function runCapabilityStep(
  * inheriting `parallel` from its own definition, not its parent's). Steps run
  * sequentially unless `phase.parallel` is set, in which case they run via
  * `Promise.all`, matching ../op/local-executor.ts's phase semantics.
+ *
+ * `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.
  */
 async function runPhase(
   phaseDef: DriverPhase,
@@ -382,6 +394,7 @@ async function runPhase(
   registry: CapabilityRegistry,
   phaseOutputs: Record<string, Record<string, unknown>>,
   componentOutputs: Record<string, Record<string, unknown>>,
+  onProgress?: (event: RunProgressEvent) => void,
 ): Promise<{ records: DriverStepRecord[]; executed: ExecutedStep[] }> {
   const gate = phaseDef.steps.find(isGateStep);
   if (gate) throw new DriverGateUnsupportedError(ctx.component, gate.signalName);
@@ -393,13 +406,14 @@ async function runPhase(
   ): Promise<{ records: DriverStepRecord[]; executed: ExecutedStep[]; failed: boolean }> => {
     if (isPhaseStep(entry)) {
       try {
-        const nested = await runPhase(entry, ctx, registry, phaseOutputs, componentOutputs);
+        const nested = await runPhase(entry, ctx, registry, phaseOutputs, componentOutputs, onProgress);
         return { ...nested, failed: false };
       } catch (err) {
         if (err instanceof StepFailure) return { records: err.records, executed: err.executed, failed: true };
         throw err;
       }
     }
+    onProgress?.({ type: "step", component: ctx.component, phase: phaseDef.phase, step: entry.kind, status: "running" });
     const { record, resolvedInput, output } = await runCapabilityStep(
       entry,
       phaseDef.phase,
@@ -408,6 +422,14 @@ async function runPhase(
       phaseOutputs,
       componentOutputs,
     );
+    onProgress?.({
+      type: "step",
+      component: ctx.component,
+      phase: phaseDef.phase,
+      step: entry.kind,
+      status: record.status === "ok" ? "ok" : "failed",
+      ...(record.error !== undefined ? { error: record.error } : {}),
+    });
     if (record.status === "ok") {
       phaseOutputs[phaseDef.phase] = { ...(phaseOutputs[phaseDef.phase] ?? {}), ...(output as object) };
     }
@@ -418,35 +440,49 @@ async function runPhase(
     };
   };
 
-  if (phaseDef.parallel) {
-    const results = await Promise.all(entries.map(runEntry));
-    const records = results.flatMap((r) => r.records);
-    const executed = results.flatMap((r) => r.executed);
-    if (results.some((r) => r.failed)) throw new StepFailure(records, executed);
-    return { records, executed };
-  }
+  const runEntries = async (): Promise<{ records: DriverStepRecord[]; executed: ExecutedStep[] }> => {
+    if (phaseDef.parallel) {
+      const results = await Promise.all(entries.map(runEntry));
+      const records = results.flatMap((r) => r.records);
+      const executed = results.flatMap((r) => r.executed);
+      if (results.some((r) => r.failed)) throw new StepFailure(records, executed);
+      return { records, executed };
+    }
 
-  const records: DriverStepRecord[] = [];
-  const executed: ExecutedStep[] = [];
-  for (let i = 0; i < entries.length; i++) {
-    const result = await runEntry(entries[i]);
-    records.push(...result.records);
-    executed.push(...result.executed);
-    if (result.failed) {
-      for (const skipped of entries.slice(i + 1)) {
-        const skippedKind = isPhaseStep(skipped) ? skipped.phase : (skipped as DriverStep).kind;
-        records.push({
-          component: ctx.component,
-          phase: phaseDef.phase,
-          kind: skippedKind,
-          status: "skipped",
-          durationMs: 0,
-        });
+    const records: DriverStepRecord[] = [];
+    const executed: ExecutedStep[] = [];
+    for (let i = 0; i < entries.length; i++) {
+      const result = await runEntry(entries[i]);
+      records.push(...result.records);
+      executed.push(...result.executed);
+      if (result.failed) {
+        for (const skipped of entries.slice(i + 1)) {
+          const skippedKind = isPhaseStep(skipped) ? skipped.phase : (skipped as DriverStep).kind;
+          records.push({
+            component: ctx.component,
+            phase: phaseDef.phase,
+            kind: skippedKind,
+            status: "skipped",
+            durationMs: 0,
+          });
+        }
+        throw new StepFailure(records, executed);
       }
-      throw new StepFailure(records, executed);
     }
+    return { records, executed };
+  };
+
+  onProgress?.({ 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" });
+    return result;
+  } catch (err) {
+    if (err instanceof StepFailure) {
+      onProgress?.({ type: "phase-done", component: ctx.component, phase: phaseDef.phase, status: "failed" });
+    }
+    throw err;
   }
-  return { records, executed };
 }
 
 /**
@@ -517,12 +553,22 @@ async function rollbackExecuted(
  * handling. Cross-component artifact outputs this component published (if
  * 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.
  */
 export async function runComponentDeploy(
   component: DriverComponent,
   ctx: DeployContext,
   registry: CapabilityRegistry,
   componentOutputs: Record<string, Record<string, unknown>>,
+  onProgress?: (event: RunProgressEvent) => void,
 ): Promise<DriverComponentResult> {
   const phaseOutputs: Record<string, Record<string, unknown>> = {};
   const records: DriverStepRecord[] = [];
@@ -530,7 +576,7 @@ export async function runComponentDeploy(
 
   try {
     for (const phaseDef of component.deploy) {
-      const result = await runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs);
+      const result = await runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs, onProgress);
       records.push(...result.records);
       allExecuted.push(...result.executed);
     }
@@ -546,7 +592,7 @@ export async function runComponentDeploy(
 
     for (const phaseDef of [...(component.rollback ?? [])].reverse()) {
       try {
-        const result = await runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs);
+        const result = await runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs, onProgress);
         records.push(...result.records);
       } catch (compErr) {
         if (compErr instanceof StepFailure) records.push(...compErr.records);
@@ -635,6 +681,16 @@ export interface InterpretRunOptions {
   vars?: Record<string, unknown>;
   /** Pre-seeded cross-component/cross-stack outputs (e.g. from a prior run, or a caller resolving `stackOutput` externally). Merged with outputs this run produces. */
   componentOutputs?: Record<string, Record<string, unknown>>;
+  /**
+   * Opt-in structured progress observer (`chant run --components all
+   * --progress-json`, see ./run-progress.ts). Called with `run-start`/
+   * `wave-start`/`component-start`/…/`run-done` events as the run executes;
+   * never consulted for control flow, so leaving it `undefined` (the default
+   * for every caller that didn't pass `--progress-json`) makes every
+   * `onProgress?.(...)` call below a no-op and this function's behavior is
+   * byte-for-byte the same as before this option existed.
+   */
+  onProgress?: (event: RunProgressEvent) => void;
 }
 
 /**
@@ -659,24 +715,34 @@ 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;
+
+  onProgress?.({ type: "run-start", waves });
 
   const results: DriverComponentResult[] = [];
   let failedComponent: string | undefined;
 
-  waveLoop: for (const wave of waves) {
+  waveLoop: for (const [waveIndex, wave] of waves.entries()) {
+    const waveNum = waveIndex + 1;
+    onProgress?.({ type: "wave-start", wave: waveNum, components: wave });
     const waveComponents = wave.map((name) => byName.get(name)!);
     const waveResults = await Promise.all(
-      waveComponents.map((component) =>
-        runComponentDeploy(
+      waveComponents.map(async (component) => {
+        onProgress?.({ type: "component-start", wave: waveNum, component: component.name });
+        const result = await runComponentDeploy(
           component,
           { env: options.env, component: component.name, vars: options.vars },
           registry,
           componentOutputs,
-        ),
-      ),
+          onProgress,
+        );
+        onProgress?.({ type: "component-done", wave: waveNum, component: component.name, status: result.ok ? "ok" : "failed" });
+        return result;
+      }),
     );
     results.push(...waveResults);
     const failed = waveResults.find((r) => !r.ok);
+    onProgress?.({ type: "wave-done", wave: waveNum, status: failed ? "failed" : "ok" });
     if (failed) {
       failedComponent = failed.component;
       break waveLoop;
@@ -684,6 +750,7 @@ export async function runInterpretDriver(
   }
 
   const ok = failedComponent === undefined;
+  onProgress?.({ type: "run-done", status: ok ? "ok" : "failed" });
   const result: DriverRunResult = { order, waves, results, ok, failedComponent, componentOutputs };
   if (!ok) throw new DriverRunFailure(result);
   return result;

package/src/components/run-progress.ts

@@ -0,0 +1,117 @@
+/**
+ * Structured progress events for `chant run --components <sel> --progress-json`
+ * (behold roadmap M3: a consumer that renders live wave/phase/step progress
+ * instead of tailing raw logs).
+ *
+ * This is purely additive observation over the interpret driver's existing
+ * wave -> component -> phase -> step execution loop (./driver.ts): an
+ * optional `onProgress` callback, threaded through
+ * `runInterpretDriver`/`runComponentDeploy`/`runPhase` (and the CLI's
+ * single-component path, ./cli-support.ts's `runComponents`), that never
+ * changes run ordering, gating, `onFailure`, rollback, or exit codes — it
+ * only reports what already happened, as it happens. See ./driver.ts's
+ * module doc for what actually executes; streaming progress on the *durable*
+ * (Temporal) path is a separate, later concern (Temporal already exposes
+ * durable run state via `chant run status`/`log`).
+ *
+ * `RunProgressEvent` is a discriminated union on `type`, one JSON object per
+ * NDJSON line (see `ndjsonProgressSink` below and
+ * ../cli/handlers/run.ts's `--progress-json` wiring).
+ */
+
+/** Terminal status for a wave/component/phase/run — mirrors DriverStepRecord's ok/fail split, collapsed to the two outcomes a consumer renders progress against. */
+export type RunProgressStatus = "ok" | "failed";
+
+/** The run is about to start. `waves` are the parallel-safe waves the run will attempt, in order (see resolveComponentGraph) — 1-based wave numbers in every other event index into this array. */
+export interface RunStartEvent {
+  type: "run-start";
+  waves: string[][];
+}
+
+/** A wave is about to start; its components may run concurrently (independent components share a wave). */
+export interface WaveStartEvent {
+  type: "wave-start";
+  /** 1-based wave number. */
+  wave: number;
+  components: string[];
+}
+
+/** A component within a wave is about to start its `deploy` composition. */
+export interface ComponentStartEvent {
+  type: "component-start";
+  wave: number;
+  component: string;
+}
+
+/** A named phase of a component's composition is about to run its steps. Emitted for nested (fan-out) phases too, keyed by the nested phase's own name. */
+export interface PhaseStartEvent {
+  type: "phase-start";
+  component: string;
+  phase: string;
+}
+
+/** A single capability step within a phase — one event when it starts, one when it settles. */
+export interface StepEvent {
+  type: "step";
+  component: string;
+  phase: string;
+  step: string;
+  status: "running" | "ok" | "failed";
+  /** Present only alongside `status: "failed"`, when the capability threw. */
+  error?: string;
+}
+
+/** A phase finished — `ok` if every step in it succeeded, `failed` if any step failed (the phase's remaining steps were skipped, per the driver's fail-fast-within-a-phase semantics). */
+export interface PhaseDoneEvent {
+  type: "phase-done";
+  component: string;
+  phase: string;
+  status: RunProgressStatus;
+}
+
+/** A component's `deploy` composition finished (after any saga rollback + component-level `rollback` phases the driver ran on failure). */
+export interface ComponentDoneEvent {
+  type: "component-done";
+  wave: number;
+  component: string;
+  status: RunProgressStatus;
+}
+
+/** A wave finished — `failed` if any component in it failed, which also stops the run before any later wave starts. */
+export interface WaveDoneEvent {
+  type: "wave-done";
+  wave: number;
+  status: RunProgressStatus;
+}
+
+/** The run finished. Mirrors the driver's own terminal `DriverRunResult.ok` / exit code. */
+export interface RunDoneEvent {
+  type: "run-done";
+  status: RunProgressStatus;
+}
+
+export type RunProgressEvent =
+  | RunStartEvent
+  | WaveStartEvent
+  | ComponentStartEvent
+  | PhaseStartEvent
+  | StepEvent
+  | PhaseDoneEvent
+  | ComponentDoneEvent
+  | WaveDoneEvent
+  | RunDoneEvent;
+
+/** A sink that receives progress events as they occur. The driver only ever calls this — it never writes to a stream directly, so it stays testable without stdout. */
+export type RunProgressSink = (event: RunProgressEvent) => void;
+
+/**
+ * Build a sink that writes `JSON.stringify(event) + "\n"` to `write` (default:
+ * `process.stdout.write`), one line per event, as they happen — the
+ * `--progress-json` CLI wiring's sink (../cli/handlers/run.ts). Kept separate
+ * from `driver-output.ts`'s end-of-run renderers: this emits *during* the
+ * run, one line at a time; `renderDriverJson`/`renderDriverHuman` render the
+ * completed `DriverRunResult` once, after the run finishes.
+ */
+export function ndjsonProgressSink(write: (chunk: string) => void = (s) => void process.stdout.write(s)): RunProgressSink {
+  return (event) => write(JSON.stringify(event) + "\n");
+}