@intentius/chant-lexicon-aws 0.124.31 → 0.124.32

package/src/components/apply.ts

@@ -21,7 +21,7 @@
 
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
-import type { Capability, CapabilityPlan, DeployContext } from "@intentius/chant/components/capability";
+import type { Capability, CapabilityPlan, DeployContext, PlannedOutputs } from "@intentius/chant/components/capability";
 import type { ChangeSetEntry, ChangeSetHole, ChangeSetPart } from "@intentius/chant/change-set";
 import { computePlanDigest } from "@intentius/chant/lifecycle/plan-digest";
 import { defaultCloudExecutor, type CfnChange, type CfnChangeSet, type CloudExecutor } from "./cloud-executor";
@@ -67,13 +67,17 @@ export function cfnChangeReplaces(change: CfnChange): boolean {
  */
 export function cfnChangeEntry(member: string, change: CfnChange): ChangeSetEntry {
   const attributes = [...new Set(change.details ?? [])].sort().map((path) => ({ path }));
+  // A change inside a nested stack (#3997) sits under the nested stacks'
+  // logical ids, the way a terraform address sits under its module.
+  const module = change.nestedStack?.length ? change.nestedStack.join("/") : undefined;
   const base = {
     member,
     lexicon: "aws",
     planner: "chant" as const,
-    address: change.logicalResourceId,
+    address: module ? `${module}/${change.logicalResourceId}` : change.logicalResourceId,
     type: change.resourceType,
     name: change.logicalResourceId,
+    ...(module ? { module } : {}),
     attributes,
   };
   switch (change.action) {
@@ -92,6 +96,66 @@ export function cfnChangeEntry(member: string, change: CfnChange): ChangeSetEntr
   }
 }
 
+/**
+ * The changes `onReplace: "block"` refuses: those CloudFormation says replace
+ * their resource (`Replacement: True`). `run` and `plan` refuse on the same
+ * set, so a plan that passes is one `run` would not block (#3997).
+ */
+function blockedReplacements(changes: CfnChange[]): CfnChange[] {
+  return changes.filter((c) => c.replacement);
+}
+
+/**
+ * What a `cfn-deploy` plan hands `run` through `DeployContext.plans[stack]`
+ * (#3997): the stack and a digest over the changes the plan's change set
+ * proposed. `run` creates its change set, and executes it only when its
+ * changes have the same digest.
+ */
+export interface CfnPlanArtifact {
+  kind: "cfn-deploy-plan";
+  stack: string;
+  /** {@link cfnChangesDigest} of the planned change set's changes. */
+  changesDigest: string;
+}
+
+function isCfnPlanArtifact(value: unknown): value is CfnPlanArtifact {
+  const v = value as Partial<CfnPlanArtifact> | undefined;
+  return v?.kind === "cfn-deploy-plan" && typeof v.stack === "string" && typeof v.changesDigest === "string";
+}
+
+/**
+ * A digest over a change set's changes as entries, independent of the change
+ * set's name and of the order CloudFormation lists them in. A change set with
+ * nothing to apply digests as no entries.
+ */
+export function cfnChangesDigest(stack: string, changeSet: CfnChangeSet): string {
+  const entries = isNoopChangeSet(changeSet) ? [] : changeSet.changes.map((c) => cfnChangeEntry(stack, c));
+  entries.sort((a, b) => a.address.localeCompare(b.address) || a.action.localeCompare(b.action));
+  return computePlanDigest("cfn-deploy-changes", { stack, entries });
+}
+
+/**
+ * Thrown by `run` when the change set it created proposes other changes than
+ * the change set its plan read (#3997): the stack, the template or the
+ * parameters moved between the plan and the apply. The change set is deleted
+ * unexecuted. `planMoved` is core's mark for a moved plan
+ * (`isPlanMovedError`), so the command that applied it exits 3.
+ */
+export class CfnPlanMovedError extends Error {
+  readonly planMoved = true;
+  constructor(
+    public readonly stack: string,
+    public readonly planned: string,
+    public readonly now: string,
+  ) {
+    super(
+      `cfn-deploy "${stack}": refusing to apply. The change set proposes other changes than the plan that was approved ` +
+        `(planned ${planned}, now ${now}); the stack, its template or its parameters changed since. Plan it again.`,
+    );
+    this.name = "CfnPlanMovedError";
+  }
+}
+
 /** The template's bytes as a digest, or `null` when it cannot be read here (the change set then reports why). */
 function templateDigest(path: string): string | null {
   try {
@@ -133,7 +197,23 @@ function cfnPlanDigest(
  * deleted too. A change set with nothing to apply (`isNoopChangeSet`) gives
  * a member with no entries. A step whose parameters read outputs that are
  * not known yet, from a stack the same run applies first, creates no change
- * set: its member gets a hole saying whose outputs it waits on.
+ * set: its member gets a hole saying whose outputs it waits on, and no
+ * artifact, so `run` plans it afresh.
+ *
+ * With `onReplace: "block"` (the default), a change set that replaces a
+ * resource fails the plan with {@link CfnReplacementBlockedError}, so the
+ * refusal shows in the pull request's plan rather than at apply (#3997).
+ * Otherwise the result carries a {@link CfnPlanArtifact} that `run` checks
+ * its own change set against.
+ *
+ * The plan answers the outputs the stack will have (#3999), from the
+ * outputs it has now (`DescribeStacks`) and the change set: an output keeps
+ * its value when every resource its template `Value` reads keeps its
+ * physical resource, which an in-place `Modify` does and an `Add`, a
+ * `Remove` or a replacement does not ({@link cfnPlannedOutputs}). An output
+ * that reads a parameter, an import or a condition is known only after
+ * apply. A wrong guess costs a round, never a wrong apply: a dependent whose
+ * input applies as another value is held back and planned again.
  */
 async function planCfnDeploy(executor: CloudExecutor, ctx: DeployContext, input: CfnDeployInput): Promise<CapabilityPlan> {
   const stack = input.stack ?? ctx.component;
@@ -176,15 +256,23 @@ async function planCfnDeploy(executor: CloudExecutor, ctx: DeployContext, input:
   });
   try {
     if (isNoopChangeSet(changeSet)) {
-      return { member: stack, planDigest, changeSet: { member: member([]), entries: [] } };
+      const artifact: CfnPlanArtifact = { kind: "cfn-deploy-plan", stack, changesDigest: cfnChangesDigest(stack, changeSet) };
+      // Nothing to apply, so the outputs the stack has are the ones it will have (#3999).
+      const standing = await standingOutputs(executor, stack);
+      const outputs = standing ? { known: { ...standing }, unknown: [] } : undefined;
+      return { member: stack, planDigest, artifact, changeSet: { member: member([]), entries: [] }, ...(outputs ? { outputs } : {}) };
     }
     if (changeSet.status === "FAILED") {
       throw new Error(
         `cfn-deploy "${stack}": CloudFormation could not create a change set to plan it${changeSet.statusReason ? `: ${changeSet.statusReason}` : ""}`,
       );
     }
+    const blocked = blockedReplacements(changeSet.changes);
+    if (blocked.length > 0 && (input.onReplace ?? "block") === "block") throw new CfnReplacementBlockedError(stack, blocked);
     const entries = changeSet.changes.map((c) => cfnChangeEntry(stack, c));
-    return { member: stack, planDigest, changeSet: { member: member([]), entries } };
+    const artifact: CfnPlanArtifact = { kind: "cfn-deploy-plan", stack, changesDigest: cfnChangesDigest(stack, changeSet) };
+    const outputs = changeSet.stackCreated ? undefined : await plannedStackOutputs(executor, stack, input.template, changeSet.changes);
+    return { member: stack, planDigest, artifact, changeSet: { member: member([]), entries }, ...(outputs ? { outputs } : {}) };
   } finally {
     await cleanUpPlanChangeSet(executor, changeSet);
   }
@@ -211,6 +299,118 @@ async function cleanUpPlanChangeSet(executor: CloudExecutor, changeSet: CfnChang
   }
 }
 
+/** The stack's outputs as they stand, or `undefined` when they cannot be read. */
+async function standingOutputs(executor: CloudExecutor, stack: string): Promise<Record<string, string> | undefined> {
+  try {
+    return { ...(await executor.cloudformation.describeStack(stack)).outputs };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * What the plan says of the stack's outputs once `changes` apply: none to
+ * say for a template with no `Outputs`, which needs no `DescribeStacks`.
+ */
+async function plannedStackOutputs(executor: CloudExecutor, stack: string, templatePath: string, changes: readonly CfnChange[]): Promise<PlannedOutputs | undefined> {
+  const template = readTemplate(templatePath) as { Outputs?: Record<string, unknown> } | undefined;
+  if (!template || typeof template !== "object") return undefined;
+  if (Object.keys(template.Outputs ?? {}).length === 0) return { known: {}, unknown: [] };
+  return cfnPlannedOutputs(template, changes, await standingOutputs(executor, stack));
+}
+
+/** The template at `path` as JSON, or `undefined` when it cannot be read or parsed here. */
+function readTemplate(path: string): unknown {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * What a template's `Value` reads (#3999): the logical ids it names through
+ * `Ref`, `Fn::GetAtt` and `Fn::Sub`, and whether it reads anything this plan
+ * cannot follow (`Fn::ImportValue`, a condition's `Fn::If`, or an intrinsic
+ * it does not know).
+ */
+function valueReads(value: unknown): { ids: Set<string>; opaque: boolean } {
+  const ids = new Set<string>();
+  let opaque = false;
+  const sub = (text: string): void => {
+    for (const m of text.matchAll(/\$\{([^}!][^}]*)\}/g)) ids.add(m[1]!.split(".")[0]!);
+  };
+  const walk = (v: unknown): void => {
+    if (Array.isArray(v)) return v.forEach(walk);
+    if (v === null || typeof v !== "object") return;
+    const entries = Object.entries(v as Record<string, unknown>);
+    if (entries.length === 1) {
+      const [key, arg] = entries[0]!;
+      if (key === "Ref") {
+        if (typeof arg === "string") ids.add(arg);
+        else opaque = true;
+        return;
+      }
+      if (key === "Fn::GetAtt") {
+        if (Array.isArray(arg) && typeof arg[0] === "string") ids.add(arg[0]);
+        else if (typeof arg === "string") ids.add(arg.split(".")[0]!);
+        else opaque = true;
+        return;
+      }
+      if (key === "Fn::Sub") {
+        if (typeof arg === "string") sub(arg);
+        else if (Array.isArray(arg) && typeof arg[0] === "string") {
+          const vars = (arg[1] ?? {}) as Record<string, unknown>;
+          for (const m of arg[0].matchAll(/\$\{([^}!][^}]*)\}/g)) if (!(m[1]! in vars)) ids.add(m[1]!.split(".")[0]!);
+          walk(vars);
+        } else opaque = true;
+        return;
+      }
+      if (key === "Fn::Join" || key === "Fn::Select" || key === "Fn::Split" || key === "Fn::Base64") return walk(arg);
+      if (key.startsWith("Fn::") || key === "Condition") {
+        opaque = true;
+        return;
+      }
+    }
+    entries.forEach(([, x]) => walk(x));
+  };
+  walk(value);
+  return { ids, opaque };
+}
+
+/**
+ * The outputs a stack will have once `changes` apply (#3999), from its
+ * template and the outputs it has now. An output is known, at the value it
+ * has now, when its `Value` reads only pseudo parameters and resources whose
+ * physical resource the change set keeps (no `Add`, `Remove`, `Import` or
+ * `Dynamic`, no replacement, no change in a nested stack under it). One
+ * that reads a parameter, an import or a condition, one the stack does not
+ * have yet, and every output of a template this cannot read, is unknown.
+ * `undefined` when there is no template or no standing stack to read from.
+ */
+export function cfnPlannedOutputs(template: unknown, changes: readonly CfnChange[], standing: Record<string, string> | undefined): PlannedOutputs | undefined {
+  if (!standing || template === null || typeof template !== "object") return undefined;
+  const t = template as { Outputs?: Record<string, { Value?: unknown; Condition?: unknown }>; Parameters?: Record<string, unknown> };
+  const parameters = new Set(Object.keys(t.Parameters ?? {}));
+  const moved = new Set<string>();
+  for (const c of changes) {
+    const id = c.nestedStack?.[0] ?? c.logicalResourceId;
+    const keeps = !c.nestedStack && c.action === "Modify" && !c.replacement && c.replacementMode !== "True" && c.replacementMode !== "Conditional";
+    if (!keeps) moved.add(id);
+  }
+  const known: Record<string, unknown> = {};
+  const unknown: string[] = [];
+  for (const [name, output] of Object.entries(t.Outputs ?? {}).sort(([a], [b]) => a.localeCompare(b))) {
+    const { ids, opaque } = valueReads(output?.Value);
+    const stays =
+      !opaque && output?.Condition === undefined && name in standing &&
+      [...ids].every((id) => id.startsWith("AWS::") || (!parameters.has(id) && !moved.has(id)));
+    if (stays) known[name] = standing[name];
+    else unknown.push(name);
+  }
+  return { known, unknown };
+}
+
 /** Whether a CloudFormation error says the stack does not exist. */
 const STACK_MISSING = /does not exist/i;
 
@@ -324,6 +524,18 @@ export function createCfnDeployCapability(
         parameters: flattenCfnInputs(input),
       });
 
+      // Handed the plan the approver approved (#3997), apply only a change
+      // set that proposes the same changes. Anything else means the stack,
+      // the template or the parameters moved since the plan.
+      const planned = ctx.plans?.[stack];
+      if (isCfnPlanArtifact(planned)) {
+        const now = cfnChangesDigest(stack, changeSet);
+        if (now !== planned.changesDigest) {
+          await cleanUpPlanChangeSet(executor, changeSet);
+          throw new CfnPlanMovedError(stack, planned.changesDigest, now);
+        }
+      }
+
       // An unchanged stack yields a change set with nothing to apply.
       // `execute-change-set` rejects it ("The submitted information didn't
       // contain changes"), which would fail this component and stop the whole
@@ -340,7 +552,7 @@ export function createCfnDeployCapability(
         return { stackStatus, outputs };
       }
 
-      const replacements = changeSet.changes.filter((c) => c.replacement);
+      const replacements = blockedReplacements(changeSet.changes);
       let snapshotId: string | undefined;
 
       if (replacements.length > 0 && onReplace === "block") {

package/src/components/cfn-plan-floci.e2e.test.ts

@@ -0,0 +1,76 @@
+/**
+ * `cfn-deploy`'s plan and apply against Floci (#3997), through the real
+ * executor (`aws` CLI). Set CHANT_FLOCI_ENDPOINT to a running Floci, for
+ * example `docker run -d -p 4611:4566 floci/floci` and
+ * `CHANT_FLOCI_ENDPOINT=http://localhost:4611`. Skipped without it.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { CfnPlanMovedError, createCfnDeployCapability } from "./apply";
+import { defaultCloudExecutor } from "./cloud-executor";
+
+const endpoint = process.env.CHANT_FLOCI_ENDPOINT;
+
+describe.skipIf(!endpoint)("cfn-deploy plan against Floci (#3997)", () => {
+  const stack = `chant-plan-${process.pid}-${Date.now()}`;
+  const ctx = { env: "local", component: stack };
+  const saved = { ...process.env };
+  let dir: string;
+  let template: string;
+  const aws = (...args: string[]): string => execFileSync("aws", ["--endpoint-url", endpoint!, ...args], { encoding: "utf8" });
+  // The change sets still open on the stack. Floci also lists executed ones, as EXECUTE_COMPLETE.
+  const changeSets = (): string[] =>
+    ((JSON.parse(aws("cloudformation", "list-change-sets", "--stack-name", stack)) as { Summaries?: Array<{ ChangeSetName: string; ExecutionStatus?: string }> }).Summaries ?? [])
+      .filter((c) => c.ExecutionStatus !== "EXECUTE_COMPLETE")
+      .map((c) => c.ChangeSetName);
+  const write = (resources: Record<string, unknown>): void => writeFileSync(template, JSON.stringify({ Resources: resources }));
+  const topic = (name: string) => ({ Type: "AWS::SNS::Topic", Properties: { DisplayName: name } });
+
+  beforeAll(() => {
+    Object.assign(process.env, { AWS_ENDPOINT_URL: endpoint, AWS_ACCESS_KEY_ID: "test", AWS_SECRET_ACCESS_KEY: "test", AWS_REGION: "us-east-1" });
+    dir = mkdtempSync(join(tmpdir(), "cfn-plan-floci-"));
+    template = join(dir, "stack.template.json");
+  });
+
+  afterAll(() => {
+    try {
+      aws("cloudformation", "delete-stack", "--stack-name", stack);
+    } catch { /* never created */ }
+    process.env = saved;
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("plans a create, an update and no change, applies what it planned, and refuses a plan the template moved past", async () => {
+    const capability = createCfnDeployCapability(defaultCloudExecutor());
+
+    write({ Topic: topic("a") });
+    const created = await capability.plan!(ctx, { stack, template });
+    expect(created.changeSet!.entries.map((e) => [e.address, e.action])).toEqual([["Topic", "create"]]);
+    // The plan left no stack behind: the empty one its CREATE change set made is gone.
+    await expect(capability.outputs!(ctx, { stack, template })).resolves.toEqual({});
+    const first = await capability.run({ ...ctx, plans: { [stack]: created.artifact } }, { stack, template });
+    expect(first.stackStatus).toBe("CREATE_COMPLETE");
+
+    write({ Topic: topic("b"), Queue: { Type: "AWS::SQS::Queue" } });
+    const updated = await capability.plan!(ctx, { stack, template });
+    expect(updated.changeSet!.entries.map((e) => [e.address, e.action]).sort()).toEqual([["Queue", "create"], ["Topic", "update"]]);
+    expect(changeSets()).toEqual([]);
+
+    // The template moves after the plan: run refuses and leaves no change set.
+    write({ Topic: topic("b"), Queue: { Type: "AWS::SQS::Queue" }, Dlq: { Type: "AWS::SQS::Queue" } });
+    await expect(capability.run({ ...ctx, plans: { [stack]: updated.artifact } }, { stack, template })).rejects.toBeInstanceOf(CfnPlanMovedError);
+    expect(changeSets()).toEqual([]);
+
+    write({ Topic: topic("b"), Queue: { Type: "AWS::SQS::Queue" } });
+    const second = await capability.run({ ...ctx, plans: { [stack]: updated.artifact } }, { stack, template });
+    expect(second.stackStatus).toBe("UPDATE_COMPLETE");
+
+    const same = await capability.plan!(ctx, { stack, template });
+    expect(same.changeSet!.entries).toEqual([]);
+    expect(changeSets()).toEqual([]);
+  }, 600_000); // each `aws` call takes seconds, and a plan or a run makes several
+});

