@intentius/chant 0.124.27 → 0.124.29

package/dist/components/driver.js

@@ -52,6 +52,7 @@ import { gateName } from "../op/gate-name.js";
 import { GateNotRecordableError } from "../lifecycle/no-record.js";
 import { componentPlanDigest } from "./gate-plan.js";
 import { isPromotedArtifact } from "./auto-release.js";
+import { gateEventsOf, joinRunEventSinks, progressSinkOf } from "../run-event-stream.js";
 function isGateStep(step) {
     return step.kind === "gate";
 }
@@ -185,6 +186,41 @@ export function resolveStepInput(input, phaseOutputs, componentOutputs) {
     };
     return walk(input);
 }
+/**
+ * The components (or stacks) whose outputs `input` reads through
+ * cross-component wiring, `stackOutput()` or `@<component>.publish.*`, and
+ * which have no value for it in `componentOutputs`, sorted and each once
+ * (#4084). {@link resolveStepInput} turns each such reference into
+ * `undefined`; a plan uses this to say whose outputs it is waiting on.
+ */
+export function unresolvedWiringSources(input, componentOutputs) {
+    const found = new Set();
+    const walk = (value) => {
+        if (typeof value === "string") {
+            if (PRIOR_STEP_REF.test(value))
+                return;
+            const ref = value.match(COMPONENT_ARTIFACT_REF);
+            if (ref && resolvePath(componentOutputs[ref[1]]?.publish, ref[2]) === undefined)
+                found.add(ref[1]);
+            return;
+        }
+        if (Array.isArray(value)) {
+            value.forEach(walk);
+            return;
+        }
+        if (value && typeof value === "object") {
+            if ("stackOutput" in value) {
+                const { stack, name } = value.stackOutput;
+                if (resolvePath(componentOutputs[stack], name) === undefined)
+                    found.add(stack);
+                return;
+            }
+            Object.values(value).forEach(walk);
+        }
+    };
+    walk(input);
+    return [...found].sort();
+}
 class StepFailure extends Error {
     constructor(records, executed) {
         super("step failed");
@@ -210,7 +246,7 @@ class GateStop extends Error {
         this.name = "GateStop";
     }
 }
-/** A result status as the progress stream spells it — the only difference is `fail` vs `failed`, which the two vocabularies have always disagreed on. */
+/** A result status as the event stream spells it — the only difference is `fail` vs `failed`, which the two vocabularies have always disagreed on. */
 function progressStatus(status) {
     return status === "fail" ? "failed" : status;
 }
@@ -261,30 +297,44 @@ async function runCapabilityStep(step, phaseName, ctx, registry, phaseOutputs, c
  * gate is a read of the ledger rather than work, and starting activities a
  * pending gate is about to strand defeats the point of stopping at it.
  *
- * `onProgress`, when supplied, is called with a `phase-start` event before any
- * step runs, a `step` event around each capability invocation (`"running"`
- * then `"ok"`/`"failed"`), and a `phase-done` event once the phase settles —
- * purely additive observation, never consulted for control flow. Recursion
- * into a nested fan-out phase passes the same callback through, so a nested
- * phase's events use its own name. Left `undefined` by every caller that
- * doesn't opt into `--progress-json` (see ./run-progress.ts), in which case
- * every `onProgress?.(...)` call below is a no-op and behavior is unchanged.
+ * `emit`, when supplied, gets the phase's run events (#4041): `phase-start`
+ * before any step runs, a `step-start` and a `step-settle` around each gate
+ * and each capability invocation, the gate's `gate-resolved` or
+ * `gate-waiting`, a `skipped` settle with `skip: "not-run"` for each step a
+ * failure or a gate stopped, and `phase-settle` once the phase settles. It
+ * is observation only, never consulted for control flow. Recursion into a
+ * nested fan-out phase passes the same sink through, so a nested phase's
+ * events use its own name. `--progress-json` reads the same events through
+ * `progressOfRunEvent` (../run-event-stream.ts), which keeps the older
+ * stream's shape.
  */
-async function runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs, gates, onProgress) {
+async function runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs, gates, emit) {
+    /** Where a step of this phase sits, for its events. */
+    const stepAt = (entry, step) => ({
+        component: ctx.component,
+        phase: phaseDef.phase,
+        step,
+        index: phaseDef.steps.indexOf(entry),
+    });
     /** Decide this phase's gates against the ledger, in authored order, before any of its work starts. Throws `GateStop` at the first one nobody has approved. */
     const decideGates = async () => {
         const gateRecords = [];
         for (const gate of phaseDef.steps.filter(isGateStep)) {
             const start = Date.now();
             const base = { component: ctx.component, phase: phaseDef.phase, kind: `gate:${gateName(gate)}` };
+            const at = stepAt(gate, base.kind);
+            emit?.({ type: "step-start", ...at });
             let check;
             try {
                 check = await evaluateGate(gates.port, {
-                    op: ctx.component,
+                    op: gates.releaseGate?.op ?? ctx.component,
                     gate: gateName(gate),
                     // #2574: an approval counts only for this environment and this plan.
                     environment: ctx.env,
                     ...(gates.planDigest !== undefined ? { planDigest: gates.planDigest } : {}),
+                    // #4045: and under a release, only for that release.
+                    ...(gates.releaseGate ? { releaseDigest: gates.releaseGate.releaseDigest } : {}),
+                    ...(gates.releaseGate?.verifyEmpty ? { verifyEmpty: gates.releaseGate.verifyEmpty } : {}),
                     ...(gate.description ? { description: gate.description } : {}),
                     ...(gate.timeout ? { timeout: gate.timeout } : {}),
                     ...(gates.now ? { now: gates.now } : {}),
@@ -296,11 +346,18 @@ async function runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs,
                 if (!(err instanceof GateNotRecordableError))
                     throw err;
                 gateRecords.push({ ...base, status: "fail", durationMs: Date.now() - start, error: err.message });
+                emit?.({ type: "step-settle", ...at, status: "failed", durationMs: Date.now() - start, error: err.message });
                 for (const skipped of phaseDef.steps.filter((s) => !isGateStep(s))) {
                     gateRecords.push(skippedRecord(skipped));
                 }
                 throw new StepFailure(gateRecords, []);
             }
+            for (const body of gateEventsOf(check, { ...at, op: gates.releaseGate?.op ?? ctx.component, gate: gateName(gate) }, {
+                durationMs: Date.now() - start,
+                ...(!check.satisfied && check.mismatch ? { message: "an approval stands for this gate, but for another environment or plan" } : {}),
+            })) {
+                emit?.(body);
+            }
             if (!check.satisfied) {
                 gateRecords.push({ ...base, status: "skipped", durationMs: Date.now() - start });
                 for (const skipped of phaseDef.steps.filter((s) => !isGateStep(s))) {
@@ -317,6 +374,8 @@ async function runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs,
                     resolvedBy: check.resolution.resolvedBy,
                     timestamp: check.resolution.timestamp,
                     ...(check.resolution.url ? { url: check.resolution.url } : {}),
+                    ...(gates.releaseGate ? { op: gates.releaseGate.op } : {}),
+                    ...(check.via === "empty" ? { empty: true } : {}),
                 },
             });
         }
@@ -326,7 +385,7 @@ async function runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs,
     const runEntry = async (entry) => {
         if (isPhaseStep(entry)) {
             try {
-                const nested = await runPhase(entry, ctx, registry, phaseOutputs, componentOutputs, gates, onProgress);
+                const nested = await runPhase(entry, ctx, registry, phaseOutputs, componentOutputs, gates, emit);
                 return { ...nested, failed: false };
             }
             catch (err) {
@@ -348,14 +407,14 @@ async function runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs,
                 throw err;
             }
         }
-        onProgress?.({ type: "step", component: ctx.component, phase: phaseDef.phase, step: entry.kind, status: "running" });
+        const at = stepAt(entry, entry.kind);
+        emit?.({ type: "step-start", ...at });
         const { record, resolvedInput, output } = await runCapabilityStep(entry, phaseDef.phase, ctx, registry, phaseOutputs, componentOutputs);
-        onProgress?.({
-            type: "step",
-            component: ctx.component,
-            phase: phaseDef.phase,
-            step: entry.kind,
+        emit?.({
+            type: "step-settle",
+            ...at,
             status: record.status === "ok" ? "ok" : "failed",
+            durationMs: record.durationMs,
             ...(record.error !== undefined ? { error: record.error } : {}),
         });
         if (record.status === "ok") {
@@ -372,13 +431,12 @@ async function runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs,
             failed: record.status === "fail",
         };
     };
-    const skippedRecord = (entry) => ({
-        component: ctx.component,
-        phase: phaseDef.phase,
-        kind: isPhaseStep(entry) ? entry.phase : entry.kind,
-        status: "skipped",
-        durationMs: 0,
-    });
+    /** A step a failure or a gate stopped before it started: recorded, and settled `skipped` with `skip: "not-run"`. */
+    const skippedRecord = (entry) => {
+        const kind = isPhaseStep(entry) ? entry.phase : entry.kind;
+        emit?.({ type: "step-settle", ...stepAt(entry, kind), status: "skipped", skip: "not-run", durationMs: null });
+        return { component: ctx.component, phase: phaseDef.phase, kind, status: "skipped", durationMs: 0 };
+    };
     const runEntries = async () => {
         const gateRecords = await decideGates();
         if (phaseDef.parallel) {
@@ -412,18 +470,18 @@ async function runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs,
         }
         return { records, executed };
     };
-    onProgress?.({ type: "phase-start", component: ctx.component, phase: phaseDef.phase });
+    emit?.({ type: "phase-start", component: ctx.component, phase: phaseDef.phase });
     try {
         const result = await runEntries();
-        onProgress?.({ type: "phase-done", component: ctx.component, phase: phaseDef.phase, status: "ok" });
+        emit?.({ type: "phase-settle", component: ctx.component, phase: phaseDef.phase, status: "ok" });
         return result;
     }
     catch (err) {
         if (err instanceof GateStop) {
-            onProgress?.({ type: "phase-done", component: ctx.component, phase: phaseDef.phase, status: "gated" });
+            emit?.({ type: "phase-settle", component: ctx.component, phase: phaseDef.phase, status: "gated" });
         }
         else if (err instanceof StepFailure) {
-            onProgress?.({ type: "phase-done", component: ctx.component, phase: phaseDef.phase, status: "failed" });
+            emit?.({ type: "phase-settle", component: ctx.component, phase: phaseDef.phase, status: "failed" });
         }
         throw err;
     }
@@ -492,16 +550,17 @@ async function rollbackExecuted(executed, ctx, registry) {
  * any) are recorded into `componentOutputs` under its own name so downstream
  * components can reference `@<name>.publish.*`.
  *
- * `onProgress`, when supplied, is forwarded to every `runPhase` call (both the
- * forward `deploy` phases and, on failure, the component's own authored
- * `rollback` phases) so a `--progress-json` consumer sees `phase-start`/
- * `step`/`phase-done` events for whichever phases actually ran. The saga
- * unwind step-by-step compensation (`rollbackExecuted` below) is not part of
- * the `RunProgressEvent` contract and stays silent — it isn't a `deploy`
- * phase, and its record statuses (`rolled-back`/`rollback-opted-out`) don't
- * map onto the `step` event's `running`/`ok`/`failed` shape.
+ * `onProgress` (the older `RunProgressEvent` stream) and `onRunEvent` (run
+ * events, #4041), when supplied, are forwarded to every `runPhase` call (both
+ * the forward `deploy` phases and, on failure, the component's own authored
+ * `rollback` phases), so a consumer sees the phase and step events of
+ * whichever phases actually ran. The saga unwind step-by-step compensation
+ * (`rollbackExecuted` below) stays silent: it isn't a `deploy` phase, and
+ * its record statuses (`rolled-back`/`rollback-opted-out`) are not step
+ * statuses either stream has.
  */
-export async function runComponentDeploy(component, ctx, registry, componentOutputs, onProgress, gateContext = { port: gitGateLedgerPort() }) {
+export async function runComponentDeploy(component, ctx, registry, componentOutputs, onProgress, gateContext = { port: gitGateLedgerPort() }, onRunEvent) {
+    const emit = joinRunEventSinks(onRunEvent, progressSinkOf(onProgress));
     // Each component tracks its own release: a digest one component promoted never stamps another's deploy.
     if (ctx.release)
         ctx = { ...ctx, release: { ...ctx.release } };
@@ -515,18 +574,20 @@ export async function runComponentDeploy(component, ctx, registry, componentOutp
         ctx.release.version = release;
     const gates = {
         ...gateContext,
-        planDigest: componentPlanDigest({
-            environment: ctx.env,
-            component,
-            ...(ctx.vars ? { vars: ctx.vars } : {}),
-            ...(release !== undefined ? { release } : {}),
-        }),
+        // #4045: a release gate binds the release's change set, not this composition.
+        planDigest: gateContext.releaseGate?.planDigest ??
+            componentPlanDigest({
+                environment: ctx.env,
+                component,
+                ...(ctx.vars ? { vars: ctx.vars } : {}),
+                ...(release !== undefined ? { release } : {}),
+            }),
     };
     const records = [];
     const allExecuted = [];
     try {
         for (const phaseDef of component.deploy) {
-            const result = await runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs, gates, onProgress);
+            const result = await runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs, gates, emit);
             records.push(...result.records);
             allExecuted.push(...result.executed);
         }
@@ -559,7 +620,7 @@ export async function runComponentDeploy(component, ctx, registry, componentOutp
         records.push(...(await rollbackExecuted(allExecuted, ctx, registry)));
         for (const phaseDef of [...(component.rollback ?? [])].reverse()) {
             try {
-                const result = await runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs, gates, onProgress);
+                const result = await runPhase(phaseDef, ctx, registry, phaseOutputs, componentOutputs, gates, emit);
                 records.push(...result.records);
             }
             catch (compErr) {
@@ -688,29 +749,30 @@ export async function runInterpretDriver(components, registry, options) {
     const { order, waves } = resolveComponentGraph(components);
     const byName = new Map(components.map((c) => [c.name, c]));
     const componentOutputs = { ...(options.componentOutputs ?? {}) };
-    const { onProgress } = options;
+    const emit = joinRunEventSinks(options.onRunEvent, progressSinkOf(options.onProgress));
     const gates = {
         port: options.gates ?? gitGateLedgerPort(),
         ...(options.now ? { now: options.now } : {}),
         ...(options.releases ? { releases: options.releases } : {}),
+        ...(options.releaseGate ? { releaseGate: options.releaseGate } : {}),
     };
-    onProgress?.({ type: "run-start", waves });
+    emit?.({ type: "run-start", waves });
     const results = [];
     let failedComponent;
     let gated;
     waveLoop: for (const [waveIndex, wave] of waves.entries()) {
         const waveNum = waveIndex + 1;
-        onProgress?.({ type: "wave-start", wave: waveNum, components: wave });
+        emit?.({ type: "wave-start", wave: waveNum, components: wave });
         const waveComponents = wave.map((name) => byName.get(name));
         const waveResults = await Promise.all(waveComponents.map(async (component) => {
-            onProgress?.({ type: "component-start", wave: waveNum, component: component.name });
-            const result = await runComponentDeploy(component, deployContext(options, component.name), registry, componentOutputs, onProgress, gates);
-            onProgress?.({ type: "component-done", wave: waveNum, component: component.name, status: progressStatus(result.status) });
+            emit?.({ type: "component-start", wave: waveNum, component: component.name });
+            const result = await runComponentDeploy(component, deployContext(options, component.name), registry, componentOutputs, undefined, gates, emit);
+            emit?.({ type: "component-settle", wave: waveNum, component: component.name, status: progressStatus(result.status) });
             return result;
         }));
         results.push(...waveResults);
         const stopped = waveResults.find((r) => r.status !== "ok");
-        onProgress?.({ type: "wave-done", wave: waveNum, status: progressStatus(stopped?.status ?? "ok") });
+        emit?.({ type: "wave-settle", wave: waveNum, status: progressStatus(stopped?.status ?? "ok") });
         if (stopped) {
             // A failure in the same wave outranks a gate: something is actually
             // broken, and reporting the run as "waiting on a human" would hide it.
@@ -724,7 +786,7 @@ export async function runInterpretDriver(components, registry, options) {
     }
     const status = failedComponent ? "fail" : gated ? "gated" : "ok";
     const ok = status === "ok";
-    onProgress?.({ type: "run-done", status: progressStatus(status) });
+    emit?.({ type: "run-settle", status: progressStatus(status), durationMs: null });
     const result = {
         order, waves, results, ok, status, failedComponent, componentOutputs,
         ...(gated

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

@@ -0,0 +1,69 @@
+/**
+ * What each component of a fan-out would apply, as one digest per component
+ * (#4081), and which of an earlier attempt's progress still holds against it.
+ *
+ * A fan-out's plan digest identifies the derivation: who runs, in what order,
+ * off which edges. Two different changes that touch the same components in
+ * the same shape derive the same plan, so the plan digest alone cannot say
+ * whether "cluster-a already applied" is about the change in front of us.
+ * The attempt record therefore keeps, for each component it applied, the
+ * input digest computed here, and a resumed attempt carries a component as
+ * `already-applied` only when that digest is the one the component has now.
+ *
+ * ## What a component's input digest covers
+ *
+ * - The environment. Progress against `local` says nothing about `prod`.
+ * - The composition: every phase and step as authored, `rollback` included.
+ *   A `stackOutput` reference is hashed as the reference, not its value.
+ * - The bytes of every file a step input names. A string input that resolves,
+ *   relative to the project root, to a file or directory inside the root is
+ *   read and hashed, so `template: "dist/cluster-a.template.json"` covers the
+ *   built template and a rebuild that changes it changes the digest. A
+ *   directory is hashed by its files, skipping `.git`, `node_modules` and
+ *   `.chant`, the last because the attempt record itself lives there.
+ * - The input digests of the components it depends on. A parameter filled
+ *   from an upstream output gets its value from that upstream's apply, so a
+ *   change upstream changes the digest of everything downstream of it, the
+ *   same reach the fan-out's own walk has.
+ *
+ * Nothing decided during the run goes in: no run id, no time, no output an
+ * apply produced.
+ */
+import type { DriverComponent } from "./driver.js";
+export interface ComponentInputOptions {
+    /** The root step inputs' file paths are read relative to, the project the fan-out runs in. */
+    projectRoot: string;
+    /** The environment the fan-out applies to. */
+    env: string;
+    /** Environment config resolved ahead of the run, when the caller has any. */
+    vars?: Record<string, unknown>;
+}
+/**
+ * One input digest per component in `components`, keyed by name. Each folds
+ * in the digests of the components it depends on, so `components` should be
+ * the whole project: a dependency it does not contain is hashed by name only.
+ */
+export declare function componentInputDigests(components: DriverComponent[], options: ComponentInputOptions): Record<string, string>;
+/** What of an earlier attempt's progress holds against the inputs the components have now. */
+export interface CarriedProgress {
+    /** Components the attempt applied whose input is the same now. These stay `already-applied`. */
+    carried: string[];
+    /** Components the attempt applied whose input moved since. These run again. */
+    changed: string[];
+    /**
+     * True when the record has no input digests at all, as one written before
+     * #4081 has. Nothing carries from such a record, since nothing in it says
+     * what was applied.
+     */
+    unrecorded: boolean;
+}
+/**
+ * Split an attempt's `completed` by whether each component's input is the
+ * same as now. A component the record holds no digest for counts as changed:
+ * a claim that it applied is only worth keeping for the input it applied.
+ */
+export declare function progressThatCarries(attempt: {
+    completed: string[];
+    inputs?: Record<string, string>;
+}, now: Record<string, string>): CarriedProgress;
+//# sourceMappingURL=fan-out-inputs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fan-out-inputs.d.ts","sourceRoot":"","sources":["../../src/components/fan-out-inputs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAMH,OAAO,KAAK,EAAE,eAAe,EAAe,MAAM,UAAU,CAAC;AAE7D,MAAM,WAAW,qBAAqB;IACpC,8FAA8F;IAC9F,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAyED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,EAAE,qBAAqB,GAC7B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA+BxB;AAED,8FAA8F;AAC9F,MAAM,WAAW,eAAe;IAC9B,gGAAgG;IAChG,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,+EAA+E;IAC/E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE;IAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,EACjE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC1B,eAAe,CAUjB"}

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

@@ -0,0 +1,169 @@
+/**
+ * What each component of a fan-out would apply, as one digest per component
+ * (#4081), and which of an earlier attempt's progress still holds against it.
+ *
+ * A fan-out's plan digest identifies the derivation: who runs, in what order,
+ * off which edges. Two different changes that touch the same components in
+ * the same shape derive the same plan, so the plan digest alone cannot say
+ * whether "cluster-a already applied" is about the change in front of us.
+ * The attempt record therefore keeps, for each component it applied, the
+ * input digest computed here, and a resumed attempt carries a component as
+ * `already-applied` only when that digest is the one the component has now.
+ *
+ * ## What a component's input digest covers
+ *
+ * - The environment. Progress against `local` says nothing about `prod`.
+ * - The composition: every phase and step as authored, `rollback` included.
+ *   A `stackOutput` reference is hashed as the reference, not its value.
+ * - The bytes of every file a step input names. A string input that resolves,
+ *   relative to the project root, to a file or directory inside the root is
+ *   read and hashed, so `template: "dist/cluster-a.template.json"` covers the
+ *   built template and a rebuild that changes it changes the digest. A
+ *   directory is hashed by its files, skipping `.git`, `node_modules` and
+ *   `.chant`, the last because the attempt record itself lives there.
+ * - The input digests of the components it depends on. A parameter filled
+ *   from an upstream output gets its value from that upstream's apply, so a
+ *   change upstream changes the digest of everything downstream of it, the
+ *   same reach the fan-out's own walk has.
+ *
+ * Nothing decided during the run goes in: no run id, no time, no output an
+ * apply produced.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { computePlanDigest } from "../lifecycle/plan-digest.js";
+import { sha256Hex } from "../content-digest.js";
+const SKIPPED_DIRS = new Set([".git", "node_modules", ".chant"]);
+/** Inside `root`, and not `root` itself: a bare "." names the whole project, which is no one step's input. */
+function insideRoot(root, path) {
+    const rel = relative(root, path);
+    return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+/** Hash a file, or a directory by the relative path and bytes of each file under it. */
+function hashPath(path) {
+    let stat;
+    try {
+        stat = statSync(path);
+    }
+    catch {
+        return undefined;
+    }
+    if (stat.isFile())
+        return `sha256:${sha256Hex(readFileSync(path))}`;
+    if (!stat.isDirectory())
+        return undefined;
+    const files = {};
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (SKIPPED_DIRS.has(entry.name))
+                continue;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else if (entry.isFile())
+                files[relative(path, full).split(sep).join("/")] = sha256Hex(readFileSync(full));
+        }
+    };
+    walk(path);
+    return computePlanDigest("component-input-dir", files);
+}
+/** Every file or directory a component's steps name, keyed by the string the step wrote. */
+function referencedFiles(component, root) {
+    const out = {};
+    const visit = (value) => {
+        if (typeof value === "string") {
+            if (value === "" || value.includes("\n") || value in out)
+                return;
+            const path = resolve(root, value);
+            if (!insideRoot(root, path) || !existsSync(path))
+                return;
+            const digest = hashPath(path);
+            if (digest !== undefined)
+                out[value] = digest;
+            return;
+        }
+        if (Array.isArray(value))
+            value.forEach(visit);
+        else if (value && typeof value === "object")
+            Object.values(value).forEach(visit);
+    };
+    // Only a step's inputs name files. A phase name or a step's `kind` that
+    // happens to match a directory in the project is not one.
+    const visitPhases = (phases) => {
+        for (const phase of phases ?? []) {
+            for (const step of phase.steps) {
+                if (isPhase(step)) {
+                    visitPhases([step]);
+                    continue;
+                }
+                if (step.kind === "gate")
+                    continue;
+                const { kind: _kind, ...inputs } = step;
+                visit(inputs);
+            }
+            visitPhases(phase.onFailure);
+        }
+    };
+    visitPhases(component.deploy);
+    visitPhases(component.rollback);
+    return out;
+}
+function isPhase(step) {
+    return typeof step.phase === "string" && Array.isArray(step.steps);
+}
+/**
+ * One input digest per component in `components`, keyed by name. Each folds
+ * in the digests of the components it depends on, so `components` should be
+ * the whole project: a dependency it does not contain is hashed by name only.
+ */
+export function componentInputDigests(components, options) {
+    const root = resolve(options.projectRoot);
+    const byName = new Map(components.map((c) => [c.name, c]));
+    const digests = new Map();
+    const visiting = new Set();
+    const digestOf = (name) => {
+        const known = digests.get(name);
+        if (known !== undefined)
+            return known;
+        const component = byName.get(name);
+        // An unknown dependency or a cycle is refused by the fan-out's derivation
+        // before this runs; here it only has to not loop.
+        if (!component || visiting.has(name))
+            return null;
+        visiting.add(name);
+        const upstream = [...(component.dependsOn ?? [])].sort().map((dep) => ({ component: dep, digest: digestOf(dep) }));
+        visiting.delete(name);
+        const digest = computePlanDigest("component-input", {
+            environment: options.env,
+            component: name,
+            deploy: component.deploy,
+            rollback: component.rollback ?? null,
+            vars: options.vars ?? null,
+            files: referencedFiles(component, root),
+            upstream,
+        });
+        digests.set(name, digest);
+        return digest;
+    };
+    for (const c of components)
+        digestOf(c.name);
+    return Object.fromEntries([...digests.entries()].sort(([a], [b]) => a.localeCompare(b)));
+}
+/**
+ * Split an attempt's `completed` by whether each component's input is the
+ * same as now. A component the record holds no digest for counts as changed:
+ * a claim that it applied is only worth keeping for the input it applied.
+ */
+export function progressThatCarries(attempt, now) {
+    const recorded = attempt.inputs;
+    const carried = [];
+    const changed = [];
+    for (const name of [...attempt.completed].sort()) {
+        const then = recorded?.[name];
+        if (then !== undefined && now[name] !== undefined && then === now[name])
+            carried.push(name);
+        else
+            changed.push(name);
+    }
+    return { carried, changed, unrecorded: recorded === undefined };
+}

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

@@ -25,6 +25,14 @@
  * `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.
+ *
+ * `inputs` holds, for each component in `completed`, the input digest it
+ * applied (#4081, ./fan-out-inputs.ts). The plan digest only identifies the
+ * derivation, and two different changes with the same shape derive the same
+ * one, so the digest alone would carry "cluster-a already applied" into a
+ * change that never applied it. A resumed attempt carries a component only
+ * when its input digest is the same now. A record written before #4081 has
+ * no `inputs`, and none of its progress carries.
  */
 import { type WaveRecord } from "../wave-engine.js";
 import type { ChangeSetDocument } from "../change-set.js";
@@ -64,6 +72,11 @@ export interface FanOutAttempt {
     carried?: Record<string, unknown>;
     /** A pull request's apply only (#3464). */
     prApply?: PrApplyRecord;
+    /**
+     * The input digest each completed component applied (#4081), keyed by
+     * name. Absent on a record written before it, which then carries nothing.
+     */
+    inputs?: Record<string, string>;
 }
 /** Read an attempt record, or `undefined` when there is none yet. Throws on a file that is not JSON. */
 export declare function readFanOutAttempt(path: string): FanOutAttempt | undefined;

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

@@ -1 +1 @@
-{"version":3,"file":"fan-out-record.d.ts","sourceRoot":"","sources":["../../src/components/fan-out-record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EAAwC,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,oFAAoF;AACpF,MAAM,WAAW,aAAa;IAC5B,yFAAyF;IACzF,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,oDAAoD;IACpD,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB,qGAAqG;IACrG,SAAS,EAAE,iBAAiB,CAAC;IAC7B;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjD,wCAAwC;IACxC,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,2CAA2C;IAC3C,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AA+BD,wGAAwG;AACxG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAkBzE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,IAAI,CAE7E"}
+{"version":3,"file":"fan-out-record.d.ts","sourceRoot":"","sources":["../../src/components/fan-out-record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,EAAwC,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,oFAAoF;AACpF,MAAM,WAAW,aAAa;IAC5B,yFAAyF;IACzF,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,oDAAoD;IACpD,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB,qGAAqG;IACrG,SAAS,EAAE,iBAAiB,CAAC;IAC7B;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjD,wCAAwC;IACxC,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,2CAA2C;IAC3C,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AA+BD,wGAAwG;AACxG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAwBzE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,IAAI,CAE7E"}

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

@@ -25,6 +25,14 @@
  * `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.
+ *
+ * `inputs` holds, for each component in `completed`, the input digest it
+ * applied (#4081, ./fan-out-inputs.ts). The plan digest only identifies the
+ * derivation, and two different changes with the same shape derive the same
+ * one, so the digest alone would carry "cluster-a already applied" into a
+ * change that never applied it. A resumed attempt carries a component only
+ * when its input digest is the same now. A record written before #4081 has
+ * no `inputs`, and none of its progress carries.
  */
 import { existsSync, readFileSync } from "node:fs";
 import { readWaveRecords, writeWaveRecordFile } from "../wave-engine.js";
@@ -71,6 +79,13 @@ export function readFanOutAttempt(path) {
     }
     const waves = readWaveRecords(parsed.waves);
     const prApply = readPrApplyRecord(parsed.prApply);
+    let inputs;
+    if (isRecord(parsed.inputs)) {
+        inputs = {};
+        for (const [name, value] of Object.entries(parsed.inputs))
+            if (typeof value === "string")
+                inputs[name] = value;
+    }
     return {
         digest: typeof parsed.digest === "string" ? parsed.digest : "",
         completed: Array.isArray(parsed.completed) ? parsed.completed.filter((n) => typeof n === "string") : [],
@@ -79,6 +94,7 @@ export function readFanOutAttempt(path) {
         ...(waves.length > 0 ? { waves } : {}),
         ...(isRecord(parsed.carried) && Object.keys(parsed.carried).length > 0 ? { carried: parsed.carried } : {}),
         ...(prApply ? { prApply } : {}),
+        ...(inputs ? { inputs } : {}),
     };
 }
 /**