@intentius/chant 0.124.50 → 0.124.52

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

@@ -30,7 +30,7 @@ import {
 } from "./pr-run";
 import { changeSetDigest, changeSetDocumentDigest, composeChangeSet, 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 +78,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 +124,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] ?? {}) } };
     },
@@ -404,6 +407,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 +445,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 +474,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 +1021,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"] });

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.
@@ -78,6 +79,7 @@ import {
   PR_REPORT_SCHEMA_ID,
   type PrApproval,
   type PrMember,
+  type PrMemberRead,
   type PrRefusal,
   type PrRound,
   type PrReport,
@@ -88,12 +90,14 @@ 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 { coveredRound, type PlanShape, type RoundCoverage } from "./covered-round";
 import type { PrApplyRecord } from "./fan-out-record";
 import type { CapabilityRegistry, PlannedOutputs } from "./capability";
 import type { RunProgressEvent } from "./run-progress";
@@ -145,6 +149,8 @@ export interface PrPlanSet {
    * report's `plannedOutputs`.
    */
   plannedOutputs?: Record<string, string[]>;
+  /** The shapes lexicons supplied with their plans (#4419), by member. */
+  shapes?: Record<string, PlanShape>;
   /** Whether any component failed to plan. */
   failed: boolean;
 }
@@ -178,7 +184,9 @@ 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 });
@@ -223,6 +231,8 @@ export async function planPrSet(options: PrPlanSetOptions): Promise<PrPlanSet> {
       const component = byName.get(p.component)!;
       const unknown = unknownInputsOf(component, outputs, inChange);
       if (unknown.unknown.length > 0 || unknown.build.length > 0) unknownOf.set(p.component, unknown);
+      const reads = readsOf(component, outputs);
+      if (reads.length > 0) readsBy.set(p.component, reads);
       if ("error" in p) {
         failed = true;
         plannedBy.set(p.component, undefined);
@@ -234,6 +244,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 +257,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,6 +267,7 @@ 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)));
@@ -266,6 +279,7 @@ export async function planPrSet(options: PrPlanSetOptions): Promise<PrPlanSet> {
     plans,
     outputs,
     failed,
+    ...(Object.keys(shapes).length > 0 ? { shapes } : {}),
     ...(Object.keys(deployedOutputs).length > 0 ? { deployedOutputs } : {}),
     ...(Object.keys(plannedOutputs).length > 0 ? { plannedOutputs } : {}),
   };
@@ -295,6 +309,31 @@ function unknownInputsOf(
   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
@@ -409,13 +448,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 +479,66 @@ 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" };
+  // 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();
+  }
+  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, ...(fresh.shapes ? { shapes: fresh.shapes } : {}) },
+    changedKnown,
+    attributes: (member) => memberAttributes(options.set.doc, fresh.doc, member, fresh.shapes?.[member] !== 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";
@@ -500,22 +609,37 @@ 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);
+    record(next.status === "fail" ? "failed" : "applied", decision.approval, undefined, decision.covered);
     run = joinRuns(run, next);
   }
 
@@ -688,9 +812,8 @@ export async function resumePrSet(options: PrResumeOptions): Promise<PrResume> {
     seededOutputs: { ...(options.seededOutputs ?? {}), ...options.record.planOutputs },
     ...(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,
@@ -731,20 +854,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);
 }

package/src/components/wave-plan.ts

@@ -27,6 +27,7 @@
  * `@<component>.publish.*`) resolves.
  */
 
+import type { PlanShape } from "./covered-round";
 import { assertTargetsAccepted, resolveStepInput, unresolvedWiringSources, type DriverComponent, type DriverPhase, type DriverStep } from "./driver";
 import { componentPlanDigest } from "./gate-plan";
 import { componentDeployInputs, type ComponentDeployInputs } from "./deploy-inputs";
@@ -44,7 +45,7 @@ import type { ChangeSetPart } from "../change-set";
  * merges a run's outputs; absent when no step's plan says.
  */
 export type WaveComponentPlan =
