@intentius/chant 0.124.28 → 0.124.30

package/src/cli/handlers/fan-out.test.ts

@@ -84,6 +84,13 @@ let inputs: Record<string, Record<string, unknown>> = {};
 let stepOutputs: Record<string, Record<string, unknown>> = {};
 /** Called as a component's step starts, before it applies. */
 let onStart: (component: string) => void = () => {};
+/**
+ * What each stack exposes in the deployed estate, read through the step's
+ * `outputs` as cfn-deploy's `describeStack` does (#4104). `undefined` leaves
+ * the capability with no `outputs`; an `Error` makes the read fail.
+ */
+let liveOutputs: Record<string, Record<string, unknown> | Error> | undefined;
+let outputsRead: string[] = [];
 
 function makeArgs(overrides: Partial<ParsedArgs>): ParsedArgs {
   return {
@@ -114,6 +121,8 @@ beforeEach(() => {
   inputs = {};
   stepOutputs = {};
   onStart = () => {};
+  liveOutputs = undefined;
+  outputsRead = [];
   gateLedger = memoryGateLedgerPort();
   stderrLines = [];
   stdoutLines = [];
@@ -149,6 +158,16 @@ beforeEach(() => {
         if (failing.includes(runCtx.component)) throw new Error(`${runCtx.component} failed`);
         return { ok: true, ...(stepOutputs[runCtx.component] ? { outputs: stepOutputs[runCtx.component] } : {}) };
       },
+      ...(liveOutputs
+        ? {
+            async outputs(readCtx: { component: string }) {
+              outputsRead.push(readCtx.component);
+              const live = liveOutputs![readCtx.component];
+              if (live instanceof Error) throw live;
+              return { ...(live ?? {}) };
+            },
+          }
+        : {}),
     } as never);
     return Promise.resolve(registry);
   });
@@ -233,7 +252,8 @@ describe("proof: a plan-only invocation prints the derivation and dispatches not
 
       ran = [];
       stderrLines = [];
-      expect(await runComponentsFanOut(ctx({ base: "main", resume, dryRun: true }))).toBe(0);
+      // The same environment: progress is bound to it (#4081).
+      expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume, dryRun: true }))).toBe(0);
 
       expect(ran).toEqual([]);
       const out = stderr();
@@ -656,6 +676,46 @@ describe("--events-json (#4041)", () => {
     expect(events.at(-1)).toMatchObject({ type: "run-settle", status: "failed" });
   });
 
+  test("a component behind a failure settles blocked, naming it, after the failing wave and before the next starts (#4007)", async () => {
+    failing = ["cluster-a"];
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", eventsJson: true }))).toBe(1);
+    const events = checkRunEventLines(lines());
+    const blocked = events.filter((e) => e.type === "component-settle" && e.status === "blocked");
+    expect(blocked.map((e) => ({ wave: (e as { wave: number }).wave, component: (e as { component: string }).component, blockedBy: (e as { blockedBy?: string }).blockedBy }))).toEqual([
+      { wave: 3, component: "app-one", blockedBy: "cluster-a" },
+      { wave: 3, component: "app-two", blockedBy: "cluster-a" },
+    ]);
+    const wave2Settle = events.findIndex((e) => e.type === "wave-settle" && e.wave === 2);
+    const wave3Start = events.findIndex((e) => e.type === "wave-start" && e.wave === 3);
+    expect(events.indexOf(blocked[0]!)).toBeGreaterThan(wave2Settle);
+    expect(events.indexOf(blocked[1]!)).toBeLessThan(wave3Start);
+    // A blocked component never starts.
+    expect(events.some((e) => e.type === "component-start" && e.component === "app-one")).toBe(false);
+  });
+
+  test("a resumed fan-out settles what the earlier attempt applied as already-applied, in the derivation's waves (#4007)", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "fan-out-"));
+    try {
+      const resume = join(dir, "attempt.json");
+      failing = ["cluster-a"];
+      expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume }))).toBe(1);
+      failing = [];
+      stdoutLines = [];
+      expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume, eventsJson: true }))).toBe(0);
+      const events = checkRunEventLines(lines());
+      const firstWave = events.findIndex((e) => e.type === "wave-start");
+      const applied = events.filter((e) => e.type === "component-settle" && e.status === "already-applied");
+      expect(applied.map((e) => [(e as { component: string }).component, (e as { wave: number }).wave])).toEqual([["app-three", 3], ["cluster-b", 2], ["net", 1]]);
+      for (const e of applied) expect(events.indexOf(e)).toBeLessThan(firstWave);
+      // --progress-json never printed them, and still does not.
+      stdoutLines = [];
+      expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume, progressJson: true }))).toBe(0);
+      expect(stdoutLines.filter((l) => l.startsWith('{"type"')).map((l) => JSON.parse(l).type)).toEqual(["run-start", "run-done"]);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
   test("--progress-json on a set the gate stops now prints run-start and run-done gated (a level-0 change)", async () => {
     expect(await runComponentsFanOut(ctx({ base: "main", env: "test", gate: "release", progressJson: true }))).toBe(3);
     const progress = stdoutLines.filter((l) => l.startsWith('{"type"')).map((l) => JSON.parse(l));
@@ -670,3 +730,204 @@ describe("--events-json (#4041)", () => {
     expect(stderr()).toContain("--events-json and --progress-json both stream to stdout");
   });
 });
