@intentius/chant 0.124.51 → 0.124.54

package/src/components/pr-run.test.ts

@@ -10,7 +10,18 @@
  */
 
 import { describe, expect, test } from "vitest";
-import { CapabilityRegistry, type DeployContext, type PlannedOutputs } from "./capability";
+import {
+  CapabilityRegistry,
+  type CapabilityGroupOutcome,
+  type DeployContext,
+  type GroupContext,
+  type GroupFallback,
+  type GroupMember,
+  type GroupRun,
+  type PlannedOutputs,
+} from "./capability";
+import { findComponentGroups, groupFanOut } from "./groups";
+import { failedRunExitCode } from "./driver";
 import { memoryGateLedgerPort } from "../op/gate";
 import { planFanOut } from "./fan-out";
 import {
@@ -28,9 +39,9 @@ import {
   waveNotCovered,
   type PrPlanSet,
 } from "./pr-run";
-import { changeSetDigest, changeSetDocumentDigest, composeChangeSet, type ChangeSetEntry, type ChangeSetPart } from "../change-set";
+import { changeSetDigest, changeSetDocumentDigest, composeChangeSet, isEmptyChangeSet, type ChangeSetEntry, type ChangeSetPart } from "../change-set";
 import type { PrApplyRecord } from "./fan-out-record";
-import { renderPrNote } from "../pr-loop";
+import { renderPrNote, type PrApproval } from "../pr-loop";
 import type { FanOutPlan } from "./fan-out";
 import { computePlanDigest } from "../lifecycle/plan-digest";
 import type { DriverComponent } from "./driver";
@@ -78,6 +89,8 @@ function world() {
     predict: {} as Record<string, (() => PlannedOutputs | undefined) | undefined>,
     /** What `a` writes when it applies, when not what its version gives. */
     appliesAs: undefined as string | undefined,
+    /** `a` applying makes `app` plan a change its first plan did not show. */
+    bumpAppOnApply: false,
   };
   w.predict.net = () => ({ known: { ...(w.state.net ?? {}) }, unknown: [] });
   w.predict.a = () => ({ known: { id: `a-${w.versions.a ?? "v1"}` }, unknown: [] });
@@ -122,6 +135,7 @@ function world() {
       w.ranWith[input.root] = input.vars;
       if (w.failing.has(input.root)) throw new Error(`${input.root} failed`);
       w.applied.push(input.root);
+      if (input.root === "a" && w.bumpAppOnApply) w.versions.app = "v2";
       if (input.root === "a") w.state.a = { id: w.appliesAs ?? `a-${w.versions.a ?? "v1"}` };
       return { outputs: { ...(w.state[input.root] ?? {}) } };
     },
@@ -311,7 +325,7 @@ describe("a dependency outside the selection (#4104)", () => {
     if (!resumed.ok) throw new Error(resumed.reasons.join("; "));
     expect(w.outputsRead).toEqual([]);
     expect(resumed.set.doc.digest).toBe(set.doc.digest);
-    expect(resumed.set.outputs).toBe(record.planOutputs);
+    expect(resumed.set.outputs).toEqual(record.planOutputs);
   });
 });
 
@@ -404,6 +418,19 @@ describe("a dependent planned on its upstream's planned outputs (#3999)", () =>
     expect(w.applied).toEqual(["a", "app"]);
   });
 
+  test("each member names every upstream output it reads, the known ones too, and the apply report keeps them", async () => {
+    const w = world();
+    w.versions.a = "v2";
+    const set = await planPrSet({ components: ESTATE, plan: plan(), registry: w.registry, env: "prod" });
+    // a reads net, which is not in the change: a read of a deployed output is a read too.
+    expect(set.members.map((m) => [m.member, m.reads])).toEqual([
+      ["a", [{ upstream: "net", outputs: ["cidr"] }]],
+      ["app", [{ upstream: "a", outputs: ["id"] }]],
+    ]);
+    const applied = await applyPrSet({ components: ESTATE, plan: plan(), registry: w.registry, env: "prod", set });
+    expect(applied.members.find((m) => m.member === "app")?.reads).toEqual([{ upstream: "a", outputs: ["id"] }]);
+  });
+
   test("an output the change moves: the dependent plans on the moved value, not the one standing now", async () => {
     const w = world();
     w.versions.a = "v2";
@@ -429,6 +456,7 @@ describe("a dependent planned on its upstream's planned outputs (#3999)", () =>
       ["a", undefined],
       ["app", ["a.id"]],
     ]);
+    expect(set.members.find((m) => m.member === "app")?.reads).toEqual([{ upstream: "a", outputs: ["id"], unknown: ["id"] }]);
 
     // No approval of the plan made after a applied: a applies, app waits.
     const waiting = await applyPrSet({ components: ESTATE, plan: plan(), registry: w.registry, env: "prod", set, decideRound: decideWith(new Set()) });
@@ -457,6 +485,121 @@ describe("a dependent planned on its upstream's planned outputs (#3999)", () =>
     expect(applied.members.find((m) => m.member === "app")).toMatchObject({ status: "applied", round: 2 });
   });
 
