@intentius/chant 0.124.51 → 0.124.54

package/src/components/cli-support.ts

@@ -39,6 +39,7 @@ import {
   type DriverGate,
   type DriverPhase,
   type DriverRunResult,
+  type InterpretGroups,
 } from "./driver";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import type { GateDigestMismatch, GateLedgerPort } from "../op/gate";
@@ -51,7 +52,10 @@ import { existsSync, statSync } from "node:fs";
 import { getHeadCommit } from "../lifecycle/git";
 import { buildCapabilityRegistry } from "./capability-plugin-loader";
 import type { CapabilityRegistry } from "./capability";
+import type { FanOutPlan } from "./fan-out";
+import { componentSetFanOut, formRunGroups, planAndRunComponentGroup } from "./groups";
 import { applyConfigDefaults } from "./config-defaults";
+import { withDeclaredReads } from "./declared-reads";
 import { loadChantConfig, type ChantConfig } from "../config";
 
 /** One component in `chant list --components` output. */
@@ -510,6 +514,8 @@ export interface RunComponentsResult {
   };
   /** This run's resolved build-time parameters (chant #1108) — the component-driver counterpart of `../cli/commands/build.ts`'s `BuildResult.buildParams`. Present only once the run actually reached dispatch (mirrors `BuildResult.buildParams`, which is likewise absent on an early-error return). */
   buildParams?: BuildParamProvenance[];
+  /** The grouped fan-out the run applied (ws-107, #4465), when a group formed or a component fell back from one. */
+  grouped?: FanOutPlan;
 }
 
 /**
@@ -545,6 +551,13 @@ export interface ResolvedComponentTargets {
   targets: DriverComponent[];
   /** For a list selector (#3950): the dependencies the closure added that the list did not name, in discovery order. */
   added?: string[];
+  /**
+   * For a list selector: the names the list gave, and every enabled component
+   * the closure was taken over (#4516). `runComponents` takes the closure again
+   * once the declared reads are written in, so a listed importer pulls in the
+   * component whose export it reads.
+   */
+  list?: { named: string[]; enabled: DriverComponent[] };
   /** Component name to the environments it declares (#3153), for the components that declare any (#4330). */
   sites?: Record<string, ComponentEnvironmentDeclaration[]>;
   error?: string;
@@ -650,6 +663,14 @@ function resolveComponentList(
   }
 
   const enabled = withoutDisabled(discovered, all);
