@intentius/chant-lexicon-terraform 0.58.0 → 0.60.0

package/src/__fixtures__/ACCEPTANCE.md

@@ -0,0 +1,181 @@
+# What the gated acceptance suites have actually run against
+
+Four `describe` blocks across three files run this lexicon against a real
+binary rather than a fixture, and every one of them skips rather than fails
+when its dependency is absent. A skip is silent by design, so without this
+file nothing in the tree says which of them has ever passed, against what, or
+when. The evidence had been living in PR prose (`#2157` for the live apply
+pair), which no reader of the suite can see.
+
+One row per gated block below: what it proves, what gates it, the command,
+and the last binary and emulator it is known to have passed against.
+
+`live-estate/README.md` next door is the sibling record for the two recorded
+documents (`../live-plan.json`, `../live-ls.json`) rather than for a suite,
+and stays where it is.
+
+## The binary and the emulator these rows name
+
+`choudoufu v0.14.0` below means the published release binary, not a source
+build: `gh release download v0.14.0 -R INTENTIUS/choudoufu -p
+'choudoufu_v0.14.0_darwin_arm64.tar.gz' -p SHA256SUMS`, verified against
+`SHA256SUMS` (`41c705d9b5fec47100c4f2fb9ab0694f0160b31a4e0661e877b4d9821bc464e3`),
+extracted and put first on PATH. `choudoufu version` prints `choudoufu v0.14.0
+(based on OpenTofu v1.13.0-dev)`.
+
+`the pinned floci emulator` means choudoufu's own smoke stack image,
+`ghcr.io/lex00/floci@sha256:a39185cc3971d0188663d61043cb038dff1260d8a975b1aa72c4e2bb1feac3cb`
+(that checkout's `live/floci-image`), brought up from
+`live/smoke/docker-compose.yml` and exported as
+`CHOUDOUFU_EMULATOR_ENDPOINT=http://localhost:<mapped port>`.
+
+## The four blocks
+
+### 1. `TerraformApplyOp applies a real root`
+
+`composites/terraform-apply-op.acceptance.test.ts`. One test: `runOpLocally`
+drives `TerraformApplyOp` with `gate: "never"` through Init, Plan and Apply
+over the `with-backend/` fixture in a temp directory, and two
+`null_resource`s in the resulting state is the pass. The backend is `local`,
+so no credentials and no remote state are involved.
+
+Gated on a `terraform` or `tofu` on PATH, and on the provider download
+reaching `registry.terraform.io` (`CHANT_OFFLINE` unset and the host
+resolvable).
+
+```
+npx vitest run lexicons/terraform/src/composites/terraform-apply-op.acceptance.test.ts
+```
+
+Last passed: 2026-09-07, `Terraform v1.15.8` on `darwin_arm64`, with
+`hashicorp/null` resolved from the public registry for the fixture's `~> 3.2`
+constraint. No emulator is involved. Re-run by chant #2168 alongside the two
+live blocks in the same file, so the file's three rows all come from one run.
+
+### 2. `TerraformApplyOp applies a live root against choudoufu's emulator`
+
+Same file, second block. Two tests. The first is the live-root happy path end
+to end through `runOpLocally`: Init, `plan -out=<file>`, `show` over that
+file, `apply <file>`, two `null_resource`s applied against the `live/`
+fixture. The second moves the world between plan and apply and asserts both
+named refusals (`approval-mismatch`, `wrong-estate`) come back as results
+carrying choudoufu's own message rather than as thrown errors, then applies
+the same file once the world is restored.
+
+Gated on a `choudoufu` on PATH, on it reporting a release version at or above
+`MIN_CHOUDOUFU_VERSION` (0.14.0), and on `CHOUDOUFU_EMULATOR_ENDPOINT`. Not
+gated on choudoufu #894 and never was: the plan half here is the stock `plan
+-out` path and reads no JSON document.
+
+```
+npx vitest run lexicons/terraform/src/composites/terraform-apply-op.acceptance.test.ts
+```
+
+Last passed: 2026-09-07, choudoufu v0.14.0 with the pinned floci emulator up,
+recorded by chant #2168. That run is reproducible from this file: the binary
+is a release asset and the emulator is a pinned digest. Before it, the only
+record was PR #2157's prose ("the acceptance suite 3 passed against v0.13.0
+with the emulator up", merged at `81200b5d97c15920619de4b109c4393ec3223720`),
+which #2220 could not reproduce because no binary existed on the machine that
+wrote this file.
+
+### 3. `choudoufu live-check and live-plan against the fixture`
+
+`op/activities/choudoufu.acceptance.test.ts`. Two tests. `live-check -json`
+admits the `live/` fixture root (no cloud calls, so this half needs only the
+binary), and `live-plan` reads the emulator and proposes creating both
+`null_resource`s on a fresh estate.
+
+Gated on a `choudoufu` on PATH and on `CHOUDOUFU_EMULATOR_ENDPOINT`. The
+`CHOUDOUFU_894_OPEN` constant that used to skip the block whatever was on
+PATH is gone.
+
+```
+npx vitest run lexicons/terraform/src/op/activities/choudoufu.acceptance.test.ts
+```
+
+Last passed: 2026-09-07, choudoufu v0.14.0 with the pinned floci emulator up,
+recorded by chant #2168. That is the first pass this block has ever had as a
+suite, and the first the `live-plan` test has ever had at all. It had been
+gated shut on choudoufu #894 since commit `65821d76` (2026-09-06 12:45Z);
+before that gate, PR #2135's body records a hand verification of the
+`live-check` half only.
+
+Two chant-side changes in #2168 were what the pass needed, both consequences
+of what choudoufu PR 915 shipped. `-estate` is still refused beside a declared
+estate; what changed is that the flag is no longer needed, so
+`choudoufuLivePlanCommand` omits it exactly when the configuration names its
+own estate. And the human-render call carries `-detailed-exitcode` too, so
+exit 2 there is a plan with changes rather than a failure, which is what the
+first real run of this block found.
+
+### 4. `TerraformAdoptOp adopts an unmarked live resource`
+
+`composites/terraform-adopt-op.acceptance.test.ts`. One test: create an
+unmarked VPC directly against the emulator so it is a live resource this
+estate does not own at an identity the `live-adopt/` root declares, run the
+Ledger step and expect exactly one adoptable match carrying the two marker
+values, run the Adopt step and let it write them, then re-plan and expect the
+estate to own the same VPC with nothing left adoptable.
+
+Gated on a `choudoufu` on PATH, on an `aws` CLI on PATH (the unmarked
+resource is created and adopted through it), on
+`CHOUDOUFU_EMULATOR_ENDPOINT`, and then on
+`CHOUDOUFU_ADOPTABLE_NOT_IN_DOCUMENT`, which replaced the #894 gate and names
+choudoufu #962.
+
+```
+npx vitest run lexicons/terraform/src/composites/terraform-adopt-op.acceptance.test.ts
+```
+
+Last passed: never, and the reason changed on 2026-09-07 rather than going
+away. chant #2168 dropped the #894 gate and ran the block against choudoufu
+v0.14.0 and the pinned floci emulator. It reached the document and stopped
+there, with `ledger.adoptions` empty:
+
+```
+AssertionError: expected [] to have a length of 1 but got +0
+ ❯ terraform-adopt-op.acceptance.test.ts:116:34
+```
+
+The document's `unowned[]` is the resources found at an identity the
+configuration itself declares, and it works: an unmarked
+`aws_cloudwatch_log_group` in the same fixture shape comes back on the same
+binary with `adopt_tofu_estate` and `adopt_tofu_address` on it, which is the
+shape `../live-plan.json` recorded. An `aws_vpc` has no such identity, so the
+document reports `omissions[].reason = "NEEDS_DISCOVERY"` and leaves
+`unowned[]` empty. The VPC is matched by choudoufu's content matcher during
+the estate-wide unclaimed sweep instead, and that match is printed only in the
+human render's "Adoptable" section, for which `views.LivePlanDocument` has no
+field. `-adoption-only` is refused alongside `-json`, and
+`TOFU_LIVE_COLLECT_UNCLAIMED=1` on the `-json` run leaves `"unowned": []`
+while the text run beside it prints `Adoptable: 1 live resource matches a
+declared resource`. Filed upstream as choudoufu #962
+(https://github.com/INTENTIUS/choudoufu/issues/962), which carries the full
+measurement; chant #2168 has the same.
+
+The fixture was deliberately left as an `aws_vpc`. A log group would make the
+block pass and would stop it proving the content-matcher path, which is the
+only thing it exists to prove.
+
+## Running everything that can run on a machine with no choudoufu
+
+```
+npx vitest run \
+  lexicons/terraform/src/composites/terraform-apply-op.acceptance.test.ts \
+  lexicons/terraform/src/composites/terraform-adopt-op.acceptance.test.ts \
+  lexicons/terraform/src/op/activities/choudoufu.acceptance.test.ts
+```
+
+With `terraform` on PATH and the registry reachable, that is 1 passed and 5
+skipped, and each skip names its own reason in the block title. With
+choudoufu v0.14.0, the `aws` CLI and the emulator all present, it is 5 passed
+and 1 skipped: block 4 is the skip. On 2026-09-07 that is exactly what it
+printed.
+
+## Keeping this file honest
+
+Add a row when a suite is added, and update a "last passed" line in the same
+change that makes a run happen. A line here that names no binary version and
+no date is worth less than no line at all, so if a run cannot be reproduced,
+say whose prose the claim comes from and that it was not reproduced.

package/src/__fixtures__/remote-backend/main.tf

@@ -0,0 +1,34 @@
+# The `with-backend` root next door keeps its state local on purpose, so
+# TF001 reports it (#2218). This one is the same configuration with a remote
+# backend, and is what a root TF001 says nothing about looks like. Nothing
+# ever runs `terraform init` here, so the bucket need not exist.
+terraform {
+  required_version = ">= 1.5.0"
+
+  backend "s3" {
+    bucket = "tfstate"
+    key    = "app/terraform.tfstate"
+    region = "us-east-1"
+  }
+
+  required_providers {
+    null = {
+      source  = "hashicorp/null"
+      version = "~> 3.2"
+    }
+  }
+}
+
+provider "null" {}
+
+resource "null_resource" "first" {
+  triggers = {
+    name = "first"
+  }
+}
+
+resource "null_resource" "second" {
+  triggers = {
+    name = "second"
+  }
+}

package/src/__fixtures__/with-backend/main.tf

@@ -1,3 +1,10 @@
+# The `terraform-apply-op` acceptance test copies this root into a temp
+# directory and runs a real `terraform init`, `plan` and `apply` against it,
+# so the backend has to be one that works with no credentials and no network
+# beyond the provider registry. That is `local`, which is why TF001 reports
+# this root (#2218): the finding is correct, and the local state is the point
+# of the fixture. `remote-backend/` next door is the same configuration with
+# a backend TF001 says nothing about.
 terraform {
   required_version = ">= 1.5.0"
 

package/src/codegen/lint-rules-page.test.ts

@@ -3,6 +3,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { describe, expect, test } from "vitest";
 import { scanRules } from "@intentius/chant/codegen/docs-rule-scanning";
+import { RULE_CATALOG } from "@intentius/chant/audit/catalog";
 
 /**
  * `docs/pages/lint-rules.mdx` is authored by hand, one `##` section per rule
@@ -14,9 +15,25 @@ import { scanRules } from "@intentius/chant/codegen/docs-rule-scanning";
  */
 const pkgDir = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 
+/**
+ * The TF ids core owns rather than this lexicon (#2220). `scanRules` walks
+ * this package's `src/`, so it cannot see them: TF023 (Terraform state
+ * committed to the repository) lives in `packages/core/src/audit/catalog.ts`
+ * because it reads the discovered file list rather than a parsed root module,
+ * and its page section here was the one TF section nothing guarded. Read off
+ * `RULE_CATALOG` rather than hardcoded, so a second core-owned TF id is
+ * covered on the day it lands.
+ */
+function coreOwnedTfIds(): string[] {
+  return Object.keys(RULE_CATALOG).filter((id) => /^TF\d+$/.test(id));
+}
+
 describe("lint-rules.mdx stays in sync with the rule catalog", () => {
   test("every rule id scanned from source has a ## section on the authored page", () => {
-    const ids = scanRules(join(pkgDir, "src")).map((r) => r.id).sort();
+    const core = coreOwnedTfIds();
+    expect(core, "core owns at least TF023").toContain("TF023");
+
+    const ids = [...new Set([...scanRules(join(pkgDir, "src")).map((r) => r.id), ...core])].sort();
     expect(ids.length).toBeGreaterThan(0);
 
     const page = readFileSync(join(pkgDir, "docs", "pages", "lint-rules.mdx"), "utf-8");

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

@@ -20,25 +20,46 @@
  * 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
+ * ## Why this still skips on choudoufu v0.14.0
  *
- * 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.
+ * Not #894 any more. v0.14.0 (choudoufu PR 915) made `live-plan -json`
+ * reachable on a configuration that names its own estate, and this suite was
+ * run against it on 2026-09-07 for the first time. It got as far as the
+ * document and stopped there: `ledger.adoptions` came back empty, because the
+ * #788 document carries no adoptable-by-content section at all.
  *
- * 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.
+ * The document's `unowned[]` is the resources found at an identity the
+ * configuration itself declares. A `aws_cloudwatch_log_group` has one (its
+ * name is in the block), so an unmarked live one comes back in `unowned[]`
+ * with `adopt_tofu_estate`/`adopt_tofu_address` on it, which is exactly what
+ * `../__fixtures__/live-plan.json` recorded and what `readAdoptionLedger`
+ * reads. An `aws_vpc` has none: EC2 assigns the id, so the document reports
+ * `omissions[].reason = "NEEDS_DISCOVERY"` and leaves `unowned[]` empty. The
+ * VPC is matched instead by choudoufu's content matcher during the
+ * estate-wide unclaimed sweep, and that match is printed only in the human
+ * render's "Adoptable" section. `views.LivePlanDocument` has no field for it,
+ * `-adoption-only` is refused alongside `-json` ("-adoption-only and -json
+ * cannot be combined"), and `TOFU_LIVE_COLLECT_UNCLAIMED=1` on the `-json`
+ * run makes no difference: the text render then prints "Adoptable: 1 live
+ * resource matches a declared resource" and the document beside it still says
+ * `"unowned": []`.
+ *
+ * So `choudoufuLivePlan` cannot produce a ledger for a provider-assigned
+ * identity on any binary that exists today, and this suite is what would
+ * prove it can. Filed upstream as
+ * [choudoufu #962](https://github.com/INTENTIUS/choudoufu/issues/962); the
+ * measurements are there and on chant #2168.
+ *
+ * The gate below names that, alongside the three ordinary dependencies: a
+ * `choudoufu`, an `aws` CLI, and the emulator's endpoint.
  *
  * 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.
+ *
+ * `../__fixtures__/ACCEPTANCE.md` records what this block has last passed
+ * against, which is still nothing, and why the reason changed.
  */
 
 import { execSync } from "node:child_process";
@@ -58,11 +79,16 @@ function onPath(cmd: string): boolean {
 }
 
 /**
- * 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.
+ * `true` while `live-plan -json`'s document carries no adoptable-by-content
+ * section, so a provider-assigned identity like an `aws_vpc` never reaches
+ * `readAdoptionLedger`. Filed upstream as
+ * [choudoufu #962](https://github.com/INTENTIUS/choudoufu/issues/962), with
+ * the measurements against the v0.14.0 release binary on 2026-09-07; flip to
+ * `false` when a choudoufu release puts the content matcher's "Adoptable"
+ * rows in the document, either in `unowned[]` or in a sibling array.
+ * choudoufu #894, which gated this block before, is fixed and gone.
  */
-const CHOUDOUFU_894_OPEN = true;
+const CHOUDOUFU_ADOPTABLE_NOT_IN_DOCUMENT = true;
 
 const emulatorEndpoint = process.env.CHOUDOUFU_EMULATOR_ENDPOINT;
 
@@ -72,9 +98,10 @@ const skipReason = !onPath("choudoufu")
     ? "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"
+      : CHOUDOUFU_ADOPTABLE_NOT_IN_DOCUMENT
+        ? "choudoufu#962: live-plan -json's document carries no adoptable-by-content section, so the " +
+          "fixture's unmarked aws_vpc reaches omissions[NEEDS_DISCOVERY] and never unowned[]; " +
+          "measured on choudoufu v0.14.0"
         : "";
 
 const FIXTURE = join(import.meta.dirname, "..", "__fixtures__", "live-adopt");

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

@@ -80,7 +80,7 @@ describe("TerraformAdoptOp gates on the ledger (#2105)", () => {
     // 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(gateOf(props(base)).gate).toBe("approve-estate-adopt");
     expect(Object.keys(TerraformAdoptOp(base))).toEqual(["op"]);
   });
 
@@ -91,9 +91,14 @@ describe("TerraformAdoptOp gates on the ledger (#2105)", () => {
     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" });
+  // #2202: `gateName` is the option; `signalName` is read through 0.59.0.
+  test("the deprecated `signalName` option still names the gate", () => {
+    expect(gateOf(props({ ...base, signalName: "ok" })).gate).toBe("ok");
+  });
+
+  test("gate name, timeout and description are overridable", () => {
+    const gate = gateOf(props({ ...base, gateName: "ok", gateTimeout: "2h", gateDescription: "mine" }));
+    expect(gate).toMatchObject({ gate: "ok", timeout: "2h", description: "mine" });
   });
 
   test("no timeout given means the gate carries none, so core's own default applies", () => {

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

@@ -89,7 +89,7 @@ import {
 } from "../op/builders";
 
 export interface TerraformAdoptOpConfig {
-  /** Op name (kebab-case). `signalName` defaults to `approve-<name>`. */
+  /** Op name (kebab-case). `gateName` 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;
@@ -99,7 +99,12 @@ export interface TerraformAdoptOpConfig {
    * sidecar, which is the usual case.
    */
   estate?: string;
-  /** Gate signal name. Default: `approve-<name>`, as `TerraformApplyOp` does. */
+  /** The gate's name. Default: `approve-<name>`, as `TerraformApplyOp` does. */
+  gateName?: string;
+  /**
+   * @deprecated The gate's name was `signalName` through 0.58.0 and is
+   * `gateName` since #2202, matching `TerraformApplyOp`. Removed in 0.60.0.
+   */
   signalName?: string;
   /** How long a recorded pending gate stays valid, as a duration string. Default: core's own (48h). */
   gateTimeout?: string;
@@ -176,7 +181,7 @@ export function TerraformAdoptOp(config: TerraformAdoptOpConfig): TerraformAdopt
       phase("Check", [check]),
       phase("Ledger", [ledger]),
       phase("Gate", [
-        gate(config.signalName ?? `approve-${config.name}`, {
+        gate(config.gateName ?? config.signalName ?? `approve-${config.name}`, {
           ...(config.gateTimeout ? { timeout: config.gateTimeout } : {}),
           description:
             config.gateDescription ??

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

@@ -20,6 +20,10 @@
  *
  * Gating copied from `lexicons/k3s/src/serializer.acceptance.test.ts`, which
  * skips the same way when Docker is absent.
+ *
+ * `../__fixtures__/ACCEPTANCE.md` records what both blocks in this file have
+ * last passed against, with the binary version and the date (#2220). Update
+ * it in the same change as a run.
  */
 
 import { execSync } from "node:child_process";
@@ -152,18 +156,19 @@ describe.skipIf(skipReason !== "")(
  * `../op/activities/choudoufu.acceptance.test.ts` is, plus a version floor:
  *
  *   - no `choudoufu` on PATH,
- *   - a `choudoufu` older than {@link MIN_CHOUDOUFU_VERSION}, which is the
- *     release that shipped the approval artifact
+ *   - a `choudoufu` older than {@link MIN_CHOUDOUFU_VERSION}: v0.13.0 shipped
+ *     the approval artifact
  *     ([choudoufu #878](https://github.com/INTENTIUS/choudoufu/issues/878),
- *     PR 889): before it, `plan -out` was refused under a live block and this
- *     Op could not be built the way it is built now,
+ *     PR 889), before which `plan -out` was refused under a live block and
+ *     this Op could not be built the way it is built now, and v0.14.0 moved
+ *     the floor again for the document the other two Ops read
+ *     ([choudoufu #894](https://github.com/INTENTIUS/choudoufu/issues/894)),
  *   - `CHOUDOUFU_EMULATOR_ENDPOINT` unset (bring up choudoufu's `just smoke`
  *     docker compose stack and export `http://localhost:<mapped port>`).
  *
- * The #894 clause the first version of this suite carried is gone. That issue
- * is still open, but it is about `live-plan -json`, which the apply Op no
- * longer runs: the plan half is the stock `plan -out` path. `TerraformWatchOp`
- * and `TerraformAdoptOp` still need the document and still wait on it.
+ * The #894 clause the first version of this suite carried is gone, and stayed
+ * gone: that issue was about `live-plan -json`, which the apply Op does not
+ * run at all, since the plan half is the stock `plan -out` path.
  *
  * The first test is the happy path end to end through `runOpLocally`. The
  * second is the refusal, and it runs the activities directly rather than
@@ -213,7 +218,7 @@ const liveSkipReason: string = !onPath("choudoufu")
   : choudoufuVersion === undefined
     ? "the choudoufu on PATH reports no release version (a dev build), so the approval artifact cannot be assumed"
     : isOlderVersion(choudoufuVersion, MIN_CHOUDOUFU_VERSION)
-      ? `choudoufu ${choudoufuVersion} is older than v${MIN_CHOUDOUFU_VERSION}, which shipped the approval artifact (choudoufu #878)`
+      ? `choudoufu ${choudoufuVersion} is older than v${MIN_CHOUDOUFU_VERSION}, the lexicon's floor (choudoufu #878's approval artifact in v0.13.0, #894's -json document in v0.14.0)`
       : !emulatorEndpoint
         ? "CHOUDOUFU_EMULATOR_ENDPOINT is not set (bring up choudoufu's `just smoke` emulator stack and export it)"
         : "";

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

@@ -78,20 +78,28 @@ describe("TerraformApplyOp gate (#2086)", () => {
   test("signal name defaults to approve-<name>", () => {
     const op = props({ name: "prod-apply", root: "app" });
     const gate = op.phases.find((p) => p.name === "Gate")!.steps.find(isGate)!;
-    expect(gate.signalName).toBe("approve-prod-apply");
+    expect(gate.gate).toBe("approve-prod-apply");
   });
 
-  test("an explicit signalName, timeout and description win", () => {
+  // #2202: `gate` on this config already means the gate MODE, so the gate's
+  // name is `gateName` here. `signalName` is read through 0.59.0.
+  test("the deprecated `signalName` option still names the gate", () => {
+    const op = props({ name: "prod-apply", root: "app", signalName: "approve-terraform" });
+    const gate = op.phases.find((p) => p.name === "Gate")!.steps.find(isGate)!;
+    expect(gate.gate).toBe("approve-terraform");
+  });
+
+  test("an explicit gateName, timeout and description win", () => {
     const op = props({
       name: "prod-apply",
       root: "app",
-      signalName: "approve-terraform",
+      gateName: "approve-terraform",
       gateTimeout: "72h",
       gateDescription: "Change window only",
     });
     const gate = op.phases.find((p) => p.name === "Gate")!.steps.find(isGate)!;
     expect(gate).toMatchObject({
-      signalName: "approve-terraform",
+      gate: "approve-terraform",
       timeout: "72h",
       description: "Change window only",
     });
@@ -186,7 +194,7 @@ describe("TerraformApplyOp on the local executor (#2086, gate-as-fact #2119)", (
 
     expect(result.status).toBe("gated");
     expect(result.gate?.op).toBe("prod-apply");
-    expect(result.gate?.gate).toBe(op.phases.flatMap((p) => p.steps).find(isGate)?.signalName);
+    expect(result.gate?.gate).toBe(op.phases.flatMap((p) => p.steps).find(isGate)?.gate);
     expect(gates.appended).toHaveLength(1);
     // Init, Plan and the pre-gate `show` ran; Apply is behind the gate and did not.
     expect(ran).toEqual(["terraformInit", "terraformPlan", "terraformShow"]);

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

@@ -96,7 +96,7 @@ import {
 export type TerraformGateMode = "on-destroy" | "always" | "never";
 
 export interface TerraformApplyOpConfig {
-  /** Op name (kebab-case). `signalName` defaults to `approve-<name>`. */
+  /** Op name (kebab-case). `gateName` defaults to `approve-<name>`. */
   name: string;
   /** Key into the project's `terraform.roots`. The root carries dir, workspace, var files and backend config. */
   root: string;
@@ -108,7 +108,13 @@ export interface TerraformApplyOpConfig {
    * same phase.
    */
   gate?: TerraformGateMode;
-  /** Gate signal name. Default: `approve-<name>`, as `ApplyOp` does. */
+  /** The gate's name. Default: `approve-<name>`, as `ApplyOp` does. */
+  gateName?: string;
+  /**
+   * @deprecated The gate's name was `signalName` through 0.58.0 and is
+   * `gateName` since #2202 (`gate` is taken here by {@link TerraformGateMode}).
+   * Still read; removed in 0.60.0.
+   */
   signalName?: string;
   /** How long a recorded pending gate stays valid, as a duration string. Default: core's own (48h). */
   gateTimeout?: string;
@@ -164,10 +170,14 @@ export function TerraformApplyOp(config: TerraformApplyOpConfig): TerraformApply
   // 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): "unknown" reads as stock, the
-  // conservative direction. The mode no longer changes which steps are
-  // emitted; it decides the policy refusal below and the wording of the gate.
+  // 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";
 
@@ -175,6 +185,12 @@ export function TerraformApplyOp(config: TerraformApplyOpConfig): TerraformApply
     // 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(
@@ -208,7 +224,7 @@ export function TerraformApplyOp(config: TerraformApplyOpConfig): TerraformApply
     phases.push(
       phase("Gate", [
         show,
-        gate(config.signalName ?? `approve-${config.name}`, {
+        gate(config.gateName ?? config.signalName ?? `approve-${config.name}`, {
           ...(config.gateTimeout ? { timeout: config.gateTimeout } : {}),
           description:
             config.gateDescription ??