@intentius/chant 0.124.27 → 0.124.29

package/src/cli/handlers/build.ts

@@ -7,6 +7,22 @@ import { generateComponentsPipeline } from "../../components/cli-support";
 import { loadChantConfigUpward, type ChantConfig } from "../../config";
 import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
 import { findWorkspaceRoot } from "../../project-root";
+import { resolvePromotionSource } from "../../components/promote-order";
+import type { PrLoopPipelineOptions } from "../../components/pr-pipeline";
+
+/**
+ * The `prLoop` generator option from `--pr-loop`'s flags (#3183): the gate
+ * and the branch, and with `--events-json` and `--report-url` (#4007) the
+ * flags the generated jobs pass to pr-plan and pr-apply.
+ */
+function prLoopOption(args: CommandContext["args"]): PrLoopPipelineOptions {
+  return {
+    ...(args.gate ? { gate: args.gate } : {}),
+    ...(args.branch ? { branch: args.branch } : {}),
+    ...(args.eventsJson ? { events: true } : {}),
+    ...(args.reportUrl ? { reportUrl: args.reportUrl } : {}),
+  };
+}
 
 /**
  * `chant build --components --generate <lexicon>` — generate mode (#563,
@@ -45,6 +61,24 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
+  // #4030: the generated promote job runs `promote --from <env> --to <promote-to>`,
+  // which the member's declared promotion order refuses when it skips a step.
+  // Refuse here, with the same code, rather than write a job that fails.
+  if (args.promoteTo) {
+    // Loaded here, not at the top: a build without --promote-to loads no workspace module (#2526).
+    const { promotionOrder } = await import("../../workspace/promotion-order");
+    const resolved = resolvePromotionSource({
+      order: promotionOrder(config.environments),
+      to: args.promoteTo,
+      from: args.env ?? "production",
+      ...(args.allowSkip ? { allowSkip: true } : {}),
+    });
+    if ("error" in resolved) {
+      console.error(formatError({ message: `${resolved.error.message} [${resolved.error.code}]`, hint: resolved.error.fix }));
+      return 1;
+    }
+  }
+
   // A project inside a workspace member gets that member's pipeline (#2542):
   // path-filtered, run in the member's directory, written to a file named
   // after the member and recorded as the member's generated file. The
@@ -62,11 +96,14 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
         lexicon,
         env: args.env,
         promoteTo: args.promoteTo,
+        ...(args.allowSkip ? { allowSkip: true } : {}),
         output: args.output,
         params: args.param,
         paramsFile: args.paramsFile,
         ...(args.waveGate ? { waveGate: { gate: args.waveGate, ...(args.canary?.length ? { canary: args.canary } : {}), ...(args.base ? { base: args.base } : {}) } } : {}),
-        ...(args.prLoop ? { prLoop: { ...(args.gate ? { gate: args.gate } : {}), ...(args.branch ? { branch: args.branch } : {}) } } : {}),
+        ...(args.prLoop ? { prLoop: prLoopOption(args) } : {}),
+        ...(args.image ? { image: args.image } : {}),
+        ...(args.beforeScript?.length ? { beforeScript: args.beforeScript } : {}),
       });
     } catch (err) {
       console.error(formatError({ message: memberPipeline.describeError(err) }));
@@ -84,15 +121,20 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
     {
       env: args.env,
       ...(args.promoteTo ? { promoteTo: args.promoteTo } : {}),
+      // #4030: the job passes --allow-skip through, so it is not refused again at deploy time.
+      ...(args.promoteTo && args.allowSkip
+        ? { promoteCommand: ["chant", "components", "promote", "--from", args.env ?? "production", "--to", args.promoteTo, "--allow-skip"] }
+        : {}),
       ...(plan ? { member: plan.member } : {}),
       // #3049: one job per wave of a gated-wave fan-out instead of one per component.
       ...(args.waveGate
         ? { gatedWaves: { gate: args.waveGate, ...(args.canary?.length ? { canary: args.canary } : {}), ...(args.base ? { base: args.base } : {}) } }
         : {}),
       // #3183: a plan job per pull request and an apply job per merge.
-      ...(args.prLoop
-        ? { prLoop: { ...(args.gate ? { gate: args.gate } : {}), ...(args.branch ? { branch: args.branch } : {}) } }
-        : {}),
+      ...(args.prLoop ? { prLoop: prLoopOption(args) } : {}),
+      // #4002: the job image and the lines that install what it lacks, chant itself included.
+      ...(args.image ? { image: args.image } : {}),
+      ...(args.beforeScript?.length ? { beforeScript: args.beforeScript } : {}),
     },
     args.sandbox,
     paramsResolution.provenance,

package/src/cli/handlers/change-set.ts

@@ -1,10 +1,12 @@
 import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import { CHANGE_SET_CONTRACT, CHANGE_SET_SCHEMA_ID, type ChangeSetDocument } from "../../change-set";
 import { GITHUB_COMMENT_LIMIT, groupChangeSet, renderPlanSummaryMarkdown, renderPlanSummaryText } from "../../plan-summary";
-import { formatError } from "../format";
+import { formatError, formatWarning } from "../format";
 import type { CommandContext } from "../registry";
 
 const USAGE = "chant change-set summary <change-set.json> [--format text|json|markdown] [--limit <chars>]";
+const SHOW_USAGE = "chant change-set show <digest> [--member <name>] [--json]";
 
 /**
  * `chant change-set summary <file>` (#3188): the grouped plan summary of a
@@ -42,3 +44,49 @@ export async function runChangeSetSummary(ctx: CommandContext): Promise<number>
   else process.stdout.write(renderPlanSummaryText(summary));
   return 0;
 }
+
+/**
+ * `chant change-set show <digest>` (#4022): the change-set document a gate
+ * bound, stored on `chant/lifecycle` under its digest, with each entry's
+ * graph node. `--json` prints the read contract's `change-set-show`
+ * document (`../../workspace/change-set-show.ts`); without it, the grouped
+ * summary and each entry with its node. `--member` reads a workspace
+ * member's ledger from anywhere in the checkout. Exit 1 when nothing is
+ * stored under the digest.
+ */
+export async function runChangeSetShow(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const digest = args.extraPositional;
+  const { changeSetShowDocument, CHANGE_SET_DIGEST_PATTERN } = await import("../../workspace/change-set-show");
+  if (!digest || !CHANGE_SET_DIGEST_PATTERN.test(digest)) {
+    console.error(formatError({ message: digest ? `${digest} is not a change-set digest` : "change-set show needs the digest a gate binds", hint: SHOW_USAGE }));
+    return 1;
+  }
+  if ((args.members?.length ?? 0) > 1) {
+    console.error(formatError({ message: `change-set show reads one member, not ${args.members!.join(", ")}`, hint: SHOW_USAGE }));
+    return 1;
+  }
+  const member = args.members?.[0]?.split("/").filter(Boolean);
+  const doc = await changeSetShowDocument({ cwd: resolve("."), digest, ...(member ? { member } : {}) });
+  if (args.json) {
+    console.log(JSON.stringify(doc, null, 2));
+    return "error" in doc || doc.changeSet === null ? 1 : 0;
+  }
+  if ("error" in doc) {
+    console.error(formatError({ message: doc.error.message, hint: SHOW_USAGE }));
+    return 1;
+  }
+  if (doc.reason) console.error(formatWarning({ message: doc.reason.message }));
+  if (doc.changeSet === null) {
+    if (!doc.reason) console.error(formatError({ message: `no change set is stored under ${digest}${doc.member ? ` for member ${doc.member}` : ""}`, hint: "A pull-request or release gate stores the change set it binds; a component gate binds a lifecycle plan and stores none." }));
+    return 1;
+  }
+  process.stdout.write(renderPlanSummaryText(groupChangeSet(doc.changeSet)));
+  const graph = doc.changeSet.graph;
+  console.log(graph ? `\nNodes from the graph of ${graph.member ?? "this project"}${graph.at ? ` at ${graph.at.slice(0, 12)}` : ""}:` : "\nNo graph was read, so no entry has a node.");
+  for (const e of doc.changeSet.entries) {
+    if (e.action === "no-op" || e.action === "read") continue;
+    console.log(`  ${e.action.padEnd(8)} ${e.member}  ${e.address}${e.deposed ? ` (deposed ${e.deposed})` : ""}  ${e.node ?? "(no node)"}`);
+  }
+  return 0;
+}

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

