@intentius/chant 0.124.13 → 0.124.15

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

@@ -0,0 +1,165 @@
+/**
+ * Renderers for a derived fan-out (#2420) — the printed derivation #2417's
+ * proof list asks for and nothing produced.
+ *
+ * `./driver-output.ts` is the precedent and the shape is deliberately the
+ * same: a human renderer that logs to stderr, a JSON renderer that owns
+ * stdout and writes nothing else, both over the types the model already
+ * returns (`./fan-out.ts`'s `FanOutPlan`, `./fan-out-run.ts`'s
+ * `FanOutRunResult`). No new fields are computed here. A renderer that had to
+ * derive something to print it would be deriving it twice.
+ *
+ * ## What gets printed, and why each line is not optional
+ *
+ * A fan-out that applies the right components without saying why it picked
+ * them reads exactly like one that fanned out to everything, which is the
+ * failure #2417's precision decision exists to prevent. So:
+ *
+ * - **the waves**, because the claim is that the order was derived from the
+ *   source rather than declared, and a flat list cannot show that
+ * - **every component that is not running, with its reason** — `unaffected`,
+ *   `indeterminate`, `already-applied`, `blocked` — because "absent from the
+ *   list" and "deliberately held back" look identical otherwise
+ * - **`indeterminate` on its own line**, because it is the third outcome and a
+ *   two-state render would quietly drop it into one of the other two
+ * - **`seeds`**, because those values are being taken on trust from a run that
+ *   happened earlier and somewhere else
+ * - **the `digest`, verbatim and unabbreviated**, because it is the string
+ *   `chant approve --plan` takes. Truncating it for width would make the line
+ *   unusable for the one job it has.
+ */
+import { waveGateName } from "../gated-waves.js";
+const stderr = (line) => process.stderr.write(line + "\n");
+const stdout = (line) => process.stdout.write(line + "\n");
+/** `unaffected` → `unaffected`; `blocked` also names the failure it was reached from. */
+function reasonOf(skip) {
+    return skip.reason === "blocked" && skip.blockedBy
+        ? `blocked by "${skip.blockedBy}"`
+        : skip.reason;
+}
+/** Longest component name in `skips`, for a column that lines up without padding every render. */
+function widestName(skips) {
+    return skips.reduce((w, s) => Math.max(w, s.component.length), 0);
+}
+/**
+ * The derivation itself: the waves, what is not running and why, what is
+ * seeded, and the digest an approval binds to.
+ *
+ * This is the whole output of a plan-only invocation and the header of a run,
+ * so it is one function rather than two nearly identical ones.
+ */
+export function renderFanOutPlan(plan, options = {}) {
+    const write = options.write ?? stderr;
+    // Three outcomes, never two (#2417). The counts come first because they are
+    // the claim the rest of the block substantiates.
+    const unaffected = plan.skipped.filter((s) => s.reason === "unaffected").length;
+    const held = plan.skipped.filter((s) => s.reason === "already-applied" || s.reason === "blocked").length;
+    write(`fan-out: ${plan.order.length} selected, ${unaffected} unaffected, ` +
+        `${plan.indeterminate.length} indeterminate` +
+        (held > 0 ? `, ${held} held back` : ""));
+    if (plan.order.length === 0) {
+        write("  nothing to run");
+    }
+    else {
+        for (const [index, wave] of plan.waves.entries()) {
+            const gated = options.waveGate ? `  (gate ${waveGateName(options.waveGate.gate, index + 1)})` : "";
+            write(`  wave ${index + 1}: ${wave.join(", ")}${gated}`);
+        }
+    }
+    if (plan.seeds.length > 0) {
+        write(`  seeded from an earlier run: ${plan.seeds.join(", ")}`);
+    }
+    if (plan.skipped.length > 0) {
+        write(`  not running (${plan.skipped.length}):`);
+        const width = widestName(plan.skipped);
+        for (const skip of plan.skipped) {
+            write(`    ${skip.component.padEnd(width)}  ${reasonOf(skip)}`);
+        }
+    }
+    if (plan.indeterminate.length > 0) {
+        // Named separately from the `indeterminate` rows above because the two say
+        // different things: those rows are "not selected", this line is "a source
+        // diff could not judge it and the walk never reached it either", which is
+        // the one outcome nobody should read as a decision.
+        write(`  a source diff cannot judge these, and the walk did not reach them: ` +
+            plan.indeterminate.join(", "));
+    }
+    // Verbatim: this is the string `chant approve --plan` takes.
+    write(`  plan: ${plan.digest}`);
+    if (options.gate) {
+        write(`  approve: chant approve ${options.gate.op} ${options.gate.gate} --plan ${plan.digest}`);
+    }
+    if (options.waveGate) {
+        write(`  each wave is planned when it is reached, and its gate binds that wave's set digest`);
+    }
+}
+/** One line per wave a gated-wave run reached (#3049): its digest, members and where it got to. */
+function renderWaves(waves, write) {
+    for (const wave of waves) {
+        const state = wave.status === "applied"
+            ? `applied, approved by ${wave.approvedBy ?? "unknown"}`
+            : wave.status === "gated"
+                ? wave.approved
+                    ? "stopped: the set changed after it was approved"
+                    : "waiting for approval"
+                : "failed";
+        write(`wave ${wave.wave} (${wave.gate}): ${state}`);
+        if (wave.digest)
+            write(`  set digest: ${wave.digest}`);
+        for (const member of wave.members)
+            write(`    ${member.member}  ${member.planDigest}`);
+        if (wave.approved)
+            write(`  approved digest: ${wave.approved}`);
+        for (const f of wave.failed ?? [])
+            write(`  ${f.component} failed${f.error ? `: ${f.error}` : ""}`);
+    }
+}
+/**
+ * A dispatched fan-out: the derivation that ran, then what it did.
+ *
+ * `result.plan` is the plan as dispatched, so on a resume this prints the
+ * narrowed one, with everything an earlier attempt finished listed as
+ * `already-applied`. That is the point of printing the plan off the result
+ * rather than off whatever the caller derived.
+ */
+export function renderFanOutHuman(result, options = {}) {
+    const write = options.write ?? stderr;
+    renderFanOutPlan(result.plan, { ...options, write });
+    if (result.waves)
+        renderWaves(result.waves, write);
+    if (result.status === "gated" && result.waves) {
+        const at = result.waves[result.waves.length - 1];
+        write(`gated at wave ${at?.wave ?? "?"}: ${result.completed.length} applied before it, ` +
+            `nothing in it or after it ran.`);
+        if (result.gate?.expiresAt)
+            write(`  expires: ${result.gate.expiresAt}`);
+        return;
+    }
+    if (result.status === "gated") {
+        const gate = result.gate;
+        write(`gated: nothing ran. ${gate ? `Waiting on "${gate.gate}" on "${gate.op}".` : "Waiting on an approval."}`);
+        if (gate?.expiresAt)
+            write(`  expires: ${gate.expiresAt}`);
+        return;
+    }
+    if (result.completed.length > 0)
+        write(`applied: ${result.completed.join(", ")}`);
+    if (result.failed.length > 0)
+        write(`failed: ${result.failed.join(", ")}`);
+    for (const blocked of result.blocked) {
+        write(`  ${blocked.component}: ${reasonOf(blocked)}, so it never ran`);
+    }
+    const counts = `${result.completed.length} applied, ${result.failed.length} failed, ` +
+        `${result.blocked.length} blocked`;
+    write(result.status === "ok" ? `fan-out completed: ${counts}` : `fan-out failed: ${counts}`);
+}
+/**
+ * The plan or the run result as JSON on stdout, and nothing else on stdout.
+ *
+ * One function for both because the run result carries the plan under `plan`,
+ * so a consumer discriminates on that key rather than on a flag it was told
+ * about out of band.
+ */
+export function renderFanOutJson(payload, write = stdout) {
+    write(JSON.stringify(payload));
+}

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