+  const approvedFirst: PrApproval = { status: "approved", approvedBy: ["github:rev"] };
+
+  test("the first approval covers the round that only fills in what was unknown: no gate of its own, recorded as covered (#4419)", async () => {
+    const w = world();
+    w.versions.a = "v2";
+    w.predict.a = () => ({ known: {}, unknown: ["id"] });
+    const set = await planPrSet({ components: ESTATE, plan: plan(), registry: w.registry, env: "prod" });
+    let asked = 0;
+    const applied = await applyPrSet({
+      components: ESTATE,
+      plan: plan(),
+      registry: w.registry,
+      env: "prod",
+      set,
+      approval: approvedFirst,
+      decideRound: async () => {
+        asked++;
+        return { satisfied: false, approval: { status: "pending" } };
+      },
+    });
+    expect(asked).toBe(0);
+    expect(applied.status).toBe("applied");
+    expect(w.applied).toEqual(["a", "app"]);
+    expect(w.ranWith.app).toEqual({ subnet: "a-v2" });
+    expect(applied.rounds).toHaveLength(1);
+    expect(applied.rounds![0]).toMatchObject({
+      round: 2,
+      status: "applied",
+      approval: approvedFirst,
+      covered: { digest: set.doc.digest, filledInputs: ["a.id"] },
+    });
+  });
+
+  test("a round that plans a change the first plan did not show asks for its own approval, with the reason (#4419)", async () => {
+    const w = world();
+    w.versions.a = "v2";
+    w.predict.a = () => ({ known: {}, unknown: ["id"] });
+    w.bumpAppOnApply = true;
+    const set = await planPrSet({ components: ESTATE, plan: plan(), registry: w.registry, env: "prod" });
+    const seen: Array<string | undefined> = [];
+    const applied = await applyPrSet({
+      components: ESTATE,
+      plan: plan(),
+      registry: w.registry,
+      env: "prod",
+      set,
+      approval: approvedFirst,
+      decideRound: async ({ notCovered }) => {
+        seen.push(notCovered);
+        return { satisfied: false, approval: { status: "pending" } };
+      },
+    });
+    expect(applied.status).toBe("waiting");
+    expect(w.applied).toEqual(["a"]);
+    expect(seen).toEqual(["app now plans to update terraform_data.x, which the first plan did not"]);
+    expect(applied.rounds![0]).toMatchObject({ status: "waiting", notCovered: seen[0] });
+    expect(applied.rounds![0]!.covered).toBeUndefined();
+  });
+
+  test("a third member that reads a previewed member's known output is covered when the round plans that output as the same value (#4419)", async () => {
+    const chain: DriverComponent[] = [
+      root("x"),
+      root("y", ["x"], { id: { stackOutput: { stack: "x", name: "id" } } }),
+      root("z", ["y"], { port: { stackOutput: { stack: "y", name: "port" } } }),
+    ];
+    const w = world();
+    w.state = { x: { id: "x-v1" }, y: { port: "8080" }, z: {} };
+    w.versions.x = "v2";
+    w.versions.y = "v2";
+    w.versions.z = "v2";
+    w.predict.x = () => ({ known: {}, unknown: ["id"] });
+    w.predict.y = () => ({ known: { port: "8080" }, unknown: [] });
+    w.predict.z = () => undefined;
+    const chainPlan = planFanOut({ components: chain, changed: ["x"] });
+    const set = await planPrSet({ components: chain, plan: chainPlan, registry: w.registry, env: "prod" });
+    const seen: Array<string | undefined> = [];
+    const applied = await applyPrSet({
+      components: chain,
+      plan: chainPlan,
+      registry: w.registry,
+      env: "prod",
+      set,
+      approval: approvedFirst,
+      decideRound: async ({ notCovered }) => {
+        seen.push(notCovered);
+        return { satisfied: false, approval: { status: "pending" } };
+      },
+    });
+    expect(seen).toEqual([]);
+    expect(applied.status).toBe("applied");
+    expect(w.applied).toEqual(["x", "y", "z"]);
+    expect(applied.rounds![0]).toMatchObject({ round: 2, components: ["y", "z"], covered: { digest: set.doc.digest, filledInputs: ["x.id"] } });
+  });
+
+  test("an input the first plan read with a value that moved is not covered (#4419)", async () => {
+    const w = world();
+    w.versions.a = "v2";
+    w.appliesAs = "a-v2-real";
+    const set = await planPrSet({ components: ESTATE, plan: plan(), registry: w.registry, env: "prod" });
+    const seen: Array<string | undefined> = [];
+    await applyPrSet({
+      components: ESTATE,
+      plan: plan(),
+      registry: w.registry,
+      env: "prod",
+      set,
+      approval: approvedFirst,
+      decideRound: async ({ notCovered }) => {
+        seen.push(notCovered);
+        return { satisfied: false, approval: { status: "pending" } };
+      },
+    });
+    expect(seen).toEqual(["app reads a.id, which the first plan read as another value"]);
+  });
+
   test("an upstream new in the same pull request plans, and so does its dependent", async () => {
     const pair: DriverComponent[] = [root("vpc"), root("svc", ["vpc"], { vpc: { stackOutput: { stack: "vpc", name: "id" } } })];
     const w = world();
@@ -889,6 +1032,85 @@ describe("planCoveredBy", () => {
   });
 });
 
