@intentius/chant-lexicon-terraform 0.124.52 → 0.124.54

package/src/components/placeholder-preview.ts

@@ -0,0 +1,257 @@
+/**
+ * Previewing a root whose `vars` read outputs not known yet (#4463).
+ *
+ * terraform takes no unknown variable, so such a root used to get no plan at
+ * pull-request time, only a hole. Now it is planned with a stand-in for each
+ * variable that holds no value yet, typed from the root's own `variable`
+ * block ({@link terraformPlaceholder}). Every attribute and output the
+ * stand-ins drive is then marked unknown after apply in the plan JSON
+ * ({@link markPlaceholderDriven}) before the change set, the shape and the
+ * planned outputs are read from it, so no stand-in value reaches the note or
+ * the digest. The member's change-set part lists the variables under
+ * `placeholders`.
+ *
+ * What a stand-in drives is read from the plan's own `configuration`: an
+ * attribute whose expression references `var.<name>`, through module inputs
+ * too, plus any string attribute or output whose planned value carries
+ * {@link TERRAFORM_UNKNOWN_MARK}. A value that reaches an attribute another
+ * way (a number through a `local`) is not marked; the fresh plan at apply
+ * then differs from the preview and asks for an approval of its own, which
+ * costs a round and never applies a change nobody approved.
+ *
+ * A preview is not possible when a variable that holds the unknown read is
+ * not declared, when the unknown sits inside a larger value, when a `count`
+ * or `for_each` reads a stand-in (the preview would show a count the real
+ * value does not have), or when the placeholder plan fails, say on a
+ * `validation` block. The member then stays a hole, as before, and the
+ * hole's reason says why (the 2026-10-25 ruling on #4463).
+ */
+
+import type { ChangeSetHole } from "@intentius/chant/change-set";
+
+/** The marker every string stand-in carries, so a reader can tell it from a real value. */
+export const TERRAFORM_UNKNOWN_MARK = "known-after-apply";
+
+type Json = Record<string, unknown>;
+const isObject = (v: unknown): v is Json => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/** Split `text` on `sep` where no bracket is open. */
+function splitTop(text: string, sep: string | RegExp): string[] {
+  const out: string[] = [];
+  let depth = 0;
+  let quoted = false;
+  let start = 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]!;
+    if (c === '"' && text[i - 1] !== "\\") quoted = !quoted;
+    if (quoted) continue;
+    if (c === "(" || c === "[" || c === "{") depth++;
+    else if (c === ")" || c === "]" || c === "}") depth--;
+    else if (depth === 0 && (typeof sep === "string" ? c === sep : sep.test(c))) {
+      out.push(text.slice(start, i));
+      start = i + 1;
+    }
+  }
+  out.push(text.slice(start));
+  return out.map((s) => s.trim()).filter((s) => s !== "");
+}
+
+/** `name(inner)` read off a type expression, or `undefined` when it is not one. */
+function call(type: string, name: string): string | undefined {
+  const m = type.match(new RegExp(`^${name}\\s*\\(([\\s\\S]*)\\)$`));
+  return m ? m[1]!.trim() : undefined;
+}
+
+/**
+ * A stand-in for a variable of `type`, a Terraform type expression as the
+ * `variable` block writes it (`string`, `list(string)`, `object({ id = string })`).
+ *
+ * - `string`, `any` or no type: {@link TERRAFORM_UNKNOWN_MARK}.
+ * - `number`: 0. `bool`: false.
+ * - `list(...)`, `set(...)`: an empty list. `map(...)`: an empty map.
+ * - `tuple([a, b])`: one stand-in per element type.
+ * - `object({ a = t })`: one stand-in per attribute, `optional(t)` read as `t`.
+ *
+ * An empty collection plans no element, so a resource that iterates one
+ * plans none; the fresh plan at apply then asks for its own approval.
+ */
+export function terraformPlaceholder(type: string | undefined): unknown {
+  const t = (type ?? "").trim().replace(/^\$\{([\s\S]*)\}$/, "$1").trim();
+  if (t === "" || t === "any" || t === "string") return TERRAFORM_UNKNOWN_MARK;
+  if (t === "number") return 0;
+  if (t === "bool") return false;
+  const optional = call(t, "optional");
+  if (optional !== undefined) return terraformPlaceholder(splitTop(optional, ",")[0]);
+  if (call(t, "list") !== undefined || call(t, "set") !== undefined) return [];
+  if (call(t, "map") !== undefined) return {};
+  const tuple = call(t, "tuple");
+  if (tuple !== undefined) {
+    const inner = tuple.replace(/^\[([\s\S]*)\]$/, "$1");
+    return splitTop(inner, ",").map((e) => terraformPlaceholder(e));
+  }
+  const object = call(t, "object");
+  if (object !== undefined) {
+    const inner = object.replace(/^\{([\s\S]*)\}$/, "$1");
+    const out: Record<string, unknown> = {};
+    for (const attr of splitTop(inner, /[,\n]/)) {
+      const at = attr.indexOf("=");
+      if (at < 0) continue;
+      const name = attr.slice(0, at).trim().replace(/^"(.*)"$/, "$1");
+      out[name] = terraformPlaceholder(attr.slice(at + 1));
+    }
+    return out;
+  }
+  return TERRAFORM_UNKNOWN_MARK;
+}
+
+const containsUndefined = (v: unknown): boolean =>
+  v === undefined || (Array.isArray(v) ? v.some(containsUndefined) : isObject(v) ? Object.values(v).some(containsUndefined) : false);
+
+/** The variables a preview gives stand-ins, and the `vars` it plans with. */
+export interface PlaceholderVars {
+  /** The variable names given a stand-in, sorted. */
+  placeholders: string[];
+  /** The step's `vars` with each of them replaced by its stand-in. */
+  vars: Record<string, unknown>;
+}
+
+/**
+ * The stand-ins for a step's `vars` (#4463): each variable whose value is
+ * `undefined` (a `stackOutput()` read with nothing to read yet) gets
+ * {@link terraformPlaceholder} of its declared type. Returns why instead when
+ * no preview can be made: no variable holds the unknown read, one that does
+ * is not declared in the root, or the unknown sits inside a larger value.
+ */
+export function placeholderVars(vars: Record<string, unknown> | undefined, declared: ReadonlyMap<string, { type?: string }>): PlaceholderVars | string {
+  const given = vars ?? {};
+  const placeholders: string[] = [];
+  const out: Record<string, unknown> = {};
+  for (const [name, value] of Object.entries(given)) {
+    if (value === undefined) {
+      const decl = declared.get(name);
+      if (!decl) return `var.${name} holds the unknown read and the root declares no variable "${name}" to type a stand-in from`;
+      placeholders.push(name);
+      out[name] = terraformPlaceholder(decl.type);
+    } else if (containsUndefined(value)) {
+      return `the unknown read sits inside var.${name}, which a stand-in cannot fill in part`;
+    } else out[name] = value;
+  }
+  if (placeholders.length === 0) return "no variable of the step holds the unknown read";
+  return { placeholders: placeholders.sort(), vars: out };
+}
+
+/** Every `references` entry under an expression, at any depth (nested blocks are arrays of expression objects). */
+function referencesIn(expr: unknown, out: string[] = []): string[] {
+  if (Array.isArray(expr)) for (const e of expr) referencesIn(e, out);
+  else if (isObject(expr)) {
+    if (Array.isArray(expr.references)) for (const r of expr.references) if (typeof r === "string") out.push(r);
+    for (const [k, v] of Object.entries(expr)) if (k !== "references" && k !== "constant_value") referencesIn(v, out);
+  }
+  return out;
+}
+
+const readsVar = (expr: unknown, vars: ReadonlySet<string>): boolean =>
+  referencesIn(expr).some((r) => {
+    const m = r.match(/^var\.([^.[]+)/);
+    return m !== null && vars.has(m[1]!);
+  });
+
+/** What the stand-ins drive, from the plan's configuration. */
+interface Driven {
+  /** `<module path>|<mode>.<type>.<name>` to the top-level attributes a stand-in drives. */
+  attributes: Map<string, Set<string>>;
+  /** Root outputs whose expression reads a stand-in. */
+  outputs: Set<string>;
+  /** A `count` or `for_each` that reads a stand-in, by address: the preview cannot say how many. */
+  expansions: string[];
+}
+
+const resourceKey = (modulePath: string, mode: string, type: string, name: string): string => `${modulePath}|${mode === "data" ? "data." : ""}${type}.${name}`;
+
+function walkModule(mod: unknown, path: string, vars: ReadonlySet<string>, driven: Driven): void {
+  if (!isObject(mod) || vars.size === 0) return;
+  const at = (address: string) => (path ? `${path}.${address}` : address);
+  for (const r of Array.isArray(mod.resources) ? mod.resources : []) {
+    if (!isObject(r)) continue;
+    const mode = String(r.mode ?? "managed");
+    const address = String(r.address ?? `${r.type}.${r.name}`);
+    if (readsVar(r.count_expression, vars) || readsVar(r.for_each_expression, vars)) driven.expansions.push(at(address));
+    const exprs = isObject(r.expressions) ? r.expressions : {};
+    const attrs = new Set(Object.entries(exprs).filter(([, e]) => readsVar(e, vars)).map(([k]) => k));
+    if (attrs.size > 0) driven.attributes.set(resourceKey(path, mode, String(r.type), String(r.name)), attrs);
+  }
+  for (const [name, c] of Object.entries(isObject(mod.module_calls) ? mod.module_calls : {})) {
+    if (!isObject(c)) continue;
+    if (readsVar(c.count_expression, vars) || readsVar(c.for_each_expression, vars)) driven.expansions.push(at(`module.${name}`));
+    const exprs = isObject(c.expressions) ? c.expressions : {};
+    const inputs = new Set(Object.entries(exprs).filter(([, e]) => readsVar(e, vars)).map(([k]) => k));
+    walkModule(c.module, at(`module.${name}`), inputs, driven);
+  }
+  if (path === "") {
+    for (const [name, o] of Object.entries(isObject(mod.outputs) ? mod.outputs : {})) {
+      if (isObject(o) && readsVar(o.expression, vars)) driven.outputs.add(name);
+    }
+  }
+}
+
+const carriesMark = (v: unknown): boolean =>
+  typeof v === "string" ? v.includes(TERRAFORM_UNKNOWN_MARK) : Array.isArray(v) ? v.some(carriesMark) : isObject(v) ? Object.values(v).some(carriesMark) : false;
+
+/** A `resource_changes` item's key in {@link Driven.attributes}: its module path without instance keys. */
+function changeKey(rc: Json): string {
+  const modulePath = typeof rc.module_address === "string" ? rc.module_address.replace(/\[[^\]]*\]/g, "") : "";
+  return resourceKey(modulePath, String(rc.mode ?? "managed"), String(rc.type), String(rc.name));
+}
+
+/** What {@link markPlaceholderDriven} returns. */
+export type MarkedPlan = { plan: unknown } | { refused: string };
+
+/**
+ * `planJson` (`show -json` of the placeholder plan) with every attribute and
+ * root output the stand-ins for `placeholders` drive marked unknown after
+ * apply, their planned values dropped. Returns why instead when a `count` or
+ * `for_each` reads a stand-in. The input is not changed.
+ */
+export function markPlaceholderDriven(planJson: unknown, placeholders: readonly string[]): MarkedPlan {
+  const plan = structuredClone(isObject(planJson) ? planJson : {}) as Json;
+  const driven: Driven = { attributes: new Map(), outputs: new Set(), expansions: [] };
+  const config = isObject(plan.configuration) ? plan.configuration : {};
+  walkModule(config.root_module, "", new Set(placeholders), driven);
+  if (driven.expansions.length > 0) {
+    return { refused: `the count or for_each of ${[...new Set(driven.expansions)].sort().join(", ")} reads a stand-in, so the preview cannot say how many instances there are` };
+  }
+  for (const r of Array.isArray(plan.resource_changes) ? plan.resource_changes : []) {
+    if (!isObject(r) || !isObject(r.change)) continue;
+    const change = r.change;
+    const after = isObject(change.after) ? change.after : undefined;
+    const attrs = new Set(driven.attributes.get(changeKey(r)) ?? []);
+    for (const [k, v] of Object.entries(after ?? {})) if (carriesMark(v)) attrs.add(k);
+    if (attrs.size === 0) continue;
+    const afterUnknown = isObject(change.after_unknown) ? change.after_unknown : {};
+    for (const k of attrs) {
+      afterUnknown[k] = true;
+      if (after) delete after[k];
+    }
+    change.after_unknown = afterUnknown;
+  }
+  const outputChanges = isObject(plan.output_changes) ? plan.output_changes : {};
+  const plannedOutputs = isObject(plan.planned_values) && isObject(plan.planned_values.outputs) ? plan.planned_values.outputs : {};
+  for (const [name, o] of Object.entries(outputChanges)) if (isObject(o) && carriesMark(o.after)) driven.outputs.add(name);
+  for (const [name, o] of Object.entries(plannedOutputs)) if (isObject(o) && carriesMark(o.value)) driven.outputs.add(name);
+  for (const name of driven.outputs) {
+    const o = isObject(outputChanges[name]) ? (outputChanges[name] as Json) : (outputChanges[name] = {} as Json);
+    delete o.after;
+    o.after_unknown = true;
+    delete plannedOutputs[name];
+  }
+  return { plan };
+}
+
+/** The hole a root keeps when its preview is not possible: the old reason, and why there is no preview. */
+export function waitingHole(root: string, unresolved: readonly string[], why?: string): ChangeSetHole {
+  return {
+    address: root,
+    type: "terraform_root",
+    reason: `inputs from ${unresolved.join(", ")}; planned again once they apply${why ? `; no preview: ${why}` : ""}`,
+  };
+}

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

