@intentius/chant-lexicon-terraform 0.57.0 → 0.58.0

package/src/lint/rules/plan-before-apply.test.ts

@@ -1,7 +1,11 @@
-import { describe, expect, test } from "vitest";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, test } from "vitest";
 import * as ts from "typescript";
 import type { LintContext } from "@intentius/chant/lint/rule";
 import { planBeforeApplyRule } from "./plan-before-apply";
+import { loadRuleFixture } from "./fixtures/load";
 
 function createContext(code: string, fileName = "infra.op.ts"): LintContext {
   const sourceFile = ts.createSourceFile(fileName, code, ts.ScriptTarget.Latest, true);
@@ -10,18 +14,18 @@ function createContext(code: string, fileName = "infra.op.ts"): LintContext {
 
 describe("TF101: plan-before-apply", () => {
   test("flags a literal plan path", () => {
-    const diags = planBeforeApplyRule.check(
-      createContext(`
-        const plan = terraformPlan({ root: "app" });
-        const apply = terraformApply({ planFile: "/tmp/plan.out" });
-      `),
-    );
+    const diags = planBeforeApplyRule.check(loadRuleFixture("TF101", "positive"));
     expect(diags).toHaveLength(1);
     expect(diags[0].ruleId).toBe("TF101");
     expect(diags[0].severity).toBe("error");
     expect(diags[0].message).toContain("literal path");
   });
 
+  test("passes a step-output reference to the preceding plan (fixtures/TF101/negative.op.ts)", () => {
+    const diags = planBeforeApplyRule.check(loadRuleFixture("TF101", "negative"));
+    expect(diags).toHaveLength(0);
+  });
+
   test("flags a template literal plan path", () => {
     const diags = planBeforeApplyRule.check(
       createContext(`
@@ -109,3 +113,104 @@ describe("TF101: plan-before-apply", () => {
     expect(diags).toHaveLength(0);
   });
 });
+
+describe("TF101: a live root is checked like any other (#2106 follow-up)", () => {
+  const dirs: string[] = [];
+
+  afterEach(() => {
+    for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+  });
+
+  /** A throwaway project with one `terraform.roots` entry, live or stock. */
+  function project(opts: { binary?: string; live?: boolean }): string {
+    const dir = mkdtempSync(join(tmpdir(), "chant-tf101-mode-"));
+    dirs.push(dir);
+    mkdirSync(join(dir, "root"), { recursive: true });
+    writeFileSync(
+      join(dir, "root", "main.tf"),
+      opts.live
+        ? ["terraform {", "  live {", '    estate = "fixture-estate"', "  }", "}", ""].join("\n")
+        : 'resource "null_resource" "x" {}\n',
+    );
+    writeFileSync(
+      join(dir, "chant.config.json"),
+      JSON.stringify({ terraform: { binary: opts.binary ?? "terraform", roots: { app: { dir: "./root" } } } }),
+    );
+    return dir;
+  }
+
+  /** A `LintContext` whose file lives inside `project`, so a config walk would find it if the rule did one. */
+  function contextIn(project: string, code: string): LintContext {
+    const filePath = join(project, "ops", "app.op.ts");
+    const sourceFile = ts.createSourceFile(filePath, code, ts.ScriptTarget.Latest, true);
+    return { sourceFile, entities: [], filePath };
+  }
+
+  test("fires on a terraformApply call over a live root, where #2106 exempted it", () => {
+    const dir = project({ binary: "choudoufu", live: true });
+    const diags = planBeforeApplyRule.check(
+      contextIn(
+        dir,
+        `
+          const apply = terraformApply("app", { planFile: "/tmp/plan.out" });
+        `,
+      ),
+    );
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("literal path");
+  });
+
+  test("fires on a stock root in the same shape", () => {
+    const dir = project({ binary: "terraform", live: false });
+    const diags = planBeforeApplyRule.check(
+      contextIn(
+        dir,
+        `
+          const apply = terraformApply("app", { planFile: "/tmp/plan.out" });
+        `,
+      ),
+    );
+    expect(diags).toHaveLength(1);
+  });
+
+  test("a live root's paired call still passes", () => {
+    const dir = project({ binary: "choudoufu", live: true });
+    const diags = planBeforeApplyRule.check(
+      contextIn(
+        dir,
+        `
+          const plan = terraformPlan("app", { id: "plan" });
+          const apply = terraformApply("app", { planFile: plan.out.planFile });
+        `,
+      ),
+    );
+    expect(diags).toHaveLength(0);
+  });
+
+  test("the object-literal-only call form is checked the same way", () => {
+    const dir = project({ binary: "choudoufu", live: true });
+    const diags = planBeforeApplyRule.check(
+      contextIn(
+        dir,
+        `
+          const apply = terraformApply({ root: "app", planFile: "/tmp/plan.out" });
+        `,
+      ),
+    );
+    expect(diags).toHaveLength(1);
+  });
+
+  test("no project config at all changes nothing: the rule reads none", () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-tf101-mode-"));
+    dirs.push(dir);
+    const diags = planBeforeApplyRule.check(
+      contextIn(
+        dir,
+        `
+          const apply = terraformApply("app", { planFile: "/tmp/plan.out" });
+        `,
+      ),
+    );
+    expect(diags).toHaveLength(1);
+  });
+});

package/src/lint/rules/plan-before-apply.ts

@@ -27,6 +27,17 @@ import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lin
  * silent — the same deliberately shallow "bail rather than guess" posture
  * `validateStepOutputRefs` takes, since the runtime brand on a real
  * `StepOutputRef` is invisible to a source-level AST match.
+ *
+ * Fires on every `terraformApply` call, live root or stock. #2106 exempted
+ * live roots for one release, because choudoufu refused `-out` and
+ * `apply <planfile>` and the activity ran a bare `apply -auto-approve` with no
+ * plan file to pair. choudoufu v0.13.0 admits both under a `live` block
+ * ([choudoufu #878](https://github.com/INTENTIUS/choudoufu/issues/878)), and
+ * there the pairing matters more than on a stock root, not less: the apply
+ * re-plans the live system and compares its fresh plan against the file it was
+ * handed, so a plan file spelled out as a literal is an approval for a run
+ * nobody can trace back to a plan step. The exemption is gone with the
+ * condition that produced it, and this rule reads no project config at all.
  */
 export const planBeforeApplyRule: LintRule = {
   id: "TF101",

package/src/lint/secret-shape.test.ts

@@ -0,0 +1,150 @@
+import { describe, expect, test } from "vitest";
+import {
+  isCredentialShapedValue,
+  isLiteralString,
+  isPlaceholderValue,
+  isSecretName,
+  secretShapedAssignment,
+} from "./secret-shape";
+
+describe("the name heuristic", () => {
+  test.each([
+    "password",
+    "db_password",
+    "PASSWORD",
+    "passwd",
+    "admin_passwd",
+    "secret",
+    "client_secret",
+    "secret_key",
+    "token",
+    "deploy_token",
+    "api_key",
+    "openai_api_key",
+    "private_key",
+    "access_key",
+  ])("%s reads like a credential", (name) => {
+    expect(isSecretName(name)).toBe(true);
+  });
+
+  test.each([
+    "region",
+    "instance_count",
+    "keystore",
+    "tokenizer",
+    "passwordless_sudo_enabled",
+    "bucket",
+  ])("%s does not", (name) => {
+    expect(isSecretName(name)).toBe(false);
+  });
+
+  test.each([
+    "secret_arn",
+    "db_password_file",
+    "api_key_id",
+    "private_key_path",
+    "deploy_token_name",
+  ])("%s is a locator, not the credential itself", (name) => {
+    expect(isSecretName(name)).toBe(false);
+  });
+
+  test("a locator suffix only excludes when it is the suffix", () => {
+    expect(isSecretName("arn_password")).toBe(true);
+    expect(isSecretName("file_secret")).toBe(true);
+  });
+});
+
+describe("the value heuristic", () => {
+  test("an AWS access key id is credential-shaped, through core's own detector", () => {
+    expect(isCredentialShapedValue("AKIA2E0XYZ4PQRSTUVWX")).toBe(true);
+  });
+
+  test("a GitHub token is, for the same reason", () => {
+    expect(isCredentialShapedValue("ghp_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8")).toBe(true);
+  });
+
+  test("a JWT is", () => {
+    expect(
+      isCredentialShapedValue("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImV4cCI6MTc2NH0.9mAcYbBqp4Ck2XjLwr7QeR1sT3uVwXyZ"),
+    ).toBe(true);
+  });
+
+  test("a PEM header is, even without the closing block", () => {
+    expect(isCredentialShapedValue("-----BEGIN RSA PRIVATE KEY-----\nMIIEow...")).toBe(true);
+  });
+
+  test("a long high-entropy token is", () => {
+    expect(isCredentialShapedValue("8Jd0hVn2XqB7sLtR4mYcE1zPgWfKa5UiQ3oNrTbA")).toBe(true);
+  });
+
+  test.each(["eu-west-1", "t3.micro", "postgres", "app-prod"])("%s is not", (value) => {
+    expect(isCredentialShapedValue(value)).toBe(false);
+  });
+
+  test("a model id or image ref is not, through core's identifier-slug filter", () => {
+    expect(isCredentialShapedValue("registry.example.com/team/app-server")).toBe(false);
+  });
+
+  test("a value shorter than eight characters is never judged", () => {
+    expect(isCredentialShapedValue("aB3$xY")).toBe(false);
+  });
+});
+
+describe("placeholders", () => {
+  test.each(["changeme", "CHANGE_ME", "change-me", "YOUR_API_KEY", "example-secret", "0000000000000000"])(
+    "%s is a placeholder",
+    (value) => {
+      expect(isPlaceholderValue(value)).toBe(true);
+    },
+  );
+
+  test("a placeholder is never a finding, whatever the attribute is called", () => {
+    expect(secretShapedAssignment("db_password", "CHANGE_ME")).toBeUndefined();
+    expect(secretShapedAssignment("api_key", "your-api-key")).toBeUndefined();
+  });
+});
+
+describe("literals versus references", () => {
+  test("an hcl2json expression is not a literal", () => {
+    // Both `x = var.y` and `x = "${var.y}"` parse to this string.
+    expect(isLiteralString("${var.db_password}")).toBe(false);
+    expect(isLiteralString("${data.aws_secretsmanager_secret_version.db.secret_string}")).toBe(false);
+  });
+
+  test("a template with an interpolation in it is not a literal either", () => {
+    expect(isLiteralString("prefix-${var.env}-suffix")).toBe(false);
+  });
+
+  test("a plain string is", () => {
+    expect(isLiteralString("hunter2-prod-db")).toBe(true);
+  });
+
+  test("a non-string is not", () => {
+    expect(isLiteralString(3)).toBe(false);
+    expect(isLiteralString(true)).toBe(false);
+    expect(isLiteralString(["a"])).toBe(false);
+  });
+});
+
+describe("secretShapedAssignment", () => {
+  test("fires on the name when the value is an unremarkable literal", () => {
+    expect(secretShapedAssignment("db_password", "hunter2-prod-db")).toEqual({ reason: "name", length: 15 });
+  });
+
+  test("fires on the value when the name says nothing", () => {
+    const shape = secretShapedAssignment("bootstrap", "AKIA2E0XYZ4PQRSTUVWX");
+    expect(shape?.reason).toBe("value");
+  });
+
+  test("prefers the value reason when both hold", () => {
+    expect(secretShapedAssignment("api_key", "ghp_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8")?.reason).toBe("value");
+  });
+
+  test("declines a reference, which is the fix rather than the finding", () => {
+    expect(secretShapedAssignment("db_password", "${var.db_password}")).toBeUndefined();
+  });
+
+  test("declines a short value", () => {
+    expect(secretShapedAssignment("password", "abc123")).toBeUndefined();
+  });
+});

package/src/lint/secret-shape.ts

@@ -0,0 +1,159 @@
+/**
+ * The two heuristics the secrets rules of the TF family share: does this
+ * attribute's NAME read like a credential, and does its VALUE look like one.
+ *
+ * tfsec shipped `general-secrets-sensitive-in-variable`,
+ * `-in-local` and `-in-attribute`, and trivy dropped all three when it
+ * absorbed tfsec, so no maintained tool checks them today (#2107's survey).
+ * TF007, TF008, TF009 and TF022 are chant's versions, and they only stay
+ * consistent with each other if "secret-shaped" means one thing. That is what
+ * this module is.
+ *
+ * Nothing here re-implements a detector `packages/core/src/audit/secrets.ts`
+ * already has. The value heuristic runs a candidate through `scanForSecrets`
+ * first, so every vendor prefix the SEC family knows (AWS key ids, GitHub,
+ * Slack, Google, Stripe), the PEM block shape and the connection-string shape
+ * are recognised here for free, and it reuses that module's placeholder
+ * vocabulary, its identifier-slug filter and its entropy function. What it
+ * adds is what a Terraform attribute needs and a raw text scan does not: the
+ * JWT and bare PEM-header shapes, and a lower length floor than SEC010's 24
+ * characters, because an attribute value is already a single token rather
+ * than a line of prose to fish tokens out of.
+ */
+
+import {
+  looksLikeIdentifierSlug,
+  looksLikePlaceholder,
+  scanForSecrets,
+  shannonEntropy,
+} from "@intentius/chant/audit/secrets";
+
+/**
+ * Credential words, matched against the whole attribute name on `_`
+ * boundaries, so `db_password` and `access_key` match but `keystore` and
+ * `tokenizer` do not.
+ */
+const SECRET_NAME_RE = /(^|_)(password|passwd|secret|token|api_key|private_key|access_key)(_|$)/;
+
+/**
+ * Suffixes that turn a credential word into a REFERENCE to a credential:
+ * `secret_arn`, `db_password_file`, `api_key_id`, `private_key_path`,
+ * `token_name`. The value under one of these is a locator, and a locator is
+ * exactly what the fix for the other rules asks for, so flagging it would
+ * flag the remediation.
+ */
+const LOCATOR_SUFFIX_RE = /_(file|path|arn|id|name)$/;
+
+/** Minimum length for a value to be worth judging at all. */
+export const MIN_SECRET_LENGTH = 8;
+
+/** Minimum length for the generic high-entropy shape (below it, entropy says nothing). */
+const MIN_ENTROPY_LENGTH = 16;
+
+/** Bits per character above which a token of that length reads as random. */
+const ENTROPY_THRESHOLD = 3.5;
+
+/** `eyJ...header.eyJ...payload.signature`. An unsigned JWT still carries claims. */
+const JWT_RE = /^ey[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}(\.[A-Za-z0-9_-]*)?$/;
+
+/** A PEM header on its own, without the closing block `scanForSecrets` requires. */
+const PEM_HEADER_RE = /-----BEGIN ([A-Z]+ )?PRIVATE KEY-----/;
+
+/** Normalize an attribute or variable name for the name heuristic. */
+function normalizeName(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+}
+
+/**
+ * Does this attribute or variable name read like a credential? Case-insensitive
+ * and word-bounded, with the locator suffixes excluded.
+ */
+export function isSecretName(name: string): boolean {
+  const normalized = normalizeName(name);
+  if (LOCATOR_SUFFIX_RE.test(normalized)) return false;
+  return SECRET_NAME_RE.test(normalized);
+}
+
+/**
+ * Is this a plain string literal, as opposed to an expression? `hcl2json`
+ * renders every expression as a `"${...}"` template, so a value carrying one
+ * is a reference (`var.db_password`, `data.aws_secretsmanager_secret_version.x.secret_string`)
+ * or an interpolation, never a committed constant. Those are the fix, not the
+ * finding.
+ */
+export function isLiteralString(value: unknown): value is string {
+  return typeof value === "string" && !value.includes("${");
+}
+
+/**
+ * A placeholder rather than a credential. Core's list is checked twice: once
+ * as written, once with separators stripped, so the `CHANGE_ME` and
+ * `YOUR_API_KEY` spellings land on the same `changeme` / `your-api-key`
+ * entries as the unseparated ones.
+ */
+export function isPlaceholderValue(value: string): boolean {
+  return looksLikePlaceholder(value) || looksLikePlaceholder(value.replace(/[-_\s]/g, ""));
+}
+
+/** At least 3 of {lower, upper, digit, symbol}, which cuts plain words and pure hex. */
+function hasClassDiversity(value: string): boolean {
+  let classes = 0;
+  if (/[a-z]/.test(value)) classes++;
+  if (/[A-Z]/.test(value)) classes++;
+  if (/[0-9]/.test(value)) classes++;
+  if (/[^A-Za-z0-9]/.test(value)) classes++;
+  return classes >= 3;
+}
+
+/** The generic shape: a long, diverse, high-entropy token that isn't a slug. */
+function isHighEntropyToken(value: string): boolean {
+  if (value.length < MIN_ENTROPY_LENGTH) return false;
+  if (!/^[A-Za-z0-9+/=_-]+$/.test(value)) return false;
+  if (!hasClassDiversity(value)) return false;
+  if (looksLikeIdentifierSlug(value)) return false;
+  return shannonEntropy(value) >= ENTROPY_THRESHOLD;
+}
+
+/**
+ * Does this value look like a live credential on its own, whatever it is
+ * called? A known vendor shape (through core's detectors), a JWT, a PEM key,
+ * or a high-entropy token.
+ */
+export function isCredentialShapedValue(value: unknown): boolean {
+  if (!isLiteralString(value)) return false;
+  if (value.length < MIN_SECRET_LENGTH) return false;
+  if (isPlaceholderValue(value)) return false;
+  if (JWT_RE.test(value)) return true;
+  if (PEM_HEADER_RE.test(value)) return true;
+  // Core's own scan, over the single value: every SEC00x detector plus its
+  // high-entropy catch-all, with no file to walk.
+  if (scanForSecrets([{ path: "value", content: value }]).length > 0) return true;
+  return isHighEntropyToken(value);
+}
+
+/** Which heuristic fired, so a diagnostic can say why it is complaining. */
+export type SecretShapeReason = "name" | "value";
+
+export interface SecretShape {
+  reason: SecretShapeReason;
+  /** The value's length, for a message that never quotes the value itself. */
+  length: number;
+}
+
+/**
+ * The combined test the rules use: is `value`, assigned to an attribute called
+ * `name`, a committed secret? Either heuristic is enough, but both sides of the
+ * gate are the same, since the value has to be a literal, long enough to be a
+ * credential, and not a placeholder, so `sensitive = true`-style
+ * remediation advice is never given for `password = "changeme"`.
+ *
+ * Findings never carry the value. Callers get the reason and the length.
+ */
+export function secretShapedAssignment(name: string, value: unknown): SecretShape | undefined {
+  if (!isLiteralString(value)) return undefined;
+  if (value.length < MIN_SECRET_LENGTH) return undefined;
+  if (isPlaceholderValue(value)) return undefined;
+  if (isCredentialShapedValue(value)) return { reason: "value", length: value.length };
+  if (isSecretName(name)) return { reason: "name", length: value.length };
+  return undefined;
+}

package/src/live-ownership.ts

@@ -0,0 +1,60 @@
+/**
+ * The live root's ownership channel (#2104): choudoufu's two marker tags.
+ *
+ * Sibling of `./state-ownership.ts`, and here for the same mechanical reason:
+ * `plugin.ts` declares `ownershipChannel` eagerly while `describeResources`
+ * is behind a dynamic import, so the key names cannot live in the reader
+ * without dragging the reader, and `node:child_process` with it, into every
+ * plugin load.
+ *
+ * ## Why the keys are declared and the verdicts are set by hand
+ *
+ * The issue that added this asked which of two ways to go: widen core's
+ * `OwnershipChannel` so a lexicon can supply its own classifier, or declare
+ * the keys for discoverability and set the verdicts in the reader, the way
+ * `lexicons/fly/src/ownership.ts` does for its two tiers. The second, and the
+ * reason is that the first buys nothing.
+ *
+ * Core's `classifyOwnership` tests one thing: does `tags[keys.managedBy]`
+ * equal the literal `"chant"`. Nothing in core ever calls it on a lexicon's
+ * behalf. `packages/core/src/ownership.ts` exports it, every lexicon calls it
+ * itself where the test happens to fit, and the ones it does not fit, fly's
+ * app boundary and aws's stack tags, already set verdicts directly. Adding a
+ * `classify` member to `OwnershipChannel` would give core a field only this
+ * lexicon passes and only this lexicon reads back, which is a longer way of
+ * writing the function `./describe-resources.ts` already has.
+ *
+ * What the declaration is still for is the claim it makes. Declaring
+ * `describeResources` on the channel is what turns the observation
+ * conformance suite's ownership assertion from a shape check into a
+ * behavioural one, and that claim holds on a live root exactly as it does on
+ * a stock one, from a different reading. The suite runs for both modes in
+ * `./describe-resources.test.ts`.
+ *
+ * ## The keys, and the slot that does not fit
+ *
+ * `ChannelKeys` is a managed-by / stack / env triple, because everywhere else
+ * chant stamps three tags. choudoufu's marker is two tags and no managed-by
+ * key at all: per `live/MARKERS.md`'s "Ownership semantics", a resource
+ * carrying `tofu-estate` belongs to that estate and there is no secondary
+ * check, so `tofu-estate` is both the managed-by claim and the stack
+ * identity. `tofu-address` takes the third slot because it is the marker's
+ * other half, not because it is an environment: a choudoufu marker has no
+ * environment in it, which is why `ResourceMetadata.marker` on a live read
+ * carries the estate as its `stack` and leaves `env` absent rather than
+ * filling it with an address.
+ */
+
+import type { ChannelKeys } from "@intentius/chant/ownership";
+
+/**
+ * The two tag keys `live/MARKERS.md` spec version 1 defines, named here so a
+ * reader of the plugin can see what a live root's verdict is read from.
+ * `./hcl/marker.ts` holds the constants the reader itself uses, along with
+ * the escaping and the ownership semantics that go with them.
+ */
+export const TERRAFORM_LIVE_MARKER_KEYS: ChannelKeys = {
+  managedBy: "tofu-estate",
+  stack: "tofu-estate",
+  env: "tofu-address",
+};

package/src/lsp/completions.test.ts

@@ -91,7 +91,8 @@ describe("LSP completions", () => {
     const labels = items.map((i) => i.label);
     expect(labels).toContain("gate");
     expect(labels).toContain("compensate");
-    expect(labels).toContain("taskQueue");
+    expect(labels).toContain("gateTimeout");
+    expect(labels).not.toContain("taskQueue");
   });
 
   it("completes a builder's own opts keys inside its second argument", () => {
@@ -103,7 +104,7 @@ describe("LSP completions", () => {
   it("completes root-entry keys inside chant.config.ts's terraform.roots.<name>", () => {
     const content = "export default {\n  terraform: {\n    roots: {\n      app: {\n        ";
     const items = completions(ctx({ content, position: { line: 4, character: 8 } }));
-    expect(items.map((i) => i.label).sort()).toEqual(["backendConfig", "dir", "varFiles", "workspace"]);
+    expect(items.map((i) => i.label).sort()).toEqual(["backendConfig", "delete", "dir", "varFiles", "workspace"]);
   });
 
   it("completes the terraform namespace's own top-level keys", () => {

package/src/lsp/option-keys.ts

@@ -15,7 +15,7 @@ export interface OptionKey {
 
 /** `TerraformConfig`'s own top-level keys (`terraform: { <here> }`). */
 export const CONFIG_NAMESPACE_KEYS: OptionKey[] = [
-  { key: "binary", detail: '"terraform" | "tofu" — which CLI drives the roots. Default: "terraform".' },
+  { key: "binary", detail: '"terraform" | "tofu" | "choudoufu" — which CLI drives the roots. Default: "terraform".' },
   { key: "roots", detail: "Named root modules. The name is the entity-key prefix." },
 ];
 
@@ -25,21 +25,21 @@ export const ROOT_ENTRY_KEYS: OptionKey[] = [
   { key: "workspace", detail: "Terraform workspace to select for this root. Omitted means `default`." },
   { key: "varFiles", detail: "`-var-file` arguments, in order, relative to `dir`." },
   { key: "backendConfig", detail: "`-backend-config` key/value pairs handed to `init`." },
+  { key: "delete", detail: '"never" | "owned-only" | "gated" — this root\'s delete mode, mapped onto choudoufu\'s policy block on a live root.' },
 ];
 
 /** `TerraformApplyOpConfig`'s keys (`TerraformApplyOp({ <here> })`). */
 export const APPLY_OP_KEYS: OptionKey[] = [
-  { key: "name", detail: "Op name (kebab-case). Also the default task queue and gate signal suffix." },
+  { key: "name", detail: "Op name (kebab-case). `signalName` defaults to `approve-<name>`." },
   { key: "root", detail: "Key into the project's `terraform.roots`." },
   { key: "planFile", detail: "Plan file written by Plan and consumed by Apply. Default: `chant.tfplan`." },
   { key: "gate", detail: '"on-destroy" | "always" | "never" — when to emit the approval gate. Default: "on-destroy".' },
   { key: "signalName", detail: "Gate signal name. Default: `approve-<name>`." },
-  { key: "gateTimeout", detail: "Temporal duration the gate waits before timing out. Default: core's own (48h)." },
+  { key: "gateTimeout", detail: "How long a recorded pending gate stays valid, as a duration string. Default: core's own (48h)." },
   { key: "gateDescription", detail: "Override the gate description shown to the approver." },
   { key: "upgrade", detail: "`-upgrade` on the Init step: re-resolve provider and module versions." },
   { key: "cwd", detail: "Directory each step starts the `chant.config.*` search from." },
   { key: "compensate", detail: "Saga-style rollback on a failed apply: `true` with no command throws; supply `{ command }`." },
-  { key: "taskQueue", detail: "Override the task queue. Defaults to `name`." },
 ];
 
 /** `compensate`'s own shape when it is an object: `compensate: { <here> }`. */
@@ -71,7 +71,12 @@ export const PLAN_OPTS_KEYS: OptionKey[] = [
 
 /** `terraformApply(root, { <here> })`'s opts — `TerraformApplyArgs` minus `root`, plus step opts. */
 export const APPLY_OPTS_KEYS: OptionKey[] = [
-  { key: "planFile", detail: "The saved plan file to apply, relative to the root directory. Required." },
+  {
+    key: "planFile",
+    detail:
+      "The saved plan file to apply. Required on either kind of root; on a live root it is the approval " +
+      "artifact the apply re-plans against and refuses on a mismatch (choudoufu #878).",
+  },
   { key: "cwd", detail: "Directory to start the `chant.config.*` search from." },
   ...STEP_OPTS,
 ];