@@ -0,0 +1,94 @@
+/**
+ * The fan-out attempt record (`--resume`, #2420, #2417, #3049): what an
+ * attempt left behind and what the next one reads.
+ *
+ * It lives here rather than in the CLI handler so a caller that runs a wave
+ * per CI job (#3183) reads and writes the same file without importing the
+ * command.
+ *
+ * The digest is stored alongside the progress because progress is only
+ * meaningful for the plan it was made against. A fan-out derived from different
+ * source is a different fan-out, and carrying "cluster-a already applied" into
+ * it would be a claim about work nobody did.
+ *
+ * `outputs` holds what each completed component exposed. A component left to
+ * run may read one of them through `stackOutput()`, and without the record the
+ * re-run would resolve that reference to nothing unless somebody supplied the
+ * value by hand with `--seed-outputs`.
+ *
+ * `waves`, for a gated-wave fan-out, holds one entry per wave reached: its set
+ * digest, its members, its gate and where it got to. A resumed attempt plans
+ * a wave afresh rather than trusting this, since the point of the gate is the
+ * plan now. The entries are for whoever reads the record, the plan report
+ * (#3349) among them.
+ *
+ * `carried` holds what a step asked to keep for its member (#3459). It rides
+ * in the record rather than beside it because the record is the one file a
+ * per-wave CI job hands to the next.
+ */
+import { dirname } from "node:path";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { readWaveRecords } from "../gated-waves.js";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isStringArray = (value) => Array.isArray(value) && value.every((v) => typeof v === "string");
+/** The `prApply` entry, when it has every field a resume needs. Anything else reads as no entry. */
+function readPrApplyRecord(value) {
+    if (!isRecord(value))
+        return undefined;
+    const { op, gate, head, digest, approvedBy, members, changeSet, planOutputs } = value;
+    if (typeof op !== "string" || typeof gate !== "string" || typeof head !== "string" || typeof digest !== "string")
+        return undefined;
+    if (!isStringArray(approvedBy) || !Array.isArray(members) || !members.every(isRecord))
+        return undefined;
+    if (!isRecord(changeSet) || changeSet.digest !== digest || !Array.isArray(changeSet.members) || !Array.isArray(changeSet.entries))
+        return undefined;
+    const outputs = {};
+    if (isRecord(planOutputs)) {
+        for (const [name, v] of Object.entries(planOutputs))
+            if (isRecord(v))
+                outputs[name] = v;
+    }
+    return {
+        op,
+        gate,
+        head,
+        digest,
+        approvedBy,
+        members: members,
+        changeSet: changeSet,
+        planOutputs: outputs,
+    };
+}
+/** Read an attempt record, or `undefined` when there is none yet. Throws on a file that is not JSON. */
+export function readFanOutAttempt(path) {
+    if (!existsSync(path))
+        return undefined;
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    const outputs = {};
+    if (isRecord(parsed.outputs)) {
+        for (const [name, value] of Object.entries(parsed.outputs))
+            if (isRecord(value))
+                outputs[name] = value;
+    }
+    const waves = readWaveRecords(parsed.waves);
+    const prApply = readPrApplyRecord(parsed.prApply);
+    return {
+        digest: typeof parsed.digest === "string" ? parsed.digest : "",
+        completed: Array.isArray(parsed.completed) ? parsed.completed.filter((n) => typeof n === "string") : [],
+        failed: Array.isArray(parsed.failed) ? parsed.failed.filter((n) => typeof n === "string") : [],
+        outputs,
+        ...(waves.length > 0 ? { waves } : {}),
+        ...(isRecord(parsed.carried) && Object.keys(parsed.carried).length > 0 ? { carried: parsed.carried } : {}),
+        ...(prApply ? { prApply } : {}),
+    };
+}
+/**
+ * Written through a temporary file and a rename, so a process killed during the
+ * write leaves the previous record whole rather than half a JSON document.
+ */
+export function writeFanOutAttempt(path, attempt) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, JSON.stringify(attempt, null, 2) + "\n");
+    renameSync(temporary, path);
+}

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

