@intentius/chant 0.70.0 → 0.71.0

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

@@ -0,0 +1,336 @@
+/**
+ * `chant components fan-out` (#2420) — run a change out across the components
+ * downstream of it, in an order chant derives from the source.
+ *
+ * #2417 built the four pieces this command joins (`componentsForUnits`,
+ * `planFanOut`, `remainingFanOut`, `runFanOut`, all in ../../components/) and
+ * left them reachable only from their own tests. `chant lifecycle affected`
+ * produces the stack-level change signal at one end; `runFanOut` consumes a
+ * plan at the other; this is the line between them.
+ *
+ * ## Why a sibling command rather than a third `--components` selector
+ *
+ * `chant run --components all` stops the whole run at the first failed
+ * component, and it should: there the user asked for everything, so a failure
+ * means the estate is in a state nobody described. A fan-out deliberately does
+ * the opposite, skipping the failure's own subtree and letting independent
+ * branches finish (#2419 added a second runner for exactly that reason). Two
+ * opposite failure semantics behind one flag's third value would be a trap. The
+ * flags differ too: a fan-out is parameterised by a change signal, which
+ * `chant run` has no business growing a `--base` for.
+ *
+ * ## The loop
+ *
+ * ```
+ * chant components fan-out --base main --env prod --dry-run
+ * chant components fan-out --base main --env prod --gate release --resume .chant/fan-out.json
+ * chant approve fan-out release --plan sha256:...
+ * chant components fan-out --base main --env prod --gate release --resume .chant/fan-out.json
+ * ```
+ *
+ * The last two lines are the same command twice, which is the point: an attempt
+ * that stopped is finished by repeating it, not by hand-picking what is left.
+ * `--resume` carries the earlier attempt's progress, `remainingFanOut` narrows
+ * the plan before the gate is decided, and the digest is carried rather than
+ * recomputed, so the approval still stands.
+ */
+
+import { resolve, dirname } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { loadChantConfig, resolveAutoReleaseDisabled, type ChantConfig } from "../../config";
+import { affectedStacks } from "../../lifecycle/affected";
+import { deriveFanOut, fanOutRegistry } from "../../components/fan-out-support";
+import { runFanOut } from "../../components/fan-out-run";
+import { renderFanOutHuman, renderFanOutJson, renderFanOutPlan } from "../../components/fan-out-output";
+import { ndjsonProgressSink } from "../../components/run-progress";
+import { writeGatedRunSummary } from "../../op/gate-summary";
+import { remainingFanOut, type ChangedUnits, type FanOutProgress } from "../../components/fan-out";
+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 type { CommandContext } from "../registry";
+
+
+
+/**
+ * What an attempt left behind, and what the next one reads (`--resume`).
+ *
+ * The digest is stored alongside the progress because progress is only
+ * meaningful for the plan it was made against. A fan-out derived from different
+ * source is a different fan-out, and carrying "cluster-a already applied" into
+ * it would be a claim about work nobody did.
+ */
+interface FanOutAttempt {
+  digest: string;
+  completed: string[];
+  failed: string[];
+}
+
+function readAttempt(path: string): FanOutAttempt | undefined {
+  if (!existsSync(path)) return undefined;
+  const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<FanOutAttempt>;
+  return {
+    digest: typeof parsed.digest === "string" ? parsed.digest : "",
+    completed: Array.isArray(parsed.completed) ? parsed.completed.filter((n): n is string => typeof n === "string") : [],
+    failed: Array.isArray(parsed.failed) ? parsed.failed.filter((n): n is string => typeof n === "string") : [],
+  };
+}
+
+function writeAttempt(path: string, attempt: FanOutAttempt): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(attempt, null, 2) + "\n");
+}
+
+/**
+ * The stack-level change signal, from whichever end the invocation supplied.
+ *
+ * `--base` re-derives it here, which is the one-command shape a developer
+ * wants. `--from-affected` reads what `chant lifecycle affected --json` already
+ * wrote, which is the shape a CI job wants when an earlier step has run the
+ * diff and there is no reason to build twice. Exactly one, because defaulting
+ * either way would let a stale file silently beat a fresh `--base` or the other
+ * way round.
+ *
+ * `dependents` is folded into `changed` when it is present. It is only present
+ * when somebody asked for it (`--include-dependents`), and a stack that
+ * consumes a changed export is affected at stack granularity in the same way a
+ * changed component is at component granularity.
+ */
+async function resolveChangedUnits(
+  ctx: CommandContext,
+  config: ChantConfig,
+): Promise<{ units: ChangedUnits } | { error: string; hint?: string }> {
+  const { args } = ctx;
+  const fromFile = args.fromAffected;
+  if (args.base && fromFile) {
+    return {
+      error: "--base and --from-affected both name a change signal",
+      hint: "Pass --base <ref> to derive it here, or --from-affected <file> to read one `chant lifecycle affected --json` already wrote.",
+    };
+  }
+
+  if (fromFile) {
+    let parsed: { changed?: unknown; dependents?: unknown; indeterminate?: unknown };
+    try {
+      parsed = JSON.parse(readFileSync(resolve(fromFile), "utf8"));
+    } catch (err) {
+      return { error: `--from-affected: could not read "${fromFile}": ${err instanceof Error ? err.message : String(err)}` };
+    }
+    const names = (value: unknown): string[] =>
+      Array.isArray(value) ? value.filter((n): n is string => typeof n === "string") : [];
+    if (!Array.isArray(parsed.changed)) {
+      return {
+        error: `--from-affected: "${fromFile}" has no "changed" array`,
+        hint: "It should be the output of `chant lifecycle affected --base <ref> --json`.",
+      };
+    }
+    return {
+      units: {
+        changed: [...new Set([...names(parsed.changed), ...names(parsed.dependents)])].sort(),
+        indeterminate: names(parsed.indeterminate),
+      },
+    };
+  }
+
+  if (!args.base) {
+    return {
+      error: "A change signal is required: chant components fan-out --base <ref> [--head <ref>]",
+      hint: "Or pass --from-affected <file> with the JSON `chant lifecycle affected --base <ref> --json` wrote.",
+    };
+  }
+
+  try {
+    const result = await affectedStacks({
+      // Components are discovered from the current directory, the convention
+      // every component command follows. In a multi-stack project the diff
+      // reads the same root, because `stacks[].src` is written relative to it.
+      projectPath: config.stacks?.length ? resolve(".") : resolveBuildRoot(args, config),
+      serializers: ctx.plugins.map((p) => p.serializer),
+      baseRef: args.base,
+      headRef: args.head,
+      includeDependents: args.includeDependents,
+      // A project that declares its stacks gets an answer keyed by stack name,
+      // which is the name a component's deploy step uses. Without this the diff
+      // answers by lexicon partition and the join below claims none of it.
+      ...(config.stacks ? { stacks: config.stacks } : {}),
+    });
+    return {
+      units: {
+        changed: [...new Set([...result.changed, ...result.dependents])].sort(),
+        indeterminate: result.indeterminate,
+      },
+    };
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * 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]
+ */
+export async function runComponentsFanOut(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const projectPath = resolve(".");
+  const { config } = await loadChantConfig(projectPath).catch(() => ({ config: {} as ChantConfig }));
+
+  const paramsResolution = resolveCliBuildParams(config.buildParams, {
+    cli: parseParamFlags(args.param),
+    paramsFile: args.paramsFile,
+    verbose: args.verbose,
+  });
+  if (!paramsResolution.success) {
+    for (const message of paramsResolution.errors) console.error(message);
+    return 1;
+  }
+
+  const signal = await resolveChangedUnits(ctx, config);
+  if ("error" in signal) {
+    console.error(formatError({ message: signal.error, ...(signal.hint ? { hint: signal.hint } : {}) }));
+    return 1;
+  }
+
+  let derived;
+  try {
+    derived = await deriveFanOut({
+      path: projectPath,
+      units: signal.units,
+      sandbox: args.sandbox,
+      buildParams: paramsResolution.provenance,
+      config,
+    });
+  } catch (err) {
+    // A cycle or an unknown `dependsOn` refuses here, over the whole graph and
+    // before anything is selected (#2417). The message names the members.
+    console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    return 1;
+  }
+  if (!derived.success) {
+    console.error(formatError({ message: derived.error ?? "Could not discover components" }));
+    return 1;
+  }
+
+  // A changed stack no component deploys is a hole in this fan-out's coverage.
+  // Reporting it is the whole reason `componentsForUnits` returns it.
+  if (derived.signal.unclaimed.length > 0) {
+    console.error(formatWarning({
+      message: `no component deploys these changed unit(s): ${derived.signal.unclaimed.join(", ")}`,
+      hint: "They are outside this fan-out. Deploy them another way, or give a component a step that names them.",
+    }));
+  }
+
+  const gate = args.gate ? { op: FAN_OUT_GATE_OP, gate: args.gate } : undefined;
+
+  // `--resume`: what an earlier attempt at this same plan finished. Read before
+  // the dry-run branch so a plan-only invocation shows what is actually left
+  // rather than what the fan-out looked like the first time. Narrowing for the
+  // 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;
+  let priorCompleted: string[] = [];
+  let progress: FanOutProgress | undefined;
+  if (resumePath) {
+    let attempt: FanOutAttempt | undefined;
+    try {
+      attempt = readAttempt(resumePath);
+    } catch (err) {
+      console.error(formatError({ message: `--resume: could not read "${args.resume}": ${err instanceof Error ? err.message : String(err)}` }));
+      return 1;
+    }
+    if (attempt && attempt.digest !== derived.plan.digest) {
+      console.error(formatWarning({
+        message: `--resume: "${args.resume}" records a different fan-out (${attempt.digest || "no digest"}), so its progress does not apply here`,
+        hint: "The derivation changed, which makes this a different change. Everything selected will run.",
+      }));
+    } else if (attempt) {
+      // Only `completed` is carried forward. The earlier attempt's failures are
+      // recorded in the file for whoever has to read it, but feeding them back
+      // 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;
+      progress = { completed: attempt.completed };
+    }
+  }
+
+  if (args.dryRun) {
+    // `remainingFanOut` carries the digest rather than minting a new one, so
+    // the digest printed here is the same string that approves the real run.
+    const plan = progress ? remainingFanOut(derived.plan, derived.components, progress) : derived.plan;
+    if (args.json) renderFanOutJson(plan);
+    else renderFanOutPlan(plan, { ...(gate ? { gate } : {}) });
+    return 0;
+  }
+
+  const seededOutputs: Record<string, Record<string, unknown>> = {};
+  for (const file of args.seedOutputs ?? []) {
+    try {
+      Object.assign(seededOutputs, JSON.parse(readFileSync(resolve(file), "utf8")));
+    } catch (err) {
+      console.error(formatError({ message: `--seed-outputs: could not read "${file}": ${err instanceof Error ? err.message : String(err)}` }));
+      return 1;
+    }
+  }
+
+  const registry = await fanOutRegistry(projectPath, config);
+  const result = await runFanOut(derived.plan, derived.components, registry, {
+    env: args.env ?? "local",
+    componentOutputs: seededOutputs,
+    ...(gate ? { gate } : {}),
+    ...(progress ? { progress } : {}),
+    ...(args.progressJson ? { onProgress: ndjsonProgressSink() } : {}),
+  });
+
+  if (args.dumpOutputs) {
+    const dumpPath = resolve(args.dumpOutputs);
+    mkdirSync(dirname(dumpPath), { recursive: true });
+    writeFileSync(dumpPath, JSON.stringify(result.componentOutputs, null, 2));
+  }
+
+  // Written even on a failure and even on a gate: the next attempt needs to
+  // know what this one got through, and a gated attempt got through nothing,
+  // which is itself worth recording against this plan's digest.
+  if (resumePath) {
+    writeAttempt(resumePath, {
+      digest: result.plan.digest,
+      completed: [...new Set([...priorCompleted, ...result.completed])].sort(),
+      failed: result.failed,
+    });
+  }
+
+  if (args.json) renderFanOutJson(result);
+  else renderFanOutHuman(result, { ...(gate ? { gate } : {}) });
+
+  // The same durable trace `chant run --components` leaves (#597), for the
+  // components this fan-out actually applied. A partial fan-out records the
+  // branches that finished and nothing else, which is the whole reason the
+  // runner reports `completed` separately from `failed`.
+  if (result.status !== "gated") {
+    await recordAutoReleasesForRun(
+      result.results,
+      args.env ?? "local",
+      `fan-out-${Date.now()}`,
+      resolveAutoReleaseDisabled(config, args.noReleaseRecord),
+    );
+  }
+
+  if (result.status === "gated" && result.gate) {
+    const pending = result.gate;
+    console.error(formatInfo(`approve : chant approve ${pending.op} ${pending.gate} --plan ${result.plan.digest}`));
+    writeGatedRunSummary({
+      op: pending.op,
+      gate: pending.gate,
+      ...(pending.description ? { description: pending.description } : {}),
+      expiresAt: pending.expiresAt,
+      ...(pending.url ? { url: pending.url } : {}),
+      ...(pending.planDigest ? { planDigest: pending.planDigest } : {}),
+    });
+    return GATED_EXIT_CODE;
+  }
+
+  return result.status === "ok" ? 0 : 1;
+}

package/src/cli/handlers/lifecycle.test.ts

@@ -29,6 +29,7 @@ const loadChantConfigMock = vi.fn();
 const pushLifecycleMock = vi.fn();
 const readBlobFromPathMock = vi.fn();
 const writeBlobToPathMock = vi.fn();
+const affectedStacksMock = vi.fn();
 
 vi.mock("../../build", () => ({ build: (...args: unknown[]) => buildMock(...args) }));
 vi.mock("../../lifecycle/git", () => ({
@@ -54,7 +55,11 @@ vi.mock("../../config", async () => {
   };
 });
 
-const { runLifecycleDiff, runLifecyclePlan, runLifecycleSnapshot, runLifecycleShow, runLifecycleLog, runLifecycleTeardown, runLifecycleWhoami, runLifecycleUnknown } = await import("./lifecycle");
+vi.mock("../../lifecycle/affected", () => ({
+  affectedStacks: (...args: unknown[]) => affectedStacksMock(...args),
+}));
+
+const { runLifecycleDiff, runLifecyclePlan, runLifecycleSnapshot, runLifecycleShow, runLifecycleLog, runLifecycleTeardown, runLifecycleWhoami, runLifecycleUnknown, runLifecycleAffected } = await import("./lifecycle");
 
 function makeArgs(overrides: Partial<ParsedArgs>): ParsedArgs {
   return {
@@ -2107,3 +2112,71 @@ describe("runLifecycleWhoami (#1982)", () => {
     }
   });
 });
+
+describe("runLifecycleAffected (#2420)", () => {
+  let stdoutBuf: string[];
+  let stderrBuf: string[];
+
+  beforeEach(() => {
+    stdoutBuf = [];
+    stderrBuf = [];
+    vi.spyOn(console, "log").mockImplementation((s: string) => { stdoutBuf.push(s); });
+    vi.spyOn(console, "error").mockImplementation((s: string) => { stderrBuf.push(s); });
+    loadChantConfigMock.mockReset();
+    affectedStacksMock.mockReset();
+    affectedStacksMock.mockResolvedValue({ changed: ["api-stack"], dependents: [], indeterminate: [] });
+  });
+
+  afterEach(() => vi.restoreAllMocks());
+
+  const multiStack = [
+    { name: "api-stack", src: "stacks/api" },
+    { name: "worker-stack", src: "stacks/worker" },
+  ];
+
+  function affectedCtx(overrides: Partial<ParsedArgs> = {}) {
+    return {
+      args: makeArgs({ command: "lifecycle", path: "affected", base: "main", ...overrides }),
+      plugins: [], serializers: [],
+    };
+  }
+
+  test("passes config.stacks through, so the answer is keyed by stack name", async () => {
+    loadChantConfigMock.mockResolvedValue({ config: { stacks: multiStack } });
+    expect(await runLifecycleAffected(affectedCtx())).toBe(0);
+    expect(affectedStacksMock).toHaveBeenCalledWith(expect.objectContaining({ stacks: multiStack }));
+    expect(stdoutBuf.join("\n")).toContain("api-stack");
+  });
+
+  test("a project with no stacks declared passes none — same single-root build", async () => {
+    loadChantConfigMock.mockResolvedValue({ config: {} });
+    expect(await runLifecycleAffected(affectedCtx())).toBe(0);
+    expect(affectedStacksMock.mock.calls[0][0].stacks).toBeUndefined();
+  });
+
+  test("multi-stack + --include-dependents says where the downstream relation lives", async () => {
+    loadChantConfigMock.mockResolvedValue({ config: { stacks: multiStack } });
+    expect(await runLifecycleAffected(affectedCtx({ includeDependents: true }))).toBe(0);
+    const stderr = stderrBuf.join("\n");
+    expect(stderr).toContain("dependsOn");
+    expect(stderr).toContain("chant components fan-out");
+  });
+
+  test("no note for a single-root project, even with --include-dependents", async () => {
+    loadChantConfigMock.mockResolvedValue({ config: {} });
+    expect(await runLifecycleAffected(affectedCtx({ includeDependents: true }))).toBe(0);
+    expect(stderrBuf.join("\n")).not.toContain("chant components fan-out");
+  });
+
+  test("no note for a multi-stack project when dependents were not asked for", async () => {
+    loadChantConfigMock.mockResolvedValue({ config: { stacks: multiStack } });
+    expect(await runLifecycleAffected(affectedCtx())).toBe(0);
+    expect(stderrBuf.join("\n")).not.toContain("chant components fan-out");
+  });
+
+  test("--base is required", async () => {
+    loadChantConfigMock.mockResolvedValue({ config: {} });
+    expect(await runLifecycleAffected(affectedCtx({ base: undefined }))).toBe(1);
+    expect(affectedStacksMock).not.toHaveBeenCalled();
+  });
+});

package/src/cli/handlers/lifecycle.ts

@@ -1871,6 +1871,19 @@ function printSnapshotTable(snapshot: LifecycleSnapshot): void {
  * Read-only: report which stacks a change affects (directly-changed via artifact
  * diff, dependents via the cross-stack graph, external-input as indeterminate).
  * Returns the set; fanning plan/apply over it is an Op the user composes.
+ *
+ * `config.stacks` is passed through, so on a multi-stack project the answer is
+ * keyed by deployed **stack name** — the name a component's `cfn-deploy` step
+ * uses — instead of by lexicon partition. That is what lets `chant components
+ * fan-out` join a change set to the components that deploy it; an aws-only
+ * estate of fifteen stacks used to answer "aws" no matter which one moved. A
+ * project with no `stacks` declared is untouched: one build of the source root,
+ * one lexicon-keyed answer.
+ *
+ * The cost of per-stack mode is that `dependents` comes back empty (the build
+ * carries cross-lexicon edges, not stack ones), so `--include-dependents` prints
+ * a note saying where the downstream relation actually lives rather than showing
+ * an empty list as if it meant "nothing downstream".
  */
 export async function runLifecycleAffected(ctx: CommandContext): Promise<number> {
   const { args, plugins } = ctx;
@@ -1882,13 +1895,17 @@ export async function runLifecycleAffected(ctx: CommandContext): Promise<number>
   }
 
   const { config } = await loadChantConfig(resolve("."));
-  const projectPath = resolveBuildRoot(args, config);
+  // A multi-stack project's `stacks[].src` entries are written relative to the
+  // project root, and they are themselves the scoping, so `--src`/`sourceDir`
+  // does not narrow the root a second time (see `AffectedStacksOptions.stacks`).
+  const projectPath = config.stacks?.length ? resolve(".") : resolveBuildRoot(args, config);
 
   let result;
   try {
     result = await affectedStacks({
       projectPath,
       serializers: plugins.map((p) => p.serializer),
+      stacks: config.stacks,
       baseRef: args.base,
       headRef: args.head,
       includeDependents: args.includeDependents,
@@ -1898,6 +1915,17 @@ export async function runLifecycleAffected(ctx: CommandContext): Promise<number>
     return 1;
   }
 
+  // Per-stack mode has no stack graph to walk, so an empty `dependents` here
+  // means "not computed", not "nothing downstream". Say so on stderr — silently
+  // handing back an empty list is the failure this command exists to avoid.
+  const multiStack = (config.stacks?.length ?? 0) > 0;
+  if (multiStack && args.includeDependents) {
+    console.error(formatWarning({
+      message: "Dependents are not computed for a multi-stack project: the downstream relation between deployed stacks is stated by the components' dependsOn, not by the build.",
+      hint: "Run chant components fan-out to walk it.",
+    }));
+  }
+
   if (args.json) {
     console.log(JSON.stringify(result, null, 2));
     return 0;

package/src/cli/handlers/operator.test.ts

@@ -513,6 +513,28 @@ describe("runApprove", () => {
     errSpy.mockRestore();
   });
 
+  test("the fan-out op is not reported as a missing *.op.ts, and the hint names the right command (#2420)", async () => {
+    discoverOpsMock.mockResolvedValue({ ops: new Map(), errors: [] });
+    seedPending("fan-out", "release", PLAN_A);
+    appendGateResolutionMock.mockResolvedValue({
+      commit: "sha",
+      record: { version: 1, op: "fan-out", gate: "release", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z", planDigest: PLAN_A },
+    });
+    const lines: string[] = [];
+    const errSpy = vi.spyOn(console, "error").mockImplementation((...a: unknown[]) => {
+      lines.push(a.map(String).join(" "));
+    });
+
+    const code = await runApprove(ctx({ path: "fan-out", extraPositional: "release", actor: "alex" }));
+
+    expect(code).toBe(0);
+    const out = lines.join("\n");
+    expect(out).not.toContain("was not found among discovered");
+    expect(out).toContain("Repeat the `chant components fan-out` command");
+    expect(out).not.toContain("chant run fan-out");
+    errSpy.mockRestore();
+  });
+
   test("warns (but still records) when the op isn't among discovered *.op.ts declarations", async () => {
     discoverOpsMock.mockResolvedValue({ ops: new Map(), errors: [] });
     seedPending("unknown-op", "g", PLAN_A);

package/src/cli/handlers/operator.ts

@@ -35,6 +35,7 @@ import {
   resolveApprovalUrl, isApprovalUrl,
 } from "../../lifecycle/gate-ledger";
 import { isPlanDigest } from "../../lifecycle/plan-digest";
+import { FAN_OUT_GATE_OP } from "../../op/gate-name";
 import { pushLifecycle, requireLifecycleLedger } from "../../lifecycle/git";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
 import type { CommandContext } from "../registry";
@@ -677,7 +678,9 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
         (pushed ? "" : " (local only — the push did not land)"),
     ));
     console.error(formatInfo(
-      `The next \`chant run ${opName}\` decides this gate from scratch and records a fresh pending fact.`,
+      opName === FAN_OUT_GATE_OP
+        ? `The next \`chant components fan-out\` decides this gate from scratch and records a fresh pending fact.`
+        : `The next \`chant run ${opName}\` decides this gate from scratch and records a fresh pending fact.`,
     ));
     return 0;
   }
@@ -696,7 +699,9 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
 
   console.error(formatInfo(
     `This records the resolution as a fact; it does not itself re-run anything. ` +
-      `Run \`chant run ${opName}\` and it walks through gate "${gate}".`,
+      (opName === FAN_OUT_GATE_OP
+        ? `Repeat the \`chant components fan-out\` command and it walks through gate "${gate}".`
+        : `Run \`chant run ${opName}\` and it walks through gate "${gate}".`),
   ));
   return 0;
 }
@@ -742,7 +747,10 @@ export async function recordGateApproval(
   opts: GateApprovalOptions,
 ): Promise<GateApprovalOutcome> {
   const { ops } = await discoverOps();
-  if (!ops.has(opName)) {
+  // `fan-out` is the op name every `chant components fan-out` gate is recorded
+  // under (../handlers/fan-out.ts). It is a command rather than a declaration,
+  // so there is no `*.op.ts` to find and nothing is wrong when none is there.
+  if (!ops.has(opName) && opName !== FAN_OUT_GATE_OP) {
     console.error(formatWarning({
       message: `Op "${opName}" was not found among discovered *.op.ts declarations — recording the resolution anyway`,
     }));

package/src/cli/handlers/run.ts

@@ -570,8 +570,14 @@ export async function runOp(ctx: CommandContext): Promise<number> {
  * failure (`reason: "error"`) is surfaced, as a warning — never a nonzero
  * exit, since the deploy itself already succeeded and a ledger-write hiccup
  * must not retroactively fail it.
+ *
+ * Exported for `chant components fan-out` (#2420), which applies components
+ * through a different runner and would otherwise leave no trace in the release
+ * ledger for work `chant run --components` records. Each result is filtered on
+ * its own `ok`, so a fan-out that partly succeeded records exactly the
+ * components that did.
  */
-async function recordAutoReleasesForRun(
+export async function recordAutoReleasesForRun(
   results: DriverComponentResult[],
   env: string,
   runId: string,

package/src/cli/main.ts

@@ -26,6 +26,7 @@ import { runCarveApply } from "./handlers/carve-apply";
 import { runCarveStatus } from "./handlers/carve-status";
 import { runLifecycleSnapshot, runLifecycleShow, runLifecycleDiff, runLifecycleRollback, runLifecyclePlan, runLifecycleAffected, runLifecycleLog, runLifecycleTeardown, runLifecycleWhoami, runLifecycleUnknown } from "./handlers/lifecycle";
 import { runComponentsStatus, runComponentsReleaseRecord, runComponentsExport, runComponentsUnknown } from "./handlers/components";
+import { runComponentsFanOut } from "./handlers/fan-out";
 import { runScenarioCheck, runScenarioUnknown } from "./handlers/scenario";
 import { runGraph } from "./handlers/graph";
 import { runExplain } from "./handlers/explain";
@@ -301,6 +302,12 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.head = args[++i];
     } else if (arg === "--include-dependents") {
       result.includeDependents = true;
+    } else if (arg === "--from-affected") {
+      result.fromAffected = args[++i];
+    } else if (arg === "--gate") {
+      result.gate = args[++i];
+    } else if (arg === "--resume") {
+      result.resume = args[++i];
     } else if (arg === "--local") {
       result.local = true;
     } else if (arg === "--json") {
@@ -621,6 +628,13 @@ Component release ledger + status:
                             --json: stable machine-readable contract;
                             --compare-to <env>: cross-check the same
                             component's recorded digest against another env)
+  components fan-out       Run a change out across the components downstream
+                            of it, in an order derived from the source
+                            (--base <ref> [--head <ref>] [--include-dependents],
+                             or --from-affected <file>; --dry-run prints the
+                             derivation and dispatches nothing; --gate <name>
+                             puts one approval over the whole set; --resume
+                             <file> finishes an attempt that stopped)
   components release <env> Append one immutable release record
                             (--component <name> --digest <sha256:...>
                              [--git-sha <sha>] [--run-id <id>] [--actor <name>])
@@ -736,7 +750,8 @@ Options:
                         project source; network egress is NOT blocked (see
                         docs). Default: off (also settable via
                         chant.config.ts's build.sandbox: true; #1045)
-  --param <name=value>  (build, graph, run --components) Bind a declared
+  --param <name=value>  (build, graph, run --components, components fan-out)
+                        Bind a declared
                         build-time parameter (chant.config.ts's buildParams)
                         to a value, for source to read as params.<name>
                         (#1064) instead of process.env — repeatable.
@@ -744,7 +759,8 @@ Options:
                         Parameter(): this resolves before synthesis, so it
                         can change which resources are produced at all.
                         Highest precedence.
-  --params-file <path>  (build, graph, run --components) JSON file of
+  --params-file <path>  (build, graph, run --components, components fan-out)
+                        JSON file of
                         { "name": value } build-time parameter values
                         (#1064). Second precedence, after --param.
 
@@ -967,6 +983,7 @@ export const commandRegistry: CommandDef[] = [
   { name: "scenario check", requiresPlugins: true, handler: runScenarioCheck },
 
   // Component release ledger + status surface (#568, epic #551)
+  { name: "components fan-out", requiresPlugins: true, handler: runComponentsFanOut },
   { name: "components status", requiresPlugins: true, handler: runComponentsStatus },
   { name: "components release", handler: runComponentsReleaseRecord },
   { name: "components export", handler: runComponentsExport },
@@ -1102,12 +1119,17 @@ async function main(): Promise<void> {
   // missing plugins there is "no live evidence" (a warning), not a hard exit.
   const isGenerateComponents = match.def.name === "build" && args.components && !!args.generate;
   const isComponentsStatus = match.def.name === "components status";
+  // `components fan-out` (#2420) needs serializers only when it derives the
+  // change signal itself (`--base` builds both refs). Reading one somebody
+  // else already produced (`--from-affected`) touches no lexicon at all, so a
+  // components-only project is not turned away for a step it will not run.
+  const isFanOutFromFile = match.def.name === "components fan-out" && !args.base;
   // `emulator` (#920) is a property of the *configured* lexicons, not of any infra
   // file — a fresh/local project with no declarables still boots Floci. Load from
   // chant.config best-effort, like components status, rather than detectLexicon.
   const isEmulator = match.def.name === "emulator" || match.def.name.startsWith("emulator ");
   const plugins = match.def.requiresPlugins
-    ? isGenerateComponents || isComponentsStatus || isEmulator
+    ? isGenerateComponents || isComponentsStatus || isEmulator || isFanOutFromFile
       ? await loadPlugins(await resolveProjectLexicons(resolve(projectPath)).catch(() => [])).catch(() => [])
       : await loadPluginsOrExit(projectPath)
     : [];