@intentius/chant 0.124.51 → 0.124.54

package/src/components/pr-run.ts

@@ -23,8 +23,9 @@
  *   component in the project and not the selection.
  * - the upstream is in the change and its plan cannot say, or says the value
  *   is known only after apply: no value. The dependent's members list the
- *   reference under `unknownInputs`, and the approval does not cover what
- *   it will do with it.
+ *   reference under `unknownInputs`. The apply plans it again once the
+ *   upstream applied, and the approval covers that round when it matches the
+ *   preview (see `coveredRound`).
  *
  * `--seed-outputs` wins over both. The apply stage's plan reads the same
  * values, so on the same estate it gets the digest the plan stage showed.
@@ -66,6 +67,14 @@
  * says whether the approved change set covers what it planned, by the same
  * test a resume uses ({@link planCoveredBy}). Covered, the wave applies under
  * the pull request's approval; not covered, it needs its own.
+ *
+ * ## Groups
+ *
+ * A fan-out with `groups` (ws-107, `./groups.ts`) plans each group with one
+ * `planGroup` call at its wave and applies it with one `runGroup` call
+ * there. A member's read of another member of its group is computed by that
+ * apply: it is no `unknownInputs` entry and holds nothing back. Each member's
+ * digest binds the group's, so the one approval binds the composition.
  */
 
 import { composeChangeSet, verifyChangeSetDigest, type ChangeSetDocument, type ChangeSetEntry, type ChangeSetPart } from "../change-set";
