@intentius/chant-lexicon-terraform 0.57.0 → 0.59.0

package/README.md

@@ -51,3 +51,12 @@ just docs
 - `src/lint/rules/`, source-level lint rules
 - `src/lint/post-synth/`, checks over the parsed roots (TF001 and up)
 - `src/lsp/`, LSP completions and hover
+
+## Acceptance evidence
+
+Four `describe` blocks run this lexicon against a real `terraform`, `tofu` or
+`choudoufu` binary, and each of them skips rather than fails when its
+dependency is absent. `src/__fixtures__/ACCEPTANCE.md` records, per block,
+what it proves, what gates it, the command that runs it, and the last binary
+and emulator it passed against with the date. Two of the four have never
+passed against anything, and that file says so.

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

@@ -0,0 +1,131 @@
+/**
+ * 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 { OpResource } from "@intentius/chant/op";
+export interface TerraformAdoptOpConfig {
+    /** 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;
+    /**
+     * 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;
+    /** 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;
+    /** 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 declare function TerraformAdoptOp(config: TerraformAdoptOpConfig): TerraformAdoptOpResources;
+//# sourceMappingURL=terraform-adopt-op.d.ts.map

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

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

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

@@ -1,17 +1,66 @@
 /**
- * TerraformApplyOp composite (#2086) — init, plan, approve, apply for one root
+ * TerraformApplyOp composite (#2086), init, plan, approve, apply for one root
  * module named in `terraform.roots`.
  *
  * Authority stays with terraform: chant runs the binary, reads its plan, and
- * hands the same saved plan to apply. The Apply step never re-plans, because
- * it takes the Plan step's own `planFile` as a `StepOutputRef` — whatever was
- * approved is what runs.
+ * hands the same saved plan to apply. The Apply step never applies something
+ * no gate saw, because it takes the Plan step's own `planFile` as a
+ * `StepOutputRef`.
  *
- * Phases: Init, Plan, Gate, Apply.
+ * Phases: Init, Plan, Gate, Apply. One shape, both kinds of root. A live root
+ * (#2103, `terraform.binary: "choudoufu"` plus a declared estate) ran a
+ * different shape for one release, because choudoufu refused `-out` and
+ * `apply <planfile>`; choudoufu v0.13.0 admits both under a `live` block
+ * ([choudoufu #878](https://github.com/INTENTIUS/choudoufu/issues/878),
+ * PR 889), so the plan-file discipline is back and the two shapes are one
+ * again.
  *
- * The gate is durable-runtime work, so an Op that emits one needs Temporal;
- * `packages/core/src/op/local-executor.ts` refuses any Op containing a gate.
- * `gate: "never"` is what makes the Op runnable with `chant run` locally.
+ * **What the approval covers on a live root.** `plan -out=<planFile>` writes
+ * stock's own plan file, and that file is what the approver reads and what
+ * the Apply step names. `apply <planFile>` does not replay it: prior state on
+ * a live root is a projection rebuilt from the live system every run, so the
+ * apply re-plans against the live system the way every live-markers run does,
+ * then compares its fresh plan with the file's. Same addresses, same actions,
+ * same live objects, and the same planned values, or it refuses before
+ * anything changes:
+ *
+ *   - `The approved plan no longer matches the live system`, and
+ *   - `The approved plan belongs to a different estate`,
+ *
+ * both with exit status **3**, which is neither 1 (any ordinary failure) nor
+ * `-detailed-exitcode`'s 2. `terraformApply` maps that status to a named
+ * result rather than a thrown error (`refused: "approval-mismatch" |
+ * "wrong-estate"`, with choudoufu's message in `refusal`), so a workflow
+ * reading the Apply step's output can route the run back to review instead of
+ * treating it as a broken step. The seam #2106 left named and unused on the
+ * apply args is now the plan file itself.
+ *
+ * TF101 therefore fires on a live root's `terraformApply` call again: there
+ * is a plan file to pair once more, and pairing it is what the refusal above
+ * has to compare against.
+ *
+ * **Delete modes.** chant's `delete: "never" | "owned-only" | "gated"`
+ * (`terraform.roots.<name>.delete`, `../config.ts`) maps onto choudoufu's
+ * `policy` block. `"owned-only"` is choudoufu's own default verb for the
+ * `undeclared_tagged` quadrant (an orphaned marked resource) and needs
+ * nothing; `"gated"` needs nothing beyond this composite's own approval gate;
+ * `"never"` requires the root's `policy` block to set `undeclared_tagged` to
+ * `"keep"`, `"untag"` or `"report"`, and TF026 (`../lint/post-synth/tf026.ts`)
+ * enforces that at build time, naming the setting to add. Separately, and
+ * regardless of `delete`, this composite refuses outright to build against a
+ * root whose `policy` sets `undeclared_untagged = "delete"` (account-scoped
+ * reconciliation, which needs a `scope` block): that quadrant deletes
+ * resources the estate never claimed, anywhere the scope reaches, and chant
+ * never proposes deleting a resource it does not own, not for a root, and not
+ * for an Op it generated.
+ *
+ * A gate is a fact on the gate ledger, not a wait (#2119). Reaching one,
+ * `chant run` consults the ledger (`packages/core/src/op/gate.ts`): a
+ * resolution newer than the gate's newest pending fact lets the run walk
+ * through, and anything else records the pending fact and ends the run with
+ * status `gated` and exit 3. `chant approve <op> <gate>` writes the
+ * resolution, and the next run reads it. `gate: "never"` drops the Gate phase
+ * entirely, so a run never stops.
  *
  * @example
  * ```typescript
@@ -29,13 +78,13 @@ import { OpResource } from "@intentius/chant/op";
  * cannot branch at build time on a count the plan only produces at run time.
  * The workable v1 is that `"on-destroy"` and `"always"` emit the same Gate
  * phase, and the approver is told what is at stake instead: the phase reports
- * the plan's `destroys` count as the `Destroys` search attribute before it
- * waits, and the gate description says so. A gate that skips itself when the
- * plan turns out additive is a new step kind, out of scope here.
+ * the plan's `destroys` count as the `Destroys` run outcome before the
+ * gate is reached, and the gate description says so. A gate that skips itself
+ * when the plan turns out additive is a new step kind, out of scope here.
  */
 export type TerraformGateMode = "on-destroy" | "always" | "never";
 export interface TerraformApplyOpConfig {
-    /** Op name (kebab-case). Also the default task queue and gate signal suffix. */
+    /** 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;
@@ -47,9 +96,15 @@ 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;
-    /** Temporal duration the gate waits before timing out. Default: core's own (48h). */
+    /** 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;
@@ -68,7 +123,7 @@ export interface TerraformApplyOpConfig {
      * Terraform has no automatic rollback: a half-applied plan is undone by
      * planning and applying the inverse, which is a decision about the estate
      * rather than something chant can synthesize. So compensation here is
-     * total or refused, the same stance `ApplyOp` takes (`lexicons/temporal/src/
+     * total or refused, the same stance `ApplyOp` takes (`packages/core/src/op/
      * composites/apply-op.ts`) — `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 needed. Supply `compensate: { command: "..." }` with a
@@ -77,8 +132,6 @@ export interface TerraformApplyOpConfig {
     compensate?: boolean | {
         command?: string;
     };
-    /** Override the task queue. Defaults to `name`. */
-    taskQueue?: string;
 }
 export interface TerraformApplyOpResources {
     /** Op resource — generates the Init/Plan/[Gate]/Apply workflow. */

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

@@ -1 +1 @@
-{"version":3,"file":"terraform-apply-op.d.ts","sourceRoot":"","sources":["../../src/composites/terraform-apply-op.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAA6B,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAS5E;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,QAAQ,GAAG,OAAO,CAAC;AAElE,MAAM,WAAW,sBAAsB;IACrC,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,+GAA+G;IAC/G,IAAI,EAAE,MAAM,CAAC;IACb,0GAA0G;IAC1G,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,mEAAmE;IACnE,EAAE,EAAE,YAAY,CAAC,OAAO,UAAU,CAAC,CAAC;CACrC;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,yBAAyB,CAqE1F"}
+{"version":3,"file":"terraform-apply-op.d.ts","sourceRoot":"","sources":["../../src/composites/terraform-apply-op.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AAEH,OAAO,EAA6B,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAW5E;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,QAAQ,GAAG,OAAO,CAAC;AAElE,MAAM,WAAW,sBAAsB;IACrC,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,+GAA+G;IAC/G,IAAI,EAAE,MAAM,CAAC;IACb,0GAA0G;IAC1G,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qGAAqG;IACrG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED,MAAM,WAAW,yBAAyB;IACxC,mEAAmE;IACnE,EAAE,EAAE,YAAY,CAAC,OAAO,UAAU,CAAC,CAAC;CACrC;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,yBAAyB,CA2G1F"}

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

@@ -7,7 +7,7 @@
  * the plan found. `terraform plan -detailed-exitcode` is the whole mechanism.
  * Exit 0 is "the world matches the configuration", exit 2 is drift, and
  * `terraformPlan` turns that into the boolean `changed`, which rides out of
- * the Op as the `Drift` search attribute.
+ * the Op as the run's `Drift` outcome.
  *
  * Phases: Init, Plan, and (for a finding mode that opens something) Report.
  *
@@ -23,37 +23,59 @@
  * post the JSON, and `terraform-watch-op.test.ts` asserts no reference to it
  * reaches the finding step.
  *
+ * The same rule holds on a live root, where the JSON is choudoufu's own
+ * bound/omissions/unowned document rather than a plan representation, and
+ * carries live identities and tag values for every resource the estate
+ * touched. `choudoufuLivePlan` composes the plan text and the adoption ledger
+ * into one `finding` string for exactly this reason: the body is one
+ * reference to one text field, so there is no arrangement of the args in
+ * which the document reaches a body.
+ *
+ * ## A live root reports three things, not one (#2105)
+ *
+ * `live: true` swaps the Plan step for `choudoufuLivePlan`. On a choudoufu
+ * root ownership is a pair of tags on the resource rather than an entry in a
+ * state file, so a plan against the live system can answer three questions
+ * where a stock plan answers one: whether the estate drifted (the
+ * `-detailed-exitcode` exit, `Drift` as before), how many live resources sit
+ * at a declared identity carrying no marker (`Unowned`), and how many of those
+ * an exact content match makes claimable (`Adoptable`). All three come off a
+ * single live read, published as three run outcomes from the one step.
+ *
+ * The finding modes then carry the adoption ledger under the plan text: one
+ * line per adoptable match with its address, its live identity and the
+ * `tofu-estate`/`tofu-address` values that claim it, in the row form
+ * `live-plan -adoption-only` prints, followed by any contested address. That
+ * is a report, not an action. `TerraformAdoptOp` next door is what writes the
+ * markers, and it gates first.
+ *
  * ## Findings reuse `reconcilePr`
  *
- * `issue` and `pull-request` call the temporal lexicon's `reconcilePr`
- * activity, the one place in chant that shells to `gh issue create` /
- * `gh pr create`, rather than growing a second copy of those calls here.
+ * `issue`, `comment` and `pull-request` call core's `reconcilePr` activity,
+ * the one place in chant that shells to `gh`, rather than growing a second
+ * copy of those calls here.
  * That activity built its own change-set summary and had no way to be handed
  * one, so #2087 added a single field to it (`ReconcilePrArgs.body`), which is
  * what carries the `-no-color` plan through. Note that the pull-request mode
  * of `reconcilePr` regenerates chant TypeScript via `chant import`; a
- * terraform-native regeneration of HCL from live state is #2089, so until
- * then `findingMode: "issue"` is the mode with an end-to-end answer and
- * `"pull-request"` opens a PR whose body is the plan.
+ * terraform-native regeneration of HCL from live state is #2089, so
+ * `findingMode: "issue"` is the mode with an end-to-end answer and
+ * `"pull-request"` opens a PR whose body is the plan. `"comment"` (#2231) is
+ * the mode for the plan-on-pull-request shape: the plan is posted onto the
+ * pull request that triggered the run and re-edited there on the next push,
+ * which is where a reviewer is already looking. It needs that trigger; a run
+ * without one fails the Report step by name rather than posting elsewhere. On a live root #2089's
+ * question has a different answer rather than a pending one, and it is not
+ * regeneration: see `TerraformAdoptOp`.
  *
  * ## The schedule
  *
- * A cron makes this a `{ op, schedule }` pair, the shape
- * `lexicons/temporal/src/composites/workflow-audit-op.ts` and
- * `reconcile-op.ts` return. The schedule resource is `Temporal::Schedule`,
- * built here through core's own `createResource` rather than imported from
- * `@intentius/chant-lexicon-temporal`: no lexicon in this repo imports
- * another lexicon's package at runtime, and a static import would mean a
- * project that installs terraform and runs `chant run` on the local executor
- * could not load `@intentius/chant-lexicon-terraform` at all without also
- * installing temporal. The declarable is the same one temporal's
- * `TemporalSchedule` produces (`createResource("Temporal::Schedule",
- * "temporal", {})`, `lexicons/temporal/src/resources.ts`), so temporal's
- * serializer renders it unchanged when a project has both.
- *
- * A project with no Temporal at all runs the same Op on a CI cron instead:
- * `generateOpsPipeline` against the github lexicon turns the Op plus its cron
- * into a workflow. `examples/scheduled-watch/` is that recipe.
+ * A cron lands on the Op itself as `schedule` (#2120), the same field
+ * `WatchOp` and `ConvergeOp` set. It is runtime-neutral data: `chant
+ * operator` reads it as this Op's tick cadence, `generateOpsPipeline` against
+ * the github lexicon renders it as a CI cron, and a hosting lexicon hands it
+ * to its own scheduler. The one-shot `chant run app-watch` path ignores it.
+ * `examples/scheduled-watch/` is the CI recipe.
  *
  * @example
  * ```typescript
@@ -62,41 +84,90 @@
  * // one-shot, local executor: chant run app-watch
  * export const { op } = TerraformWatchOp({ name: "app-watch", root: "app" });
  *
+ * // the plan as a sticky comment on the pull request that triggered the run
+ * export const { op } = TerraformWatchOp({
+ *   name: "app-plan",
+ *   root: "app",
+ *   findingMode: "comment",
+ * });
+ *
  * // nightly, opening an issue when the plan is non-empty
- * export const { op, schedule } = TerraformWatchOp({
+ * export const { op } = TerraformWatchOp({
  *   name: "app-watch",
  *   root: "app",
  *   schedule: "0 6 * * *",
  *   findingMode: "issue",
  * });
+ *
+ * // a choudoufu estate: drift, unowned and adoptable, with the ledger in the issue
+ * export const { op } = TerraformWatchOp({
+ *   name: "estate-watch",
+ *   root: "estate",
+ *   live: true,
+ *   findingMode: "issue",
+ * });
  * ```
  */
 import { OpResource } from "@intentius/chant/op";
-import type { Declarable } from "@intentius/chant/declarable";
 /**
  * What to do with a non-empty plan. A subset of core's `OpFindingMode`
  * (`packages/core/src/lexicon.ts`): `merge-request` is GitLab's spelling of
  * `pull-request` and is produced by the CI generator, not chosen here.
+ *
+ * `comment` (#2231) is the mode a plan-on-pull-request Op wants: the plan
+ * lands as one comment on the pull request that triggered the run and the
+ * next push edits that same comment. It needs a `pull_request` trigger on the
+ * `ScheduledOpSpec` the workflow is generated from, and the github generator
+ * refuses it by name on any other trigger.
  */
-export type TerraformFindingMode = "report" | "issue" | "pull-request";
+export type TerraformFindingMode = "report" | "issue" | "comment" | "pull-request";
 export interface TerraformWatchOpConfig {
-    /** Op name (kebab-case). Also the default task queue and schedule id base. */
+    /** Op name (kebab-case). */
     name: string;
     /** Key into the project's `terraform.roots`. The root carries dir, workspace, var files and backend config. */
     root: string;
     /**
-     * Cron expression. When set, a `Temporal::Schedule` is returned alongside
-     * the Op; omit for one-shot `chant run` on the local executor, or for a CI
-     * cron built by `generateOpsPipeline`.
+     * Cron expression. When set, it lands on the Op as `schedule` — the cadence
+     * `chant operator` ticks on and `generateOpsPipeline` renders as a CI cron.
+     * Omit for one-shot `chant run` on the local executor.
      */
     schedule?: string;
     /**
      * What to do when the plan proposes changes. Default: `"report"`, which
-     * opens nothing. The `Drift` search attribute and the run's own log are
+     * opens nothing. The `Drift` run outcome and the run's own log are
      * the report.
      */
     findingMode?: TerraformFindingMode;
-    /** Plan file the Plan step writes, relative to the root dir. Default: `chant.tfplan`. */
+    /**
+     * Watch a live root (#2105): the root runs `terraform.binary: "choudoufu"`
+     * and declares an estate, so the Plan phase is `choudoufuLivePlan` rather
+     * than `terraformPlan`. See the module doc for what changes.
+     *
+     * Declared here rather than detected, because a composite is built by
+     * `chant build` without reading a root module's `.tf` files. The activities
+     * detect the estate at run time (`op/activities/live-detect.ts`), but by then
+     * the phases are already serialized.
+     *
+     * Two things check the answer against the root's real mode, since a wrong
+     * one is otherwise silent (#2216). This function refuses a mismatch outright
+     * when it can resolve the mode synchronously, which is a
+     * `chant.config.json` project (`op/resolve-root-mode.ts`); TF028
+     * (`lint/post-synth/tf028.ts`) reports the same mismatch off the parsed HCL
+     * for every project, `chant.config.ts` included.
+     */
+    live?: boolean;
+    /**
+     * The estate to plan against, for a live root whose estate this Op should
+     * name explicitly. Omitted, `choudoufuLivePlan` auto-detects it from the
+     * root's own `live` block or `estate.chdf.hcl` sidecar, which is the usual
+     * case. Refused on a stock root.
+     */
+    estate?: string;
+    /**
+     * Plan file the Plan step writes, relative to the root dir. Default:
+     * `chant.tfplan`. Refused on a live root, where choudoufu takes no plan file
+     * at all.
+     */
     planFile?: string;
     /** `-upgrade` on the Init step: re-resolve provider and module versions. */
     upgrade?: boolean;
@@ -111,14 +182,10 @@ export interface TerraformWatchOpConfig {
     title?: string;
     /** Branch the pull-request mode opens from. Default: `reconcilePr`'s own. */
     branch?: string;
-    /** Override the task queue. Defaults to `name`. */
-    taskQueue?: string;
 }
 export interface TerraformWatchOpResources {
-    /** Op resource. Generates the Init/Plan/[Report] workflow. */
+    /** Op resource. Generates the Init/Plan/[Report] phases. */
     op: InstanceType<typeof OpResource>;
-    /** `Temporal::Schedule`, present only when `schedule` was given. */
-    schedule?: Declarable;
 }
 export declare function TerraformWatchOp(config: TerraformWatchOpConfig): TerraformWatchOpResources;
 //# sourceMappingURL=terraform-watch-op.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"terraform-watch-op.d.ts","sourceRoot":"","sources":["../../src/composites/terraform-watch-op.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AAEH,OAAO,EAAa,UAAU,EAAqB,MAAM,qBAAqB,CAAC;AAE/E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAI9D;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,OAAO,GAAG,cAAc,CAAC;AAcvE,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,+GAA+G;IAC/G,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,oBAAoB,CAAC;IACnC,yFAAyF;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,8DAA8D;IAC9D,EAAE,EAAE,YAAY,CAAC,OAAO,UAAU,CAAC,CAAC;IACpC,oEAAoE;IACpE,QAAQ,CAAC,EAAE,UAAU,CAAC;CACvB;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,yBAAyB,CA6D1F"}
+{"version":3,"file":"terraform-watch-op.d.ts","sourceRoot":"","sources":["../../src/composites/terraform-watch-op.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6GG;AAEH,OAAO,EAAa,UAAU,EAAqB,MAAM,qBAAqB,CAAC;AAS/E;;;;;;;;;;GAUG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,cAAc,CAAC;AAEnF,MAAM,WAAW,sBAAsB;IACrC,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,+GAA+G;IAC/G,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,oBAAoB,CAAC;IACnC;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,yBAAyB;IACxC,4DAA4D;IAC5D,EAAE,EAAE,YAAY,CAAC,OAAO,UAAU,CAAC,CAAC;CACrC;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,yBAAyB,CA8G1F"}

package/dist/config.d.ts

@@ -23,6 +23,23 @@
  */
 import { z } from "zod";
 import type { ChantConfig } from "@intentius/chant/config";
+/**
+ * chant's cross-lexicon delete-mode vocabulary (`lexicons/k8s/src/op/
+ * activities/kubectl.ts`'s `ApplyDeleteMode`, `packages/core/src/op/
+ * activities/apply.ts`'s `DeleteMode`), read here for a live root and mapped
+ * onto choudoufu's `policy` block (#2106): `"never"` requires the root's
+ * `policy` to set `undeclared_tagged` to `"keep"`, `"untag"` or `"report"`
+ * (TF026 enforces this at build time); `"owned-only"` is choudoufu's own
+ * default verb for that quadrant (`delete`) and needs nothing; `"gated"`
+ * needs nothing beyond `TerraformApplyOp`'s own approval gate. Inert on a
+ * stock root: choudoufu's `policy` block does not exist there.
+ */
+export declare const terraformDeleteModeSchema: z.ZodEnum<{
+    gated: "gated";
+    never: "never";
+    "owned-only": "owned-only";
+}>;
+export type TerraformDeleteMode = z.infer<typeof terraformDeleteModeSchema>;
 /**
  * One Terraform root module chant reads. `dir` is the only required field:
  * everything else names how the root is invoked rather than what it declares.
@@ -41,16 +58,40 @@ export declare const terraformRootSchema: z.ZodObject<{
     varFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
     /** `-backend-config` key/value pairs handed to `init`. */
     backendConfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    /** This root's declared delete mode. See {@link terraformDeleteModeSchema}. */
+    delete: z.ZodOptional<z.ZodEnum<{
+        gated: "gated";
+        never: "never";
+        "owned-only": "owned-only";
+    }>>;
 }, z.core.$strict>;
 export declare const terraformConfigSchema: z.ZodObject<{
     /**
-     * Which CLI drives the roots. The two are wire-compatible for everything
-     * this lexicon does, so the choice is recorded rather than inferred.
+     * Which CLI drives the roots. `terraform` and `tofu` are wire-compatible
+     * for everything this lexicon does, so the choice is recorded rather than
+     * inferred. `choudoufu` (#2103) is an OpenTofu fork: a root running it also
+     * needs a declared estate (a `live` block or an `estate.chdf.hcl` sidecar,
+     * seen by the shared HCL parse) before it counts as live. Declaring the
+     * binary alone runs the root stock, exactly as `terraform`/`tofu` do.
      */
     binary: z.ZodOptional<z.ZodEnum<{
+        choudoufu: "choudoufu";
         terraform: "terraform";
         tofu: "tofu";
     }>>;
+    /**
+     * How far a root's parse follows its `module` calls (#2112), spelled the
+     * way tflint spells it. `local` (the default) reads modules sourced from a
+     * relative path, so TF014, TF015 and TF020 see inside them; `none` reads
+     * only each root's own directory; `all` is reserved for fetching registry
+     * and git modules and is refused with a message, since chant fetches
+     * nothing. See `hcl/descend.ts`.
+     */
+    callModuleType: z.ZodOptional<z.ZodEnum<{
+        local: "local";
+        none: "none";
+        all: "all";
+    }>>;
     /** Named root modules. The name is the entity-key prefix, so keep it stable. */
     roots: z.ZodRecord<z.ZodString, z.ZodObject<{
         /** Root module directory, relative to the project root (where `chant.config.*` lives). */
@@ -61,6 +102,12 @@ export declare const terraformConfigSchema: z.ZodObject<{
         varFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
         /** `-backend-config` key/value pairs handed to `init`. */
         backendConfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        /** This root's declared delete mode. See {@link terraformDeleteModeSchema}. */
+        delete: z.ZodOptional<z.ZodEnum<{
+            gated: "gated";
+            never: "never";
+            "owned-only": "owned-only";
+        }>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type TerraformRootConfig = z.infer<typeof terraformRootSchema>;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB;IAC9B,0FAA0F;;IAE1F,4EAA4E;;IAE5E,0DAA0D;;IAE1D,0DAA0D;;kBAE1D,CAAC;AAEH,eAAO,MAAM,qBAAqB;IAChC;;;OAGG;;;;;IAEH,gFAAgF;;QAhBhF,0FAA0F;;QAE1F,4EAA4E;;QAE5E,0DAA0D;;QAE1D,0DAA0D;;;kBAY1D,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AACtE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,OAAO,QAAQ,yBAAyB,CAAC;IACvC,UAAU,WAAW;QACnB,SAAS,CAAC,EAAE,eAAe,CAAC;KAC7B;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,wBAAwB,GAAG,WAAW,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB;;;;EAA2C,CAAC;AAClF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB;IAC9B,0FAA0F;;IAE1F,4EAA4E;;IAE5E,0DAA0D;;IAE1D,0DAA0D;;IAE1D,+EAA+E;;;;;;kBAE/E,CAAC;AAEH,eAAO,MAAM,qBAAqB;IAChC;;;;;;;OAOG;;;;;;IAEH;;;;;;;OAOG;;;;;;IAEH,gFAAgF;;QA/BhF,0FAA0F;;QAE1F,4EAA4E;;QAE5E,0DAA0D;;QAE1D,0DAA0D;;QAE1D,+EAA+E;;;;;;;kBAyB/E,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AACtE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,OAAO,QAAQ,yBAAyB,CAAC;IACvC,UAAU,WAAW;QACnB,SAAS,CAAC,EAAE,eAAe,CAAC;KAC7B;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,wBAAwB,GAAG,WAAW,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC"}