@intentius/chant-lexicon-terraform 0.124.31 → 0.124.33

package/dist/op/activities/terraform.js

@@ -0,0 +1,1270 @@
+/**
+ * terraform Op activities (#2086) — init, plan, apply and show against a root
+ * module named in the project's `terraform.roots` config namespace (#2083).
+ *
+ * Shaped after `lexicons/k3s/src/op/activities/k3s.ts`: `promisify(exec)` with
+ * the caller's `AbortSignal` forwarded so a local timeout or Ctrl-C kills the
+ * child, and every command and environment string produced by a pure exported
+ * function so a test can assert on it without running terraform.
+ *
+ * Two invariants hold for every call:
+ *
+ *   - `TF_IN_AUTOMATION=1` is in the environment, which is what tells terraform
+ *     it is not talking to a person.
+ *   - `-input=false` is on every command that accepts it, so a missing variable
+ *     fails the step instead of blocking on a prompt nobody will answer.
+ *     `terraform show` is the one command that does not accept the flag
+ *     (terraform answers `flag provided but not defined: -input`), so it
+ *     carries the environment variable alone.
+ *
+ * `terraformApply` takes a saved plan file and nothing else on a stock root,
+ * since a bare apply re-plans at apply time, which is exactly the gap an
+ * approval gate exists to close, so it is refused rather than offered. On a
+ * live root (#2103, `terraform.binary: "choudoufu"` plus a declared estate)
+ * it is the opposite: choudoufu refuses a plan file by design, so
+ * `terraformApply` refuses one there and runs a bare `apply -auto-approve`
+ * instead.
+ *
+ * `choudoufuLivePlan`, `choudoufuLiveLs` and `choudoufuLiveCheck` (#2103) are
+ * choudoufu-only activities living in this same module for the same reason
+ * the four above do: pure command builders, the `promisify(exec)` shape, and
+ * no dependency on the lexicon's HCL parse. `./live-detect.ts` is a
+ * deliberately separate, cheap regex-based read of "does this root declare a
+ * live estate," used only to decide how `terraformApply` reads a non-zero
+ * exit and to
+ * auto-detect `-estate` for the two live-only reads that need it; the
+ * accurate, AST-based version lives in `../../hcl/parse.ts` and stays out of
+ * this module's dependency graph. `choudoufu version` is checked once per
+ * module load (`ensureChoudoufuVersion`) and refuses a binary older than
+ * {@link MIN_CHOUDOUFU_VERSION}.
+ */
+import { exec } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { promisify } from "node:util";
+import { resolve, dirname, join, relative, sep } from "node:path";
+import { loadChantConfigUpward } from "@intentius/chant/config";
+import { liveReadKey, memoLiveRead } from "@intentius/chant/live-read-session";
+import { terraformPlanDigest } from "../../plan-digest.js";
+import { choudoufuSetPlanParts, plannerForBinary, terraformChangeSetPart } from "../../change-set.js";
+import { detectLiveEstate } from "./live-detect.js";
+import { parseAdoptionCommands, readAdoptionLedger, renderAdoptionLedger, } from "../adoption.js";
+const execAsync = promisify(exec);
+/**
+ * `terraform show -json` on a large estate runs to megabytes, well past
+ * `exec`'s 1 MiB default, and the failure mode there is a truncated buffer
+ * rather than a clear error.
+ */
+const MAX_BUFFER = 64 * 1024 * 1024;
+/** Plan file written into the root directory when a step names none. */
+export const DEFAULT_PLAN_FILE = "chant.tfplan";
+/** Binary used when the `terraform` namespace records no preference. */
+export const DEFAULT_TERRAFORM_BINARY = "terraform";
+/** Where {@link choudoufuLivePlan} writes GitHub issue #788's JSON document, relative to the root directory. */
+export const DEFAULT_LIVE_PLAN_DOCUMENT_FILE = "chant.live-plan.json";
+/**
+ * choudoufu below this refuses. v0.12.0 brought `live-plan -json`, `live-ls`
+ * and `live-check -json` (#2103); v0.13.0 brought the approval artifact
+ * ([choudoufu #878](https://github.com/INTENTIUS/choudoufu/issues/878), PR
+ * 889): under a live block `plan -out=FILE` is accepted and `apply FILE`
+ * re-plans the live system and refuses on a mismatch with exit status 3.
+ * v0.14.0 brought the `-json` document on a configuration that names its own
+ * estate ([choudoufu #894](https://github.com/INTENTIUS/choudoufu/issues/894),
+ * PR 915), which is the shape every chant live root has: before it,
+ * {@link choudoufuLivePlan} could not produce the document for a real root at
+ * all. v0.15.0 brought the document's `adoptable` section and the `swept`
+ * list beside it
+ * ([choudoufu #962](https://github.com/INTENTIUS/choudoufu/issues/962), PR
+ * 963), which is the only place a content match reaches a machine: before it,
+ * a declared resource whose identity the provider assigns could never be
+ * adopted through the document at all, and `TerraformAdoptOp`'s own
+ * acceptance suite had never passed on any binary (#2241).
+ *
+ * {@link terraformApply} depends on the exit-3 refusal, `describeResources()`
+ * and both document-reading Ops depend on the document, and the adopt path
+ * depends on the `adoptable` section, so the floor is the release that
+ * shipped the last of the three.
+ */
+export const MIN_CHOUDOUFU_VERSION = "0.15.0";
+/**
+ * The choudoufu release a gated wave needs for a choudoufu root (#3459):
+ * the set digest on `live-plan-set -json`, and `live-wave-apply` with its
+ * resume file (choudoufu#1754, merged as choudoufu PR 1816 after v0.21.0).
+ * choudoufu's changelog lists both under `v0.22.0 (Unreleased)`, so this is
+ * the version main releases as.
+ *
+ * Only the wave path checks it, so plain `terraform` and `tofu` roots, and a
+ * choudoufu root run any other way, do not wait on it. A dev build prints no
+ * release version. For one, the check is the capability itself: a set plan
+ * document without a top-level `digest` came from a choudoufu older than
+ * choudoufu#1754, and {@link choudoufuPlanSet} refuses it.
+ */
+export const MIN_CHOUDOUFU_WAVES_VERSION = "0.22.0";
+/**
+ * Where a choudoufu root's wave files live, relative to the project root:
+ * `<root>/plan-set.json` (the set plan document chant planned and the
+ * approver approved), `<root>/resume-<digest>.json` (choudoufu's resume
+ * file) and `<root>/out/` (plan files and logs).
+ */
+export const CHOUDOUFU_WAVES_DIR = ".chant/choudoufu-waves";
+/** `live-wave-apply`'s exit statuses (choudoufu#1754). */
+export const CHOUDOUFU_WAVE_EXIT = { landed: 0, error: 1, setMoved: 3, rootFailed: 4 };
+/**
+ * choudoufu's own refusal summary for `-out` on the `live-plan -estate`
+ * surface (`internal/command/live_mode.go`). That is the one surface where a
+ * saved plan file is still refused: a directory reached through `-estate` has
+ * no `live` block, so plain `plan` and `apply` there are ordinary state-backed
+ * commands and a file written from this form would be applied by something
+ * that never heard of the estate. Under a `live` block `plan -out` is
+ * accepted (choudoufu #878).
+ */
+export const CHOUDOUFU_LIVE_PLAN_OUT_REFUSAL = "Saved plan files are not available under live resource markers";
+/** Exit status choudoufu's approval refusals carry: not 1 (any ordinary failure), not 2 (`-detailed-exitcode`). */
+export const CHOUDOUFU_APPROVAL_EXIT_CODE = 3;
+/** Summary line of choudoufu's refusal when the fresh live plan differs from the approved plan file. */
+export const CHOUDOUFU_APPROVAL_MISMATCH_REFUSAL = "The approved plan no longer matches the live system";
+/** Summary line of choudoufu's sibling refusal when the plan file was produced against another estate. */
+export const CHOUDOUFU_WRONG_ESTATE_REFUSAL = "The approved plan belongs to a different estate";
+export { terraformPlanChangeSet, terraformPlanDigest } from "../../plan-digest.js";
+// ── Pure command and environment builders ───────────────────────────────────
+/**
+ * Quote a command-line argument for the shell `exec` runs it through, leaving
+ * ordinary paths and `key=value` pairs untouched so command strings stay
+ * readable in logs and in tests.
+ */
+export function quoteArg(value) {
+    return /^[A-Za-z0-9._/:=@,+-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** Which CLI drives the roots: `terraform.binary`, defaulting to `terraform`. */
+export function terraformBinary(config) {
+    return config?.binary ?? DEFAULT_TERRAFORM_BINARY;
+}
+/**
+ * Environment for every invocation. `TF_IN_AUTOMATION` suppresses the
+ * "run terraform apply next" hand-holding and is terraform's own signal that
+ * no human is watching; `TF_WORKSPACE` is how a workspace gets selected
+ * without a separate `terraform workspace select` round-trip.
+ */
+export function terraformEnvironment(root) {
+    return {
+        TF_IN_AUTOMATION: "1",
+        ...(root?.workspace ? { TF_WORKSPACE: root.workspace } : {}),
+    };
+}
+/** `terraform init`, with the root's `backendConfig` as `-backend-config=k=v` flags. */
+export function terraformInitCommand(opts) {
+    const parts = [opts.binary, "init", "-input=false"];
+    if (opts.upgrade)
+        parts.push("-upgrade");
+    if (opts.reconfigure)
+        parts.push("-reconfigure");
+    for (const [key, value] of Object.entries(opts.backendConfig ?? {})) {
+        parts.push(`-backend-config=${quoteArg(`${key}=${value}`)}`);
+    }
+    return parts.join(" ");
+}
+/**
+ * `terraform plan`. `-detailed-exitcode` is what makes the run answerable:
+ * 0 means no changes, 2 means changes, and anything else is a failure. See
+ * {@link terraformPlan}.
+ */
+export function terraformPlanCommand(opts) {
+    const parts = [opts.binary, "plan", "-input=false", "-detailed-exitcode"];
+    if (opts.destroy)
+        parts.push("-destroy");
+    for (const varFile of opts.varFiles ?? [])
+        parts.push(`-var-file=${quoteArg(varFile)}`);
+    for (const [name, value] of Object.entries(opts.vars ?? {}).sort(([a], [b]) => a.localeCompare(b))) {
+        if (value === undefined)
+            continue;
+        parts.push(`-var=${quoteArg(`${name}=${typeof value === "string" ? value : JSON.stringify(value)}`)}`);
+    }
+    parts.push(`-out=${quoteArg(opts.planFile)}`);
+    return parts.join(" ");
+}
+/**
+ * `terraform apply <planFile>` — a saved plan, never a bare apply. The same
+ * command on a live root: choudoufu v0.13.0 admits a plan file under a `live`
+ * block, and a matched one applies without re-prompting, exactly as stock's
+ * own `apply <planfile>` does, so no `-auto-approve` is needed or passed.
+ */
+export function terraformApplyCommand(opts) {
+    return `${opts.binary} apply -input=false ${quoteArg(opts.planFile)}`;
+}
+/**
+ * `live-plan -detailed-exitcode [-json] [-estate=<estate>]`. `-json` is what
+ * prints GitHub issue #788's document instead of the plan; the human render
+ * needs a second invocation without it (see {@link choudoufuLivePlan}).
+ *
+ * `estate` is omitted exactly when the configuration names its own estate.
+ * choudoufu refuses `-estate` beside a `live` block or an `estate.chdf.hcl`
+ * sidecar ("Estate named by both the live block and -estate"), and since
+ * v0.14.0 it does not need one: the run reads the declared name itself and
+ * prints the same document ([choudoufu #894](https://github.com/INTENTIUS/choudoufu/issues/894),
+ * PR 915). The flag is still how a root that declares nothing names an
+ * estate for the run.
+ *
+ * `adoptionOnly` makes that second invocation print the adoption ledger and
+ * nothing else (GitHub issue #587). It is refused here alongside `json`
+ * because choudoufu refuses the pair itself, and a builder that emitted a
+ * command the binary rejects would move the error to the far side of a
+ * process spawn for no gain.
+ */
+export function choudoufuLivePlanCommand(opts) {
+    if (opts.json && opts.adoptionOnly) {
+        throw new Error("choudoufuLivePlanCommand: -adoption-only and -json cannot be combined. choudoufu refuses the pair " +
+            "(-adoption-only asks for the adoption ledger and -json asks for the bound/omissions/unowned " +
+            "document), so the two reports come from two runs.");
+    }
+    const parts = [opts.binary, "live-plan", "-detailed-exitcode"];
+    if (opts.json)
+        parts.push("-json");
+    if (opts.adoptionOnly)
+        parts.push("-adoption-only");
+    if (opts.noColor)
+        parts.push("-no-color");
+    if (opts.estate !== undefined)
+        parts.push(`-estate=${quoteArg(opts.estate)}`);
+    return parts.join(" ");
+}
+/** `live-ls -estate=<estate> -json [-consistent]`. */
+export function choudoufuLiveLsCommand(opts) {
+    const parts = [opts.binary, "live-ls", `-estate=${quoteArg(opts.estate)}`, "-json"];
+    if (opts.consistent)
+        parts.push("-consistent");
+    return parts.join(" ");
+}
+/**
+ * `live-check -json`. No `DIR` argument: the activity already runs in the
+ * root directory (`cwd`), so `-json` alone checks it, since DIR defaults to
+ * `.`. Makes no cloud calls; a non-zero exit is a refusal, not a failure this
+ * builder's caller need distinguish from one.
+ */
+export function choudoufuLiveCheckCommand(opts) {
+    return `${opts.binary} live-check -json`;
+}
+/**
+ * Project `live-plan -json`'s `unowned` section into counts: how many live
+ * resources at a declared identity carry no ownership marker for this
+ * estate, and of those, how many an exact content match makes adoptable
+ * (`adopt_tofu_estate`/`adopt_tofu_address` present).
+ */
+export function countLivePlanUnowned(document) {
+    const doc = (document ?? {});
+    const unowned = Array.isArray(doc.unowned) ? doc.unowned : [];
+    const claimable = (entry) => {
+        const e = entry;
+        return Boolean(e?.adopt_tofu_estate || e?.adopt_tofu_address);
+    };
+    const matched = Array.isArray(doc.adoptable) ? doc.adoptable.filter(claimable).length : 0;
+    return { unowned: unowned.length, adoptable: unowned.filter(claimable).length + matched };
+}
+/**
+ * `terraform show`. The one command here that takes no `-input` flag
+ * (terraform answers `flag provided but not defined: -input`), so automation
+ * rests on `TF_IN_AUTOMATION` alone. Show reads an artifact and prompts for
+ * nothing in the first place.
+ */
+export function terraformShowCommand(opts) {
+    const parts = [opts.binary, "show", opts.json ? "-json" : "-no-color"];
+    if (opts.planFile)
+        parts.push(quoteArg(opts.planFile));
+    return parts.join(" ");
+}
+/**
+ * Project a plan's `resource_changes` into add/change/destroy counts, the same
+ * three terraform prints at the end of a plan. A replace (`["delete","create"]`)
+ * counts as one add and one destroy, exactly as terraform reports it.
+ */
+export function countPlanChanges(planJson) {
+    const counts = { adds: 0, changes: 0, destroys: 0 };
+    const changes = planJson?.resource_changes;
+    if (!Array.isArray(changes))
+        return counts;
+    for (const entry of changes) {
+        const actions = entry?.change?.actions;
+        if (!Array.isArray(actions))
+            continue;
+        if (actions.includes("create"))
+            counts.adds++;
+        if (actions.includes("update"))
+            counts.changes++;
+        if (actions.includes("delete"))
+            counts.destroys++;
+    }
+    return counts;
+}
+/**
+ * Parse the ordinary "Plan: N to add, N to change, N to destroy." (or "...N
+ * to import, N to add...") summary line out of a human-readable `live-plan`
+ * render (#2106). "No changes." — the exit-0 case — matches nothing and
+ * reads as zero on every count, the same conservative default
+ * {@link countPlanChanges} falls back to on a shape it does not recognize.
+ */
+export function parseChoudoufuPlanSummary(text) {
+    const match = /Plan:\s*(?:\d+\s+to import,\s*)?(\d+)\s+to add,\s*(\d+)\s+to change,\s*(\d+)\s+to destroy\./.exec(text);
+    if (!match)
+        return { adds: 0, changes: 0, destroys: 0 };
+    return { adds: Number(match[1]), changes: Number(match[2]), destroys: Number(match[3]) };
+}
+// ── choudoufu version check ─────────────────────────────────────────────────
+/**
+ * Parse a semver-ish string's leading `major.minor.patch`, ignoring anything
+ * after (a `-dev`/`-rc1` suffix, say). Unparseable input reads as `0.0.0`,
+ * which sorts as "older than everything" rather than crashing, since a
+ * version string this check cannot make sense of should not be quietly trusted.
+ */
+function parseVersionCore(version) {
+    const m = /(\d+)\.(\d+)\.(\d+)/.exec(version);
+    if (!m)
+        return [0, 0, 0];
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+/** Whether `version` is strictly older than `min`, comparing `major.minor.patch` numerically. */
+export function isOlderVersion(version, min) {
+    const a = parseVersionCore(version);
+    const b = parseVersionCore(min);
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] < b[i];
+    }
+    return false;
+}
+/**
+ * Extract the release version from `choudoufu version`'s human-readable
+ * output: `"choudoufu v0.13.0 (based on OpenTofu v1.13.0)\non darwin_arm64"`.
+ * `choudoufu version -json`'s `terraform_version` field is the wrong number
+ * here: it names the upstream OpenTofu base this build forked from, not the
+ * choudoufu release itself (`internal/command/views/version.go`), so this
+ * reads the human form's `choudoufu vX.Y.Z` prefix instead. A dev build with
+ * no release tag baked in (`version.Fork` unset) prints only the upstream
+ * line and carries no choudoufu version to check at all: `undefined` here,
+ * same as an output this cannot parse.
+ */
+export function parseChoudoufuVersion(versionOutput) {
+    const m = /^choudoufu\s+v?(\d+\.\d+\.\d+)/m.exec(versionOutput);
+    return m?.[1];
+}
+/** Cached per activity-module load (#2103): `choudoufu version` runs at most once per process. */
+let choudoufuVersionCheck;
+/**
+ * Refuse a choudoufu binary older than {@link MIN_CHOUDOUFU_VERSION}. Runs
+ * `choudoufu version` (never `-json`; see {@link parseChoudoufuVersion}) at
+ * most once per module load, cached across every activity call regardless of
+ * which one triggered it. A no-op for `terraform`/`tofu`, and a no-op when
+ * the version cannot be determined at all (a dev build): this refuses a
+ * known-old binary, not an unknown one.
+ */
+async function ensureChoudoufuVersion(binary, signal) {
+    if (binary !== "choudoufu")
+        return;
+    choudoufuVersionCheck ?? (choudoufuVersionCheck = (async () => {
+        const { stdout } = await execAsync(`${binary} version`, { env: process.env, signal });
+        const version = parseChoudoufuVersion(stdout);
+        if (version === undefined)
+            return;
+        if (isOlderVersion(version, MIN_CHOUDOUFU_VERSION)) {
+            throw new Error(`choudoufu ${version} is older than the minimum supported version v${MIN_CHOUDOUFU_VERSION} ` +
+                "(needed for live-plan -json, live-ls, live-check -json, the approval artifact `plan -out` / " +
+                "`apply <planfile>` pair, and the document's adoptable section). Upgrade choudoufu.");
+        }
+    })());
+    return choudoufuVersionCheck;
+}
+/** Test-only: clear the cached version check so a test can simulate a fresh module load. */
+export function __resetChoudoufuVersionCheckForTests() {
+    choudoufuVersionCheck = undefined;
+    choudoufuWavesVersionCheck = undefined;
+}
+/**
+ * Why `choudoufu version`'s output cannot drive a gated wave, or `undefined`
+ * when it can (#3459). A release older than
+ * {@link MIN_CHOUDOUFU_WAVES_VERSION} is refused. A dev build names no
+ * release and passes here; {@link parseChoudoufuPlanSet} then refuses a set
+ * plan document with no digest, which is what an older dev build prints.
+ */
+export function choudoufuWavesVersionRefusal(versionOutput) {
+    const version = parseChoudoufuVersion(versionOutput);
+    if (version === undefined || !isOlderVersion(version, MIN_CHOUDOUFU_WAVES_VERSION))
+        return undefined;
+    return (`choudoufu ${version} is older than v${MIN_CHOUDOUFU_WAVES_VERSION}, the first release with the set digest and ` +
+        "live-wave-apply (choudoufu#1754) that a gated wave uses for a choudoufu root. Upgrade choudoufu, or run the " +
+        "fan-out without --wave-gate.");
+}
+/** Cached like {@link choudoufuVersionCheck}, and only ever run on the wave path. */
+let choudoufuWavesVersionCheck;
+async function ensureChoudoufuWavesVersion(binary, signal) {
+    choudoufuWavesVersionCheck ?? (choudoufuWavesVersionCheck = (async () => {
+        const { stdout } = await execAsync(`${binary} version`, { env: process.env, signal });
+        const refusal = choudoufuWavesVersionRefusal(stdout);
+        if (refusal)
+            throw new Error(refusal);
+    })());
+    return choudoufuWavesVersionCheck;
+}
+/**
+ * Read `terraform.roots` out of the project config and resolve one entry.
+ * The walk is {@link loadChantConfigUpward}, so a step invoked from a
+ * subdirectory still finds the project's `chant.config.*`, and `dir` resolves
+ * against the directory that config lives in rather than against the cwd.
+ *
+ * Also runs {@link ensureChoudoufuVersion} and, on a choudoufu root,
+ * {@link detectLiveEstate}, so every activity answers "is this root live"
+ * the same way without repeating either check itself.
+ */
+async function resolveRoot(args, signal) {
+    const start = resolve(args.cwd ?? process.cwd());
+    const { config, configPath } = await loadChantConfigUpward(start);
+    const projectRoot = configPath ? dirname(configPath) : start;
+    const namespace = config.terraform;
+    const roots = namespace?.roots ?? {};
+    const root = roots[args.root];
+    if (!root) {
+        const known = Object.keys(roots).sort();
+        throw new Error(`terraform: no root named "${args.root}" in terraform.roots` +
+            `${configPath ? ` (${configPath})` : ""} — ` +
+            (known.length > 0 ? `known roots: ${known.join(", ")}` : "the namespace declares no roots"));
+    }
+    const binary = terraformBinary(namespace);
+    const dir = resolve(projectRoot, root.dir);
+    await ensureChoudoufuVersion(binary, signal);
+    const estate = binary === "choudoufu" ? detectLiveEstate(dir) : undefined;
+    // `estate` stays what it has always been: the estate the root's own HCL
+    // declares, which is what decides whether `-estate` may be passed at all.
+    // `live` is the broader question, and a root that names its estate in
+    // chant.config rather than in HCL (#2479) is just as live - that is the
+    // `-estate` flag form, choudoufu's own supported second pipeline.
+    const configEstate = binary === "choudoufu" ? root.estate : undefined;
+    return {
+        binary,
+        root,
+        dir,
+        ...(estate !== undefined ? { estate } : {}),
+        live: estate !== undefined || configEstate !== undefined,
+        projectRoot,
+    };
+}
+/** Run `cmd` in `dir`, forwarding the signal so an abort kills the child. */
+async function run(cmd, dir, env, signal) {
+    return execAsync(cmd, { cwd: dir, env: { ...process.env, ...env }, signal, maxBuffer: MAX_BUFFER });
+}
+/**
+ * Echo a subprocess's own output to the console for a human watching a
+ * `chant run` step. Both streams land on real stderr (`console.error`),
+ * never on real stdout (chant#2395): every activity here is reachable two
+ * ways — as a declared Op step, where a human is watching the terminal and
+ * stdout/stderr are both visible to them, and as an internal read a reader
+ * like `describeResources()` makes on a caller's behalf (`choudoufuLivePlan`,
+ * via `../../describe-resources.ts`), where the caller's own stdout is
+ * reserved for exactly one thing: the command's own JSON document, when one
+ * was asked for. Putting the subprocess's raw output on real stdout used to
+ * mean a caller running under `--json` (`chant lifecycle plan --live --json`,
+ * `chant components status --live --json`) got that raw `choudoufu
+ * live-plan -json` text landing on stdout ahead of chant's own document — two
+ * concatenated JSON values on one stream, which broke `convergeTick`'s bare
+ * `JSON.parse(stdout)` (`packages/core/src/op/activities/converge.ts`) with
+ * `Unexpected non-whitespace character after JSON at position …`. Stderr is
+ * still on the same terminal for an interactive `chant run`, so a human loses
+ * nothing; a `--json` caller now gets exactly one document on stdout.
+ */
+function report(stdout, stderr) {
+    if (stdout)
+        console.error(stdout);
+    if (stderr)
+        console.error(stderr);
+}
+// ── Activities ──────────────────────────────────────────────────────────────
+/**
+ * `terraform init` in the named root, with the root's `backendConfig` supplied
+ * as `-backend-config` flags. Uses the longInfra profile: init downloads
+ * providers and modules, a network call of unpredictable size.
+ */
+export async function terraformInit(args, signal) {
+    const { binary, root, dir } = await resolveRoot(args, signal);
+    const cmd = terraformInitCommand({
+        binary,
+        ...(root.backendConfig ? { backendConfig: root.backendConfig } : {}),
+        ...(args.upgrade ? { upgrade: true } : {}),
+        ...(args.reconfigure ? { reconfigure: true } : {}),
+    });
+    const { stdout, stderr } = await run(cmd, dir, terraformEnvironment(root), signal);
+    report(stdout, stderr);
+    return { dir, ...(root.workspace ? { workspace: root.workspace } : {}) };
+}
+/**
+ * `terraform plan -detailed-exitcode -out=<planFile>` in the named root, then
+ * `terraform show` over the written plan in both `-json` and `-no-color` form.
+ *
+ * The exit code is the answer, not an error condition: 0 is a plan with no
+ * changes, 2 is a plan with changes, and anything else, 1 included, is a
+ * failure thrown with terraform's own stderr attached. Both `show` renders
+ * come back with the result, so a gate, a report or an apply downstream reads
+ * the plan that ran instead of planning again against a moved world.
+ *
+ * Uses the longInfra profile: plan refreshes every resource against its
+ * provider.
+ */
+export async function terraformPlan(args, signal) {
+    const { binary, root, dir } = await resolveRoot(args, signal);
+    const planFile = args.planFile ?? DEFAULT_PLAN_FILE;
+    const env = terraformEnvironment(root);
+    const cmd = terraformPlanCommand({
+        binary,
+        planFile,
+        ...(root.varFiles ? { varFiles: root.varFiles } : {}),
+        ...(args.vars ? { vars: args.vars } : {}),
+        ...(args.destroy ? { destroy: true } : {}),
+    });
+    let changed;
+    try {
+        const { stdout, stderr } = await run(cmd, dir, env, signal);
+        report(stdout, stderr);
+        changed = false;
+    }
+    catch (err) {
+        // An abort or a spawn failure carries no numeric exit code. That is not
+        // terraform answering, so it propagates untouched.
+        const failure = err;
+        if (typeof failure.code !== "number")
+            throw err;
+        if (failure.code !== 2) {
+            const detail = (failure.stderr ?? "").trim() || (failure.stdout ?? "").trim();
+            throw new Error(`${binary} plan failed in ${dir} (exit ${failure.code})${detail ? `\n${detail}` : ""}`);
+        }
+        report(failure.stdout ?? "", failure.stderr ?? "");
+        changed = true;
+    }
+    const jsonRun = await run(terraformShowCommand({ binary, json: true, planFile }), dir, env, signal);
+    const textRun = await run(terraformShowCommand({ binary, json: false, planFile }), dir, env, signal);
+    const json = JSON.parse(jsonRun.stdout);
+    return {
+        changed,
+        planFile,
+        dir,
+        json,
+        text: textRun.stdout,
+        planDigest: terraformPlanDigest(json),
+        changeSet: terraformChangeSetPart({
+            member: args.root,
+            plan: json,
+            planner: plannerForBinary(binary),
+            ...((root.estate ?? root.workspace) ? { scope: root.estate ?? root.workspace } : {}),
+        }),
+        ...countPlanChanges(json),
+    };
+}
+/**
+ * Which of choudoufu's two approval refusals an exit-3 apply printed, or
+ * `undefined` when the output carries neither summary line. Reads both the
+ * stderr the diagnostic is written to and the stdout the fresh plan is
+ * rendered on, since the two travel separately.
+ */
+export function classifyApprovalRefusal(output) {
+    if (output.includes(CHOUDOUFU_WRONG_ESTATE_REFUSAL))
+        return "wrong-estate";
+    if (output.includes(CHOUDOUFU_APPROVAL_MISMATCH_REFUSAL))
+        return "approval-mismatch";
+    return undefined;
+}
+/**
+ * `terraform apply <planFile>` in the named root, on a stock root and on a
+ * live one alike.
+ *
+ * Neither kind has a bare-apply mode here: without a saved `planFile`, apply
+ * re-plans at apply time and acts on something no gate ever saw, so a missing
+ * one is refused before the CLI runs. choudoufu v0.13.0 is what makes the
+ * live half of that true (choudoufu #878, PR 889): `plan -out` is accepted
+ * under a `live` block, and `apply <planfile>` re-plans against the live
+ * system, compares its fresh plan with the file's down to the planned values,
+ * and applies only when they agree.
+ *
+ * When they do not, choudoufu exits **3**, neither 1 (any ordinary failure)
+ * nor `-detailed-exitcode`'s 2, with one of two named refusals. That is an
+ * answer rather than a breakage, so it comes back as a result (`refused`,
+ * `refusal`) instead of a thrown error, and a workflow can route the run back
+ * to review. Exit 3 is read this way only on a live root; on a stock root
+ * nothing produces it and every non-zero exit stays a failure.
+ *
+ * Uses the longInfra profile.
+ */
+export async function terraformApply(args, signal) {
+    const { binary, root, dir, live } = await resolveRoot(args, signal);
+    const hasPlanFile = typeof args.planFile === "string" && args.planFile.trim() !== "";
+    if (!hasPlanFile) {
+        throw new Error("terraformApply: planFile is required — this activity applies a saved plan and has no bare-apply mode. " +
+            "Pass the Plan step's own output (`plan.out.planFile`).");
+    }
+    const planFile = args.planFile;
+    const cmd = terraformApplyCommand({ binary, planFile });
+    try {
+        const { stdout, stderr } = await run(cmd, dir, terraformEnvironment(root), signal);
+        report(stdout, stderr);
+        return { planFile, dir, applied: true };
+    }
+    catch (err) {
+        // An abort or a spawn failure carries no numeric exit code. That is not
+        // the CLI answering, so it propagates untouched, same as terraformPlan.
+        const failure = err;
+        const refused = live && failure.code === CHOUDOUFU_APPROVAL_EXIT_CODE
+            ? classifyApprovalRefusal(`${failure.stderr ?? ""}\n${failure.stdout ?? ""}`)
+            : undefined;
+        if (refused === undefined)
+            throw err;
+        report(failure.stdout ?? "", failure.stderr ?? "");
+        return {
+            planFile,
+            dir,
+            applied: false,
+            refused,
+            refusal: (failure.stderr ?? "").trim() || (failure.stdout ?? "").trim(),
+        };
+    }
+}
+/**
+ * `terraform output -json` in the named root, as `{ name: value }` (#3049).
+ * A sensitive output's value comes back like any other, since the caller
+ * asked for the values to hand them on.
+ */
+export async function terraformOutputs(args, signal) {
+    const { binary, root, dir } = await resolveRoot(args, signal);
+    const { stdout } = await run(`${binary} output -json`, dir, terraformEnvironment(root), signal);
+    const parsed = JSON.parse(stdout || "{}");
+    return Object.fromEntries(Object.entries(parsed).map(([name, entry]) => [name, entry?.value]));
+}
+// ── choudoufu gated waves (#3459) ───────────────────────────────────────────
+/**
+ * `live-plan-set -json` over one root, from the project root, so the
+ * document names the root by its path from there, which is what
+ * `live-wave-apply` resolves it against.
+ */
+export function choudoufuPlanSetCommand(opts) {
+    return [opts.binary, "live-plan-set", "-json", `-out-dir=${quoteArg(opts.outDir)}`, quoteArg(opts.root)].join(" ");
+}
+/**
+ * `live-wave-apply` over a one-root set. The set chant hands choudoufu is
+ * one root, so choudoufu's waves over it are a single wave and `-wave=1` is
+ * always that root's. chant's waves are the order; choudoufu's command is
+ * the apply, with its set check and its resume file.
+ */
+export function choudoufuWaveApplyCommand(opts) {
+    return [
+        opts.binary,
+        "live-wave-apply",
+        `-plan-set=${quoteArg(opts.planSet)}`,
+        `-digest=${quoteArg(opts.digest)}`,
+        "-wave=1",
+        `-resume=${quoteArg(opts.resume)}`,
+        `-out-dir=${quoteArg(opts.outDir)}`,
+        "-json",
+    ].join(" ");
+}
+/**
+ * The root's directory as a set plan document names it: its path from the
+ * project root, with forward slashes. `undefined` when the root is the
+ * project root itself or outside it, since choudoufu takes only roots inside
+ * the working directory.
+ */
+export function choudoufuSetRootPath(projectRoot, dir) {
+    const rel = relative(projectRoot, dir);
+    if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || resolve(projectRoot, rel) !== resolve(dir))
+        return undefined;
+    return rel.split(sep).join("/");
+}
+/**
+ * Whether a gated wave runs this root through choudoufu's own set commands
+ * (#3459), and if not, why not. It does for a live choudoufu root that
+ * `live-plan-set` can plan as chant would: those commands run plain `init`
+ * and `plan` in each root, with no `-var-file`, no `-var` and no
+ * `-backend-config`, so a root that needs any of them goes the `plan -out`
+ * and `apply PLANFILE` way instead, where choudoufu's per-root refusal
+ * (choudoufu #878) still stands in front of the apply.
+ */
+export async function choudoufuWaveRoot(args, signal) {
+    const resolved = await resolveRoot(args, signal);
+    if (resolved.binary !== "choudoufu")
+        return { wave: false, reason: `the root runs ${resolved.binary}` };
+    if (!resolved.live)
+        return { wave: false, reason: "the root declares no live estate" };
+    if (args.vars && Object.values(args.vars).some((v) => v !== undefined)) {
+        return { wave: false, reason: "the step passes -var values, which live-plan-set does not take" };
+    }
+    if (resolved.root.varFiles && resolved.root.varFiles.length > 0) {
+        return { wave: false, reason: "the root has var files, which live-plan-set does not take" };
+    }
+    if (resolved.root.backendConfig && Object.keys(resolved.root.backendConfig).length > 0) {
+        return { wave: false, reason: "the root has backend config, which live-plan-set does not take" };
+    }
+    const root = choudoufuSetRootPath(resolved.projectRoot, resolved.dir);
+    if (root === undefined)
+        return { wave: false, reason: "the root's directory is not inside the project" };
+    return { wave: true, root };
+}
+const isObjectValue = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Read `live-plan-set -json`'s document for one root (#3459). Refuses a
+ * document with no set digest: that choudoufu predates choudoufu#1754, and
+ * this is how a dev build, which names no release, is held to
+ * {@link MIN_CHOUDOUFU_WAVES_VERSION}. Refuses a root that did not plan,
+ * with choudoufu's own error.
+ */
+export function parseChoudoufuPlanSet(stdout, opts) {
+    let doc;
+    try {
+        doc = JSON.parse(stdout);
+    }
+    catch {
+        throw new Error(`choudoufu live-plan-set printed no JSON document for root "${opts.member}"`);
+    }
+    if (!isObjectValue(doc) || !Array.isArray(doc.roots)) {
+        throw new Error(`choudoufu live-plan-set printed no set plan document for root "${opts.member}"`);
+    }
+    if (typeof doc.digest !== "string" || doc.digest === "") {
+        throw new Error(`choudoufu's set plan document for root "${opts.member}" carries no set digest, so this choudoufu predates ` +
+            `choudoufu#1754. A gated wave over a choudoufu root needs v${MIN_CHOUDOUFU_WAVES_VERSION} or later.`);
+    }
+    const roots = doc.roots.filter(isObjectValue);
+    const entry = roots.find((r) => r.root === opts.root);
+    if (roots.length !== 1 || !entry) {
+        throw new Error(`choudoufu's set plan document for root "${opts.member}" names ${roots.map((r) => String(r.root)).join(", ") || "no root"}, ` +
+            `not only "${opts.root}"`);
+    }
+    if (entry.status !== "planned" || !isObjectValue(entry.plan)) {
+        const stage = typeof entry.stage === "string" && entry.stage ? ` at ${entry.stage}` : "";
+        const error = typeof entry.error === "string" && entry.error ? `: ${entry.error}` : "";
+        throw new Error(`choudoufu could not plan root "${opts.member}"${stage}${error}`);
+    }
+    if (typeof entry.digest !== "string" || entry.digest === "") {
+        throw new Error(`choudoufu's set plan document gives root "${opts.member}" no digest`);
+    }
+    const [changeSet] = choudoufuSetPlanParts({ document: doc, memberFor: () => opts.member });
+    return {
+        setDigest: doc.digest,
+        rootDigest: entry.digest,
+        planDigest: terraformPlanDigest(entry.plan),
+        changed: entry.changes === true,
+        json: entry.plan,
+        changeSet: changeSet,
+    };
+}
+/** The directory a root's wave files go in, absolute. */
+function choudoufuWavesDir(projectRoot, root) {
+    return join(projectRoot, CHOUDOUFU_WAVES_DIR, root.replace(/[^A-Za-z0-9._-]/g, "_"));
+}
+/** A path under the project root as choudoufu, run from there, should be given it. */
+function fromProject(projectRoot, path) {
+    return relative(projectRoot, path).split(sep).join("/");
+}
+/**
+ * Plan one live choudoufu root as a one-root set: `live-plan-set -json` from
+ * the project root (#3459). The document goes to
+ * `<CHOUDOUFU_WAVES_DIR>/<root>/plan-set.json`, the file a later
+ * `live-wave-apply` hands back to choudoufu with the set digest.
+ */
+export async function choudoufuPlanSet(args, signal) {
+    const resolved = await resolveRoot(args, signal);
+    const { binary, root, dir, projectRoot } = resolved;
+    if (binary !== "choudoufu")
+        throw new Error(`choudoufuPlanSet: root "${args.root}" runs ${binary}, not choudoufu`);
+    await ensureChoudoufuWavesVersion(binary, signal);
+    const rootPath = choudoufuSetRootPath(projectRoot, dir);
+    if (rootPath === undefined)
+        throw new Error(`choudoufuPlanSet: root "${args.root}" (${dir}) is not inside ${projectRoot}`);
+    const wavesDir = choudoufuWavesDir(projectRoot, args.root);
+    mkdirSync(wavesDir, { recursive: true });
+    const cmd = choudoufuPlanSetCommand({ binary, root: rootPath, outDir: fromProject(projectRoot, join(wavesDir, "out")) });
+    let stdout;
+    try {
+        const out = await run(cmd, projectRoot, terraformEnvironment(root), signal);
+        report("", out.stderr);
+        stdout = out.stdout;
+    }
+    catch (err) {
+        // 2 is "planned, with changes" and 4 is "a root failed", which the
+        // document itself explains. Anything else is the command not running.
+        const failure = err;
+        if (failure.code !== 2 && failure.code !== 4)
+            throw err;
+        report("", failure.stderr ?? "");
+        stdout = failure.stdout ?? "";
+    }
+    const parsed = parseChoudoufuPlanSet(stdout, { member: args.root, root: rootPath });
+    const planSetFile = join(wavesDir, "plan-set.json");
+    writeFileSync(planSetFile, stdout);
+    return { ...parsed, planSetFile, root: rootPath };
+}
+/**
+ * The resume file to hand choudoufu for `setDigest`, from what an earlier
+ * attempt carried, or `undefined`. choudoufu refuses a resume file written
+ * for another digest, and a re-planned root with a moved plan has another
+ * digest, so only a file for this same set comes back.
+ */
+export function carriedChoudoufuResume(carried, setDigest) {
+    if (!isObjectValue(carried) || carried.kind !== "choudoufu-wave-resume")
+        return undefined;
+    if (carried.setDigest !== setDigest || !isObjectValue(carried.resume))
+        return undefined;
+    return carried.resume.set_digest === setDigest ? carried.resume : undefined;
+}
+/** One line for each of `live-wave-apply`'s exit statuses, with choudoufu's own error when it gave one. */
+export function describeChoudoufuWaveExit(exitCode, result, stderr) {
+    const error = isObjectValue(result) && typeof result.error === "string" && result.error ? result.error : "";
+    const moved = isObjectValue(result) && Array.isArray(result.moved)
+        ? result.moved
+            .filter(isObjectValue)
+            .map((m) => `${String(m.root)} moved: approved ${String(m.approved_digest)}, now ${String(m.fresh_digest)}`)
+        : [];
+    const detail = error || moved.join("; ") || stderr.trim().split("\n").find((l) => l.trim() !== "")?.trim() || "";
+    const suffix = detail ? ` (${detail})` : "";
+    switch (exitCode) {
+        case CHOUDOUFU_WAVE_EXIT.landed:
+            return "landed";
+        case CHOUDOUFU_WAVE_EXIT.setMoved:
+            return `choudoufu refused the approved set: the root's plan moved since it was approved, and nothing was applied${suffix}`;
+        case CHOUDOUFU_WAVE_EXIT.rootFailed:
+            return `choudoufu could not land the root; its resume file records why${suffix}`;
+        default:
+            return `choudoufu live-wave-apply could not run (exit ${exitCode})${suffix}`;
+    }
+}
+/**
+ * Apply one live choudoufu root through `live-wave-apply` (#3459), with the
+ * set plan document and set digest {@link choudoufuPlanSet} produced. When
+ * the root carried a resume file for this same digest from an earlier
+ * attempt, it is written back first, so choudoufu sees what it already
+ * recorded. Its resume file after the run comes back as `carry`, landed or
+ * not.
+ *
+ * Never throws for a choudoufu answer: exit 3 (the set moved) and exit 4 (the
+ * root failed) come back with `landed: false`, and so does exit 1. An abort
+ * or a spawn failure propagates.
+ */
+export async function choudoufuWaveApply(args, signal) {
+    const resolved = await resolveRoot(args, signal);
+    const { binary, root, projectRoot } = resolved;
+    if (binary !== "choudoufu")
+        throw new Error(`choudoufuWaveApply: root "${args.root}" runs ${binary}, not choudoufu`);
+    await ensureChoudoufuWavesVersion(binary, signal);
+    const wavesDir = choudoufuWavesDir(projectRoot, args.root);
+    mkdirSync(wavesDir, { recursive: true });
+    // One file per digest: choudoufu refuses a resume file written for
+    // another, and a file left by an earlier set must not block this one.
+    const resumeFile = join(wavesDir, `resume-${args.setDigest.replace(/^sha256:/, "").slice(0, 16)}.json`);
+    const carried = carriedChoudoufuResume(args.carried, args.setDigest);
+    if (carried !== undefined)
+        writeFileSync(resumeFile, JSON.stringify(carried, null, 2) + "\n");
+    const cmd = choudoufuWaveApplyCommand({
+        binary,
+        planSet: fromProject(projectRoot, args.planSetFile),
+        digest: args.setDigest,
+        resume: fromProject(projectRoot, resumeFile),
+        outDir: fromProject(projectRoot, join(wavesDir, "out")),
+    });
+    let exitCode = 0;
+    let stdout = "";
+    let stderr = "";
+    try {
+        const out = await run(cmd, projectRoot, terraformEnvironment(root), signal);
+        stdout = out.stdout;
+        stderr = out.stderr;
+    }
+    catch (err) {
+        const failure = err;
+        if (typeof failure.code !== "number")
+            throw err;
+        exitCode = failure.code;
+        stdout = failure.stdout ?? "";
+        stderr = failure.stderr ?? "";
+    }
+    report(stdout, stderr);
+    let result;
+    try {
+        result = stdout.trim() ? JSON.parse(stdout) : undefined;
+    }
+    catch {
+        result = undefined;
+    }
+    let carry;
+    if (existsSync(resumeFile)) {
+        try {
+            carry = { kind: "choudoufu-wave-resume", setDigest: args.setDigest, resume: JSON.parse(readFileSync(resumeFile, "utf8")) };
+        }
+        catch {
+            carry = undefined;
+        }
+    }
+    return {
+        exitCode,
+        landed: exitCode === CHOUDOUFU_WAVE_EXIT.landed,
+        ...(result !== undefined ? { result } : {}),
+        ...(carry ? { carry } : {}),
+        message: describeChoudoufuWaveExit(exitCode, result, stderr),
+    };
+}
+/**
+ * `terraform show` over current state, or over a saved plan when `planFile` is
+ * given. Returns the parsed `-json` output and the `-no-color` render, plus
+ * the add/change/destroy counts when the subject is a plan. State has no
+ * change set, so for state the three counts are zero.
+ *
+ * Uses the fastIdempotent profile: show reads an artifact and calls no
+ * provider.
+ */
+export async function terraformShow(args, signal) {
+    const { binary, root, dir } = await resolveRoot(args, signal);
+    const env = terraformEnvironment(root);
+    const planFile = args.planFile;
+    const jsonRun = await run(terraformShowCommand({ binary, json: true, ...(planFile ? { planFile } : {}) }), dir, env, signal);
+    const textRun = await run(terraformShowCommand({ binary, json: false, ...(planFile ? { planFile } : {}) }), dir, env, signal);
+    const json = JSON.parse(jsonRun.stdout);
+    return {
+        source: planFile ? "plan" : "state",
+        json,
+        text: textRun.stdout,
+        dir,
+        ...(planFile ? { planFile } : {}),
+        ...(planFile ? countPlanChanges(json) : { adds: 0, changes: 0, destroys: 0 }),
+    };
+}
+/**
+ * The estate a choudoufu-only activity runs against, in precedence order:
+ * `args.estate` when the step names one, then the root's own `estate`
+ * (#2479), then the one {@link resolveRoot} auto-detected from the root's
+ * `live` block or `estate.chdf.hcl` sidecar. Throws when none of the three
+ * names one, since `live-plan`/`live-ls` need an estate to filter on, unlike
+ * a stock command.
+ *
+ * The order is step, then root, then declaration - narrowest first. A root's
+ * `estate` and a declared one cannot both be in play on a healthy project:
+ * TF028 refuses that pair at build time, for the same reason choudoufu
+ * refuses `-estate` beside a `live` block. The precedence here is what
+ * happens if that refusal is ever bypassed, and it deliberately lets the
+ * declaration win, because the declaration is the thing choudoufu itself
+ * will act on.
+ */
+function resolveEstate(args, resolved, activity) {
+    const estate = args.estate ?? resolved.estate ?? resolved.root.estate;
+    if (!estate) {
+        throw new Error(`${activity}: no estate to run against. Declare one in the root's \`live\` block or ` +
+            "`estate.chdf.hcl` sidecar, give the root an `estate` in chant.config, or pass `estate` explicitly.");
+    }
+    return estate;
+}
+/**
+ * `choudoufu live-plan -detailed-exitcode -json -estate=<estate>`, plus a
+ * second `live-plan` without `-json` for the human-readable render. GitHub
+ * issue #788's JSON document carries no render of the plan itself
+ * (`views.LivePlanDocument` has no such field), so unlike `terraformPlan`'s
+ * single saved artifact this genuinely needs two live reads.
+ *
+ * The exit code is the answer, exactly as `terraformPlan`'s is: 0 is no
+ * drift, 2 is drift, and anything else is a failure thrown with choudoufu's
+ * own stderr attached. The JSON document is written to `documentPath` (under
+ * `dir`) for a later step or reviewer to open directly.
+ *
+ * Uses the longInfra profile: like `terraformPlan`, this reads the live
+ * system in full (the estate-wide sweep).
+ */
+/**
+ * The JSON document within a `live-plan -json` stdout: everything from the
+ * first line that is a bare `{` to the end. Returns the input unchanged when
+ * no such line exists.
+ *
+ * Defensive, and kept deliberately. choudoufu v0.14.0 keeps `-json` stdout to
+ * the document on every form of live root, so on a supported binary this
+ * returns its input unchanged and the slice never fires: it was written for
+ * the `-estate` path's refresh progress lines
+ * ([choudoufu #894](https://github.com/INTENTIUS/choudoufu/issues/894), fixed
+ * in PR 915, which routes every human-prose renderer of a `-json` run through
+ * `views.View.StdoutOnStderr()`). What it buys is that a future writer put
+ * back on stdout ahead of the document costs a stale slice rather than a
+ * `JSON.parse` failure, and a stdout carrying no document at all still fails
+ * in `JSON.parse` with the real text in the error.
+ */
+export function liveDocumentFrom(stdout) {
+    const lines = stdout.split("\n");
+    const start = lines.findIndex((line) => line.trim() === "{");
+    return start === -1 ? stdout : lines.slice(start).join("\n");
+}
+/**
+ * `live-plan -detailed-exitcode -json` alone: the document, without the
+ * second run that renders the plan for a human (chant #2498).
+ *
+ * Two of {@link choudoufuLivePlan}'s three callers never read `text`:
+ * `describeResources()` indexes the document and `predictBehaviour()` prices
+ * it. Each was paying for the render anyway, and on a drifted estate whose
+ * provider retries a deleted resource the render costs as much as the
+ * document. This is the read they make instead.
+ *
+ * Inside a `withLiveReadSession` scope (core's `live-read-session.ts`) the
+ * run is shared with every identical read in the same command, keyed on
+ * the root, its resolved directory, the binary, the estate, the flags and
+ * the root's environment. The graph command runs in such a scope, so its
+ * observation and its prediction see one `live-plan` between them, and the
+ * graph's statuses and the prediction's figures are statements about the
+ * same read. The document file is still written on every call.
+ */
+export async function choudoufuLivePlanDocument(args, signal) {
+    const resolved = await resolveRoot(args, signal);
+    const { binary, dir } = resolved;
+    const estate = resolveEstate(args, resolved, "choudoufuLivePlan");
+    const env = terraformEnvironment(resolved.root);
+    const documentPath = args.documentPath ?? DEFAULT_LIVE_PLAN_DOCUMENT_FILE;
+    // A root that declares its own estate is run without `-estate`: choudoufu
+    // refuses the flag beside a declaration and, since v0.14.0, settles the name
+    // from the declaration itself. See {@link choudoufuLivePlanCommand}.
+    const estateFlag = resolved.estate === undefined ? { estate } : {};
+    const planCmd = choudoufuLivePlanCommand({ binary, ...estateFlag, json: true });
+    // The document's `adoptable` and `swept` sections are populated only on a
+    // run that asked the estate-wide sweep the account-bounded question, which
+    // `-adoption-only` implies and a `-json` run does not
+    // (`internal/command/live_collect_unclaimed.go`). `-adoption-only` cannot
+    // ride the `-json` invocation, so the env var is how a document-producing
+    // run asks for the same thing. Set only under `adoptionOnly`: the sweep is
+    // an account-wide list per admitted type, and an observation read has no use
+    // for it.
+    const adoptionOnly = args.adoptionOnly === true;
+    const planEnv = adoptionOnly ? { ...env, TOFU_LIVE_COLLECT_UNCLAIMED: "1" } : env;
+    const key = liveReadKey("live-plan", { root: args.root, dir, binary, estate, adoptionOnly, env });
+    const { drift, jsonStdout } = await memoLiveRead(key, async () => {
+        try {
+            const { stdout, stderr } = await run(planCmd, dir, planEnv, signal);
+            report(stdout, stderr);
+            return { drift: false, jsonStdout: stdout };
+        }
+        catch (err) {
+            const failure = err;
+            if (typeof failure.code !== "number")
+                throw err;
+            if (failure.code !== 2) {
+                const detail = (failure.stderr ?? "").trim() || (failure.stdout ?? "").trim();
+                throw new Error(`${binary} live-plan failed in ${dir} (exit ${failure.code})${detail ? `\n${detail}` : ""}`);
+            }
+            report(failure.stdout ?? "", failure.stderr ?? "");
+            return { drift: true, jsonStdout: failure.stdout ?? "" };
+        }
+    });
+    // Belt and braces: v0.14.0 keeps `-json` stdout to the document, so this is
+    // the identity on a supported binary. See {@link liveDocumentFrom}.
+    const document = liveDocumentFrom(jsonStdout);
+    const json = JSON.parse(document);
+    writeFileSync(join(dir, documentPath), document);
+    return { drift, json, dir, documentPath, estate, ...countLivePlanUnowned(json) };
+}
+export async function choudoufuLivePlan(args, signal) {
+    const { drift, json, dir, documentPath, estate, ...unowned } = await choudoufuLivePlanDocument(args, signal);
+    const resolved = await resolveRoot(args, signal);
+    const { binary } = resolved;
+    const env = terraformEnvironment(resolved.root);
+    const estateFlag = resolved.estate === undefined ? { estate } : {};
+    // #788's document carries no render of the human plan itself
+    // (`views.LivePlanDocument` has no such field), so the human text needs a
+    // second live read rather than a field on the same response. `-adoption-only`
+    // (#2105) changes which report that second read prints, never whether there
+    // is one: choudoufu refuses the flag alongside `-json`, so the two reports
+    // were always going to be two runs.
+    const textCmd = choudoufuLivePlanCommand({
+        binary,
+        ...estateFlag,
+        json: false,
+        noColor: true,
+        ...(args.adoptionOnly ? { adoptionOnly: true } : {}),
+    });
+    // The human render carries `-detailed-exitcode` too, so a plan with changes
+    // comes back as exit 2 on this call exactly as it does on the `-json` one.
+    // Both are success, and the drift answer is already settled above, so exit 2
+    // here yields its stdout rather than throwing; anything else is a failure
+    // with choudoufu's own output attached.
+    let text;
+    try {
+        text = (await run(textCmd, dir, env, signal)).stdout;
+    }
+    catch (err) {
+        const failure = err;
+        if (failure.code !== 2) {
+            const detail = (failure.stderr ?? "").trim() || (failure.stdout ?? "").trim();
+            throw new Error(`${binary} live-plan (human render) failed in ${dir} (exit ${String(failure.code)})` +
+                `${detail ? `\n${detail}` : ""}`);
+        }
+        text = failure.stdout ?? "";
+    }
+    // An `adoptable[]` row carries its own tagging command in the document
+    // (choudoufu #962). An `unowned[]` row does not, and the render is the only
+    // place one is printed for it, so the parse still runs on an adoption run
+    // and the map still feeds that half. A candidate off an ordinary run carries
+    // the two marker values and no command, which is the whole ownership
+    // contract either way.
+    const ledger = readAdoptionLedger(json, args.adoptionOnly ? parseAdoptionCommands(text) : undefined);
+    const ledgerText = renderAdoptionLedger(ledger, estate);
+    return {
+        drift,
+        json,
+        text,
+        ledger: ledgerText,
+        finding: `${text.trimEnd()}\n\n${ledgerText}\n`,
+        adoptions: ledger.adoptions,
+        contested: ledger.contested,
+        ambiguous: ledger.ambiguous,
+        swept: ledger.swept,
+        dir,
+        documentPath,
+        estate,
+        ...unowned,
+        ...parseChoudoufuPlanSummary(text),
+    };
+}
+/**
+ * `choudoufu live-ls -estate=<estate> -json [-consistent]`: every resource
+ * the account holds under the estate, read straight from the Resource Groups
+ * Tagging API. No configuration, state or record store is read.
+ *
+ * Uses the fastIdempotent profile: like `terraformShow`, this reads an
+ * artifact-shaped answer and does not plan.
+ */
+export async function choudoufuLiveLs(args, signal) {
+    const resolved = await resolveRoot(args, signal);
+    const { binary, dir } = resolved;
+    const estate = resolveEstate(args, resolved, "choudoufuLiveLs");
+    const env = terraformEnvironment(resolved.root);
+    const consistent = args.consistent === true;
+    const cmd = choudoufuLiveLsCommand({ binary, estate, ...(consistent ? { consistent: true } : {}) });
+    // Shared with every identical listing in the same read session, the way
+    // {@link choudoufuLivePlanDocument} shares the document (chant #2498).
+    const key = liveReadKey("live-ls", { root: args.root, dir, binary, estate, consistent, env });
+    const stdout = await memoLiveRead(key, async () => {
+        const result = await run(cmd, dir, env, signal);
+        report(result.stdout, result.stderr);
+        return result.stdout;
+    });
+    return { json: JSON.parse(stdout), dir, estate };
+}
+/**
+ * Claim the adoptable matches an adoption ledger found, by writing the two
+ * ownership markers onto each live resource (#2105).
+ *
+ * ## Why a tag write and not a policy verb
+ *
+ * choudoufu's `policy` block has an `adopt` verb for exactly this cell
+ * (`declared_untagged`), and `site/content/docs/use/migrate.md` names
+ * `policy { declared_untagged = "adopt" }` as the way to adopt a whole estate
+ * at once instead of one resource at a time. That would have been the smaller
+ * write: one apply, no tagging calls of chant's own. It is not reachable from
+ * outside the configuration, and #2105 checked both ways in:
+ *
+ *   - a `live` block in a terraform override file is dropped in silence.
+ *     `Module.mergeFile` (choudoufu's `internal/configs/module.go`) merges
+ *     backends, cloud blocks, providers and resources from an override file
+ *     and has no `Lives` case at all, so an `override.tf` carrying
+ *     `terraform { live { policy { declared_untagged = "adopt" } } }` changes
+ *     nothing. Measured, not inferred: a policy block with a deliberately
+ *     invalid verb in an override file passes `live-check` clean, and the same
+ *     block in a primary file is refused by name.
+ *   - a second primary file carrying one is refused outright: "A module may
+ *     have only one 'live' block." So is a sidecar beside an in-block form.
+ *
+ * Which leaves editing the root's own checked-in live configuration, running
+ * an apply, and putting it back — a mutation of a reviewed file, with a
+ * failure mode (a run that dies between the two edits) that leaves the estate
+ * declaring "adopt everything declared and unmarked" for every later apply.
+ * chant does not do that to a repository it does not own.
+ *
+ * So the mechanism is the tag write, which choudoufu's own migration guide
+ * calls the whole contract: "There is no `choudoufu adopt` command and no need
+ * for one. Two tags is the whole contract (`live/MARKERS.md`), so any tool
+ * that writes two tags can adopt a resource." The command each write runs is
+ * the paste-ready one choudoufu printed under `live-plan -adoption-only`,
+ * carried on the candidate — built from choudoufu's own provider
+ * configuration, so it lands on the region and endpoint the plan just read
+ * rather than wherever an operator's AWS CLI profile points, and shell-quoted
+ * by choudoufu for exactly this use.
+ *
+ * ## What it refuses
+ *
+ * A candidate with no printed command (a service whose tagging call this fork
+ * does not spell out: IAM, Route53, S3) is refused with its two marker values
+ * named, not guessed at. A contested address — more than one live resource at
+ * one declared identity — is refused because no single tag write claims it;
+ * `contested` is passed in so the Op's own result names what was refused
+ * beside what was written, and nothing in this function can adopt one, since
+ * `readAdoptionLedger` never puts a contested candidate in `adoptions`.
+ *
+ * Uses the longInfra profile: one tagging round trip per resource, against the
+ * cloud.
+ */
+export async function choudoufuAdopt(args, signal) {
+    const resolved = await resolveRoot(args, signal);
+    const { dir } = resolved;
+    const env = terraformEnvironment(resolved.root);
+    const adoptions = args.adoptions ?? [];
+    const contested = args.contested ?? [];
+    const adopted = [];
+    const refused = [];
+    for (const candidate of contested) {
+        refused.push({
+            addr: candidate.addr,
+            identity: candidate.identity,
+            reason: "more than one live resource sits at this declared identity, so no single tag write claims it. " +
+                `Delete the duplicate, or write tofu-estate=${candidate.markerEstate} ` +
+                `tofu-address=${candidate.markerAddress} onto the one you mean.`,
+        });
+    }
+    for (const candidate of adoptions) {
+        if (!candidate.command) {
+            refused.push({
+                addr: candidate.addr,
+                identity: candidate.identity,
+                reason: `${candidate.type} is tagged through its own service call, which choudoufu does not print a ` +
+                    `command for. Write tofu-estate=${candidate.markerEstate} ` +
+                    `tofu-address=${candidate.markerAddress} onto it with that call.`,
+            });
+            continue;
+        }
+        const { stdout, stderr } = await run(candidate.command, dir, env, signal);
+        report(stdout, stderr);
+        adopted.push(candidate.addr);
+    }
+    return {
+        mechanism: "tag-write",
+        adopted,
+        adoptedCount: adopted.length,
+        refused,
+        ambiguous: new Set(contested.map((c) => c.addr)).size,
+        dir,
+    };
+}
+/**
+ * `choudoufu live-check -json`: whether the configuration in this root can
+ * move under live resource markers, and what stops it if it cannot. Makes no
+ * cloud calls and needs no `live` block at all, since the check this activity
+ * runs works on any configuration, which is why it needs no `estate`.
+ *
+ * A non-zero exit is a refusal choudoufu reports, not a failure of this
+ * activity: `refused: true` carries it back rather than throwing. An abort
+ * or a spawn failure (no numeric exit code) still throws.
+ *
+ * Uses the fastIdempotent profile: no cloud calls, no state.
+ */
+export async function choudoufuLiveCheck(args, signal) {
+    const { binary, root, dir } = await resolveRoot(args, signal);
+    const env = terraformEnvironment(root);
+    const cmd = choudoufuLiveCheckCommand({ binary });
+    const parseOrUndefined = (text) => {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    try {
+        const { stdout, stderr } = await run(cmd, dir, env, signal);
+        report(stdout, stderr);
+        return { refused: false, json: parseOrUndefined(stdout), text: stdout, dir };
+    }
+    catch (err) {
+        const failure = err;
+        if (typeof failure.code !== "number")
+            throw err;
+        const stdout = failure.stdout ?? "";
+        report(stdout, failure.stderr ?? "");
+        return { refused: true, json: parseOrUndefined(stdout), text: stdout, dir };
+    }
+}