@intentius/chant 0.18.28 → 0.18.30

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");
+}

package/src/lifecycle/status.test.ts

@@ -135,6 +135,29 @@ describe("status", () => {
       expect(rows[0].reconciliation).toBe("drifted");
     });
 
+    test("surfaces machine-readable live + stack status when observed (#57 hardening)", () => {
+      const liveEvidence = new Map<string, LiveComponentEvidence>([
+        ["search-service", { live: true, ownership: "owned", stack: { name: "app-prod-search", status: "CREATE_COMPLETE", healthy: true } }],
+      ]);
+      const rows = reconcileStatus("prod", [record()], { liveEvidence });
+      expect(rows[0].live).toBe(true);
+      expect(rows[0].stack).toEqual({ name: "app-prod-search", status: "CREATE_COMPLETE", healthy: true });
+    });
+
+    test("live is false (never undefined) under --live when a component's stack is absent", () => {
+      const liveEvidence = new Map<string, LiveComponentEvidence>([
+        ["search-service", { live: false }],
+      ]);
+      const rows = reconcileStatus("prod", [record()], { liveEvidence });
+      expect(rows[0].live).toBe(false);
+    });
+
+    test("live is absent (not queried) when no liveEvidence is passed", () => {
+      const rows = reconcileStatus("prod", [record()]);
+      expect(rows[0].live).toBeUndefined();
+      expect(rows[0].stack).toBeUndefined();
+    });
+
     test("recorded but nothing live -> stale", () => {
       const liveEvidence = new Map<string, LiveComponentEvidence>();
       const rows = reconcileStatus("prod", [record()], { liveEvidence });