@intentius/chant 0.124.51 → 0.124.54

package/dist/components/pr-run.js

@@ -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,14 +67,24 @@
  * 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 } from "../change-set.js";
 import { evaluateGate } from "../op/gate.js";
 import { memberCounts, PR_APPLY_GATE, prRoundGate, PR_REPORT_CONTRACT, PR_REPORT_SCHEMA_ID, } from "../pr-loop.js";
-import { deployContext, movedWiringReferences, unresolvedWiringReferences, } from "./driver.js";
+import { deployContext, movedWiringReferences, unresolvedWiringReferences, wiringReads, } from "./driver.js";
 import { deployUnits } from "./deploy-units.js";
 import { runFanOut } from "./fan-out-run.js";
 import { remainingFanOut } from "./fan-out.js";
+import { coveredRound } from "./covered-round.js";
+import { groupsByComponent, narrowGroups, planComponentGroup, regroupRemaining } from "./groups.js";
 import { capabilitySteps, planWaveComponent, readDeployedOutputs } from "./wave-plan.js";
 /** The phase a pull request's planning is, in its run's events. */
 export const PR_PLAN_PHASE = "plan";
@@ -105,17 +116,24 @@ export async function planPrSet(options) {
     const parts = [];
     const componentOf = new Map();
     const unknownOf = new Map();
+    const readsBy = new Map();
     const plans = {};
+    const shapes = {};
     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 = [];
     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 = [];
         for (const dep of deps) {
             read.add(dep);
@@ -130,25 +148,62 @@ export async function planPrSet(options) {
             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);
+        const settle = (name, start, p) => {
             emit?.({
                 type: "step-settle",
-                ...at,
+                component: name,
+                phase: PR_PLAN_PHASE,
+                step: "plan",
                 status: "error" in p ? "failed" : "ok",
                 durationMs: Date.now() - start,
                 ...("error" in p ? { error: p.error } : {}),
             });
-            return p;
-        }));
+        };
+        const groupsHere = [...new Set(wave.map((name) => groupOf.get(name)).filter((g) => 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) => "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);
@@ -160,6 +215,7 @@ export async function planPrSet(options) {
             }
             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);
@@ -171,6 +227,7 @@ export async function planPrSet(options) {
     const members = 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,
@@ -180,17 +237,23 @@ export async function planPrSet(options) {
             ...(m.error ? { error: m.error } : {}),
             ...(unknown?.unknown.length ? { unknownInputs: unknown.unknown } : {}),
             ...(unknown?.build.length ? { buildInputs: unknown.build } : {}),
+            ...(reads ? { reads } : {}),
         };
     });
     const sorted = (r) => 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 } : {}),
     };
@@ -201,33 +264,64 @@ export async function planPrSet(options) {
  * 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, outputs, inChange) {
+function unknownInputsOf(component, outputs, inChange, group) {
     const unknown = new Set();
     const build = new Set();
     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, outputs) {
+    const by = new Map();
+    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(), unknown: new Set() };
+            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, read, now, inChange = new Set()) {
+export function heldReason(component, read, now, inChange = new Set(), group = new Set()) {
     const refs = new Set();
     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)))
+            if (!(r.publish && inChange.has(r.source)) && !group.has(r.source))
                 refs.add(r.ref);
     }
     if (refs.size === 0)
@@ -289,6 +383,97 @@ export function approversWhoAuthored(approvedBy, authors) {
     const wrote = new Set(authors.map(norm));
     return approvedBy.filter((by) => wrote.has(norm(by)));
 }
+/**
+ * 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, fresh, plan, now, inChange, byName) {
+    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 = { ...now };
+    for (const name of plan.order)
+        if (fresh.outputs[name])
+            reads[name] = fresh.outputs[name];
+    const changedKnown = {};
+    for (const name of plan.order) {
+        const component = byName.get(name);
+        if (!component)
+            continue;
+        const refs = new Set();
+        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) => inRound.some((c) => ref === c || ref.startsWith(`${c}.`));
+    const waits = (m) => (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, fresh, order) {
+    const same = (a, b) => 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, fresh, member, hasShape) {
+    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, b) {
     const status = a.status === "fail" || b.status === "fail" ? "fail" : a.status === "gated" || b.status === "gated" ? "gated" : "ok";
@@ -303,6 +488,8 @@ function joinRuns(a, b) {
         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 ?? {}) } } : {}),
     };
 }
 /**
@@ -325,18 +512,24 @@ export async function applyPrSet(options) {
         ...Object.fromEntries(Object.entries(options.set.outputs).filter(([name]) => !toApply.has(name))),
         ...(options.resumed?.outputs ?? {}),
     };
-    const runRound = (plan, plans, read, outputs) => runFanOut(plan, options.components, options.registry, {
-        env: options.env,
-        ...(options.vars ? { vars: options.vars } : {}),
-        plans,
-        ...(options.targets ? { targets: options.targets } : {}),
-        componentOutputs: outputs,
-        hold: (name, now) => heldReason(byName.get(name), read, now, inChange),
-        ...(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 });
+    const runRound = (plan, set, read, outputs) => {
+        // 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: 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, 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, options.set.outputs, { ...standing });
     const rounds = [];
     /** Per component, the round that applied it or holds it, and that round's set, after the first. */
     const roundOf = new Map();
@@ -345,7 +538,8 @@ export async function applyPrSet(options) {
         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,
@@ -357,41 +551,63 @@ export async function applyPrSet(options) {
         });
         for (const name of plan.order)
             roundOf.set(name, { round, set });
-        const record = (status, approval, message) => {
-            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, approval, message, covered) => {
+            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 = 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) => {
         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) => {
         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 = later && fresh ? { ...m, planDigest: fresh.planDigest, counts: fresh.counts, round: later.round } : m;
+        const planned = 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 = 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 };
@@ -506,25 +722,46 @@ export function planCoveredBy(approved, fresh, member) {
  * 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) {
     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 !== 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 {
@@ -535,7 +772,9 @@ export async function resumePrSet(options) {
             doc: options.record.changeSet,
             members: options.record.members.map((m) => ({ ...m, status: "planned" })),
             plans: fresh.plans,
-            outputs: options.record.planOutputs,
+            outputs: { ...options.record.planOutputs, ...fromGroup },
+            ...(fresh.groups ? { groups: fresh.groups } : {}),
+            ...(fresh.fallbacks ? { fallbacks: fresh.fallbacks } : {}),
             failed: false,
         },
     };
@@ -554,7 +793,17 @@ export function prWavePlan(plan, components, wave, completed = []) {
     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 } : {}),
+    };
 }
 /**
  * Why the approved change set does not cover a wave's new plan, one line per
@@ -564,27 +813,77 @@ export function prWavePlan(plan, components, wave, completed = []) {
  * 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, fresh, approvedMembers = []) {
+export function waveNotCovered(approved, fresh, approvedMembers = [], shapes = {}) {
     // #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 !== undefined);
 }
+/**
+ * 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, waves) {
+    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) {
     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])));
+    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,
@@ -615,7 +914,9 @@ export function prReport(input) {
             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,
     };
 }