@intentius/chant-lexicon-terraform 0.124.52 → 0.124.54

package/src/components/pr-loop.tofu.test.ts

@@ -11,8 +11,17 @@
  * The roots use `terraform_data`, which is built into `tofu` and `terraform`,
  * with local state, so nothing downloads a provider or reaches a cloud. The
  * estate is net -> a, b and a -> app, with dns on its own; a and b read net's
- * output and app reads a's, through `stackOutput()`. Skipped when neither
- * binary is on the PATH.
+ * output and app reads a's, through `stackOutput()`. It lives in
+ * `../__fixtures__/pr-loop`, whose README also gives chant#4463's recorded
+ * run over it. Skipped when neither binary is on the PATH.
+ *
+ * app is previewed with a placeholder for `var.subnet` (#4463). A pull
+ * request that makes a's id end in `-v2` stays within that preview, so one
+ * approval applies both roots. One that makes it end in `-wide` adds
+ * `terraform_data.wide[0]` to app's real plan through a count the preview
+ * does not follow, so app's round 2 waits on its own gate (#4487).
+ *
+ * Composed runs over three roots are `pr-loop-compose.tofu.e2e.test.ts`.
  */
 
 import { execFileSync } from "node:child_process";
@@ -22,7 +31,7 @@ import { dirname, join } from "node:path";
 import { afterAll, beforeAll, describe, expect, test, vi } from "vitest";
 import type { ParsedArgs } from "@intentius/chant/cli/registry";
 import type { PrReport } from "@intentius/chant/pr-loop";
-import { buildGraphIr } from "@intentius/chant/graph-ir";
+import { buildGraphIr, withInstanceNodes } from "@intentius/chant/graph-ir";
 import { terraformPlugin } from "../plugin";
 import { renderTerraformRoots } from "../hcl/roots";
 
@@ -38,40 +47,27 @@ function which(bin: string): boolean {
 }
 const BINARY = which("tofu") ? "tofu" : which("terraform") ? "terraform" : undefined;
 
-const ROOTS: Record<string, string> = {
-  net: 'resource "terraform_data" "vpc" {\n  input = "10.0.0.0/16"\n}\n\noutput "cidr" {\n  value = terraform_data.vpc.output\n}\n',
-  a: 'variable "cidr" {\n  type = string\n}\n\nresource "terraform_data" "subnet" {\n  input = "${var.cidr}/a-v1"\n}\n\noutput "id" {\n  value = terraform_data.subnet.output\n}\n',
-  b: 'variable "cidr" {\n  type = string\n}\n\nresource "terraform_data" "subnet" {\n  input = "${var.cidr}/b-v1"\n}\n',
-  app: 'variable "subnet" {\n  type = string\n}\n\nresource "terraform_data" "app" {\n  input = "app on ${var.subnet}"\n}\n',
-  dns: 'resource "terraform_data" "zone" {\n  input = "example.test"\n}\n',
-};
+/** The workspace, `../__fixtures__/pr-loop` (its README says what each pull request below exercises). */
+const FIXTURE = join(import.meta.dirname, "..", "__fixtures__", "pr-loop");
+const ROOT_NAMES = ["net", "a", "b", "app", "dns"];
+const ROOTS: Record<string, string> = Object.fromEntries(ROOT_NAMES.map((r) => [r, readFileSync(join(FIXTURE, "roots", r, "main.tf"), "utf8")]));
 
 // The source passes `chant lint`, since `chant graph --format ir`, which maps
 // the stored change set onto nodes (#4022), refuses source that does not.
 /**
  * The estate's graph node ids, read in process with the pair `chant graph
  * --format ir` runs for terraform roots (`renderTerraformRoots`, then
- * `buildGraphIr`), so pr-apply maps its stored change set without starting a
+ * `buildGraphIr` and `withInstanceNodes`), so pr-apply maps its stored change set without starting a
  * chant child process. `change-set-graph.e2e.test.ts` holds these ids equal
  * to the spawned `chant graph --format ir`'s.
  */
 async function estateGraphIds(projectRoot: string): Promise<{ ids: string[] }> {
   const config = JSON.parse(readFileSync(join(projectRoot, "chant.config.json"), "utf8")) as { terraform: { binary?: string; roots: Record<string, { dir: string }> } };
   const rendered = await renderTerraformRoots({ projectRoot, roots: config.terraform.roots, ...(config.terraform.binary ? { binary: config.terraform.binary } : {}) });
-  return { ids: buildGraphIr(rendered.entities).nodes.map((n) => n.id) };
+  return { ids: withInstanceNodes(buildGraphIr(rendered.entities), rendered.entities).nodes.map((n) => n.id) };
 }
 
-const COMPONENTS = `import { phase, stackOutput, type Component } from "@intentius/chant/components";
-
-const apply = (root: string, vars?: Record<string, unknown>) =>
-  [phase("Apply", [{ kind: "terraform-apply", root, noRollback: "test roots with local state", vars: vars ?? {} }])];
-
-export const net: Component = { name: "net", dependsOn: [], deploy: apply("net") };
-export const a: Component = { name: "a", dependsOn: ["net"], deploy: apply("a", { cidr: stackOutput("net", "cidr") }) };
-export const b: Component = { name: "b", dependsOn: ["net"], deploy: apply("b", { cidr: stackOutput("net", "cidr") }) };
-export const app: Component = { name: "app", dependsOn: ["a"], deploy: apply("app", { subnet: stackOutput("a", "id") }) };
-export const dns: Component = { name: "dns", dependsOn: [], deploy: apply("dns") };
-`;
+const COMPONENTS = readFileSync(join(FIXTURE, "estate.component.ts"), "utf8");
 
 /** GitHub as far as the loop uses it: comments, statuses, reviews and the merged pull request of a commit. */
 class FakeGithub {
@@ -215,14 +211,20 @@ describe.skipIf(!BINARY)(`the pull-request loop over five ${BINARY ?? "terraform
     expect(plan.status).toBe("planned");
     expect(plan.selection).toMatchObject({ changed: ["a"], dependents: ["app"], waves: [["a"], ["app"]] });
     // a's id is terraform_data's output, which tofu knows only after apply,
-    // so app is not planned against the id a has now (#3999): the note says
-    // the approval does not cover what app does with it.
+    // so app is not planned against the id a has now (#3999). It is previewed
+    // with a stand-in for var.subnet instead (#4463): its update is in the
+    // change set, and the note says the approval covers app's plan once a
+    // applies only while that plan does what the preview shows.
     expect(plan.members.map((m) => [m.member, m.counts.update, m.unknownInputs])).toEqual([
       ["a", 1, undefined],
-      ["app", 0, ["a.id"]],
+      ["app", 1, ["a.id"]],
     ]);
-    expect(plan.changeSet.members.find((m) => m.member === "app")?.holes).toEqual([
-      { address: "app", type: "terraform_root", reason: "inputs from a; planned again once they apply" },
+    const app = plan.changeSet.members.find((m) => m.member === "app");
+    expect(app?.holes).toEqual([]);
+    expect(app?.placeholders).toEqual(["var.subnet"]);
+    expect(plan.changeSet.entries.map((e) => [e.member, e.address, e.action])).toEqual([
+      ["a", "terraform_data.subnet", "update"],
+      ["app", "terraform_data.app", "update"],
     ]);
     expect(plan.plannedOutputs).toEqual({ a: [] });
     expect(plan.deployedOutputs).toEqual({ net: ["cidr"] });
@@ -233,6 +235,7 @@ describe.skipIf(!BINARY)(`the pull-request loop over five ${BINARY ?? "terraform
     expect(note.body.startsWith("<!-- chant-pr:local -->")).toBe(true);
     expect(note.body).toContain(`chant approve pr-1 pr-apply --plan ${plan.digest} --approver github:<your-login> --sign`);
     expect(note.body).toContain("Known only after apply: `app` reads `a.id`.");
+    expect(note.body).toContain("previewed with placeholders for `var.subnet`");
     expect(github.statuses.at(-1)).toMatchObject({ context: "chant/plan", state: "success", sha: plan.head });
   }, 240_000);
 
@@ -241,43 +244,29 @@ describe.skipIf(!BINARY)(`the pull-request loop over five ${BINARY ?? "terraform
     github.reviews[1] = [{ user: { login: "alice" }, state: "APPROVED" }];
     expect((await recordGateApproval("pr-1", "pr-apply", { actor: "github:alice", plan: plan.digest })).ok).toBe(true);
 
-    // a applies; app, planned now against the id a applied as, waits on its own gate.
-    expect(await merge(1)).toBe(3);
-    const waiting = report("apply");
-    expect(waiting.digest).toBe(plan.digest);
-    expect(waiting.status).toBe("waiting");
-    expect(waiting.members.map((m) => [m.member, m.status, m.round])).toEqual([
-      ["a", "applied", undefined],
-      ["app", "waiting", 2],
-    ]);
-    const round = waiting.rounds![0]!;
-    expect(round).toMatchObject({ round: 2, gate: "pr-apply-round-2", components: ["app"], status: "waiting", approval: { status: "pending" } });
-    expect(round.changeSet.entries.map((e) => [e.member, e.address, e.action])).toEqual([["app", "terraform_data.app", "update"]]);
-    expect(state("a")).toContain("10.0.0.0/16/a-v2");
-    expect(state("app")).not.toContain("a-v2");
-    expect(github.statuses.at(-1)).toMatchObject({ context: "chant/apply", state: "pending" });
-    expect(github.comments.find((c) => c.pr === 1)!.body).toContain(`chant approve pr-1 pr-apply-round-2 --plan ${round.digest}`);
-  }, 240_000);
-
-  test("once the reviewer approves the round's plan, the same apply carries on from its record and applies the dependent (#3999)", async () => {
-    const plan = report("plan");
-    const round = report("apply").rounds![0]!;
-    expect((await recordGateApproval("pr-1", "pr-apply-round-2", { actor: "github:alice", plan: round.digest })).ok).toBe(true);
-    expect(await handlers.runComponentsPrApply(ctx({ base: mergedFrom, forge: "github", requireReview: true, resume: RESUME }) as never)).toBe(0);
+    // a applies; app is planned again against the id a applied as. That plan
+    // does what the placeholder preview showed, with a.id filled in, so the
+    // first approval covers it and it applies in the same run (#4463).
+    expect(await merge(1)).toBe(0);
     const applied = report("apply");
     expect(applied.digest).toBe(plan.digest);
     expect(applied.status).toBe("applied");
     expect(applied.approval).toEqual({ status: "approved", approvedBy: ["github:alice"] });
-    expect(applied.resumed).toEqual({ applied: ["a"] });
     expect(applied.members.map((m) => [m.member, m.status, m.round])).toEqual([
       ["a", "applied", undefined],
       ["app", "applied", 2],
     ]);
-    expect(applied.rounds?.map((r) => [r.digest, r.status, r.approval.approvedBy])).toEqual([[round.digest, "applied", ["github:alice"]]]);
+    const round = applied.rounds![0]!;
+    expect(round).toMatchObject({ round: 2, gate: "pr-apply-round-2", components: ["app"], status: "applied" });
+    expect(round.covered).toEqual({ digest: plan.digest, filledInputs: ["a.id"] });
+    expect(round.notCovered).toBeUndefined();
+    expect(round.changeSet.entries.map((e) => [e.member, e.address, e.action])).toEqual([["app", "terraform_data.app", "update"]]);
+    expect(state("a")).toContain("10.0.0.0/16/a-v2");
     expect(state("app")).toContain("app on 10.0.0.0/16/a-v2");
-    // The same note, now with the apply's outcome.
     expect(github.comments.filter((c) => c.pr === 1)).toHaveLength(1);
-    expect(github.comments.find((c) => c.pr === 1)!.body).toContain("### chant apply for `local`");
+    const body = github.comments.find((c) => c.pr === 1)!.body;
+    expect(body).toContain("### chant apply for `local`");
+    expect(body).toContain(`covered by the approval of \`${plan.digest}\`, with \`a.id\` filled in, so it applied without a new approval`);
     expect(github.statuses.at(-1)).toMatchObject({ context: "chant/apply", state: "success", sha: applied.head });
   }, 240_000);
 