+
+describe("progress carries only for an unchanged input (#4081)", () => {
+  /** The estate with each component deploying a built template from `templates/`, read relative to the project. */
+  const templated = ESTATE.map((c) => ({
+    ...c,
+    deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", stack: `${c.name}-stack`, template: `templates/${c.name}.json` }] }],
+  }));
+  let dir: string;
+  const writeTemplate = (name: string, body: unknown) =>
+    writeFile(join(dir, "templates", `${name}.json`), JSON.stringify(body));
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "fan-out-inputs-"));
+    const { mkdir } = await import("node:fs/promises");
+    await mkdir(join(dir, "templates"));
+    for (const c of templated) await writeTemplate(c.name, { Resources: { [c.name]: { Type: "AWS::SNS::Topic" } } });
+    // The project is the temp directory, so the templates are read from there and nothing touches the checkout.
+    vi.spyOn(process, "cwd").mockReturnValue(dir);
+    discoverComponentsMock.mockResolvedValue({
+      components: new Map(templated.map((c) => [c.name, { component: c, exportName: c.name, filePath: `${c.name}.component.ts` }])),
+      sourceFiles: [],
+      errors: [],
+    });
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("same shape, changed content: a stale record does not skip the components whose input moved", async () => {
+    const resume = join(dir, "attempt.json");
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume }))).toBe(0);
+    const first = JSON.parse(await readFile(resume, "utf8"));
+    expect(first.completed).toEqual(["app-one", "app-three", "app-two", "cluster-a", "cluster-b", "net"]);
+    expect(Object.keys(first.inputs).sort()).toEqual(first.completed);
+    const digest = /plan: (jcs1-sha256:[0-9a-f]{64})/.exec(stderr())?.[1];
+
+    // The next change: net's topic gets a display name and cluster-a a queue.
+    // Same components, same edges, so the same plan digest.
+    await writeTemplate("net", { Resources: { net: { Type: "AWS::SNS::Topic", Properties: { DisplayName: "estate" } } } });
+    await writeTemplate("cluster-a", { Resources: { "cluster-a": { Type: "AWS::SNS::Topic" }, events: { Type: "AWS::SQS::Queue" } } });
+    ran = [];
+    stderrLines = [];
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume }))).toBe(0);
+
+    expect([...ran].sort()).toEqual(["app-one", "app-three", "app-two", "cluster-a", "cluster-b", "net"]);
+    const out = stderr();
+    expect(out).toContain(`plan: ${digest}`);
+    expect(out).toContain("net: changed since the earlier attempt, so it runs again");
+    expect(out).toContain("cluster-a: changed since the earlier attempt, so it runs again");
+    // Downstream of net, so its parameters read a changed upstream.
+    expect(out).toContain("app-three: changed since the earlier attempt, so it runs again");
+    expect(out).not.toMatch(/already-applied/);
+    expect(out).toContain("fan-out completed: 6 applied, 0 failed, 0 blocked");
+    const second = JSON.parse(await readFile(resume, "utf8"));
+    expect(second.inputs.net).not.toBe(first.inputs.net);
+    expect(second.inputs["cluster-b"]).not.toBe(first.inputs["cluster-b"]);
+  });
+
+  test("a change below the root reruns only its own subtree", async () => {
+    const resume = join(dir, "attempt.json");
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume }))).toBe(0);
+    await writeTemplate("cluster-a", { Resources: { "cluster-a": { Type: "AWS::SNS::Topic" }, events: { Type: "AWS::SQS::Queue" } } });
+    ran = [];
+    stderrLines = [];
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume }))).toBe(0);
+    expect(ran).toEqual(["cluster-a", "app-one", "app-two"]);
+    expect(stderr()).toMatch(/cluster-b +already-applied/);
+    expect(stderr()).not.toContain("net: changed");
+  });
+
+  test("the README's fail-then-fix: the fix reruns the failed subtree and the rest stay already-applied", async () => {
+    const resume = join(dir, "attempt.json");
+    failing = ["cluster-a"];
+    await writeTemplate("cluster-a", { Resources: { events: { Type: "AWS::SQS::Queue", Properties: { FifoQueue: true, QueueName: "events" } } } });
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume }))).toBe(1);
+    const digest = /plan: (jcs1-sha256:[0-9a-f]{64})/.exec(stderr())?.[1];
+
+    // The fix changes cluster-a's template, which never applied.
+    failing = [];
+    await writeTemplate("cluster-a", { Resources: { events: { Type: "AWS::SQS::Queue", Properties: { FifoQueue: true, QueueName: "events.fifo" } } } });
+    ran = [];
+    stderrLines = [];
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume }))).toBe(0);
+    expect(ran).toEqual(["cluster-a", "app-one", "app-two"]);
+    const out = stderr();
+    expect(out).toContain(`plan: ${digest}`);
+    expect(out).not.toContain("changed since the earlier attempt");
+    for (const name of ["net", "cluster-b", "app-three"]) expect(out).toMatch(new RegExp(`${name} +already-applied`));
+    expect(out).toContain("fan-out completed: 3 applied, 0 failed, 0 blocked");
+  });
+
+  test("the fix keeps the approval: approval binds the derivation, progress binds the inputs", async () => {
+    const resume = join(dir, "attempt.json");
+    failing = ["cluster-a"];
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", gate: "release", resume }))).toBe(3);
+    const pending = gateLedger.appended[0]!;
+    gateLedger = memoryGateLedgerPort({
+      pending: [pending],
+      resolutions: [
+        {
+          version: 1,
+          kind: "resolution",
+          op: "fan-out",
+          gate: "release",
+          resolvedBy: "operator",
+          timestamp: new Date(Date.parse(pending.timestamp) + 1000).toISOString(),
+          planDigest: pending.planDigest,
+        },
+      ],
+    });
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", gate: "release", resume }))).toBe(1);
+
+    failing = [];
+    await writeTemplate("cluster-a", { Resources: { fixed: { Type: "AWS::SQS::Queue" } } });
+    ran = [];
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", gate: "release", resume }))).toBe(0);
+    expect(ran).toEqual(["cluster-a", "app-one", "app-two"]);
+  });
+
+  test("the input digest is per environment: progress against one does not carry into another", async () => {
+    const resume = join(dir, "attempt.json");
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume }))).toBe(0);
+    ran = [];
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "prod", resume }))).toBe(0);
+    expect(ran).toHaveLength(6);
+  });
+
+  test("a record without input digests carries nothing, and says so", async () => {
+    const resume = join(dir, "attempt.json");
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", dryRun: true }))).toBe(0);
+    const digest = /plan: (jcs1-sha256:[0-9a-f]{64})/.exec(stderr())![1]!;
+    await writeFile(resume, JSON.stringify({ digest, completed: ["net", "cluster-b"], failed: [], outputs: {} }));
+    stderrLines = [];
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", resume }))).toBe(0);
+    expect(ran).toHaveLength(6);
+    expect(stderr()).toContain("does not record what each component applied, so none of its progress carries");
+  });
+});
+
+describe("a seed's outputs, read from the deployed estate (#4104)", () => {
+  /** cluster-a reads net's TopicArn, and the change touches cluster-a alone. */
+  function wireClusterA(): void {
+    const wired: Component = {
+      name: "cluster-a",
+      dependsOn: ["net"],
+      deploy: [
+        {
+          phase: "Apply",
+          steps: [{ kind: "cfn-deploy", stack: "cluster-a-stack", inputs: { topic: { stackOutput: { stack: "net", name: "TopicArn" } } } }],
+        },
+      ],
+    };
+    const estate = ESTATE.map((c) => (c.name === "cluster-a" ? wired : c));
+    discoverComponentsMock.mockResolvedValue({
+      components: new Map(estate.map((c) => [c.name, { component: c, exportName: c.name, filePath: `${c.name}.component.ts` }])),
+      sourceFiles: [],
+      errors: [],
+    });
+    affectedStacksMock.mockResolvedValue({ changed: ["cluster-a-stack"], dependents: [], indeterminate: [] });
+  }
+
+  test("a cluster-a-only change runs cluster-a with net's deployed outputs, and says it read them", async () => {
+    wireClusterA();
+    liveOutputs = { net: { TopicArn: "arn:aws:sns:us-east-1:000000000000:net", QueueUrl: "http://q" } };
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test" }))).toBe(0);
+    expect(ran).not.toContain("net");
+    expect(outputsRead).toEqual(["net"]);
+    expect(inputs["cluster-a"]).toEqual(expect.objectContaining({ inputs: { topic: "arn:aws:sns:us-east-1:000000000000:net" } }));
+    expect(stderr()).toContain("net: outputs read from the deployed estate (QueueUrl, TopicArn)");
+  });
+
+  test("--seed-outputs wins: a seed it gives is not read", async () => {
+    wireClusterA();
+    liveOutputs = { net: { TopicArn: "arn:deployed" } };
+    const dir = await mkdtemp(join(tmpdir(), "fan-out-"));
+    try {
+      const seed = join(dir, "seed.json");
+      await writeFile(seed, JSON.stringify({ net: { TopicArn: "arn:seeded" } }));
+      expect(await runComponentsFanOut(ctx({ base: "main", env: "test", seedOutputs: [seed] }))).toBe(0);
+      expect(outputsRead).toEqual([]);
+      expect(inputs["cluster-a"]).toEqual(expect.objectContaining({ inputs: { topic: "arn:seeded" } }));
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("a read that fails stops the fan-out before anything runs, naming the seed", async () => {
+    wireClusterA();
+    liveOutputs = { net: new Error("ExpiredToken") };
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test" }))).toBe(1);
+    expect(ran).toEqual([]);
+    expect(stderr()).toContain("could not read the deployed outputs of net: ExpiredToken");
+  });
+
+  test("--dry-run reads nothing", async () => {
+    wireClusterA();
+    liveOutputs = { net: { TopicArn: "arn:deployed" } };
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", dryRun: true }))).toBe(0);
+    expect(outputsRead).toEqual([]);
+  });
+});

package/src/cli/handlers/fan-out.ts

@@ -34,6 +34,15 @@
  * the plan before the gate is decided, and the digest is carried rather than
  * recomputed, so the approval still stands.
  *
+ * The approval and the progress are bound to different things (#4081). The
+ * approval is bound to the plan digest, the derivation: who runs, in what
+ * order, off which edges. The progress is bound to each component's input
+ * digest (../../components/fan-out-inputs.ts): a component the earlier
+ * attempt applied stays `already-applied` only while what it would apply is
+ * the same, and one whose template, step inputs or upstream moved runs again
+ * with a line saying so. The fix after a failure keeps the approval, and a
+ * different change of the same shape does not inherit the progress.
+ *
  * `--wave-gate <name>` (#3049) swaps the one gate for one per wave: the same
  * repeated command stops at each wave's gate in turn, each planned after the
  * wave before it applied, and `chant approve fan-out <name>-wave-<n>` answers
@@ -49,6 +58,7 @@ import { changedFilesBetween, lexiconChangedUnits } from "../../components/chang
 import { deriveFanOut, fanOutRegistry } from "../../components/fan-out-support";
 import { EarlierWaveNotAppliedError, runFanOut } from "../../components/fan-out-run";
 import { readFanOutAttempt, writeFanOutAttempt, type FanOutAttempt } from "../../components/fan-out-record";
+import { componentInputDigests, progressThatCarries } from "../../components/fan-out-inputs";
 import { describeChangedWave, withWaveRecord, type WaveRecord } from "../../gated-waves";
 import { renderFanOutHuman, renderFanOutJson, renderFanOutPlan } from "../../components/fan-out-output";
 import { ndjsonProgressSink } from "../../components/run-progress";
@@ -57,6 +67,8 @@ import { summaryLedgerPrefix, writeGatedRunSummary } from "../../op/gate-summary
 import { approveCommand, gateIsSealed } from "../../op/gate";
 import { getHeadCommit } from "../../lifecycle/git";
 import { remainingFanOut, type ChangedUnits, type FanOutProgress } from "../../components/fan-out";
+import { readDeployedOutputs } from "../../components/wave-plan";
+import { deployContext } from "../../components/driver";
 import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
 import { formatError, formatInfo, formatWarning } from "../format";
 import { FAN_OUT_GATE_OP } from "../../op/gate-name";
@@ -253,7 +265,12 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
   // real run happens inside `runFanOut`, before the gate is decided, so an
   // approval survives the resume rather than being re-asked for.
   const resumePath = args.resume ? resolve(args.resume) : undefined;
+  // What each component would apply now (#4081). The record keeps it for
+  // every component that applies, and a later attempt carries progress only
+  // where it is unchanged.
+  const inputsNow = resumePath ? componentInputDigests(derived.components, { projectRoot: projectPath, env: args.env ?? "local" }) : {};
   let priorCompleted: string[] = [];
+  let priorInputs: Record<string, string> = {};
   let priorOutputs: Record<string, Record<string, unknown>> = {};
   let priorWaves: WaveRecord[] = [];
   let priorCarried: Record<string, unknown> = {};
@@ -277,11 +294,28 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
       // as progress would block their subtrees again on the very run that
       // exists to retry them — the operator repeated the command precisely
       // because the thing that failed is now expected to work.
-      priorCompleted = attempt.completed;
+      //
+      // And only the part of `completed` whose input is the same now (#4081).
+      // The plan digest identifies the derivation, which a different change
+      // of the same shape shares; the input digest says what was applied.
+      const split = progressThatCarries(attempt, inputsNow);
+      if (split.unrecorded && split.changed.length > 0) {
+        console.error(formatWarning({
+          message: `--resume: "${args.resume}" does not record what each component applied, so none of its progress carries`,
+          hint: "It was written before chant recorded component inputs. Everything selected will run.",
+        }));
+      } else {
+        for (const name of split.changed) {
+          console.error(formatInfo(`${name}: changed since the earlier attempt, so it runs again`));
+        }
+      }
+      const carried = new Set(split.carried);
+      priorCompleted = split.carried;
+      priorInputs = Object.fromEntries(split.carried.map((name) => [name, inputsNow[name]!]));
       priorOutputs = Object.fromEntries(
-        Object.entries(attempt.outputs).filter(([name]) => attempt.completed.includes(name)),
+        Object.entries(attempt.outputs).filter(([name]) => carried.has(name)),
       );
-      progress = { completed: attempt.completed };
+      progress = { completed: split.carried };
       priorWaves = attempt.waves ?? [];
       // What steps kept per member (#3459), such as a choudoufu root's wave
       // resume file. Each step decides whether what it kept still applies.
@@ -311,6 +345,36 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
   }
 
   const registry = await fanOutRegistry(projectPath, config);
+  const env = args.env ?? "local";
+
+  // A completed component's recorded outputs win over a `--seed-outputs`
+  // entry for the same name, as a fresh apply's outputs merge over a seed in
+  // the driver: the record holds what this fan-out itself applied. A seed
+  // neither gives is read from the deployed estate (#4104), through its
+  // capability's `outputs`, as pr-plan reads a dependency outside the change.
+  // One that cannot be read leaves its dependents' references unresolved.
+  const componentOutputs: Record<string, Record<string, unknown>> = { ...seededOutputs, ...priorOutputs };
+  const seeds = (progress ? remainingFanOut(derived.plan, derived.components, progress) : derived.plan).seeds;
+  let deployedSeeds: Record<string, string[]>;
+  try {
+    deployedSeeds = await readDeployedOutputs(
+      seeds,
+      new Map(derived.components.map((c) => [c.name, c])),
+      registry,
+      (name) => deployContext({ env }, name),
+      componentOutputs,
+    );
+  } catch (err) {
+    console.error(formatError({
+      message: `could not read the deployed outputs of ${seeds.filter((s) => !(s in componentOutputs)).join(", ")}: ${err instanceof Error ? err.message : String(err)}`,
+      hint: "Nothing ran. --seed-outputs <file> gives a component's outputs instead of reading them.",
+    }));
+    return 1;
+  }
+  for (const [name, keys] of Object.entries(deployedSeeds)) {
+    console.error(formatInfo(`${name}: outputs read from the deployed estate (${keys.length > 0 ? keys.join(", ") : "none yet"})`));
+  }
+
   // #3061: the commit this run deploys, for the workloads' vcs.ref.head.revision.
   const revision = await getHeadCommit().catch(() => undefined);
 
@@ -319,6 +383,7 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
   // runner, ctrl-c) then still knows that the first two applied, and the
   // repeated command picks up from there instead of redoing them.
   const completedSoFar = new Set(priorCompleted);
+  const inputsSoFar: Record<string, string> = { ...priorInputs };
   const failedSoFar: string[] = [];
   const outputsSoFar = { ...priorOutputs };
   let wavesSoFar = priorWaves;
@@ -330,6 +395,7 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
       completed: [...completedSoFar].sort(),
       failed: [...failedSoFar].sort(),
       outputs: outputsSoFar,
+      inputs: Object.fromEntries(Object.entries(inputsSoFar).sort(([a], [b]) => a.localeCompare(b))),
       ...(wavesSoFar.length > 0 ? { waves: wavesSoFar } : {}),
       ...(Object.keys(carriedSoFar).length > 0 ? { carried: carriedSoFar } : {}),
     };
@@ -344,12 +410,9 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
   let result;
   try {
     result = await runFanOut(derived.plan, derived.components, registry, {
-      env: args.env ?? "local",
+      env,
       releaseIdentity: () => (revision ? { revision } : {}),
-      // A completed component's recorded outputs win over a `--seed-outputs`
-      // entry for the same name, as a fresh apply's outputs merge over a seed in
-      // the driver: the record holds what this fan-out itself applied.
-      componentOutputs: { ...seededOutputs, ...priorOutputs },
+      componentOutputs,
       ...(gate ? { gate } : {}),
       ...(waveGate ? { waveGate } : {}),
       ...(waveGate
@@ -377,6 +440,7 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
             onComponentSettled: (settled, outputs) => {
               if (settled.status === "ok") {
                 completedSoFar.add(settled.component);
+                if (inputsNow[settled.component] !== undefined) inputsSoFar[settled.component] = inputsNow[settled.component]!;
                 if (outputs) outputsSoFar[settled.component] = outputs;
               } else if (settled.status === "fail") {
                 failedSoFar.push(settled.component);

package/src/cli/handlers/intent-trace.e2e.test.ts

@@ -0,0 +1,201 @@
+/**
+ * The why chain of `graph --intent` (#4023), from work item to production
+ * release. Everything runs in a temp repo with no remote, so nothing is
+ * pushed: a workspace with a work item, a commit whose trailer links it, a
+ * green tag, a real cut, a real `components promote --release` into prod that
+ * stops at its release gate, a real `chant approve`, and the promote that
+ * follows. Only the capability registry is replaced, so no deploy step
+ * reaches a cloud, and the member's graph, so the resource node resolves to
+ * its component file without building the member.
+ */
+
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { CapabilityRegistry, type DeployContext } from "../../components/capability";
+import type { DriverComponent } from "../../components/driver";
+import type { ParsedArgs } from "../registry";
+import { appendReleaseRecord, readReleaseLedger } from "../../lifecycle/release-ledger";
+import { readGateLedger } from "../../lifecycle/gate-ledger";
+import { cutRelease } from "../../lifecycle/release-cut";
+import { resetGateOrigin } from "../../lifecycle/gate-origin";
+import { contract, REPO } from "../../workspace/__fixtures__/contract-repo";
+import { intentGraph, type IntentDocument } from "../../workspace/intent";
+import intentSchema from "../../workspace/intent.schema.json";
+import type { ReleaseArtifact } from "../../lifecycle/release-store";
+import type { CompiledTarget, TargetCompiler } from "../../components/release-compile";
+
+const DIGEST = `sha256:${"0123456789abcdef".repeat(4)}`;
+
+const api: DriverComponent = {
+  name: "api",
+  deploy: [
+    { phase: "Publish", steps: [{ kind: "publish-image", from: "archive:api.tar" }] },
+    { phase: "Apply", steps: [{ kind: "gate", gate: "prod-release" }, { kind: "apply", template: "dist/api.template.json", imageRef: "@Publish.digest" }] },
+  ],
+};
+
+vi.mock("../../config", async () => {
+  const actual = await vi.importActual<typeof import("../../config")>("../../config");
+  return { ...actual, loadChantConfig: async () => ({ config: {} }) };
+});
+vi.mock("../../components/cli-support", () => ({
+  isComponentList: () => false,
+  resolveComponentTargets: async () => ({ success: true, targets: [api] }),
+}));
+vi.mock("../../components/fan-out-support", () => ({
+  fanOutRegistry: async () => {
+    const registry = new CapabilityRegistry();
+    registry.register({ kind: "publish-image", async run(_ctx: DeployContext) { return { digest: DIGEST, uri: `reg/api@${DIGEST}` }; } } as never);
+    registry.register({ kind: "apply", async run() { return {}; } } as never);
+    return registry;
+  },
+}));
+vi.mock("../../op/discover", () => ({ discoverOps: async () => ({ errors: [], ops: new Map() }) }));
+vi.mock("./run", () => ({ GATED_EXIT_CODE: 3 }));
+
+const { runComponentsPromote } = await import("./promote");
+const { recordGateApproval } = await import("./approve");
+
+function git(dir: string, ...args: string[]): string {
+  const r = spawnSync("git", args, { cwd: dir, encoding: "utf-8" });
+  if (r.status !== 0) throw new Error(`git ${args.join(" ")}: ${r.stderr}`);
+  return r.stdout.trim();
+}
+
+/** A compiler that compiles each environment to its own template and builds one image. */
+const compiler: TargetCompiler = {
+  async compile(env): Promise<CompiledTarget> {
+    return {
+      env,
+      params: [],
+      components: ["api"],
+      buildSteps: { api: [{ kind: "docker-build", context: "api", into: "api.tar" }] },
+      buildInputs: { api: ["api"] },
+      componentFiles: { api: "api.component.ts" },
+      templates: [{ component: "api", path: "dist/api.template.json", content: `{"env":"${env}"}\n` }],
+    };
+  },
+  async buildArtifacts(_env, components): Promise<ReleaseArtifact[]> {
+    return components.map((c) => ({ component: c, kind: "image" as const, path: `${c}.tar`, digest: DIGEST }));
+  },
+};
+
+function args(overrides: Partial<ParsedArgs>): ParsedArgs {
+  return {
+    command: "components", path: "promote", format: "", fix: false, watch: false, verbose: false, help: false, live: false,
+    migrateFrom: "staging", migrateTo: "prod", actor: "bob", runId: "run-9", ...overrides,
+  } as ParsedArgs;
+}
+const ctx = (a: Partial<ParsedArgs>) => ({ args: args(a), plugins: [] }) as never;
+
+const REF = join(REPO, "reference-workspace");
+const KIND_FILES: Record<string, string> = {
+  "work/work.kind.mjs": readFileSync(join(REF, "work", "work.kind.mjs"), "utf-8"),
+  "work/work.schema.json": readFileSync(join(REF, "work", "work.schema.json"), "utf-8"),
+  "decisions/decision.kind.mjs": readFileSync(join(REF, "decisions", "decision.kind.mjs"), "utf-8"),
+  "decisions/decision.schema.json": readFileSync(join(REF, "decisions", "decision.schema.json"), "utf-8"),
+};
+const W001 = `---\n${JSON.stringify({ schema: 1, id: "W-001", title: "Ship the api to prod", state: "open", implements: [], needs: [], constrains: ["path:api.component.ts"], evidence: [], opened_on: "2026-10-16", supersedes: [] }, null, 2)}\n---\n\n# W-001\n`;
+const DECLARATION = JSON.stringify({ name: "shop", schema: 1, members: [{ name: "api", dir: ".", kind: "other", because: "the api and its component" }] });
+const intent = contract(intentSchema);
+type Result = Exclude<IntentDocument, { error: unknown }>;
+
+describe("the why chain from work item to production release (#4023)", () => {
+  const cwd = process.cwd();
+  afterEach(() => {
+    process.chdir(cwd);
+    resetGateOrigin();
+    vi.restoreAllMocks();
+  });
+
+  test(
+    "the trace from the api's resource node walks W-001, the linked commit, its green tag, the cut, the release gate approval and the prod deploy",
+    async () => {
+      vi.spyOn(console, "error").mockImplementation(() => {});
+      vi.spyOn(console, "log").mockImplementation(() => {});
+      vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+      await withTestDir(async (dir) => {
+        git(dir, "init", "-q", "-b", "main");
+        git(dir, "config", "user.email", "t@chant.dev");
+        git(dir, "config", "user.name", "T");
+        const files: Record<string, string> = {
+          "chant.workspace.json": DECLARATION,
+          "chant.config.ts": `export default { environments: ["dev", "staging", "prod"] };\n`,
+          "api.component.ts": "export const api = {};\n",
+          "work/W-001-ship.md": W001,
+          ...KIND_FILES,
+        };
+        for (const [path, text] of Object.entries(files)) {
+          mkdirSync(join(dir, path, ".."), { recursive: true });
+          writeFileSync(join(dir, path), text);
+        }
+        git(dir, "add", ".");
+        git(dir, "commit", "-q", "-m", "the api and W-001");
+        // The work: a commit whose trailer names W-001, made green.
+        writeFileSync(join(dir, "api.component.ts"), "export const api = { port: 8081 };\n");
+        git(dir, "commit", "-q", "-am", "serve the api on 8081", "--trailer", "Chant-Record: work:W-001");
+        const sha = git(dir, "rev-parse", "HEAD");
+        git(dir, "tag", `ci/green/${sha}`, sha);
+        process.chdir(dir);
+
+        // The release is cut from the green commit, and promoted to prod through its release gate.
+        const cut = await cutRelease({ cwd: dir, compiler, label: "v1.0.0", actor: "alice", env: {}, now: () => new Date("2026-10-16T10:00:00.000Z") });
+        const releaseDigest = cut.release.releaseDigest;
+        await appendReleaseRecord({ component: "api", env: "staging", digest: DIGEST, gitSha: sha, runId: "run-1", timestamp: "2026-10-16T10:30:00.000Z", actor: "ci" }, { cwd: dir });
+        expect(await runComponentsPromote(ctx({ release: "v1.0.0" }))).toBe(3);
+        expect((await recordGateApproval("release", "prod-release", { origin: "cli", actor: "alice", cwd: dir, environment: "prod" })).ok).toBe(true);
+        expect(await runComponentsPromote(ctx({ release: "v1.0.0" }))).toBe(0);
+        const [deploy] = (await readReleaseLedger("prod", { cwd: dir })).records;
+        const [resolution] = (await readGateLedger("release", { cwd: dir })).resolutions;
+
+        const walk = async (region: string): Promise<Result> => {
+          const { doc } = await intentGraph({
+            cwd: dir,
+            region,
+            kinds: [join(dir, "work/work.kind.mjs")],
+            resolveNode: async (_cwd, _at, member, id) => (member === "api" && id === "api/api" ? { file: "api.component.ts", line: null } : null),
+          });
+          intent.expectValid(doc);
+          if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+          return doc;
+        };
+
+        // From the resource node: who asked for it, and who let it ship, in one read.
+        const doc = await walk("api/api");
+        expect(doc.nodes[0]).toMatchObject({ kind: "region", path: "api.component.ts", node: "api/api" });
+        const trace = doc.trace!;
+        expect(trace.reasons).toEqual([]);
+        const c = trace.commits.find((x) => x.sha === sha)!;
+        expect(c.work).toEqual({ state: "linked", items: [{ id: "work:W-001", node: "record:work/W-001", source: { ref: sha, field: "Chant-Record", value: "work:W-001" } }], problems: [] });
+        expect(c.tag).toMatchObject({ state: "green", green: { tag: `ci/green/${sha}` } });
+        expect(c.releases).toEqual([{ release: releaseDigest, link: "cut-from", source: { ref: `chant/lifecycle:_releases/${releaseDigest.replace(/:/g, "_")}.json`, field: "commit", value: sha } }]);
+        expect(c.deploys.map((d) => [d.env, d.link])).toEqual([["prod", "built-from"], ["staging", "built-from"]]);
+
+        const [release] = trace.releases;
+        expect(trace.releases).toHaveLength(1);
+        expect(release).toMatchObject({ releaseDigest, label: "v1.0.0", commit: sha, tag: { state: "green" }, cuts: [{ label: "v1.0.0", actor: "alice" }] });
+        // The gate approval: who, on which channel, when, and the change set the promote stored for it (#4022).
+        expect(release.gates).toEqual([
+          expect.objectContaining({ op: "release", gate: "prod-release", environment: "prod", resolvedBy: "alice", channel: "cli", at: resolution.timestamp, planDigest: resolution.planDigest, changeSet: resolution.planDigest, empty: false }),
+        ]);
+        expect(release.gates[0].changeSetSource).toEqual({ ref: `chant/lifecycle:_change-sets/${resolution.planDigest!.replace(/:/g, "_")}.json`, field: "planDigest", value: resolution.planDigest });
+
+        // The prod deploy record, admitted by that resolution.
+        const prod = trace.deploys.find((d) => d.env === "prod")!;
+        expect(release.deploys).toEqual([prod.id]);
+        expect(prod).toMatchObject({ component: "api", runId: deploy.runId, gitSha: sha, release: releaseDigest, approver: "alice", admittedBy: { op: "release", gate: "prod-release", resolvedBy: "alice", at: resolution.timestamp } });
+        // Staging was a plain deploy of the same commit: it names no release.
+        expect(trace.deploys.find((d) => d.env === "staging")).toMatchObject({ release: null, admittedBy: null });
+
+        // The same chain from the commit itself.
+        const byCommit = await walk(sha);
+        expect(byCommit.trace!.commits).toEqual([c]);
+        expect(byCommit.trace!.releases).toEqual(trace.releases);
+      });
+    },
+    240_000,
+  );
+});