@intentius/chant-lexicon-terraform 0.124.54 → 0.124.56

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
@@ -100,9 +100,31 @@
  * 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 } from "node:fs";
+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";
@@ -127,13 +149,22 @@ import {
   terraformOutputs,
   terraformPlan,
 } from "../op/activities/terraform";
+import { terraformPlanMoved } from "../exit-codes";
 import { terraformPlanShape } from "../plan-shape";
-import { terraformChangeSetPart } from "../change-set";
+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 {
@@ -143,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. */
@@ -159,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[];
 }
 
-const rootArgs = (input: TerraformApplyStepInput) => ({ root: input.root, ...(input.cwd ? { cwd: input.cwd } : {}) });
+/** 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 };
+}
+
+/**
+ * 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 === "") {
@@ -179,12 +262,27 @@ async function planRoot(input: TerraformApplyStepInput, targets?: string[]): Pro
     ...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,
   };
 }
@@ -290,8 +388,9 @@ async function rootDir(input: TerraformApplyStepInput): Promise<{ dir: string; b
   const start = resolve(input.cwd ?? process.cwd());
   const { config, configPath } = await loadChantConfigUpward(start);
   const terraform = (config as { terraform?: TerraformConfig }).terraform;
-  const dir = terraform?.roots?.[input.root]?.dir;
-  if (dir === undefined) return undefined;
+  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 } : {}) };
 }
 
@@ -364,11 +463,12 @@ async function previewRoot(ctx: DeployContext, input: TerraformApplyStepInput, u
 }
 
 /**
- * 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;
@@ -378,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";
@@ -390,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 {
@@ -416,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,
@@ -430,26 +544,40 @@ 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);
+  // #4627: `plan` refreshes the root's state before it plans unless told `-refresh=false`, which chant never passes,
+  // so `--refresh` asks for what every plan does and the digest still binds it. `-target` plans a resource with what it
+  // depends on and never what depends on it, so `--target-dependents` has nothing to map onto.
+  planFlags: {
+    refresh: "accept",
+    targetDependents: { refuse: "terraform and tofu plan a -target with what it depends on, never what depends on it, so there is no flag to widen it to its dependents; name each dependent with --target" },
+  },
+  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();
     const targets = ctx.targets && ctx.targets.length > 0 ? ctx.targets : undefined;
     if (unresolved.length > 0) return previewRoot(ctx, input, unresolved, targets);
-    // 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 } : {}) });
+    // 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), 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),
@@ -466,7 +594,29 @@ export const terraformApplyCapability: Capability<TerraformApplyStepInput, Terra
   // #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),
-  groupFallback: (ctx, members) => terraformComposeGroup.groupFallback(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> {
@@ -475,10 +625,10 @@ export const terraformApplyCapability: Capability<TerraformApplyStepInput, Terra
     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(input, ctx.targets);
+      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 });
+      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 ?? ""}`);
       }
@@ -487,15 +637,16 @@ export const terraformApplyCapability: Capability<TerraformApplyStepInput, Terra
     }
     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));
@@ -505,6 +656,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 = {
@@ -513,7 +667,7 @@ 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;

package/src/components/compose-group.ts

@@ -341,7 +341,7 @@ function waitingGroup(ctx: GroupContext, members: readonly GroupMember<StepInput
   return { members: plans, digest: computePlanDigest("terraform-apply-group-unresolved", { components: ctx.components, unresolved: waits }) };
 }
 
-/** A composed plan that no longer matches the one approved. Core's moved-plan mark, so nothing applies and the command exits 3. */
+/** A composed plan that no longer matches the one approved. Core's moved-plan mark, so nothing applies and the command exits `CHANT_EXIT.moved`, 4 (#4553). */
 export class ComposedPlanMovedError extends Error {
   readonly planMoved = true;
   constructor(message: string) {

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

@@ -287,7 +287,7 @@ chainSuite("with terraform.compose, three roots plan and apply as one group", {
     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);
+    expect(await loop.merge(2)).toBe(4);
     const refused = loop.report("apply");
     expect(refused.status).toBe("refused");
     expect(refused.refusal).toBe("plan-changed");

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

@@ -298,7 +298,7 @@ describe.skipIf(!BINARY)(`the pull-request loop over five ${BINARY ?? "terraform
     write("roots/a/main.tf", ROOTS.a.replace("a-v1", "a-v4"));
     git("commit", "-qam", "a v4");
 
-    expect(await merge(2)).toBe(3);
+    expect(await merge(2)).toBe(4);
     const refused = report("apply");
     expect(refused.status).toBe("refused");
     expect(refused.refusal).toBe("plan-changed");

package/src/components/release-inputs.ts

@@ -0,0 +1,69 @@
+/**
+ * The files a release records for a `terraform-apply` step (chant#4542).
+ *
+ * The step names its root by key, so core can't see which files it deploys.
+ * `terraformReleaseInputs` answers core's `releaseInputs` with the set a
+ * pull request's plan treats as the root's change (`rootWatchPaths`): the
+ * root's directory, each local module it reaches, and its var files, plus
+ * its backend-config files. A release cut records them for the component,
+ * and a promote or rollback under the release writes them under
+ * `.chant/release-templates/<digest>/` and sets the step's `dir` to the copy
+ * of the root, so `terraform-apply` plans the release's configuration against
+ * the environment's state.
+ *
+ * A root whose state is a file in its own directory (the `local` backend) is
+ * unbound: a plan run in a copy elsewhere would read no state and propose
+ * creating everything. Such a root rolls back through `chant lifecycle
+ * rollback --to`. A live choudoufu root has no state file and is recorded.
+ */
+
+import { dirname, relative, resolve } from "node:path";
+import type { ReleaseInputs, ReleaseInputsContext, ReleaseInputsUnbound } from "@intentius/chant/components/capability";
+import { loadChantConfigUpward } from "@intentius/chant/config";
+import { rootWatchPaths } from "../changed-roots";
+import type { TerraformConfig } from "../config";
+import { liveEstate } from "../compose/hcl";
+import { readBackend } from "../state/backend";
+
+/** The parts of the `terraform-apply` input this reads. */
+interface StepInput {
+  root: string;
+  cwd?: string;
+  dir?: string;
+}
+
+const toPosix = (p: string): string => p.split("\\").join("/") || ".";
+
+/** What a release records for one `terraform-apply` step, relative to the member's directory. Null when the root is not declared. */
+export async function terraformReleaseInputs(input: StepInput, ctx: ReleaseInputsContext): Promise<ReleaseInputs | ReleaseInputsUnbound | null> {
+  if (typeof input.root !== "string" || input.root === "") return null;
+  const start = resolve(ctx.memberDir, input.cwd ?? ".");
+  const { config, configPath } = await loadChantConfigUpward(start);
+  const projectRoot = configPath ? dirname(configPath) : start;
+  const terraform = (config as { terraform?: TerraformConfig }).terraform;
+  const root = terraform?.roots?.[input.root];
+  if (!root) return null;
+  const binary = terraform?.binary;
+  const rootDir = resolve(projectRoot, input.dir ?? root.dir);
+  const live = binary === "choudoufu" && (root.estate !== undefined || liveEstate(rootDir, binary).live);
+  if (!live) {
+    const { backend } = readBackend(rootDir, {
+      ...(root.backendConfig ? { backendConfig: root.backendConfig } : {}),
+      ...(root.backendConfigFiles ? { backendConfigFiles: root.backendConfigFiles } : {}),
+      ...(binary ? { binary } : {}),
+    });
+    if (backend.type === "local") {
+      return {
+        unbound:
+          `root "${input.root}" keeps its state in a local file under ${toPosix(relative(ctx.memberDir, rootDir))}, ` +
+          "so a plan of a recorded copy would read no state; roll it back with chant lifecycle rollback --to <ref>",
+      };
+    }
+  }
+  const fromMember = (abs: string): string => toPosix(relative(ctx.memberDir, abs));
+  const paths = rootWatchPaths(projectRoot, { dir: relative(projectRoot, rootDir) || ".", ...(root.varFiles ? { varFiles: root.varFiles } : {}) }, binary).map((p) =>
+    fromMember(resolve(projectRoot, p)),
+  );
+  for (const file of root.backendConfigFiles ?? []) paths.push(fromMember(resolve(rootDir, file)));
+  return { field: "dir", dir: fromMember(rootDir), paths: [...new Set(paths)].sort() };
+}

package/src/components/trace-facts.test.ts

@@ -0,0 +1,21 @@
+/**
+ * `terraform-apply`'s engine facts (INTENTIUS/chant#4555): the root and the
+ * binary, for the step's span and run record.
+ */
+
+import { describe, expect, test } from "vitest";
+import { terraformTraceFacts } from "./trace-facts";
+
+describe("terraform-apply's trace facts (#4555)", () => {
+  test("name the root, the configured binary and whether the wave's plan applied", () => {
+    expect(terraformTraceFacts({ root: "network" }, { output: { root: "network", planDigest: "sha256:x", fromWavePlan: true, outputs: { vpc_id: "v" } } }, "/usr/local/bin/tofu")).toEqual({
+      attributes: { root: "network", binary: "tofu", "apply.from_wave_plan": true, "apply.outputs": 1 },
+    });
+  });
+
+  test("default to terraform, and keep the root and the cone on a failed apply", () => {
+    expect(terraformTraceFacts({ root: "network", cone: "HEAD~1" }, { error: new Error("refused") }, undefined)).toEqual({
+      attributes: { root: "network", binary: "terraform", "plan.cone": "HEAD~1" },
+    });
+  });
+});

package/src/components/trace-facts.ts

@@ -0,0 +1,27 @@
+/**
+ * `terraform-apply`'s engine facts for its span and op-wave run record
+ * (INTENTIUS/chant#4555): the root, the binary that applied it, and whether
+ * it applied the plan the wave decided. Core adds the plan's resource counts
+ * by action, and writes every key under the CI product's prefix
+ * (`terragucci.root`, `terragucci.binary`).
+ */
+
+import type { CapabilityTraceFacts } from "@intentius/chant/otlp";
+import type { TerraformApplyStepInput, TerraformApplyStepOutput } from "./capability-plugin";
+
+/** `traceFacts` for `terraform-apply` (#4555). `binary` is the config's `terraform.binary`, `terraform` when it names none. */
+export function terraformTraceFacts(
+  input: TerraformApplyStepInput,
+  outcome: { output: TerraformApplyStepOutput } | { error: unknown },
+  binary: string | undefined,
+): CapabilityTraceFacts {
+  const bin = (binary ?? "terraform").split(/[\\/]/).pop() || "terraform";
+  return {
+    attributes: {
+      root: input.root,
+      binary: bin,
+      ...("output" in outcome && outcome.output ? { "apply.from_wave_plan": outcome.output.fromWavePlan, "apply.outputs": Object.keys(outcome.output.outputs ?? {}).length } : {}),
+      ...(input.cone ? { "plan.cone": input.cone } : {}),
+    },
+  };
+}