package/src/components/cfn-plan.test.ts

@@ -11,11 +11,14 @@ import { join } from "node:path";
 import { CapabilityRegistry } from "@intentius/chant/components/capability";
 import type { DriverComponent } from "@intentius/chant/components/driver";
 import { planFanOut } from "@intentius/chant/components/fan-out";
-import { planPrSet, prReport } from "@intentius/chant/components/pr-run";
+import { applyPrSet, planPrSet, prReport } from "@intentius/chant/components/pr-run";
 import { composeChangeSet } from "@intentius/chant/change-set";
 import { groupChangeSet, planSummaryHeadline } from "@intentius/chant/plan-summary";
 import { memberCounts, prStatusDescription, renderPrNote } from "@intentius/chant/pr-loop";
-import { createCfnDeployCapability } from "./apply";
+import { CfnPlanMovedError, CfnReplacementBlockedError, cfnChangeEntry, createCfnDeployCapability, type CfnDeployInput } from "./apply";
+import { isPlanMovedError } from "@intentius/chant/components/capability";
+import { planMovedIn } from "@intentius/chant/components/driver";
+import { readCfnChanges, templateHasNestedStacks, type DescribedCfnChangeSet } from "./cloud-executor";
 import { createMockCloudExecutor, type FakeStackConfig } from "./__tests__/mock-cloud-executor";
 
 let dir: string;
