@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/src/op/activities/terraform.ts

@@ -45,12 +45,16 @@ import { tmpdir } from "node:os";
 import { promisify } from "node:util";
 import { resolve, dirname, join, relative, sep } from "node:path";
 import { loadChantConfigUpward } from "@intentius/chant/config";
+import { findWorkspaceRoot } from "@intentius/chant/project-root";
 import { liveReadKey, memoLiveRead } from "@intentius/chant/live-read-session";
 import { terraformPlanDigest } from "../../plan-digest";
 import { choudoufuSetPlanParts, plannerForBinary, terraformChangeSetPart } from "../../change-set";
 import type { ChangeSetPart } from "@intentius/chant/change-set";
 import type { TerraformConfig, TerraformRootConfig } from "../../config";
 import { detectLiveEstate } from "./live-detect";
+import { backendConfigValues } from "../../backend-config";
+import { lockTimeoutArgs } from "../../lock-timeout";
+import { coneArgs, readPlanCone, type PlanCone } from "../../cone";
 import {
   parseAdoptionCommands,
   readAdoptionLedger,
@@ -116,6 +120,36 @@ export const MIN_CHOUDOUFU_VERSION = "0.15.0";
  */
 export const MIN_CHOUDOUFU_WAVES_VERSION = "0.22.0";
 
+/**
+ * The choudoufu release a composed run of estates needs (#4445): a root with
+ * no `live` block that calls estate directories as modules, planned and
+ * applied as one walk, with a `terraform_estate_outputs` read of another
+ * estate in the run answered inside it (choudoufu#2059, first released in
+ * v0.31.0). Only the composed estate run (`compose/estate.ts`) checks it;
+ * below it the members plan wave by wave. A dev build names no release and
+ * passes, as for the other floors.
+ */
+export const MIN_CHOUDOUFU_ESTATES_VERSION = "0.31.0";
+
+/**
+ * The choudoufu release whose `live-graph -json -from-plan=<file>` prints the
+ * engine graph document (chant#4520's design section 4, choudoufu#2285), the
+ * one `describeResources()` reads engine facts from on a live root
+ * (chant#4528). choudoufu's changelog lists the command under
+ * `v0.32.0 (Unreleased)`, so this is the version it releases as. The chant
+ * side of the same contract, the first chant that writes those facts, is
+ * `ENGINE_FACTS_FLOOR` in core's engine-facts.ts, which is NEXT_RELEASE
+ * until the cut.
+ *
+ * Not a refusal. Facts are for people and never feed a decision, so a
+ * choudoufu without the command (a usage error, see
+ * {@link classifyLiveGraphFailure}) leaves `facts` absent with one note
+ * naming this version, and the rest of the read is unchanged. The check is
+ * the capability, not the version string: a local or dev build names a
+ * version below this or none at all, and still carries the command.
+ */
+export const MIN_CHOUDOUFU_GRAPH_VERSION = "0.32.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
@@ -163,6 +197,14 @@ export interface TerraformRootArgs {
    * `process.cwd()`, which is the project root under `chant run`.
    */
   cwd?: string;
+  /**
+   * The directory the root's files are read from in place of the entry's
+   * `dir`, relative to the project root (chant#4542). A promote or rollback
+   * under a release sets it to the release's recorded copy of the root; the
+   * entry's workspace, var files, backend config and estate still apply, and
+   * its var files and backend-config files resolve against this directory.
+   */
+  dir?: string;
 }
 
 export interface TerraformInitArgs extends TerraformRootArgs {
@@ -191,6 +233,27 @@ export interface TerraformPlanArgs extends TerraformRootArgs {
    * of that file changes nothing else.
    */
   targets?: string[];
+  /**
+   * `false` skips `show -no-color`, the human-readable render (#4479). The
+   * plan then runs one `show` process, `show -json`, whose document gives the
+   * digest, the change set and everything a caller derives from `json`, and
+   * {@link TerraformPlanResult.text} is `""`. For a caller that never reads
+   * the text, such as the `terraform-apply` capability. Default: `true`.
+   */
+  text?: boolean;
+  /**
+   * How long the plan waits for another run's state lock (#4545), passed as
+   * `-lock-timeout` unless `TF_CLI_ARGS` or `TF_CLI_ARGS_plan` names one.
+   * Default: no flag, terraform's own (no wait).
+   */
+  lockTimeout?: string;
+  /**
+   * choudoufu only (#4545): plan the cone of the change since this revision
+   * (`-cone=<base>`) on a root under a `live` block that is not an estate
+   * file. Any other root, binary, or a plan with `targets` or `destroy`,
+   * plans in full. {@link TerraformPlanResult.cone} says which it was.
+   */
+  cone?: string;
 }
 
 export interface TerraformApplyArgs extends TerraformRootArgs {
@@ -211,6 +274,8 @@ export interface TerraformApplyArgs extends TerraformRootArgs {
    * separate to pass.
    */
   planFile?: string;
+  /** How long the apply waits for another run's state lock (#4545), as {@link TerraformPlanArgs.lockTimeout}. */
+  lockTimeout?: string;
 }
 
 export interface TerraformShowArgs extends TerraformRootArgs {
@@ -280,6 +345,13 @@ export interface TerraformInitResult {
   dir: string;
   /** Workspace the run selected via `TF_WORKSPACE`, when the root names one. */
   workspace?: string;
+  /**
+   * The root module directory relative to the chant workspace root, with `/`
+   * separators (chant#4482), when the root sits inside a workspace. A
+   * TerraformApplyOp publishes it as the `TerraformRootPath` run outcome, so a
+   * ledger read can name the member whose directory holds the root it applied.
+   */
+  rootPath?: string;
 }
 
 /** Counts projected out of a plan's `resource_changes`. */
@@ -304,7 +376,7 @@ export interface TerraformPlanResult extends PlanChangeCounts {
   dir: string;
   /** `terraform show -json <planFile>`, parsed. */
   json: unknown;
-  /** `terraform show -no-color <planFile>` — the human-readable plan. */
+  /** `terraform show -no-color <planFile>` — the human-readable plan. `""` when the plan ran with `text: false`. */
   text: string;
   /**
    * This plan's identity (#2300) — {@link terraformPlanDigest} over
@@ -320,6 +392,8 @@ export interface TerraformPlanResult extends PlanChangeCounts {
    * `composeChangeSet` and bind the run's gate to the document's digest.
    */
   changeSet: ChangeSetPart;
+  /** Set when the plan was asked for a cone (#4545): the cone it planned, or why it planned the whole estate. */
+  cone?: PlanCone;
 }
 
 /**
@@ -537,19 +611,24 @@ export function terraformEnvironment(root?: Pick<TerraformRootConfig, "workspace
   };
 }
 
-/** `terraform init`, with the root's `backendConfig` as `-backend-config=k=v` flags. */
+/**
+ * `terraform init`, with the root's `backendConfigFiles` as
+ * `-backend-config=<path>` flags and then its `backendConfig` as
+ * `-backend-config=k=v` flags (chant#4459): init applies later flags over
+ * earlier ones, so a pair overrides a file. A path is passed as written; init
+ * runs in the root's directory, which a relative one resolves against.
+ */
 export function terraformInitCommand(opts: {
   binary: string;
   backendConfig?: Record<string, string>;
+  backendConfigFiles?: readonly string[];
   upgrade?: boolean;
   reconfigure?: boolean;
 }): string {
   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}`)}`);
-  }
+  for (const value of backendConfigValues(opts)) parts.push(`-backend-config=${quoteArg(value)}`);
   return parts.join(" ");
 }
 
@@ -565,9 +644,12 @@ export function terraformPlanCommand(opts: {
   vars?: Record<string, unknown>;
   destroy?: boolean;
   targets?: string[];
+  /** Extra flags after the fixed ones (#4545): `-lock-timeout`, `-cone`. */
+  extra?: readonly string[];
 }): string {
   const parts = [opts.binary, "plan", "-input=false", "-detailed-exitcode"];
   if (opts.destroy) parts.push("-destroy");
+  for (const flag of opts.extra ?? []) parts.push(quoteArg(flag));
   for (const target of [...new Set(opts.targets ?? [])].sort()) parts.push(`-target=${quoteArg(target)}`);
   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))) {
@@ -584,8 +666,9 @@ export function terraformPlanCommand(opts: {
  * 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: { binary: string; planFile: string }): string {
-  return `${opts.binary} apply -input=false ${quoteArg(opts.planFile)}`;
+export function terraformApplyCommand(opts: { binary: string; planFile: string; extra?: readonly string[] }): string {
+  const extra = (opts.extra ?? []).map((f) => ` ${quoteArg(f)}`).join("");
+  return `${opts.binary} apply -input=false${extra} ${quoteArg(opts.planFile)}`;
 }
 
 /**
@@ -629,6 +712,37 @@ export function choudoufuLivePlanCommand(opts: {
   return parts.join(" ");
 }
 
+/**
+ * `live-graph -json -from-plan=<file> [-estate=<estate>]` (choudoufu#2285).
+ * No `DIR` argument: like {@link choudoufuLiveCheckCommand}, the activity
+ * runs in the root directory, which is DIR's default. `-estate` follows
+ * {@link choudoufuLivePlanCommand}'s rule: only for a root that does not
+ * name its own estate. `-history` is never passed: record versions take a
+ * listing per record and `s3:ListBucketVersions`, and an observation read
+ * has no use for them (the #4520 ruling, Q6: opt-in).
+ */
+export function choudoufuLiveGraphCommand(opts: { binary: string; fromPlan: string; estate?: string }): string {
+  const parts = [opts.binary, "live-graph", "-json", `-from-plan=${quoteArg(opts.fromPlan)}`];
+  if (opts.estate !== undefined) parts.push(`-estate=${quoteArg(opts.estate)}`);
+  return parts.join(" ");
+}
+
+/**
+ * Whether a failed `live-graph` run is a choudoufu that has no such command
+ * or flag (`"unsupported"`), or a real failure (`"failed"`). Older builds
+ * answer an unknown command two ways: the new CLI prints `OpenTofu has no
+ * command named "live-graph"` and exits 1 (cmd/choudoufu/command_main.go),
+ * and the older mitchellh/cli path prints its usage and exits 127. A build
+ * whose `live-graph` predates `-from-plan` fails the flag parse with `flag
+ * provided but not defined`.
+ */
+export function classifyLiveGraphFailure(code: unknown, output: string): "unsupported" | "failed" {
+  if (code === 127) return "unsupported";
+  if (/no command named "?live-graph"?/i.test(output)) return "unsupported";
+  if (/flag provided but not defined: -(?:from-plan|json|estate)\b/.test(output)) return "unsupported";
+  return "failed";
+}
+
 /** `live-ls -estate=<estate> -json [-consistent]`. */
 export function choudoufuLiveLsCommand(opts: { binary: string; estate: string; consistent?: boolean }): string {
   const parts = [opts.binary, "live-ls", `-estate=${quoteArg(opts.estate)}`, "-json"];
@@ -854,7 +968,7 @@ async function resolveRoot(args: TerraformRootArgs, signal?: AbortSignal): Promi
     );
   }
   const binary = terraformBinary(namespace);
-  const dir = resolve(projectRoot, root.dir);
+  const dir = resolve(projectRoot, args.dir ?? 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
@@ -917,8 +1031,8 @@ function report(stdout: string, stderr: string): void {
 // ── Activities ──────────────────────────────────────────────────────────────
 
 /**
- * `terraform init` in the named root, with the root's `backendConfig` supplied
- * as `-backend-config` flags. Uses the longInfra profile: init downloads
+ * `terraform init` in the named root, with the root's `backendConfigFiles` and
+ * `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(
@@ -929,19 +1043,55 @@ export async function terraformInit(
   const cmd = terraformInitCommand({
     binary,
     ...(root.backendConfig ? { backendConfig: root.backendConfig } : {}),
+    ...(root.backendConfigFiles ? { backendConfigFiles: root.backendConfigFiles } : {}),
     ...(args.upgrade ? { upgrade: true } : {}),
     ...(args.reconfigure ? { reconfigure: true } : {}),
   });
 
-  const { stdout, stderr } = await run(cmd, dir, terraformEnvironment(root), signal);
-  report(stdout, stderr);
+  // Known once the root resolves, before init runs (chant#4512), so a failed
+  // init still publishes them and the ledger names the root it was for.
+  const rootPath = workspaceRelativePath(dir);
+  const result: TerraformInitResult = { dir, ...(root.workspace ? { workspace: root.workspace } : {}), ...(rootPath !== undefined ? { rootPath } : {}) };
+
+  let out: { stdout: string; stderr: string };
+  try {
+    out = await run(cmd, dir, terraformEnvironment(root), signal);
+  } catch (err) {
+    throw withKnownOutputs(err, result);
+  }
+  report(out.stdout, out.stderr);
+  return result;
+}
 
-  return { dir, ...(root.workspace ? { workspace: root.workspace } : {}) };
+/**
+ * `err` carrying `outputs` as the outputs the activity knew when it failed
+ * (chant#4512): the `knownOutputs` property core's executor reads a failed
+ * step's outcome attributes from (core's `withKnownOutputs`). It is set here
+ * rather than imported so the lexicon needs no newer core; an older executor
+ * reads the error as any other failure.
+ */
+function withKnownOutputs(err: unknown, outputs: object): Error {
+  const e = err instanceof Error ? err : new Error(String(err));
+  return Object.assign(e, { knownOutputs: outputs });
+}
+
+/**
+ * `dir` relative to the chant workspace that holds it, `/`-separated, or
+ * undefined outside a workspace or outside its root (chant#4482). The
+ * workspace root `"."` stands for itself.
+ */
+export function workspaceRelativePath(dir: string): string | undefined {
+  const found = findWorkspaceRoot(dir);
+  if (!found) return undefined;
+  const rel = relative(found.dir, dir);
+  if (rel.startsWith("..")) return undefined;
+  return rel === "" ? "." : rel.split(sep).join("/");
 }
 
 /**
  * `terraform plan -detailed-exitcode -out=<planFile>` in the named root, then
- * `terraform show` over the written plan in both `-json` and `-no-color` form.
+ * `terraform show` over the written plan in both `-json` and `-no-color` form
+ * (`-json` alone with `text: false`).
  *
  * 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
@@ -956,9 +1106,13 @@ export async function terraformPlan(
   args: TerraformPlanArgs,
   signal?: AbortSignal,
 ): Promise<TerraformPlanResult> {
-  const { binary, root, dir } = await resolveRoot(args, signal);
+  const { binary, root, dir, live } = await resolveRoot(args, signal);
   const planFile = args.planFile ?? DEFAULT_PLAN_FILE;
   const env = terraformEnvironment(root);
+  const lock = args.lockTimeout !== undefined ? lockTimeoutArgs("plan", args.lockTimeout) : [];
+  // #4545: a cone only on a live root that is not an estate file; -target and -destroy plan in full.
+  const fixed = [...(args.destroy ? ["-destroy"] : []), ...((args.targets ?? []).length > 0 ? ["-target"] : [])];
+  const cone = args.cone !== undefined ? coneArgs(binary, args.cone, fixed, live && !existsSync(join(dir, "estate.chdf.hcl"))) : [];
   const cmd = terraformPlanCommand({
     binary,
     planFile,
@@ -966,12 +1120,15 @@ export async function terraformPlan(
     ...(args.vars ? { vars: args.vars } : {}),
     ...(args.destroy ? { destroy: true } : {}),
     ...(args.targets && args.targets.length > 0 ? { targets: args.targets } : {}),
+    ...(cone.length + lock.length > 0 ? { extra: [...cone, ...lock] } : {}),
   });
 
   let changed: boolean;
+  let output = "";
   try {
     const { stdout, stderr } = await run(cmd, dir, env, signal);
     report(stdout, stderr);
+    output = `${stdout}\n${stderr}`;
     changed = false;
   } catch (err) {
     // An abort or a spawn failure carries no numeric exit code. That is not
@@ -985,11 +1142,12 @@ export async function terraformPlan(
       );
     }
     report(failure.stdout ?? "", failure.stderr ?? "");
+    output = `${failure.stdout ?? ""}\n${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 text = args.text === false ? "" : (await run(terraformShowCommand({ binary, json: false, planFile }), dir, env, signal)).stdout;
   const json: unknown = JSON.parse(jsonRun.stdout);
 
   return {
@@ -997,7 +1155,7 @@ export async function terraformPlan(
     planFile,
     dir,
     json,
-    text: textRun.stdout,
+    text,
     planDigest: terraformPlanDigest(json),
     changeSet: terraformChangeSetPart({
       member: args.root,
@@ -1006,6 +1164,7 @@ export async function terraformPlan(
       ...((root.estate ?? root.workspace) ? { scope: root.estate ?? root.workspace } : {}),
     }),
     ...countPlanChanges(json),
+    ...(cone.length > 0 ? { cone: readPlanCone(output, join(dir, planFile), args.cone!) } : {}),
   };
 }
 
@@ -1057,7 +1216,8 @@ export async function terraformApply(
   }
 
   const planFile = args.planFile!;
-  const cmd = terraformApplyCommand({ binary, planFile });
+  const lock = args.lockTimeout !== undefined ? lockTimeoutArgs("apply", args.lockTimeout) : [];
+  const cmd = terraformApplyCommand({ binary, planFile, ...(lock.length > 0 ? { extra: lock } : {}) });
 
   try {
     const { stdout, stderr } = await run(cmd, dir, terraformEnvironment(root), signal);
@@ -1092,7 +1252,11 @@ export async function terraformOutputs(
   args: TerraformRootArgs,
   signal?: AbortSignal,
 ): Promise<Record<string, unknown>> {
-  const { binary, root, dir } = await resolveRoot(args, signal);
+  return outputsIn(await resolveRoot(args, signal), signal);
+}
+
+/** `<binary> output -json` in a resolved root, as `{ name: value }`. */
+async function outputsIn({ binary, root, dir }: ResolvedRoot, signal?: AbortSignal): Promise<Record<string, unknown>> {
   const { stdout } = await run(`${binary} output -json`, dir, terraformEnvironment(root), signal);
   const parsed = JSON.parse(stdout || "{}") as Record<string, { value?: unknown }>;
   return Object.fromEntries(Object.entries(parsed).map(([name, entry]) => [name, entry?.value]));
@@ -1174,7 +1338,7 @@ export async function choudoufuWaveRoot(
   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) {
+  if ((resolved.root.backendConfig && Object.keys(resolved.root.backendConfig).length > 0) || (resolved.root.backendConfigFiles?.length ?? 0) > 0) {
     return { wave: false, reason: "the root has backend config, which live-plan-set does not take" };
   }
   const root = choudoufuSetRootPath(resolved.projectRoot, resolved.dir);
@@ -1275,13 +1439,17 @@ export interface ChoudoufuPlanSetResult extends ChoudoufuPlanSet {
  * `live-wave-apply` hands back to choudoufu with the set digest.
  */
 export async function choudoufuPlanSet(args: TerraformRootArgs, signal?: AbortSignal): Promise<ChoudoufuPlanSetResult> {
-  const resolved = await resolveRoot(args, signal);
+  return planSetIn(await resolveRoot(args, signal), args.root, signal);
+}
+
+/** {@link choudoufuPlanSet} over a resolved root, `key` naming it in errors, in the waves directory and as the change-set member. */
+async function planSetIn(resolved: ResolvedRoot, key: string, signal?: AbortSignal): Promise<ChoudoufuPlanSetResult> {
   const { binary, root, dir, projectRoot } = resolved;
-  if (binary !== "choudoufu") throw new Error(`choudoufuPlanSet: root "${args.root}" runs ${binary}, not choudoufu`);
+  if (binary !== "choudoufu") throw new Error(`choudoufuPlanSet: root "${key}" 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);
+  if (rootPath === undefined) throw new Error(`choudoufuPlanSet: root "${key}" (${dir}) is not inside ${projectRoot}`);
+  const wavesDir = choudoufuWavesDir(projectRoot, key);
   mkdirSync(wavesDir, { recursive: true });
   const cmd = choudoufuPlanSetCommand({ binary, root: rootPath, outDir: fromProject(projectRoot, join(wavesDir, "out")) });
 
@@ -1299,12 +1467,64 @@ export async function choudoufuPlanSet(args: TerraformRootArgs, signal?: AbortSi
     stdout = failure.stdout ?? "";
   }
 
-  const parsed = parseChoudoufuPlanSet(stdout, { member: args.root, root: rootPath });
+  const parsed = parseChoudoufuPlanSet(stdout, { member: key, root: rootPath });
   const planSetFile = join(wavesDir, "plan-set.json");
   writeFileSync(planSetFile, stdout);
   return { ...parsed, planSetFile, root: rootPath };
 }
 
+// ── A choudoufu workspace member's outputs (#4455) ─────────────────────────
+
+/**
+ * A choudoufu member of the workspace, as `member-outputs` names it: not a
+ * `terraform.roots` entry of the reading project but a directory the
+ * workspace declaration gives. Its binary is `choudoufu`, it has no var
+ * files, workspace or backend config, and it runs from `projectRoot`, a
+ * directory above it (the workspace root), since `live-plan-set` plans only
+ * roots inside the directory it runs in.
+ */
+export interface ChoudoufuMemberArgs {
+  /** The member's name: the waves directory's name, and the plan's member in errors. */
+  member: string;
+  /** The member's directory, absolute. */
+  dir: string;
+  /** Where `live-plan-set` runs from, absolute: a directory above `dir`. */
+  projectRoot: string;
+}
+
+async function resolveMemberRoot(args: ChoudoufuMemberArgs, signal?: AbortSignal): Promise<ResolvedRoot> {
+  const binary = "choudoufu";
+  await ensureChoudoufuVersion(binary, signal);
+  const dir = resolve(args.dir);
+  const estate = detectLiveEstate(dir);
+  return { binary, root: { dir }, dir, ...(estate !== undefined ? { estate } : {}), live: estate !== undefined, projectRoot: resolve(args.projectRoot) };
+}
+
+/**
+ * The member's outputs as applied (#4455): `choudoufu init`, then `choudoufu
+ * output -json` in its directory, the read the `terraform-apply` capability's
+ * `outputs` makes for a root. A live estate's outputs come from its record
+ * store.
+ */
+export async function choudoufuMemberOutputs(args: ChoudoufuMemberArgs, signal?: AbortSignal): Promise<Record<string, unknown>> {
+  const resolved = await resolveMemberRoot(args, signal);
+  const { stdout, stderr } = await run(terraformInitCommand({ binary: resolved.binary }), resolved.dir, terraformEnvironment(resolved.root), signal);
+  report(stdout, stderr);
+  return outputsIn(resolved, signal);
+}
+
+/**
+ * The member planned as a one-root set (#4455), the way a choudoufu root in
+ * a gated wave is ({@link choudoufuPlanSet}): `live-plan-set -json` from
+ * `projectRoot`. The document's embedded plan carries `planned_values` and
+ * `output_changes`, which say what the member's outputs will be.
+ */
+export async function choudoufuMemberPlanSet(args: ChoudoufuMemberArgs, signal?: AbortSignal): Promise<ChoudoufuPlanSetResult> {
+  const resolved = await resolveMemberRoot(args, signal);
+  if (!resolved.live) throw new Error(`choudoufu member "${args.member}" (${resolved.dir}) declares no live estate, so live-plan-set cannot plan it`);
+  return planSetIn(resolved, args.member, signal);
+}
+
 /**
  * What a choudoufu root keeps in the fan-out's attempt record (#3459):
  * choudoufu's resume file, under the set digest it was written for.
@@ -1514,10 +1734,11 @@ export function terraformPlanReadCommand(opts: { binary: string; planFile: strin
  * The one line a person runs to initialise a root chant refuses to plan,
  * with the root's `backendConfig` carried, so it can be pasted as printed.
  */
-export function terraformInitLine(opts: { binary: string; dir: string; backendConfig?: Record<string, string> }): string {
+export function terraformInitLine(opts: { binary: string; dir: string; backendConfig?: Record<string, string>; backendConfigFiles?: readonly string[] }): string {
   const init = terraformInitCommand({
     binary: opts.binary,
     ...(opts.backendConfig ? { backendConfig: opts.backendConfig } : {}),
+    ...(opts.backendConfigFiles ? { backendConfigFiles: opts.backendConfigFiles } : {}),
   });
   return init.replace(`${opts.binary} init`, `${opts.binary} -chdir=${quoteArg(opts.dir)} init`);
 }
@@ -1629,7 +1850,12 @@ export async function terraformPlanRead(
 ): Promise<TerraformPlanReadResult> {
   const { binary, root, dir } = await resolveRoot(args, signal);
   const env = terraformEnvironment(root);
-  const initLine = terraformInitLine({ binary, dir, ...(root.backendConfig ? { backendConfig: root.backendConfig } : {}) });
+  const initLine = terraformInitLine({
+    binary,
+    dir,
+    ...(root.backendConfig ? { backendConfig: root.backendConfig } : {}),
+    ...(root.backendConfigFiles ? { backendConfigFiles: root.backendConfigFiles } : {}),
+  });
   const notInitialised = (detail: string): TerraformPlanReadError =>
     new TerraformPlanReadError(
       "not-initialised",
@@ -1912,6 +2138,65 @@ export async function choudoufuLivePlan(
   };
 }
 
+/** What {@link choudoufuLiveGraph} resolved. */
+export type ChoudoufuLiveGraphResult =
+  | {
+      /** choudoufu printed the engine graph document. */
+      supported: true;
+      /** The document, parsed: a GraphIR v1 with `meta.engineGraph` (chant#4527's schema). */
+      json: unknown;
+      /** Absolute path of the root module directory. */
+      dir: string;
+    }
+  | {
+      /** This choudoufu has no `live-graph -from-plan` (older than {@link MIN_CHOUDOUFU_GRAPH_VERSION}). */
+      supported: false;
+      /** choudoufu's own first line, for the note. */
+      detail: string;
+      dir: string;
+    };
+
+export interface ChoudoufuLiveGraphArgs extends TerraformRootArgs {
+  /** Absolute path of the `live-plan -json` document this graph takes its facts from. */
+  fromPlan: string;
+  /** The estate (`-estate`), for a root that does not declare its own. */
+  estate?: string;
+}
+
+/**
+ * `choudoufu live-graph -json -from-plan=<file>` (choudoufu#2285, read by
+ * chant#4528): the root's graph as one engine graph document, its facts taken
+ * from a `live-plan -json` document this process already read. No second live
+ * read: choudoufu builds the graph from the configuration and that file
+ * alone, starts no provider and calls no cloud, so facts and verdicts come
+ * from the same refresh (choudoufu #1014).
+ *
+ * A usage error ({@link classifyLiveGraphFailure}) resolves `supported:
+ * false` rather than throwing, since the caller degrades to no facts; any
+ * other failure throws with choudoufu's output. Warnings (an empty scope
+ * estate, a plan without `observed_at`) go to stderr and are echoed like
+ * every other activity's.
+ */
+export async function choudoufuLiveGraph(args: ChoudoufuLiveGraphArgs, signal?: AbortSignal): Promise<ChoudoufuLiveGraphResult> {
+  const resolved = await resolveRoot(args, signal);
+  const { binary, dir } = resolved;
+  const env = terraformEnvironment(resolved.root);
+  const estateFlag: { estate?: string } = resolved.estate === undefined && args.estate !== undefined ? { estate: args.estate } : {};
+  const cmd = choudoufuLiveGraphCommand({ binary, fromPlan: args.fromPlan, ...estateFlag });
+  try {
+    const { stdout, stderr } = await run(cmd, dir, env, signal);
+    if (stderr) console.error(stderr);
+    return { supported: true, json: JSON.parse(liveDocumentFrom(stdout)), dir };
+  } catch (err) {
+    const failure = err as ExecFailure;
+    if (typeof failure.code !== "number") throw err;
+    const output = `${failure.stderr ?? ""}\n${failure.stdout ?? ""}`;
+    const detail = output.trim().split("\n").find((line) => line.trim() !== "")?.trim() ?? `exit ${failure.code}`;
+    if (classifyLiveGraphFailure(failure.code, output) === "unsupported") return { supported: false, detail, dir };
+    throw new Error(`${binary} live-graph failed in ${dir} (exit ${failure.code})${detail ? `\n${output.trim()}` : ""}`);
+  }
+}
+
 /**
  * `choudoufu live-ls -estate=<estate> -json [-consistent]`: every resource
  * the account holds under the estate, read straight from the Resource Groups

package/src/op/activity-contracts.test.ts

@@ -23,6 +23,7 @@ const ACTIVITY_NAMES = [
   "choudoufuLiveLs",
   "choudoufuLiveCheck",
   "choudoufuAdopt",
+  "choudoufuPlanSet",
   "terraformPinRollout",
 ];
 

package/src/op/activity-contracts.ts

@@ -66,7 +66,8 @@ export const terraformInitContract = activityContract(
     upgrade: z.boolean().optional(),
     reconfigure: z.boolean().optional(),
   }),
-  z.object({ dir: z.string(), workspace: z.string().optional() }),
+  // `rootPath` (#4482) is what TerraformApplyOp's Init step publishes as `TerraformRootPath`; OPS012 checks it here.
+  z.object({ dir: z.string(), workspace: z.string().optional(), rootPath: z.string().optional() }),
   rootEntity,
 );
 
@@ -181,6 +182,28 @@ export const choudoufuAdoptContract = activityContract(
   rootEntity,
 );
 
+/**
+ * `choudoufuPlanSet` (#4483): one live choudoufu root planned as a one-root
+ * set. `changeSet` is the root's part, the field an Op hands to
+ * `composeChangeSet`; `planDigest` is what a gate binds; `planSetFile` and
+ * `setDigest` are what a later `live-wave-apply` takes.
+ */
+export const choudoufuPlanSetContract = activityContract(
+  "choudoufuPlanSet",
+  z.strictObject({ ...rootArgs }),
+  z.object({
+    setDigest: z.string(),
+    rootDigest: z.string(),
+    planDigest: z.string(),
+    changed: z.boolean(),
+    json: z.unknown(),
+    changeSet: z.object({ member: z.object({ member: z.string(), planDigest: z.string().nullable() }).passthrough(), entries: z.array(z.unknown()) }),
+    planSetFile: z.string(),
+    root: z.string(),
+  }),
+  rootEntity,
+);
+
 /** One root of a pin-bump rollout ({@link PinRoot} in `../pin/waves.ts`). */
 const pinRoot = z.strictObject({ root: z.string(), dependsOn: z.array(z.string()).optional(), tsSource: z.string().optional() });
 

package/src/op/builders.ts

@@ -31,6 +31,7 @@ import type {
   ChoudoufuLiveLsArgs,
   ChoudoufuLiveCheckArgs,
   ChoudoufuAdoptArgs,
+  TerraformRootArgs,
 } from "./activities/terraform";
 import type { TerraformPinRolloutArgs } from "./activities/pin-rollout";
 
@@ -186,6 +187,19 @@ export const terraformShow = (
   );
 };
 
+/**
+ * `choudoufuPlanSet` (#4483): `live-plan-set -json` over one live choudoufu
+ * root. Hand `step.out.changeSet` from each root's step to `composeChangeSet`
+ * to make one change-set document over several roots, such as one per cloud.
+ */
+export const choudoufuPlanSet = (
+  root: string,
+  opts?: WithStepRefs<Omit<TerraformRootArgs, "root">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("choudoufuPlanSet", { root, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+
 /**
  * One run of a pin-bump rollout (#3189). `opts` is
  * {@link TerraformPinRolloutArgs} itself. It names no root: the rollout finds