@@ -77,7 +86,9 @@ import {
   PR_REPORT_CONTRACT,
   PR_REPORT_SCHEMA_ID,
   type PrApproval,
+  type PrGroup,
   type PrMember,
+  type PrMemberRead,
   type PrRefusal,
   type PrRound,
   type PrReport,
@@ -88,17 +99,20 @@ import {
   deployContext,
   movedWiringReferences,
   unresolvedWiringReferences,
+  wiringReads,
   type DriverComponent,
   type DriverComponentResult,
 } from "./driver";
 import { deployUnits } from "./deploy-units";
 import { runFanOut, type FanOutRunResult } from "./fan-out-run";
-import { remainingFanOut, type ComponentChangeSignal, type FanOutPlan } from "./fan-out";
+import { remainingFanOut, type ComponentChangeSignal, type FanOutGroup, type FanOutGroupFallback, type FanOutPlan } from "./fan-out";
+import { coveredRound, type PlanShape, type RoundCoverage } from "./covered-round";
 import type { PrApplyRecord } from "./fan-out-record";
-import type { CapabilityRegistry, PlannedOutputs } from "./capability";
+import type { CapabilityRegistry, GroupRun, PlannedOutputs } from "./capability";
+import { groupsByComponent, narrowGroups, planComponentGroup, regroupRemaining } from "./groups";
 import type { RunProgressEvent } from "./run-progress";
 import type { RunEventSink } from "../run-event-stream";
-import { capabilitySteps, planWaveComponent, readDeployedOutputs } from "./wave-plan";
+import { capabilitySteps, planWaveComponent, readDeployedOutputs, type WaveComponentPlan } from "./wave-plan";
 import type { PrMigrationFile } from "../pr-migrations";
 
 export interface PrPlanSetOptions {
@@ -145,10 +159,26 @@ export interface PrPlanSet {
    * report's `plannedOutputs`.
    */
   plannedOutputs?: Record<string, string[]>;
+  /** The shapes lexicons supplied with their plans (#4419), by member. */
+  shapes?: Record<string, PlanShape>;
+  /** The groups planned as one (ws-107), in plan order of their first member. Absent when none. */
+  groups?: PrPlanGroup[];
+  /** The components that could have grouped and did not, with why (ws-107, ruling 1): the fan-out's `fallbacks`. */
+  fallbacks?: FanOutGroupFallback[];
   /** Whether any component failed to plan. */
   failed: boolean;
 }
 
+/** A group a pull request planned as one (ws-107). */
+export interface PrPlanGroup extends FanOutGroup {
+  /** The group digest folded into each member's `planDigest`; `null` when the group failed to plan. */
+  digest: string | null;
+  /** Why it failed to plan. Every member is then plan-failed with it. */
+  error?: string;
+  /** What `runGroup` gets back. Like `plans`, it lives in the process that planned. */
+  run?: GroupRun;
+}
+
 /** A failed component's members: the units its steps target, else the component itself. */
 function failedParts(component: DriverComponent, error: string): ChangeSetPart[] {
   const units = deployUnits(component.deploy).map((u) => u.unit);
@@ -178,18 +208,25 @@ export async function planPrSet(options: PrPlanSetOptions): Promise<PrPlanSet> {
   const parts: ChangeSetPart[] = [];
   const componentOf = new Map<string, string>();
   const unknownOf = new Map<string, { unknown: string[]; build: string[] }>();
+  const readsBy = new Map<string, PrMemberRead[]>();
   const plans: Record<string, Record<string, unknown>> = {};
+  const shapes: Record<string, PlanShape> = {};
   let failed = false;
   const emit = options.onRunEvent;
   emit?.({ type: "phase-start", component: null, phase: PR_PLAN_PHASE });
+  // ws-107: each group plans once, in its wave, with one call.
+  const groupOf = groupsByComponent(options.plan);
+  const groups: PrPlanGroup[] = [];
 
   for (const wave of options.plan.waves) {
     // The dependencies' outputs first, each once. One the change plans is
     // read from its plan, which an earlier wave made (#3999). Any other is
     // read from the deployed estate (#4104). A dependency that cannot say
     // leaves its references unresolved, which its dependent's plan reports
-    // if it needs them.
-    const deps = [...new Set(wave.flatMap((name) => byName.get(name)?.dependsOn ?? []))].filter((dep) => !read.has(dep));
+    // if it needs them. A member of the dependent's own group plans with it.
+    const deps = [
+      ...new Set(wave.flatMap((name) => (byName.get(name)?.dependsOn ?? []).filter((dep) => !groupOf.get(name)?.components.includes(dep)))),
+    ].filter((dep) => !read.has(dep));
     const fromEstate: string[] = [];
     for (const dep of deps) {
       read.add(dep);
@@ -203,26 +240,60 @@ export async function planPrSet(options: PrPlanSetOptions): Promise<PrPlanSet> {
       planned[dep] = Object.keys(known).sort();
     }
     Object.assign(deployed, await readDeployedOutputs(fromEstate, byName, options.registry, (dep) => deployContext(options, dep), outputs));
-    const results = await Promise.all(
-      wave.map(async (name) => {
-        const at = { component: name, phase: PR_PLAN_PHASE, step: "plan" };
-        emit?.({ type: "step-start", ...at });
-        const start = Date.now();
-        const p = await planWaveComponent(byName.get(name)!, options.registry, deployContext(options, name), outputs);
-        emit?.({
-          type: "step-settle",
-          ...at,
-          status: "error" in p ? "failed" : "ok",
-          durationMs: Date.now() - start,
-          ...("error" in p ? { error: p.error } : {}),
-        });
-        return p;
-      }),
-    );
+    const settle = (name: string, start: number, p: WaveComponentPlan): void => {
+      emit?.({
+        type: "step-settle",
+        component: name,
+        phase: PR_PLAN_PHASE,
+        step: "plan",
+        status: "error" in p ? "failed" : "ok",
+        durationMs: Date.now() - start,
+        ...("error" in p ? { error: p.error } : {}),
+      });
+    };
+    const groupsHere = [...new Set(wave.map((name) => groupOf.get(name)).filter((g): g is FanOutGroup => g !== undefined))];
+    const results = (
+      await Promise.all([
+        ...wave
+          .filter((name) => !groupOf.has(name))
+          .map(async (name) => {
+            emit?.({ type: "step-start", component: name, phase: PR_PLAN_PHASE, step: "plan" });
+            const start = Date.now();
+            const p = await planWaveComponent(byName.get(name)!, options.registry, deployContext(options, name), outputs);
+            settle(name, start, p);
+            return [p];
+          }),
+        ...groupsHere.map(async (group) => {
+          for (const name of group.components) emit?.({ type: "step-start", component: name, phase: PR_PLAN_PHASE, step: "plan" });
+          const start = Date.now();
+          const g = await planComponentGroup({
+            group,
+            components: byName,
+            registry: options.registry,
+            env: options.env,
+            ...(options.vars ? { vars: options.vars } : {}),
+            ctxOf: (name) => deployContext(options, name),
+            outputs,
+          });
+          for (const p of g.plans) settle(p.component, start, p);
+          const error = g.plans.find((p): p is Extract<WaveComponentPlan, { error: string }> => "error" in p)?.error;
+          groups.push({ ...group, digest: g.digest ?? null, ...(error !== undefined ? { error } : {}), ...(g.run ? { run: g.run } : {}) });
+          return g.plans;
+        }),
+      ])
+    ).flat();
+    /** What each member of a group planned to expose, for its group-mates' reads. */
+    const plannedHere = new Map(results.map((p) => [p.component, "error" in p ? undefined : p.outputs?.known]));
     for (const p of results) {
       const component = byName.get(p.component)!;
-      const unknown = unknownInputsOf(component, outputs, inChange);
+      const group = groupOf.get(p.component);
+      const mates = group ? new Set(group.components) : undefined;
+      const unknown = unknownInputsOf(component, outputs, inChange, mates);
       if (unknown.unknown.length > 0 || unknown.build.length > 0) unknownOf.set(p.component, unknown);
+      // A read of a group-mate is known when that mate's plan knows it.
+      const readsView = group ? { ...outputs, ...Object.fromEntries(group.components.filter((c) => c !== p.component).map((c) => [c, { ...(plannedHere.get(c) ?? {}) }])) } : outputs;
+      const reads = readsOf(component, readsView);
+      if (reads.length > 0) readsBy.set(p.component, reads);
       if ("error" in p) {
         failed = true;
         plannedBy.set(p.component, undefined);
@@ -234,6 +305,7 @@ export async function planPrSet(options: PrPlanSetOptions): Promise<PrPlanSet> {
       }
       plannedBy.set(p.component, p.outputs);
       plans[p.component] = p.plans;
+      Object.assign(shapes, p.shapes);
       for (const part of p.parts) {
         parts.push(part);
         componentOf.set(part.member.member, p.component);
@@ -246,6 +318,7 @@ export async function planPrSet(options: PrPlanSetOptions): Promise<PrPlanSet> {
   const members: PrMember[] = doc.members.map((m) => {
     const component = componentOf.get(m.member) ?? m.member;
     const unknown = unknownOf.get(component);
+    const reads = readsBy.get(component);
     return {
       member: m.member,
       component,
@@ -255,17 +328,23 @@ export async function planPrSet(options: PrPlanSetOptions): Promise<PrPlanSet> {
       ...(m.error ? { error: m.error } : {}),
       ...(unknown?.unknown.length ? { unknownInputs: unknown.unknown } : {}),
       ...(unknown?.build.length ? { buildInputs: unknown.build } : {}),
+      ...(reads ? { reads } : {}),
     };
   });
   const sorted = (r: Record<string, string[]>) => Object.fromEntries(Object.entries(r).sort(([a], [b]) => a.localeCompare(b)));
   const deployedOutputs = sorted(deployed);
   const plannedOutputs = sorted(planned);
+  const at = new Map(options.plan.order.map((name, i) => [name, i]));
+  groups.sort((a, b) => (at.get(a.components[0]!) ?? 0) - (at.get(b.components[0]!) ?? 0));
   return {
     doc,
     members,
     plans,
     outputs,
     failed,
+    ...(groups.length > 0 ? { groups } : {}),
+    ...(options.plan.fallbacks?.length ? { fallbacks: options.plan.fallbacks } : {}),
+    ...(Object.keys(shapes).length > 0 ? { shapes } : {}),
     ...(Object.keys(deployedOutputs).length > 0 ? { deployedOutputs } : {}),
     ...(Object.keys(plannedOutputs).length > 0 ? { plannedOutputs } : {}),
   };
@@ -277,41 +356,72 @@ export async function planPrSet(options: PrPlanSetOptions): Promise<PrPlanSet> {
  * that upstream applies, each sorted. `build` are the published artifact
  * identities a build in the change produces (`WiringReference.publish`):
  * the build's provenance binds those, so they are never approved again.
- * `unknown` are the rest.
+ * `unknown` are the rest. A reference to a member of `group`, the
+ * component's own group (ws-107), is neither: the group's apply computes it.
  */
 function unknownInputsOf(
   component: DriverComponent,
   outputs: Record<string, Record<string, unknown>>,
   inChange: ReadonlySet<string>,
+  group?: ReadonlySet<string>,
 ): { unknown: string[]; build: string[] } {
   const unknown = new Set<string>();
   const build = new Set<string>();
   for (const step of capabilitySteps(component.deploy)) {
     const { kind: _kind, ...rest } = step;
     for (const r of unresolvedWiringReferences(rest, outputs)) {
+      if (group?.has(r.source)) continue;
       if (inChange.has(r.source)) (r.publish ? build : unknown).add(r.ref);
     }
   }
   return { unknown: [...unknown].sort(), build: [...build].sort() };
 }
 
+/**
+ * Every other component's output `component`'s steps read, one entry per
+ * upstream, sorted: what the report's `reads` says. A read whose value
+ * `outputs` holds is listed as well as one it lacks (`unknown`), so the
+ * report names each read between components whether or not the plan knew
+ * its value. A component's reads of its own outputs are left out.
+ */
+function readsOf(component: DriverComponent, outputs: Record<string, Record<string, unknown>>): PrMemberRead[] {
+  const by = new Map<string, { outputs: Set<string>; unknown: Set<string> }>();
+  for (const step of capabilitySteps(component.deploy)) {
+    const { kind: _kind, ...rest } = step;
+    for (const r of wiringReads(rest, outputs)) {
+      if (r.source === component.name) continue;
+      const name = r.ref.slice(r.source.length + 1);
+      const at = by.get(r.source) ?? { outputs: new Set<string>(), unknown: new Set<string>() };
+      by.set(r.source, at);
+      at.outputs.add(name);
+      if (!r.known) at.unknown.add(name);
+    }
+  }
+  return [...by.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([upstream, r]) => ({ upstream, outputs: [...r.outputs].sort(), ...(r.unknown.size > 0 ? { unknown: [...r.unknown].sort() } : {}) }));
+}
+
 /**
  * Why `component` cannot apply the plan that read `read` now that `now`
  * stands (#3999): each reference its steps make that resolves to another
  * value, said once. `undefined` when every one resolves as it did. A
  * published artifact's identity from a build in `inChange` never holds a
- * member back: the build's provenance binds it, not this approval.
+ * member back: the build's provenance binds it, not this approval. Nor
+ * does a reference to a member of `group`, the component's own group
+ * (ws-107), whose apply computes it.
  */
 export function heldReason(
   component: DriverComponent,
   read: Record<string, Record<string, unknown>>,
   now: Record<string, Record<string, unknown>>,
   inChange: ReadonlySet<string> = new Set(),
+  group: ReadonlySet<string> = new Set(),
 ): string | undefined {
   const refs = new Set<string>();
   for (const step of capabilitySteps(component.deploy)) {
     const { kind: _kind, ...rest } = step;
-    for (const r of movedWiringReferences(rest, read, now)) if (!(r.publish && inChange.has(r.source))) refs.add(r.ref);
+    for (const r of movedWiringReferences(rest, read, now)) if (!(r.publish && inChange.has(r.source)) && !group.has(r.source)) refs.add(r.ref);
   }
   if (refs.size === 0) return undefined;
   return `its plan read ${[...refs].sort().join(", ")} before ${refs.size === 1 ? "that output" : "those outputs"} applied as another value`;
@@ -409,13 +519,23 @@ export interface PrApplyOptions {
    * The gate is {@link prRoundGate}. Without it, held members are left
    * `waiting` and nothing is planned again.
    */
-  decideRound?: (round: { round: number; gate: string; set: PrPlanSet; plan: FanOutPlan }) => Promise<PrRoundDecision>;
+  /**
+   * Where the approval of `set` stands (#4419). When it is `approved`, a round
+   * whose fresh plan does only what `set` previewed, with only the inputs it
+   * marked unknown filled in, applies under that approval without a gate of
+   * its own (`coveredRound`), and the round records it (`PrRound.covered`).
+   * Without it every round decides its own gate.
+   */
+  approval?: PrApproval;
+  decideRound?: (round: { round: number; gate: string; set: PrPlanSet; plan: FanOutPlan; notCovered?: string }) => Promise<PrRoundDecision>;
 }
 
 /** How a round's gate was decided: whether it applies, and where its approval stands. */
 export interface PrRoundDecision {
   satisfied: boolean;
   approval: PrApproval;
+  /** Set when the first approval covered the round (#4419): no gate of its own was decided. */
+  covered?: PrRound["covered"];
   /** Why it does not apply, when an approval stands but does not count (`--require-review`). */
   message?: string;
 }
@@ -430,6 +550,98 @@ export interface PrApplyResult {
   rounds?: PrRound[];
 }
 
+/**
+ * Whether the first approval covers a round's fresh plan (#4419). The
+ * approval binds `options.set.doc.digest`; the round's components and
+ * members must be ones that plan previewed, and what differs is only what
+ * it marked unknown.
+ */
+function roundCover(
+  options: PrApplyOptions,
+  fresh: PrPlanSet,
+  plan: FanOutPlan,
+  now: Record<string, Record<string, unknown>>,
+  inChange: ReadonlySet<string>,
+  byName: ReadonlyMap<string, DriverComponent>,
+): RoundCoverage {
+  if (options.approval?.status !== "approved") return { covered: false, reason: "no approval of the first plan stands" };
+  // ws-107: a round's group is covered only when it has the approved group's members.
+  const moved = groupsMoved(options.set.groups ?? [], fresh.groups ?? [], plan.order);
+  if (moved) return { covered: false, reason: moved };
+  // The values the round reads of a component it plans again are the ones
+  // that plan says it will expose: it has not applied yet, so the outputs
+  // standing say nothing of it. An output the first plan knew and the round's
+  // plan knows as the same value is not a changed input, whichever of the
+  // two applies first.
+  const reads: Record<string, Record<string, unknown>> = { ...now };
+  for (const name of plan.order) if (fresh.outputs[name]) reads[name] = fresh.outputs[name]!;
+  const changedKnown: Record<string, string[]> = {};
+  for (const name of plan.order) {
+    const component = byName.get(name);
+    if (!component) continue;
+    const refs = new Set<string>();
+    for (const step of capabilitySteps(component.deploy)) {
+      const { kind: _kind, ...rest } = step;
+      for (const r of movedWiringReferences(rest, options.set.outputs, reads)) if (!(r.publish && inChange.has(r.source))) refs.add(r.ref);
+    }
+    changedKnown[name] = [...refs].sort();
+  }
+  // A member whose round plan still reads only outputs of components this
+  // round plans and has not applied (a chain of imports, #4466d) cannot apply
+  // in this round: it is held again once those apply, and its own round
+  // checks its coverage. Only the members this round can apply are checked.
+  const inRound = plan.order;
+  const fromRound = (ref: string): boolean => inRound.some((c) => ref === c || ref.startsWith(`${c}.`));
+  const waits = (m: { unknownInputs?: string[] }): boolean => (m.unknownInputs?.length ?? 0) > 0 && m.unknownInputs!.every(fromRound);
+  const approved = { doc: options.set.doc, members: options.set.members, ...(options.set.shapes ? { shapes: options.set.shapes } : {}) };
+  return coveredRound({
+    approved,
+    approvedDigest: options.set.doc.digest,
+    fresh: { doc: fresh.doc, members: fresh.members.filter((m) => !waits(m)), ...(fresh.shapes ? { shapes: fresh.shapes } : {}) },
+    changedKnown,
+    attributes: (member) => memberAttributes(options.set.doc, fresh.doc, member, fresh.shapes?.[member] !== undefined),
+  });
+}
+
+/**
+ * Why the groups `fresh` planned are not the `approved` ones over the
+ * components in `order` (ws-107), or `undefined` when each group the round
+ * plans has the members the approved group had.
+ */
+function groupsMoved(approved: readonly FanOutGroup[], fresh: readonly FanOutGroup[], order: readonly string[]): string | undefined {
+  const same = (a: readonly string[], b: readonly string[]): boolean => a.length === b.length && a.every((c) => b.includes(c));
+  const inRound = new Set(order);
+  for (const was of approved) {
+    const here = was.components.filter((c) => inRound.has(c));
+    if (here.length === 0) continue;
+    const now = fresh.find((g) => g.components.includes(here[0]!));
+    if (!now || !same(now.components, was.components)) {
+      return `the approved plan grouped ${was.components.join(", ")}, and the round ${now ? `groups ${now.components.join(", ")}` : `plans ${here.join(", ")} without that group`}`;
+    }
+  }
+  for (const now of fresh) {
+    if (!approved.some((was) => same(was.components, now.components))) return `the round groups ${now.components.join(", ")}, which the approved plan did not`;
+  }
+  return undefined;
+}
+
+/**
+ * The part of coverage that reads the change set's own attributes, shared by
+ * a round, a resume and a wave: a member whose planner describes no changes
+ * (and gave no shape) is covered only by the digest it was approved with, and
+ * anything else is {@link planCoveredBy}'s.
+ */
+function memberAttributes(approved: ChangeSetDocument, fresh: ChangeSetDocument, member: string, hasShape: boolean): string | undefined {
+  if (!hasShape) {
+    const now = fresh.members.find((m) => m.member === member);
+    const was = approved.members.find((m) => m.member === member);
+    if (now && was && now.planner === "chant" && now.lexicon === "chant" && now.status === "planned" && now.planDigest !== was.planDigest) {
+      return `${member} now plans to ${now.planDigest}, not the approved ${was.planDigest ?? "(none)"}, and its planner describes no changes to compare`;
+    }
+  }
+  return planCoveredBy(approved, fresh, member);
+}
+
 /** Two runs of one apply as one: `b` ran after `a`, against the outputs `a` left. */
 function joinRuns(a: FanOutRunResult, b: FanOutRunResult): FanOutRunResult {
   const status: FanOutRunResult["status"] = a.status === "fail" || b.status === "fail" ? "fail" : a.status === "gated" || b.status === "gated" ? "gated" : "ok";
@@ -444,6 +656,8 @@ function joinRuns(a: FanOutRunResult, b: FanOutRunResult): FanOutRunResult {
     componentOutputs: b.componentOutputs,
     ...(gate ? { gate } : {}),
     ...(b.held ? { held: b.held } : {}),
+    ...(a.notStarted || b.notStarted ? { notStarted: [...new Set([...(a.notStarted ?? []), ...(b.notStarted ?? [])])].sort() } : {}),
+    ...(a.groupOutcomes || b.groupOutcomes ? { groupOutcomes: { ...(a.groupOutcomes ?? {}), ...(b.groupOutcomes ?? {}) } } : {}),
   };
 }
 
@@ -467,20 +681,25 @@ export async function applyPrSet(options: PrApplyOptions): Promise<PrApplyResult
     ...Object.fromEntries(Object.entries(options.set.outputs).filter(([name]) => !toApply.has(name))),
     ...(options.resumed?.outputs ?? {}),
   };
-  const runRound = (plan: FanOutPlan, plans: Record<string, Record<string, unknown>>, read: Record<string, Record<string, unknown>>, outputs: Record<string, Record<string, unknown>>) =>
-    runFanOut(plan, options.components, options.registry, {
+  const runRound = (plan: FanOutPlan, set: Pick<PrPlanSet, "plans" | "groups">, read: Record<string, Record<string, unknown>>, outputs: Record<string, Record<string, unknown>>) => {
+    // ws-107: each group runs the plan its group planned, and a read of a group-mate holds nothing back.
+    const groupOf = groupsByComponent(plan);
+    const groupRuns = Object.fromEntries((set.groups ?? []).filter((g) => g.run).map((g) => [g.components[0]!, g.run!]));
+    return runFanOut(plan, options.components, options.registry, {
       env: options.env,
       ...(options.vars ? { vars: options.vars } : {}),
-      plans,
+      plans: set.plans,
+      ...(Object.keys(groupRuns).length > 0 ? { groupRuns } : {}),
       ...(options.targets ? { targets: options.targets } : {}),
       componentOutputs: outputs,
-      hold: (name, now) => heldReason(byName.get(name)!, read, now, inChange),
+      hold: (name, now) => heldReason(byName.get(name)!, read, now, inChange, new Set(groupOf.get(name)?.components ?? [])),
       ...(options.onProgress ? { onProgress: options.onProgress } : {}),
       ...(options.onRunEvent ? { onRunEvent: options.onRunEvent } : {}),
       ...(options.onComponentSettled ? { onComponentSettled: options.onComponentSettled } : {}),
     });
+  };
 
-  let run = await runRound(options.plan, options.set.plans, options.set.outputs, { ...standing });
+  let run = await runRound(options.plan, options.set, options.set.outputs, { ...standing });
   const rounds: PrRound[] = [];
   /** Per component, the round that applied it or holds it, and that round's set, after the first. */
   const roundOf = new Map<string, { round: number; set: PrPlanSet }>();
@@ -489,7 +708,8 @@ export async function applyPrSet(options: PrApplyOptions): Promise<PrApplyResult
     const round = rounds.length + 2;
     const gate = prRoundGate(options.gate ?? PR_APPLY_GATE, round);
     const heldNames = new Set(run.held.map((h) => h.component));
-    const plan = remainingFanOut(options.plan, options.components, { completed: options.plan.order.filter((name) => !heldNames.has(name)) });
+    // A held group is planned again as the same group (ws-107).
+    const plan = narrowGroups(remainingFanOut(options.plan, options.components, { completed: options.plan.order.filter((name) => !heldNames.has(name)) }), options.components, options.plan.groups);
     const set = await planPrSet({
       components: options.components,
       plan,
@@ -500,39 +720,62 @@ export async function applyPrSet(options: PrApplyOptions): Promise<PrApplyResult
       ...(options.targets ? { targets: options.targets } : {}),
     });
     for (const name of plan.order) roundOf.set(name, { round, set });
-    const record = (status: PrRound["status"], approval: PrApproval, message?: string): void => {
-      rounds.push({ round, gate, digest: set.doc.digest, components: plan.order, approval, status, ...(message ? { message } : {}), changeSet: set.doc });
+    const cover = roundCover(options, set, plan, run.componentOutputs, inChange, byName);
+    const record = (status: PrRound["status"], approval: PrApproval, message?: string, covered?: PrRound["covered"]): void => {
+      rounds.push({
+        round,
+        gate,
+        digest: set.doc.digest,
+        components: plan.order,
+        approval,
+        status,
+        ...(message ? { message } : {}),
+        ...(covered ? { covered } : {}),
+        ...(!covered && options.approval?.status === "approved" && cover.covered === false ? { notCovered: cover.reason } : {}),
+        changeSet: set.doc,
+      });
     };
     if (set.failed) {
       record("plan-failed", { status: "pending" });
       stopped = "plan-failed";
       break;
     }
-    const decision = await options.decideRound({ round, gate, set, plan });
+    const decision: PrRoundDecision =
+      cover.covered && options.approval
+        ? { satisfied: true, approval: options.approval, covered: { digest: cover.digest, filledInputs: cover.filledInputs } }
+        : await options.decideRound({ round, gate, set, plan, ...(options.approval?.status === "approved" && !cover.covered ? { notCovered: cover.reason } : {}) });
     if (!decision.satisfied) {
       record("waiting", decision.approval, decision.message);
       stopped = "waiting";
       break;
     }
-    const next = await runRound(plan, set.plans, set.outputs, run.componentOutputs);
-    record(next.status === "fail" ? "failed" : "applied", decision.approval);
+    const next = await runRound(plan, set, set.outputs, run.componentOutputs);
+    record(next.status === "fail" ? "failed" : "applied", decision.approval, undefined, decision.covered);
     run = joinRuns(run, next);
   }
 
   const completed = new Set(run.completed);
+  const notStarted = new Set(run.notStarted ?? []);
   const held = new Map((run.held ?? []).map((h) => [h.component, h]));
   const blocked = new Map(run.blocked.map((b) => [b.component, b.blockedBy]));
   const errorOf = (component: string): string | undefined => {
     const result = [...run.results].reverse().find((r) => r.component === component);
     if (result?.status === "gated") return `stopped at its own gate ${result.gate?.gate ?? ""}`.trim();
-    return result?.records.find((r) => r.status === "fail")?.error;
+    return result?.records.find((r) => r.status === "fail" || (notStarted.has(component) && r.status === "skipped"))?.error;
   };
   const members = options.set.members.map((m): PrMember => {
     if (priorCompleted.has(m.component)) return { ...m, status: "applied" };
     const later = roundOf.get(m.component);
     const fresh = later?.set.members.find((x) => x.member === m.member);
-    const asPlanned: PrMember = later && fresh ? { ...m, planDigest: fresh.planDigest, counts: fresh.counts, round: later.round } : m;
+    const planned: PrMember = later && fresh ? { ...m, planDigest: fresh.planDigest, counts: fresh.counts, round: later.round } : m;
+    // #4446: how its part of a group's apply ended, as the capability said.
+    const groupOutcome = run.groupOutcomes?.[m.component];
+    const asPlanned: PrMember = groupOutcome ? { ...planned, groupOutcome } : planned;
     if (completed.has(m.component)) return { ...asPlanned, status: "applied" };
+    if (notStarted.has(m.component)) {
+      const error = errorOf(m.component);
+      return { ...asPlanned, status: "not-started", ...(error ? { error } : {}) };
+    }
     const h = held.get(m.component);
     if (h) return { ...asPlanned, status: "waiting", held: h.heldBy ? `${h.heldBy} is held: ${h.reason}` : h.reason };
     if (fresh?.status === "plan-failed") return { ...asPlanned, status: "plan-failed", ...(fresh.error ? { error: fresh.error } : {}) };
@@ -639,6 +882,12 @@ export interface PrResumeOptions {
   record: PrApplyRecord;
   /** Components an earlier attempt applied. */
   completed: string[];
+  /**
+   * The outputs the components in `completed` left (#4446). A member left
+   * of an approved group plans against the outputs its group-mates applied
+   * with, which the group's apply computed and the approved plan did not know.
+   */
+  applied?: Record<string, Record<string, unknown>>;
 }
 
 export type PrResume =
@@ -672,25 +921,48 @@ export type PrResume =
  * is `record.digest`, and the document gives that digest. The digest binds
  * the entries, holes and side effects {@link planCoveredBy} reads (#3555),
  * so a record cannot widen what a re-planned member may do.
+ *
+ * A group that failed part way (ws-107, "Resume"; #4446) leaves its
+ * `partial`, `failed` and `not-started` members; `applied` and `no-changes`
+ * ones are in `completed`. What is left of each approved group is grouped
+ * again ({@link regroupRemaining}), so it plans as a smaller group, or one
+ * by one when the rule or the capability says so. The smaller group's
+ * digest differs from the approved one, so coverage rests on entries and
+ * shapes, as for any resumed member.
  */
 export async function resumePrSet(options: PrResumeOptions): Promise<PrResume> {
   const { record } = options;
   if (record.changeSet.digest !== record.digest || !verifyChangeSetDigest(record.changeSet)) {
     return { ok: false, reasons: [`the record's change set is not the one its digest ${record.digest} names`] };
   }
-  const plan = remainingFanOut(options.plan, options.components, { completed: options.completed });
+  const plan = await regroupRemaining({
+    components: options.components,
+    plan: remainingFanOut(options.plan, options.components, { completed: options.completed }),
+    registry: options.registry,
+    env: options.env,
+    ...(options.vars ? { vars: options.vars } : {}),
+    groups: options.plan.groups,
+    ...(options.plan.fallbacks ? { fallbacks: options.plan.fallbacks } : {}),
+  });
+  // The outputs of the applied members of a group with members left: the values the group's apply computed.
+  const left = new Set(plan.order);
+  const fromGroup = Object.fromEntries(
+    (options.plan.groups ?? [])
+      .filter((g) => g.components.some((c) => left.has(c)))
+      .flatMap((g) => g.components.filter((c) => !left.has(c) && options.applied?.[c] !== undefined))
+      .map((c) => [c, options.applied![c]!]),
+  );
   const fresh = await planPrSet({
     components: options.components,
     plan,
     registry: options.registry,
     env: options.env,
     ...(options.vars ? { vars: options.vars } : {}),
-    seededOutputs: { ...(options.seededOutputs ?? {}), ...options.record.planOutputs },
+    seededOutputs: { ...(options.seededOutputs ?? {}), ...options.record.planOutputs, ...fromGroup },
     ...(options.targets ? { targets: options.targets } : {}),
   });
-  const reasons = fresh.doc.members
-    .map((m) => planCoveredBy(options.record.changeSet, fresh.doc, m.member))
-    .filter((r): r is string => r !== undefined);
+  // #4422: decided as a round decides (`coveredRound`), by the same function a wave uses.
+  const reasons = waveNotCovered(options.record.changeSet, fresh.doc, options.record.members);
   if (reasons.length > 0) return { ok: false, reasons, fresh };
   return {
     ok: true,
@@ -700,7 +972,9 @@ export async function resumePrSet(options: PrResumeOptions): Promise<PrResume> {
       doc: options.record.changeSet,
       members: options.record.members.map((m) => ({ ...m, status: "planned" as const })),
       plans: fresh.plans,
-      outputs: options.record.planOutputs,
+      outputs: { ...options.record.planOutputs, ...fromGroup },
+      ...(fresh.groups ? { groups: fresh.groups } : {}),
+      ...(fresh.fallbacks ? { fallbacks: fresh.fallbacks } : {}),
       failed: false,
     },
   };
@@ -720,7 +994,17 @@ export function prWavePlan(plan: FanOutPlan, components: DriverComponent[], wave
   const seeds = [
     ...new Set([...plan.seeds, ...order.flatMap((name) => (byName.get(name)?.dependsOn ?? []).filter((dep) => !inWave.has(dep)))]),
   ].sort();
-  return { order, waves: order.length > 0 ? [order] : [], skipped: [], seeds, indeterminate: plan.indeterminate, digest: plan.digest };
+  // ws-107: a group sits in one wave, so what is left of it plans and applies as one there.
+  const groups = (plan.groups ?? []).map((g) => ({ ...g, components: g.components.filter((c) => inWave.has(c)) })).filter((g) => g.components.length > 1);
+  return {
+    order,
+    waves: order.length > 0 ? [order] : [],
+    skipped: [],
+    seeds,
+    indeterminate: plan.indeterminate,
+    digest: plan.digest,
+    ...(groups.length > 0 ? { groups } : {}),
+  };
 }
 
 /**
@@ -731,20 +1015,47 @@ export function prWavePlan(plan: FanOutPlan, components: DriverComponent[], wave
  * returns no change set) is covered only by the digest it was approved
  * with, since with no entries there is nothing to compare a moved plan by.
  */
-export function waveNotCovered(approved: ChangeSetDocument, fresh: ChangeSetDocument, approvedMembers: readonly PrMember[] = []): string[] {
+export function waveNotCovered(
+  approved: ChangeSetDocument,
+  fresh: ChangeSetDocument,
+  approvedMembers: readonly PrMember[] = [],
+  shapes: { approved?: Record<string, PlanShape>; fresh?: Record<string, PlanShape> } = {},
+): string[] {
   // #3999: a member whose approved plan waited only on an artifact a build in
   // the change publishes is covered by that build's provenance, as it is
   // without --wave-gate.
   const byBuild = new Set(approvedMembers.filter((m) => m.buildInputs?.length && !m.unknownInputs?.length).map((m) => m.member));
+  const prMember = new Map(approvedMembers.map((m) => [m.member, m]));
+  // #4422: the same decision a round makes (`coveredRound`), so a resume, a
+  // wave and a round agree for equivalent inputs. A member the document names
+  // and the caller does not stands for a component of its own name.
+  const approvedSide = {
+    doc: approved,
+    members: approved.members.map((m) => ({
+      member: m.member,
+      component: prMember.get(m.member)?.component ?? m.member,
+      ...(prMember.get(m.member)?.unknownInputs?.length ? { unknownInputs: prMember.get(m.member)!.unknownInputs } : {}),
+    })),
+    ...(shapes.approved && shapes.fresh ? { shapes: shapes.approved } : {}),
+  };
   return fresh.members
     .map((m) => {
       if (byBuild.has(m.member)) return undefined;
       const was = approved.members.find((a) => a.member === m.member);
-      const opaque = m.planner === "chant" && m.lexicon === "chant" && m.status === "planned";
-      if (opaque && was && was.planDigest !== m.planDigest) {
-        return `${m.member} now plans to ${m.planDigest}, not the approved ${was.planDigest ?? "(none)"}, and its planner describes no changes to compare`;
-      }
-      return planCoveredBy(approved, fresh, m.member);
+      if (!was) return planCoveredBy(approved, fresh, m.member);
+      if (was.planDigest !== null && m.planDigest === was.planDigest) return undefined;
+      const hasShape = shapes.approved !== undefined && shapes.fresh?.[m.member] !== undefined;
+      const cover = coveredRound({
+        approved: approvedSide,
+        approvedDigest: approved.digest,
+        fresh: {
+          doc: fresh,
+          members: [{ member: m.member, component: prMember.get(m.member)?.component ?? m.member }],
+          ...(hasShape ? { shapes: shapes.fresh! } : {}),
+        },
+        attributes: (member) => memberAttributes(approved, fresh, member, hasShape),
+      });
+      return cover.covered ? undefined : cover.reason;
     })
     .filter((r): r is string => r !== undefined);
 }
@@ -778,9 +1089,36 @@ export interface PrReportInput {
   migrations?: PrMigrationFile[];
 }
 
+/**
+ * The report's `groups` (#4446): each group the set planned, with the wave
+ * of `waves` its members sit in and the reads of group-mates its members'
+ * change-set parts name, which the group's apply computes.
+ */
+function reportGroups(set: PrPlanSet, waves: readonly string[][]): PrGroup[] {
+  const componentOf = new Map(set.members.map((m) => [m.member, m.component]));
+  return (set.groups ?? []).map((g) => {
+    const wave = waves.findIndex((w) => g.components.some((c) => w.includes(c))) + 1;
+    const reads = set.doc.members
+      .filter((m) => g.components.includes(componentOf.get(m.member) ?? m.member))
+      .flatMap((m) => (m.group?.reads ?? []).map((ref) => ({ component: componentOf.get(m.member) ?? m.member, ref })))
+      .sort((a, b) => a.component.localeCompare(b.component) || a.ref.localeCompare(b.ref));
+    return {
+      capability: g.capability,
+      components: [...g.components],
+      wave: wave > 0 ? wave : 1,
+      digest: g.digest,
+      ...(g.error !== undefined ? { error: g.error } : {}),
+      ...(reads.length > 0 ? { reads } : {}),
+    };
+  });
+}
+
 /** The report a stage writes. */
 export function prReport(input: PrReportInput): PrReport {
   const changed = new Set(input.signal.changed);
+  const groups = reportGroups(input.set, input.plan.waves);
+  const groupOf = new Map(groups.flatMap((g, i) => g.components.map((c) => [c, i] as const)));
+  const members = (input.members ?? input.set.members).map((m) => (groupOf.has(m.component) ? { ...m, group: groupOf.get(m.component)! } : m));
   return {
     $schema: PR_REPORT_SCHEMA_ID,
     contract: PR_REPORT_CONTRACT,
@@ -811,7 +1149,9 @@ export function prReport(input: PrReportInput): PrReport {
       indeterminate: input.plan.indeterminate,
       waves: input.plan.waves,
     },
-    members: input.members ?? input.set.members,
+    ...(groups.length > 0 ? { groups } : {}),
+    ...(input.set.fallbacks?.length ? { fallbacks: input.set.fallbacks.map((f) => ({ ...f })) } : {}),
+    members,
     changeSet: input.set.doc,
   };
 }