@@ -291,9 +280,10 @@ describe.skipIf(!BINARY)(`the pull-request loop over five ${BINARY ?? "terraform
     expect(stored.digest).toBe(applied.digest);
     expect(stored.graph).toEqual({ member: null, at: applied.head });
     // The plan's addresses, each on the block the terraform lexicon's graph names `<root>/<address>`.
-    // app's plan had a hole for a's id, and no entries.
+    // app's entry is its placeholder preview (#4463).
     expect(stored.entries.map((e) => [e.member, e.address, e.action, e.node])).toEqual([
       ["a", "terraform_data.subnet", "update", "a/terraform_data.subnet"],
+      ["app", "terraform_data.app", "update", "app/terraform_data.app"],
     ]);
     // And those are ids the estate's graph has.
     const graph = await estateGraphIds(dir);
@@ -325,4 +315,70 @@ describe.skipIf(!BINARY)(`the pull-request loop over five ${BINARY ?? "terraform
     const gate = gates.find((g) => g.component === "pr-2")!;
     expect(gate).toMatchObject({ state: "pending", planDigest: refused.digest, changeSet: refused.digest });
   }, 240_000);
+
+  // A round the first approval does not cover, over real tofu (#4487). app's
+  // `wide` count reads var.subnet through a local, so the preview's stand-in
+  // plans no wide instance; a's real id ends in `-wide`, so app's real plan
+  // creates one, which is more than the preview showed.
+  test("a dependent whose real plan exceeds its placeholder preview waits on its own round-2 gate (#4487)", async () => {
+    const plan = await openPullRequest(3, "a-wide");
+    expect(plan.status).toBe("planned");
+    expect(plan.members.map((m) => [m.member, m.counts.create, m.counts.update, m.unknownInputs])).toEqual([
+      ["a", 0, 1, undefined],
+      ["app", 0, 1, ["a.id"]],
+    ]);
+    expect(plan.changeSet.members.find((m) => m.member === "app")?.placeholders).toEqual(["var.subnet"]);
+    expect(plan.changeSet.entries.map((e) => [e.member, e.address, e.action])).toEqual([
+      ["a", "terraform_data.subnet", "update"],
+      ["app", "terraform_data.app", "update"],
+    ]);
+    github.reviews[3] = [{ user: { login: "alice" }, state: "APPROVED" }];
+    expect((await recordGateApproval("pr-3", "pr-apply", { actor: "github:alice", plan: plan.digest })).ok).toBe(true);
+
+    // a applies; app, planned now against the id a applied as, goes beyond the preview and waits on its own gate.
+    expect(await merge(3)).toBe(3);
+    const waiting = report("apply");
+    expect(waiting.digest).toBe(plan.digest);
+    expect(waiting.status).toBe("waiting");
+    expect(waiting.members.map((m) => [m.member, m.status, m.round])).toEqual([
+      ["a", "applied", undefined],
+      ["app", "waiting", 2],
+    ]);
+    const round = waiting.rounds![0]!;
+    expect(round).toMatchObject({ round: 2, gate: "pr-apply-round-2", components: ["app"], status: "waiting", approval: { status: "pending" } });
+    expect(round.changeSet.entries.map((e) => [e.member, e.address, e.action])).toEqual([
+      ["app", "terraform_data.app", "update"],
+      ["app", "terraform_data.wide[0]", "create"],
+    ]);
+    // The fresh plan's shape adds a resource the preview did not show, so the first approval does not cover it, and the reason names it.
+    expect(round.covered).toBeUndefined();
+    expect(round.notCovered).toContain("terraform_data.wide");
+    expect(state("a")).toContain("10.0.0.0/16/a-wide");
+    expect(state("app")).not.toContain("a-wide");
+    expect(github.statuses.at(-1)).toMatchObject({ context: "chant/apply", state: "pending" });
+    expect(github.comments.find((c) => c.pr === 3)!.body).toContain(`chant approve pr-3 pr-apply-round-2 --plan ${round.digest}`);
+  }, 240_000);
+
+  test("once the reviewer approves the round's plan, the same apply carries on from its record and applies the dependent (#4487)", async () => {
+    const plan = report("plan");
+    const round = report("apply").rounds![0]!;
+    expect((await recordGateApproval("pr-3", "pr-apply-round-2", { actor: "github:alice", plan: round.digest })).ok).toBe(true);
+    expect(await handlers.runComponentsPrApply(ctx({ base: mergedFrom, forge: "github", requireReview: true, resume: RESUME }) as never)).toBe(0);
+    const applied = report("apply");
+    expect(applied.digest).toBe(plan.digest);
+    expect(applied.status).toBe("applied");
+    expect(applied.approval).toEqual({ status: "approved", approvedBy: ["github:alice"] });
+    expect(applied.resumed).toEqual({ applied: ["a"] });
+    expect(applied.members.map((m) => [m.member, m.status, m.round])).toEqual([
+      ["a", "applied", undefined],
+      ["app", "applied", 2],
+    ]);
+    expect(applied.rounds?.map((r) => [r.digest, r.status, r.approval.approvedBy])).toEqual([[round.digest, "applied", ["github:alice"]]]);
+    expect(state("app")).toContain("app on 10.0.0.0/16/a-wide");
+    expect(state("app")).toContain("wide on 10.0.0.0/16/a-wide");
+    // The same note, now with the apply's outcome.
+    expect(github.comments.filter((c) => c.pr === 3)).toHaveLength(1);
+    expect(github.comments.find((c) => c.pr === 3)!.body).toContain("### chant apply for `local`");
+    expect(github.statuses.at(-1)).toMatchObject({ context: "chant/apply", state: "success", sha: applied.head });
+  }, 240_000);
 });