@@ -31,10 +34,10 @@ afterEach(() => rmSync(dir, { recursive: true, force: true }));
 
 const ctx = { env: "local", component: "network" };
 
-async function planOne(config: FakeStackConfig) {
+async function planOne(config: FakeStackConfig, extra: Partial<CfnDeployInput> = {}) {
   const mock = createMockCloudExecutor({ stacks: { network: config } });
   const capability = createCfnDeployCapability(mock.executor);
-  const planned = await capability.plan!(ctx, { stack: "network", template });
+  const planned = await capability.plan!(ctx, { stack: "network", template, ...extra });
   const doc = composeChangeSet([planned.changeSet!]);
   return { mock, planned, doc, counts: memberCounts(doc, "network") };
 }
@@ -77,17 +80,51 @@ describe("cfn-deploy plan (#4084)", () => {
         { action: "Modify", logicalResourceId: "Topic", resourceType: "AWS::SNS::Topic", replacement: false, replacementMode: "Conditional" },
         { action: "Remove", logicalResourceId: "Old", resourceType: "AWS::SQS::Queue", replacement: false },
       ],
-    });
+    }, { onReplace: "allow" });
     expect(counts).toEqual({ create: 0, update: 0, replace: 2, delete: 1 });
     expect(planSummaryHeadline(groupChangeSet(doc))).toContain("3 destroys or replacements");
   });
 
