@intentius/chant-lexicon-aws 0.124.51 → 0.124.52

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

@@ -15,6 +15,7 @@ import { applyPrSet, planPrSet, prReport } from "@intentius/chant/components/pr-
 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 { PlanShapeMovedError } from "@intentius/chant/components/covered-round";
 import { CfnPlanMovedError, CfnReplacementBlockedError, cfnChangeEntry, createCfnDeployCapability, type CfnDeployInput } from "./apply";
 import { isPlanMovedError } from "@intentius/chant/components/capability";
 import { planMovedIn } from "@intentius/chant/components/driver";
@@ -122,6 +123,31 @@ describe("cfn-deploy plan (#4084)", () => {
     expect(planned.outputs).toEqual({ known: { Region: "us-east-1", TopicArn: "arn:topic" }, unknown: ["EnvName", "Imported", "QueueUrl", "TableArn"] });
   });
 
+  it("an output that is a plain string, or a Ref to a parameter this plan has a value for, is known at that value, changed or new (#4419)", async () => {
+    writeFileSync(
+      template,
+      JSON.stringify({
+        Parameters: { Port: { Type: "String" }, Later: { Type: "String" } },
+        Resources: { Setting: { Type: "AWS::SSM::Parameter" } },
+        Outputs: {
+          Literal: { Value: "8090" },
+          NewLiteral: { Value: "9000" },
+          Passed: { Value: { Ref: "Port" } },
+          NotYet: { Value: { Ref: "Later" } },
+          Setting: { Value: { Ref: "Setting" } },
+        },
+      }),
+    );
+    const { planned } = await planOne(
+      {
+        outputs: { Literal: "8080", Passed: "8080", NotYet: "x", Setting: "/setting" },
+        changes: [{ action: "Modify", logicalResourceId: "Setting", resourceType: "AWS::SSM::Parameter", replacement: false, replacementMode: "False" }],
+      },
+      { inputs: { Port: "8090" } },
+    );
+    expect(planned.outputs).toEqual({ known: { Literal: "8090", NewLiteral: "9000", Passed: "8090", Setting: "/setting" }, unknown: ["NotYet"] });
+  });
+
   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();
@@ -240,7 +266,8 @@ describe("pr-plan over cfn-deploy members (#4084)", () => {
     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 | ? | ? | ? | ? |");
+    // The member is previewed against a stand-in, so it counts its changes (#4419).
+    expect(note).toContain("| `cluster-a` | cluster-a | planned | 1 | 0 | 0 | 0 |");
     expect(note).toContain("Known only after apply: `cluster-a` reads `network.TopicArn`.");
   });
 