+  return { success: true, ...dependencyClosure(names, enabled), list: { named: names, enabled } };
+}
+
+/**
+ * `names` and every component of `enabled` they depend on, transitively, in
+ * `enabled`'s order, and which of those the names did not give (#3950).
+ */
+export function dependencyClosure(names: readonly string[], enabled: readonly DriverComponent[]): { targets: DriverComponent[]; added: string[] } {
   const byName = new Map(enabled.map((c) => [c.name, c]));
   const included = new Set<string>();
   const visit = (name: string): void => {
@@ -662,7 +683,7 @@ function resolveComponentList(
 
   const targets = enabled.filter((c) => included.has(c.name));
   const named = new Set(names);
-  return { success: true, targets, added: targets.map((c) => c.name).filter((n) => !named.has(n)) };
+  return { targets, added: targets.map((c) => c.name).filter((n) => !named.has(n)) };
 }
 
 export async function runComponents(
@@ -674,13 +695,6 @@ export async function runComponents(
   if (!resolved.success) {
     return { success: false, selected: [], error: resolved.error };
   }
-  const targets = resolved.targets;
-  const narrowed = options.targets ?? {};
-  const outside = Object.keys(narrowed).filter((name) => !targets.some((c) => c.name === name));
-  if (outside.length > 0) {
-    return { success: false, selected: [], error: `--target names ${outside.join(", ")}, which this run does not run` };
-  }
-  const targeted = Object.keys(narrowed).length > 0 ? { targets: narrowed } : {};
 
   // (#629) Resolve `chant.config.ts`'s `sbom`/`signing`/`vulnPolicy` sections
   // and fill their defaults into every recognized step (`generate-sbom`,
@@ -700,8 +714,27 @@ export async function runComponents(
       lexicons: lexiconNames(config.lexicons),
     }));
   const env = options.env ?? "local";
-  const selected = targets.map((c) => c.name);
-  const resolvedTargets = targets.map((component) => applyConfigDefaults(component, config));
+  // #4516: the reads a capability finds in its steps' files (a template's
+  // Fn::ImportValue) order a set run as `deriveFanOut` orders a fan-out, so an
+  // importer runs after the component whose export it reads. A list takes its
+  // closure again with them written in, so a listed importer pulls in its
+  // exporter. A single name runs on its own, against seeded outputs.
+  let resolvedTargets: DriverComponent[];
+  let added = resolved.added ?? [];
+  if (resolved.list) {
+    const enabled = await withDeclaredReads(resolved.list.enabled.map((component) => applyConfigDefaults(component, config)), registry, path);
+    ({ targets: resolvedTargets, added } = dependencyClosure(resolved.list.named, enabled));
+  } else {
+    const defaulted = resolved.targets.map((component) => applyConfigDefaults(component, config));
+    resolvedTargets = selector === "all" ? await withDeclaredReads(defaulted, registry, path) : defaulted;
+  }
+  const selected = resolvedTargets.map((c) => c.name);
+  const narrowed = options.targets ?? {};
+  const outside = Object.keys(narrowed).filter((name) => !selected.includes(name));
+  if (outside.length > 0) {
+    return { success: false, selected: [], error: `--target names ${outside.join(", ")}, which this run does not run` };
+  }
+  const targeted = Object.keys(narrowed).length > 0 ? { targets: narrowed } : {};
   // Cross-component/cross-stack outputs to resolve references against. Seeded
   // from a caller (a downstream CI job passing an upstream job's dumped
   // outputs via `--seed-outputs`); grows as this run's components complete.
@@ -719,16 +752,38 @@ export async function runComponents(
 
   try {
     if (selector === "all" || isComponentList(selector)) {
+      // ws-107 (#4465): the components a capability takes as one plan in their
+      // wave and apply as one group, by the rule the pull-request run uses.
+      // A cycle or unknown dependency throws here the error the driver would:
+      // `componentSetFanOut` drops a dependency outside the set, so the full
+      // graph is resolved first.
+      resolveComponentGraph(resolvedTargets);
+      const grouped = await formRunGroups({ components: resolvedTargets, plan: componentSetFanOut(resolvedTargets), registry, env });
       if (isComponentList(selector) && options.onPlan) {
         // Resolved here, before dispatch, so the order is printed before any
-        // component runs. A cycle or unknown dependency throws the same error
-        // `runInterpretDriver` would, caught below.
-        const graph = resolveComponentGraph(resolvedTargets);
-        options.onPlan({ order: graph.order, waves: graph.waves, added: resolved.added ?? [] });
+        // component runs.
+        options.onPlan({ order: grouped.order, waves: grouped.waves.filter((w) => w.length > 0), added });
       }
+      const byName = new Map(resolvedTargets.map((c) => [c.name, c]));
+      const groups: InterpretGroups | undefined = grouped.groups?.length
+        ? {
+            waves: grouped.waves,
+            groups: grouped.groups,
+            run: (group, componentOutputs) =>
+              planAndRunComponentGroup({
+                group,
+                components: byName,
+                registry,
+                env,
+                ctxOf: (name) => deployContext({ env, releaseIdentity, ...targeted }, name),
+                componentOutputs,
+              }),
+          }
+        : undefined;
       const run = await runInterpretDriver(resolvedTargets, registry, {
         env,
         releaseIdentity,
+        ...(groups ? { groups } : {}),
         ...targeted,
         componentOutputs: seedOutputs,
         ...(emit ? { onRunEvent: emit } : {}),
@@ -740,6 +795,7 @@ export async function runComponents(
         selected,
         components: resolvedTargets,
         buildParams: options.buildParams,
+        ...(grouped.groups?.length || grouped.fallbacks?.length ? { grouped } : {}),
         ...(run.status === "gated" && run.gate
           ? {
               gated: {

package/src/components/covered-round.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, test } from "vitest";
+import {
+  coveredRound,
+  normalizePlanShape,
+  PlanShapeMovedError,
+  planShapeCovers,
+  planShapeDifferences,
+  planShapeDigest,
+  type PlanShape,
+  type PlanShapeEntry,
+} from "./covered-round";
+import type { ChangeSetDocument } from "../change-set";
+
+const shape = (over: Partial<PlanShape> = {}): PlanShape => ({
+  member: "svc",
+  entries: [
+    { logicalId: "Fn", action: "create" },
+    { logicalId: "Role", action: "update", replacement: "conditional" },
+  ],
+  unknownInputs: ["vpc.id"],
+  ...over,
+});
+
+describe("planShapeCovers", () => {
+  test("the same ids and actions with the unknown input filled in is covered", () => {
+    expect(planShapeCovers(shape(), shape({ unknownInputs: [], replacement: undefined } as never))).toBeUndefined();
+  });
+
+  test("a resource the preview did not show is not covered", () => {
+    const fresh = shape({ unknownInputs: [], entries: [...shape().entries, { logicalId: "Bucket", action: "create" }] });
+    expect(planShapeCovers(shape(), fresh)).toBe("svc now plans to create Bucket, which the first plan did not");
+  });
+
+  test("a different action is not covered", () => {
+    const fresh = shape({ unknownInputs: [], entries: [{ logicalId: "Fn", action: "delete" }] });
+    expect(planShapeCovers(shape(), fresh)).toBe("svc now plans to delete Fn, where the first plan showed create");
+  });
+
+  test("a replacement the preview did not show is not covered; a conditional one resolving either way is", () => {
+    const previewed = shape({ entries: [{ logicalId: "Role", action: "update", replacement: "false" }] });
+    const replaced = shape({ unknownInputs: [], entries: [{ logicalId: "Role", action: "update", replacement: "true" }] });
+    expect(planShapeCovers(previewed, replaced)).toBe("svc now replaces Role, which the first plan did not show");
+    for (const r of ["true", "false"] as const) {
+      const fresh = shape({ unknownInputs: [], entries: [{ logicalId: "Role", action: "update", replacement: r }] });
+      expect(planShapeCovers(shape(), fresh)).toBeUndefined();
+    }
+  });
+
+  test("a changed known input is not covered, an unknown one filled is", () => {
+    const was = shape({ knownInputs: { "net.cidr": "10.0.0.0/16" } });
+    expect(planShapeCovers(was, shape({ unknownInputs: [], knownInputs: { "net.cidr": "10.1.0.0/16" } }))).toBe(
+      "svc now reads net.cidr as a different value than the first plan",
+    );
+    expect(planShapeCovers(was, shape({ unknownInputs: [], knownInputs: { "net.cidr": "10.0.0.0/16", "vpc.id": "vpc-1" } }))).toBeUndefined();
+  });
+
+  test("an input still unknown is not covered", () => {
+    expect(planShapeCovers(shape(), shape())).toBe("svc still reads vpc.id, which is not known yet");
+  });
+});
+
+describe("coveredRound", () => {
+  const doc = { members: [], entries: [] } as unknown as ChangeSetDocument;
+  const side = (component: string, unknownInputs?: string[], shapes?: Record<string, PlanShape>) => ({
+    doc,
+    members: [{ member: "svc", component, ...(unknownInputs ? { unknownInputs } : {}) }],
+    ...(shapes ? { shapes } : {}),
+  });
+
+  test("covered: binds the first approval's digest and names the inputs filled in", () => {
+    const r = coveredRound({
+      approved: side("svc", ["vpc.id"], { svc: shape() }),
+      approvedDigest: "sha256:aaa",
+      fresh: side("svc", undefined, { svc: shape({ unknownInputs: [] }) }),
+    });
+    expect(r).toEqual({ covered: true, digest: "sha256:aaa", filledInputs: ["vpc.id"] });
+  });
+
+  test("a component the first plan did not preview is not covered", () => {
+    const r = coveredRound({ approved: side("svc", ["vpc.id"]), approvedDigest: "sha256:aaa", fresh: side("other") });
+    expect(r).toEqual({ covered: false, reason: "other was not in the first plan" });
+  });
+
+  test("a member that was a hole with no preview shape is not covered, even with its unknown input filled in (#4422)", () => {
+    // The approved side has no shape for svc and no entries: the reviewer never saw what it would do.
+    const fresh = { svc: shape({ unknownInputs: [], entries: [{ logicalId: "Fn", action: "create" }] }) };
+    const r = coveredRound({ approved: side("svc", ["vpc.id"]), approvedDigest: "sha256:aaa", fresh: side("svc", undefined, fresh) });
+    expect(r).toEqual({ covered: false, reason: "svc now plans to create Fn, which the first plan did not" });
+  });
+
+  test("a known input that moved is not covered", () => {
+    const r = coveredRound({
+      approved: side("svc", ["vpc.id"]),
+      approvedDigest: "sha256:aaa",
+      fresh: side("svc"),
+      changedKnown: { svc: ["net.cidr", "vpc.id"] },
+    });
+    expect(r).toEqual({ covered: false, reason: "svc reads net.cidr, which the first plan read as another value" });
+  });
+});
+
+describe("property-level shapes (ported from plan-shape, #4419)", () => {
+  const entry = (over: Partial<PlanShapeEntry> = {}): PlanShapeEntry => ({
+    logicalId: "Eni",
+    action: "update",
+    replacement: "false",
+    type: "T",
+    properties: ["A", "B"],
+    unknown: ["B"],
+    ...over,
+  });
+  const sh = (...entries: PlanShapeEntry[]): PlanShape => ({ member: "m", unknownInputs: ["p"], entries });
+  const fresh = (...entries: PlanShapeEntry[]): PlanShape => ({ member: "m", unknownInputs: [], entries });
+
+  test("digests the same for the same shape in another order", () => {
+    const a = sh(entry({ logicalId: "a" }), entry({ logicalId: "b", properties: ["Z", "Y"] }));
+    const b = sh(entry({ logicalId: "b", properties: ["Y", "Z"] }), entry({ logicalId: "a" }));
+    expect(planShapeDigest(a)).toBe(planShapeDigest(b));
+    expect(normalizePlanShape(b).entries.map((e) => e.logicalId)).toEqual(["a", "b"]);
+    expect(planShapeDigest(a)).not.toBe(planShapeDigest(sh(entry({ logicalId: "a" }))));
+  });
+
+  test("accepts an identical change and one narrowed where an unknown input drives it", () => {
+    expect(planShapeDifferences(sh(entry()), fresh(entry()))).toEqual([]);
+    expect(planShapeDifferences(sh(entry()), fresh(entry({ properties: ["A"] })))).toEqual([]);
+    expect(planShapeDifferences(sh(entry({ replacement: "true" })), fresh(entry({ replacement: "false" })))).toEqual([]);
+    expect(planShapeDifferences(sh(entry({ properties: ["B"] })), fresh())).toEqual([]);
+  });
+
+  test("refuses an added resource, an added property, another action, more replacement", () => {
+    expect(planShapeDifferences(sh(entry()), fresh(entry(), entry({ logicalId: "n" })))).toHaveLength(1);
+    expect(planShapeCovers(sh(entry()), fresh(entry({ properties: ["A", "B", "C"] })))).toContain("also changes C");
+    expect(planShapeCovers(sh(entry()), fresh(entry({ action: "delete" })))).toContain("where the first plan showed update");
+    expect(planShapeCovers(sh(entry()), fresh(entry({ replacement: "true" })))).toContain("now replaces Eni");
+    expect(planShapeCovers(sh(entry()), fresh(entry({ type: "U" })))).toContain("as U, where the first plan showed T");
+  });
+
+  test("refuses a change that vanishes or weakens with no unknown input behind it", () => {
+    expect(planShapeDifferences(sh(entry({ unknown: [] })), fresh())).toHaveLength(1);
+    expect(planShapeDifferences(sh(entry({ unknown: [], replacement: "true" })), fresh(entry({ unknown: [], replacement: "false" })))).toHaveLength(1);
+    expect(planShapeCovers(sh(entry()), fresh(entry({ properties: ["B"] })))).toContain("no longer changes A");
+  });
+
+  test("a previewed entry without property detail may drop out, as before", () => {
+    expect(planShapeDifferences({ member: "m", unknownInputs: [], entries: [{ logicalId: "x", action: "create" }] }, fresh())).toEqual([]);
+  });
+
+  test("an entry with property detail is compared even when its action is no-op", () => {
+    const imp = entry({ logicalId: "I", action: "no-op" });
+    expect(planShapeCovers(sh(), fresh(imp))).toContain("now plans to no-op I");
+    expect(planShapeCovers(sh(imp), fresh(imp))).toBeUndefined();
+  });
+
+  test("the refusal names the differences and marks the plan as moved", () => {
+    const err = new PlanShapeMovedError("m", ["m now plans to create Eni, which the first plan did not"]);
+    expect(err.planMoved).toBe(true);
+    expect(err.message).toContain("Eni, which the first plan did not");
+  });
+
+  test("a round is not covered when a property level difference shows in the shapes a lexicon supplied", () => {
+    const doc = { members: [], entries: [] } as unknown as ChangeSetDocument;
+    const side = (shape: PlanShape, unknownInputs?: string[]) => ({ doc, members: [{ member: "m", component: "c", ...(unknownInputs ? { unknownInputs } : {}) }], shapes: { m: shape } });
+    const r = coveredRound({ approved: side(sh(entry()), ["up.id"]), approvedDigest: "d", fresh: side(fresh(entry({ properties: ["A", "C"] }))) });
+    expect(r).toEqual({ covered: false, reason: "m now also changes C on Eni" });
+  });
+});

package/src/components/covered-round.ts

@@ -0,0 +1,293 @@
+/**
+ * Covered rounds (#4419): a round planned after an upstream applied is
+ * covered by the pull request's first approval when it does only what that
+ * approval previewed.
+ *
+ * A member that reads an output an upstream in the same change has not
+ * created yet is previewed with a hole: the input is marked unknown
+ * (`PrMember.unknownInputs`). Once the upstream applied, the apply plans the
+ * member again with the real value. That fresh plan is covered when
+ *
+ * - it touches only components the first plan previewed,
+ * - within each, only the logical ids and actions previewed (and no
+ *   replacement the preview did not show), and
+ * - the only inputs that differ are the ones the preview marked unknown.
+ *
+ * A lexicon that can say more than the change set's entries (CloudFormation
+ * previews the member with placeholder parameters and reads the real change
+ * set afterwards) supplies a {@link PlanShape} on its `CapabilityPlan`.
+ * Core decides coverage; the lexicon only reports what it planned.
+ *
+ * A shape may go below the entry, to the properties a change touches and the
+ * ones an unknown input drives. Where it does, a property may drop out when
+ * an unknown input drives it (the real value turned out equal to the current
+ * one), and never otherwise, and a property may never be added.
+ *
+ * Coverage binds to the digest of the first approval. {@link coveredRound}
+ * takes that digest and records it, so a round planned for a different
+ * composition never counts as covered by an approval of another one.
+ */
+
+import type { ChangeSetAction, ChangeSetDocument } from "../change-set";
+import { computePlanDigest } from "../lifecycle/plan-digest";
+
+/** CloudFormation's `Replacement`, in lower case. */
+export type ShapeReplacement = "true" | "false" | "conditional";
+
+/** One resource a plan touches. */
+export interface PlanShapeEntry {
+  /** The resource's id in the lexicon's own terms: a CloudFormation logical id, a Terraform address. */
+  logicalId: string;
+  action: ChangeSetAction;
+  /**
+   * Whether the change replaces the resource, for an `update` or `replace`.
+   * `conditional` is the preview not knowing, because a parameter it
+   * depends on was a placeholder. Absent means the lexicon does not say.
+   */
+  replacement?: ShapeReplacement;
+  /** The resource's type, when the lexicon says. Compared for equality when both sides carry it. */
+  type?: string;
+  /**
+   * The properties the change touches, when the lexicon lists them. Present
+   * on both sides, the fresh plan may touch fewer where an unknown input
+   * drives them, and never more.
+   */
+  properties?: string[];
+  /**
+   * The properties an unknown input drives. On an update a subset of
+   * `properties`; on a create, where a planner cannot list properties, they
+   * stand alone. Present (even empty) on an entry that carries detail.
+   */
+  unknown?: string[];
+}
+
+/** What one member's plan does, without the values: what a lexicon supplies and core compares. */
+export interface PlanShape {
+  /** The member the shape is of, as in the change set. */
+  member: string;
+  /** Every resource the plan touches. A `no-op` or `read` entry may be left out. */
+  entries: PlanShapeEntry[];
+  /**
+   * The inputs the plan was made without, as `<component>.<output>`: the
+   * ones the preview marked unknown. A fresh plan lists none of them; it
+   * is the inputs that were filled in that are recorded.
+   */
+  unknownInputs: string[];
+  /**
+   * The inputs the plan read with a value, by reference. When both shapes
+   * carry a reference, the values must be equal, or an input that was
+   * known has changed. Optional: a shape without it is checked on its
+   * entries alone, plus the change set's own attributes in core.
+   */
+  knownInputs?: Record<string, unknown>;
+}
+
+const SKIPPED: ReadonlySet<ChangeSetAction> = new Set(["no-op", "read"]);
+
+const REPLACEMENT_RANK: Record<ShapeReplacement, number> = { false: 0, conditional: 1, true: 2 };
+
+/** An entry with property detail is compared whatever its action: a lexicon that lists properties means it. */
+const skipped = (e: PlanShapeEntry): boolean => SKIPPED.has(e.action) && e.properties === undefined;
+
+/**
+ * Every way `fresh` goes beyond `previewed`, as reasons; none means covered.
+ * Both are shapes of the same member.
+ *
+ * The fresh plan may match the preview exactly, or be narrower where an
+ * unknown input drives it: a property whose real value equals the current one
+ * drops out, a replacement that depended on a stand-in may not happen. It
+ * may never add a resource, add a property, change an action or a type,
+ * replace more than previewed, read an input that is still unknown, or read a
+ * known input as another value.
+ */
+export function planShapeDifferences(previewed: PlanShape, fresh: PlanShape): string[] {
+  const member = fresh.member;
+  const out: string[] = [];
+  const was = new Map(previewed.entries.map((e) => [e.logicalId, e]));
+  const now = new Set<string>();
+  for (const e of fresh.entries) {
+    if (skipped(e)) continue;
+    now.add(e.logicalId);
+    const p = was.get(e.logicalId);
+    if (!p) {
+      out.push(`${member} now plans to ${e.action} ${e.logicalId}, which the first plan did not`);
+      continue;
+    }
+    if (p.action !== e.action) out.push(`${member} now plans to ${e.action} ${e.logicalId}, where the first plan showed ${p.action}`);
+    if (p.type !== undefined && e.type !== undefined && p.type !== e.type) out.push(`${member} now has ${e.logicalId} as ${e.type}, where the first plan showed ${p.type}`);
+    if (p.properties && e.properties) {
+      const extra = e.properties.filter((x) => !p.properties!.includes(x));
+      if (extra.length > 0) out.push(`${member} now also changes ${extra.join(", ")} on ${e.logicalId}`);
+      const driven = p.unknown ?? [];
+      const lost = p.properties.filter((x) => !driven.includes(x) && !e.properties!.includes(x));
+      if (lost.length > 0) out.push(`${member} no longer changes ${lost.join(", ")} on ${e.logicalId}, which no unknown input drives`);
+    }
+    if (e.replacement === "true" && p.replacement !== "true" && p.replacement !== "conditional") {
+      out.push(`${member} now replaces ${e.logicalId}, which the first plan did not show`);
+    } else if (e.replacement === "conditional" && p.replacement !== "conditional" && p.replacement !== "true") {
+      out.push(`${member} may now replace ${e.logicalId}, which the first plan did not show`);
+    } else if (e.replacement && p.replacement && p.unknown?.length === 0 && REPLACEMENT_RANK[e.replacement] < REPLACEMENT_RANK[p.replacement]) {
+      out.push(`${member} replacement of ${e.logicalId} was ${p.replacement}, now ${e.replacement}, and no unknown input drives it`);
+    }
+  }
+  // A previewed change that is gone: allowed only where unknown inputs drive all of it.
+  for (const p of previewed.entries) {
+    if (now.has(p.logicalId) || skipped(p) || !p.properties) continue;
+    const driven = p.unknown ?? [];
+    if (!(p.properties.length > 0 && p.properties.every((x) => driven.includes(x)))) {
+      out.push(`${member} no longer plans to ${p.action} ${p.logicalId}, which the first plan did and no unknown input drives`);
+    }
+  }
+  const unknown = new Set(previewed.unknownInputs);
+  const stillUnknown = fresh.unknownInputs[0];
+  if (stillUnknown) out.push(`${member} still reads ${stillUnknown}, which is not known yet`);
+  for (const [ref, value] of Object.entries(fresh.knownInputs ?? {})) {
+    if (unknown.has(ref)) continue;
+    if (!previewed.knownInputs) continue;
+    if (!(ref in previewed.knownInputs)) out.push(`${member} now reads ${ref}, which the first plan did not`);
+    else if (JSON.stringify(previewed.knownInputs[ref] ?? null) !== JSON.stringify(value ?? null)) {
+      out.push(`${member} now reads ${ref} as a different value than the first plan`);
+    }
+  }
+  return out;
+}
+
+/**
+ * Why `fresh` is not covered by `previewed`, or `undefined` when it is: the
+ * first of {@link planShapeDifferences}.
+ */
+export function planShapeCovers(previewed: PlanShape, fresh: PlanShape): string | undefined {
+  return planShapeDifferences(previewed, fresh)[0];
+}
+
+/** A shape in the order that makes equal shapes digest equal. */
+export function normalizePlanShape(shape: PlanShape): PlanShape {
+  const sorted = (xs: string[]): string[] => [...new Set(xs)].sort();
+  return {
+    member: shape.member,
+    entries: shape.entries
+      .map((e) => ({
+        logicalId: e.logicalId,
+        action: e.action,
+        ...(e.replacement ? { replacement: e.replacement } : {}),
+        ...(e.type !== undefined ? { type: e.type } : {}),
+        ...(e.properties ? { properties: sorted(e.properties) } : {}),
+        ...(e.unknown ? { unknown: sorted(e.unknown) } : {}),
+      }))
+      .sort((a, b) => a.logicalId.localeCompare(b.logicalId) || a.action.localeCompare(b.action)),
+    unknownInputs: sorted(shape.unknownInputs),
+    ...(shape.knownInputs ? { knownInputs: shape.knownInputs } : {}),
+  };
+}
+
+export function planShapeDigest(shape: PlanShape): string {
+  return computePlanDigest("plan-shape", normalizePlanShape(shape));
+}
+
+/**
+ * What a lexicon hands the run for a previewed member, through
+ * `DeployContext.plans[member]`. `kind` is the lexicon's own so its `run`
+ * can tell a shape from its other artifacts.
+ */
+export interface PlanShapeArtifact {
+  kind: string;
+  member: string;
+  shape: PlanShape;
+  digest: string;
+}
+
+/**
+ * Thrown by a member's `run` when the change it created is not covered by the
+ * shape previewed. The change set is deleted unexecuted. `planMoved` is
+ * core's mark for a moved plan, so the command that applied it exits 3.
+ */
+export class PlanShapeMovedError extends Error {
+  readonly planMoved = true;
+  constructor(
+    public readonly member: string,
+    public readonly differences: string[],
+  ) {
+    super(`"${member}": refusing to apply. The change differs from the preview that was approved: ${differences.join("; ")}. Plan it again.`);
+    this.name = "PlanShapeMovedError";
+  }
+}
+
+/** The shape a change-set document gives for `member`, when its lexicon supplies none. */
+export function shapeFromChangeSet(doc: ChangeSetDocument, member: string, inputs: { unknownInputs?: string[]; knownInputs?: Record<string, unknown> } = {}): PlanShape {
+  return {
+    member,
+    entries: doc.entries
+      .filter((e) => e.member === member)
+      .map((e) => ({ logicalId: e.deposed ? `${e.address}#${e.deposed}` : e.address, action: e.action })),
+    unknownInputs: [...(inputs.unknownInputs ?? [])].sort(),
+    ...(inputs.knownInputs ? { knownInputs: inputs.knownInputs } : {}),
+  };
+}
+
+/** What a round was covered by, as the report records it (`PrRound.covered`). */
+export interface RoundCover {
+  /** The digest of the first approval, which the coverage is bound to. */
+  digest: string;
+  /** The inputs the first plan marked unknown and this round planned with a value, `<component>.<output>`, sorted. */
+  filledInputs: string[];
+}
+
+export type RoundCoverage = ({ covered: true } & RoundCover) | { covered: false; reason: string };
+
+/** One side of the comparison: a plan set, as far as coverage needs it. */
+export interface CoverageSide {
+  doc: ChangeSetDocument;
+  /** Per member, its component and (first plan only) the inputs it was previewed without. */
+  members: { member: string; component: string; unknownInputs?: string[] }[];
+  /** Shapes a lexicon supplied, by member. Where absent, the change set gives the shape. */
+  shapes?: Record<string, PlanShape>;
+}
+
+export interface CoveredRoundInput {
+  /** The first plan, whose approval is being relied on. */
+  approved: CoverageSide;
+  /** The digest that approval binds: the report's `digest`. */
+  approvedDigest: string;
+  /** The round's fresh plan. */
+  fresh: CoverageSide;
+  /**
+   * Known inputs that changed between the first plan and the round, as
+   * `<component>.<output>`: an input the first plan read with a value that
+   * stands as another one now. Core reads them from the outputs.
+   */
+  changedKnown?: ReadonlyMap<string, string[]> | Record<string, string[]>;
+  /** The check on the change set's own attributes, per member (`planCoveredBy`). */
+  attributes?: (member: string) => string | undefined;
+}
+
+/**
+ * Whether the approval of `approvedDigest` covers `fresh`. Covered, the
+ * result names the digest and the inputs that were filled in; not covered,
+ * the reason, which the apply reports with the approval it asks for.
+ */
+export function coveredRound(input: CoveredRoundInput): RoundCoverage {
+  const { approved, fresh } = input;
+  const previewedComponents = new Set(approved.members.map((m) => m.component));
+  const approvedMember = new Map(approved.members.map((m) => [m.member, m]));
+  const filled = new Set<string>();
+  for (const m of fresh.members) {
+    if (!previewedComponents.has(m.component)) return { covered: false, reason: `${m.component} was not in the first plan` };
+    const was = approvedMember.get(m.member);
+    if (!was) return { covered: false, reason: `${m.member} was not in the first plan` };
+    if (was.component !== m.component) return { covered: false, reason: `${m.member} moved from ${was.component} to ${m.component}` };
+    const previewed = approved.shapes?.[m.member] ?? shapeFromChangeSet(approved.doc, m.member, { unknownInputs: was.unknownInputs });
+    const both = [...new Set([...(previewed.unknownInputs ?? []), ...(was.unknownInputs ?? [])])];
+    // A lexicon that only knows the upstream stack lists the bare component; the member names the output. Keep the named one.
+    const unknownInputs = both.filter((ref) => !both.some((other) => other.startsWith(`${ref}.`))).sort();
+    const now = fresh.shapes?.[m.member] ?? shapeFromChangeSet(fresh.doc, m.member);
+    const reason = planShapeCovers({ ...previewed, unknownInputs }, now);
+    if (reason) return { covered: false, reason };
+    const changed = (input.changedKnown instanceof Map ? input.changedKnown.get(m.component) : (input.changedKnown as Record<string, string[]> | undefined)?.[m.component]) ?? [];
+    const changedKnown = changed.filter((ref: string) => !unknownInputs.includes(ref));
+    if (changedKnown.length > 0) return { covered: false, reason: `${m.member} reads ${changedKnown.join(", ")}, which the first plan read as another value` };
+    const attrs = input.attributes?.(m.member);
+    if (attrs) return { covered: false, reason: attrs };
+    for (const ref of unknownInputs) filled.add(ref);
+  }
+  return { covered: true, digest: input.approvedDigest, filledInputs: [...filled].sort() };
+}