@intentius/chant 0.124.13 → 0.124.15

package/dist/components/driver.js

@@ -0,0 +1,728 @@
+/**
+ * Thin interpret driver — Phase 1 (#556), saga rollback hardened in Phase 4
+ * (#565, epic #551).
+ *
+ * One generic orchestrator that runs an arbitrary set of components on the
+ * local in-process executor: it orders components by `dependsOn` (reusing the
+ * same Kahn-layering approach `computeStackGraph` uses for `chant graph
+ * --stacks`, see ../build.ts), then for each component in order runs its
+ * `deploy` composition by dispatching every step to the `CapabilityRegistry`
+ * by `kind`. It resolves the three wiring reference forms from
+ * component.schema.json (`@Phase.field` prior-step references,
+ * `@<component>.publish.<field>` cross-component artifact references, and
+ * passes through `$env.*`/`stackOutput` values as opaque env config), runs
+ * `parallel` phases concurrently, decides a `gate` against the gate ledger
+ * (#2119 — the same `../op/gate.ts` the Op executor uses, so `chant run
+ * --components` and `chant run <op>` can never disagree about what a gate
+ * means), and on terminal failure unwinds every executed step in reverse via
+ * that step's capability `rollback`, then runs `onFailure` phases in reverse
+ * order (best-effort), mirroring the Op local executor's saga semantics.
+ *
+ * A gate nobody has approved is not a failure: the component stops there with
+ * status `gated`, the pending fact is on the ledger, and no rollback and no
+ * `onFailure` phase runs — nothing failed and the steps that did run are the
+ * steps the author meant to run before the approval. The next run re-reads the
+ * ledger and continues past the gate if `chant approve` has answered it.
+ *
+ * A step whose capability declares no `rollback` is never silently passed
+ * over during unwind: it gets a `"rollback-opted-out"` record (see
+ * `rollbackExecuted`), carrying the step's `noRollback` reason when the
+ * composition declared one. This mirrors, at run time, the opt-out the
+ * COMP003 lint rule (../lint/rules/comp/comp003-mutating-no-rollback.ts)
+ * already requires at author time — the driver reports the same fact the
+ * lint rule already made a component author state.
+ *
+ * This unwind runs entirely in-process: if the process crashes mid-rollback,
+ * nothing resumes it — there is no persisted run state to resume from (see
+ * docs/components/orchestration.mdx#rollback-comes-free). The *mechanism*
+ * (reverse-order unwind calling each capability's `rollback`) is
+ * capability-agnostic; *durable resume of a rollback already in progress*
+ * would be a hosting runtime's to offer, the same boundary that already
+ * applies to forward `onFailure` compensation on an Op.
+ *
+ * Contains zero per-component logic: nothing in this module branches on a
+ * component or capability `kind`/name. All behavior is either generic
+ * (ordering, phase/step dispatch, wiring resolution) or delegated to the
+ * `CapabilityRegistry` the caller supplies.
+ */
+import { topoSort } from "../codegen/topo-sort.js";
+import { kahnLayers } from "./layers.js";
+import { evaluateGate, gitGateLedgerPort } from "../op/gate.js";
+import { gateName } from "../op/gate-name.js";
+import { componentPlanDigest } from "./gate-plan.js";
+import { isPromotedArtifact } from "./auto-release.js";
+function isGateStep(step) {
+    return step.kind === "gate";
+}
+function isPhaseStep(step) {
+    return typeof step.phase === "string" && Array.isArray(step.steps);
+}
+// ── Errors ────────────────────────────────────────────────────────────────
+/** Thrown when a dependency cycle is found among `dependsOn` edges. */
+export class DependencyCycleError extends Error {
+    constructor(cycle) {
+        super(`dependency cycle among components: ${cycle.join(" -> ")}`);
+        this.cycle = cycle;
+        this.name = "DependencyCycleError";
+    }
+}
+/** Thrown when a component's `dependsOn` names a component not present in the run set. */
+export class UnknownDependencyError extends Error {
+    constructor(component, dependency) {
+        super(`component "${component}" depends on unknown component "${dependency}"`);
+        this.component = component;
+        this.dependency = dependency;
+        this.name = "UnknownDependencyError";
+    }
+}
+/** Thrown on terminal run failure; carries the partial run result for rendering/inspection. */
+export class DriverRunFailure extends Error {
+    constructor(result) {
+        super(`interpret run failed at component "${result.failedComponent ?? "unknown"}"`);
+        this.result = result;
+        this.name = "DriverRunFailure";
+    }
+}
+/**
+ * Resolve run order and parallel-safe waves from each component's `dependsOn`.
+ * Reuses the generic `topoSort` (../codegen/topo-sort.ts) for the flat order,
+ * and the same Kahn-layering approach `computeStackGraph` uses for `chant
+ * graph --stacks` (../build.ts) to additionally group independent components
+ * into waves. This is a plain string-graph algorithm — no lexicon/AttrRef
+ * machinery — since a component's `dependsOn` is already a flat name list.
+ */
+export function resolveComponentGraph(components) {
+    const byName = new Map(components.map((c) => [c.name, c]));
+    for (const c of components) {
+        for (const dep of c.dependsOn ?? []) {
+            if (!byName.has(dep))
+                throw new UnknownDependencyError(c.name, dep);
+        }
+    }
+    // Kahn layering (mirrors computeStackGraph's wave computation in ../build.ts):
+    // a component is ready once every dependency it names has already been placed.
+    // Computed first because it doubles as cycle detection: `topoSort` below is a
+    // plain DFS with no cycle guard, so it must only run once a cycle is ruled out.
+    const deps = new Map();
+    for (const c of components)
+        deps.set(c.name, new Set(c.dependsOn ?? []));
+    const layered = kahnLayers(deps);
+    if (layered.cycle)
+        throw new DependencyCycleError(layered.cycle);
+    const waves = layered.waves;
+    const order = topoSort(components, (c) => c.name, (c) => c.dependsOn ?? []).map((c) => c.name);
+    return { order, waves };
+}
+// ── Wiring resolution ─────────────────────────────────────────────────────
+const PRIOR_STEP_REF = /^@([A-Za-z0-9_ ]+)\.([A-Za-z0-9_.]+)$/;
+const COMPONENT_ARTIFACT_REF = /^@([a-z0-9]+(?:-[a-z0-9]+)*)\.publish\.(uri|digest|key)$/;
+/** Dot-path lookup, matching ../op/local-executor.ts's resolvePath. */
+function resolvePath(value, path) {
+    return path
+        .split(".")
+        .reduce((acc, key) => (acc == null ? acc : acc[key]), value);
+}
+/**
+ * Resolve one wiring value against already-produced outputs. Three reference
+ * forms, all resolved here rather than by any component-specific code:
+ *  - `@Phase.field` — a prior step's output within the same component, keyed
+ *    by phase name (`phaseOutputs`).
+ *  - `@<component>.publish.uri|digest|key` — another component's published
+ *    artifact output (`componentOutputs`), per composition-and-wiring.mdx.
+ *  - `{ stackOutput: { stack, name } }` — a cross-stack output; Phase 1 has no
+ *    cross-stack apply-order integration (out of scope per #556), so this
+ *    resolves via the same `componentOutputs` map keyed by `stack`/`name`,
+ *    letting tests and callers seed cross-stack values the same way as
+ *    artifact outputs. `$env.*` and plain literals pass through unchanged —
+ *    env resolution is the caller's `DeployContext.vars`, not the driver's.
+ */
+export function resolveWiring(value, phaseOutputs, componentOutputs) {
+    if (typeof value === "string") {
+        const priorStep = value.match(PRIOR_STEP_REF);
+        if (priorStep) {
+            const [, phaseName, field] = priorStep;
+            return resolvePath(phaseOutputs[phaseName], field);
+        }
+        const artifactRef = value.match(COMPONENT_ARTIFACT_REF);
+        if (artifactRef) {
+            const [, componentName, field] = artifactRef;
+            return resolvePath(componentOutputs[componentName]?.publish, field);
+        }
+        return value; // literal, or `$env.*` — left for the caller to resolve via DeployContext.
+    }
+    if (value && typeof value === "object" && "stackOutput" in value) {
+        const { stack, name } = value.stackOutput;
+        return resolvePath(componentOutputs[stack], name);
+    }
+    return value;
+}
+/**
+ * Deep-walk an object, resolving every string/stackOutput wiring value found.
+ * Arrays and nested objects are walked too.
+ *
+ * Exported (not just used internally) so a hosting runtime that runs steps
+ * out of process can resolve a step's wiring the same way — the orchestrator
+ * only accumulates `phaseOutputs`/`componentOutputs` and passes them through;
+ * resolution logic stays in one place so local and hosted execution can never
+ * silently diverge.
+ */
+export function resolveStepInput(input, phaseOutputs, componentOutputs) {
+    const walk = (value) => {
+        if (typeof value === "string")
+            return resolveWiring(value, phaseOutputs, componentOutputs);
+        if (Array.isArray(value))
+            return value.map(walk);
+        if (value && typeof value === "object") {
+            if ("stackOutput" in value)
+                return resolveWiring(value, phaseOutputs, componentOutputs);
+            const out = {};
+            for (const [k, v] of Object.entries(value))
+                out[k] = walk(v);
+            return out;
+        }
+        return value;
+    };
+    return walk(input);
+}
+class StepFailure extends Error {
+    constructor(records, executed) {
+        super("step failed");
+        this.records = records;
+        this.executed = executed;
+        this.name = "StepFailure";
+    }
+}
+/** Internal: a phase stopped at an unapproved gate (#2119). Carries what ran before it, so the records survive; not a failure, so no unwind follows. */
+class GateStop extends Error {
+    constructor(records, executed, pending, 
+    /** Whether this run's own append reached the remote — see {@link DriverComponentResult.gatePushed} (#2310). */
+    pushed, pushWarning, 
+    /** Set when an approval stands for this gate but not for this plan (#2574). */
+    mismatch) {
+        super(`gate "${pending.gate}" is pending approval`);
+        this.records = records;
+        this.executed = executed;
+        this.pending = pending;
+        this.pushed = pushed;
+        this.pushWarning = pushWarning;
+        this.mismatch = mismatch;
+        this.name = "GateStop";
+    }
+}
+/** A result status as the progress stream spells it — the only difference is `fail` vs `failed`, which the two vocabularies have always disagreed on. */
+function progressStatus(status) {
+    return status === "fail" ? "failed" : status;
+}
+/** Run a single capability step. Never throws for a capability-run failure; returns a fail record instead. */
+async function runCapabilityStep(step, phaseName, ctx, registry, phaseOutputs, componentOutputs) {
+    const { kind, ...rest } = step;
+    const resolvedInput = resolveStepInput(rest, phaseOutputs, componentOutputs);
+    const start = Date.now();
+    try {
+        const capability = registry.resolve(kind);
+        const output = await capability.run(ctx, resolvedInput);
+        return {
+            record: {
+                component: ctx.component,
+                phase: phaseName,
+                kind,
+                status: "ok",
+                durationMs: Date.now() - start,
+                output,
+            },
+            resolvedInput,
+            output,
+        };
+    }
+    catch (err) {
+        return {
+            record: {
+                component: ctx.component,
+                phase: phaseName,
+                kind,
+                status: "fail",
+                durationMs: Date.now() - start,
+                error: errMessage(err),
+            },
+            resolvedInput,
+        };
+    }
+}
+/**
+ * Run a phase's steps. A step may be a `Gate` (decided against the gate
+ * ledger, in authored order — a resolution newer than the gate's newest
+ * pending fact lets it pass carrying the approver, anything else records the
+ * fact and stops the component) or a nested `Phase` (a fan-out unit; recursed
+ * into, 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 — and
+ * as there, a gate in a parallel phase is decided before the fan-out, since a
+ * gate is a read of the ledger rather than work, and starting activities a
+ * pending gate is about to strand defeats the point of stopping at it.
+ *
+ * `onProgress`, when supplied, is called with a `phase-start` event before any
+ * step runs, a `step` event around each capability invocation (`"running"`
+ * then `"ok"`/`"failed"`), and a `phase-done` event once the phase settles —
+ * purely additive observation, never consulted for control flow. Recursion
+ * into a nested fan-out phase passes the same callback through, so a nested
+ * phase's events use its own name. Left `undefined` by every caller that
+ * doesn't opt into `--progress-json` (see ./run-progress.ts), in which case
+ * every `onProgress?.(...)` call below is a no-op and behavior is unchanged.
+ */
+async function runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs, gates, onProgress) {
+    /** Decide this phase's gates against the ledger, in authored order, before any of its work starts. Throws `GateStop` at the first one nobody has approved. */
+    const decideGates = async () => {
+        const gateRecords = [];
+        for (const gate of phaseDef.steps.filter(isGateStep)) {
+            const start = Date.now();
+            const check = await evaluateGate(gates.port, {
+                op: ctx.component,
+                gate: gateName(gate),
+                // #2574: an approval counts only for this environment and this plan.
+                environment: ctx.env,
+                ...(gates.planDigest !== undefined ? { planDigest: gates.planDigest } : {}),
+                ...(gate.description ? { description: gate.description } : {}),
+                ...(gate.timeout ? { timeout: gate.timeout } : {}),
+                ...(gates.now ? { now: gates.now } : {}),
+            });
+            const base = { component: ctx.component, phase: phaseDef.phase, kind: `gate:${gateName(gate)}` };
+            if (!check.satisfied) {
+                gateRecords.push({ ...base, status: "skipped", durationMs: Date.now() - start });
+                for (const skipped of phaseDef.steps.filter((s) => !isGateStep(s))) {
+                    gateRecords.push(skippedRecord(skipped));
+                }
+                throw new GateStop(gateRecords, [], check.pending, check.pushed, check.pushWarning, check.mismatch);
+            }
+            gateRecords.push({
+                ...base,
+                status: "ok",
+                durationMs: Date.now() - start,
+                approval: {
+                    gate: gateName(gate),
+                    resolvedBy: check.resolution.resolvedBy,
+                    timestamp: check.resolution.timestamp,
+                    ...(check.resolution.url ? { url: check.resolution.url } : {}),
+                },
+            });
+        }
+        return gateRecords;
+    };
+    const entries = phaseDef.steps.filter((s) => !isGateStep(s));
+    const runEntry = async (entry) => {
+        if (isPhaseStep(entry)) {
+            try {
+                const nested = await runPhase(entry, ctx, registry, phaseOutputs, componentOutputs, gates, onProgress);
+                return { ...nested, failed: false };
+            }
+            catch (err) {
+                if (err instanceof StepFailure)
+                    return { records: err.records, executed: err.executed, failed: true };
+                // A nested fan-out phase's gate stops the whole component, but the
+                // records it produced before the gate still belong in the run.
+                if (err instanceof GateStop) {
+                    return {
+                        records: err.records,
+                        executed: err.executed,
+                        failed: false,
+                        pending: err.pending,
+                        pushed: err.pushed,
+                        pushWarning: err.pushWarning,
+                        mismatch: err.mismatch,
+                    };
+                }
+                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, ctx, registry, 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 };
+            // The release's service.version is the digest a later deploy step stamps (#3061): the
+            // last artifact this component promoted, the same one auto-release records.
+            if (ctx.release && isPromotedArtifact(output) && typeof output.digest === "string" && output.digest !== "") {
+                ctx.release.version = output.digest;
+            }
+        }
+        return {
+            records: [record],
+            executed: record.status === "ok" ? [{ step: entry, resolvedInput, phaseName: phaseDef.phase, output }] : [],
+            failed: record.status === "fail",
+        };
+    };
+    const skippedRecord = (entry) => ({
+        component: ctx.component,
+        phase: phaseDef.phase,
+        kind: isPhaseStep(entry) ? entry.phase : entry.kind,
+        status: "skipped",
+        durationMs: 0,
+    });
+    const runEntries = async () => {
+        const gateRecords = await decideGates();
+        if (phaseDef.parallel) {
+            const results = await Promise.all(entries.map(runEntry));
+            const records = gateRecords.concat(results.flatMap((r) => r.records));
+            const executed = results.flatMap((r) => r.executed);
+            const withPending = results.find((r) => r.pending);
+            if (withPending?.pending) {
+                throw new GateStop(records, executed, withPending.pending, withPending.pushed, withPending.pushWarning, withPending.mismatch);
+            }
+            if (results.some((r) => r.failed))
+                throw new StepFailure(records, executed);
+            return { records, executed };
+        }
+        const records = [...gateRecords];
+        const executed = [];
+        for (let i = 0; i < entries.length; i++) {
+            const result = await runEntry(entries[i]);
+            records.push(...result.records);
+            executed.push(...result.executed);
+            if (result.pending) {
+                for (const skipped of entries.slice(i + 1))
+                    records.push(skippedRecord(skipped));
+                throw new GateStop(records, executed, result.pending, result.pushed, result.pushWarning, result.mismatch);
+            }
+            if (result.failed) {
+                for (const skipped of entries.slice(i + 1))
+                    records.push(skippedRecord(skipped));
+                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 GateStop) {
+            onProgress?.({ type: "phase-done", component: ctx.component, phase: phaseDef.phase, status: "gated" });
+        }
+        else if (err instanceof StepFailure) {
+            onProgress?.({ type: "phase-done", component: ctx.component, phase: phaseDef.phase, status: "failed" });
+        }
+        throw err;
+    }
+}
+/**
+ * Roll back every executed step in reverse order via its capability's
+ * `rollback`, if declared. Best-effort: a rollback failure is recorded but
+ * does not stop the unwind.
+ *
+ * A step whose capability declares no `rollback` is not silently passed over:
+ * it gets its own `"rollback-opted-out"` record, carrying the step's
+ * `noRollback` reason when the composition declared one (the same opt-out
+ * property COMP003 lint requires at author time — see
+ * ../lint/rules/comp/comp003-mutating-no-rollback.ts) or a generic fallback
+ * message otherwise. This is decided purely by whether `capability.rollback`
+ * exists — never by the step's `kind` or the component's name — so it stays
+ * capability-agnostic like the rest of this module.
+ */
+async function rollbackExecuted(executed, ctx, registry) {
+    const records = [];
+    for (const { step, resolvedInput, phaseName, output } of [...executed].reverse()) {
+        const start = Date.now();
+        try {
+            const capability = registry.resolve(step.kind);
+            if (!capability.rollback) {
+                const reason = typeof step.noRollback === "string" ? step.noRollback : undefined;
+                records.push({
+                    component: ctx.component,
+                    phase: phaseName,
+                    kind: step.kind,
+                    status: "rollback-opted-out",
+                    durationMs: Date.now() - start,
+                    error: reason ?? `capability "${step.kind}" declares no rollback and the step has no "noRollback" reason`,
+                });
+                continue;
+            }
+            await capability.rollback(ctx, resolvedInput, output);
+            records.push({
+                component: ctx.component,
+                phase: phaseName,
+                kind: step.kind,
+                status: "rolled-back",
+                durationMs: Date.now() - start,
+            });
+        }
+        catch (err) {
+            records.push({
+                component: ctx.component,
+                phase: phaseName,
+                kind: step.kind,
+                status: "fail",
+                durationMs: Date.now() - start,
+                error: errMessage(err),
+            });
+        }
+    }
+    return records;
+}
+// ── Per-component deploy ─────────────────────────────────────────────────
+/**
+ * Run one component's `deploy` composition. On terminal failure: unwind every
+ * executed step in reverse via its capability's `rollback` (saga
+ * compensation), then run the component's declared `rollback` phases in
+ * reverse order (best-effort), matching ../op/local-executor.ts's `onFailure`
+ * 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, ctx, registry, componentOutputs, onProgress, gateContext = { port: gitGateLedgerPort() }) {
+    // Each component tracks its own release: a digest one component promoted never stamps another's deploy.
+    if (ctx.release)
+        ctx = { ...ctx, release: { ...ctx.release } };
+    const phaseOutputs = {};
+    // #2574: every gate this component reaches binds its approval to this
+    // environment and this composition, so an approval for staging or for last
+    // week's deploy cannot pass it.
+    const release = gateContext.releases?.get(component.name);
+    // A promote or rollback deploys a recorded digest without publishing one (#2574); that digest is the release's version.
+    if (ctx.release && release !== undefined && ctx.release.version === undefined)
+        ctx.release.version = release;
+    const gates = {
+        ...gateContext,
+        planDigest: componentPlanDigest({
+            environment: ctx.env,
+            component,
+            ...(ctx.vars ? { vars: ctx.vars } : {}),
+            ...(release !== undefined ? { release } : {}),
+        }),
+    };
+    const records = [];
+    const allExecuted = [];
+    try {
+        for (const phaseDef of component.deploy) {
+            const result = await runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs, gates, onProgress);
+            records.push(...result.records);
+            allExecuted.push(...result.executed);
+        }
+    }
+    catch (err) {
+        // A pending gate stops the component where it stands (#2119): no saga
+        // unwind and no `rollback` phase. The steps before the gate ran on
+        // purpose and are meant to survive the wait for an approval — undoing
+        // them would make every gated run a no-op with a rollback attached.
+        if (err instanceof GateStop) {
+            records.push(...err.records);
+            return {
+                component: component.name,
+                ok: false,
+                status: "gated",
+                records,
+                gate: err.pending,
+                ...(err.pushed !== undefined ? { gatePushed: err.pushed } : {}),
+                ...(err.pushWarning ? { gatePushWarning: err.pushWarning } : {}),
+                ...(err.mismatch ? { gateMismatch: err.mismatch } : {}),
+            };
+        }
+        if (err instanceof StepFailure) {
+            records.push(...err.records);
+            allExecuted.push(...err.executed);
+        }
+        else {
+            throw err;
+        }
+        records.push(...(await rollbackExecuted(allExecuted, ctx, registry)));
+        for (const phaseDef of [...(component.rollback ?? [])].reverse()) {
+            try {
+                const result = await runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs, gates, onProgress);
+                records.push(...result.records);
+            }
+            catch (compErr) {
+                if (compErr instanceof StepFailure || compErr instanceof GateStop)
+                    records.push(...compErr.records);
+                else
+                    throw compErr;
+            }
+        }
+        return { component: component.name, ok: false, status: "fail", records };
+    }
+    // Publish-family and stack outputs become this component's entry in
+    // `componentOutputs` — through the same exported accumulator a hosted
+    // runtime calls (#700), so local and hosted runs can never diverge on what
+    // downstream references see.
+    accumulateComponentOutputs(componentOutputs, component.name, phaseOutputs);
+    return { component: component.name, ok: true, status: "ok", records };
+}
+/**
+ * Collect the cross-component outputs one finished component exposes to its
+ * downstream consumers, from every phase output it produced:
+ *
+ *   - publish-family outputs (publish-image / publish-artifact /
+ *     load-image-on-host all return at least one of uri/digest/key — see
+ *     ./verbs/publish.ts) are namespaced under `publish`, so downstream
+ *     `@<name>.publish.*` references resolve;
+ *   - stack outputs from an apply step (cfn-deploy returns
+ *     `CfnDeployOutput.outputs`) are merged at the top level, peer to
+ *     `publish`, so `resolveWiring`'s stackOutput branch —
+ *     `resolvePath(componentOutputs[stack], name)` — finds each output by
+ *     name (the cross-stack apply-order integration deferred in #556, closed
+ *     in #699). The entry is keyed by the component's own name, which by
+ *     convention is the stack name a `stackOutput` reference targets (see the
+ *     pilots and composition-and-wiring.mdx).
+ *
+ * Both halves are generic by output *shape*, not by capability `kind`, keeping
+ * the driver free of per-capability branching. Returns `undefined` when the
+ * component exposed nothing.
+ *
+ * Exported, like `resolveStepInput`, so a hosting runtime accumulates outputs
+ * via this exact function rather than re-deriving it (#700). The resolver and the
+ * accumulator are the two halves of one contract; sharing only the resolver
+ * is how the cross-stack gap #699 closed locally could reopen durably.
+ */
+export function collectComponentOutputs(phaseOutputs) {
+    const publishOutput = findPublishOutput(phaseOutputs);
+    const stackOutputs = findStackOutputs(phaseOutputs);
+    if (!publishOutput && !stackOutputs)
+        return undefined;
+    return { ...(stackOutputs ?? {}), ...(publishOutput ? { publish: publishOutput } : {}) };
+}
+/**
+ * Record a finished component's outputs (`collectComponentOutputs`) into the
+ * shared `componentOutputs` map under the component's own name, merging over
+ * any seeded entry (`--seed-outputs`, or a parent orchestrator's
+ * thread-through). Mutates and returns `componentOutputs`, so an out-of-process
+ * step can hand the updated map back over a JSON boundary — every value in it
+ * is plain result data, so the map is serializable by construction. A no-op
+ * when the component exposed nothing.
+ */
+export function accumulateComponentOutputs(componentOutputs, componentName, phaseOutputs) {
+    const collected = collectComponentOutputs(phaseOutputs);
+    if (collected) {
+        componentOutputs[componentName] = { ...componentOutputs[componentName], ...collected };
+    }
+    return componentOutputs;
+}
+/**
+ * Find the output of the last step that looks like a publish result (carries
+ * `uri`, `digest`, or `key`) across every phase this component ran, so
+ * `collectComponentOutputs` can populate `@<component>.publish.*` for a
+ * downstream consumer.
+ */
+function findPublishOutput(phaseOutputs) {
+    let found;
+    for (const output of Object.values(phaseOutputs)) {
+        if (output && ("uri" in output || "digest" in output || "key" in output)) {
+            found = { ...found, ...output };
+        }
+    }
+    return found;
+}
+/**
+ * Find the stack `outputs` map produced by an apply-style step (cfn-deploy
+ * returns `CfnDeployOutput.outputs`) across every phase this component ran, so
+ * a deployed stack's outputs can seed downstream `stackOutput()` resolution.
+ */
+function findStackOutputs(phaseOutputs) {
+    let found;
+    for (const output of Object.values(phaseOutputs)) {
+        const outputs = output?.outputs;
+        if (outputs && typeof outputs === "object" && !Array.isArray(outputs)) {
+            found = { ...found, ...outputs };
+        }
+    }
+    return found;
+}
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Run a set of components to completion on the local in-process executor:
+ * resolve dependency order and parallel-safe waves from `dependsOn`, then run
+ * each wave's components (independent components within a wave run
+ * concurrently; components across waves run in wave order), dispatching
+ * every step to `registry` by `kind`. Stops the whole run at the first failed
+ * component (after that component's own saga rollback completes), returning
+ * a result with `ok: false`; throws `DriverRunFailure` carrying that result
+ * so callers can choose to inspect or propagate it.
+ *
+ * A component that stops at an unapproved gate (#2119) ends the run the same
+ * way, with `status: "gated"` and the pending fact on `gate` — but it is
+ * *returned*, never thrown, because nothing failed. Downstream waves do not
+ * run: a gate is the author saying a human decides before the rest happens.
+ *
+ * Zero per-component logic: this function and everything it calls dispatches
+ * purely on the generic `Component`/`Phase`/`Step` shapes and the registry —
+ * no branch anywhere names a specific component or capability.
+ */
+/** A component's `DeployContext` for a run: its env, vars and, when the caller knows it, its release. */
+export function deployContext(options, component) {
+    const release = options.releaseIdentity?.(component);
+    return { env: options.env, component, ...(options.vars ? { vars: options.vars } : {}), ...(release ? { release: { ...release } } : {}) };
+}
+export async function runInterpretDriver(components, registry, options) {
+    const { order, waves } = resolveComponentGraph(components);
+    const byName = new Map(components.map((c) => [c.name, c]));
+    const componentOutputs = { ...(options.componentOutputs ?? {}) };
+    const { onProgress } = options;
+    const gates = {
+        port: options.gates ?? gitGateLedgerPort(),
+        ...(options.now ? { now: options.now } : {}),
+        ...(options.releases ? { releases: options.releases } : {}),
+    };
+    onProgress?.({ type: "run-start", waves });
+    const results = [];
+    let failedComponent;
+    let gated;
+    waveLoop: for (const [waveIndex, wave] of waves.entries()) {
+        const waveNum = waveIndex + 1;
+        onProgress?.({ type: "wave-start", wave: waveNum, components: wave });
+        const waveComponents = wave.map((name) => byName.get(name));
+        const waveResults = await Promise.all(waveComponents.map(async (component) => {
+            onProgress?.({ type: "component-start", wave: waveNum, component: component.name });
+            const result = await runComponentDeploy(component, deployContext(options, component.name), registry, componentOutputs, onProgress, gates);
+            onProgress?.({ type: "component-done", wave: waveNum, component: component.name, status: progressStatus(result.status) });
+            return result;
+        }));
+        results.push(...waveResults);
+        const stopped = waveResults.find((r) => r.status !== "ok");
+        onProgress?.({ type: "wave-done", wave: waveNum, status: progressStatus(stopped?.status ?? "ok") });
+        if (stopped) {
+            // A failure in the same wave outranks a gate: something is actually
+            // broken, and reporting the run as "waiting on a human" would hide it.
+            const failure = waveResults.find((r) => r.status === "fail");
+            if (failure)
+                failedComponent = failure.component;
+            else
+                gated = stopped;
+            break waveLoop;
+        }
+    }
+    const status = failedComponent ? "fail" : gated ? "gated" : "ok";
+    const ok = status === "ok";
+    onProgress?.({ type: "run-done", status: progressStatus(status) });
+    const result = {
+        order, waves, results, ok, status, failedComponent, componentOutputs,
+        ...(gated
+            ? {
+                gatedComponent: gated.component,
+                gate: gated.gate,
+                ...(gated.gatePushed !== undefined ? { gatePushed: gated.gatePushed } : {}),
+                ...(gated.gatePushWarning ? { gatePushWarning: gated.gatePushWarning } : {}),
+                ...(gated.gateMismatch ? { gateMismatch: gated.gateMismatch } : {}),
+            }
+            : {}),
+    };
+    if (status === "fail")
+        throw new DriverRunFailure(result);
+    return result;
+}