package/src/compose/apply-events.test.ts

@@ -0,0 +1,62 @@
+/**
+ * Each member's outcome of a composed apply (#4442), read from recorded
+ * `apply -json` output of a run of the three-module plan that failed in its
+ * second module (`../__fixtures__/compose/apply-failed-in-app.jsonl`).
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { composedApplyOutcomes, memberApply, readApplyEvents } from "./apply-events";
+
+const out = readFileSync(join(import.meta.dirname, "..", "__fixtures__", "compose", "apply-failed-in-app.jsonl"), "utf-8");
+const modules = ["net", "app", "edge"];
+
+describe("readApplyEvents", () => {
+  const ev = readApplyEvents(out, modules);
+
+  test("counts each module's started and completed changes and keeps its first error", () => {
+    expect(ev.started).toEqual(new Map([["net", 1], ["app", 1]]));
+    expect(ev.done).toEqual(new Map([["net", 1]]));
+    expect(ev.errored.get("app")).toBe("terraform_data.service: module.app.terraform_data.service: Creation errored after 0s");
+    expect(ev.errored.has("edge")).toBe(false);
+  });
+
+  test("an error no module's resource names is other", () => {
+    expect(ev.other).toEqual(["Provider produced inconsistent final plan: This is a bug in the provider."]);
+  });
+
+  test("a run that failed in the second module: applied, failed, not-started", () => {
+    expect(memberApply("net", 1, ev)).toEqual({ apply: "applied", done: 1 });
+    expect(memberApply("app", 2, ev)).toEqual({ apply: "failed", done: 0 });
+    expect(memberApply("edge", 1, ev)).toEqual({ apply: "not-started", done: 0 });
+  });
+
+  test("some changes done is partial; none planned is no-changes", () => {
+    expect(memberApply("net", 2, ev)).toEqual({ apply: "partial", done: 1 });
+    expect(memberApply("edge", 0, ev)).toEqual({ apply: "no-changes", done: 0 });
+  });
+
+  test("a diagnostic naming a module's resource is that module's error when no hook named one", () => {
+    const line = JSON.stringify({ type: "diagnostic", diagnostic: { severity: "error", summary: "Invalid input", detail: "first\nsecond", address: "module.edge.terraform_data.dns" } });
+    expect(readApplyEvents(line, modules).errored.get("edge")).toBe("terraform_data.dns: Error: Invalid input: first");
+  });
+
+  test("a module whose name starts with another's is its own", () => {
+    const line = JSON.stringify({ type: "apply_complete", hook: { resource: { addr: "module.app2.terraform_data.x" } } });
+    expect(readApplyEvents(line, ["app", "app2"]).done).toEqual(new Map([["app2", 1]]));
+  });
+});
+
+describe("composedApplyOutcomes", () => {
+  test("every member by component, the failed one with its error", () => {
+    const c = { order: ["net", "app", "edge"], modules: new Map(modules.map((m) => [m, m])) };
+    const { members, other } = composedApplyOutcomes(c, new Map([["net", 1], ["app", 2], ["edge", 1]]), out);
+    expect(members).toEqual({
+      net: { status: "applied", done: 1 },
+      app: { status: "failed", done: 0, error: "terraform_data.service: module.app.terraform_data.service: Creation errored after 0s" },
+      edge: { status: "not-started", done: 0 },
+    });
+    expect(other).toHaveLength(1);
+  });
+});

package/src/compose/apply-events.ts

@@ -0,0 +1,100 @@
+/**
+ * How each member's part of a composed apply ended (chant#4442, epic #4419),
+ * read from the binary's `apply -json` lines: `applied`, `partial`,
+ * `failed`, `not-started` or `no-changes`, core's `GroupMemberStatus`
+ * (ws-107).
+ *
+ * Lifted from terragucci's `packages/terragucci/src/compose.ts` at c493e0e
+ * (`readApplyEvents`, `memberApply`).
+ */
+
+import type { GroupMemberStatus } from "@intentius/chant/components/capability";
+import type { Composition } from "../compose";
+import { stripModule, topModule } from "./module-address";
+
+/** How one member's part of the apply ended. */
+export type MemberApply = GroupMemberStatus;
+
+/** What `apply -json` said of each module: the changes that completed, started, or errored, and the first error. */
+export interface ApplyEvents {
+  done: Map<string, number>;
+  started: Map<string, number>;
+  errored: Map<string, string>;
+  /** Errors no module's resource names. */
+  other: string[];
+}
+
+interface ApplyLine {
+  type?: string;
+  hook?: { resource?: { addr?: string }; error?: string };
+  diagnostic?: { severity?: string; summary?: string; detail?: string; address?: string };
+  "@message"?: string;
+}
+
+/** Read `apply -json` lines into each module's progress. A line that is not JSON is skipped. */
+export function readApplyEvents(out: string, modules: readonly string[]): ApplyEvents {
+  const ev: ApplyEvents = { done: new Map(), started: new Map(), errored: new Map(), other: [] };
+  const known = new Set(modules);
+  const moduleOf = (addr: string | undefined): string | undefined => {
+    const m = addr !== undefined ? topModule(addr) : undefined;
+    return m !== undefined && known.has(m) && addr !== `module.${m}` ? m : undefined;
+  };
+  const bump = (map: Map<string, number>, m: string) => map.set(m, (map.get(m) ?? 0) + 1);
+  for (const line of out.split("\n")) {
+    if (!line.startsWith("{")) continue;
+    let e: ApplyLine;
+    try {
+      e = JSON.parse(line) as ApplyLine;
+    } catch {
+      continue;
+    }
+    const addr = e.hook?.resource?.addr;
+    const m = moduleOf(addr);
+    if (e.type === "apply_start" && m) bump(ev.started, m);
+    else if (e.type === "apply_complete" && m) bump(ev.done, m);
+    else if (e.type === "apply_errored" && m && !ev.errored.has(m)) ev.errored.set(m, `${stripModule(addr!)}: ${e.hook?.error ?? e["@message"] ?? "errored"}`);
+    else if (e.type === "diagnostic" && e.diagnostic?.severity === "error") {
+      const dm = moduleOf(e.diagnostic.address);
+      const text = `${e.diagnostic.summary ?? "Error"}${e.diagnostic.detail ? `: ${e.diagnostic.detail.split("\n")[0]}` : ""}`;
+      if (dm && !ev.errored.has(dm)) ev.errored.set(dm, `${stripModule(e.diagnostic.address!)}: Error: ${text}`);
+      else if (!dm) ev.other.push(text);
+    }
+  }
+  return ev;
+}
+
+/** How a member's part of the apply ended, from its planned changes and the events. */
+export function memberApply(m: string, planned: number, ev: ApplyEvents): { apply: MemberApply; done: number } {
+  const done = Math.min(ev.done.get(m) ?? 0, planned);
+  if (planned === 0) return { apply: "no-changes", done: 0 };
+  if (done >= planned) return { apply: "applied", done };
+  if (done > 0) return { apply: "partial", done };
+  if (ev.errored.has(m) || (ev.started.get(m) ?? 0) > 0) return { apply: "failed", done };
+  return { apply: "not-started", done };
+}
+
+/** One member's outcome of a composed apply. */
+export interface MemberApplyOutcome {
+  status: MemberApply;
+  /** Its planned changes that completed. */
+  done: number;
+  /** The first error its part named. */
+  error?: string;
+}
+
+/**
+ * Every member's outcome of a composed apply, by component, from the
+ * `apply -json` output and each member's planned changes
+ * (`PlanCounts.changes` of its slice).
+ */
+export function composedApplyOutcomes(c: Pick<Composition, "order" | "modules">, planned: ReadonlyMap<string, number>, out: string): { members: Record<string, MemberApplyOutcome>; other: string[] } {
+  const ev = readApplyEvents(out, c.order.map((member) => c.modules.get(member)!));
+  const members: Record<string, MemberApplyOutcome> = {};
+  for (const member of c.order) {
+    const m = c.modules.get(member)!;
+    const { apply, done } = memberApply(m, planned.get(member) ?? 0, ev);
+    const error = ev.errored.get(m);
+    members[member] = { status: apply, done, ...(error && apply !== "applied" ? { error } : {}) };
+  }
+  return { members, other: ev.other };
+}

