@intentius/chant 0.124.52 → 0.124.54

package/src/components/promote.ts

@@ -44,6 +44,8 @@ import { CapabilityRegistry, type Capability } from "./capability";
 import {
   runInterpretDriver,
   DriverRunFailure,
+  deployContext,
+  type InterpretGroups,
   type DriverComponent,
   type DriverComponentResult,
   type DriverGate,
@@ -53,6 +55,9 @@ import {
   type DriverStep,
 } from "./driver";
 import type { GateLedgerPort } from "../op/gate";
+import type { GroupRun } from "./capability";
+import type { FanOutGroup, FanOutPlan } from "./fan-out";
+import { planAndRunComponentGroup, runComponentGroup } from "./groups";
 import type { Release } from "../lifecycle/release-store";
 import type { RunProgressEvent } from "./run-progress";
 import type { RunEventSink } from "../run-event-stream";
@@ -631,6 +636,27 @@ export interface RunPromotionOptions {
   onProgress?: (event: RunProgressEvent) => void;
   /** Where the run's events go (#4041, `--events-json`). */
   onRunEvent?: RunEventSink;
+  /**
+   * The grouped fan-out (ws-107, #4465, `formRunGroups`): each of its groups
+   * applies as one, in the wave it places it in. Absent, or without
+   * `groups`: every component runs its own deploy, as before.
+   */
+  grouped?: FanOutPlan;
+  /**
+   * The approved plan of each group, as the release gate's plan made it
+   * (`ReleasePlan.groups`). A group runs the one whose members are its own;
+   * the newest first. A group with none plans in its wave and applies only
+   * under `planGroupsAtWave`, and fails otherwise.
+   */
+  groupRuns?: readonly GroupRun[];
+  /** A promote with no release gate to bind plans each group in its wave (#4465). */
+  planGroupsAtWave?: boolean;
+}
+
+/** The run in `runs` that plans exactly the members of `group`. */
+function approvedRunOf(runs: readonly GroupRun[] | undefined, group: FanOutGroup): GroupRun | undefined {
+  const want = [...group.components].sort().join("\n");
+  return runs?.find((r) => Object.keys(r.plans).sort().join("\n") === want);
 }
 
 /**
@@ -647,18 +673,42 @@ export async function runPromotion(options: RunPromotionOptions): Promise<Driver
     .filter((c) => names.has(c.name))
     .map((c) => ({ ...c, dependsOn: (c.dependsOn ?? []).filter((d) => names.has(d)) }));
   const expected = new Map(plan.items.map((i) => [i.component, i.digest]));
+  const registry = checkPublishedDigest(options.registry, expected);
+  const releaseIdentity = (component: string) => {
+    const item = plan.items.find((i) => i.component === component);
+    return item ? { version: item.digest, revision: item.source.gitSha } : undefined;
+  };
+  // ws-107 (#4465): a group applies as one, through its approved plan.
+  const grouped = options.grouped?.groups?.length ? options.grouped : undefined;
+  const byName = new Map(targets.map((c) => [c.name, c]));
+  const groups: InterpretGroups | undefined = grouped
+    ? {
+        waves: grouped.waves,
+        groups: grouped.groups!,
+        run: (group, componentOutputs) => {
+          const each = {
+            group,
+            components: byName,
+            registry,
+            env: plan.to,
+            ctxOf: (name: string) => deployContext({ env: plan.to, releaseIdentity }, name),
+            componentOutputs,
+          };
+          const approved = approvedRunOf(options.groupRuns, group);
+          return approved === undefined && options.planGroupsAtWave ? planAndRunComponentGroup(each) : runComponentGroup({ ...each, run: approved });
+        },
+      }
+    : undefined;
   try {
-    return await runInterpretDriver(targets, checkPublishedDigest(options.registry, expected), {
+    return await runInterpretDriver(targets, registry, {
       env: plan.to,
       componentOutputs: options.componentOutputs ?? {},
       // #2574: a gate approval for this promote or rollback is bound to the
       // release it deploys, as well as the environment and composition.
       releases: expected,
       // #3061: the workload's service.version and vcs.ref.head.revision are the earlier release's own.
-      releaseIdentity: (component) => {
-        const item = plan.items.find((i) => i.component === component);
-        return item ? { version: item.digest, revision: item.source.gitSha } : undefined;
-      },
+      releaseIdentity,
+      ...(groups ? { groups } : {}),
       ...(options.onProgress ? { onProgress: options.onProgress } : {}),
       ...(options.onRunEvent ? { onRunEvent: options.onRunEvent } : {}),
       ...(options.gates ? { gates: options.gates } : {}),

package/src/components/registry.test.ts

@@ -99,7 +99,7 @@ describe("createCapabilityRegistry", () => {
   // for them to live in instead.
   test("family table lists exactly the agnostic starter families plus the Cloudflare apply leaves (#1293)", () => {
     expect(Object.keys(STARTER_VERB_FAMILIES).sort()).toEqual(
-      ["build", "cloudflare", "escapeHatch", "publish", "sbom", "secrets", "supplyChainPolicy", "supplyChainSecurity", "waitVerify"].sort(),
+      ["build", "cloudflare", "engineOutputs", "escapeHatch", "publish", "sbom", "secrets", "supplyChainPolicy", "supplyChainSecurity", "waitVerify"].sort(),
     );
   });
 

package/src/components/release-gate.ts

@@ -60,7 +60,9 @@
  * recorded since (#4035): its record names what ran before that run.
  */
 
-import type { CapabilityRegistry, PlannedOutputs } from "./capability";
+import type { CapabilityRegistry, GroupRun, PlannedOutputs } from "./capability";
+import type { FanOutGroup, FanOutGroupFallback, FanOutPlan } from "./fan-out";
+import { groupsByComponent, planComponentGroup } from "./groups";
 import { deployContext, resolveComponentGraph, resolveStepInput, unresolvedWiringReferences, type DriverComponent, type DriverGate, type DriverPhase, type DriverStep } from "./driver";
 import { componentPlanDigest } from "./gate-plan";
 import { gateName, RELEASE_GATE_OP } from "../op/gate-name";
@@ -137,6 +139,24 @@ export interface ReleaseChangeSetInput {
    * `seededOutputs`, which then holds what the run left. Default: every one.
    */
   only?: ReadonlySet<string>;
+  /**
+   * The promote's grouped fan-out (ws-107, #4465, `formRunGroups`). Each of
+   * its groups plans with one `planGroup` call in the wave it places it in,
+   * and the group digest is folded into each member's part, so the release
+   * gate's digest binds the composition. Absent, or without `groups`: every
+   * component plans by itself, wave by wave.
+   */
+  grouped?: FanOutPlan;
+}
+
+/** A group the release gate's plan planned as one (ws-107, #4465). */
+export interface ReleasePlanGroup extends FanOutGroup {
+  /** The group digest folded into each member's `planDigest`; `null` when the group failed to plan. */
+  digest: string | null;
+  /** Why the group failed to plan. Every member is then a failed member. */
+  error?: string;
+  /** What `runGroup` gets back. It lives in the process that planned, as the promote that applies it is. */
+  run?: GroupRun;
 }
 
 /** A release's change set for an environment, and what each component was planned against. */
@@ -148,6 +168,10 @@ export interface ReleasePlan {
   plannedOutputs?: Record<string, string[]>;
   /** Per component, the references to a promoted upstream that no value stands for until it applies, sorted. Absent when none. */
   unknownInputs?: Record<string, string[]>;
+  /** The groups planned as one (#4465), in the order they planned. Absent when none. */
+  groups?: ReleasePlanGroup[];
+  /** The components that could have grouped and did not, with why: `grouped.fallbacks`. Absent when none. */
+  fallbacks?: FanOutGroupFallback[];
 }
 
 const byString = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
@@ -287,10 +311,94 @@ export async function planReleaseSet(input: ReleaseChangeSetInput): Promise<Rele
   const inPlan = (name: string): boolean => input.only === undefined || input.only.has(name);
   const isPlannable = (c: DriverComponent): boolean =>
     capabilitySteps(c.deploy).some((s) => registry.has(s.kind) && registry.resolve(s.kind).plan !== undefined);
-  const { waves } = resolveComponentGraph(components.map((c) => ({ ...c, dependsOn: (c.dependsOn ?? []).filter((d) => byName.has(d)) })));
+  const failedPart = (member: string, err: unknown): ChangeSetPart => ({
+    member: {
+      member,
+      lexicon: "chant",
+      planner: "chant",
+      status: "failed",
+      error: err instanceof Error ? err.message : String(err),
+      planDigest: null,
+      holes: [],
+    },
+    entries: [],
+  });
+  /** Read each dependency of `component` once, leaving out `mates`, its own group (#4465), and keep what it read. */
+  const readDependencies = async (component: DriverComponent, mates: ReadonlySet<string>): Promise<void> => {
+    for (const dep of component.dependsOn ?? []) {
+      if (mates.has(dep) || read.has(dep) || !byName.has(dep)) continue;
+      read.add(dep);
+      // A dependency this promote plans exposes what its plan says (#3999).
+      if (plannedBy.has(dep) && isPlannable(byName.get(dep)!)) {
+        const known = plannedBy.get(dep)?.known ?? {};
+        outputs[dep] = { ...known };
+        planned[dep] = Object.keys(known).sort();
+        continue;
+      }
+      const found = await readComponentOutputs(byName.get(dep)!, registry, deployContext({ env }, dep), outputs);
+      if (found) outputs[dep] = found;
+    }
+    reads[component.name] = Object.fromEntries(
+      (component.dependsOn ?? []).filter((d) => !mates.has(d) && d in outputs).map((d) => [d, structuredClone(outputs[d])]),
+    );
+  };
+  /** The references of `component`'s plannable steps to a promoted upstream outside `mates` that its plan can't say yet. */
+  const unknownOf = (component: DriverComponent, mates: ReadonlySet<string>): Set<string> => {
+    const unknown = new Set<string>();
+    for (const step of capabilitySteps(component.deploy)) {
+      if (!registry.has(step.kind) || registry.resolve(step.kind).plan === undefined) continue;
+      const { kind: _kind, ...rest } = step;
+      for (const r of unresolvedWiringReferences(rest, outputs)) if (plannedBy.has(r.source) && !r.publish && !mates.has(r.source)) unknown.add(r.ref);
+    }
+    return unknown;
+  };
+
+  // ws-107 (#4465): a group plans once, in the wave the grouped fan-out places it in.
+  const grouped = input.grouped?.groups?.length ? input.grouped : undefined;
+  const groupOf = grouped ? groupsByComponent(grouped) : new Map<string, FanOutGroup>();
+  const groups: ReleasePlanGroup[] = [];
+  const planGroupAt = async (group: FanOutGroup): Promise<void> => {
+    const mates = new Set(group.components);
+    try {
+      for (const name of group.components) await readDependencies(byName.get(name)!, mates);
+    } catch (err) {
+      for (const name of group.components) {
+        plannedBy.set(name, undefined);
+        parts.push(failedPart(name, err));
+      }
+      groups.push({ ...group, digest: null, error: err instanceof Error ? err.message : String(err) });
+      return;
+    }
+    const g = await planComponentGroup({ group, components: byName, registry, env, ctxOf: (name) => deployContext({ env }, name), outputs });
+    const error = g.plans.find((p): p is Extract<typeof p, { error: string }> => "error" in p)?.error;
+    groups.push({ ...group, digest: g.digest ?? null, ...(error !== undefined ? { error } : {}), ...(g.run ? { run: g.run } : {}) });
+    for (const p of g.plans) {
+      if ("error" in p) {
+        plannedBy.set(p.component, undefined);
+        parts.push(failedPart(p.component, p.error));
+        continue;
+      }
+      plannedBy.set(p.component, p.outputs);
+      parts.push(...p.parts);
+      const unknown = unknownOf(byName.get(p.component)!, mates);
+      if (unknown.size > 0) unknownInputs[p.component] = [...unknown].sort();
+    }
+  };
+
+  const waves = grouped
+    ? grouped.waves.map((w) => w.filter((name) => byName.has(name)))
+    : resolveComponentGraph(components.map((c) => ({ ...c, dependsOn: (c.dependsOn ?? []).filter((d) => byName.has(d)) }))).waves;
   for (const wave of waves) {
     const planning = wave.filter(inPlan);
+    const inWave = new Set(planning);
+    // What is left of a group in this plan; one member alone plans by itself.
+    const groupsHere = [...new Set(planning.map((name) => groupOf.get(name)).filter((g): g is FanOutGroup => g !== undefined))]
+      .map((g) => ({ ...g, components: g.components.filter((c) => inWave.has(c)) }))
+      .filter((g) => g.components.length > 1);
+    const grouping = new Set(groupsHere.flatMap((g) => g.components));
+    for (const group of groupsHere) await planGroupAt(group);
     for (const name of planning) {
+      if (grouping.has(name)) continue;
       const component = byName.get(name)!;
       const digest = input.digests.get(name) ?? "";
       const plannable = capabilitySteps(component.deploy).filter((s) => registry.has(s.kind) && registry.resolve(s.kind).plan !== undefined);
@@ -300,25 +408,11 @@ export async function planReleaseSet(input: ReleaseChangeSetInput): Promise<Rele
       }
       const ctx = deployContext({ env }, name);
       try {
-        for (const dep of component.dependsOn ?? []) {
-          if (read.has(dep) || !byName.has(dep)) continue;
-          read.add(dep);
-          // A dependency this promote plans exposes what its plan says (#3999).
-          if (plannedBy.has(dep) && isPlannable(byName.get(dep)!)) {
-            const known = plannedBy.get(dep)?.known ?? {};
-            outputs[dep] = { ...known };
-            planned[dep] = Object.keys(known).sort();
-            continue;
-          }
-          const found = await readComponentOutputs(byName.get(dep)!, registry, deployContext({ env }, dep), outputs);
-          if (found) outputs[dep] = found;
-        }
-        reads[name] = Object.fromEntries((component.dependsOn ?? []).filter((d) => d in outputs).map((d) => [d, structuredClone(outputs[d])]));
-        const unknown = new Set<string>();
+        await readDependencies(component, new Set());
+        const unknown = unknownOf(component, new Set());
         let exposes: PlannedOutputs | undefined;
         for (const step of plannable) {
           const { kind, ...rest } = step;
-          for (const r of unresolvedWiringReferences(rest, outputs)) if (plannedBy.has(r.source) && !r.publish) unknown.add(r.ref);
           const result = await registry.resolve(kind).plan!(planContext(ctx, rest, outputs), resolveStepInput(rest, {}, outputs) as never);
           if (result.outputs) exposes = { known: { ...(exposes?.known ?? {}), ...result.outputs.known }, unknown: [...new Set([...(exposes?.unknown ?? []), ...result.outputs.unknown])].sort() };
           parts.push(
@@ -339,18 +433,7 @@ export async function planReleaseSet(input: ReleaseChangeSetInput): Promise<Rele
         if (unknown.size > 0) unknownInputs[name] = [...unknown].sort();
       } catch (err) {
         plannedBy.set(name, undefined);
-        parts.push({
-          member: {
-            member: name,
-            lexicon: "chant",
-            planner: "chant",
-            status: "failed",
-            error: err instanceof Error ? err.message : String(err),
-            planDigest: null,
-            holes: [],
-          },
-          entries: [],
-        });
+        parts.push(failedPart(name, err));
       }
     }
   }
@@ -363,6 +446,8 @@ export async function planReleaseSet(input: ReleaseChangeSetInput): Promise<Rele
     reads,
     ...(Object.keys(planned).length > 0 ? { plannedOutputs: planned } : {}),
     ...(Object.keys(unknownInputs).length > 0 ? { unknownInputs } : {}),
+    ...(groups.length > 0 ? { groups } : {}),
+    ...(input.grouped?.fallbacks?.length ? { fallbacks: input.grouped.fallbacks } : {}),
   };
 }
 