+/**
+ * One decision for a round, a resume and a wave (#4422). The same estate and
+ * the same two outcomes go through `applyPrSet`'s round, `resumePrSet` and
+ * `waveNotCovered` (what `--wave-gate` uses), and each path must give the same
+ * verdict with the same reason.
+ */
+describe("one coverage decision on a round, a resume and a wave (#4422)", () => {
+  const plan = () => planFanOut({ components: ESTATE, changed: ["a"] });
+  const approvedFirst: PrApproval = { status: "approved", approvedBy: ["github:rev"] };
+  /** `a` v2, whose id is known only after apply; `app` reads it. */
+  async function first(w: ReturnType<typeof world>) {
+    w.versions.a = "v2";
+    w.predict.a = () => ({ known: {}, unknown: ["id"] });
+    return planPrSet({ components: ESTATE, plan: plan(), registry: w.registry, env: "prod" });
+  }
+
+  const paths: Record<string, (extra: boolean) => Promise<string | undefined>> = {
+    round: async (extra) => {
+      const w = world();
+      const set = await first(w);
+      w.bumpAppOnApply = extra;
+      let reason: string | undefined;
+      const applied = await applyPrSet({
+        components: ESTATE,
+        plan: plan(),
+        registry: w.registry,
+        env: "prod",
+        set,
+        approval: approvedFirst,
+        decideRound: async ({ notCovered }) => {
+          reason = notCovered;
+          return { satisfied: false, approval: { status: "pending" } };
+        },
+      });
+      expect(applied.status).toBe(extra ? "waiting" : "applied");
+      return reason;
+    },
+    resume: async (extra) => {
+      const w = world();
+      const set = await first(w);
+      w.state.a = { id: "a-v2" };
+      if (extra) w.versions.app = "v2";
+      const resumed = await resumePrSet({ components: ESTATE, plan: plan(), registry: w.registry, env: "prod", record: recordOf(set), completed: ["a"] });
+      return resumed.ok ? undefined : resumed.reasons[0];
+    },
+    wave: async (extra) => {
+      const w = world();
+      const set = await first(w);
+      if (extra) w.versions.app = "v2";
+      const wavePlan = prWavePlan(plan(), ESTATE, 2);
+      const fresh = await planPrSet({ components: ESTATE, plan: wavePlan, registry: w.registry, env: "prod", seededOutputs: { ...set.outputs, a: { id: "a-v2" } } });
+      return waveNotCovered(set.doc, fresh.doc, set.members)[0];
+    },
+  };
+
+  test.each([
+    ["only the previewed unknown filled in", false, undefined],
+    ["an entry the first plan did not show", true, "app now plans to update terraform_data.x, which the first plan did not"],
+  ] as const)("%s", async (_name, extra, expected) => {
+    for (const [path, decide] of Object.entries(paths)) {
+      expect({ path, reason: await decide(extra) }).toEqual({ path, reason: expected });
+    }
+  });
+
+  test("a member that was a hole with no preview is not covered by an approval that never saw its shape", () => {
+    const part = (digest: string, entries: ChangeSetEntry[], holes: ChangeSetPart["member"]["holes"]): ChangeSetPart => ({
+      member: { member: "svc", lexicon: "aws", planner: "chant", status: "planned", planDigest: `jcs1-sha256:${digest.repeat(64)}`, holes },
+      entries,
+    });
+    const approved = composeChangeSet([part("1", [], [{ address: "svc", reason: "inputs from net; re-checked on apply" }])]);
+    const entry: ChangeSetEntry = { member: "svc", lexicon: "aws", planner: "chant", address: "Queue", type: "AWS::SQS::Queue", action: "create", attributes: [] };
+    const fresh = composeChangeSet([part("2", [entry], [])]);
+    const members = [{ member: "svc", component: "svc", planDigest: null, status: "planned" as const, counts: { create: 0, update: 0, replace: 0, delete: 0 }, unknownInputs: ["net.id"] }];
+    // Even with the input named unknown, nothing was previewed to cover a create.
+    expect(waveNotCovered(approved, fresh, members)).toEqual(["svc now plans to create Queue, which the first plan did not"]);
+    expect(waveNotCovered(approved, fresh)).toEqual(["svc now plans to create Queue, which the first plan did not"]);
+  });
+});
+
 describe("a gate per wave on merge (#4003)", () => {
   const estate = [root("net"), root("a", ["net"]), root("b", ["net"]), root("app", ["a"])];
   const plan = planFanOut({ components: estate, changed: ["net"] });
@@ -942,3 +1164,505 @@ describe("a gate per wave on merge (#4003)", () => {
     expect(moved[0]).toMatch(/^job now plans to jcs1-sha256:2+, not the approved jcs1-sha256:1+, and its planner describes no changes to compare$/);
   });
 });