@@ -0,0 +1,363 @@
+/**
+ * Composed runs (#4447) through the pull-request loop over a chain of three
+ * real Terraform roots, with and without `terraform.compose`: `chant
+ * components pr-plan` on the pull request and `chant components pr-apply` on
+ * the merge, each talking to a fake GitHub, as in `pr-loop.tofu.test.ts`.
+ * Every case runs tofu or terraform several times, so they sit in the e2e
+ * project. Skipped when neither binary is on the PATH.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+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 { FakeGithub } from "@intentius/chant-test-utils/pr-loop-harness";
+import { terraformPlugin } from "../plugin";
+import { renderTerraformRoots } from "../hcl/roots";
+
+const REPO = join(import.meta.dirname, "..", "..", "..", "..");
+
+function which(bin: string): boolean {
+  try {
+    execFileSync(bin, ["version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+const BINARY = which("tofu") ? "tofu" : which("terraform") ? "terraform" : undefined;
+
+/**
+ * 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
+ * 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) };
+}
+
+const args = (overrides: Partial<ParsedArgs>): ParsedArgs => ({
+  command: "components",
+  path: ".",
+  format: "",
+  fix: false,
+  watch: false,
+  verbose: false,
+  help: false,
+  live: false,
+  env: "local",
+  noReleaseRecord: true,
+  ...overrides,
+});
+
+// ── Composed runs (#4447) ─────────────────────────────────────────────────
+//
+// Three roots in a chain: b reads a's id and c reads b's, through
+// `stackOutput()` in `vars`. With `terraform.compose.enabled` the pull
+// request plans them as one group (ws-107), so b and c are not holes, and the
+// merge applies the three in one apply with no round in between. Without the
+// setting the loop behaves as above: b is a hole and its round waits on an
+// approval of its own.
+
+const CHAIN: Record<string, string> = {
+  a: 'resource "terraform_data" "subnet" {\n  input = "a-v1"\n}\n\noutput "id" {\n  value = terraform_data.subnet.output\n}\n',
+  b: 'variable "a_id" {\n  type = string\n}\n\nresource "terraform_data" "link" {\n  input = "${var.a_id}/b"\n}\n\noutput "id" {\n  value = terraform_data.link.output\n}\n',
+  c: 'variable "b_id" {\n  type = string\n}\n\nresource "terraform_data" "edge" {\n  input = "${var.b_id}/c"\n}\n\noutput "id" {\n  value = terraform_data.edge.output\n}\n',
+};
+
+/** The chain's components; with `reader`, d, a shell step outside the group, writes c's id to `d.out`. */
+const chainComponents = (reader: boolean) => `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 a: Component = { name: "a", dependsOn: [], deploy: apply("a") };
+export const b: Component = { name: "b", dependsOn: ["a"], deploy: apply("b", { a_id: stackOutput("a", "id") }) };
+export const c: Component = { name: "c", dependsOn: ["b"], deploy: apply("c", { b_id: stackOutput("b", "id") }) };
+${
+  reader
+    ? `export const d: Component = {
+  name: "d",
+  dependsOn: ["c"],
+  deploy: [phase("Apply", [{ kind: "shell", cmd: "printenv C_ID > d.out", env: { C_ID: stackOutput("c", "id") }, reason: "reads c's applied id from outside the group" }])],
+};
+`
+    : ""
+}`;
+
+/** What a composed suite's tests reach. */
+interface ChainLoop {
+  dir: string;
+  github: FakeGithub;
+  report(stage: "plan" | "apply"): PrReport;
+  state(root: string): string;
+  git(...a: string[]): string;
+  /** A pull request that rewrites root a's input to `version`. */
+  open(pr: number, version: string): Promise<PrReport>;
+  /** Merge it and run pr-apply. */
+  merge(pr: number): Promise<number>;
+  /** Run pr-apply again from its resume record, as after a round's approval. */
+  again(): Promise<number>;
+  approve(pr: number, gate: string, digest: string): Promise<void>;
+  /** Lock files, kept states and composed-root files left in the checkout. */
+  leftovers(): string[];
+}
+
+/** Every path under `dir` (outside `node_modules` and `.git`) a composed run must not leave behind. */
+function leftoversIn(dir: string): string[] {
+  const out: string[] = [];
+  const walk = (at: string): void => {
+    for (const e of readdirSync(at, { withFileTypes: true })) {
+      if (e.name === "node_modules" || e.name === ".git") continue;
+      const path = join(at, e.name);
+      if (e.name === ".chant-compose" || e.name === "chant_compose.tf" || e.name.endsWith(".tflock") || e.name.endsWith(".chant-unwritten")) out.push(path.slice(dir.length + 1));
+      if (e.isDirectory() && e.name !== ".terraform") walk(path);
+    }
+  };
+  walk(dir);
+  return out.sort();
+}
+
+function chainSuite(title: string, opts: { compose: boolean; files?: Record<string, string>; reader?: boolean }, tests: (loop: ChainLoop) => void): void {
+  describe.skipIf(!BINARY)(`${title} (${BINARY ?? "terraform"})`, () => {
+    const loop = {} as ChainLoop;
+    let dir = "";
+    let cwd = "";
+    let mergedFrom = "";
+    const env = { ...process.env };
+    const github = new FakeGithub();
+    const RESUME = ".chant/pr-resume/pr-apply.json";
+    const ctx = (overrides: Partial<ParsedArgs>) => ({ args: args(overrides), plugins: [terraformPlugin], serializers: [terraformPlugin.serializer] });
+    let handlers: typeof import("@intentius/chant/cli/handlers/pr");
+    let recordGateApproval: typeof import("@intentius/chant/cli/handlers/operator").recordGateApproval;
+
+    beforeAll(async () => {
+      dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-pr-compose-")));
+      const git = (...a: string[]) => execFileSync("git", a, { cwd: dir, encoding: "utf8" }).trim();
+      const write = (path: string, text: string) => {
+        mkdirSync(dirname(join(dir, path)), { recursive: true });
+        writeFileSync(join(dir, path), text);
+      };
+      symlinkSync(join(REPO, "node_modules"), join(dir, "node_modules"));
+      for (const [name, text] of Object.entries(CHAIN)) write(`roots/${name}/main.tf`, text);
+      for (const [path, text] of Object.entries(opts.files ?? {})) write(path, text);
+      const terraform = {
+        binary: BINARY,
+        ...(opts.compose ? { compose: { enabled: true } } : {}),
+        roots: Object.fromEntries(Object.keys(CHAIN).map((r) => [r, { dir: `roots/${r}` }])),
+      };
+      write("chant.config.json", JSON.stringify({ lexicons: ["terraform"], terraform }, null, 2));
+      write("chain.component.ts", chainComponents(opts.reader === true));
+      write(".gitignore", "node_modules\n.terraform\n.terraform.lock.hcl\n*.tfstate*\nchant.tfplan\n.chant\nd.out\n");
+      git("init", "-q", "-b", "main");
+      git("config", "user.email", "ci@example.test");
+      git("config", "user.name", "ci");
+      git("add", "-A");
+      git("commit", "-qm", "three roots");
+
+      cwd = process.cwd();
+      process.chdir(dir);
+      Object.assign(process.env, {
+        GITHUB_REPOSITORY: "acme/infra",
+        GITHUB_TOKEN: "t0k",
+        GITHUB_API_URL: "https://api.github.com",
+        GITHUB_SERVER_URL: "https://github.com",
+        GITHUB_RUN_ID: "1",
+      });
+      vi.stubGlobal("fetch", github.fetch);
+      handlers = await import("@intentius/chant/cli/handlers/pr");
+      (await import("@intentius/chant/lifecycle/gate-change-set")).setGraphIdReader(estateGraphIds);
+      ({ recordGateApproval } = await import("@intentius/chant/cli/handlers/operator"));
+
+      // Every root applied once, root by root (a fan-out never composes), so each has state and outputs.
+      const { runComponentsFanOut } = await import("@intentius/chant/cli/handlers/fan-out");
+      write("all.json", JSON.stringify({ changed: ["a"] }));
+      expect(await runComponentsFanOut(ctx({ fromAffected: "all.json" }) as never)).toBe(0);
+      rmSync(join(dir, "all.json"));
+
+      Object.assign(loop, {
+        dir,
+        github,
+        git,
+        report: (stage: "plan" | "apply"): PrReport => JSON.parse(readFileSync(join(dir, ".chant", "pr", `pr-${stage}.json`), "utf8")),
+        state: (root: string) => readFileSync(join(dir, "roots", root, "terraform.tfstate"), "utf8"),
+        async open(pr: number, version: string) {
+          git("checkout", "-qb", `pr-${pr}`);
+          write("roots/a/main.tf", CHAIN.a!.replace("a-v1", version));
+          git("commit", "-qam", `a ${version}`);
+          expect(await handlers.runComponentsPrPlan(ctx({ base: "main", pr, forge: "github" }) as never)).toBe(0);
+          return loop.report("plan");
+        },
+        async merge(pr: number) {
+          git("checkout", "-q", "main");
+          mergedFrom = git("rev-parse", "HEAD");
+          git("merge", "-q", "--no-ff", `pr-${pr}`, "-m", `Merge pull request #${pr}`);
+          github.mergedBy[git("rev-parse", "HEAD")] = pr;
+          return handlers.runComponentsPrApply(ctx({ base: mergedFrom, forge: "github", requireReview: true, resume: RESUME }) as never);
+        },
+        again: () => handlers.runComponentsPrApply(ctx({ base: mergedFrom, forge: "github", requireReview: true, resume: RESUME }) as never),
+        async approve(pr: number, gate: string, digest: string) {
+          github.reviews[pr] = [{ user: { login: "alice" }, state: "APPROVED" }];
+          expect((await recordGateApproval(`pr-${pr}`, gate, { actor: "github:alice", plan: digest })).ok).toBe(true);
+        },
+        leftovers: () => leftoversIn(dir),
+      } satisfies ChainLoop);
+    }, 240_000);
+
+    afterAll(async () => {
+      (await import("@intentius/chant/lifecycle/gate-change-set")).setGraphIdReader(undefined);
+      vi.unstubAllGlobals();
+      if (cwd) process.chdir(cwd);
+      for (const key of Object.keys(process.env)) if (!(key in env)) delete process.env[key];
+      if (dir) rmSync(dir, { recursive: true, force: true });
+    });
+
+    tests(loop);
+  });
+}
+
+chainSuite("with terraform.compose, three roots plan and apply as one group", { compose: true }, (loop) => {
+  test("one plan: b's read of a's new id is no hole, one digest binds the three, and the plan leaves nothing behind", async () => {
+    const plan = await loop.open(1, "a-v2");
+
+    expect(plan.status).toBe("planned");
+    expect(plan.selection).toMatchObject({ changed: ["a"], dependents: ["b", "c"] });
+    // The group is one unit in a's wave; the waves it emptied stay, so wave numbers keep their meaning.
+    expect(plan.selection.waves.filter((w) => w.length > 0)).toEqual([["a", "b", "c"]]);
+    expect(plan.groups).toEqual([expect.objectContaining({ capability: "terraform-apply", components: ["a", "b", "c"], wave: 1 })]);
+    expect(plan.groups![0]!.digest).toEqual(expect.any(String));
+    expect(plan.fallbacks ?? []).toEqual([]);
+    for (const m of ["b", "c"]) {
+      const member = plan.changeSet.members.find((x) => x.member === m)!;
+      expect(member.holes).toEqual([]);
+      // Ruling 4: the reads the group's apply computes are marked, so the change set never passes as empty.
+      expect(member.group?.digest).toBe(plan.groups![0]!.digest);
+      expect(member.group?.reads).toEqual([m === "b" ? "a.id" : "b.id"]);
+    }
+    expect(plan.members.map((m) => [m.member, m.status])).toEqual([
+      ["a", "planned"],
+      ["b", "planned"],
+      ["c", "planned"],
+    ]);
+    expect(plan.changeSet.digest).toBe(plan.digest);
+    expect(plan.approval).toEqual({ status: "pending" });
+
+    // The plan waits on its approval: no lock is held, and the composed root and every rewritten file are gone.
+    expect(loop.leftovers()).toEqual([]);
+    expect(loop.git("status", "--porcelain")).toBe("");
+  }, 240_000);
+
+  test("one approval and one apply: pr-apply exits 0 and no round gate is asked", async () => {
+    const plan = loop.report("plan");
+    await loop.approve(1, "pr-apply", plan.digest);
+    expect(await loop.merge(1)).toBe(0);
+
+    const applied = loop.report("apply");
+    expect(applied.digest).toBe(plan.digest);
+    expect(applied.status).toBe("applied");
+    expect(applied.rounds ?? []).toEqual([]);
+    expect(applied.members.map((m) => [m.member, m.status, m.groupOutcome])).toEqual([
+      ["a", "applied", "applied"],
+      ["b", "applied", "applied"],
+      ["c", "applied", "applied"],
+    ]);
+    // a's new id reached b, and b's reached c, inside the one apply.
+    expect(loop.state("a")).toContain('"a-v2"');
+    expect(loop.state("b")).toContain('"a-v2/b"');
+    expect(loop.state("c")).toContain('"a-v2/b/c"');
+    const note = loop.github.comments.find((c) => c.pr === 1)!.body;
+    expect(note).not.toContain("pr-apply-round-2");
+    expect(loop.github.statuses.at(-1)).toMatchObject({ context: "chant/apply", state: "success", sha: applied.head });
+    expect(loop.leftovers()).toEqual([]);
+    expect(loop.git("status", "--porcelain")).toBe("");
+  }, 240_000);
+
+  test("a plan that changed after review is refused, nothing applies, and no lock or file is left", async () => {
+    const reviewed = await loop.open(2, "a-v3");
+    await loop.approve(2, "pr-apply", reviewed.digest);
+    // Pushed after the review.
+    writeFileSync(join(loop.dir, "roots/a/main.tf"), CHAIN.a!.replace("a-v1", "a-v4"));
+    loop.git("commit", "-qam", "a v4");
+
+    expect(await loop.merge(2)).toBe(3);
+    const refused = loop.report("apply");
+    expect(refused.status).toBe("refused");
+    expect(refused.refusal).toBe("plan-changed");
+    expect(loop.state("a")).toContain('"a-v2"');
+    expect(loop.state("c")).toContain('"a-v2/b/c"');
+    expect(loop.leftovers()).toEqual([]);
+    expect(loop.git("status", "--porcelain")).toBe("");
+  }, 240_000);
+});
+
+chainSuite("without terraform.compose, the same three roots plan as on main", { compose: false }, (loop) => {
+  test("b is a hole, the setting's fallback is recorded and not printed, and b's round waits on its own approval", async () => {
+    const plan = await loop.open(1, "a-v2");
+    expect(plan.groups ?? []).toEqual([]);
+    expect((plan.fallbacks ?? []).map((f) => [f.component, f.kind])).toEqual([
+      ["a", "off"],
+      ["b", "off"],
+      ["c", "off"],
+    ]);
+    expect(plan.changeSet.members.find((m) => m.member === "b")?.holes).toEqual([
+      { address: "b", type: "terraform_root", reason: "inputs from a; planned again once they apply" },
+    ]);
+    expect(plan.members.find((m) => m.member === "b")?.unknownInputs).toEqual(["a.id"]);
+    const note = loop.github.comments.find((c) => c.pr === 1)!.body;
+    expect(note).not.toContain("terraform.compose");
+
+    await loop.approve(1, "pr-apply", plan.digest);
+    expect(await loop.merge(1)).toBe(3);
+    const waiting = loop.report("apply");
+    expect(waiting.status).toBe("waiting");
+    expect(waiting.members.find((m) => m.member === "a")?.status).toBe("applied");
+    const round = waiting.rounds![0]!;
+    expect(round).toMatchObject({ round: 2, gate: "pr-apply-round-2", status: "waiting" });
+    expect(round.components).toContain("b");
+    expect(round.covered).toBeUndefined();
+    expect(loop.state("a")).toContain('"a-v2"');
+    expect(loop.state("b")).not.toContain("a-v2");
+  }, 240_000);
+});
+
+chainSuite(
+  "with terraform.compose, a root #4438 refuses falls back and the rest group (#4419 ruling 1)",
+  { compose: true, files: { "roots/c/paths.tf": 'locals {\n  here = path.root\n}\n' } },
+  (loop) => {
+    test("a and b group; the report's fallbacks name c with its kind, and c plans in its own wave", async () => {
+      const plan = await loop.open(1, "a-v2");
+      expect(plan.groups?.map((g) => g.components)).toEqual([["a", "b"]]);
+      expect((plan.fallbacks ?? []).map((f) => [f.component, f.capability, f.kind])).toEqual([["c", "terraform-apply", "path"]]);
+      expect(plan.fallbacks![0]!.reason).toContain("`c` uses `path.root` or `path.cwd`");
+      expect(plan.changeSet.members.find((m) => m.member === "b")?.holes ?? []).toHaveLength(0);
+      expect(plan.selection.waves).toEqual([["a", "b"], [], ["c"]]);
+      expect(loop.leftovers()).toEqual([]);
+    }, 240_000);
+  },
+);
+
+chainSuite("with terraform.compose, a component outside the group reads c", { compose: true, reader: true }, (loop) => {
+  test("d gets c's applied output", async () => {
+    const plan = await loop.open(1, "a-v2");
+    expect(plan.groups?.map((g) => g.components)).toEqual([["a", "b", "c"]]);
+    await loop.approve(1, "pr-apply", plan.digest);
+    let code = await loop.merge(1);
+    // d read c's id before c applied: a round plans it once the group applied, and waits on an approval unless the first covers it.
+    if (code === 3) {
+      const round = loop.report("apply").rounds!.find((r) => r.status === "waiting")!;
+      await loop.approve(1, round.gate, round.digest);
+      code = await loop.again();
+    }
+    expect(code).toBe(0);
+    expect(loop.report("apply").members.find((m) => m.component === "d")?.status).toBe("applied");
+    expect(readFileSync(join(loop.dir, "d.out"), "utf8").trim()).toBe("a-v2/b/c");
+  }, 240_000);
+});