-  | { component: string; members: WaveMember[]; plans: Record<string, unknown>; parts: ChangeSetPart[]; outputs?: PlannedOutputs }
+  | { component: string; members: WaveMember[]; plans: Record<string, unknown>; parts: ChangeSetPart[]; outputs?: PlannedOutputs; shapes?: Record<string, PlanShape> }
   | { component: string; error: string };
 
 /** A part with no entries, for a member whose planner describes no changes. `unbound` steps become its holes (#4155). */
@@ -101,6 +102,7 @@ export async function planWaveComponent(
     const plans: Record<string, unknown> = {};
     const parts: ChangeSetPart[] = [];
     let outputs: PlannedOutputs | undefined;
+    const shapes: Record<string, PlanShape> = {};
     assertTargetsAccepted(component, registry, ctx);
     for (const step of capabilitySteps(component.deploy)) {
       const capability = registry.resolve(step.kind);
@@ -112,6 +114,7 @@ export async function planWaveComponent(
       members.push(member);
       parts.push(planned.changeSet ?? emptyPart(member));
       if (planned.artifact !== undefined) plans[planned.member] = planned.artifact;
+      if (planned.shape) shapes[planned.member] = { ...planned.shape, member: planned.member };
       if (planned.outputs) outputs = mergePlannedOutputs(outputs, planned.outputs);
     }
     // #4155: the steps without a plan, which no member above covers.
@@ -141,7 +144,7 @@ export async function planWaveComponent(
         parts.push(emptyPart(member, read.unbound));
       }
     }
-    return { component: component.name, members, plans, parts, ...(outputs ? { outputs } : {}) };
+    return { component: component.name, members, plans, parts, ...(outputs ? { outputs } : {}), ...(Object.keys(shapes).length > 0 ? { shapes } : {}) };
   } catch (err) {
     return { component: component.name, error: err instanceof Error ? err.message : String(err) };
   }

package/src/pr-loop.test.ts

@@ -204,7 +204,8 @@ describe("the note", () => {
   test("a plan names the outputs read from upstream plans and the ones known only after apply (#3999)", () => {
     const note = renderPrNote(unknownReport);
     expect(note).toContain("Planned against the outputs this change's plans say its upstreams will have: `a` (`arn`).");
-    expect(note).toContain("Known only after apply: `app` reads `a.id`. This approval does not cover what those members do with them.");
+    expect(note).toContain("Known only after apply: `app` reads `a.id`. The apply plans those members again once their upstream applied.");
+    expect(note).toContain("anything else asks for an approval of its own");
     expect(renderPrNote(planReport)).not.toContain("Known only after apply");
     expect(note).toContain("From this pull request's build: `app` reads `img.publish.digest`. The image digest comes from this pull request's build");
     expect(renderPrNote(planReport)).not.toContain("From this pull request's build");
@@ -212,6 +213,18 @@ describe("the note", () => {
     expect(schema.required).not.toContain("plannedOutputs");
   });
 
+  test("a covered round names the first digest and the inputs filled in; an uncovered one gives the reason (#4419)", () => {
+    const covered = renderPrNote({
+      ...unknownReport,
+      status: "applied",
+      rounds: [{ ...waitingReport.rounds![0]!, status: "applied", approval: { status: "approved", approvedBy: ["github:rev"] }, covered: { digest: unknownReport.digest, filledInputs: ["a.id"] } }],
+    } as never);
+    expect(covered).toContain(`covered by the approval of \`${unknownReport.digest}\`, with \`a.id\` filled in, so it applied without a new approval`);
+    const not = renderPrNote({ ...unknownReport, rounds: [{ ...waitingReport.rounds![0]!, notCovered: "app now plans to create Bucket, which the first plan did not" }] } as never);
+    expect(not).toContain(`not covered by the approval of \`${unknownReport.digest}\`: app now plans to create Bucket, which the first plan did not.`);
+    expect(not).toContain("Not approved yet");
+  });
+
   test("a waiting apply names the round's digest and the command that approves it (#3999)", () => {
     const note = renderPrNote(waitingReport, { approver: "github:<your-login>" });
     expect(note).toContain("Applied 1 of 2 members; 1 wait on an approval of the plan made after their upstream applied.");