@@ -52,6 +52,7 @@ const sealedGates = new Set<string>();
 const { CapabilityRegistry } = await import("../../components/capability");
 const { memoryGateLedgerPort } = await import("../../op/gate");
 const { runComponentsFanOut } = await import("./fan-out");
+const { checkRunEventLines } = await import("../../workspace/__fixtures__/run-event-check");
 
 let gateLedger = memoryGateLedgerPort();
 
@@ -232,7 +233,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();
@@ -622,3 +624,228 @@ describe("gated waves (#3049): one gate per wave, bound to the wave's set digest
     expect(stderr()).toContain("--wave runs one wave");
   });
 });
+
+describe("--events-json (#4041)", () => {
+  const lines = () => stdoutLines.filter((l) => l.startsWith('{"$schema"'));
+
+  test("a fan-out over the set: the gate is a gate phase settled gated, and nothing after it starts", async () => {
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", gate: "release", eventsJson: true }))).toBe(3);
+    const events = checkRunEventLines(lines());
+    expect(events[0]).toMatchObject({ type: "run-start", kind: "component", waves: [["net"], ["cluster-a", "cluster-b"], ["app-one", "app-three", "app-two"]] });
+    expect(events.map((e) => e.type)).toEqual(["run-start", "phase-start", "step-start", "gate-waiting", "step-settle", "phase-settle", "run-settle"]);
+    expect(events.find((e) => e.type === "gate-waiting")).toMatchObject({ component: null, phase: "gate", step: "gate:release", op: "fan-out", gate: "release" });
+    expect(events.at(-1)).toMatchObject({ status: "gated" });
+  });
+
+  test("approved, the gate resolves and every wave and component follows, each step started before it settles", async () => {
+    await runComponentsFanOut(ctx({ base: "main", env: "test", gate: "release" }));
+    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,
+      }],
+    });
+    stdoutLines = [];
+    failing = ["cluster-b"];
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", gate: "release", eventsJson: true }))).toBe(1);
+    const events = checkRunEventLines(lines());
+    expect(events.find((e) => e.type === "gate-resolved")).toMatchObject({ gate: "release", resolvedBy: "operator" });
+    expect(events.filter((e) => e.type === "wave-start").map((e) => (e as { wave: number }).wave)).toEqual([1, 2, 3]);
+    expect(events.find((e) => e.type === "component-settle" && e.component === "cluster-b")).toMatchObject({ status: "failed" });
+    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));
+    expect(progress).toEqual([
+      { type: "run-start", waves: [["net"], ["cluster-a", "cluster-b"], ["app-one", "app-three", "app-two"]] },
+      { type: "run-done", status: "gated" },
+    ]);
+  });
+
+  test("beside --progress-json it is refused", async () => {
+    expect(await runComponentsFanOut(ctx({ base: "main", eventsJson: true, progressJson: true }))).toBe(1);
+    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");
+  });
+});

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,9 +58,11 @@ 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";
+import { openCliRunEvents, refusesBothStreams } from "../run-events";
 import { summaryLedgerPrefix, writeGatedRunSummary } from "../../op/gate-summary";
 import { approveCommand, gateIsSealed } from "../../op/gate";
 import { getHeadCommit } from "../../lifecycle/git";
