@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/dist/components/capability-plugin.js

@@ -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,11 +81,111 @@
  *
  * 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 { loadChantConfigUpward } from "@intentius/chant/config";
+import { PlanShapeMovedError, planShapeDifferences, planShapeDigest, } from "@intentius/chant/components/covered-round";
 import { computePlanDigest } from "@intentius/chant/lifecycle/plan-digest";
 import { ownPackageVersion } from "@intentius/chant/components/capability-plugin";
-import { choudoufuPlanSet, choudoufuWaveApply, choudoufuWaveRoot, terraformApply, terraformInit, terraformOutputs, terraformPlan, } from "../op/activities/terraform.js";
-const rootArgs = (input) => ({ root: input.root, ...(input.cwd ? { cwd: input.cwd } : {}) });
+import { choudoufuMemberOutputs, choudoufuMemberPlanSet, choudoufuPlanSet, choudoufuWaveApply, choudoufuWaveRoot, terraformApply, terraformInit, terraformOutputs, terraformPlan, } from "../op/activities/terraform.js";
+import { terraformPlanMoved } from "../exit-codes.js";
+import { terraformPlanShape } from "../plan-shape.js";
+import { plannerForBinary, terraformChangeSetPart } from "../change-set.js";
+import { terraformDefaultLockGrain, terraformLockGrainRefusal, terraformLockRows, terraformLockRowsFromPart } from "../lock-rows.js";
+import { rootTexts } from "../compose/hcl.js";
+import { declaredVariables } from "../compose/root.js";
+import { terraformComposeGroup } from "./compose-group.js";
+import { markPlaceholderDriven, placeholderVars, waitingHole } from "./placeholder-preview.js";
+import { terraformReleaseInputs } from "./release-inputs.js";
+import { terraformTraceFacts } from "./trace-facts.js";
+import { DEFAULT_LOCK_TIMEOUT, isLockTimeout } from "../lock-timeout.js";
+import { conePlanDigest } from "../cone.js";
+import { fillStateReads, stateReadsProblems, waitingReadsReason } from "../state-reads.js";
+import { terraformStateOpCapabilities } from "../state-ops.js";
+/** The lock timeout a step's plan and apply pass (#4545). */
+function lockTimeoutOf(input) {
+    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 };
+}
+/**
+ * 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) {
+    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, input, waiting) {
+    const planDigest = computePlanDigest("terraform-apply-reads-waiting", { env: ctx.env, root: input.root, upstreams: waiting.upstreams });
+    const changeSet = {
+        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) => ({ root: input.root, ...(input.cwd ? { cwd: input.cwd } : {}), ...(input.dir ? { dir: input.dir } : {}) });
 function requireRoot(input) {
     if (typeof input.root !== "string" || input.root === "") {
         throw new Error('terraform-apply: "root" is required and names an entry in terraform.roots');
@@ -76,15 +194,35 @@ function requireRoot(input) {
 async function planRoot(input, targets) {
     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,
     };
 }
@@ -127,12 +265,34 @@ export function terraformPlannedOutputs(json) {
     return { known, unknown };
 }
 /**
- * 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) {
+    return { ...terraformPlannedOutputs(set.json), planDigest: set.planDigest, changes: set.changed };
+}
+const memberArgs = (ref) => ({ 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.
+ */
+export const choudoufuOutputSource = {
+    kinds: ["choudoufu"],
+    applied: (_ctx, ref) => choudoufuMemberOutputs(memberArgs(ref)),
+    planned: async (_ctx, ref) => choudoufuMemberPlannedOutputs(await choudoufuMemberPlanSet(memberArgs(ref))),
+};
+const resolvedVars = (input) => 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, input, unresolved) {
-    const vars = Object.fromEntries(Object.entries(input.vars ?? {}).map(([k, v]) => [k, v === undefined ? null : v]));
+function waitingRoot(ctx, input, unresolved, noPreview) {
+    const vars = resolvedVars(input);
     const planDigest = computePlanDigest("terraform-apply-unresolved", { env: ctx.env, root: input.root, vars, unresolved });
     const changeSet = {
         member: {
@@ -141,18 +301,107 @@ function waitingRoot(ctx, input, unresolved) {
             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";
+function isShapeArtifact(value) {
+    const v = value;
+    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) {
+    const start = resolve(input.cwd ?? process.cwd());
+    const { config, configPath } = await loadChantConfigUpward(start);
+    const terraform = config.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) => {
+    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, input, unresolved, targets) {
+    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;
+    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 = { 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 = { ...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 {
     constructor(root, message) {
@@ -162,8 +411,6 @@ export class TerraformPlanMovedError extends Error {
         this.name = "TerraformPlanMovedError";
     }
 }
-/** `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) {
     const v = value;
     return typeof v?.planFile === "string" && typeof v.planDigest === "string";
@@ -186,13 +433,28 @@ async function runChoudoufuWave(ctx, input, planned) {
         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)
+        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) {
+    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, plan) {
+    const binary = (await rootDir(input).catch(() => undefined))?.binary;
+    if (binary !== undefined)
+        return plannerForBinary(binary);
+    const planner = plan?.changeSet?.member.planner;
+    return planner === "terraform" || planner === "tofu" || planner === "choudoufu" ? planner : "terraform";
+}
 export const terraformApplyCapability = {
     kind: "terraform-apply",
     // A root's apply has no undo short of applying the previous configuration,
@@ -200,29 +462,38 @@ export const terraformApplyCapability = {
     rollbackPolicy: "needs-opt-out",
     // #4300: `--target` passes through as `-target`, and the saved plan holds those addresses alone.
     targets: "accept",
-    async plan(ctx, input) {
-        requireRoot(input);
+    async plan(ctx, given) {
+        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 = {
                 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 } : {}),
         };
     },
@@ -233,20 +504,64 @@ export const terraformApplyCapability = {
         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?.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, input) {
         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 = 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))
+            // 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);
         }
@@ -256,6 +571,9 @@ export const terraformApplyCapability = {
 };
 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"],
 };
 export const terraformCapabilityPlugin = {
     name: "terraform",
@@ -263,9 +581,12 @@ export const terraformCapabilityPlugin = {
         return ownPackageVersion(import.meta.url);
     },
     capabilities() {
-        return [terraformApplyCapability];
+        return [terraformApplyCapability, ...terraformStateOpCapabilities.map((c) => c)];
     },
     families() {
         return TERRAFORM_VERB_FAMILIES;
     },
+    engineOutputSources() {
+        return [choudoufuOutputSource];
+    },
 };