@intentius/chant-lexicon-terraform 0.57.0 → 0.58.0

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

@@ -0,0 +1,166 @@
+/**
+ * The acceptance test is choudoufu, not a fixture (#2105): adopt a live
+ * resource nothing has marked, end to end.
+ *
+ * `terraform-adopt-op.test.ts` next door proves the shape chant emits.
+ * `choudoufu.test.ts` proves the activities' contract against a stubbed child
+ * process. This proves the shape does the thing: create an unmarked VPC
+ * directly against choudoufu's pinned emulator, so it is a live resource this
+ * estate does not own at an identity this root's configuration declares; run
+ * the Ledger step and expect exactly one adoptable match with the two marker
+ * values on it; run the Adopt step and let it write them; re-plan and expect
+ * the estate to own the same VPC, with nothing left adoptable.
+ *
+ * The Op's phases are not run through `runOpLocally` here, deliberately.
+ * `TerraformAdoptOp` always emits a gate — adoption moves the estate's
+ * boundary, and there is no ungated form — so a local run would stop at the
+ * gate and record a pending fact rather than reach the Adopt phase
+ * (`packages/core/src/op/gate.ts`). So this drives the two activities the Op's
+ * Ledger and Adopt phases are built from, in the same order and with the same
+ * hand-off, which is the part a real binary can falsify. `choudoufu.acceptance.test.ts` takes the same approach for the same
+ * reason.
+ *
+ * ## Why this skips today
+ *
+ * choudoufu#894: `live-plan -json` is reachable only through the `-estate`
+ * form, and that form is refused on a configuration that names its own estate
+ * ("Estate named by both the live block and -estate"), while the same root
+ * without `-estate` refuses with "Machine-readable output is not available
+ * under live resource markers yet". The one configuration shape choudoufu's
+ * own docs lead with is the one shape the #788 document cannot be produced
+ * for, so `choudoufuLivePlan` throws on any real live root until that lands.
+ * Found by chant #2104 against a source build at HEAD.
+ *
+ * The gate below names it, alongside the ordinary two: no binary, and no
+ * emulator. When #894 ships, drop `CHOUDOUFU_894_OPEN` and this suite runs as
+ * written.
+ *
+ * Gating copied from `./terraform-apply-op.acceptance.test.ts` (`onPath`),
+ * which in turn copies `lexicons/k3s/src/serializer.acceptance.test.ts`'s
+ * pattern of skipping with the reason named in the describe title rather than
+ * failing when the real dependency is absent.
+ */
+
+import { execSync } from "node:child_process";
+import { cpSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, it } from "vitest";
+import { choudoufuAdopt, choudoufuLivePlan, terraformInit } from "../op/activities/terraform";
+
+function onPath(cmd: string): boolean {
+  try {
+    execSync(`command -v ${cmd}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * https://github.com/INTENTIUS/choudoufu/issues/894. Flip to `false` when the
+ * `-json` document becomes reachable on a root that declares its own estate.
+ * chant #2168 tracks this and the other four reversals that unblock together.
+ */
+const CHOUDOUFU_894_OPEN = true;
+
+const emulatorEndpoint = process.env.CHOUDOUFU_EMULATOR_ENDPOINT;
+
+const skipReason = !onPath("choudoufu")
+  ? "no choudoufu binary on PATH"
+  : !onPath("aws")
+    ? "no aws CLI on PATH (the unmarked resource is created with it, and adopted through it)"
+    : !emulatorEndpoint
+      ? "CHOUDOUFU_EMULATOR_ENDPOINT is not set (bring up choudoufu's `just smoke` emulator stack and export it)"
+      : CHOUDOUFU_894_OPEN
+        ? "choudoufu#894: live-plan -json is refused on a configuration that declares its own estate, " +
+          "so there is no adoption ledger to act on yet"
+        : "";
+
+const FIXTURE = join(import.meta.dirname, "..", "__fixtures__", "live-adopt");
+const ESTATE = "chant-adopt-fixture";
+const CIDR = "10.77.0.0/16";
+const workspaces: string[] = [];
+
+afterAll(() => {
+  for (const dir of workspaces) rmSync(dir, { recursive: true, force: true });
+});
+
+/** A fresh copy of the live-adopt fixture, wired up with a real project config. */
+function project(): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-adopt-accept-"));
+  workspaces.push(dir);
+  cpSync(FIXTURE, join(dir, "root"), { recursive: true });
+  writeFileSync(
+    join(dir, "chant.config.json"),
+    JSON.stringify(
+      { lexicons: ["terraform"], terraform: { binary: "choudoufu", roots: { estate: { dir: "./root" } } } },
+      null,
+      2,
+    ),
+  );
+  return dir;
+}
+
+describe.skipIf(skipReason !== "")(
+  `TerraformAdoptOp adopts an unmarked live resource${skipReason ? ` (skipped: ${skipReason})` : ""}`,
+  () => {
+    it(
+      "ledgers one adoptable VPC, writes its two markers, and re-plans with it owned",
+      { timeout: 600_000 },
+      async () => {
+        const dir = project();
+
+        process.env.AWS_ENDPOINT_URL ??= emulatorEndpoint;
+        process.env.AWS_ACCESS_KEY_ID ??= "choudoufu-emulator";
+        process.env.AWS_SECRET_ACCESS_KEY ??= "choudoufu-emulator";
+        process.env.AWS_DEFAULT_REGION ??= "us-east-1";
+
+        // The stock-created resource: a VPC at the cidr this root declares,
+        // carrying no ownership marker at all. Nothing about it says which
+        // configuration made it, which is exactly the migration situation.
+        execSync(
+          `aws ec2 create-vpc --cidr-block ${CIDR} --endpoint-url ${emulatorEndpoint} --region us-east-1`,
+          { stdio: "pipe" },
+        );
+
+        await terraformInit({ root: "estate", cwd: dir });
+
+        const ledger = await choudoufuLivePlan({ root: "estate", cwd: dir, adoptionOnly: true });
+        expect(ledger.estate).toBe(ESTATE);
+        expect(ledger.contested).toEqual([]);
+        expect(ledger.adoptions).toHaveLength(1);
+        const [candidate] = ledger.adoptions;
+        expect(candidate.addr).toBe("aws_vpc.adoptable");
+        expect(candidate.markerEstate).toBe(ESTATE);
+        expect(candidate.markerAddress).toBe("aws_vpc.adoptable");
+        // A VPC is tagged through `ec2 create-tags`, which choudoufu prints a
+        // command for; a candidate with none would be refused below instead.
+        expect(candidate.command).toContain("create-tags");
+        expect(ledger.ledger).toContain("aws_vpc.adoptable <- aws_vpc vpc-");
+
+        const adopted = await choudoufuAdopt({
+          root: "estate",
+          cwd: dir,
+          adoptions: ledger.adoptions,
+          contested: ledger.contested,
+        });
+        expect(adopted.mechanism).toBe("tag-write");
+        expect(adopted.adopted).toEqual(["aws_vpc.adoptable"]);
+        expect(adopted.refused).toEqual([]);
+
+        // The markers are the whole ownership answer, so a re-plan binds the
+        // same live VPC instead of proposing a second one: nothing is left
+        // unowned at this estate's declared identity, and nothing adoptable.
+        const after = await choudoufuLivePlan({ root: "estate", cwd: dir });
+        expect(after.adoptable).toBe(0);
+        expect(after.unowned).toBe(0);
+        expect(after.adoptions).toEqual([]);
+
+        // And the estate now says so: the VPC is bound at the declared address.
+        const bound = (after.json as { bound?: Array<{ addr?: string; identity?: string }> }).bound ?? [];
+        expect(bound.map((b) => b.addr)).toContain("aws_vpc.adoptable");
+      },
+    );
+  },
+);

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

@@ -0,0 +1,170 @@
+/**
+ * TerraformAdoptOp composite tests (#2105): the four phases, the gate that is
+ * always there, the two references the Adopt step takes off the ledger, and
+ * the rule an adoption Op exists to keep — an ambiguous match is reported and
+ * never written.
+ */
+
+import { describe, test, expect } from "vitest";
+import {
+  collectStepOutputRefs,
+  isStepOutputRef,
+  type ActivityStep,
+  type GateStep,
+  type OpConfig,
+  type StepDefinition,
+} from "@intentius/chant/op";
+
+import { TerraformAdoptOp } from "./terraform-adopt-op";
+
+function props(config: Parameters<typeof TerraformAdoptOp>[0]): OpConfig {
+  return (TerraformAdoptOp(config).op as unknown as { props: OpConfig }).props;
+}
+
+const phaseNames = (op: OpConfig): string[] => op.phases.map((p) => p.name);
+const isActivity = (s: StepDefinition): s is ActivityStep => s.kind === "activity";
+const steps = (op: OpConfig): ActivityStep[] => op.phases.flatMap((p) => p.steps.filter(isActivity));
+const base = { name: "estate-adopt", root: "estate" };
+
+describe("TerraformAdoptOp phases (#2105)", () => {
+  test("Check, Ledger, Gate, Adopt, in that order", () => {
+    const op = props(base);
+    expect(phaseNames(op)).toEqual(["Check", "Ledger", "Gate", "Adopt"]);
+    expect(steps(op).map((s) => s.fn)).toEqual(["choudoufuLiveCheck", "choudoufuLivePlan", "choudoufuAdopt"]);
+  });
+
+  test("Check runs live-check first, and reports whether the root was refused", () => {
+    const check = props(base).phases[0].steps[0] as ActivityStep;
+    expect(check.fn).toBe("choudoufuLiveCheck");
+    expect(check.outcomeAttribute).toEqual({ name: "Refused", from: "refused" });
+    // No cloud calls, so this is the cheapest place to learn the root cannot
+    // move under markers at all.
+    expect(check.profile).toBe("fastIdempotent");
+  });
+
+  test("Ledger is the -adoption-only live plan, and publishes both counts", () => {
+    const ledger = props(base).phases[1].steps[0] as ActivityStep;
+    expect(ledger.fn).toBe("choudoufuLivePlan");
+    expect(ledger.id).toBe("ledger");
+    expect(ledger.args?.adoptionOnly).toBe(true);
+    expect(ledger.outcomeAttribute).toEqual([
+      { name: "Adoptable", from: "adoptable" },
+      { name: "Ambiguous", from: "ambiguous" },
+    ]);
+  });
+
+  test("every step names the configured root", () => {
+    for (const step of steps(props(base))) expect(step.args?.root).toBe("estate");
+  });
+
+  test("cwd rides every step, and no cwd means no cwd arg", () => {
+    for (const step of steps(props({ ...base, cwd: "/repo" }))) expect(step.args?.cwd).toBe("/repo");
+    for (const step of steps(props(base))) expect(step.args && "cwd" in step.args).toBe(false);
+  });
+
+  test("an explicit estate rides the Ledger step only", () => {
+    const op = props({ ...base, estate: "prod-networking" });
+    expect((op.phases[1].steps[0] as ActivityStep).args?.estate).toBe("prod-networking");
+    expect((op.phases[0].steps[0] as ActivityStep).args?.estate).toBeUndefined();
+  });
+});
+
+describe("TerraformAdoptOp gates on the ledger (#2105)", () => {
+  const gateOf = (op: OpConfig): GateStep => {
+    const step = op.phases[2].steps[0];
+    expect(step.kind).toBe("gate");
+    return step as GateStep;
+  };
+
+  test("the gate is always emitted: there is no ungated adoption", () => {
+    // Unlike TerraformApplyOp there is no `gate: "never"` here. Adoption moves
+    // the estate's boundary onto resources it did not own, which is not a
+    // thing to do unattended.
+    expect(gateOf(props(base)).signalName).toBe("approve-estate-adopt");
+    expect(Object.keys(TerraformAdoptOp(base))).toEqual(["op"]);
+  });
+
+  test("the description names the ledger as the approval subject", () => {
+    const description = gateOf(props(base)).description!;
+    expect(description).toContain("adoption ledger");
+    expect(description).toContain("tofu-estate and tofu-address");
+    expect(description).toContain("an ambiguous address is never adopted");
+  });
+
+  test("signal name, timeout and description are overridable", () => {
+    const gate = gateOf(props({ ...base, signalName: "ok", gateTimeout: "2h", gateDescription: "mine" }));
+    expect(gate).toMatchObject({ signalName: "ok", timeout: "2h", description: "mine" });
+  });
+
+  test("no timeout given means the gate carries none, so core's own default applies", () => {
+    expect(gateOf(props(base)).timeout).toBeUndefined();
+  });
+});
+
+describe("TerraformAdoptOp adopts the ledger's matches and nothing else (#2105)", () => {
+  const adoptStep = (op: OpConfig): ActivityStep => op.phases[3].steps[0] as ActivityStep;
+
+  test("the Adopt step takes the ledger's adoptable set by reference", () => {
+    const adopt = adoptStep(props(base));
+    expect(adopt.fn).toBe("choudoufuAdopt");
+    expect(isStepOutputRef(adopt.args?.adoptions)).toBe(true);
+    expect(adopt.args?.adoptions).toMatchObject({ step: "ledger", path: "adoptions" });
+  });
+
+  test("an ambiguous match is handed over as `contested`, which is a separate field from `adoptions`", () => {
+    // `readAdoptionLedger` never puts a contested candidate in `adoptions`, so
+    // the Adopt step cannot write one however it behaves; `contested` is
+    // passed so the Op's own result names what it declined and why.
+    const adopt = adoptStep(props(base));
+    expect(adopt.args?.contested).toMatchObject({ step: "ledger", path: "contested" });
+    expect(adopt.args?.contested).not.toEqual(adopt.args?.adoptions);
+  });
+
+  test("the Adopt step reports how many resources it claimed", () => {
+    expect(adoptStep(props(base)).outcomeAttribute).toEqual({ name: "Adopted", from: "adoptedCount" });
+  });
+
+  test("the Op references exactly the two ledger fields and no document", () => {
+    const op = props(base);
+    const refs = op.phases.flatMap((p) => p.steps.filter(isActivity)).flatMap((s) => collectStepOutputRefs(s.args));
+    expect(refs.map((r) => r.path).sort()).toEqual(["adoptions", "contested"]);
+    expect(refs.every((r) => r.step === "ledger")).toBe(true);
+    // The bound/omissions/unowned document never leaves the Ledger step.
+    expect(JSON.stringify(op)).not.toContain('"json"');
+  });
+});
+
+describe("TerraformAdoptOp compensation (#2105)", () => {
+  test("compensate: true throws, because un-adopting is untag", () => {
+    expect(() => TerraformAdoptOp({ ...base, compensate: true })).toThrow(/un-adopting is untag/);
+  });
+
+  test("an object with no command throws the same way", () => {
+    expect(() => TerraformAdoptOp({ ...base, compensate: {} })).toThrow(/TerraformAdoptOp "estate-adopt"/);
+  });
+
+  test("a supplied command becomes an onFailure Rollback phase", () => {
+    const op = props({ ...base, compensate: { command: "./untag.sh" } });
+    expect(op.onFailure?.map((p) => p.name)).toEqual(["Rollback"]);
+    expect((op.onFailure![0].steps[0] as ActivityStep).args?.cmd).toBe("./untag.sh");
+  });
+
+  test("compensate: false and omitting it both leave no onFailure", () => {
+    expect(props(base).onFailure).toBeUndefined();
+    expect(props({ ...base, compensate: false }).onFailure).toBeUndefined();
+  });
+});
+
+describe("TerraformAdoptOp labels (#2105, #2118)", () => {
+  test("marks the Op as an adoption on a live root", () => {
+    expect(props(base).labels).toEqual({
+      Adopt: "true",
+      TerraformRoot: "estate",
+      TerraformMode: "live",
+    });
+  });
+
+  test("no task queue rides on the Op (#2118)", () => {
+    expect(props(base)).not.toHaveProperty("taskQueue");
+  });
+});

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

@@ -0,0 +1,197 @@
+/**
+ * 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: Check, Ledger, Gate, Adopt.
+ *
+ *   - **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, OpResource } from "@intentius/chant/op";
+import {
+  choudoufuLiveCheck as checkStep,
+  choudoufuLivePlan as ledgerStep,
+  choudoufuAdopt as adoptStep,
+} from "../op/builders";
+
+export interface TerraformAdoptOpConfig {
+  /** Op name (kebab-case). `signalName` defaults to `approve-<name>`. */
+  name: string;
+  /** Key into the project's `terraform.roots`. Must be a live root: choudoufu, with a declared estate. */
+  root: string;
+  /**
+   * The estate whose markers this run looks for. Omitted, `choudoufuLivePlan`
+   * auto-detects it from the root's own `live` block or `estate.chdf.hcl`
+   * sidecar, which is the usual case.
+   */
+  estate?: string;
+  /** Gate signal name. Default: `approve-<name>`, as `TerraformApplyOp` does. */
+  signalName?: string;
+  /** How long a recorded pending gate stays valid, as a duration string. Default: core's own (48h). */
+  gateTimeout?: string;
+  /** Override the gate description shown to the approver. */
+  gateDescription?: string;
+  /**
+   * Directory each step starts the `chant.config.*` search from, which is what
+   * `terraform.roots` and the root's relative `dir` resolve against. Default:
+   * the running process's cwd.
+   */
+  cwd?: string;
+  /**
+   * Saga-style rollback on a failed adoption, run as an `onFailure` phase.
+   *
+   * Refused without a command. Undoing an adoption is `untag` — removing this
+   * estate's marker from a live resource — which is a decision about the
+   * estate, and one this Op cannot even scope correctly: a resource that
+   * already carried the markers is not one this run claimed. So `true`, or an
+   * 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 };
+}
+
+export interface TerraformAdoptOpResources {
+  /** Op resource. Generates the Check/Ledger/Gate/Adopt workflow. */
+  op: InstanceType<typeof OpResource>;
+}
+
+export function TerraformAdoptOp(config: TerraformAdoptOpConfig): TerraformAdoptOpResources {
+  const compensateCommand = typeof config.compensate === "object" ? config.compensate.command : 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("Check", [check]),
+      phase("Ledger", [ledger]),
+      phase("Gate", [
+        gate(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 })])] }
+      : {}),
+  });
+
+  return { op };
+}