@@ -259,19 +286,28 @@ describe("pr-plan over cfn-deploy members (#4084)", () => {
     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 () => {
+  it("a member whose inputs come from a stack the run creates first is previewed against a stand-in, and the stand-in is deleted (#4419)", async () => {
     const { mock, set, report } = await planBoth({
       network: { missing: true, changes: [{ action: "Add", logicalResourceId: "Topic", resourceType: "AWS::SNS::Topic", replacement: false }] },
-      "cluster-a": { missing: true },
+      "cluster-a": { missing: true, changes: [{ action: "Add", logicalResourceId: "clusterAQueue", resourceType: "AWS::SQS::Queue", replacement: false }] },
     });
     const clusterA = set.doc.members.find((m) => m.member === "cluster-a")!;
-    expect(clusterA).toMatchObject({ status: "planned", holes: [{ address: "cluster-a", reason: "inputs from network; re-checked on apply" }] });
-    expect(set.doc.entries.filter((e) => e.member === "cluster-a")).toEqual([]);
-    expect(mock.calls.filter((c) => c.method === "createChangeSet").map((c) => (c.args as { stackName: string }).stackName)).toEqual(["network"]);
+    expect(clusterA).toMatchObject({ status: "planned", holes: [] });
+    expect(set.doc.entries.filter((e) => e.member === "cluster-a")).toHaveLength(1);
+    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: "known-after-apply" });
+    const deleted = mock.calls.filter((c) => c.method === "deleteChangeSet").map((c) => (c.args as { stackName: string }).stackName);
+    expect(deleted.sort()).toEqual(["cluster-a", "network"]);
     const note = renderPrNote(report);
-    expect(note).toContain("| `cluster-a` | cluster-a | planned; inputs from network; re-checked on apply | ? | ? | ? | ? |");
+    expect(note).toContain("| `cluster-a` | cluster-a | planned | 1 | 0 | 0 | 0 |");
     expect(note).toContain("| `network` | network | planned | 1 | 0 | 0 | 0 |");
-    expect(prStatusDescription(report)).toContain("1 with holes");
+  });
+
+  it("a member whose upstream is unresolved but names no unknown input stays a hole", async () => {
+    const mock = createMockCloudExecutor({ stacks: { network: {} } });
+    const planned = await createCfnDeployCapability(mock.executor).plan!({ ...ctx, unresolvedInputs: ["up"] }, { stack: "network", template });
+    expect(planned.changeSet?.member.holes).toMatchObject([{ reason: "inputs from up; re-checked on apply" }]);
+    expect(mock.calls.filter((c) => c.method === "createChangeSet")).toEqual([]);
   });
 
   it("planning the same state twice gives the same digest, so the apply's plan matches the approved one", async () => {
@@ -335,7 +371,7 @@ describe("cfn-deploy applies the change set it planned (#3997)", () => {
     expect(methods(mock).slice(3)).toEqual(["createChangeSet", "deleteChangeSet", "deleteStackShell"]);
   });
 
-  it("a member with holes hands run no artifact, so run plans it afresh", async () => {
+  it("a member with a hole it could not preview 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 });
@@ -438,3 +474,286 @@ describe("cfn-deploy targets (#4300)", () => {
     expect(targetRefusal(createCfnDeployCapability(createMockCloudExecutor().executor))).toMatch(/cfn-deploy can't narrow/);
   });
 });
+
+describe("cfn-deploy previews a member whose inputs are unknown, and checks the real change against it (#4419)", () => {
+  const eni = { action: "Modify" as const, logicalResourceId: "Eni", resourceType: "AWS::EC2::NetworkInterface", replacement: false, replacementMode: "False" as const };
+  const withDriver = (property: string, causingEntity = "SubnetId") => ({
+    ...eni,
+    details: [property, "Description"],
+    drivers: [{ property, changeSource: "ParameterReference", causingEntity }, { property: "Description", changeSource: "DirectModification" }],
+  });
+  const input = (): CfnDeployInput => ({ stack: "net", template, inputs: { SubnetId: undefined as never } });
+
+  beforeEach(() => {
+    writeFileSync(
+      template,
+      JSON.stringify({
+        Parameters: { SubnetId: { Type: "AWS::EC2::Subnet::Id" }, Desc: { Type: "String", Default: "x" } },
+        Resources: {
+          Eni: { Type: "AWS::EC2::NetworkInterface", Properties: { SubnetId: { Ref: "SubnetId" }, Description: "d" } },
+          Q: { Type: "AWS::SQS::Queue", Properties: { QueueName: { "Fn::Sub": "q-${SubnetId}" } } },
+        },
+      }),
+    );
+  });
+
+  const q = { action: "Add" as const, logicalResourceId: "Q", resourceType: "AWS::SQS::Queue", replacement: false };
+
+  it("creates the change set with an id-shaped stand-in, marks the driven properties unknown, and deletes the change set", async () => {
+    const mock = createMockCloudExecutor({ stacks: { net: { changes: [withDriver("SubnetId"), q] } } });
+    const planned = await createCfnDeployCapability(mock.executor).plan!({ ...ctx, unresolvedInputs: ["vpc"] }, input());
+    const created = mock.calls.find((c) => c.method === "createChangeSet")!.args as { parameters: Record<string, string> };
+    expect(created.parameters).toEqual({ SubnetId: "subnet-00000000known-after-apply" });
+    const entries = planned.changeSet!.entries;
+    expect(entries.find((e) => e.address === "Eni")?.attributes).toEqual([
+      { path: "Description" },
+      { path: "SubnetId", unknown: true },
+    ]);
+    // A create names no properties; the template says which one reads the parameter.
+    expect(entries.find((e) => e.address === "Q")?.attributes).toEqual([{ path: "QueueName", unknown: true }]);
+    expect(planned.changeSet!.member.holes).toEqual([]);
+    expect(methods(mock)).toEqual(["createChangeSet", "deleteChangeSet"]);
+    expect(planned.artifact).toMatchObject({ kind: "cfn-deploy-shape" });
+    // The preview reports its shape to core, unknown where a placeholder drives it (#4419).
+    expect(planned.shape).toMatchObject({ member: "net", unknownInputs: ["vpc"] });
+    expect(planned.shape!.entries.find((e) => e.logicalId === "Eni")).toMatchObject({ action: "update", replacement: "false", properties: ["Description", "SubnetId"], unknown: ["SubnetId"] });
+    expect(planned.shape!.entries.find((e) => e.logicalId === "Q")).toMatchObject({ action: "create", unknown: ["QueueName"] });
+  });
+
+  it("a previewed member still says the outputs that do not read an unknown input (#4419)", async () => {
+    writeFileSync(
+      template,
+      JSON.stringify({
+        Parameters: { SubnetId: { Type: "AWS::EC2::Subnet::Id" }, Port: { Type: "String" } },
+        Resources: { Eni: { Type: "AWS::EC2::NetworkInterface", Properties: { SubnetId: { Ref: "SubnetId" } } } },
+        Outputs: { Port: { Value: { Ref: "Port" } }, Fixed: { Value: "8080" }, Id: { Value: { Ref: "SubnetId" } } },
+      }),
+    );
+    const mock = createMockCloudExecutor({ stacks: { net: { outputs: { Port: "1", Fixed: "1", Id: "x" }, changes: [{ ...eni, action: "Add" as const, details: [] }] } } });
+    const planned = await createCfnDeployCapability(mock.executor).plan!({ ...ctx, unresolvedInputs: ["vpc"] }, { stack: "net", template, inputs: { SubnetId: undefined as never, Port: "8080" } });
+    expect(planned.outputs).toEqual({ known: { Fixed: "8080", Port: "8080" }, unknown: ["Id"] });
+  });
+
+  it("a conditional replacement in the real change set is read as conditional", async () => {
+    const mock = createMockCloudExecutor({ stacks: { net: { changes: [{ ...eni, replacementMode: "Conditional" as never }] } } });
+    const planned = await createCfnDeployCapability(mock.executor).plan!(ctx, { stack: "net", template, inputs: { SubnetId: "subnet-1" } });
+    expect(planned.shape!.entries[0]).toMatchObject({ logicalId: "Eni", replacement: "conditional" });
+  });
+
+  it("falls back to a hole when CloudFormation refuses the stand-in", async () => {
+    const mock = createMockCloudExecutor({ stacks: { net: { changes: [] } } });
+    const real = mock.executor.cloudformation.createChangeSet;
+    mock.executor.cloudformation.createChangeSet = async () => {
+      throw new Error("Parameter validation failed: parameter value subnet-00000000known-after-apply for parameter name SubnetId does not exist");
+    };
+    void real;
+    const planned = await createCfnDeployCapability(mock.executor).plan!(ctx, input());
+    expect(planned.artifact).toBeUndefined();
+    expect(planned.changeSet!.member.holes[0].reason).toMatch(/no preview: CloudFormation refused .*does not exist/);
+  });
+
+  async function previewThenRun(previewed: ReturnType<typeof withDriver>[], real: Array<typeof eni | typeof q | ReturnType<typeof withDriver>>) {
+    const mock = createMockCloudExecutor({ stacks: { net: { changes: previewed } } });
+    const capability = createCfnDeployCapability(mock.executor);
+    const planned = await capability.plan!(ctx, input());
+    mock.setStack("net", { changes: real });
+    const result = await capability.run({ ...ctx, plans: { net: planned.artifact } }, { stack: "net", template, inputs: { SubnetId: "subnet-1" } }).catch((e: unknown) => e);
+    return { mock, result };
+  }
+
+  it("executes when the real change matches the preview", async () => {
+    const { mock, result } = await previewThenRun([withDriver("SubnetId")], [withDriver("SubnetId")]);
+    expect(result).toMatchObject({ stackStatus: expect.any(String) });
+    expect(methods(mock)).toContain("executeChangeSet");
+  });
+
+  it("executes when an unknown-driven property drops out because the real value equals the current one", async () => {
+    const { mock, result } = await previewThenRun([withDriver("SubnetId")], [{ ...eni, details: ["Description"] }]);
+    expect(result).toMatchObject({ stackStatus: expect.any(String) });
+    expect(methods(mock)).toContain("executeChangeSet");
+  });
+
+  it("refuses, executing nothing, when the real change adds a resource", async () => {
+    const { mock, result } = await previewThenRun([withDriver("SubnetId")], [withDriver("SubnetId"), q]);
+    expect(result).toBeInstanceOf(PlanShapeMovedError);
+    expect((result as Error).message).toContain("net now plans to create Q, which the first plan did not");
+    expect((result as { planMoved?: boolean }).planMoved).toBe(true);
+    expect(methods(mock)).not.toContain("executeChangeSet");
+    expect(methods(mock).at(-1)).toBe("deleteChangeSet");
+  });
+
+  it("refuses when a property no unknown input drives stops changing", async () => {
+    const { mock, result } = await previewThenRun([withDriver("SubnetId")], [{ ...eni, details: ["SubnetId"] }]);
+    expect(result).toBeInstanceOf(PlanShapeMovedError);
+    expect((result as Error).message).toContain("no longer changes Description on Eni");
+    expect(methods(mock)).not.toContain("executeChangeSet");
+  });
+
+  it("refuses when the real change replaces and the preview did not", async () => {
+    const { result } = await previewThenRun([withDriver("SubnetId")], [{ ...withDriver("SubnetId"), replacementMode: "Conditional" as never }]);
+    expect(result).toBeInstanceOf(PlanShapeMovedError);
+    expect((result as Error).message).toContain("may now replace Eni, which the first plan did not show");
+  });
+});
+
+describe("pr-apply through AWS and core together: a previewed member in a round (#4422, #4423)", () => {
+  const queueAdd = { action: "Add" as const, logicalResourceId: "clusterAQueue", resourceType: "AWS::SQS::Queue", replacement: false };
+  const extraAdd = { action: "Add" as const, logicalResourceId: "Extra", resourceType: "AWS::SNS::Topic", replacement: false };
+  const approvedFirst = { status: "approved" as const, approvedBy: ["github:rev"] };
+
+  beforeEach(() => {
+    writeFileSync(
+      template,
+      JSON.stringify({
+        Parameters: { TopicArn: { Type: "String" } },
+        Resources: { Topic: { Type: "AWS::SNS::Topic" }, clusterAQueue: { Type: "AWS::SQS::Queue", Properties: { QueueName: { "Fn::Sub": "q-${TopicArn}" } } } },
+      }),
+    );
+  });
+
+  const components = (): DriverComponent[] => [
+    { name: "network", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", stack: "network", template }] }] },
+    {
+      name: "cluster-a",
+      dependsOn: ["network"],
+      deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", stack: "cluster-a", template, inputs: { TopicArn: { stackOutput: { stack: "network", name: "TopicArn" } } } }] }],
+    },
+  ];
+
+  async function planned(stacks: Record<string, FakeStackConfig>) {
+    const mock = createMockCloudExecutor({ stacks });
+    const registry = new CapabilityRegistry();
+    registry.register(createCfnDeployCapability(mock.executor));
+    const all = components();
+    const plan = planFanOut({ components: all, changed: ["network"] });
+    const set = await planPrSet({ components: all, plan, registry, env: "local" });
+    return { mock, registry, all, plan, set };
+  }
+
+  const stacks = (): Record<string, FakeStackConfig> => ({
+    network: { outputs: { TopicArn: "arn:topic" }, changes: [{ action: "Add", logicalResourceId: "Topic", resourceType: "AWS::SNS::Topic", replacement: false }] },
+    "cluster-a": { changes: [queueAdd] },
+  });
+  const executed = (mock: ReturnType<typeof createMockCloudExecutor>) =>
+    mock.calls.filter((c) => c.method === "executeChangeSet").map((c) => (c.args as { stackName: string }).stackName);
+
+  it("the real change set has the previewed shape: the first approval covers the round, nothing asks again, and both stacks are executed", async () => {
+    const { mock, registry, all, plan, set } = await planned(stacks());
+    expect(set.shapes?.["cluster-a"]).toMatchObject({ member: "cluster-a" });
+    let asked = 0;
+    const applied = await applyPrSet({
+      components: all,
+      plan,
+      registry,
+      env: "local",
+      set,
+      approval: approvedFirst,
+      decideRound: async () => {
+        asked++;
+        return { satisfied: false, approval: { status: "pending" } };
+      },
+    });
+    expect(asked).toBe(0);
+    expect(applied.status).toBe("applied");
+    expect(executed(mock)).toEqual(["network", "cluster-a"]);
+    expect(applied.rounds?.[0]).toMatchObject({ round: 2, gate: "pr-apply-round-2", status: "applied", covered: { digest: set.doc.digest, filledInputs: ["network.TopicArn"] } });
+  });
+
+  it("a real change set with a resource the preview did not show is not executed: the member waits at pr-apply-round-2, naming the reason and the new digest", async () => {
+    const { mock, registry, all, plan, set } = await planned(stacks());
+    mock.setStack("cluster-a", { changes: [queueAdd, extraAdd] });
+    const seen: Array<{ gate: string; notCovered?: string; digest: string }> = [];
+    const applied = await applyPrSet({
+      components: all,
+      plan,
+      registry,
+      env: "local",
+      set,
+      approval: approvedFirst,
+      decideRound: async ({ gate, notCovered, set: round }) => {
+        seen.push({ gate, ...(notCovered ? { notCovered } : {}), digest: round.doc.digest });
+        return { satisfied: false, approval: { status: "pending" } };
+      },
+    });
+    expect(applied.status).toBe("waiting");
+    expect(executed(mock)).toEqual(["network"]);
+    expect(seen).toHaveLength(1);
+    expect(seen[0]).toMatchObject({ gate: "pr-apply-round-2", notCovered: "cluster-a now plans to create Extra, which the first plan did not" });
+    expect(applied.rounds?.[0]).toMatchObject({ round: 2, gate: "pr-apply-round-2", status: "waiting", digest: seen[0]!.digest, notCovered: seen[0]!.notCovered });
+    expect(applied.rounds?.[0]?.digest).not.toBe(set.doc.digest);
+    expect(applied.members.find((m) => m.member === "cluster-a")).toMatchObject({ status: "waiting", round: 2 });
+  });
+
+  it("a failure part way leaves what applied, applied, and the report says which member failed", async () => {
+    const { mock, registry, all, plan, set } = await planned(stacks());
+    const run = mock.executor.cloudformation.waitForStack;
+    mock.executor.cloudformation.waitForStack = async (name: string, ...rest: never[]) => {
+      if (name === "cluster-a") throw new Error("cluster-a: CREATE_FAILED");
+      return (run as (n: string) => ReturnType<typeof run>)(name, ...(rest as []));
+    };
+    const applied = await applyPrSet({ components: all, plan, registry, env: "local", set, approval: approvedFirst, decideRound: async () => ({ satisfied: false, approval: { status: "pending" } }) });
+    expect(applied.status).toBe("failed");
+    expect(applied.members.map((m) => [m.member, m.status])).toEqual([["cluster-a", "failed"], ["network", "applied"]]);
+  });
+});
+
+describe("the preview's digest and its cleanup (#4423)", () => {
+  const eni = { action: "Modify" as const, logicalResourceId: "Eni", resourceType: "AWS::EC2::NetworkInterface", replacement: false, replacementMode: "False" as const };
+  const driven = (property: string) => ({
+    ...eni,
+    details: [property],
+    drivers: [{ property, changeSource: "ParameterReference", causingEntity: "SubnetId" }],
+  });
+  const input = (): CfnDeployInput => ({ stack: "net", template, inputs: { SubnetId: undefined as never } });
+
+  beforeEach(() => {
+    writeFileSync(
+      template,
+      JSON.stringify({
+        Parameters: { SubnetId: { Type: "AWS::EC2::Subnet::Id" } },
+        Resources: { Eni: { Type: "AWS::EC2::NetworkInterface", Properties: { SubnetId: { Ref: "SubnetId" }, Description: "d" } } },
+      }),
+    );
+  });
+
+  const preview = async (config: FakeStackConfig, unresolved = ["vpc"]) => {
+    const mock = createMockCloudExecutor({ stacks: { net: config } });
+    const out = await createCfnDeployCapability(mock.executor).plan!({ ...ctx, unresolvedInputs: unresolved }, input());
+    return { mock, out };
+  };
+
+  it("the same inputs and template give the same digest across two plans; another preview shape gives another", async () => {
+    const a = await preview({ changes: [driven("SubnetId")] });
+    const b = await preview({ changes: [driven("SubnetId")] });
+    expect(a.out.artifact).toMatchObject({ kind: "cfn-deploy-shape" });
+    expect(b.out.planDigest).toBe(a.out.planDigest);
+    expect(b.out.changeSet!.member.planDigest).toBe(a.out.planDigest);
+    // The preview's digest is in it: a preview that shows another change set is another plan.
+    const other = await preview({ changes: [{ ...driven("SubnetId"), replacement: true, replacementMode: "True" as never }] });
+    expect(other.out.planDigest).not.toBe(a.out.planDigest);
+    // A member left a hole has the digest of its inputs alone.
+    const hole = await createCfnDeployCapability(createMockCloudExecutor({ stacks: { net: {} } }).executor).plan!({ ...ctx, unresolvedInputs: ["up"] }, { stack: "net", template });
+    expect(hole.planDigest).not.toBe(a.out.planDigest);
+  });
+
+  it("a preview that CloudFormation fails after creating the change set deletes the change set and the empty stack, and stays a hole", async () => {
+    const mock = createMockCloudExecutor({ stacks: { net: { missing: true, changes: [driven("SubnetId")] } } });
+    const create = mock.executor.cloudformation.createChangeSet;
+    mock.executor.cloudformation.createChangeSet = async (args) => ({ ...(await create(args)), status: "FAILED", statusReason: "Parameter value for SubnetId is not valid", changes: [] });
+    const out = await createCfnDeployCapability(mock.executor).plan!({ ...ctx, unresolvedInputs: ["vpc"] }, input());
+    expect(out.artifact).toBeUndefined();
+    expect(out.changeSet!.member.holes[0]!.reason).toMatch(/no preview: CloudFormation could not create the change set with stand-in values: Parameter value for SubnetId is not valid/);
+    expect(methods(mock)).toEqual(["createChangeSet", "deleteChangeSet", "deleteStackShell"]);
+  });
+
+  it("a preview that throws while reading the change set still deletes the change set and the empty stack", async () => {
+    const mock = createMockCloudExecutor({ stacks: { net: { missing: true, changes: [driven("SubnetId")] } } });
+    const create = mock.executor.cloudformation.createChangeSet;
+    mock.executor.cloudformation.createChangeSet = async (args) => {
+      const cs = await create(args);
+      return { ...cs, get changes(): never { throw new Error("could not read the change set"); } } as never;
+    };
+    await expect(createCfnDeployCapability(mock.executor).plan!({ ...ctx, unresolvedInputs: ["vpc"] }, input())).rejects.toThrow(/could not read the change set/);
+    expect(methods(mock)).toEqual(["createChangeSet", "deleteChangeSet", "deleteStackShell"]);
+  });
+});

package/src/components/cloud-executor.ts

@@ -54,6 +54,13 @@ export interface CfnChange {
   replacementMode?: "True" | "False" | "Conditional";
   /** Resource-specific detail, when the executor's changeset backend provides it (e.g. property/scope). */
   details?: string[];
+  /**
+   * What CloudFormation says drives each property change, when it says: the
+   * property, `ChangeSource` and `CausingEntity`. A property driven by a
+   * parameter reads `ParameterReference` with the parameter's name, which is
+   * how a preview marks it known after apply (#4419).
+   */
+  drivers?: Array<{ property: string; changeSource?: string; causingEntity?: string }>;
   /**
    * The logical ids of the nested stacks this change sits in, outermost
    * first (#3997). Absent for a change to the stack's own resources. Set when
@@ -461,7 +468,7 @@ export interface DescribedCfnChangeSet {
       LogicalResourceId: string;
       ResourceType: string;
       Replacement?: string;
-      Details?: Array<{ Target?: { Name?: string } }>;
+      Details?: Array<{ Target?: { Name?: string }; ChangeSource?: string | null; CausingEntity?: string | null }>;
       /** Set on an `AWS::CloudFormation::Stack` change when the change set includes nested stacks: the nested change set's ARN. */
       ChangeSetId?: string | null;
     };
@@ -498,6 +505,15 @@ export async function readCfnChanges(
       replacement: rc.Replacement === "True",
       ...(rc.Replacement === "True" || rc.Replacement === "False" || rc.Replacement === "Conditional" ? { replacementMode: rc.Replacement } : {}),
       details: rc.Details?.map((d) => d.Target?.Name).filter((x): x is string => !!x),
+      ...(rc.Details?.some((d) => d.Target?.Name && (d.ChangeSource || d.CausingEntity))
+        ? {
+            drivers: rc.Details.filter((d) => d.Target?.Name).map((d) => ({
+              property: d.Target!.Name!,
+              ...(d.ChangeSource ? { changeSource: d.ChangeSource } : {}),
+              ...(d.CausingEntity ? { causingEntity: d.CausingEntity } : {}),
+            })),
+          }
+        : {}),
       ...(nestedStack.length > 0 ? { nestedStack } : {}),
     });
     if (rc.ResourceType === "AWS::CloudFormation::Stack" && rc.ChangeSetId) {