@intentius/chant-lexicon-terraform 0.124.31 → 0.124.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-terraform",
-  "version": "0.124.31",
+  "version": "0.124.33",
   "type": "module",
   "files": [
     "src/",
@@ -11,38 +11,38 @@
     ".": {
       "development": "./src/index.ts",
       "types": "./dist/index.d.ts",
-      "default": "./src/index.ts"
+      "default": "./dist/index.js"
     },
     "./workspace-kinds": "./workspace-kinds.json",
     "./*": {
       "development": "./src/*.ts",
       "types": "./dist/*.d.ts",
-      "default": "./src/*.ts"
+      "default": "./dist/*.js"
     },
     "./op/activities": {
       "development": "./src/op/activities/index.ts",
       "types": "./dist/op/activities/index.d.ts",
-      "default": "./src/op/activities/index.ts"
+      "default": "./dist/op/activities/index.js"
     },
     "./op/activity-contracts": {
       "development": "./src/op/activity-contracts.ts",
       "types": "./dist/op/activity-contracts.d.ts",
-      "default": "./src/op/activity-contracts.ts"
+      "default": "./dist/op/activity-contracts.js"
     },
     "./pin": {
       "development": "./src/pin/index.ts",
       "types": "./dist/pin/index.d.ts",
-      "default": "./src/pin/index.ts"
+      "default": "./dist/pin/index.js"
     },
     "./terragrunt": {
       "development": "./src/terragrunt/index.ts",
       "types": "./dist/terragrunt/index.d.ts",
-      "default": "./src/terragrunt/index.ts"
+      "default": "./dist/terragrunt/index.js"
     },
     "./lint/post-synth": {
       "development": "./src/lint/post-synth/index.ts",
       "types": "./dist/lint/post-synth/index.d.ts",
-      "default": "./src/lint/post-synth/index.ts"
+      "default": "./dist/lint/post-synth/index.js"
     },
     "./manifest": "./dist/manifest.json",
     "./meta": "./dist/meta.json",
@@ -52,7 +52,7 @@
     "generate": "npx tsx src/codegen/generate-cli.ts",
     "validate": "npx tsx src/validate-cli.ts",
     "docs": "npx tsx src/codegen/docs-cli.ts",
-    "build": "../../scripts/tsc7.sh -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && find dist -type f \\( -name \"*.js\" -o -name \"*.js.map\" \\) -delete",
+    "build": "../../scripts/tsc7.sh -p tsconfig.build.json --sourceMap false && tsc-alias -p tsconfig.build.json",
     "prepack": "npm run generate && npm run bundle && npm run validate && npm run build",
     "bundle": "tsx src/package-cli.ts"
   },
@@ -67,7 +67,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.31",
+    "@intentius/chant": "^0.124.33",
     "zod": "^4.3.6"
   },
   "description": "terraform lexicon for chant, existing Terraform root modules as declarable entities",

package/src/codegen/package.ts

@@ -1,6 +1,6 @@
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
-import { fileURLToPath } from "url";
+import { moduleSourceDir } from "@intentius/chant/module-source";
 import { packagePipeline, collectSkills } from "@intentius/chant/codegen/package";
 import { generate } from "./generate";
 import { terraformPlugin } from "../plugin";
@@ -12,7 +12,7 @@ import { terraformPlugin } from "../plugin";
  * `lint/rules` does not exist). `lexicons/aws/src/codegen/package.ts` resolves
  * it the same way.
  */