+
+describe("a group planned and applied as one (ws-107, #4440)", () => {
+  interface StackInput {
+    root: string;
+    vars?: Record<string, unknown>;
+  }
+  const so = (stack: string, name: string) => ({ stackOutput: { stack, name } });
+  const stack = (name: string, dependsOn: string[] = [], vars?: Record<string, unknown>): DriverComponent => ({
+    name,
+    dependsOn,
+    deploy: [{ phase: "Apply", steps: [{ kind: "fake-stack", root: name, ...(vars ? { vars } : {}) }] }],
+  });
+  const plainStack = (name: string, dependsOn: string[] = [], vars?: Record<string, unknown>): DriverComponent => ({
+    name,
+    dependsOn,
+    deploy: [{ phase: "Apply", steps: [{ kind: "fake-plain", 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") })];
+
+  /**
+   * `fake-stack` creates one resource and exposes an `id` known only after
+   * it applies. With `group`, it declares `planGroup` and `runGroup`;
+   * `fallback` adds a `groupFallback`. `fake-plain` never groups, and its
+   * plan knows the `id` it will expose.
+   */
+  function groupWorld(opts: { group?: boolean; fallback?: GroupFallback } = {}) {
+    const w = {
+      registry: new CapabilityRegistry(),
+      planned: [] as string[],
+      applied: [] as string[],
+      planGroupCalls: [] as string[][],
+      runGroupCalls: [] as Array<{ components: string[]; run: GroupRun; members: GroupMember[] }>,
+      planThrows: undefined as unknown,
+      runThrows: undefined as unknown,
+      outcome: undefined as ((members: readonly GroupMember[]) => CapabilityGroupOutcome) | undefined,
+      /** Roots whose plan also creates `res.extra`, a change no earlier plan showed. */
+      extra: new Set<string>(),
+    };
+    const planOf = (input: StackInput, known: boolean) => {
+      const planDigest = computePlanDigest("fake-stack", { root: input.root, vars: input.vars ?? null });
+      const outputs: PlannedOutputs = known ? { known: { id: `${input.root}-id` }, unknown: [] } : { 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.extra.has(input.root)
+              ? [{ member: input.root, lexicon: "test", planner: "tofu" as const, address: "res.extra", 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, false);
+      },
+      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));
+              if (w.planThrows) throw w.planThrows;
+              return {
+                members: Object.fromEntries(members.map((m) => [m.component, planOf(m.input!, false)])),
+                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, members: [...members] });
+              if (w.runThrows) throw w.runThrows;
+              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` } }])) };
+            },
+          }
+        : {}),
+      ...(opts.fallback ? { groupFallback: async () => opts.fallback } : {}),
+    } as never);
+    w.registry.register({
+      kind: "fake-plain",
+      async plan(_ctx: DeployContext, input: StackInput) {
+        w.planned.push(input.root);
+        const p = planOf(input, true);
+        return { ...p, changeSet: { member: p.changeSet.member, entries: [] } };
+      },
+      async run(_ctx: DeployContext, input: StackInput) {
+        w.applied.push(input.root);
+        return { outputs: { id: `${input.root}-id` } };
+      },
+    } as never);
+    return w;
+  }
+
+  /** The fan-out `pr.ts`'s prepare step derives: planFanOut, then the groups placed. */
+  async function prepared(components: DriverComponent[], changed: string[], registry: CapabilityRegistry): Promise<FanOutPlan> {
+    const plan = planFanOut({ components, changed });
+    return groupFanOut(plan, components, await findComponentGroups({ components, plan, registry, env: "prod" }));
+  }
+
+  const approvedBy = async (digest: string) =>
+    approvalOf(await decidePrGate(memoryGateLedgerPort({ resolutions: [approval(digest)] }), { op: "pr-12", gate: "pr-apply", digest, now: NOW }));
+
+  test("A, B reading A's new output and C reading B's: one planGroup call, one digest, no unknownInputs, one runGroup call under one approval", async () => {
+    const w = groupWorld({ group: true });
+    const plan = await prepared(ABC, ["a"], w.registry);
+    expect(plan.groups).toEqual([{ capability: "fake-stack", components: ["a", "b", "c"] }]);
+    expect(plan.waves).toEqual([["a", "b", "c"], [], []]);
+
+    const set = await planPrSet({ components: ABC, plan, registry: w.registry, env: "prod" });
+    expect(w.planGroupCalls).toEqual([["a", "b", "c"]]);
+    expect(w.planned).toEqual([]);
+    expect(set.failed).toBe(false);
+    expect(set.members.map((m) => [m.member, m.status, m.unknownInputs])).toEqual([
+      ["a", "planned", undefined],
+      ["b", "planned", undefined],
+      ["c", "planned", undefined],
+    ]);
+    // The report still draws the line from b to a, unknown at plan.
+    expect(set.members.find((m) => m.member === "b")?.reads).toEqual([{ upstream: "a", outputs: ["id"], unknown: ["id"] }]);
+    const groupDigest = set.groups?.[0]?.digest;
+    expect(groupDigest).toEqual(expect.stringMatching(/sha256:/));
+    expect(set.doc.members.map((m) => [m.member, m.group])).toEqual([
+      ["a", { digest: groupDigest, reads: [] }],
+      ["b", { digest: groupDigest, reads: ["a.id"] }],
+      ["c", { digest: groupDigest, reads: ["b.id"] }],
+    ]);
+    // The member's digest binds the group's; the document's binds every member's.
+    expect(set.doc.members.find((m) => m.member === "a")?.planDigest).toBe(
+      computePlanDigest("capability-group-member", { plan: computePlanDigest("fake-stack", { root: "a", vars: null }), group: groupDigest }),
+    );
+    expect(set.doc.digest).toBe(changeSetDocumentDigest(set.doc));
+    // Ruling 4: unknown reads inside the group keep the change set from passing as empty.
+    expect(isEmptyChangeSet(set.doc)).toBe(false);
+
+    const firstApproval = await approvedBy(set.doc.digest);
+    expect(firstApproval.status).toBe("approved");
+    let asked = 0;
+    const applied = await applyPrSet({
+      components: ABC,
+      plan,
+      registry: w.registry,
+      env: "prod",
+      set,
+      approval: firstApproval,
+      decideRound: async () => {
+        asked++;
+        return { satisfied: false, approval: { status: "pending" } };
+      },
+    });
+    expect(w.runGroupCalls.map((c) => c.components)).toEqual([["a", "b", "c"]]);
+    expect(w.applied).toEqual([]);
+    expect(asked).toBe(0);
+    expect(applied.rounds).toBeUndefined();
+    expect(applied.status).toBe("applied");
+    expect(applied.members.map((m) => [m.member, m.status])).toEqual([
+      ["a", "applied"],
+      ["b", "applied"],
+      ["c", "applied"],
+    ]);
+    // runGroup got the bound group digest, the artifact planGroup gave, and b's read of a left out of its input.
+    const call = w.runGroupCalls[0]!;
+    expect(call.run.digest).toBe(groupDigest);
+    expect(call.run.artifact).toEqual({ composed: ["a", "b", "c"] });
+    expect(call.members[1]).toMatchObject({ component: "b", input: { root: "b", vars: {} }, reads: [{ at: "/vars/upstream", ref: "a.id", component: "a", output: "id" }] });
+    expect(applied.run.componentOutputs.c).toEqual({ id: "c-id" });
+  });
+
+  test("the same three without planGroup plan and apply as on main: one by one, B and C wait on unknown inputs for a round", async () => {
+    const w = groupWorld();
+    const derived = planFanOut({ components: ABC, changed: ["a"] });
+    const plan = await prepared(ABC, ["a"], w.registry);
+    expect(plan).toEqual(derived);
+
+    const set = await planPrSet({ components: ABC, plan, registry: w.registry, env: "prod" });
+    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.members.map((m) => [m.member, m.unknownInputs])).toEqual([
+      ["a", undefined],
+      ["b", ["a.id"]],
+      ["c", ["b.id"]],
+    ]);
+    const applied = await applyPrSet({
+      components: ABC,
+      plan,
+      registry: w.registry,
+      env: "prod",
+      set,
+      approval: await approvedBy(set.doc.digest),
+      decideRound: async () => ({ satisfied: false, approval: { status: "pending" } }),
+    });
+    expect(w.runGroupCalls).toEqual([]);
+    expect(w.applied[0]).toBe("a");
+    const round = applied.rounds?.[0];
+    expect(round?.round).toBe(2);
+    expect(round?.covered !== undefined || round?.status === "waiting").toBe(true);
+  });
+
+  test("a capability that refuses the set says why; the members plan one by one and the reason is in the plan set", async () => {
+    const w = groupWorld({ group: true, fallback: { kind: "too-many", reason: "fake-stack composes two at most" } });
+    const plan = await prepared(ABC, ["a"], w.registry);
+    expect(plan.groups).toBeUndefined();
+    const set = await planPrSet({ components: ABC, plan, registry: w.registry, env: "prod" });
+    expect(w.planGroupCalls).toEqual([]);
+    expect(w.planned).toEqual(["a", "b", "c"]);
+    expect(set.fallbacks).toEqual(
+      ["a", "b", "c"].map((component) => ({ component, capability: "fake-stack", kind: "too-many", reason: "fake-stack composes two at most" })),
+    );
+    expect(set.members.find((m) => m.member === "b")?.unknownInputs).toEqual(["a.id"]);
+  });
+
+  test("two plans of one group on one estate give one digest; a group with one more member gives another", async () => {
+    const w = groupWorld({ group: true });
+    const plan = await prepared(ABC, ["a"], w.registry);
+    const first = await planPrSet({ components: ABC, plan, registry: w.registry, env: "prod" });
+    const again = await planPrSet({ components: ABC, plan, registry: w.registry, env: "prod" });
+    expect(again.doc.digest).toBe(first.doc.digest);
+    expect(again.groups?.[0]?.digest).toBe(first.groups?.[0]?.digest);
+
+    const ABCE = [...ABC, stack("e", ["c"], { upstream: so("c", "id") })];
+    const wider = await prepared(ABCE, ["a"], w.registry);
+    expect(wider.groups).toEqual([{ capability: "fake-stack", components: ["a", "b", "c", "e"] }]);
+    const more = await planPrSet({ components: ABCE, plan: wider, registry: w.registry, env: "prod" });
+    expect(more.groups?.[0]?.digest).not.toBe(first.groups?.[0]?.digest);
+    // a plans the same on its own, and still its digest moves with the group's.
+    const a = (s: PrPlanSet) => s.doc.members.find((m) => m.member === "a")?.planDigest;
+    expect(a(more)).not.toBe(a(first));
+    expect(more.doc.digest).not.toBe(first.doc.digest);
+  });
+
+  test("a runGroup that applies A, fails on B and never starts C: A applied, B failed, C not-started, and what depends on C outside the group is blocked by it", async () => {
+    const w = groupWorld({ group: true });
+    w.outcome = () => ({
+      members: {
+        a: { status: "applied", outputs: { id: "a-id" } },
+        b: { status: "failed", error: "b: quota exceeded" },
+        c: { status: "not-started" },
+      },
+    });
+    const components = [...ABC, plainStack("d", ["c"], { upstream: so("c", "id") })];
+    const plan = await prepared(components, ["a"], w.registry);
+    expect(plan.waves).toEqual([["a", "b", "c"], [], [], ["d"]]);
+    const set = await planPrSet({ components, plan, registry: w.registry, env: "prod" });
+    const applied = await applyPrSet({ components, plan, registry: w.registry, env: "prod", set, approval: await approvedBy(set.doc.digest) });
+    expect(applied.status).toBe("failed");
+    expect(Object.fromEntries(applied.members.map((m) => [m.member, m.status]))).toEqual({ a: "applied", b: "failed", c: "not-started", d: "blocked" });
+    expect(applied.members.find((m) => m.member === "b")?.error).toBe("b: quota exceeded");
+    expect(applied.members.find((m) => m.member === "d")?.blockedBy).toBe("c");
+    expect(applied.run.notStarted).toEqual(["c"]);
+    expect(applied.run.componentOutputs.a).toEqual({ id: "a-id" });
+    expect(w.applied).toEqual([]);
+    // pr-apply exits with the failed run's code.
+    expect(failedRunExitCode(applied.run.results)).toBe(1);
+  });
+
+  test("a runGroup that throws a moved plan leaves every member not-started and exits 3; any other throw fails every member", async () => {
+    const moved = groupWorld({ group: true });
+    moved.runThrows = Object.assign(new Error("the target moved since it was planned"), { planMoved: true });
+    const plan = await prepared(ABC, ["a"], moved.registry);
+    const set = await planPrSet({ components: ABC, plan, registry: moved.registry, env: "prod" });
+    const stopped = await applyPrSet({ components: ABC, plan, registry: moved.registry, env: "prod", set });
+    expect(stopped.members.map((m) => m.status)).toEqual(["not-started", "not-started", "not-started"]);
+    expect(failedRunExitCode(stopped.run.results)).toBe(3);
+
+    const broken = groupWorld({ group: true });
+    broken.runThrows = new Error("connection reset");
+    const set2 = await planPrSet({ components: ABC, plan, registry: broken.registry, env: "prod" });
+    const failed = await applyPrSet({ components: ABC, plan, registry: broken.registry, env: "prod", set: set2 });
+    expect(failed.members.map((m) => [m.status, m.error])).toEqual([
+      ["failed", "connection reset"],
+      ["failed", "connection reset"],
+      ["failed", "connection reset"],
+    ]);
+    expect(failedRunExitCode(failed.run.results)).toBe(1);
+  });
+
+  test("a planGroup that throws makes every member plan-failed, and nothing falls back", async () => {
+    const w = groupWorld({ group: true });
+    w.planThrows = new Error("cannot compose: backends differ");
+    const plan = await prepared(ABC, ["a"], w.registry);
+    const set = await planPrSet({ components: ABC, plan, registry: w.registry, env: "prod" });
+    expect(set.failed).toBe(true);
+    expect(w.planned).toEqual([]);
+    expect(set.members.map((m) => [m.member, m.status, m.error])).toEqual([
+      ["a", "plan-failed", "cannot compose: backends differ"],
+      ["b", "plan-failed", "cannot compose: backends differ"],
+      ["c", "plan-failed", "cannot compose: backends differ"],
+    ]);
+    expect(set.groups).toEqual([{ capability: "fake-stack", components: ["a", "b", "c"], digest: null, error: "cannot compose: backends differ" }]);
+  });
+
+  test("under --wave-gate the group is part of the wave it was placed in, and the wave's digest covers it", async () => {
+    const w = groupWorld({ group: true });
+    const components = [plainStack("x"), stack("a", ["x"], { upstream: so("x", "id") }), stack("b", ["a"], { upstream: so("a", "id") }), stack("c", ["b"], { upstream: so("b", "id") })];
+    const plan = await prepared(components, ["x"], w.registry);
+    expect(plan.waves).toEqual([["x"], ["a", "b", "c"], [], []]);
+    const approved = await planPrSet({ components, plan, registry: w.registry, env: "prod" });
+
+    const wave = prWavePlan(plan, components, 2, ["x"]);
+    expect(wave.groups).toEqual(plan.groups);
+    const fresh = await planPrSet({ components, plan: wave, registry: w.registry, env: "prod", seededOutputs: approved.outputs });
+    expect(w.planGroupCalls).toEqual([
+      ["a", "b", "c"],
+      ["a", "b", "c"],
+    ]);
+    expect(fresh.doc.members.map((m) => m.member)).toEqual(["a", "b", "c"]);
+    expect(fresh.doc.members.map((m) => m.group?.digest)).toEqual(approved.doc.members.filter((m) => m.member !== "x").map((m) => m.group?.digest));
+    expect(waveNotCovered(approved.doc, fresh.doc, approved.members, { approved: approved.shapes, fresh: fresh.shapes })).toEqual([]);
+    // A wave whose group composed differently is not covered by the digest.
+    const other = groupWorld({ group: true });
+    const wider = [...components, stack("e", ["c"], { upstream: so("c", "id") })];
+    const widerPlan = await prepared(wider, ["x"], other.registry);
+    const widerWave = await planPrSet({ components: wider, plan: prWavePlan(widerPlan, wider, 2, ["x"]), registry: other.registry, env: "prod", seededOutputs: approved.outputs });
+    const a = (s: PrPlanSet) => s.doc.members.find((m) => m.member === "a")?.planDigest;
+    expect(a(widerWave)).not.toBe(a(approved));
+  });
+
+  describe("the report names each group and member outcome, and a resume plans what is left (#4446)", () => {
+    const at = { pr: 12, env: "prod", base: "1".repeat(40), head: "2".repeat(40), op: "pr-12", gate: "pr-apply" };
+    const signal = { changed: ["a"], indeterminate: [], unclaimed: [] };
+    /** A, B and C, where B fails and C never starts. */
+    const failOnB = (w: ReturnType<typeof groupWorld>) => {
+      w.outcome = () => ({
+        members: {
+          a: { status: "applied", outputs: { id: "a-id" } },
+          b: { status: "failed", error: "b: quota exceeded" },
+          c: { status: "not-started" },
+        },
+      });
+    };
+    /** The first attempt: plan, approve, apply with B failing. What a `--resume` record keeps. */
+    async function failedAttempt(w: ReturnType<typeof groupWorld>) {
+      failOnB(w);
+      const plan = await prepared(ABC, ["a"], w.registry);
+      const set = await planPrSet({ components: ABC, plan, registry: w.registry, env: "prod" });
+      const firstApproval = await approvedBy(set.doc.digest);
+      const first = await applyPrSet({ components: ABC, plan, registry: w.registry, env: "prod", set, approval: firstApproval });
+      w.outcome = undefined;
+      return { plan, set, first, firstApproval, record: recordOf(set) };
+    }
+
+    test("a plan report for the three-member group lists one group with three members, its wave and the group digest", async () => {
+      const w = groupWorld({ group: true });
+      const plan = await prepared(ABC, ["a"], w.registry);
+      const set = await planPrSet({ components: ABC, plan, registry: w.registry, env: "prod" });
+      const report = prReport({ stage: "plan", ...at, plan, signal, set, approval: { status: "pending" }, status: "planned" });
+      expect(report.groups).toEqual([
+        {
+          capability: "fake-stack",
+          components: ["a", "b", "c"],
+          wave: 1,
+          digest: set.groups![0]!.digest,
+          reads: [
+            { component: "b", ref: "a.id" },
+            { component: "c", ref: "b.id" },
+          ],
+        },
+      ]);
+      expect(report.groups![0]!.digest).toEqual(expect.stringMatching(/sha256:/));
+      expect(report.fallbacks).toBeUndefined();
+      expect(report.members.map((m) => [m.member, m.group, m.groupOutcome])).toEqual([
+        ["a", 0, undefined],
+        ["b", 0, undefined],
+        ["c", 0, undefined],
+      ]);
+      // The run's artifact stays in the process that planned.
+      expect(JSON.stringify(report.groups)).not.toContain("composed");
+      const note = renderPrNote(report);
+      expect(note).toContain("`a`, `b` and `c` plan and apply as one (`fake-stack`, wave 1); `b` reads `a.id` and `c` reads `b.id`, known when the group applies.");
+    });
+
+    test("an apply report after a failure on B lists A applied, B failed, C not-started, and the note says plainly that A stays applied", async () => {
+      const w = groupWorld({ group: true });
+      const { plan, set, first, firstApproval } = await failedAttempt(w);
+      const report = prReport({ stage: "apply", ...at, plan, signal, set, approval: firstApproval, status: first.status, members: first.members });
+      expect(report.status).toBe("failed");
+      expect(report.members.map((m) => [m.member, m.status, m.groupOutcome, m.group])).toEqual([
+        ["a", "applied", "applied", 0],
+        ["b", "failed", "failed", 0],
+        ["c", "not-started", "not-started", 0],
+      ]);
+      const note = renderPrNote(report);
+      expect(note).toContain("The apply failed: 1 failed, 1 not started, 1 applied.");
+      expect(note).toContain("The group's apply stopped part way: `a` applied and stays applied; `b` failed; `c` did not start. Nothing that applied is undone.");
+      expect(note).toContain("`pr-apply --resume` plans `b` and `c` again");
+    });
+
+    test("pr-apply --resume on that record plans B and C only, as a smaller group, and applies them under the first approval", async () => {
+      const w = groupWorld({ group: true });
+      const { plan, set, first, firstApproval, record } = await failedAttempt(w);
+      expect(first.run.completed).toEqual(["a"]);
+      w.planGroupCalls.length = 0;
+      w.runGroupCalls.length = 0;
+
+      const resumed = await resumePrSet({ components: ABC, plan, registry: w.registry, env: "prod", record, completed: first.run.completed, applied: { a: first.run.componentOutputs.a! } });
+      if (!resumed.ok) throw new Error(resumed.reasons.join("; "));
+      expect(resumed.plan.order).toEqual(["b", "c"]);
+      expect(resumed.plan.groups).toEqual([{ capability: "fake-stack", components: ["b", "c"] }]);
+      expect(w.planGroupCalls).toEqual([["b", "c"]]);
+      expect(w.planned).toEqual([]);
+      // The smaller group's digest is not the approved one, so coverage rested on entries.
+      expect(resumed.fresh.groups?.[0]?.digest).not.toBe(set.groups?.[0]?.digest);
+      expect(resumed.set.doc.digest).toBe(set.doc.digest);
+      expect(resumed.set.groups?.map((g) => g.components)).toEqual([["b", "c"]]);
+
+      let asked = 0;
+      const applied = await applyPrSet({
+        components: ABC,
+        plan: resumed.plan,
+        registry: w.registry,
+        env: "prod",
+        set: resumed.set,
+        approval: firstApproval,
+        resumed: { completed: first.run.completed, outputs: { a: first.run.componentOutputs.a! } },
+        decideRound: async () => {
+          asked++;
+          return { satisfied: false, approval: { status: "pending" } };
+        },
+      });
+      expect(asked).toBe(0);
+      expect(applied.rounds).toBeUndefined();
+      expect(applied.status).toBe("applied");
+      // B planned and applied against the id A applied with.
+      expect(w.runGroupCalls.map((c) => c.components)).toEqual([["b", "c"]]);
+      expect(w.runGroupCalls[0]!.members[0]).toMatchObject({ component: "b", input: { root: "b", vars: { upstream: "a-id" } } });
+      expect(applied.members.map((m) => [m.member, m.status, m.groupOutcome])).toEqual([
+        ["a", "applied", undefined],
+        ["b", "applied", "applied"],
+        ["c", "applied", "applied"],
+      ]);
+      const report = prReport({ stage: "apply", ...at, plan, signal, set: resumed.set, approval: firstApproval, status: applied.status, members: applied.members, resumed: first.run.completed });
+      expect(report.groups?.map((g) => g.components)).toEqual([["b", "c"]]);
+      expect(report.members.map((m) => [m.member, m.group])).toEqual([
+        ["a", undefined],
+        ["b", 0],
+        ["c", 0],
+      ]);
+    });
+
+    test("a resume whose new plans the approved set does not cover carries nothing, and the new plan waits at its gate", async () => {
+      const w = groupWorld({ group: true });
+      const { plan, set, first, record } = await failedAttempt(w);
+      w.extra.add("c");
+      const resumed = await resumePrSet({ components: ABC, plan, registry: w.registry, env: "prod", record, completed: first.run.completed, applied: { a: first.run.componentOutputs.a! } });
+      expect(resumed.ok).toBe(false);
+      if (resumed.ok) return;
+      expect(resumed.reasons.join("; ")).toMatch(/res\.extra/);
+      // pr-apply then plans every member again, and that plan's digest has no approval of its own.
+      const again = await planPrSet({ components: ABC, plan, registry: w.registry, env: "prod" });
+      expect(again.doc.digest).not.toBe(set.doc.digest);
+      const ledger = memoryGateLedgerPort({ resolutions: [approval(set.doc.digest)] });
+      const check = await decidePrGate(ledger, { op: "pr-12", gate: "pr-apply", digest: again.doc.digest, now: NOW });
+      expect(check.satisfied).toBe(false);
+      expect(approvalOf(check).status).toBe("changed");
+    });
+
+    test("a resume whose capability refuses the smaller group plans what is left one by one, and says why", async () => {
+      const w = groupWorld({ group: true });
+      const { plan, first, record } = await failedAttempt(w);
+      // From here on the capability takes no group.
+      const refusing = groupWorld({ group: true, fallback: { kind: "too-many", reason: "fake-stack composes three or none" } });
+      const resumed = await resumePrSet({ components: ABC, plan, registry: refusing.registry, env: "prod", record, completed: first.run.completed, applied: { a: first.run.componentOutputs.a! } });
+      expect(refusing.planGroupCalls).toEqual([]);
+      expect(refusing.planned).toEqual(["b", "c"]);
+      const fresh = resumed.fresh!;
+      expect(fresh.groups).toBeUndefined();
+      expect(fresh.fallbacks).toEqual(["b", "c"].map((component) => ({ component, capability: "fake-stack", kind: "too-many", reason: "fake-stack composes three or none" })));
+    });
+
+    test("a set the capability refused is under fallbacks with its reason, and the note prints it; kind off is reported and not printed", async () => {
+      const w = groupWorld({ group: true, fallback: { kind: "too-many", reason: "fake-stack composes two at most" } });
+      const plan = await prepared(ABC, ["a"], w.registry);
+      const set = await planPrSet({ components: ABC, plan, registry: w.registry, env: "prod" });
+      const report = prReport({ stage: "plan", ...at, plan, signal, set, approval: { status: "pending" }, status: "planned" });
+      expect(report.groups).toBeUndefined();
+      expect(report.fallbacks).toEqual(
+        ["a", "b", "c"].map((component) => ({ component, capability: "fake-stack", kind: "too-many", reason: "fake-stack composes two at most" })),
+      );
+      expect(report.members.every((m) => m.group === undefined)).toBe(true);
+      expect(renderPrNote(report)).toContain("Planned one by one, not as a group: `a`, `b`, `c` (`too-many`): fake-stack composes two at most.");
+
+      const off = groupWorld({ group: true, fallback: { kind: "off", reason: "terraform.compose is not set" } });
+      const offPlan = await prepared(ABC, ["a"], off.registry);
+      const offSet = await planPrSet({ components: ABC, plan: offPlan, registry: off.registry, env: "prod" });
+      const offReport = prReport({ stage: "plan", ...at, plan: offPlan, signal, set: offSet, approval: { status: "pending" }, status: "planned" });
+      expect(offReport.fallbacks?.map((f) => f.kind)).toEqual(["off", "off", "off"]);
+      expect(renderPrNote(offReport)).not.toContain("not as a group");
+    });
+  });
+});