@intentius/chant-lexicon-terraform 0.124.54 → 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
@@ -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[];
+}
+
+/** 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 } : {}) });
+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,33 @@ 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();
     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 +587,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 +618,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 +630,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 +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 = {
@@ -513,7 +660,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 } : {}),
+    },
+  };
+}

package/src/cone.ts

@@ -0,0 +1,138 @@
+/**
+ * choudoufu's cone plans (#4545, moved from terragucci's `cone.ts`): `plan
+ * -cone=<base>` plans only the blocks a change touches and every block that
+ * reads them.
+ *
+ * A wave that applies an open pull request plans a live root as the cone of
+ * its change since the pull request's base, as the plan note did. A wave
+ * that applies a merge commit and a drift run plan the whole estate, as do
+ * a root with no `live` block, an estate file (`estate.chdf.hcl`), whose
+ * form choudoufu refuses `-cone` on, and any binary but choudoufu.
+ *
+ * choudoufu's guard can plan the whole estate anyway (no base, a provider,
+ * terraform or live block or the lock file changed, a cone over 30% of the
+ * estate's blocks, and so on). It says why in a warning. A cone plan says
+ * its size in a warning too, and with `-out FILE` writes `FILE.cone.json`:
+ * the cone's base, the commit it named and the addresses it targets.
+ *
+ * The record's targets join the root's plan digest ({@link conePlanDigest}),
+ * so the digest an approval binds names the cone. A wave that plans again
+ * after its approval and finds another cone has another digest, and refuses
+ * as moved. choudoufu's `apply FILE` checks the same record again.
+ *
+ * Pure, apart from reading the record beside a plan file.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { computePlanDigest } from "@intentius/chant/lifecycle/plan-digest";
+
+/** The flags choudoufu refuses beside `-cone`, or plans in full with: a plan that carries one gets no `-cone`. */
+export const CONE_EXCLUDES = ["-target", "-exclude", "-destroy", "-refresh-only", "-json", "-estate"] as const;
+
+/** What choudoufu writes beside a saved cone plan, `FILE.cone.json`. */
+export interface ConeRecord {
+  base: string;
+  base_sha: string;
+  targets: string[];
+}
+
+/** What one root's cone plan did: planned the cone, or planned the whole estate for the guard's reason. */
+export interface PlanCone {
+  /** The revision the plan was asked to measure the change from. */
+  base: string;
+  /** With a cone: its blocks, and the estate's, as choudoufu counted them. Absent when it did not say. */
+  blocks?: number;
+  of?: number;
+  /** With a cone: the record beside the plan file. */
+  record?: ConeRecord;
+  /** The guard planned the whole estate: its kind and why. */
+  fallback?: { kind: string; reason: string };
+}
+
+/** Whether `binary` (a name or a path) is choudoufu. */
+export const isChoudoufu = (binary: string): boolean => basename(binary) === "choudoufu";
+
+/**
+ * The `-cone` argument a plan takes: `-cone=<base>` for choudoufu with a
+ * base, on a root that takes it (`live`), when none of `args` is a flag in
+ * {@link CONE_EXCLUDES}. Otherwise none, and the plan is full.
+ */
+export function coneArgs(binary: string, base: string | undefined, args: readonly string[], cone: boolean): string[] {
+  if (!base || !cone || !isChoudoufu(binary)) return [];
+  const excluded = args.some((a) => CONE_EXCLUDES.some((f) => a === f || a.startsWith(`${f}=`)));
+  return excluded ? [] : [`-cone=${base}`];
+}
+
+/** The path of the cone record beside a plan file. */
+export const coneRecordPath = (planFile: string): string => `${planFile}.cone.json`;
+
+/** The cone record beside `planFile`, or none when there is none or it does not read as one. */
+export function readConeRecord(planFile: string): ConeRecord | undefined {
+  const path = coneRecordPath(planFile);
+  if (!existsSync(path)) return undefined;
+  try {
+    const r = JSON.parse(readFileSync(path, "utf-8")) as Partial<ConeRecord> | null;
+    if (!r || typeof r.base !== "string" || !Array.isArray(r.targets) || !r.targets.every((t) => typeof t === "string")) return undefined;
+    return { base: r.base, base_sha: typeof r.base_sha === "string" ? r.base_sha : "", targets: [...r.targets].sort() };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The detail of the last warning with this summary in a plan's output, its
+ * lines joined. The binary prints a warning as `Warning: <summary>`, a blank
+ * line, and the detail up to the next blank line or the plan's summary; a box
+ * drawn around it with colour on is stripped.
+ */
+function warningDetail(text: string, summary: string): string | undefined {
+  const lines = text.replace(/\r\n/g, "\n").split("\n").map((l) => l.replace(/^[\s│╷╵]*/, "").trimEnd());
+  let found: string | undefined;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i] !== `Warning: ${summary}`) continue;
+    let j = i + 1;
+    while (j < lines.length && lines[j] === "") j++;
+    const detail: string[] = [];
+    for (; j < lines.length && lines[j] !== "" && !/^(Plan: |No changes\.|Changes to Outputs:)/.test(lines[j]!); j++) detail.push(lines[j]!);
+    found = detail.join(" ").replace(/\s+/g, " ").trim();
+  }
+  return found;
+}
+
+/**
+ * What a plan run with `-cone=<base>` did, from its output and the record
+ * beside `planFile`. A fallback warning means the whole estate was planned,
+ * even after a cone warning. With no fallback, the record is the cone. With
+ * neither, choudoufu said nothing this reads, and the plan counts as full.
+ */
+export function readPlanCone(output: string, planFile: string, base: string): PlanCone {
+  const fell = warningDetail(output, "Cone plan fell back to a full plan");
+  if (fell !== undefined) {
+    const m = /^This plan covers the whole estate \(guard ([^)]*)\): (.*?)\.?$/.exec(fell);
+    return { base, fallback: m ? { kind: m[1]!, reason: m[2]! } : { kind: "unknown", reason: fell } };
+  }
+  const record = readConeRecord(planFile);
+  if (!record) return { base, fallback: { kind: "unknown", reason: "choudoufu wrote no cone record beside the plan" } };
+  const size = /: (\d+) of the estate's (\d+) blocks/.exec(warningDetail(output, "Cone plan") ?? "");
+  return { base, ...(size ? { blocks: Number(size[1]), of: Number(size[2]) } : {}), record };
+}
+
+/** What a cone plan did, in words: its size, or why it planned the whole estate. */
+export function coneText(cone: PlanCone): string {
+  if (cone.fallback) return `the whole estate, since ${cone.fallback.reason} (guard ${cone.fallback.kind})`;
+  const n = cone.record?.targets.length ?? 0;
+  const size = cone.blocks !== undefined && cone.of !== undefined ? `${cone.blocks} of the estate's ${cone.of} blocks` : `${n} target${n === 1 ? "" : "s"}`;
+  return `the cone of the change since ${cone.base}, ${size}`;
+}
+
+/**
+ * A root's plan digest with its cone in it: the plan's own digest, unchanged,
+ * when the plan was full; with a cone, the digest over the plan's digest and
+ * the cone's targets, so an approval of one cone counts for no other. The
+ * digest's kind is terragucci's, so approvals recorded before the move still
+ * name the same digest.
+ */
+export function conePlanDigest(planDigest: string, cone: PlanCone | undefined): string {
+  if (!cone?.record) return planDigest;
+  return computePlanDigest("terragucci-cone-plan", { plan: planDigest, targets: [...cone.record.targets].sort() });
+}