-const srcDir = dirname(dirname(fileURLToPath(import.meta.url)));
+const srcDir = dirname(moduleSourceDir(import.meta.url));
 
 /** The published version, so the manifest cannot drift from package.json. */
 function packageVersion(): string {

package/src/components/capability-plugin.test.ts

@@ -8,6 +8,7 @@ import { beforeEach, describe, expect, test, vi } from "vitest";
 const calls: string[] = [];
 let applyResult: Record<string, unknown> = { applied: true };
 let changeSet: Record<string, unknown> | undefined;
+let planJson: unknown;
 // #3459: whether the root goes through choudoufu's set commands, and what they answer.
 let waveRoot: { wave: true; root: string } | { wave: false; reason: string } = { wave: false, reason: "the root runs terraform" };
 let waveApply: Record<string, unknown> = { exitCode: 0, landed: true, message: "landed" };
@@ -39,7 +40,7 @@ vi.mock("../op/activities/terraform", () => ({
   }),
   terraformPlan: vi.fn(async (args: { root: string; vars?: Record<string, unknown> }) => {
     calls.push(`plan ${args.root} ${JSON.stringify(args.vars ?? {})}`);
-    return { planFile: "chant.tfplan", planDigest: `jcs1-sha256:${args.root}`, ...(changeSet ? { changeSet } : {}) };
+    return { planFile: "chant.tfplan", planDigest: `jcs1-sha256:${args.root}`, json: planJson, ...(changeSet ? { changeSet } : {}) };
   }),
   terraformApply: vi.fn(async (args: { root: string; planFile: string }) => {
     calls.push(`apply ${args.root} ${args.planFile}`);
@@ -51,12 +52,14 @@ vi.mock("../op/activities/terraform", () => ({
   }),
 }));
 
-const { terraformApplyCapability, terraformCapabilityPlugin } = await import("./capability-plugin");
+const { terraformApplyCapability, terraformCapabilityPlugin, terraformPlannedOutputs, TerraformPlanMovedError } = await import("./capability-plugin");
+const { isPlanMovedError } = await import("@intentius/chant/components/capability");
 
 beforeEach(() => {
   calls.length = 0;
   applyResult = { applied: true };
   changeSet = undefined;
+  planJson = undefined;
   waveRoot = { wave: false, reason: "the root runs terraform" };
   waveApply = { exitCode: 0, landed: true, message: "landed" };
   waveApplyArgs.length = 0;
@@ -124,6 +127,24 @@ describe("terraform-apply on a choudoufu root in a gated wave (#3459)", () => {
     expect(calls).toEqual(["wave-apply e01 sha256:set-e01"]);
     expect(kept).toEqual([carry]);
   });
+
+  test("a moved set throws core's plan-moved mark, so the command exits 3 (#3997)", async () => {
+    waveApply = { exitCode: 3, landed: false, message: "choudoufu refused the approved set" };
+    const err = await terraformApplyCapability
+      .run({ env: "test", component: "e01", plans: { e01: wavePlan } }, { root: "e01" })
+      .catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(TerraformPlanMovedError);
+    expect(isPlanMovedError(err)).toBe(true);
+  });
+
+  test("a root that could not land is an ordinary failure, not a moved plan", async () => {
+    waveApply = { exitCode: 4, landed: false, message: "choudoufu could not land the root" };
+    const err = await terraformApplyCapability
+      .run({ env: "test", component: "e01", plans: { e01: wavePlan } }, { root: "e01" })
+      .catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(Error);
+    expect(isPlanMovedError(err)).toBe(false);
+  });
 });
 
 describe("terraform-apply", () => {
@@ -137,10 +158,65 @@ describe("terraform-apply", () => {
       member: "app",
       planDigest: "jcs1-sha256:app",
       artifact: { planFile: "chant.tfplan", planDigest: "jcs1-sha256:app" },
+      outputs: { known: {}, unknown: [] },
     });
     expect(calls).toEqual(["init app", 'plan app {"vpc":"v-1"}']);
   });
 
+  test("plan answers the outputs the root will have, from the plan's planned values (#3999)", async () => {
+    planJson = {
+      planned_values: { outputs: { cidr: { sensitive: false, value: "10.1.0.0/16" }, id: { sensitive: false } } },
+      output_changes: {
+        cidr: { actions: ["update"], before: "10.0.0.0/16", after: "10.1.0.0/16", after_unknown: false },
+        id: { actions: ["create"], before: null, after_unknown: true },
+      },
+    };
+    const planned = await terraformApplyCapability.plan!({ env: "test", component: "net" }, { root: "net" });
+    expect(planned.outputs).toEqual({ known: { cidr: "10.1.0.0/16" }, unknown: ["id"] });
+    // The artifact `run` gets is still the plan file alone.
+    expect(planned.artifact).toEqual({ planFile: "chant.tfplan", planDigest: "jcs1-sha256:net" });
+  });
+
+  test("a root whose vars read outputs not known yet is not planned: a hole names whose (#3999)", async () => {
+    const ctx = { env: "test", component: "app", unresolvedInputs: ["net"] };
+    const planned = await terraformApplyCapability.plan!(ctx, { root: "app", vars: { vpc: undefined, name: "app" } });
+    expect(calls).toEqual([]);
+    expect(planned.artifact).toBeUndefined();
+    expect(planned.outputs).toBeUndefined();
+    expect(planned.changeSet?.entries).toEqual([]);
+    expect(planned.changeSet?.member.holes).toEqual([{ address: "app", type: "terraform_root", reason: "inputs from net; planned again once they apply" }]);
+    expect(planned.planDigest).toBe(planned.changeSet?.member.planDigest);
+    const again = await terraformApplyCapability.plan!(ctx, { root: "app", vars: { vpc: undefined, name: "app" } });
+    expect(again.planDigest).toBe(planned.planDigest);
+    const other = await terraformApplyCapability.plan!(ctx, { root: "app", vars: { vpc: undefined, name: "web" } });
+    expect(other.planDigest).not.toBe(planned.planDigest);
+  });
+});
+
+describe("terraformPlannedOutputs (#3999)", () => {
+  test("an output is known when its planned value is there and nothing in it is unknown after apply", () => {
+    expect(
+      terraformPlannedOutputs({
+        planned_values: { outputs: { a: { value: "x" }, b: { value: { k: 1 } }, c: {}, d: { value: null } } },
+        output_changes: {
+          a: { after: "x", after_unknown: false },
+          b: { after: { k: 1 }, after_unknown: { k: false, j: true } },
+          c: { after_unknown: true },
+          d: { after: null, after_unknown: false },
+        },
+      }),
+    ).toEqual({ known: { a: "x", d: null }, unknown: ["b", "c"] });
+  });
+
+  test("an output with no planned value and no change is unknown; a plan with no outputs has none", () => {
+    expect(terraformPlannedOutputs({ planned_values: { outputs: { a: { sensitive: true } } } })).toEqual({ known: {}, unknown: ["a"] });
+    expect(terraformPlannedOutputs({})).toEqual({ known: {}, unknown: [] });
+    expect(terraformPlannedOutputs(undefined)).toEqual({ known: {}, unknown: [] });
+  });
+});
+
+describe("terraform-apply, continued", () => {
+
   test("plan hands on the root's change-set part, outside the artifact run receives (#3183)", async () => {
     changeSet = { member: { member: "app" }, entries: [] };
     const planned = await terraformApplyCapability.plan!({ env: "test", component: "app" }, { root: "app" });
@@ -178,4 +254,23 @@ describe("terraform-apply", () => {
     ).rejects.toThrow(/refused the plan it was given \(approval-mismatch\)/);
     expect(calls).not.toContain("output app");
   });
+
+  test.each(["approval-mismatch", "wrong-estate"])(
+    "choudoufu's %s refusal of the wave's plan throws core's plan-moved mark, so the command exits 3 (#3997)",
+    async (refused) => {
+      applyResult = { applied: false, refused, refusal: "refused" };
+      const err = await terraformApplyCapability
+        .run({ env: "test", component: "app", plans: { app: { planFile: "chant.tfplan", planDigest: "d" } } }, { root: "app" })
+        .catch((e: unknown) => e);
+      expect(err).toBeInstanceOf(TerraformPlanMovedError);
+      expect(isPlanMovedError(err)).toBe(true);
+    },
+  );
+
+  test("a refusal of a plan this run made itself is an ordinary failure: the next run plans afresh", async () => {
+    applyResult = { applied: false, refused: "approval-mismatch", refusal: "refused" };
+    const err = await terraformApplyCapability.run({ env: "test", component: "app" }, { root: "app" }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(Error);
+    expect(isPlanMovedError(err)).toBe(false);
+  });
 });

package/src/components/capability-plugin.ts

@@ -20,12 +20,28 @@
  * 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.
+ * #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
@@ -49,8 +65,9 @@
  * choudoufu's wave over it is always wave 1.
  */
 
-import type { Capability, DeployContext, CapabilityPlan } from "@intentius/chant/components/capability";
+import type { Capability, DeployContext, CapabilityPlan, PlannedOutputs } from "@intentius/chant/components/capability";
 import type { ChangeSetPart } from "@intentius/chant/change-set";
+import { computePlanDigest } from "@intentius/chant/lifecycle/plan-digest";
 import { ownPackageVersion, type CapabilityPlugin } from "@intentius/chant/components/capability-plugin";
 import {
   choudoufuPlanSet,
@@ -96,7 +113,7 @@ function requireRoot(input: TerraformApplyStepInput): void {
   }
 }
 
-async function planRoot(input: TerraformApplyStepInput): Promise<PlannedRoot & { changeSet?: ChangeSetPart }> {
+async function planRoot(input: TerraformApplyStepInput): Promise<PlannedRoot & { changeSet?: ChangeSetPart; json?: unknown }> {
   requireRoot(input);
   await terraformInit(rootArgs(input));
   const planned = await terraformPlan({ ...rootArgs(input), ...(input.vars ? { vars: input.vars } : {}) });
@@ -104,9 +121,84 @@ async function planRoot(input: TerraformApplyStepInput): Promise<PlannedRoot & {
     planFile: planned.planFile,
     planDigest: planned.planDigest,
     ...(planned.changeSet ? { changeSet: planned.changeSet } : {}),
+    json: planned.json,
+  };
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** Whether an `after_unknown` value marks anything unknown: `true`, or `true` anywhere inside. */
+function anyUnknown(value: unknown): boolean {
+  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: unknown): PlannedOutputs {
+  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: Record<string, unknown> = {};
+  const unknown: string[] = [];
+  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: DeployContext, input: TerraformApplyStepInput, unresolved: string[]): CapabilityPlan {
+  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: ChangeSetPart = {
+    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 {
+  readonly planMoved = true;
+  constructor(public readonly root: string, message: string) {
+    super(message);
+    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: unknown): value is PlannedRoot {
   const v = value as Partial<PlannedRoot> | undefined;
   return typeof v?.planFile === "string" && typeof v.planDigest === "string";
@@ -141,7 +233,9 @@ async function runChoudoufuWave(
   });
   if (applied.carry) ctx.carry?.(input.root, applied.carry);
   if (!applied.landed) {
-    throw new Error(`terraform-apply: root "${input.root}": ${applied.message}`);
+    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 };
@@ -152,8 +246,10 @@ export const terraformApplyCapability: Capability<TerraformApplyStepInput, Terra
   // 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: DeployContext, input: TerraformApplyStepInput): Promise<CapabilityPlan> {
+  async plan(ctx: DeployContext, input: TerraformApplyStepInput): Promise<CapabilityPlan> {
     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));
@@ -161,10 +257,16 @@ export const terraformApplyCapability: Capability<TerraformApplyStepInput, Terra
         planDigest: set.planDigest,
         choudoufu: { planSetFile: set.planSetFile, setDigest: set.setDigest },
       };
-      return { member: input.root, planDigest: set.planDigest, artifact, changeSet: set.changeSet };
+      return { member: input.root, planDigest: set.planDigest, artifact, changeSet: set.changeSet, outputs: terraformPlannedOutputs(set.json) };
     }
-    const { changeSet, ...planned } = await planRoot(input);
-    return { member: input.root, planDigest: planned.planDigest, artifact: planned, ...(changeSet ? { changeSet } : {}) };
+    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()`.
@@ -176,13 +278,16 @@ export const terraformApplyCapability: Capability<TerraformApplyStepInput, Terra
   async run(ctx: DeployContext, input: TerraformApplyStepInput): Promise<TerraformApplyStepOutput> {
     const fromWave = ctx.plans?.[input.root];
     if (isChoudoufuWavePlan(fromWave)) return runChoudoufuWave(ctx, input, fromWave);
-    const planned: PlannedRoot = isPlannedRoot(fromWave) ? fromWave : await planRoot(input);
+    const planned: PlannedRoot = isPlannedRoot(fromWave) ? fromWave : await planRoot(input).then(({ planFile, planDigest }) => ({ planFile, planDigest }));
     const applied = await terraformApply({ ...rootArgs(input), planFile: planned.planFile });
     if (!applied.applied) {
-      throw new Error(
+      const message =
         `terraform-apply: root "${input.root}" refused the plan it was given (${applied.refused ?? "refused"}). ` +
-          (applied.refusal ?? ""),
-      );
+        (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 };

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

@@ -103,6 +103,9 @@ class FakeGithub {
       return ok({});
     }
     if ((m = path.match(/^\/pulls\/(\d+)\/reviews$/))) return ok(this.reviews[Number(m[1])] ?? []);
+    // #4000: the author and committers, whose own approval never counts.
+    if ((m = path.match(/^\/pulls\/(\d+)$/))) return ok({ number: Number(m[1]), user: { login: "ci" } });
+    if ((m = path.match(/^\/pulls\/(\d+)\/commits$/))) return ok([{ author: { login: "ci" }, committer: { login: "ci" } }]);
     if ((m = path.match(/^\/commits\/([0-9a-f]+)\/pulls$/))) {
       const pr = this.mergedBy[m[1]];
       return ok(pr ? [{ number: pr, merged_at: "2026-10-03T00:00:00Z", merge_commit_sha: m[1] }] : []);
@@ -194,12 +197,16 @@ describe.skipIf(!BINARY)(`the pull-request loop over five ${BINARY ?? "terraform
     return report("plan");
   }
 
+  /** The commit before the last merge, which a re-run of its apply measures from. */
+  let mergedFrom = "";
+  const RESUME = ".chant/pr-resume/pr-apply.json";
+
   async function merge(pr: number): Promise<number> {
     git("checkout", "-q", "main");
-    const before = git("rev-parse", "HEAD");
+    mergedFrom = git("rev-parse", "HEAD");
     git("merge", "-q", "--no-ff", `pr-${pr}`, "-m", `Merge pull request #${pr}`);
     github.mergedBy[git("rev-parse", "HEAD")] = pr;
-    return handlers.runComponentsPrApply(ctx({ base: before, forge: "github", requireReview: true }) as never);
+    return handlers.runComponentsPrApply(ctx({ base: mergedFrom, forge: "github", requireReview: true, resume: RESUME }) as never);
   }
 
   test("a change to one root plans that root and its dependent, and nothing else", async () => {
@@ -207,34 +214,67 @@ describe.skipIf(!BINARY)(`the pull-request loop over five ${BINARY ?? "terraform
 
     expect(plan.status).toBe("planned");
     expect(plan.selection).toMatchObject({ changed: ["a"], dependents: ["app"], waves: [["a"], ["app"]] });
-    expect(plan.members.map((m) => [m.member, m.counts.update])).toEqual([
-      ["a", 1],
-      ["app", 0],
+    // a's id is terraform_data's output, which tofu knows only after apply,
+    // so app is not planned against the id a has now (#3999): the note says
+    // the approval does not cover what app does with it.
+    expect(plan.members.map((m) => [m.member, m.counts.update, m.unknownInputs])).toEqual([
+      ["a", 1, undefined],
+      ["app", 0, ["a.id"]],
+    ]);
+    expect(plan.changeSet.members.find((m) => m.member === "app")?.holes).toEqual([
+      { address: "app", type: "terraform_root", reason: "inputs from a; planned again once they apply" },
     ]);
+    expect(plan.plannedOutputs).toEqual({ a: [] });
+    expect(plan.deployedOutputs).toEqual({ net: ["cidr"] });
     expect(plan.changeSet.digest).toBe(plan.digest);
     expect(plan.approval).toEqual({ status: "pending" });
 
     const note = github.comments.find((c) => c.pr === 1)!;
     expect(note.body.startsWith("<!-- chant-pr:local -->")).toBe(true);
     expect(note.body).toContain(`chant approve pr-1 pr-apply --plan ${plan.digest} --approver github:<your-login> --sign`);
+    expect(note.body).toContain("Known only after apply: `app` reads `a.id`.");
     expect(github.statuses.at(-1)).toMatchObject({ context: "chant/plan", state: "success", sha: plan.head });
   }, 240_000);
 
-  test("on merge it applies the plan the reviewer approved", async () => {
+  test("on merge it applies the plan the reviewer approved, and plans the dependent again once its upstream applied (#3999)", async () => {
     const plan = report("plan");
     github.reviews[1] = [{ user: { login: "alice" }, state: "APPROVED" }];
     expect((await recordGateApproval("pr-1", "pr-apply", { actor: "github:alice", plan: plan.digest })).ok).toBe(true);
 
-    expect(await merge(1)).toBe(0);
+    // a applies; app, planned now against the id a applied as, waits on its own gate.
+    expect(await merge(1)).toBe(3);
+    const waiting = report("apply");
+    expect(waiting.digest).toBe(plan.digest);
+    expect(waiting.status).toBe("waiting");
+    expect(waiting.members.map((m) => [m.member, m.status, m.round])).toEqual([
+      ["a", "applied", undefined],
+      ["app", "waiting", 2],
+    ]);
+    const round = waiting.rounds![0]!;
+    expect(round).toMatchObject({ round: 2, gate: "pr-apply-round-2", components: ["app"], status: "waiting", approval: { status: "pending" } });
+    expect(round.changeSet.entries.map((e) => [e.member, e.address, e.action])).toEqual([["app", "terraform_data.app", "update"]]);
+    expect(state("a")).toContain("10.0.0.0/16/a-v2");
+    expect(state("app")).not.toContain("a-v2");
+    expect(github.statuses.at(-1)).toMatchObject({ context: "chant/apply", state: "pending" });
+    expect(github.comments.find((c) => c.pr === 1)!.body).toContain(`chant approve pr-1 pr-apply-round-2 --plan ${round.digest}`);
+  }, 240_000);
+
+  test("once the reviewer approves the round's plan, the same apply carries on from its record and applies the dependent (#3999)", async () => {
+    const plan = report("plan");
+    const round = report("apply").rounds![0]!;
+    expect((await recordGateApproval("pr-1", "pr-apply-round-2", { actor: "github:alice", plan: round.digest })).ok).toBe(true);
+    expect(await handlers.runComponentsPrApply(ctx({ base: mergedFrom, forge: "github", requireReview: true, resume: RESUME }) as never)).toBe(0);
     const applied = report("apply");
     expect(applied.digest).toBe(plan.digest);
     expect(applied.status).toBe("applied");
     expect(applied.approval).toEqual({ status: "approved", approvedBy: ["github:alice"] });
-    expect(applied.members.map((m) => [m.member, m.status, m.inputsMoved])).toEqual([
+    expect(applied.resumed).toEqual({ applied: ["a"] });
+    expect(applied.members.map((m) => [m.member, m.status, m.round])).toEqual([
       ["a", "applied", undefined],
-      ["app", "applied", ["a"]],
+      ["app", "applied", 2],
     ]);
-    expect(state("a")).toContain("10.0.0.0/16/a-v2");
+    expect(applied.rounds?.map((r) => [r.digest, r.status, r.approval.approvedBy])).toEqual([[round.digest, "applied", ["github:alice"]]]);
+    expect(state("app")).toContain("app on 10.0.0.0/16/a-v2");
     // The same note, now with the apply's outcome.
     expect(github.comments.filter((c) => c.pr === 1)).toHaveLength(1);
     expect(github.comments.find((c) => c.pr === 1)!.body).toContain("### chant apply for `local`");
@@ -251,9 +291,9 @@ describe.skipIf(!BINARY)(`the pull-request loop over five ${BINARY ?? "terraform
     expect(stored.digest).toBe(applied.digest);
     expect(stored.graph).toEqual({ member: null, at: applied.head });
     // The plan's addresses, each on the block the terraform lexicon's graph names `<root>/<address>`.
+    // app's plan had a hole for a's id, and no entries.
     expect(stored.entries.map((e) => [e.member, e.address, e.action, e.node])).toEqual([
       ["a", "terraform_data.subnet", "update", "a/terraform_data.subnet"],
-      ["app", "terraform_data.app", "no-op", "app/terraform_data.app"],
     ]);
     // And those are ids the estate's graph has.
     const graph = await estateGraphIds(dir);

package/src/composites/terraform-adopt-op.test.ts

@@ -176,6 +176,12 @@ describe("TerraformAdoptOp compensation (#2105)", () => {
     expect((op.onFailure![0].steps[0] as ActivityStep).args?.cmd).toBe("./untag.sh");
   });
 
+  test("a supplied image runs the rollback in that container (#4015)", () => {
+    const image = `alpine:3.20@sha256:${"b".repeat(64)}`;
+    const op = props({ ...base, compensate: { command: "./untag.sh", image } });
+    expect((op.onFailure![0].steps[0] as ActivityStep).args).toEqual({ cmd: "./untag.sh", image });
+  });
+
   test("compensate: false and omitting it both leave no onFailure", () => {
     expect(props(base).onFailure).toBeUndefined();
     expect(props({ ...base, compensate: false }).onFailure).toBeUndefined();

package/src/composites/terraform-adopt-op.ts

@@ -143,7 +143,11 @@ export interface TerraformAdoptOpConfig {
    * object with no `command`, throws when the Op is built, naming the Op,
    * rather than warning at the moment a rollback is already wanted.
    */
-  compensate?: boolean | { command?: string };
+  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 {
@@ -153,6 +157,7 @@ export interface TerraformAdoptOpResources {
 
 export function TerraformAdoptOp(config: TerraformAdoptOpConfig): TerraformAdoptOpResources {
   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 ` +
@@ -212,7 +217,7 @@ export function TerraformAdoptOp(config: TerraformAdoptOpConfig): TerraformAdopt
       phase("Adopt", [adopt]),
     ],
     ...(compensateCommand
-      ? { onFailure: [phase("Rollback", [activity("shellCmd", { cmd: compensateCommand })])] }
+      ? { onFailure: [phase("Rollback", [activity("shellCmd", { cmd: compensateCommand, ...(compensateImage ? { image: compensateImage } : {}) })])] }
       : {}),
   });
 

package/src/composites/terraform-apply-op.test.ts

@@ -179,6 +179,12 @@ describe("TerraformApplyOp compensation — total or refused (#2086)", () => {
       args: { cmd: "terraform apply -input=false rollback.tfplan" },
     });
   });
+
+  test("compensate: { command, image } runs the rollback in that image (#4015)", () => {
+    const image = `hashicorp/terraform:1.9@sha256:${"a".repeat(64)}`;
+    const op = props({ name: "a", root: "app", compensate: { command: "terraform apply rollback.tfplan", image } });
+    expect(op.onFailure![0].steps[0]).toMatchObject({ fn: "shellCmd", args: { cmd: "terraform apply rollback.tfplan", image } });
+  });
 });
 
 describe("TerraformApplyOp on the local executor (#2086, gate-as-fact #2119)", () => {

package/src/composites/terraform-apply-op.ts

@@ -158,7 +158,11 @@ export interface TerraformApplyOpConfig {
    * rollback is already needed. Supply `compensate: { command: "..." }` with a
    * rollback of your own, or leave it unset.
    */
-  compensate?: boolean | { command?: string };
+  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 {
@@ -174,6 +178,7 @@ export function TerraformApplyOp(config: TerraformApplyOpConfig): TerraformApply
   // 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 ` +
@@ -274,7 +279,7 @@ export function TerraformApplyOp(config: TerraformApplyOpConfig): TerraformApply
     },
     phases,
     ...(compensateCommand
-      ? { onFailure: [phase("Rollback", [activity("shellCmd", { cmd: compensateCommand })])] }
+      ? { onFailure: [phase("Rollback", [activity("shellCmd", { cmd: compensateCommand, ...(compensateImage ? { image: compensateImage } : {}) })])] }
       : {}),
   });
 

package/src/index.ts

@@ -8,6 +8,7 @@ export { terraformPlugin } from "./plugin";
 export {
   terraformCapabilityPlugin,
   terraformApplyCapability,
+  TerraformPlanMovedError,
   TERRAFORM_VERB_FAMILIES,
   type TerraformApplyStepInput,
   type TerraformApplyStepOutput,