@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/src/components/capability-plugin.ts

@@ -22,7 +22,7 @@
  * system and refuses with exit 3 when its fresh plan differs (choudoufu
  * #878). Either refusal fails the step. choudoufu's refusal of a plan the
  * wave handed `run` throws {@link TerraformPlanMovedError}, so the command
- * that applied it exits 3 (#3997). terraform's and tofu's stale-plan error
+ * that applied it exits 4, the table's moved code (#3997, #4553). terraform's and tofu's stale-plan error
  * is not classified and exits 1.
  *
  * Run without a wave plan (`chant run --components`, or a fan-out with no
@@ -38,9 +38,27 @@
  * when both roots are in the change.
  *
  * A root whose `vars` read an output not known yet (`DeployContext.unresolvedInputs`)
- * is not planned: terraform takes no unknown variable. Its member gets a hole
- * naming the roots it waits on and no artifact, and the run that applies it
- * plans it once their outputs are known.
+ * cannot be planned as it stands: terraform takes no unknown variable. It is
+ * previewed instead (#4463, `./placeholder-preview.ts`): planned with a
+ * stand-in per variable that holds no value, typed from the root's
+ * `variable` block, with every attribute and output a stand-in drives marked
+ * unknown after apply. The member lists the variables under `placeholders`,
+ * and its artifact is the preview's shape, never a plan file. The apply plans
+ * the root again once the upstream applied, and core covers that round with
+ * the first approval when its shape is within the preview's; a `run` handed
+ * the shape itself holds the fresh plan to it. When no preview can be made
+ * (an undeclared variable, a `count` or `for_each` over a stand-in, a
+ * placeholder plan that fails) the member stays a hole naming the roots it
+ * waits on, and the hole's reason says why there is no preview.
+ *
+ * ## The plan's shape (#4436)
+ *
+ * `plan` also answers `shape`, `terraformPlanShape` over `show -json`: each
+ * resource the plan changes with its action, type, replacement, the
+ * attributes that differ and the ones unknown after apply. Core's
+ * `coveredRound` compares it with the shape of a later plan of the root. A
+ * previewed root's shape lists the upstreams it read as unknown inputs; a
+ * root that stays a hole has no plan, so no shape, and stays uncovered.
  *
  * ## choudoufu roots in a gated wave (#3459)
  *
@@ -63,13 +81,66 @@
  *
  * chant's waves stay the order. Each root is its own one-root set, so
  * choudoufu's wave over it is always wave 1.
+ *
+ * ## Composed runs (#4447)
+ *
+ * With `terraform.compose.enabled`, a group core forms of `terraform-apply`
+ * components that read each other (ws-107) plans as one plan and applies as
+ * one apply of a composed root, and a member's read of another member's new
+ * output is not a hole: the apply passes the value on. `groupReads`,
+ * `groupFallback`, `planGroup` and `runGroup` are in `./compose-group.ts`.
+ *
+ * ## A choudoufu member's outputs, for another member (#4455)
+ *
+ * The plugin also contributes {@link choudoufuOutputSource} to core's
+ * `member-outputs` verb (`CapabilityPlugin.engineOutputSources`), which is
+ * how a chant member's parameters read a choudoufu member of the same
+ * workspace: `choudoufu output -json` in the member's directory for the
+ * applied values, and `live-plan-set -json` over it for the planned ones,
+ * read the way `plan` reads a root's (`terraformPlannedOutputs`). The member
+ * is not a `terraform.roots` entry of the reading project; its directory
+ * comes from the workspace declaration.
+ *
+ * ## Op waves (#4545)
+ *
+ * The step is what an op wave's `step` names to plan and apply each root
+ * through chant (`chant run wave`), so terragucci's waves and plywood's run
+ * the engine in chant. Three inputs come from terragucci's wave callbacks:
+ *
+ * - `lockTimeout` (default `5m`, `false` for none): `plan` and `apply` wait
+ *   that long for another run's state lock, unless `TF_CLI_ARGS` sets
+ *   `-lock-timeout` already (`../lock-timeout.ts`).
+ * - `cone`: a revision. A live choudoufu root plans the cone of the change
+ *   since it (`plan -cone`, `../cone.ts`), and the cone's targets join the
+ *   plan digest, so an approval of one cone counts for no other. Such a root
+ *   plans with `plan`, never as a one-root set.
+ * - `reads`: vars read from another root's outputs, Atmos's
+ *   `!terraform.state` (`../state-reads.ts`). An upstream with no such output
+ *   yet makes the member a hole naming it, so the root is never planned on a
+ *   stand-in.
+ *
+ * Every plan also writes its `show -json` beside the plan file and names it
+ * as `artifact.planJson`, the document a wave's cost hold prices
+ * (`../cost-hold.ts`).
  */
 
+import { rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 import type { Capability, DeployContext, CapabilityPlan, PlannedOutputs } from "@intentius/chant/components/capability";
+import { loadChantConfigUpward } from "@intentius/chant/config";
+import {
+  PlanShapeMovedError,
+  planShapeDifferences,
+  planShapeDigest,
+  type PlanShapeArtifact,
+} from "@intentius/chant/components/covered-round";
 import type { ChangeSetPart } from "@intentius/chant/change-set";
 import { computePlanDigest } from "@intentius/chant/lifecycle/plan-digest";
 import { ownPackageVersion, type CapabilityPlugin } from "@intentius/chant/components/capability-plugin";
+import type { EngineMemberRef, EngineOutputSource, EnginePlannedOutputs } from "@intentius/chant/components/verbs/member-outputs";
 import {
+  choudoufuMemberOutputs,
+  choudoufuMemberPlanSet,
   choudoufuPlanSet,
   choudoufuWaveApply,
   choudoufuWaveRoot,
@@ -78,6 +149,22 @@ import {
   terraformOutputs,
   terraformPlan,
 } from "../op/activities/terraform";
+import { terraformPlanMoved } from "../exit-codes";
+import { terraformPlanShape } from "../plan-shape";
+import { plannerForBinary, terraformChangeSetPart } from "../change-set";
+import { terraformDefaultLockGrain, terraformLockGrainRefusal, terraformLockRows, terraformLockRowsFromPart } from "../lock-rows";
+import type { LockRow } from "@intentius/chant/lifecycle/lock-rows";
+import type { TerraformConfig } from "../config";
+import { rootTexts } from "../compose/hcl";
+import { declaredVariables } from "../compose/root";
+import { terraformComposeGroup } from "./compose-group";
+import { markPlaceholderDriven, placeholderVars, waitingHole } from "./placeholder-preview";
+import { terraformReleaseInputs } from "./release-inputs";
+import { terraformTraceFacts } from "./trace-facts";
+import { DEFAULT_LOCK_TIMEOUT, isLockTimeout } from "../lock-timeout";
+import { conePlanDigest, type PlanCone } from "../cone";
+import { fillStateReads, stateReadsProblems, waitingReadsReason, type TerraformStateRead } from "../state-reads";
+import { terraformStateOpCapabilities } from "../state-ops";
 
 /** The `terraform-apply` step's input. */
 export interface TerraformApplyStepInput {
@@ -87,6 +174,14 @@ export interface TerraformApplyStepInput {
   vars?: Record<string, unknown>;
   /** Where the `chant.config.*` search starts. Default: the current directory. */
   cwd?: string;
+  /** The root's files from here instead of its entry's `dir` (#4542): a promote under a release sets it to the recorded copy. */
+  dir?: string;
+  /** How long `plan` and `apply` wait for a state lock (#4545). Default `"5m"`; `false` passes no flag. */
+  lockTimeout?: string | false;
+  /** choudoufu live roots (#4545): plan the cone of the change since this revision. */
+  cone?: string;
+  /** Vars read from other roots' outputs (#4545), Atmos's `!terraform.state`. The step's `vars` win over them. */
+  reads?: TerraformStateRead[];
 }
 
 /** What `terraform-apply` returns. `outputs` is what a dependent's `stackOutput()` reads. */
@@ -103,9 +198,53 @@ export interface TerraformApplyStepOutput {
 interface PlannedRoot {
   planFile: string;
   planDigest: string;
+  /** The plan's `show -json`, beside the plan file (#4545), for a cost hold to price. */
+  planJson?: string;
+  /** The cone the plan covered, when asked for one (#4545). */
+  cone?: PlanCone;
+  /** A choudoufu root's rows on the resource lock grain (#4552), from the plan's `show -json`. */
+  lockRows?: LockRow[];
+}
+
+/** The lock timeout a step's plan and apply pass (#4545). */
+function lockTimeoutOf(input: TerraformApplyStepInput): { lockTimeout?: string } {
+  if (input.lockTimeout === false) return {};
+  const value = input.lockTimeout ?? DEFAULT_LOCK_TIMEOUT;
+  if (!isLockTimeout(value)) throw new Error(`terraform-apply: root "${input.root}": lockTimeout "${String(value)}" is not a duration such as "5m"`);
+  return { lockTimeout: value };
 }
 
-const rootArgs = (input: TerraformApplyStepInput) => ({ root: input.root, ...(input.cwd ? { cwd: input.cwd } : {}) });
+/**
+ * The step's input with its `reads` filled (#4545): each upstream's outputs
+ * read once, the values under the step's own `vars`. `waiting` when an
+ * upstream has no such output yet. Throws when a state cannot be read.
+ */
+async function withReads(input: TerraformApplyStepInput): Promise<{ input: TerraformApplyStepInput } | { waiting: string; upstreams: string[] }> {
+  const reads = input.reads ?? [];
+  if (reads.length === 0) return { input };
+  const problems = stateReadsProblems(reads);
+  if (problems.length > 0) throw new Error(`terraform-apply: root "${input.root}": ${problems.join("; ")}`);
+  const filled = await fillStateReads(reads, async (root) => {
+    const at = { root, ...(input.cwd ? { cwd: input.cwd } : {}) };
+    await terraformInit(at);
+    return terraformOutputs(at);
+  });
+  if (filled.errors.length > 0) throw new Error(`terraform-apply: root "${input.root}": ${filled.errors.join("; ")}`);
+  if (filled.waiting.length > 0) return { waiting: waitingReadsReason(filled.waiting), upstreams: [...new Set(filled.waiting.map((w) => w.read.root))].sort() };
+  return { input: { ...input, vars: { ...filled.vars, ...(input.vars ?? {}) } } };
+}
+
+/** A root whose reads wait on an upstream (#4545): a hole naming it, and a digest over the root and those upstreams. */
+function waitingOnReads(ctx: DeployContext, input: TerraformApplyStepInput, waiting: { waiting: string; upstreams: string[] }): CapabilityPlan {
+  const planDigest = computePlanDigest("terraform-apply-reads-waiting", { env: ctx.env, root: input.root, upstreams: waiting.upstreams });
+  const changeSet: ChangeSetPart = {
+    member: { member: input.root, lexicon: "terraform", planner: "chant", status: "planned", planDigest, holes: [{ address: input.root, type: "terraform_root", reason: waiting.waiting }] },
+    entries: [],
+  };
+  return { member: input.root, planDigest, changeSet };
+}
+
+const rootArgs = (input: TerraformApplyStepInput) => ({ root: input.root, ...(input.cwd ? { cwd: input.cwd } : {}), ...(input.dir ? { dir: input.dir } : {}) });
 
 function requireRoot(input: TerraformApplyStepInput): void {
   if (typeof input.root !== "string" || input.root === "") {
@@ -116,15 +255,34 @@ function requireRoot(input: TerraformApplyStepInput): void {
 async function planRoot(input: TerraformApplyStepInput, targets?: string[]): Promise<PlannedRoot & { changeSet?: ChangeSetPart; json?: unknown }> {
   requireRoot(input);
   await terraformInit(rootArgs(input));
+  // One `show -json` per plan (#4479): its document is the digest, the change
+  // set, the planned outputs and the shape. Nothing here reads the
+  // `-no-color` render, so the plan skips it.
   const planned = await terraformPlan({
     ...rootArgs(input),
     ...(input.vars ? { vars: input.vars } : {}),
     ...(targets && targets.length > 0 ? { targets } : {}),
+    ...lockTimeoutOf(input),
+    ...(input.cone && !(targets && targets.length > 0) ? { cone: input.cone } : {}),
+    text: false,
   });
+  // #4545: the cone's targets join the digest, so an approval of this cone counts for no other.
+  const planDigest = conePlanDigest(planned.planDigest, planned.cone);
+  const changeSet = planned.changeSet && planDigest !== planned.planDigest ? { ...planned.changeSet, member: { ...planned.changeSet.member, planDigest } } : planned.changeSet;
+  // #4545: the plan document beside the plan file, which a wave's cost hold prices.
+  const planJson = join(planned.dir, `${planned.planFile}.json`);
+  let wrote = true;
+  try {
+    writeFileSync(planJson, JSON.stringify(planned.json));
+  } catch {
+    wrote = false;
+  }
   return {
     planFile: planned.planFile,
-    planDigest: planned.planDigest,
-    ...(planned.changeSet ? { changeSet: planned.changeSet } : {}),
+    planDigest,
+    ...(wrote ? { planJson } : {}),
+    ...(planned.cone ? { cone: planned.cone } : {}),
+    ...(changeSet ? { changeSet } : {}),
     json: planned.json,
   };
 }
@@ -164,12 +322,39 @@ export function terraformPlannedOutputs(json: unknown): PlannedOutputs {
 }
 
 /**
- * The member of a root whose `vars` read outputs not known yet (#3999): no
- * plan, a hole naming whose outputs it waits on, and a digest over the root,
- * the vars as resolved and those names.
+ * What a choudoufu member's set plan says about its outputs (#4455), for
+ * `member-outputs`: {@link terraformPlannedOutputs} of the embedded plan,
+ * chant's digest of that plan, and whether it has changes to apply.
+ */
+export function choudoufuMemberPlannedOutputs(set: { planDigest: string; changed: boolean; json: unknown }): EnginePlannedOutputs {
+  return { ...terraformPlannedOutputs(set.json), planDigest: set.planDigest, changes: set.changed };
+}
+
+const memberArgs = (ref: EngineMemberRef) => ({ member: ref.member, dir: ref.dir, projectRoot: ref.workspaceRoot });
+
+/**
+ * The choudoufu engine's member outputs (#4455): what core's
+ * `member-outputs` reads a workspace member of kind `choudoufu` through.
+ * Applied values from the member's root outputs (the record store, for a
+ * live estate); planned values from its one-root set plan.
  */
-function waitingRoot(ctx: DeployContext, input: TerraformApplyStepInput, unresolved: string[]): CapabilityPlan {
-  const vars = Object.fromEntries(Object.entries(input.vars ?? {}).map(([k, v]) => [k, v === undefined ? null : v]));
+export const choudoufuOutputSource: EngineOutputSource = {
+  kinds: ["choudoufu"],
+  applied: (_ctx, ref) => choudoufuMemberOutputs(memberArgs(ref)),
+  planned: async (_ctx, ref) => choudoufuMemberPlannedOutputs(await choudoufuMemberPlanSet(memberArgs(ref))),
+};
+
+const resolvedVars = (input: TerraformApplyStepInput): Record<string, unknown> =>
+  Object.fromEntries(Object.entries(input.vars ?? {}).map(([k, v]) => [k, v === undefined ? null : v]));
+
+/**
+ * The member of a root whose `vars` read outputs not known yet and that
+ * could not be previewed (#3999, #4463): no plan, a hole naming whose outputs
+ * it waits on and, when a preview was tried, why it was not possible, and a
+ * digest over the root, the vars as resolved and those names.
+ */
+function waitingRoot(ctx: DeployContext, input: TerraformApplyStepInput, unresolved: string[], noPreview?: string): CapabilityPlan {
+  const vars = resolvedVars(input);
   const planDigest = computePlanDigest("terraform-apply-unresolved", { env: ctx.env, root: input.root, vars, unresolved });
   const changeSet: ChangeSetPart = {
     member: {
@@ -178,19 +363,112 @@ function waitingRoot(ctx: DeployContext, input: TerraformApplyStepInput, unresol
       planner: "chant",
       status: "planned",
       planDigest,
-      holes: [{ address: input.root, type: "terraform_root", reason: `inputs from ${unresolved.join(", ")}; planned again once they apply` }],
+      holes: [waitingHole(input.root, unresolved, noPreview)],
     },
     entries: [],
   };
   return { member: input.root, planDigest, changeSet, ...(ctx.targets?.length ? { targets: ctx.targets } : {}) };
 }
 
+/** The plan file a preview writes, removed once it is read: a plan made with stand-ins must never apply. */
+export const PREVIEW_PLAN_FILE = ".chant-preview.tfplan";
+
+/** What a previewed root hands `run` (#4463): the shape its plan had with stand-in values. Never a plan file. */
+export interface TerraformShapeArtifact extends PlanShapeArtifact {
+  kind: "terraform-apply-shape";
+}
+
+function isShapeArtifact(value: unknown): value is TerraformShapeArtifact {
+  const v = value as Partial<TerraformShapeArtifact> | undefined;
+  return v?.kind === "terraform-apply-shape" && typeof v.digest === "string" && typeof v.shape === "object" && v.shape !== null;
+}
+
+/** The root's directory, as `terraform.roots` names it from the nearest `chant.config.*`, and the configured binary. */
+async function rootDir(input: TerraformApplyStepInput): Promise<{ dir: string; binary?: string } | undefined> {
+  const start = resolve(input.cwd ?? process.cwd());
+  const { config, configPath } = await loadChantConfigUpward(start);
+  const terraform = (config as { terraform?: TerraformConfig }).terraform;
+  const declared = terraform?.roots?.[input.root]?.dir;
+  if (declared === undefined) return undefined;
+  const dir = input.dir ?? declared;
+  return { dir: resolve(configPath ? dirname(configPath) : start, dir), ...(terraform?.binary ? { binary: terraform.binary } : {}) };
+}
+
+const firstLines = (err: unknown): string => {
+  const text = (err instanceof Error ? err.message : String(err)).trim();
+  const lines = text.split("\n").map((l) => l.trim()).filter(Boolean);
+  return lines.slice(0, 4).join(" ").slice(0, 600);
+};
+
+/**
+ * Preview a root whose `vars` read outputs not known yet (#4463): plan it
+ * with a typed stand-in per such variable, mark what the stand-ins drive
+ * unknown, and answer the change set, the planned outputs and the shape of
+ * that plan, with the shape as the artifact. The plan file is removed. When
+ * no preview can be made, the member stays a hole saying why.
+ */
+async function previewRoot(ctx: DeployContext, input: TerraformApplyStepInput, unresolved: string[], targets?: string[]): Promise<CapabilityPlan> {
+  const root = await rootDir(input);
+  if (root === undefined) return waitingRoot(ctx, input, unresolved, `no root named "${input.root}" in terraform.roots to read its variables from`);
+  const { dir } = root;
+  // #4457: the same files the binary reads (`.tofu` only for tofu and choudoufu).
+  const stand = placeholderVars(input.vars, declaredVariables(rootTexts(dir, root.binary)));
+  if (typeof stand === "string") return waitingRoot(ctx, input, unresolved, stand);
+  let planned: Awaited<ReturnType<typeof terraformPlan>>;
+  try {
+    await terraformInit(rootArgs(input));
+    planned = await terraformPlan({
+      ...rootArgs(input),
+      vars: stand.vars,
+      planFile: PREVIEW_PLAN_FILE,
+      ...(targets ? { targets } : {}),
+      text: false,
+    });
+  } catch (err) {
+    return waitingRoot(ctx, input, unresolved, `the plan with stand-in values failed: ${firstLines(err)}`);
+  } finally {
+    rmSync(join(dir, PREVIEW_PLAN_FILE), { force: true });
+  }
+  const marked = markPlaceholderDriven(planned.json, stand.placeholders);
+  if ("refused" in marked) return waitingRoot(ctx, input, unresolved, marked.refused);
+  const placeholders = stand.placeholders.map((name) => `var.${name}`);
+  const shape = terraformPlanShape(marked.plan, input.root, { unknownInputs: unresolved });
+  const artifact: TerraformShapeArtifact = { kind: "terraform-apply-shape", member: input.root, shape, digest: planShapeDigest(shape) };
+  const part = terraformChangeSetPart({
+    member: input.root,
+    plan: marked.plan,
+    ...(planned.changeSet?.member.planner ? { planner: planned.changeSet.member.planner } : {}),
+    ...(planned.changeSet?.member.scope ? { scope: planned.changeSet.member.scope } : {}),
+  });
+  // The stand-ins' values are not real, so the digest is over the preview's shape and entries, never the raw plan.
+  const planDigest = computePlanDigest("terraform-apply-preview", {
+    env: ctx.env,
+    root: input.root,
+    vars: resolvedVars(input),
+    unresolved,
+    placeholders,
+    shape: artifact.digest,
+    entries: part.entries,
+  });
+  const changeSet: ChangeSetPart = { ...part, member: { ...part.member, planDigest, placeholders } };
+  return {
+    member: input.root,
+    planDigest,
+    artifact,
+    changeSet,
+    outputs: terraformPlannedOutputs(marked.plan),
+    shape,
+    ...(targets ? { targets } : {}),
+  };
+}
+
 /**
- * choudoufu refused the plan `run` was handed by its wave (its exit 3):
- * the live system moved since the plan, or the plan names another estate.
- * Nothing was applied. `planMoved` is core's mark for a moved plan
- * (`isPlanMovedError`), so the command that applied it exits 3, as for the
- * other capabilities that refuse a moved plan (#3997).
+ * choudoufu refused the plan `run` was handed by its wave (its exit 3)
+ * because the live system moved since the plan. Nothing was applied.
+ * `planMoved` is core's mark for a moved plan (`isPlanMovedError`), so the
+ * command that applied it exits `CHANT_EXIT.moved`, 4, as for the other
+ * capabilities that refuse a moved plan (#3997, #4553). A plan made against
+ * another estate is a plain failure (`terraformExitOf` in ../exit-codes).
  */
 export class TerraformPlanMovedError extends Error {
   readonly planMoved = true;
@@ -200,9 +478,6 @@ export class TerraformPlanMovedError extends Error {
   }
 }
 
-/** `live-wave-apply`'s exit status for a set whose plan moved (`CHOUDOUFU_WAVE_EXIT.setMoved`). */
-const CHOUDOUFU_SET_MOVED_EXIT = 3;
-
 function isPlannedRoot(value: unknown): value is PlannedRoot {
   const v = value as Partial<PlannedRoot> | undefined;
   return typeof v?.planFile === "string" && typeof v.planDigest === "string";
@@ -212,6 +487,8 @@ function isPlannedRoot(value: unknown): value is PlannedRoot {
 interface ChoudoufuWavePlannedRoot {
   planDigest: string;
   choudoufu: { planSetFile: string; setDigest: string };
+  /** The root's rows on the resource lock grain (#4552), from its embedded plan. */
+  lockRows?: LockRow[];
 }
 
 function isChoudoufuWavePlan(value: unknown): value is ChoudoufuWavePlannedRoot {
@@ -238,13 +515,28 @@ async function runChoudoufuWave(
   if (applied.carry) ctx.carry?.(input.root, applied.carry);
   if (!applied.landed) {
     const message = `terraform-apply: root "${input.root}": ${applied.message}`;
-    if (applied.exitCode === CHOUDOUFU_SET_MOVED_EXIT) throw new TerraformPlanMovedError(input.root, message);
+    if (terraformPlanMoved({ command: "live-wave-apply", code: applied.exitCode })) throw new TerraformPlanMovedError(input.root, message);
     throw new Error(message);
   }
   const outputs = await terraformOutputs(rootArgs(input));
   return { root: input.root, planDigest: planned.planDigest, fromWavePlan: true, outputs };
 }
 
+/** The input a `run` that plans for itself plans with (#4545): its reads filled, or an error naming the upstream to apply first. */
+async function readsForRun(input: TerraformApplyStepInput): Promise<TerraformApplyStepInput> {
+  const read = await withReads(input);
+  if ("waiting" in read) throw new Error(`terraform-apply: root "${input.root}": ${read.waiting}`);
+  return read.input;
+}
+
+/** The engine a root plans with (#4552): the configured binary's, else the plan's planner. */
+async function plannerOf(input: TerraformApplyStepInput, plan?: CapabilityPlan): Promise<"terraform" | "tofu" | "choudoufu" | undefined> {
+  const binary = (await rootDir(input).catch(() => undefined))?.binary;
+  if (binary !== undefined) return plannerForBinary(binary) as "terraform" | "tofu" | "choudoufu";
+  const planner = plan?.changeSet?.member.planner;
+  return planner === "terraform" || planner === "tofu" || planner === "choudoufu" ? planner : "terraform";
+}
+
 export const terraformApplyCapability: Capability<TerraformApplyStepInput, TerraformApplyStepOutput> = {
   kind: "terraform-apply",
   // A root's apply has no undo short of applying the previous configuration,
@@ -252,28 +544,36 @@ export const terraformApplyCapability: Capability<TerraformApplyStepInput, Terra
   rollbackPolicy: "needs-opt-out",
   // #4300: `--target` passes through as `-target`, and the saved plan holds those addresses alone.
   targets: "accept",
-  async plan(ctx: DeployContext, input: TerraformApplyStepInput): Promise<CapabilityPlan> {
-    requireRoot(input);
+  async plan(ctx: DeployContext, given: TerraformApplyStepInput): Promise<CapabilityPlan> {
+    requireRoot(given);
+    // #4545: a root reading an upstream's output that is not there yet is a hole naming the upstream.
+    const read = await withReads(given);
+    if ("waiting" in read) return waitingOnReads(ctx, given, read);
+    const { input } = read;
     const unresolved = [...(ctx.unresolvedInputs ?? [])].sort();
-    if (unresolved.length > 0) return waitingRoot(ctx, input, unresolved);
     const targets = ctx.targets && ctx.targets.length > 0 ? ctx.targets : undefined;
-    // A targeted root plans with `plan -target`, never as a choudoufu one-root set.
-    const wave = targets ? { wave: false } : await choudoufuWaveRoot({ ...rootArgs(input), ...(input.vars ? { vars: input.vars } : {}) });
+    if (unresolved.length > 0) return previewRoot(ctx, input, unresolved, targets);
+    // A targeted root plans with `plan -target`, and a cone plan with `plan -cone` (#4545), never as a choudoufu one-root set.
+    const wave = targets || input.cone ? { wave: false } : await choudoufuWaveRoot({ ...rootArgs(input), ...(input.vars ? { vars: input.vars } : {}) });
     if (wave.wave) {
       const set = await choudoufuPlanSet(rootArgs(input));
       const artifact: ChoudoufuWavePlannedRoot = {
         planDigest: set.planDigest,
         choudoufu: { planSetFile: set.planSetFile, setDigest: set.setDigest },
+        lockRows: terraformLockRows(input.root, set.changeSet.member.scope, set.json),
       };
-      return { member: input.root, planDigest: set.planDigest, artifact, changeSet: set.changeSet, outputs: terraformPlannedOutputs(set.json) };
+      return { member: input.root, planDigest: set.planDigest, artifact, changeSet: set.changeSet, outputs: terraformPlannedOutputs(set.json), shape: terraformPlanShape(set.json, input.root) };
     }
     const { changeSet, json, ...planned } = await planRoot(input, targets);
+    // #4552: a choudoufu root's rows, keyed from the plan document while it is at hand.
+    const lockRows = changeSet?.member.planner === "choudoufu" ? terraformLockRows(input.root, changeSet.member.scope, json) : undefined;
     return {
       member: input.root,
       planDigest: planned.planDigest,
-      artifact: planned,
+      artifact: { ...planned, ...(lockRows ? { lockRows } : {}) },
       ...(changeSet ? { changeSet } : {}),
       outputs: terraformPlannedOutputs(json),
+      shape: terraformPlanShape(json, input.root),
       ...(targets ? { targets } : {}),
     };
   },
@@ -284,20 +584,62 @@ export const terraformApplyCapability: Capability<TerraformApplyStepInput, Terra
     await terraformInit(rootArgs(input));
     return terraformOutputs(rootArgs(input));
   },
+  // #4447 (ws-107): a group core forms of components that read each other plans and applies as one composed run
+  // when `terraform.compose.enabled` is set (./compose-group.ts). Delegates, so the methods are read when called.
+  groupReads: (ctx, members) => terraformComposeGroup.groupReads(ctx, members),
+  // #4542: a member pointed at a release's recorded copy plans alone, since a composition reads the declared roots.
+  groupFallback: async (ctx, members) =>
+    members.some((m) => typeof m.step.dir === "string")
+      ? { kind: "release-copy", reason: "a member deploys a release's recorded copy of its root, which a composition does not read" }
+      : terraformComposeGroup.groupFallback(ctx, members),
+  // #4542: the root's files, which a release cut records and a promote under it plans.
+  releaseInputs: (input, ctx) => terraformReleaseInputs(input, ctx),
+  // #4552: resource under choudoufu, the root under Terraform, tofu and Terragrunt, which refuse resource by name.
+  async defaultLockGrain(input, plan) {
+    return terraformDefaultLockGrain(await plannerOf(input, plan));
+  },
+  async lockGrainRefusal(input, grain, plan) {
+    if (grain !== "resource") return undefined;
+    const binary = (await rootDir(input).catch(() => undefined))?.binary;
+    return terraformLockGrainRefusal(grain, await plannerOf(input, plan), binary);
+  },
+  lockRows(input, plan) {
+    const kept = (plan.artifact as { lockRows?: LockRow[] } | undefined)?.lockRows;
+    if (Array.isArray(kept)) return kept;
+    return plan.changeSet ? terraformLockRowsFromPart(input.root, plan.changeSet) : [];
+  },
+  // #4555: the root and the binary, for the step's span and run record.
+  traceFacts: async (input, outcome) => terraformTraceFacts(input, outcome, (await rootDir(input).catch(() => undefined))?.binary),
+  planGroup: (ctx, members) => terraformComposeGroup.planGroup(ctx, members),
+  runGroup: (ctx, run, members) => terraformComposeGroup.runGroup(ctx, run, members),
   async run(ctx: DeployContext, input: TerraformApplyStepInput): Promise<TerraformApplyStepOutput> {
     const fromWave = ctx.plans?.[input.root];
     if (isChoudoufuWavePlan(fromWave)) return runChoudoufuWave(ctx, input, fromWave);
+    if (isShapeArtifact(fromWave)) {
+      // A root previewed with stand-ins (#4463): plan it now with the real
+      // values, and apply that plan only when it is within the preview's shape.
+      const fresh = await planRoot(await readsForRun(input), ctx.targets);
+      const differences = planShapeDifferences(fromWave.shape, terraformPlanShape(fresh.json, input.root));
+      if (differences.length > 0) throw new PlanShapeMovedError(input.root, differences);
+      const applied = await terraformApply({ ...rootArgs(input), planFile: fresh.planFile, ...lockTimeoutOf(input) });
+      if (!applied.applied) {
+        throw new Error(`terraform-apply: root "${input.root}" refused the plan it was given (${applied.refused ?? "refused"}). ${applied.refusal ?? ""}`);
+      }
+      const outputs = await terraformOutputs(rootArgs(input));
+      return { root: input.root, planDigest: fresh.planDigest, fromWavePlan: false, outputs };
+    }
     const planned: PlannedRoot = isPlannedRoot(fromWave)
       ? fromWave
-      : await planRoot(input, ctx.targets).then(({ planFile, planDigest }) => ({ planFile, planDigest }));
-    const applied = await terraformApply({ ...rootArgs(input), planFile: planned.planFile });
+      : await planRoot(await readsForRun(input), ctx.targets).then(({ planFile, planDigest }) => ({ planFile, planDigest }));
+    const applied = await terraformApply({ ...rootArgs(input), planFile: planned.planFile, ...lockTimeoutOf(input) });
     if (!applied.applied) {
       const message =
         `terraform-apply: root "${input.root}" refused the plan it was given (${applied.refused ?? "refused"}). ` +
         (applied.refusal ?? "");
-      // A plan the wave approved that choudoufu refuses moved since the
-      // approval. One this run made itself is planned afresh by the next run.
-      if (applied.refused !== undefined && isPlannedRoot(fromWave)) throw new TerraformPlanMovedError(input.root, message);
+      // A plan the wave approved that choudoufu refuses as no longer matching
+      // moved since the approval (#4553: one made against another estate is a
+      // failure). One this run made itself is planned afresh by the next run.
+      if (applied.refused === "approval-mismatch" && isPlannedRoot(fromWave)) throw new TerraformPlanMovedError(input.root, message);
       throw new Error(message);
     }
     const outputs = await terraformOutputs(rootArgs(input));
@@ -307,6 +649,9 @@ export const terraformApplyCapability: Capability<TerraformApplyStepInput, Terra
 
 export const TERRAFORM_VERB_FAMILIES = {
   apply: ["terraform-apply"],
+  // #4618: the binary runs outside waves, each a fixed operation; the two that change state on their own run under a gated request.
+  state: ["terraform-state-unlock", "terraform-state-push"],
+  copy: ["terraform-copy"],
 } as const;
 
 export const terraformCapabilityPlugin: CapabilityPlugin = {
@@ -315,9 +660,12 @@ export const terraformCapabilityPlugin: CapabilityPlugin = {
     return ownPackageVersion(import.meta.url);
   },
   capabilities(): Array<Capability<never, unknown>> {
-    return [terraformApplyCapability as Capability<never, unknown>];
+    return [terraformApplyCapability as Capability<never, unknown>, ...terraformStateOpCapabilities.map((c) => c as unknown as Capability<never, unknown>)];
   },
   families(): Record<string, readonly string[]> {
     return TERRAFORM_VERB_FAMILIES;
   },
+  engineOutputSources(): EngineOutputSource[] {
+    return [choudoufuOutputSource];
+  },
 };

package/src/components/change-set-graph.e2e.test.ts

@@ -16,7 +16,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { composeChangeSet } from "@intentius/chant/change-set";
-import { buildGraphIr } from "@intentius/chant/graph-ir";
+import { buildGraphIr, withInstanceNodes } from "@intentius/chant/graph-ir";
 import { readGraphIds, storeGateChangeSet } from "@intentius/chant/lifecycle/gate-change-set";
 import { readStoredChangeSet } from "@intentius/chant/lifecycle/change-set-store";
 import { terraformChangeSetPart } from "../change-set";
@@ -59,10 +59,11 @@ describe("a terraform change set mapped onto the spawned chant graph", () => {
     const spawned = await readGraphIds(dir);
     if ("error" in spawned) throw new Error(spawned.error);
     const rendered = await renderTerraformRoots({ projectRoot: dir, roots: { estate: { dir: "estate" } } });
-    expect(buildGraphIr(rendered.entities).nodes.map((n) => n.id).sort()).toEqual([...spawned.ids].sort());
+    // `chant graph` adds the instance nodes of `count = 2` (#4454).
+    expect(withInstanceNodes(buildGraphIr(rendered.entities), rendered.entities).nodes.map((n) => n.id).sort()).toEqual([...spawned.ids].sort());
   }, TIMEOUT);
 
-  test("each entry is stored on the block the graph names, and a deleted block has no node", async () => {
+  test("each entry is stored on the node the graph names, an instance on its instance node, and a deleted block has no node", async () => {
     const plan = JSON.parse(readFileSync(join(FIXTURES, "terraform.plan.json"), "utf8"));
     const doc = composeChangeSet([terraformChangeSetPart({ member: "estate", plan })]);
     const head = git("rev-parse", "HEAD");
@@ -72,13 +73,18 @@ describe("a terraform change set mapped onto the spawned chant graph", () => {
     const read = await readStoredChangeSet(doc.digest, { cwd: dir });
     if (read.status !== "found") throw new Error(read.status);
     expect(read.document.entries.map((e) => [e.address, e.node])).toEqual([
-      ["module.app.terraform_data.instance[0]", "estate/module.app/terraform_data.instance"],
-      ["module.app.terraform_data.instance[1]", "estate/module.app/terraform_data.instance"],
+      ["module.app.terraform_data.instance[0]", "estate/module.app/terraform_data.instance[0]"],
+      ["module.app.terraform_data.instance[1]", "estate/module.app/terraform_data.instance[1]"],
       ["terraform_data.config", "estate/terraform_data.config"],
       ["terraform_data.keep", "estate/terraform_data.keep"],
       ["terraform_data.old", null],
       ["terraform_data.secret", "estate/terraform_data.secret"],
       ["terraform_data.worker", "estate/terraform_data.worker"],
     ]);
+    // The instances name their block node, the rollup (#4454).
+    expect(read.document.entries.filter((e) => e.instanceOf).map((e) => e.instanceOf)).toEqual([
+      "estate/module.app/terraform_data.instance",
+      "estate/module.app/terraform_data.instance",
+    ]);
   }, TIMEOUT);
 });