@intentius/chant-lexicon-terraform 0.124.31 → 0.124.33

package/dist/components/capability-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capability-plugin.d.ts","sourceRoot":"","sources":["../../src/components/capability-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAiC,MAAM,wCAAwC,CAAC;AAExG,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,+CAA+C,CAAC;AAWzG,0CAA0C;AAC1C,MAAM,WAAW,uBAAuB;IACtC,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,gFAAgF;IAChF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,6FAA6F;AAC7F,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,YAAY,EAAE,OAAO,CAAC;IACtB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAmED,eAAO,MAAM,wBAAwB,EAAE,UAAU,CAAC,uBAAuB,EAAE,wBAAwB,CAwClG,CAAC;AAEF,eAAO,MAAM,uBAAuB;aAClC,KAAK,YAAG,iBAAiB;CACjB,CAAC;AAEX,eAAO,MAAM,yBAAyB,EAAE,gBAWvC,CAAC"}
+{"version":3,"file":"capability-plugin.d.ts","sourceRoot":"","sources":["../../src/components/capability-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAiC,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAGxH,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,+CAA+C,CAAC;AAWzG,0CAA0C;AAC1C,MAAM,WAAW,uBAAuB;IACtC,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,gFAAgF;IAChF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,6FAA6F;AAC7F,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,YAAY,EAAE,OAAO,CAAC;IACtB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAsCD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAerE;AAwBD;;;;;;GAMG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;aAEpB,IAAI,EAAE,MAAM;IADxC,QAAQ,CAAC,SAAS,QAAQ;IAC1B,YAA4B,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAGxD;CACF;AA+CD,eAAO,MAAM,wBAAwB,EAAE,UAAU,CAAC,uBAAuB,EAAE,wBAAwB,CAmDlG,CAAC;AAEF,eAAO,MAAM,uBAAuB;aAClC,KAAK,YAAG,iBAAiB;CACjB,CAAC;AAEX,eAAO,MAAM,yBAAyB,EAAE,gBAWvC,CAAC"}

package/dist/components/capability-plugin.js

@@ -0,0 +1,260 @@
+/**
+ * `terraformCapabilityPlugin` — the terraform lexicon's capability plugin
+ * (#3049). It contributes `terraform-apply`, which lets a component deploy a
+ * root named in `terraform.roots`, so a change across many roots runs as a
+ * `chant components fan-out`: in an order derived from each component's
+ * `dependsOn`, and, with `--wave-gate`, a gate per wave bound to the wave's
+ * set digest.
+ *
+ * The step is `{ kind: "terraform-apply", root: "<name>" }`, with optional
+ * `vars` (passed as `-var`, so `stackOutput()` can hand one root's output to
+ * another) and `cwd`. It works the same for `terraform`, `tofu` and
+ * `choudoufu`, since all three go through the lexicon's activities.
+ *
+ * ## Plan, then apply exactly that plan
+ *
+ * `plan` runs `init` and `plan -out`, and answers with the root as the member
+ * and `terraformPlanDigest` as its digest: the value a `TerraformApplyOp`
+ * gate on this root alone binds (#2300). A gated-wave fan-out folds those into
+ * the wave's set digest and hands the plan file back to `run`, which applies
+ * that file and nothing else. terraform and tofu refuse a saved plan whose
+ * state moved since it was written; choudoufu re-plans against the live
+ * 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
+ * is not classified and exits 1.
+ *
+ * Run without a wave plan (`chant run --components`, or a fan-out with no
+ * wave gate), `run` plans and applies in one go, which is what `terraform
+ * apply` with no plan file does too.
+ *
+ * ## What the plan says about the root's outputs (#3999)
+ *
+ * `plan` answers the outputs the root will have once that plan applies
+ * (`terraformPlannedOutputs`): `show -json`'s `planned_values.outputs`, less
+ * each output whose `output_changes` entry is unknown after apply. A pull
+ * request's plan reads a dependent's `stackOutput()` references from there
+ * 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.
+ *
+ * ## choudoufu roots in a gated wave (#3459)
+ *
+ * A live choudoufu root that `live-plan-set` can plan as chant would (no
+ * `vars`, no var files, no backend config; see `choudoufuWaveRoot`) goes
+ * through choudoufu's own set commands (choudoufu#1754), which need
+ * choudoufu v0.22.0 (`MIN_CHOUDOUFU_WAVES_VERSION`):
+ *
+ * - `plan` runs `live-plan-set -json` over the root as a one-root set. The
+ *   wave gate still binds chant's `terraformPlanDigest` of the plan the
+ *   document embeds, the same string a single-root gate binds. choudoufu's
+ *   set digest is kept for the apply, and its root digest is the change-set
+ *   part's `nativeDigest`.
+ * - `run` hands that document and choudoufu's set digest to
+ *   `live-wave-apply`, which plans the root again and applies nothing when
+ *   the plan moved (exit 3).
+ * - choudoufu's resume file is kept in the fan-out's attempt record
+ *   (`DeployContext.carry`) after every apply, landed or not, and written
+ *   back on the next attempt when it was written for the same set digest.
+ *
+ * chant's waves stay the order. Each root is its own one-root set, so
+ * choudoufu's wave over it is always wave 1.
+ */
+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 } : {}) });
+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');
+    }
+}
+async function planRoot(input) {
+    requireRoot(input);
+    await terraformInit(rootArgs(input));
+    const planned = await terraformPlan({ ...rootArgs(input), ...(input.vars ? { vars: input.vars } : {}) });
+    return {
+        planFile: planned.planFile,
+        planDigest: planned.planDigest,
+        ...(planned.changeSet ? { changeSet: planned.changeSet } : {}),
+        json: planned.json,
+    };
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Whether an `after_unknown` value marks anything unknown: `true`, or `true` anywhere inside. */
+function anyUnknown(value) {
+    if (value === true)
+        return true;
+    if (Array.isArray(value))
+        return value.some(anyUnknown);
+    if (isRecord(value))
+        return Object.values(value).some(anyUnknown);
+    return false;
+}
+/**
+ * The outputs a root will have once the plan `json` (`show -json`) applies
+ * (#3999). An output is known when `planned_values.outputs` gives its value
+ * and its `output_changes` entry marks no part of it unknown after apply.
+ * Every other output the plan names is unknown, the whole output even when
+ * only a part of it is.
+ */
+export function terraformPlannedOutputs(json) {
+    const doc = isRecord(json) ? json : {};
+    const values = isRecord(doc.planned_values) && isRecord(doc.planned_values.outputs) ? doc.planned_values.outputs : {};
+    const changes = isRecord(doc.output_changes) ? doc.output_changes : {};
+    const known = {};
+    const unknown = [];
+    for (const name of [...new Set([...Object.keys(values), ...Object.keys(changes)])].sort()) {
+        const change = changes[name];
+        const planned = values[name];
+        if (isRecord(change) && anyUnknown(change.after_unknown))
+            unknown.push(name);
+        else if (isRecord(planned) && "value" in planned)
+            known[name] = planned.value;
+        else if (isRecord(change) && "after" in change)
+            known[name] = change.after;
+        else
+            unknown.push(name);
+    }
+    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.
+ */
+function waitingRoot(ctx, input, unresolved) {
+    const vars = Object.fromEntries(Object.entries(input.vars ?? {}).map(([k, v]) => [k, v === undefined ? null : v]));
+    const planDigest = computePlanDigest("terraform-apply-unresolved", { env: ctx.env, root: input.root, vars, unresolved });
+    const changeSet = {
+        member: {
+            member: input.root,
+            lexicon: "terraform",
+            planner: "chant",
+            status: "planned",
+            planDigest,
+            holes: [{ address: input.root, type: "terraform_root", reason: `inputs from ${unresolved.join(", ")}; planned again once they apply` }],
+        },
+        entries: [],
+    };
+    return { member: input.root, planDigest, changeSet };
+}
+/**
+ * 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).
+ */
+export class TerraformPlanMovedError extends Error {
+    constructor(root, message) {
+        super(message);
+        this.root = root;
+        this.planMoved = true;
+        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";
+}
+function isChoudoufuWavePlan(value) {
+    const v = value;
+    return (typeof v?.planDigest === "string" &&
+        typeof v.choudoufu?.planSetFile === "string" &&
+        typeof v.choudoufu.setDigest === "string");
+}
+/** Apply a choudoufu root through `live-wave-apply`, carrying its resume file either way. */
+async function runChoudoufuWave(ctx, input, planned) {
+    const applied = await choudoufuWaveApply({
+        ...rootArgs(input),
+        planSetFile: planned.choudoufu.planSetFile,
+        setDigest: planned.choudoufu.setDigest,
+        ...(ctx.carried?.[input.root] !== undefined ? { carried: ctx.carried[input.root] } : {}),
+    });
+    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);
+        throw new Error(message);
+    }
+    const outputs = await terraformOutputs(rootArgs(input));
+    return { root: input.root, planDigest: planned.planDigest, fromWavePlan: true, outputs };
+}
+export const terraformApplyCapability = {
+    kind: "terraform-apply",
+    // A root's apply has no undo short of applying the previous configuration,
+    // which is a change of its own. COMP003 asks the component to say so.
+    rollbackPolicy: "needs-opt-out",
+    async plan(ctx, input) {
+        requireRoot(input);
+        const unresolved = [...(ctx.unresolvedInputs ?? [])].sort();
+        if (unresolved.length > 0)
+            return waitingRoot(ctx, input, unresolved);
+        const wave = 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 },
+            };
+            return { member: input.root, planDigest: set.planDigest, artifact, changeSet: set.changeSet, outputs: terraformPlannedOutputs(set.json) };
+        }
+        const { changeSet, json, ...planned } = await planRoot(input);
+        return {
+            member: input.root,
+            planDigest: planned.planDigest,
+            artifact: planned,
+            ...(changeSet ? { changeSet } : {}),
+            outputs: terraformPlannedOutputs(json),
+        };
+    },
+    // The root's outputs as its state holds them now (#3183): what a dependent
+    // planned before this root applies reads through `stackOutput()`.
+    async outputs(_ctx, input) {
+        requireRoot(input);
+        await terraformInit(rootArgs(input));
+        return terraformOutputs(rootArgs(input));
+    },
+    async run(ctx, input) {
+        const fromWave = ctx.plans?.[input.root];
+        if (isChoudoufuWavePlan(fromWave))
+            return runChoudoufuWave(ctx, input, fromWave);
+        const planned = isPlannedRoot(fromWave) ? fromWave : await planRoot(input).then(({ planFile, planDigest }) => ({ planFile, planDigest }));
+        const applied = await terraformApply({ ...rootArgs(input), planFile: planned.planFile });
+        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);
+            throw new Error(message);
+        }
+        const outputs = await terraformOutputs(rootArgs(input));
+        return { root: input.root, planDigest: planned.planDigest, fromWavePlan: isPlannedRoot(fromWave), outputs };
+    },
+};
+export const TERRAFORM_VERB_FAMILIES = {
+    apply: ["terraform-apply"],
+};
+export const terraformCapabilityPlugin = {
+    name: "terraform",
+    get version() {
+        return ownPackageVersion(import.meta.url);
+    },
+    capabilities() {
+        return [terraformApplyCapability];
+    },
+    families() {
+        return TERRAFORM_VERB_FAMILIES;
+    },
+};