package/src/components/release-groups.test.ts

@@ -0,0 +1,362 @@
+/**
+ * Composed runs at promote, fan-out and `run --components` (ws-107, #4465),
+ * against a fake capability: `fake-stack` creates one resource and exposes an
+ * `id` known only after it applies. With `group` it declares `planGroup` and
+ * `runGroup`; without, it plans and applies component by component, as
+ * before. The pull-request run's groups are in `pr-run.test.ts`.
+ */
+
+import { describe, expect, test } from "vitest";
+import {
+  CapabilityRegistry,
+  type CapabilityGroupOutcome,
+  type DeployContext,
+  type GroupContext,
+  type GroupMember,
+  type GroupRun,
+  type PlannedOutputs,
+} from "./capability";
+import { computePlanDigest } from "../lifecycle/plan-digest";
+import { isEmptyChangeSet } from "../change-set";
+import { makeRelease, type Release } from "../lifecycle/release-store";
+import type { ReleaseRecord } from "../lifecycle/release-ledger";
+import { memoryGateLedgerPort } from "../op/gate";
+import { runInterpretDriver, type DriverComponent, type DriverRunResult, type ReleaseGateBinding } from "./driver";
+import { remainingFanOut } from "./fan-out";
+import { runFanOut } from "./fan-out-run";
+import { componentSetFanOut, formRunGroups, planAndRunComponentGroup, regroupRemaining, WAVE_GATE_FALLBACK } from "./groups";
+import { runPromotion, type PromotionPlan } from "./promote";
+import { runPromotionInRounds } from "./promote-rounds";
+import { planReleaseSet } from "./release-gate";
+import { renderRunGroups, runGroupsReport } from "./run-groups";
+
+interface StackInput {
+  root: string;
+  vars?: Record<string, unknown>;
+}
+
+const so = (stack: string, name: string) => ({ stackOutput: { stack, name } });
+const sha = (c: string) => `sha256:${c.repeat(64)}`;
+
+const stack = (name: string, dependsOn: string[] = [], vars?: Record<string, unknown>): DriverComponent => ({
+  name,
+  dependsOn,
+  deploy: [{ phase: "Apply", steps: [{ kind: "fake-stack", root: name, ...(vars ? { vars } : {}) }] }],
+});
+/** a; b reads a's new id; c reads b's. */
+const ABC = [stack("a"), stack("b", ["a"], { upstream: so("a", "id") }), stack("c", ["b"], { upstream: so("b", "id") })];
+
+function world(opts: { group?: boolean } = {}) {
+  const w = {
+    registry: new CapabilityRegistry(),
+    planned: [] as string[],
+    applied: [] as string[],
+    planGroupCalls: [] as string[][],
+    runGroupCalls: [] as Array<{ components: string[]; run: GroupRun }>,
+    outcome: undefined as ((members: readonly GroupMember[]) => CapabilityGroupOutcome) | undefined,
+  };
+  const planOf = (input: StackInput) => {
+    const planDigest = computePlanDigest("fake-stack", { root: input.root, vars: input.vars ?? null });
+    const outputs: PlannedOutputs = { known: {}, unknown: ["id"] };
+    return {
+      member: input.root,
+      planDigest,
+      artifact: { planDigest },
+      outputs,
+      changeSet: {
+        member: { member: input.root, lexicon: "test", planner: "tofu" as const, status: "planned" as const, planDigest, holes: [] },
+        entries: [{ member: input.root, lexicon: "test", planner: "tofu" as const, address: "res.x", type: "res", action: "create" as const, attributes: [] }],
+      },
+    };
+  };
+  w.registry.register({
+    kind: "fake-stack",
+    async plan(_ctx: DeployContext, input: StackInput) {
+      w.planned.push(input.root);
+      return planOf(input);
+    },
+    async run(_ctx: DeployContext, input: StackInput) {
+      w.applied.push(input.root);
+      return { outputs: { id: `${input.root}-id` } };
+    },
+    ...(opts.group
+      ? {
+          async planGroup(_ctx: GroupContext, members: readonly GroupMember<StackInput>[]) {
+            w.planGroupCalls.push(members.map((m) => m.component));
+            return {
+              members: Object.fromEntries(members.map((m) => [m.component, planOf(m.input!)])),
+              digest: computePlanDigest("fake-composition", members.map((m) => m.component)),
+              artifact: { composed: members.map((m) => m.component) },
+            };
+          },
+          async runGroup(_ctx: GroupContext, run: GroupRun, members: readonly GroupMember<StackInput>[]) {
+            w.runGroupCalls.push({ components: members.map((m) => m.component), run });
+            if (w.outcome) return w.outcome(members);
+            return { members: Object.fromEntries(members.map((m) => [m.component, { status: "applied" as const, outputs: { id: `${m.component}-id` } }])) };
+          },
+        }
+      : {}),
+  } as never);
+  return w;
+}
+
+const release = (): Release =>
+  makeRelease({
+    member: null,
+    commit: "a".repeat(40),
+    artifactDigests: [],
+    targets: [{ env: "prod", templates: [], params: [] }],
+  });
+
+const source = (component: string): ReleaseRecord => ({
+  version: 1,
+  component,
+  env: "staging",
+  digest: sha("d"),
+  gitSha: "a".repeat(40),
+  runId: "run-1",
+  timestamp: "2026-10-01T00:00:00.000Z",
+  actor: "ci",
+});
+
+const promotion = (components: readonly DriverComponent[]): PromotionPlan => ({
+  from: "staging",
+  to: "prod",
+  items: components.map((c) => ({ component: c.name, digest: sha("d"), source: source(c.name) })),
+  notPromoted: [],
+});
+
+async function grouped(components: DriverComponent[], registry: CapabilityRegistry, waveGate = false) {
+  return formRunGroups({ components, plan: componentSetFanOut(components), registry, env: "prod", ...(waveGate ? { waveGate: true } : {}) });
+}
+
+async function planned(components: DriverComponent[], registry: CapabilityRegistry, waveGate = false) {
+  const plan = await grouped(components, registry, waveGate);
+  const set = await planReleaseSet({ release: release(), env: "prod", components, digests: new Map(), registry, current: new Map(), grouped: plan });
+  return { plan, set };
+}
+
+const binding = (digest: string): ReleaseGateBinding => ({ op: "release", planDigest: digest, releaseDigest: sha("r") });
+
+describe("promote --release plans a group as one (#4465)", () => {
+  test("A, B reading A and C reading B: one planGroup call, the group digest in every member's part, no planned outputs between members", async () => {
+    const w = world({ group: true });
+    const { plan, set } = await planned(ABC, w.registry);
+    expect(plan.groups).toEqual([{ capability: "fake-stack", components: ["a", "b", "c"] }]);
+    expect(w.planGroupCalls).toEqual([["a", "b", "c"]]);
+    expect(w.planned).toEqual([]);
+    const digest = set.groups?.[0]?.digest;
+    expect(digest).toEqual(expect.stringMatching(/^jcs1-sha256:[0-9a-f]{64}$/));
+    expect(set.groups?.[0]?.run?.digest).toBe(digest);
+    // The release gate's change set names the group (its digest) on each of its members, and what each reads inside it.
+    expect(set.doc.members.map((m) => [m.member, m.status, m.group])).toEqual([
+      ["a", "planned", { digest, reads: [] }],
+      ["b", "planned", { digest, reads: ["a.id"] }],
+      ["c", "planned", { digest, reads: ["b.id"] }],
+    ]);
+    expect(isEmptyChangeSet(set.doc)).toBe(false);
+    // A read of a group-mate is no planned output and no unknown input, so the promote runs no round for it.
+    expect(set.plannedOutputs).toBeUndefined();
+    expect(set.unknownInputs).toBeUndefined();
+  });
+
+  test("without the group pair it plans component by component, as before", async () => {
+    const w = world();
+    const { plan, set } = await planned(ABC, w.registry);
+    expect(plan.groups).toBeUndefined();
+    expect(w.planGroupCalls).toEqual([]);
+    expect(w.planned).toEqual(["a", "b", "c"]);
+    expect(set.groups).toBeUndefined();
+    expect(set.doc.members.every((m) => m.group === undefined)).toBe(true);
+    expect(set.unknownInputs).toEqual({ b: ["a.id"], c: ["b.id"] });
+  });
+
+  test("with --wave-gate no group forms: each member falls back as wave-gate and plans by itself", async () => {
+    const w = world({ group: true });
+    const { plan, set } = await planned(ABC, w.registry, true);
+    expect(plan.groups).toBeUndefined();
+    expect(plan.waves).toEqual([["a"], ["b"], ["c"]]);
+    expect(plan.fallbacks?.map((f) => [f.component, f.kind])).toEqual([
+      ["a", WAVE_GATE_FALLBACK],
+      ["b", WAVE_GATE_FALLBACK],
+      ["c", WAVE_GATE_FALLBACK],
+    ]);
+    expect(w.planGroupCalls).toEqual([]);
+    expect(w.planned).toEqual(["a", "b", "c"]);
+    expect(set.fallbacks).toEqual(plan.fallbacks);
+  });
+});
+
+describe("promote --release applies a group as one (#4465)", () => {
+  test("one runGroup call with the plan the release gate bound, and no round", async () => {
+    const w = world({ group: true });
+    const { plan, set } = await planned(ABC, w.registry);
+    const groupRuns = (set.groups ?? []).map((g) => g.run!);
+    const runs: string[][] = [];
+    const result = await runPromotionInRounds({
+      components: ABC,
+      outputs: {},
+      binding: binding(set.doc.digest),
+      approved: set.doc,
+      reads: set.reads,
+      grouped: plan,
+      replan: async () => {
+        throw new Error("no round: nothing is planned again");
+      },
+      bind: async () => {
+        throw new Error("no round: nothing is bound again");
+      },
+      run: (components, outputs, b) => {
+        runs.push(components.map((c) => c.name));
+        return runPromotion({
+          plan: promotion(components),
+          components,
+          registry: w.registry,
+          componentOutputs: outputs,
+          gates: memoryGateLedgerPort(),
+          releaseGate: b,
+          grouped: plan,
+          groupRuns,
+        });
+      },
+    });
+    expect(result.stages).toEqual([]);
+    expect(runs).toEqual([["a", "b", "c"]]);
+    expect(w.runGroupCalls.map((c) => c.components)).toEqual([["a", "b", "c"]]);
+    expect(w.runGroupCalls[0]!.run.digest).toBe(set.groups![0]!.digest);
+    expect(w.applied).toEqual([]);
+    expect(result.run.status).toBe("ok");
+    expect(result.completed).toEqual(["a", "b", "c"]);
+    expect(result.outputs).toMatchObject({ a: { id: "a-id" }, b: { id: "b-id" }, c: { id: "c-id" } });
+  });
+
+  test("a group with no approved plan fails every member unless the promote plans it in its wave", async () => {
+    const w = world({ group: true });
+    const plan = await grouped(ABC, w.registry);
+    const refused = await runPromotion({ plan: promotion(ABC), components: ABC, registry: w.registry, gates: memoryGateLedgerPort(), grouped: plan, groupRuns: [] });
+    expect(refused.status).toBe("fail");
+    expect(w.runGroupCalls).toEqual([]);
+    const ran = await runPromotion({ plan: promotion(ABC), components: ABC, registry: w.registry, gates: memoryGateLedgerPort(), grouped: plan, planGroupsAtWave: true });
+    expect(ran.status).toBe("ok");
+    expect(w.planGroupCalls).toEqual([["a", "b", "c"]]);
+    expect(w.runGroupCalls.map((c) => c.components)).toEqual([["a", "b", "c"]]);
+    expect(ran.groupOutcomes).toEqual({ a: "applied", b: "applied", c: "applied" });
+  });
+
+  test("without the group pair each component runs its own deploy, as before", async () => {
+    const w = world();
+    const plan = await grouped(ABC, w.registry);
+    const ran = await runPromotion({ plan: promotion(ABC), components: ABC, registry: w.registry, gates: memoryGateLedgerPort(), grouped: plan });
+    expect(ran.status).toBe("ok");
+    expect(w.applied).toEqual(["a", "b", "c"]);
+    expect(ran.groupOutcomes).toBeUndefined();
+  });
+
+  test("a resume after the group failed part way plans only the members left, as a smaller group", async () => {
+    const w = world({ group: true });
+    const plan = await grouped(ABC, w.registry);
+    // The first attempt: a applied, b failed, c did not start.
+    w.outcome = () => ({
+      members: { a: { status: "applied", outputs: { id: "a-id" } }, b: { status: "failed", error: "boom" }, c: { status: "not-started" } },
+    });
+    const first = await runPromotion({ plan: promotion(ABC), components: ABC, registry: w.registry, gates: memoryGateLedgerPort(), grouped: plan, planGroupsAtWave: true });
+    expect(first.status).toBe("fail");
+    expect(first.groupOutcomes).toEqual({ a: "applied", b: "failed", c: "not-started" });
+    const completed = first.results.filter((r) => r.status === "ok").map((r) => r.component);
+    expect(completed).toEqual(["a"]);
+
+    // The resume groups what is left, as the promote handler does, and plans only that.
+    w.planGroupCalls.length = 0;
+    w.outcome = undefined;
+    const left = await regroupRemaining({
+      components: ABC,
+      plan: remainingFanOut(plan, ABC, { completed }),
+      registry: w.registry,
+      env: "prod",
+      groups: plan.groups,
+    });
+    expect(left.groups).toEqual([{ capability: "fake-stack", components: ["b", "c"] }]);
+    const set = await planReleaseSet({
+      release: release(),
+      env: "prod",
+      components: ABC,
+      digests: new Map(),
+      registry: w.registry,
+      current: new Map(),
+      seededOutputs: { a: { id: "a-id" } },
+      only: new Set(["b", "c"]),
+      grouped: left,
+    });
+    expect(w.planGroupCalls).toEqual([["b", "c"]]);
+    expect(set.doc.members.map((m) => m.member)).toEqual(["b", "c"]);
+  });
+});
+
+describe("components fan-out and run --components apply a group as one (#4465)", () => {
+  test("runFanOut plans a group in its wave and applies it with one runGroup call", async () => {
+    const w = world({ group: true });
+    const plan = await grouped(ABC, w.registry);
+    const result = await runFanOut(plan, ABC, w.registry, { env: "prod", gates: memoryGateLedgerPort(), planGroupsAtWave: true });
+    expect(result.status).toBe("ok");
+    expect(w.planGroupCalls).toEqual([["a", "b", "c"]]);
+    expect(w.runGroupCalls.map((c) => c.components)).toEqual([["a", "b", "c"]]);
+    expect(result.groupOutcomes).toEqual({ a: "applied", b: "applied", c: "applied" });
+  });
+
+  test("runInterpretDriver runs a group once, in place of its members' own deploys", async () => {
+    const w = world({ group: true });
+    const plan = await grouped(ABC, w.registry);
+    const byName = new Map(ABC.map((c) => [c.name, c]));
+    const run: DriverRunResult = await runInterpretDriver(ABC, w.registry, {
+      env: "prod",
+      gates: memoryGateLedgerPort(),
+      groups: {
+        waves: plan.waves,
+        groups: plan.groups!,
+        run: (group, componentOutputs) =>
+          planAndRunComponentGroup({ group, components: byName, registry: w.registry, env: "prod", ctxOf: (name) => ({ env: "prod", component: name }), componentOutputs }),
+      },
+    });
+    expect(run.status).toBe("ok");
+    expect(run.waves).toEqual([["a", "b", "c"]]);
+    expect(w.applied).toEqual([]);
+    expect(w.runGroupCalls.map((c) => c.components)).toEqual([["a", "b", "c"]]);
+    expect(run.componentOutputs).toMatchObject({ c: { id: "c-id" } });
+  });
+});
+
+describe("the promote report names the group and each member's outcome (#4465)", () => {
+  test("a group that stopped part way: its members, wave, digest and reads, each member's outcome, and what the same promote plans next", async () => {
+    const w = world({ group: true });
+    const { plan, set } = await planned(ABC, w.registry);
+    const digest = set.groups![0]!.digest!;
+    const report = runGroupsReport({ grouped: plan, planned: set.groups!, doc: set.doc, outcomes: { a: "applied", b: "partial", c: "not-started" } });
+    expect(report.groups).toEqual([
+      {
+        capability: "fake-stack",
+        components: ["a", "b", "c"],
+        wave: 1,
+        digest,
+        reads: [
+          { member: "b", ref: "a.id" },
+          { member: "c", ref: "b.id" },
+        ],
+        outcomes: { a: "applied", b: "partial", c: "not-started" },
+      },
+    ]);
+    expect(renderRunGroups(report, "the same promote")).toEqual([
+      `a, b and c plan and apply as one (fake-stack, wave 1, group ${digest}); b reads a.id and c reads b.id, known when the group applies`,
+      "  a applied; b applied in part, and what applied stays; c did not start",
+      "  the group's apply stopped part way and nothing that applied is undone; the same promote plans b and c again, as one group where they still join",
+    ]);
+  });
+
+  test("under --wave-gate the report says why each member planned by itself", async () => {
+    const w = world({ group: true });
+    const plan = await grouped(ABC, w.registry, true);
+    const lines = renderRunGroups(runGroupsReport({ grouped: plan }), "the same promote");
+    expect(lines).toEqual([
+      "planned one by one, not as a group: a, b, c (wave-gate): a, b and c would plan and apply as one, but under --wave-gate each wave plans component by component, so no group forms",
+    ]);
+  });
+});