-  it("a change set with nothing to apply is a member with no entries and no holes", async () => {
-    const { counts, doc, mock } = await planOne({ noChanges: true });
+  it("a change set with nothing to apply is a member with no entries and no holes, whose outputs are the stack's own (#3999)", async () => {
+    const { counts, doc, mock, planned } = await planOne({ noChanges: true, outputs: { VpcId: "vpc-1" } });
     expect(counts).toEqual({ create: 0, update: 0, replace: 0, delete: 0 });
     expect(doc.members[0]).toMatchObject({ status: "planned", holes: [] });
     expect(groupChangeSet(doc, { unit: "member" }).groups[0].noChanges).toBe(true);
-    expect(methods(mock)).toEqual(["createChangeSet", "deleteChangeSet"]);
+    expect(planned.outputs).toEqual({ known: { VpcId: "vpc-1" }, unknown: [] });
+    expect(methods(mock)).toEqual(["createChangeSet", "describeStack", "deleteChangeSet"]);
+  });
+
+  it("a change set with changes keeps the outputs of resources it keeps, and not of the ones it adds or replaces (#3999)", async () => {
+    writeFileSync(
+      template,
+      JSON.stringify({
+        Parameters: { Env: { Type: "String" } },
+        Resources: { Topic: { Type: "AWS::SNS::Topic" }, Queue: { Type: "AWS::SQS::Queue" }, Table: { Type: "AWS::DynamoDB::Table" } },
+        Outputs: {
+          TopicArn: { Value: { Ref: "Topic" } },
+          QueueUrl: { Value: { "Fn::GetAtt": ["Queue", "QueueUrl"] } },
+          TableArn: { Value: { "Fn::Sub": "${Table.Arn}" } },
+          Region: { Value: { "Fn::Sub": "${AWS::Region}" } },
+          EnvName: { Value: { Ref: "Env" } },
+          Imported: { Value: { "Fn::ImportValue": "x" } },
+        },
+      }),
+    );
+    const standing = { TopicArn: "arn:topic", QueueUrl: "https://q", TableArn: "arn:table", Region: "us-east-1", EnvName: "prod", Imported: "x" };
+    const { planned } = await planOne({
+      outputs: standing,
+      changes: [
+        { action: "Modify", logicalResourceId: "Topic", resourceType: "AWS::SNS::Topic", replacement: false, replacementMode: "False" },
+        { action: "Modify", logicalResourceId: "Queue", resourceType: "AWS::SQS::Queue", replacement: true, replacementMode: "True" },
+        { action: "Modify", logicalResourceId: "Table", resourceType: "AWS::DynamoDB::Table", replacement: false, replacementMode: "Conditional" },
+      ],
+    }, { onReplace: "allow" });
+    expect(planned.outputs).toEqual({ known: { Region: "us-east-1", TopicArn: "arn:topic" }, unknown: ["EnvName", "Imported", "QueueUrl", "TableArn"] });
+  });
+
+  it("a stack the change set creates says nothing of its outputs (#3999)", async () => {
+    const { planned } = await planOne({ missing: true, changes: [{ action: "Add", logicalResourceId: "Topic", resourceType: "AWS::SNS::Topic", replacement: false }] });
+    expect(planned.outputs).toBeUndefined();
   });
 
   it("a stack that does not exist yet counts every resource as a create, and the empty stack the CREATE change set made is deleted", async () => {
@@ -175,21 +212,51 @@ describe("pr-plan over cfn-deploy members (#4084)", () => {
 
   it("counts each member's changes from its change set, and the note and status line show them", async () => {
     const { set, report } = await planBoth({
-      network: {
-        outputs: { TopicArn: "arn:topic" },
-        changes: [{ action: "Modify", logicalResourceId: "Topic", resourceType: "AWS::SNS::Topic", replacement: false, details: ["DisplayName"] }],
-      },
+      network: { outputs: { TopicArn: "arn:topic" }, noChanges: true },
       "cluster-a": { changes: [{ action: "Add", logicalResourceId: "clusterAQueue", resourceType: "AWS::SQS::Queue", replacement: false }] },
     });
     expect(set.members.map((m) => [m.member, m.counts])).toEqual([
       ["cluster-a", { create: 1, update: 0, replace: 0, delete: 0 }],
-      ["network", { create: 0, update: 1, replace: 0, delete: 0 }],
+      ["network", { create: 0, update: 0, replace: 0, delete: 0 }],
     ]);
+    // network changes nothing, so its plan knows its outputs: the ones it has (#3999).
+    expect(set.plannedOutputs).toEqual({ network: ["TopicArn"] });
     const note = renderPrNote(report);
-    expect(note).toContain("| `network` | network | planned | 0 | 1 | 0 | 0 |");
+    expect(note).toContain("| `network` | network | planned | 0 | 0 | 0 | 0 |");
     expect(note).toContain("| `cluster-a` | cluster-a | planned | 1 | 0 | 0 | 0 |");
-    expect(note).not.toContain("no changes");
-    expect(prStatusDescription(report)).toMatch(/^2 members: 2 to change, 0 to destroy or replace;/);
+    expect(prStatusDescription(report)).toMatch(/^2 members: 1 to change, 0 to destroy or replace;/);
+  });
+
+  it("a stack whose upstream changes in the same pull request reads its outputs as known only after apply (#3999)", async () => {
+    const { set, report, mock } = await planBoth({
+      network: {
+        outputs: { TopicArn: "arn:topic" },
+        changes: [{ action: "Modify", logicalResourceId: "Topic", resourceType: "AWS::SNS::Topic", replacement: false, details: ["DisplayName"] }],
+      },
+      "cluster-a": { changes: [{ action: "Add", logicalResourceId: "clusterAQueue", resourceType: "AWS::SQS::Queue", replacement: false }] },
+    });
+    // network's template has no Outputs to say TopicArn stays, so it is not the TopicArn standing now.
+    expect(mock.calls.filter((c) => c.method === "describeStack")).toEqual([]);
+    expect(set.plannedOutputs).toEqual({ network: [] });
+    expect(set.members.find((m) => m.member === "cluster-a")?.unknownInputs).toEqual(["network.TopicArn"]);
+    const note = renderPrNote(report);
+    expect(note).toContain("| `cluster-a` | cluster-a | planned; inputs from network; re-checked on apply | ? | ? | ? | ? |");
+    expect(note).toContain("Known only after apply: `cluster-a` reads `network.TopicArn`.");
+  });
+
+  it("a stack whose upstream changes a resource in place reads the output that resource keeps, at its value now (#3999)", async () => {
+    writeFileSync(template, JSON.stringify({ Resources: { Topic: { Type: "AWS::SNS::Topic" } }, Outputs: { TopicArn: { Value: { Ref: "Topic" } } } }));
+    const { set, mock } = await planBoth({
+      network: {
+        outputs: { TopicArn: "arn:topic" },
+        changes: [{ action: "Modify", logicalResourceId: "Topic", resourceType: "AWS::SNS::Topic", replacement: false, details: ["DisplayName"] }],
+      },
+      "cluster-a": { outputs: {}, changes: [{ action: "Add", logicalResourceId: "clusterAQueue", resourceType: "AWS::SQS::Queue", replacement: false }] },
+    });
+    expect(set.plannedOutputs).toEqual({ network: ["TopicArn"] });
+    expect(set.members.find((m) => m.member === "cluster-a")?.unknownInputs).toBeUndefined();
+    const created = mock.calls.filter((c) => c.method === "createChangeSet").map((c) => c.args as { stackName: string; parameters?: Record<string, string> });
+    expect(created.find((c) => c.stackName === "cluster-a")?.parameters).toEqual({ TopicArn: "arn:topic" });
   });
 
   it("a member whose inputs come from a stack the run creates first says so, with no counts and no change set", async () => {
@@ -222,3 +289,145 @@ describe("pr-plan over cfn-deploy members (#4084)", () => {
     expect(replaced.set.doc.digest).not.toBe(first.set.doc.digest);
   });
 });
+
+describe("cfn-deploy applies the change set it planned (#3997)", () => {
+  const topicUpdate = { action: "Modify" as const, logicalResourceId: "Topic", resourceType: "AWS::SNS::Topic", replacement: false, replacementMode: "False" as const, details: ["DisplayName"] };
+  const queueAdd = { action: "Add" as const, logicalResourceId: "Queue", resourceType: "AWS::SQS::Queue", replacement: false };
+
+  it("a plan hands run an artifact over its changes, and run executes a change set with the same changes", async () => {
+    const mock = createMockCloudExecutor({ stacks: { network: { changes: [topicUpdate] } } });
+    const capability = createCfnDeployCapability(mock.executor);
+    const planned = await capability.plan!(ctx, { stack: "network", template });
+    expect(planned.artifact).toMatchObject({ kind: "cfn-deploy-plan", stack: "network" });
+    const out = await capability.run({ ...ctx, plans: { network: planned.artifact } }, { stack: "network", template });
+    expect(out.stackStatus).toBe("UPDATE_COMPLETE");
+    expect(methods(mock)).toEqual(["createChangeSet", "deleteChangeSet", "createChangeSet", "executeChangeSet", "waitForStack"]);
+  });
+
+  it("run refuses, deletes its change set unexecuted and marks the error as a moved plan when the changes differ from the plan's", async () => {
+    const mock = createMockCloudExecutor({ stacks: { network: { changes: [topicUpdate] } } });
+    const capability = createCfnDeployCapability(mock.executor);
+    const planned = await capability.plan!(ctx, { stack: "network", template });
+    mock.setStack("network", { changes: [topicUpdate, queueAdd] });
+    const err = await capability.run({ ...ctx, plans: { network: planned.artifact } }, { stack: "network", template }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(CfnPlanMovedError);
+    expect(isPlanMovedError(err)).toBe(true);
+    expect((err as Error).message).toMatch(/refusing to apply.*Plan it again/);
+    expect(methods(mock).slice(2)).toEqual(["createChangeSet", "deleteChangeSet"]);
+  });
+
+  it("a plan of no changes refuses a run whose change set now has some, and accepts one that still has none", async () => {
+    const mock = createMockCloudExecutor({ stacks: { network: { noChanges: true } } });
+    const capability = createCfnDeployCapability(mock.executor);
+    const planned = await capability.plan!(ctx, { stack: "network", template });
+    await expect(capability.run({ ...ctx, plans: { network: planned.artifact } }, { stack: "network", template })).resolves.toMatchObject({ stackStatus: "UPDATE_COMPLETE" });
+    mock.setStack("network", { noChanges: false, changes: [queueAdd] });
+    await expect(capability.run({ ...ctx, plans: { network: planned.artifact } }, { stack: "network", template })).rejects.toBeInstanceOf(CfnPlanMovedError);
+    expect(methods(mock)).not.toContain("executeChangeSet");
+  });
+
+  it("a run whose CREATE change set moved deletes the empty stack it made, too", async () => {
+    const mock = createMockCloudExecutor({ stacks: { network: { missing: true, changes: [queueAdd] } } });
+    const capability = createCfnDeployCapability(mock.executor);
+    const planned = await capability.plan!(ctx, { stack: "network", template });
+    mock.setStack("network", { changes: [queueAdd, { ...queueAdd, logicalResourceId: "Dlq" }] });
+    await expect(capability.run({ ...ctx, plans: { network: planned.artifact } }, { stack: "network", template })).rejects.toBeInstanceOf(CfnPlanMovedError);
+    expect(methods(mock).slice(3)).toEqual(["createChangeSet", "deleteChangeSet", "deleteStackShell"]);
+  });
+
+  it("a member with holes hands run no artifact, so run plans it afresh", async () => {
+    const mock = createMockCloudExecutor({ stacks: { network: { changes: [queueAdd] } } });
+    const capability = createCfnDeployCapability(mock.executor);
+    const planned = await capability.plan!({ ...ctx, unresolvedInputs: ["upstream"] }, { stack: "network", template });
+    expect(planned.artifact).toBeUndefined();
+  });
+
+  it('onReplace "block" refuses at plan time, naming the resources, and the change set is still deleted', async () => {
+    const mock = createMockCloudExecutor({
+      stacks: { network: { changes: [{ action: "Modify", logicalResourceId: "Table", resourceType: "AWS::DynamoDB::Table", replacement: true, replacementMode: "True" }] } },
+    });
+    const capability = createCfnDeployCapability(mock.executor);
+    const err = await capability.plan!(ctx, { stack: "network", template }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(CfnReplacementBlockedError);
+    expect((err as Error).message).toContain("(Table)");
+    expect(methods(mock)).toEqual(["createChangeSet", "deleteChangeSet"]);
+  });
+
+  it('onReplace "block" lets a Conditional replacement plan, as run does', async () => {
+    const { counts } = await planOne({
+      changes: [{ action: "Modify", logicalResourceId: "Topic", resourceType: "AWS::SNS::Topic", replacement: false, replacementMode: "Conditional" }],
+    });
+    expect(counts.replace).toBe(1);
+  });
+
+  it("pr-apply over a moved stack fails the member with the refusal, executes nothing, and the run reads as a moved plan", async () => {
+    const mock = createMockCloudExecutor({ stacks: { network: { changes: [topicUpdate] } } });
+    const registry = new CapabilityRegistry();
+    registry.register(createCfnDeployCapability(mock.executor));
+    const components: DriverComponent[] = [
+      { name: "network", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", stack: "network", template }] }] },
+    ];
+    const plan = planFanOut({ components, changed: ["network"] });
+    const set = await planPrSet({ components, plan, registry, env: "local" });
+    expect(set.plans.network?.network).toMatchObject({ kind: "cfn-deploy-plan" });
+
+    mock.setStack("network", { changes: [queueAdd] });
+    const moved = await applyPrSet({ components, plan, registry, env: "local", set });
+    expect(moved.status).toBe("failed");
+    expect(planMovedIn(moved.run.results)).toBe(true);
+    expect(moved.members[0]).toMatchObject({ member: "network", status: "failed" });
+    expect(methods(mock)).not.toContain("executeChangeSet");
+
+    mock.setStack("network", { changes: [topicUpdate] });
+    const applied = await applyPrSet({ components, plan, registry, env: "local", set });
+    expect(applied.status).toBe("applied");
+    expect(planMovedIn(applied.run.results)).toBe(false);
+    expect(methods(mock)).toContain("executeChangeSet");
+  });
+});
+
+describe("cfn-deploy plans nested stacks (#3997)", () => {
+  it("reads a nested change set's changes under the nested stack's logical id", async () => {
+    const root: DescribedCfnChangeSet = {
+      Status: "CREATE_COMPLETE",
+      Changes: [
+        { ResourceChange: { Action: "Modify", LogicalResourceId: "Child", ResourceType: "AWS::CloudFormation::Stack", Replacement: "False", ChangeSetId: "arn:child" } },
+        { ResourceChange: { Action: "Add", LogicalResourceId: "Queue", ResourceType: "AWS::SQS::Queue" } },
+      ],
+    };
+    const nested: Record<string, DescribedCfnChangeSet> = {
+      "arn:child": {
+        Status: "CREATE_COMPLETE",
+        Changes: [
+          { ResourceChange: { Action: "Modify", LogicalResourceId: "Grand", ResourceType: "AWS::CloudFormation::Stack", Replacement: "False", ChangeSetId: "arn:grand" } },
+          { ResourceChange: { Action: "Modify", LogicalResourceId: "Topic", ResourceType: "AWS::SNS::Topic", Replacement: "True", Details: [{ Target: { Name: "TopicName" } }] } },
+        ],
+      },
+      "arn:grand": { Status: "CREATE_COMPLETE", Changes: [{ ResourceChange: { Action: "Remove", LogicalResourceId: "Old", ResourceType: "AWS::SQS::Queue" } }] },
+    };
+    const described: string[] = [];
+    const changes = await readCfnChanges(root, async (id) => {
+      described.push(id);
+      return nested[id]!;
+    });
+    expect(described).toEqual(["arn:child", "arn:grand"]);
+    expect(changes.map((c) => [c.logicalResourceId, c.nestedStack ?? []])).toEqual([
+      ["Child", []],
+      ["Grand", ["Child"]],
+      ["Old", ["Child", "Grand"]],
+      ["Topic", ["Child"]],
+      ["Queue", []],
+    ]);
+    const entries = changes.map((c) => cfnChangeEntry("app", c));
+    expect(entries.find((e) => e.name === "Topic")).toMatchObject({ address: "Child/Topic", module: "Child", action: "replace" });
+    expect(entries.find((e) => e.name === "Old")).toMatchObject({ address: "Child/Grand/Old", module: "Child/Grand", action: "delete" });
+    expect(entries.find((e) => e.name === "Queue")).toMatchObject({ address: "Queue", action: "create" });
+    expect(entries.find((e) => e.name === "Queue")).not.toHaveProperty("module");
+  });
+
+  it("asks for nested change sets only for a template that declares a nested stack", () => {
+    expect(templateHasNestedStacks(JSON.stringify({ Resources: { Child: { Type: "AWS::CloudFormation::Stack" } } }))).toBe(true);
+    expect(templateHasNestedStacks(JSON.stringify({ Resources: { Topic: { Type: "AWS::SNS::Topic" } } }))).toBe(false);
+    expect(templateHasNestedStacks("not json")).toBe(false);
+  });
+});