@@ -60,7 +71,7 @@ import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
 import { formatError, formatInfo, formatWarning } from "../format";
 import { FAN_OUT_GATE_OP } from "../../op/gate-name";
 import { resolveBuildRoot } from "./lifecycle";
-import { GATED_EXIT_CODE, recordAutoReleasesForRun } from "./run";
+import { GATED_EXIT_CODE, autoReleaseRun, recordAutoReleasesForRun } from "./run";
 import type { CommandContext } from "../registry";
 
 /**
@@ -172,10 +183,11 @@ export async function resolveChangedUnits(
  * chant components fan-out --base <ref> | --from-affected <file>
  *   [--head <ref>] [--include-dependents] [--env <env>] [--gate <name>]
  *   [--dry-run] [--json] [--resume <file>] [--seed-outputs <file>]
- *   [--dump-outputs <file>] [--progress-json]
+ *   [--dump-outputs <file>] [--progress-json | --events-json]
  */
 export async function runComponentsFanOut(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
+  if (refusesBothStreams(args)) return 1;
   const projectPath = resolve(".");
   const { config } = await loadChantConfig(projectPath).catch(() => ({ config: {} as ChantConfig }));
 
@@ -251,7 +263,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> = {};
@@ -275,11 +292,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.
@@ -317,6 +351,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;
@@ -328,12 +363,18 @@ 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 } : {}),
     };
     writeFanOutAttempt(resumePath, attempt);
   };
 
+  // The run id the release records carry, chosen before the run so that
+  // `--events-json` (#4041) names the run by it too.
+  const release = autoReleaseRun(`fan-out-${Date.now()}`);
+  const events = await openCliRunEvents(args, { kind: "component", name: `fan-out ${derived.plan.order.join(",")}`, runId: release.runId, cwd: projectPath });
+
   let result;
   try {
     result = await runFanOut(derived.plan, derived.components, registry, {
@@ -364,11 +405,13 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
           }
         : {}),
       ...(args.progressJson ? { onProgress: ndjsonProgressSink() } : {}),
+      ...(events ? { onRunEvent: events.emit } : {}),
       ...(resumePath
         ? {
             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);
@@ -379,6 +422,7 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
         : {}),
     });
   } catch (err) {
+    events?.settle("failed", err instanceof Error ? err.message : String(err));
     // `--wave <n>` reached before an earlier wave applied: nothing ran.
     if (err instanceof EarlierWaveNotAppliedError) {
       console.error(formatError({ message: err.message }));
@@ -386,6 +430,8 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
     }
     throw err;
   }
+  // The fan-out settles the stream; this only ends one it left open.
+  events?.settle(result.status === "fail" ? "failed" : result.status);
 
   if (args.dumpOutputs) {
     const dumpPath = resolve(args.dumpOutputs);
@@ -420,8 +466,9 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
     await recordAutoReleasesForRun(
       result.results,
       args.env ?? "local",
-      `fan-out-${Date.now()}`,
+      release.runId,
       resolveAutoReleaseDisabled(config, args.noReleaseRecord),
+      release.runOrigin,
     );
   }