package/src/compose/estate.choudoufu.e2e.test.ts

@@ -0,0 +1,112 @@
+/**
+ * The composed run of estates (#4445) against a real choudoufu: three
+ * estates (network, app, edge), where app tags a bucket with the id of the
+ * subnet network creates in the same apply. One plan, one apply, and the
+ * values read after it from a post-apply plan's `prior_state`.
+ *
+ * Gated on a `choudoufu` of v0.31.0 or later on PATH (choudoufu#2059) and
+ * `CHOUDOUFU_EMULATOR_ENDPOINT`, like the other acceptance suites
+ * (`../__fixtures__/ACCEPTANCE.md`), and skipped with the reason named
+ * otherwise.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, describe, expect, it } from "vitest";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { compositionFor } from "../compose";
+import type { TerraformConfig } from "../config";
+import { isOlderVersion, MIN_CHOUDOUFU_ESTATES_VERSION, parseChoudoufuVersion } from "../op/activities/terraform";
+import { runBinary, type BinaryExec } from "../state/exec";
+import { EstateRun } from "./estate";
+
+const emulatorEndpoint = process.env.CHOUDOUFU_EMULATOR_ENDPOINT;
+
+function choudoufuVersion(): string | undefined {
+  try {
+    return parseChoudoufuVersion(execFileSync("choudoufu", ["version"], { encoding: "utf-8" })) ?? "dev";
+  } catch {
+    return undefined;
+  }
+}
+const version = choudoufuVersion();
+const missing =
+  version === undefined
+    ? "choudoufu is not on PATH"
+    : version !== "dev" && isOlderVersion(version, MIN_CHOUDOUFU_ESTATES_VERSION)
+      ? `choudoufu ${version} is older than v${MIN_CHOUDOUFU_ESTATES_VERSION}`
+      : !emulatorEndpoint
+        ? "CHOUDOUFU_EMULATOR_ENDPOINT is not set (bring up choudoufu's `just smoke` emulator stack and export it)"
+        : undefined;
+
+const made: string[] = [];
+afterAll(() => {
+  for (const d of made) rmSync(d, { recursive: true, force: true });
+});
+
+function env(): NodeJS.ProcessEnv {
+  return {
+    ...process.env,
+    AWS_ENDPOINT_URL: process.env.AWS_ENDPOINT_URL ?? emulatorEndpoint,
+    AWS_ACCESS_KEY_ID: process.env.AWS_ACCESS_KEY_ID ?? "choudoufu-emulator",
+    AWS_SECRET_ACCESS_KEY: process.env.AWS_SECRET_ACCESS_KEY ?? "choudoufu-emulator",
+    AWS_DEFAULT_REGION: process.env.AWS_DEFAULT_REGION ?? "us-east-1",
+    AWS_REGION: process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION ?? "us-east-1",
+  };
+}
+
+const PROVIDERS = 'terraform {\n  required_providers {\n    aws = {\n      source = "hashicorp/aws"\n    }\n  }\n}\n\nprovider "aws" {\n  region = "us-east-1"\n}\n\n';
+const live = (estate: string, body: string): string => `terraform {\n  live {\n    estate = "${estate}"\n  }\n}\n\n${PROVIDERS}${body}`;
+const tf = (name: string): DriverComponent => ({ name, deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: name }] }] });
+
+describe.skipIf(missing !== undefined)(`a composed run of three estates against a real choudoufu (#4445)${missing ? `: skipped, ${missing}` : ""}`, () => {
+  it("plans all three as one, applies once, and app receives the subnet id network created", async () => {
+    const id = `chant-4445-${Date.now().toString(36)}`;
+    const dir = mkdtempSync(join(tmpdir(), "chant-compose-estate-e2e-"));
+    made.push(dir);
+    const files: Record<string, string> = {
+      "roots/network/main.tf": live(
+        `${id}-network`,
+        'resource "aws_vpc" "main" {\n  cidr_block = "10.61.0.0/16"\n}\n\nresource "aws_subnet" "a" {\n  vpc_id     = aws_vpc.main.id\n  cidr_block = "10.61.1.0/24"\n}\n\noutput "subnet_id" {\n  value = aws_subnet.a.id\n}\n',
+      ),
+      "roots/app/main.tf": live(
+        `${id}-app`,
+        `data "terraform_estate_outputs" "network" {\n  estate = "${id}-network"\n  names  = ["subnet_id"]\n}\n\nresource "aws_s3_bucket" "app" {\n  bucket = "${id}-app"\n  tags = {\n    subnet = data.terraform_estate_outputs.network.values.subnet_id\n  }\n}\n\noutput "subnet_tag" {\n  value = aws_s3_bucket.app.tags["subnet"]\n}\n`,
+      ),
+      "roots/edge/main.tf": live(`${id}-edge`, `resource "aws_cloudwatch_log_group" "edge" {\n  name = "/${id}/edge"\n}\n`),
+    };
+    for (const [path, text] of Object.entries(files)) {
+      mkdirSync(dirname(join(dir, path)), { recursive: true });
+      writeFileSync(join(dir, path), text);
+    }
+    const terraform: TerraformConfig = { binary: "choudoufu", roots: { network: { dir: "roots/network" }, app: { dir: "roots/app" }, edge: { dir: "roots/edge" } }, compose: { enabled: true } };
+    const composition = compositionFor({ projectRoot: dir, components: [tf("network"), tf("app"), tf("edge")], terraform, env: env() });
+    expect(composition.estate).toBe(true);
+
+    const calls: string[][] = [];
+    const exec: BinaryExec = (binary, args, at, e, io) => {
+      calls.push(args);
+      return runBinary(binary, args, at, e, io);
+    };
+    const run = new EstateRun({ projectRoot: dir, composition, terraform, env: env(), exec });
+    try {
+      const p = await run.plan();
+      expect(p.fallback).toBeUndefined();
+      expect(p.error).toBeUndefined();
+      expect(p.members.app!.shape.unknownInputs).toEqual(["network.subnet_id"]);
+      const a = await run.apply();
+      expect(a.error).toBeUndefined();
+      expect(a.ok).toBe(true);
+      const subnet = a.members.network!.outputs!.subnet_id;
+      expect(subnet).toMatch(/^subnet-/);
+      expect(a.members.app!.outputs!.subnet_tag).toBe(subnet);
+      expect(calls.filter((c) => c[0] === "apply")).toHaveLength(1);
+      expect(calls.some((c) => c[0] === "state" || c[0] === "force-unlock")).toBe(false);
+      for (const c of calls.filter((x) => x[0] === "show")) expect(c[c.length - 1]).toMatch(/\.tfplan$/);
+    } finally {
+      await run.release();
+    }
+  }, 300_000);
+});