@@ -0,0 +1,373 @@
+/**
+ * Run a derived fan-out (#2417).
+ *
+ * `./fan-out.ts` decides who runs and in what order; this dispatches it. The
+ * two are separate because the deciding is worth testing without a cloud, and
+ * because the same plan is what one approval is bound to.
+ *
+ * ## Why not `runInterpretDriver`
+ *
+ * That runner stops the whole run at the first failed component, which is the
+ * right default for `chant run --components all`: there, the user asked for
+ * everything, and a failure means the estate is in a state nobody described.
+ *
+ * A fan-out is the case where that default throws away the point. The order was
+ * derived from the source, so a branch sharing no edge with the failure is
+ * *known* to be independent rather than assumed to be. Stopping it buys nothing
+ * and costs a second approval to finish. So this runner skips the failed
+ * component's subtree and lets the rest of the wave plan proceed.
+ *
+ * Neither runner's behaviour changes the other's: `runInterpretDriver` is
+ * untouched.
+ *
+ * ## One approval, not one per component
+ *
+ * The gate is evaluated once, before the first wave, bound to the plan's digest
+ * through the same `planDigest` mechanism #2300 gave gates. Twenty components
+ * behind one fan-out is one approval, and re-deriving the same fan-out does not
+ * expire it. A component's *own* authored gates still decide per component —
+ * this adds a gate over the set, it does not remove the ones inside it.
+ *
+ * ## Or one approval per wave
+ *
+ * `waveGate` (#3049) is the other mode. Each wave is planned once the waves
+ * before it applied, and its gate binds that wave's set digest
+ * (`../gated-waves.ts`). See {@link runGatedWaves}.
+ */
+import { deployContext, runComponentDeploy, } from "./driver.js";
+import { downstreamWithin, remainingFanOut } from "./fan-out.js";
+import { evaluateGate, gitGateLedgerPort } from "../op/gate.js";
+import { planWaveComponent } from "./wave-plan.js";
+import { waveGateName, waveSetDigest } from "../gated-waves.js";
+/** Thrown when `FanOutWaveGate.only` names a wave whose predecessors have not all applied. */
+export class EarlierWaveNotAppliedError extends Error {
+    constructor(wave, earlier, components) {
+        super(`wave ${wave} cannot run yet: wave ${earlier} has not applied (${components.join(", ")}). ` +
+            `Run wave ${earlier} first, with the same --resume record.`);
+        this.wave = wave;
+        this.earlier = earlier;
+        this.components = components;
+        this.name = "EarlierWaveNotAppliedError";
+    }
+}
+/**
+ * Dispatch a fan-out plan.
+ *
+ * Resolves rather than throws on a failed component: a fan-out's partial
+ * outcome is the interesting one, and the caller needs `completed` to resume.
+ */
+export async function runFanOut(plan, components, registry, options) {
+    const byName = new Map(components.map((c) => [c.name, c]));
+    const gates = {
+        port: options.gates ?? gitGateLedgerPort(),
+        ...(options.now ? { now: options.now } : {}),
+    };
+    const componentOutputs = { ...(options.componentOutputs ?? {}) };
+    // Resume first, so the gate is decided against the work that is actually left
+    // and a re-run does not re-approve. The digest is carried, not recomputed.
+    const active = options.progress ? remainingFanOut(plan, components, options.progress) : plan;
+    if (options.gate && options.waveGate) {
+        throw new Error("a fan-out takes one gate over the set or one gate per wave, not both");
+    }
+    if (options.waveGate && options.plans) {
+        throw new Error("a gated-wave fan-out plans each wave itself, so it takes no plans made beforehand");
+    }
+    if (options.waveGate) {
+        return runGatedWaves(plan, active, components, registry, options, options.waveGate, gates, componentOutputs);
+    }
+    if (options.gate) {
+        const check = await evaluateGate(gates.port, {
+            op: options.gate.op,
+            gate: options.gate.gate,
+            planDigest: active.digest,
+            ...(options.gate.description ? { description: options.gate.description } : {}),
+            ...(options.gate.timeout ? { timeout: options.gate.timeout } : {}),
+            ...(options.now ? { now: options.now } : {}),
+        });
+        if (!check.satisfied) {
+            // Nothing ran, so nothing is half-applied and there is nothing to
+            // compensate. A gate is a fact, not a failure.
+            return {
+                plan: active,
+                status: "gated",
+                results: [],
+                completed: [],
+                failed: [],
+                blocked: [],
+                componentOutputs,
+                gate: check.pending,
+            };
+        }
+    }
+    const results = [];
+    const completed = [];
+    const failed = [];
+    const blockedBy = new Map();
+    let gatedFact;
+    const inPlan = new Set(active.order);
+    /** Skip everything downstream of `root`, blaming `root` rather than the nearest edge. */
+    const markBlocked = (root) => {
+        for (const [component, by] of downstreamWithin(components, inPlan, [root])) {
+            if (blockedBy.has(component) || failed.includes(component))
+                continue;
+            blockedBy.set(component, by);
+        }
+    };
+    options.onProgress?.({ type: "run-start", waves: active.waves });
+    for (const [waveIndex, wave] of active.waves.entries()) {
+        const waveNum = waveIndex + 1;
+        // A component whose upstream failed in an earlier wave is not dispatched.
+        const runnable = wave.filter((name) => inPlan.has(name) && !blockedBy.has(name));
+        if (runnable.length === 0)
+            continue;
+        options.onProgress?.({ type: "wave-start", wave: waveNum, components: runnable });
+        const waveResults = await Promise.all(runnable.map(async (name) => {
+            options.onProgress?.({ type: "component-start", wave: waveNum, component: name });
+            const planned = options.plans?.[name];
+            const result = await runComponentDeploy(byName.get(name), { ...fanOutContext(options, name), ...(planned && Object.keys(planned).length > 0 ? { plans: planned } : {}) }, registry, componentOutputs, options.onProgress, gates);
+            options.onProgress?.({
+                type: "component-done",
+                wave: waveNum,
+                component: name,
+                status: result.status === "fail" ? "failed" : result.status,
+            });
+            options.onComponentSettled?.(result, componentOutputs[name]);
+            return result;
+        }));
+        results.push(...waveResults);
+        for (const result of waveResults) {
+            if (result.status === "ok") {
+                completed.push(result.component);
+                continue;
+            }
+            if (result.status === "fail") {
+                failed.push(result.component);
+                markBlocked(result.component);
+                continue;
+            }
+            // A component of its own stopped at one of its authored gates. Its
+            // dependents cannot run either, for the same reason a failure's cannot:
+            // the value they would read has not landed.
+            gatedFact ?? (gatedFact = result.gate);
+            markBlocked(result.component);
+        }
+        const waveFailed = waveResults.some((r) => r.status === "fail");
+        options.onProgress?.({
+            type: "wave-done",
+            wave: waveNum,
+            status: waveFailed ? "failed" : waveResults.some((r) => r.status === "gated") ? "gated" : "ok",
+        });
+    }
+    const blocked = [...blockedBy.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([component, by]) => ({ component, reason: "blocked", blockedBy: by }));
+    // A failure outranks a gate: something is actually broken, and reporting the
+    // run as "waiting on a human" would hide it. Same precedence the driver uses.
+    const status = failed.length > 0 ? "fail" : gatedFact ? "gated" : "ok";
+    options.onProgress?.({ type: "run-done", status: status === "fail" ? "failed" : status });
+    return {
+        plan: active,
+        status,
+        results,
+        completed: [...completed].sort(),
+        failed: [...failed].sort(),
+        blocked,
+        componentOutputs,
+        ...(gatedFact ? { gate: gatedFact } : {}),
+    };
+}
+/** The run's `deployContext`, with the carried state and the carry callback (#3459) when the caller gave them. */
+function fanOutContext(options, component) {
+    return {
+        ...deployContext(options, component),
+        ...(options.carried && Object.keys(options.carried).length > 0 ? { carried: options.carried } : {}),
+        ...(options.onCarry ? { carry: options.onCarry } : {}),
+    };
+}
+/** A plan failure as a component result, so it reads like any other failed component. */
+function planFailure(component, error) {
+    return {
+        component,
+        ok: false,
+        status: "fail",
+        records: [{ component, phase: "Plan", kind: "plan", status: "fail", durationMs: 0, error }],
+    };
+}
+/**
+ * The per-wave mode (#3049). Waves keep the numbers the derivation gave them,
+ * so on a resumed attempt wave 3 is still wave 3 and its gate, and the
+ * approval recorded for it, are the same ones.
+ *
+ * For each wave with work left: plan its components against the outputs
+ * earlier waves wrote, take the set digest of what was planned, and decide
+ * `waveGateName(gate, n)` against it. Approved, the wave runs, each
+ * component applying the plans its steps just made. Not approved, the run
+ * stops there with nothing in that wave or after it applied. An approval
+ * that stands for another digest (the set changed since someone approved
+ * it) is the same stop, and the record names both digests.
+ *
+ * A component that fails to plan or to apply blocks its own dependents and
+ * nothing else, as in the whole-set mode.
+ */
+async function runGatedWaves(plan, active, components, registry, options, waveGate, gates, componentOutputs) {
+    const byName = new Map(components.map((c) => [c.name, c]));
+    const left = new Set(active.order);
+    const planComponent = waveGate.planComponent ??
+        ((component, ctx, outputs) => planWaveComponent(component, registry, ctx, outputs));
+    const results = [];
+    const completed = [];
+    const failed = [];
+    const blockedBy = new Map();
+    const waves = [];
+    let gatedFact;
+    const markBlocked = (root) => {
+        for (const [component, by] of downstreamWithin(components, left, [root])) {
+            if (blockedBy.has(component) || failed.includes(component))
+                continue;
+            blockedBy.set(component, by);
+        }
+    };
+    options.onProgress?.({ type: "run-start", waves: plan.waves });
+    for (const [waveIndex, wave] of plan.waves.entries()) {
+        const waveNum = waveIndex + 1;
+        const runnable = wave.filter((name) => left.has(name) && !blockedBy.has(name));
+        if (waveGate.only !== undefined && waveNum < waveGate.only) {
+            if (runnable.length > 0)
+                throw new EarlierWaveNotAppliedError(waveGate.only, waveNum, runnable);
+            continue;
+        }
+        if (waveGate.only !== undefined && waveNum > waveGate.only)
+            break;
+        if (runnable.length === 0)
+            continue;
+        const gateName = waveGateName(waveGate.gate, waveNum);
+        const contexts = new Map(runnable.map((name) => [name, fanOutContext(options, name)]));
+        const planned = await Promise.all(runnable.map((name) => planComponent(byName.get(name), contexts.get(name), componentOutputs)));
+        const members = [];
+        const plansFor = new Map();
+        const waveFailures = [];
+        for (const p of planned) {
+            if ("error" in p) {
+                waveFailures.push({ component: p.component, error: p.error });
+                continue;
+            }
+            members.push(...p.members);
+            plansFor.set(p.component, p.plans);
+        }
+        let digest;
+        try {
+            // A wave where nothing planned has no set, and so no digest.
+            digest = members.length > 0 ? waveSetDigest(members) : "";
+        }
+        catch (err) {
+            // Two components planning the same root: there is no one plan for it.
+            const error = err instanceof Error ? err.message : String(err);
+            for (const name of plansFor.keys())
+                waveFailures.push({ component: name, error });
+            plansFor.clear();
+            digest = "";
+        }
+        for (const f of waveFailures) {
+            failed.push(f.component);
+            results.push(planFailure(f.component, f.error ?? "plan failed"));
+            markBlocked(f.component);
+        }
+        const toRun = runnable.filter((name) => plansFor.has(name));
+        const record = {
+            wave: waveNum,
+            op: waveGate.op,
+            gate: gateName,
+            components: [...runnable].sort(),
+            digest,
+            members: [...members].sort((a, b) => a.member.localeCompare(b.member)),
+            status: "failed",
+            ...(waveFailures.length > 0 ? { failed: waveFailures } : {}),
+        };
+        if (toRun.length === 0) {
+            waves.push(record);
+            options.onWaveSettled?.(record);
+            continue;
+        }
+        const check = await evaluateGate(gates.port, {
+            op: waveGate.op,
+            gate: gateName,
+            planDigest: digest,
+            description: waveGate.description ?? `wave ${waveNum} of ${plan.waves.length}: ${toRun.join(", ")}`,
+            ...(waveGate.timeout ? { timeout: waveGate.timeout } : {}),
+            ...(options.now ? { now: options.now } : {}),
+        });
+        if (!check.satisfied) {
+            // Nothing in this wave ran, and no later wave is planned: its plan
+            // would read outputs this wave has not written.
+            const stopped = {
+                ...record,
+                status: "gated",
+                ...(check.mismatch?.approved ? { approved: check.mismatch.approved } : {}),
+            };
+            waves.push(stopped);
+            options.onWaveSettled?.(stopped);
+            gatedFact = check.pending;
+            break;
+        }
+        options.onProgress?.({ type: "wave-start", wave: waveNum, components: toRun });
+        const waveResults = await Promise.all(toRun.map(async (name) => {
+            options.onProgress?.({ type: "component-start", wave: waveNum, component: name });
+            const plans = plansFor.get(name);
+            const ctx = { ...contexts.get(name), ...(Object.keys(plans).length > 0 ? { plans } : {}) };
+            const result = await runComponentDeploy(byName.get(name), ctx, registry, componentOutputs, options.onProgress, gates);
+            options.onProgress?.({
+                type: "component-done",
+                wave: waveNum,
+                component: name,
+                status: result.status === "fail" ? "failed" : result.status,
+            });
+            options.onComponentSettled?.(result, componentOutputs[name]);
+            return result;
+        }));
+        results.push(...waveResults);
+        for (const result of waveResults) {
+            if (result.status === "ok") {
+                completed.push(result.component);
+                continue;
+            }
+            if (result.status === "fail") {
+                failed.push(result.component);
+                waveFailures.push({ component: result.component });
+            }
+            else {
+                gatedFact ?? (gatedFact = result.gate);
+            }
+            markBlocked(result.component);
+        }
+        const settled = {
+            ...record,
+            status: waveFailures.length > 0 ? "failed" : "applied",
+            approvedBy: check.resolution.resolvedBy,
+            ...(waveFailures.length > 0 ? { failed: waveFailures } : {}),
+        };
+        waves.push(settled);
+        options.onWaveSettled?.(settled);
+        options.onProgress?.({
+            type: "wave-done",
+            wave: waveNum,
+            status: waveFailures.length > 0 ? "failed" : waveResults.some((r) => r.status === "gated") ? "gated" : "ok",
+        });
+    }
+    const blocked = [...blockedBy.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([component, by]) => ({ component, reason: "blocked", blockedBy: by }));
+    const status = failed.length > 0 ? "fail" : gatedFact ? "gated" : "ok";
+    options.onProgress?.({ type: "run-done", status: status === "fail" ? "failed" : status });
+    return {
+        // The derivation's waves, not the narrowed re-layering: their numbers name the gates.
+        plan: { ...active, waves: plan.waves },
+        status,
+        results,
+        completed: [...completed].sort(),
+        failed: [...failed].sort(),
+        blocked,
+        componentOutputs,
+        ...(gatedFact ? { gate: gatedFact } : {}),
+        waves,
+    };
+}