package/dist/composites/terraform-adopt-op.d.ts

@@ -137,6 +137,8 @@ export interface TerraformAdoptOpConfig {
      */
     compensate?: boolean | {
         command?: string;
+        /** Run the rollback command in a container pinned by digest (#4015), as `shell()`'s `image` does. */
+        image?: string;
     };
 }
 export interface TerraformAdoptOpResources {

package/dist/composites/terraform-adopt-op.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"terraform-adopt-op.d.ts","sourceRoot":"","sources":["../../src/composites/terraform-adopt-op.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2FG;AAEH,OAAO,EAA6B,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAQ5E,MAAM,WAAW,sBAAsB;IACrC,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,wGAAwG;IACxG,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qGAAqG;IACrG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED,MAAM,WAAW,yBAAyB;IACxC,wEAAwE;IACxE,EAAE,EAAE,YAAY,CAAC,OAAO,UAAU,CAAC,CAAC;CACrC;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,yBAAyB,CAkE1F"}
+{"version":3,"file":"terraform-adopt-op.d.ts","sourceRoot":"","sources":["../../src/composites/terraform-adopt-op.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2FG;AAEH,OAAO,EAA6B,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAQ5E,MAAM,WAAW,sBAAsB;IACrC,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,wGAAwG;IACxG,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qGAAqG;IACrG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG;QACrB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,qGAAqG;QACrG,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED,MAAM,WAAW,yBAAyB;IACxC,wEAAwE;IACxE,EAAE,EAAE,YAAY,CAAC,OAAO,UAAU,CAAC,CAAC;CACrC;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,yBAAyB,CAmE1F"}

package/dist/composites/terraform-adopt-op.js

@@ -0,0 +1,153 @@
+/**
+ * TerraformAdoptOp composite (#2105): claim the live resources a choudoufu
+ * estate's configuration already describes.
+ *
+ * The reconcile position on the lifecycle dial, for the one backend that has
+ * a typed path from live back to the configuration. chant #2089 deferred
+ * reconcile for the terraform lexicon because stock Terraform has none: a live
+ * resource nobody has imported is knowable only as HCL somebody writes, and
+ * generating that is a different problem. choudoufu changes the question
+ * rather than answering the old one. Ownership there is two tags on the
+ * resource (`live/MARKERS.md`), `live-plan` already names every live resource
+ * that exactly matches a declared block and carries no marker, and it prints
+ * the two values that would claim it. Cloud-to-code here is "claim what the
+ * configuration already describes" — a tag write, not a regeneration.
+ *
+ * Phases: Init, Check, Ledger, Gate, Adopt.
+ *
+ *   - **Init** runs `terraform init`, the same step `TerraformApplyOp` and
+ *     `TerraformWatchOp` open with. The Ledger step's `live-plan` needs the
+ *     provider schema to discover markers on the live resources it reads, and
+ *     a checkout that has never run `init` has no `.terraform` directory to
+ *     read one from — which is every fresh CI checkout, not a GitLab
+ *     peculiarity (#2302). Without this phase `live-plan` fails outright:
+ *     `Error: Provider unavailable for marker discovery`. This composite had
+ *     no Init phase because nothing had ever run `live-adopt` before
+ *     INTENTIUS/choudoufu#1026 did, so the gap survived every guard that only
+ *     read the generated YAML.
+ *   - **Check** runs `live-check`, which makes no cloud calls and says whether
+ *     this configuration can move under markers at all. It runs first because
+ *     a root that `live-check` refuses will produce an adoption ledger that
+ *     reads as authoritative and is not, and the cheapest place to find that
+ *     out is before the estate-wide sweep.
+ *   - **Ledger** runs `live-plan` with `adoptionOnly`, so the run's human half
+ *     is choudoufu's own adoption ledger (GitHub issue #587) and its machine
+ *     half is the bound/omissions/unowned document (#788). The ledger is the
+ *     approval subject; the document is what the Adopt step acts on.
+ *   - **Gate** always. Adoption writes tags onto resources this estate does
+ *     not yet own, which is the moment the estate's boundary moves, and no
+ *     reading of that is routine enough to skip. There is no `gate: "never"`
+ *     here, unlike `TerraformApplyOp`, so every run stops at the gate until
+ *     someone has approved it. A gate is a fact on the gate ledger (#2119):
+ *     `chant run` records that the run is waiting, ends with status `gated`
+ *     and exits 3, `chant approve <op> <gate>` writes the resolution, and the
+ *     next run reads it and walks through to the Adopt phase.
+ *   - **Adopt** writes the markers. See `choudoufuAdopt`'s own doc for the
+ *     mechanism and why it is the tag write rather than choudoufu's `adopt`
+ *     policy verb.
+ *
+ * ## The adopt mechanism, and why it is not the policy verb
+ *
+ * choudoufu's `policy` block has an `adopt` verb for the declared-but-unmarked
+ * quadrant, and its migration guide names `policy { declared_untagged =
+ * "adopt" }` as the way to claim a whole estate at once. That is the smaller
+ * write, and #2105 tried to reach it from outside the configuration. It is not
+ * reachable: a `live` block in a terraform override file is dropped in silence
+ * (choudoufu's `Module.mergeFile` has no `Lives` case), a second primary file
+ * carrying one is refused as a duplicate, and a sidecar beside an in-block
+ * form is refused as two sources of truth. What is left is editing the root's
+ * own checked-in live configuration around an apply, which leaves an estate
+ * declaring "adopt everything declared and unmarked" if the run dies between
+ * the two edits.
+ *
+ * So the mechanism is the tag write, which choudoufu's migration guide calls
+ * the whole contract: "There is no `choudoufu adopt` command and no need for
+ * one. Two tags is the whole contract, so any tool that writes two tags can
+ * adopt a resource." Each write runs the paste-ready command choudoufu itself
+ * printed in the ledger, carrying its own provider configuration's region and
+ * endpoint. `choudoufuAdopt` has the measurements behind that ruling.
+ *
+ * ## Ambiguity is reported, never resolved
+ *
+ * Two live resources at one declared identity are two `unowned` entries with
+ * the same address, and no single tag write claims that address. Those
+ * candidates never enter the adoptable set; the Adopt step is handed them
+ * separately so the Op's own result names what it declined and why, beside
+ * what it wrote.
+ *
+ * ## Compensation
+ *
+ * Refused without a command, the same stance `TerraformApplyOp` takes.
+ * Un-adopting is `untag`: dropping this estate's marker from a live resource,
+ * which is a decision about the estate rather than something chant can
+ * synthesize. It is also not always the right undo — a resource that was
+ * already carrying the markers before this run is not one this run adopted.
+ *
+ * @example
+ * ```typescript
+ * import { TerraformAdoptOp } from "@intentius/chant-lexicon-terraform";
+ *
+ * export const { op } = TerraformAdoptOp({ name: "estate-adopt", root: "estate" });
+ * ```
+ */
+import { Op, phase, gate, activity } from "@intentius/chant/op";
+import { terraformInit as initStep, choudoufuLiveCheck as checkStep, choudoufuLivePlan as ledgerStep, choudoufuAdopt as adoptStep, } from "../op/builders.js";
+export function TerraformAdoptOp(config) {
+    const compensateCommand = typeof config.compensate === "object" ? config.compensate.command : undefined;
+    const compensateImage = typeof config.compensate === "object" ? config.compensate.image : undefined;
+    if (config.compensate !== undefined && config.compensate !== false && compensateCommand === undefined) {
+        throw new Error(`TerraformAdoptOp "${config.name}": compensate is enabled, but there is no automatic undo for an ` +
+            `adoption — un-adopting is untag, removing this estate's ownership marker from a live resource, ` +
+            `which is a decision about the estate rather than something chant can synthesize, and which this ` +
+            `Op cannot scope for you (a resource that already carried the markers is not one this run ` +
+            `claimed). Either supply compensate: { command: "..." } with an undo of your own, or set ` +
+            `compensate: false.`);
+    }
+    const where = config.cwd ? { cwd: config.cwd } : {};
+    const estate = config.estate ? { estate: config.estate } : {};
+    const check = checkStep(config.root, { ...where });
+    check.outcomeAttribute = { name: "Refused", from: "refused" };
+    // `id` is what makes `.out` legal. The Adopt step below reads two fields of
+    // this one: the adoptable matches, and the contested candidates it must
+    // report and never write.
+    const ledger = ledgerStep(config.root, { ...where, ...estate, adoptionOnly: true, id: "ledger" });
+    ledger.outcomeAttribute = [
+        { name: "Adoptable", from: "adoptable" },
+        { name: "Ambiguous", from: "ambiguous" },
+    ];
+    const adopt = adoptStep(config.root, {
+        ...where,
+        adoptions: ledger.out.adoptions,
+        contested: ledger.out.contested,
+    });
+    adopt.outcomeAttribute = { name: "Adopted", from: "adoptedCount" };
+    const op = Op({
+        name: config.name,
+        overview: `Adopt the live resources the "${config.root}" choudoufu estate already declares`,
+        labels: {
+            Adopt: "true",
+            TerraformRoot: config.root,
+            TerraformMode: "live",
+        },
+        phases: [
+            phase("Init", [initStep(config.root, { ...where, ...(config.upgrade ? { upgrade: true } : {}) })]),
+            phase("Check", [check]),
+            phase("Ledger", [ledger]),
+            phase("Gate", [
+                gate(config.gateName ?? config.signalName ?? `approve-${config.name}`, {
+                    ...(config.gateTimeout ? { timeout: config.gateTimeout } : {}),
+                    description: config.gateDescription ??
+                        `Approve adopting live resources into the "${config.root}" estate. The Ledger phase's ` +
+                            `adoption ledger is what is being approved: every resource it lists as adoptable gets this ` +
+                            `estate's tofu-estate and tofu-address tags written onto it. The Adoptable and Ambiguous ` +
+                            `run outcomes from that phase are its counts; an ambiguous address is never adopted.`,
+                }),
+            ]),
+            phase("Adopt", [adopt]),
+        ],
+        ...(compensateCommand
+            ? { onFailure: [phase("Rollback", [activity("shellCmd", { cmd: compensateCommand, ...(compensateImage ? { image: compensateImage } : {}) })])] }
+            : {}),
+    });
+    return { op };
+}

package/dist/composites/terraform-apply-op.d.ts

@@ -148,6 +148,8 @@ export interface TerraformApplyOpConfig {
      */
     compensate?: boolean | {
         command?: string;
+        /** Run the rollback command in a container pinned by digest (#4015), as `shell()`'s `image` does. */
+        image?: string;
     };
 }
 export interface TerraformApplyOpResources {

package/dist/composites/terraform-apply-op.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"terraform-apply-op.d.ts","sourceRoot":"","sources":["../../src/composites/terraform-apply-op.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AAEH,OAAO,EAA6B,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAW/F;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,QAAQ,GAAG,OAAO,CAAC;AAElE,MAAM,WAAW,sBAAsB;IACrC,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,+GAA+G;IAC/G,IAAI,EAAE,MAAM,CAAC;IACb,0GAA0G;IAC1G,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qGAAqG;IACrG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED,MAAM,WAAW,yBAAyB;IACxC,mEAAmE;IACnE,EAAE,EAAE,YAAY,CAAC,OAAO,UAAU,CAAC,CAAC;CACrC;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,yBAAyB,CAiH1F"}
+{"version":3,"file":"terraform-apply-op.d.ts","sourceRoot":"","sources":["../../src/composites/terraform-apply-op.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AAEH,OAAO,EAA6B,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAW/F;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,QAAQ,GAAG,OAAO,CAAC;AAElE,MAAM,WAAW,sBAAsB;IACrC,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,+GAA+G;IAC/G,IAAI,EAAE,MAAM,CAAC;IACb,0GAA0G;IAC1G,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qGAAqG;IACrG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG;QACrB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,qGAAqG;QACrG,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED,MAAM,WAAW,yBAAyB;IACxC,mEAAmE;IACnE,EAAE,EAAE,YAAY,CAAC,OAAO,UAAU,CAAC,CAAC;CACrC;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,yBAAyB,CAkH1F"}

package/dist/composites/terraform-apply-op.js

@@ -0,0 +1,184 @@
+/**
+ * TerraformApplyOp composite (#2086), init, plan, approve, apply for one root
+ * module named in `terraform.roots`.
+ *
+ * Authority stays with terraform: chant runs the binary, reads its plan, and
+ * hands the same saved plan to apply. The Apply step never applies something
+ * no gate saw, because it takes the Plan step's own `planFile` as a
+ * `StepOutputRef`.
+ *
+ * Phases: Init, Plan, Gate, Apply. One shape, both kinds of root. A live root
+ * (#2103, `terraform.binary: "choudoufu"` plus a declared estate) ran a
+ * different shape for one release, because choudoufu refused `-out` and
+ * `apply <planfile>`; choudoufu v0.13.0 admits both under a `live` block
+ * ([choudoufu #878](https://github.com/INTENTIUS/choudoufu/issues/878),
+ * PR 889), so the plan-file discipline is back and the two shapes are one
+ * again.
+ *
+ * **What the approval covers on a live root.** `plan -out=<planFile>` writes
+ * stock's own plan file, and that file is what the approver reads and what
+ * the Apply step names. `apply <planFile>` does not replay it: prior state on
+ * a live root is a projection rebuilt from the live system every run, so the
+ * apply re-plans against the live system the way every live-markers run does,
+ * then compares its fresh plan with the file's. Same addresses, same actions,
+ * same live objects, and the same planned values, or it refuses before
+ * anything changes:
+ *
+ *   - `The approved plan no longer matches the live system`, and
+ *   - `The approved plan belongs to a different estate`,
+ *
+ * both with exit status **3**, which is neither 1 (any ordinary failure) nor
+ * `-detailed-exitcode`'s 2. `terraformApply` maps that status to a named
+ * result rather than a thrown error (`refused: "approval-mismatch" |
+ * "wrong-estate"`, with choudoufu's message in `refusal`), so a workflow
+ * reading the Apply step's output can route the run back to review instead of
+ * treating it as a broken step. The seam #2106 left named and unused on the
+ * apply args is now the plan file itself.
+ *
+ * TF101 therefore fires on a live root's `terraformApply` call again: there
+ * is a plan file to pair once more, and pairing it is what the refusal above
+ * has to compare against.
+ *
+ * **Delete modes.** chant's `delete: "never" | "owned-only" | "gated"`
+ * (`terraform.roots.<name>.delete`, `../config.ts`) maps onto choudoufu's
+ * `policy` block. `"owned-only"` is choudoufu's own default verb for the
+ * `undeclared_tagged` quadrant (an orphaned marked resource) and needs
+ * nothing; `"gated"` needs nothing beyond this composite's own approval gate;
+ * `"never"` requires the root's `policy` block to set `undeclared_tagged` to
+ * `"keep"`, `"untag"` or `"report"`, and TF026 (`../lint/post-synth/tf026.ts`)
+ * enforces that at build time, naming the setting to add. Separately, and
+ * regardless of `delete`, this composite refuses outright to build against a
+ * root whose `policy` sets `undeclared_untagged = "delete"` (account-scoped
+ * reconciliation, which needs a `scope` block): that quadrant deletes
+ * resources the estate never claimed, anywhere the scope reaches, and chant
+ * never proposes deleting a resource it does not own, not for a root, and not
+ * for an Op it generated.
+ *
+ * A gate is a fact on the gate ledger, not a wait (#2119). Reaching one,
+ * `chant run` consults the ledger (`packages/core/src/op/gate.ts`): a
+ * resolution recorded for this run's own plan lets the run walk through, and
+ * anything else records the pending fact and ends the run with status `gated`
+ * and exit 3. `chant approve <op> <gate>` writes the resolution, and the next
+ * run reads it. `gate: "never"` drops the Gate phase entirely, so a run never
+ * stops.
+ *
+ * **The gate binds the plan** (#2300). The Plan step publishes
+ * `planDigest` — its `terraform show -json` change set, hashed — and the Gate
+ * step references it, so the resolution names the plan it approves. That
+ * closes the window the exit-3 refusal above does not: exit 3 compares the
+ * Apply step's fresh plan against the *file* it was handed inside one run,
+ * and this compares a later run's fresh plan against what a human actually
+ * approved. INTENTIUS/choudoufu#1026 measured the gap by approving, renaming
+ * a resource, and re-running: the second run applied without complaint. It
+ * now stops, naming the approved digest and the planned one.
+ *
+ * @example
+ * ```typescript
+ * import { TerraformApplyOp } from "@intentius/chant-lexicon-terraform";
+ *
+ * export const { op } = TerraformApplyOp({ name: "app-apply", root: "app" });
+ * ```
+ */
+import { Op, phase, gate, activity } from "@intentius/chant/op";
+import { DEFAULT_PLAN_FILE } from "../op/activities/terraform.js";
+import { detectLivePolicyVerbs } from "../op/activities/live-detect.js";
+import { resolveRootModeSync } from "../op/resolve-root-mode.js";
+import { terraformInit as initStep, terraformPlan as planStep, terraformApply as applyStep, terraformShow as showStep, } from "../op/builders.js";
+export function TerraformApplyOp(config) {
+    const planFile = config.planFile ?? DEFAULT_PLAN_FILE;
+    const gateMode = config.gate ?? "on-destroy";
+    // Terraform has no rollback to run, so asking for one without supplying it
+    // fails here, at build time, with the Op named — not as a warning when the
+    // apply has already half-run. Same shape as ApplyOp's refusal (#1449).
+    const compensateCommand = typeof config.compensate === "object" ? config.compensate.command : undefined;
+    const compensateImage = typeof config.compensate === "object" ? config.compensate.image : undefined;
+    if (config.compensate !== undefined && config.compensate !== false && compensateCommand === undefined) {
+        throw new Error(`TerraformApplyOp "${config.name}": compensate is enabled, but terraform has no automatic ` +
+            `rollback — undoing a partial apply means planning and applying the inverse, which is a ` +
+            `decision about the estate rather than something chant can synthesize. Either supply ` +
+            `compensate: { command: "..." } with a rollback of your own, or set compensate: false.`);
+    }
+    // Every step resolves the root through the same project config, so the cwd
+    // travels with each of them rather than being read off the process once.
+    const where = config.cwd ? { cwd: config.cwd } : {};
+    // Best-effort, synchronous (chant.config.json only, see resolveRootModeSync's
+    // own doc comment). The mode no longer changes which steps are emitted; it
+    // words the gate below, and it decides whether the policy refusal is even
+    // asked. "Unknown" reads as stock, which for the gate wording is harmless
+    // and for the refusal is the permissive direction, so the refusal is not
+    // this function's to guarantee: on a chant.config.ts project, which is
+    // every project in this repository, the mode never resolves and the
+    // refusal below never runs (#2216).
+    const resolved = resolveRootModeSync(config.root, config.cwd);
+    const live = resolved?.mode === "live";
+    if (live) {
+        // Regardless of `delete`: an account-scoped purge is never something
+        // chant proposes on an Op's own initiative. TF026 handles the narrower,
+        // config-driven `delete: "never"` requirement; this is unconditional.
+        //
+        // TF027 (`../lint/post-synth/tf027.ts`) makes the same refusal off the
+        // parsed HCL, whatever the config file is written in, and is the check
+        // that guarantees it. This throw is kept for the projects whose mode does
+        // resolve here, where failing at the moment the Op is built names the Op
+        // as well as the root.
+        const verbs = detectLivePolicyVerbs(resolved.dir);
+        if (verbs?.undeclaredUntagged === "delete") {
+            throw new Error(`TerraformApplyOp "${config.name}": root "${config.root}"'s policy block sets ` +
+                `undeclared_untagged = "delete" (account-scoped reconciliation, scoped by a \`scope\` block). ` +
+                "chant never proposes deleting a resource it does not own, and neither does an Op it " +
+                "generates. Remove that setting from the policy block, or narrow the estate's ownership " +
+                "answer instead of the account's.");
+        }
+    }
+    const phases = [
+        phase("Init", [initStep(config.root, { ...where, ...(config.upgrade ? { upgrade: true } : {}) })]),
+    ];
+    // `id` is what makes `plan.out` legal, and `plan.out.planFile` is how the
+    // Apply step below names this step's saved plan. On a live root that file
+    // is also the approval artifact the apply re-plans against, so the same
+    // reference carries the approval as well as the path.
+    const plan = planStep(config.root, { planFile, ...where, id: "plan" });
+    plan.outcomeAttribute = { name: "Changed", from: "changed" };
+    phases.push(phase("Plan", [plan]));
+    if (gateMode !== "never") {
+        // Re-render the saved plan just before the gate, so the approver's
+        // `Destroys` attribute comes off the plan that will actually apply.
+        // `show` against a plan file calls no provider, on either kind of root.
+        const show = showStep(config.root, { ...where, planFile: plan.out.planFile });
+        show.outcomeAttribute = { name: "Destroys", from: "destroys" };
+        phases.push(phase("Gate", [
+            show,
+            gate(config.gateName ?? config.signalName ?? `approve-${config.name}`, {
+                ...(config.gateTimeout ? { timeout: config.gateTimeout } : {}),
+                // #2300: the approval is for this plan, not for the next run. The
+                // Plan step's digest rides onto the pending fact, `chant approve`
+                // copies it onto the resolution, and a later run whose fresh plan
+                // digests differently is refused with both digests named.
+                plan: plan.out.planDigest,
+                ...(config.gateApproval ? { approval: config.gateApproval } : {}),
+                description: config.gateDescription ??
+                    `Approve terraform apply of ${live ? "live " : ""}root "${config.root}" (gate: ${gateMode}). ` +
+                        `The Destroys run outcome from this phase is the plan's destroy count.` +
+                        (live
+                            ? " The apply that follows re-plans against the live system and applies this plan file only" +
+                                " if its own fresh plan agrees; otherwise it refuses with exit status 3 and the Apply" +
+                                " step reports a named refusal for review (choudoufu #878)."
+                            : ""),
+            }),
+        ]));
+    }
+    phases.push(phase("Apply", [applyStep(config.root, { ...where, planFile: plan.out.planFile })]));
+    const op = Op({
+        name: config.name,
+        overview: `Init, plan and apply the "${config.root}" terraform root`,
+        labels: {
+            Apply: "true",
+            TerraformRoot: config.root,
+        },
+        phases,
+        ...(compensateCommand
+            ? { onFailure: [phase("Rollback", [activity("shellCmd", { cmd: compensateCommand, ...(compensateImage ? { image: compensateImage } : {}) })])] }
+            : {}),
+    });
+    return { op };
+}