@intentius/chant-lexicon-terraform 0.124.52 → 0.124.54

package/dist/components/placeholder-preview.js

@@ -0,0 +1,254 @@
+/**
+ * Previewing a root whose `vars` read outputs not known yet (#4463).
+ *
+ * terraform takes no unknown variable, so such a root used to get no plan at
+ * pull-request time, only a hole. Now it is planned with a stand-in for each
+ * variable that holds no value yet, typed from the root's own `variable`
+ * block ({@link terraformPlaceholder}). Every attribute and output the
+ * stand-ins drive is then marked unknown after apply in the plan JSON
+ * ({@link markPlaceholderDriven}) before the change set, the shape and the
+ * planned outputs are read from it, so no stand-in value reaches the note or
+ * the digest. The member's change-set part lists the variables under
+ * `placeholders`.
+ *
+ * What a stand-in drives is read from the plan's own `configuration`: an
+ * attribute whose expression references `var.<name>`, through module inputs
+ * too, plus any string attribute or output whose planned value carries
+ * {@link TERRAFORM_UNKNOWN_MARK}. A value that reaches an attribute another
+ * way (a number through a `local`) is not marked; the fresh plan at apply
+ * then differs from the preview and asks for an approval of its own, which
+ * costs a round and never applies a change nobody approved.
+ *
+ * A preview is not possible when a variable that holds the unknown read is
+ * not declared, when the unknown sits inside a larger value, when a `count`
+ * or `for_each` reads a stand-in (the preview would show a count the real
+ * value does not have), or when the placeholder plan fails, say on a
+ * `validation` block. The member then stays a hole, as before, and the
+ * hole's reason says why (the 2026-10-25 ruling on #4463).
+ */
+/** The marker every string stand-in carries, so a reader can tell it from a real value. */
+export const TERRAFORM_UNKNOWN_MARK = "known-after-apply";
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+/** Split `text` on `sep` where no bracket is open. */
+function splitTop(text, sep) {
+    const out = [];
+    let depth = 0;
+    let quoted = false;
+    let start = 0;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (c === '"' && text[i - 1] !== "\\")
+            quoted = !quoted;
+        if (quoted)
+            continue;
+        if (c === "(" || c === "[" || c === "{")
+            depth++;
+        else if (c === ")" || c === "]" || c === "}")
+            depth--;
+        else if (depth === 0 && (typeof sep === "string" ? c === sep : sep.test(c))) {
+            out.push(text.slice(start, i));
+            start = i + 1;
+        }
+    }
+    out.push(text.slice(start));
+    return out.map((s) => s.trim()).filter((s) => s !== "");
+}
+/** `name(inner)` read off a type expression, or `undefined` when it is not one. */
+function call(type, name) {
+    const m = type.match(new RegExp(`^${name}\\s*\\(([\\s\\S]*)\\)$`));
+    return m ? m[1].trim() : undefined;
+}
+/**
+ * A stand-in for a variable of `type`, a Terraform type expression as the
+ * `variable` block writes it (`string`, `list(string)`, `object({ id = string })`).
+ *
+ * - `string`, `any` or no type: {@link TERRAFORM_UNKNOWN_MARK}.
+ * - `number`: 0. `bool`: false.
+ * - `list(...)`, `set(...)`: an empty list. `map(...)`: an empty map.
+ * - `tuple([a, b])`: one stand-in per element type.
+ * - `object({ a = t })`: one stand-in per attribute, `optional(t)` read as `t`.
+ *
+ * An empty collection plans no element, so a resource that iterates one
+ * plans none; the fresh plan at apply then asks for its own approval.
+ */
+export function terraformPlaceholder(type) {
+    const t = (type ?? "").trim().replace(/^\$\{([\s\S]*)\}$/, "$1").trim();
+    if (t === "" || t === "any" || t === "string")
+        return TERRAFORM_UNKNOWN_MARK;
+    if (t === "number")
+        return 0;
+    if (t === "bool")
+        return false;
+    const optional = call(t, "optional");
+    if (optional !== undefined)
+        return terraformPlaceholder(splitTop(optional, ",")[0]);
+    if (call(t, "list") !== undefined || call(t, "set") !== undefined)
+        return [];
+    if (call(t, "map") !== undefined)
+        return {};
+    const tuple = call(t, "tuple");
+    if (tuple !== undefined) {
+        const inner = tuple.replace(/^\[([\s\S]*)\]$/, "$1");
+        return splitTop(inner, ",").map((e) => terraformPlaceholder(e));
+    }
+    const object = call(t, "object");
+    if (object !== undefined) {
+        const inner = object.replace(/^\{([\s\S]*)\}$/, "$1");
+        const out = {};
+        for (const attr of splitTop(inner, /[,\n]/)) {
+            const at = attr.indexOf("=");
+            if (at < 0)
+                continue;
+            const name = attr.slice(0, at).trim().replace(/^"(.*)"$/, "$1");
+            out[name] = terraformPlaceholder(attr.slice(at + 1));
+        }
+        return out;
+    }
+    return TERRAFORM_UNKNOWN_MARK;
+}
+const containsUndefined = (v) => v === undefined || (Array.isArray(v) ? v.some(containsUndefined) : isObject(v) ? Object.values(v).some(containsUndefined) : false);
+/**
+ * The stand-ins for a step's `vars` (#4463): each variable whose value is
+ * `undefined` (a `stackOutput()` read with nothing to read yet) gets
+ * {@link terraformPlaceholder} of its declared type. Returns why instead when
+ * no preview can be made: no variable holds the unknown read, one that does
+ * is not declared in the root, or the unknown sits inside a larger value.
+ */
+export function placeholderVars(vars, declared) {
+    const given = vars ?? {};
+    const placeholders = [];
+    const out = {};
+    for (const [name, value] of Object.entries(given)) {
+        if (value === undefined) {
+            const decl = declared.get(name);
+            if (!decl)
+                return `var.${name} holds the unknown read and the root declares no variable "${name}" to type a stand-in from`;
+            placeholders.push(name);
+            out[name] = terraformPlaceholder(decl.type);
+        }
+        else if (containsUndefined(value)) {
+            return `the unknown read sits inside var.${name}, which a stand-in cannot fill in part`;
+        }
+        else
+            out[name] = value;
+    }
+    if (placeholders.length === 0)
+        return "no variable of the step holds the unknown read";
+    return { placeholders: placeholders.sort(), vars: out };
+}
+/** Every `references` entry under an expression, at any depth (nested blocks are arrays of expression objects). */
+function referencesIn(expr, out = []) {
+    if (Array.isArray(expr))
+        for (const e of expr)
+            referencesIn(e, out);
+    else if (isObject(expr)) {
+        if (Array.isArray(expr.references))
+            for (const r of expr.references)
+                if (typeof r === "string")
+                    out.push(r);
+        for (const [k, v] of Object.entries(expr))
+            if (k !== "references" && k !== "constant_value")
+                referencesIn(v, out);
+    }
+    return out;
+}
+const readsVar = (expr, vars) => referencesIn(expr).some((r) => {
+    const m = r.match(/^var\.([^.[]+)/);
+    return m !== null && vars.has(m[1]);
+});
+const resourceKey = (modulePath, mode, type, name) => `${modulePath}|${mode === "data" ? "data." : ""}${type}.${name}`;
+function walkModule(mod, path, vars, driven) {
+    if (!isObject(mod) || vars.size === 0)
+        return;
+    const at = (address) => (path ? `${path}.${address}` : address);
+    for (const r of Array.isArray(mod.resources) ? mod.resources : []) {
+        if (!isObject(r))
+            continue;
+        const mode = String(r.mode ?? "managed");
+        const address = String(r.address ?? `${r.type}.${r.name}`);
+        if (readsVar(r.count_expression, vars) || readsVar(r.for_each_expression, vars))
+            driven.expansions.push(at(address));
+        const exprs = isObject(r.expressions) ? r.expressions : {};
+        const attrs = new Set(Object.entries(exprs).filter(([, e]) => readsVar(e, vars)).map(([k]) => k));
+        if (attrs.size > 0)
+            driven.attributes.set(resourceKey(path, mode, String(r.type), String(r.name)), attrs);
+    }
+    for (const [name, c] of Object.entries(isObject(mod.module_calls) ? mod.module_calls : {})) {
+        if (!isObject(c))
+            continue;
+        if (readsVar(c.count_expression, vars) || readsVar(c.for_each_expression, vars))
+            driven.expansions.push(at(`module.${name}`));
+        const exprs = isObject(c.expressions) ? c.expressions : {};
+        const inputs = new Set(Object.entries(exprs).filter(([, e]) => readsVar(e, vars)).map(([k]) => k));
+        walkModule(c.module, at(`module.${name}`), inputs, driven);
+    }
+    if (path === "") {
+        for (const [name, o] of Object.entries(isObject(mod.outputs) ? mod.outputs : {})) {
+            if (isObject(o) && readsVar(o.expression, vars))
+                driven.outputs.add(name);
+        }
+    }
+}
+const carriesMark = (v) => typeof v === "string" ? v.includes(TERRAFORM_UNKNOWN_MARK) : Array.isArray(v) ? v.some(carriesMark) : isObject(v) ? Object.values(v).some(carriesMark) : false;
+/** A `resource_changes` item's key in {@link Driven.attributes}: its module path without instance keys. */
+function changeKey(rc) {
+    const modulePath = typeof rc.module_address === "string" ? rc.module_address.replace(/\[[^\]]*\]/g, "") : "";
+    return resourceKey(modulePath, String(rc.mode ?? "managed"), String(rc.type), String(rc.name));
+}
+/**
+ * `planJson` (`show -json` of the placeholder plan) with every attribute and
+ * root output the stand-ins for `placeholders` drive marked unknown after
+ * apply, their planned values dropped. Returns why instead when a `count` or
+ * `for_each` reads a stand-in. The input is not changed.
+ */
+export function markPlaceholderDriven(planJson, placeholders) {
+    const plan = structuredClone(isObject(planJson) ? planJson : {});
+    const driven = { attributes: new Map(), outputs: new Set(), expansions: [] };
+    const config = isObject(plan.configuration) ? plan.configuration : {};
+    walkModule(config.root_module, "", new Set(placeholders), driven);
+    if (driven.expansions.length > 0) {
+        return { refused: `the count or for_each of ${[...new Set(driven.expansions)].sort().join(", ")} reads a stand-in, so the preview cannot say how many instances there are` };
+    }
+    for (const r of Array.isArray(plan.resource_changes) ? plan.resource_changes : []) {
+        if (!isObject(r) || !isObject(r.change))
+            continue;
+        const change = r.change;
+        const after = isObject(change.after) ? change.after : undefined;
+        const attrs = new Set(driven.attributes.get(changeKey(r)) ?? []);
+        for (const [k, v] of Object.entries(after ?? {}))
+            if (carriesMark(v))
+                attrs.add(k);
+        if (attrs.size === 0)
+            continue;
+        const afterUnknown = isObject(change.after_unknown) ? change.after_unknown : {};
+        for (const k of attrs) {
+            afterUnknown[k] = true;
+            if (after)
+                delete after[k];
+        }
+        change.after_unknown = afterUnknown;
+    }
+    const outputChanges = isObject(plan.output_changes) ? plan.output_changes : {};
+    const plannedOutputs = isObject(plan.planned_values) && isObject(plan.planned_values.outputs) ? plan.planned_values.outputs : {};
+    for (const [name, o] of Object.entries(outputChanges))
+        if (isObject(o) && carriesMark(o.after))
+            driven.outputs.add(name);
+    for (const [name, o] of Object.entries(plannedOutputs))
+        if (isObject(o) && carriesMark(o.value))
+            driven.outputs.add(name);
+    for (const name of driven.outputs) {
+        const o = isObject(outputChanges[name]) ? outputChanges[name] : (outputChanges[name] = {});
+        delete o.after;
+        o.after_unknown = true;
+        delete plannedOutputs[name];
+    }
+    return { plan };
+}
+/** The hole a root keeps when its preview is not possible: the old reason, and why there is no preview. */
+export function waitingHole(root, unresolved, why) {
+    return {
+        address: root,
+        type: "terraform_root",
+        reason: `inputs from ${unresolved.join(", ")}; planned again once they apply${why ? `; no preview: ${why}` : ""}`,
+    };
+}

package/dist/compose/apply-events.d.ts

@@ -0,0 +1,46 @@
+/**
+ * How each member's part of a composed apply ended (chant#4442, epic #4419),
+ * read from the binary's `apply -json` lines: `applied`, `partial`,
+ * `failed`, `not-started` or `no-changes`, core's `GroupMemberStatus`
+ * (ws-107).
+ *
+ * Lifted from terragucci's `packages/terragucci/src/compose.ts` at c493e0e
+ * (`readApplyEvents`, `memberApply`).
+ */
+import type { GroupMemberStatus } from "@intentius/chant/components/capability";
+import type { Composition } from "../compose.js";
+/** How one member's part of the apply ended. */
+export type MemberApply = GroupMemberStatus;
+/** What `apply -json` said of each module: the changes that completed, started, or errored, and the first error. */
+export interface ApplyEvents {
+    done: Map<string, number>;
+    started: Map<string, number>;
+    errored: Map<string, string>;
+    /** Errors no module's resource names. */
+    other: string[];
+}
+/** Read `apply -json` lines into each module's progress. A line that is not JSON is skipped. */
+export declare function readApplyEvents(out: string, modules: readonly string[]): ApplyEvents;
+/** How a member's part of the apply ended, from its planned changes and the events. */
+export declare function memberApply(m: string, planned: number, ev: ApplyEvents): {
+    apply: MemberApply;
+    done: number;
+};
+/** One member's outcome of a composed apply. */
+export interface MemberApplyOutcome {
+    status: MemberApply;
+    /** Its planned changes that completed. */
+    done: number;
+    /** The first error its part named. */
+    error?: string;
+}
+/**
+ * Every member's outcome of a composed apply, by component, from the
+ * `apply -json` output and each member's planned changes
+ * (`PlanCounts.changes` of its slice).
+ */
+export declare function composedApplyOutcomes(c: Pick<Composition, "order" | "modules">, planned: ReadonlyMap<string, number>, out: string): {
+    members: Record<string, MemberApplyOutcome>;
+    other: string[];
+};
+//# sourceMappingURL=apply-events.d.ts.map

package/dist/compose/apply-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-events.d.ts","sourceRoot":"","sources":["../../src/compose/apply-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAChF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C,gDAAgD;AAChD,MAAM,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAE5C,oHAAoH;AACpH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,yCAAyC;IACzC,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AASD,gGAAgG;AAChG,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,WAAW,CA6BpF;AAED,uFAAuF;AACvF,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,GAAG;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAO7G;AAED,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,WAAW,CAAC;IACpB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,SAAS,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAUpM"}

package/dist/compose/apply-events.js

@@ -0,0 +1,77 @@
+/**
+ * How each member's part of a composed apply ended (chant#4442, epic #4419),
+ * read from the binary's `apply -json` lines: `applied`, `partial`,
+ * `failed`, `not-started` or `no-changes`, core's `GroupMemberStatus`
+ * (ws-107).
+ *
+ * Lifted from terragucci's `packages/terragucci/src/compose.ts` at c493e0e
+ * (`readApplyEvents`, `memberApply`).
+ */
+import { stripModule, topModule } from "./module-address.js";
+/** Read `apply -json` lines into each module's progress. A line that is not JSON is skipped. */
+export function readApplyEvents(out, modules) {
+    const ev = { done: new Map(), started: new Map(), errored: new Map(), other: [] };
+    const known = new Set(modules);
+    const moduleOf = (addr) => {
+        const m = addr !== undefined ? topModule(addr) : undefined;
+        return m !== undefined && known.has(m) && addr !== `module.${m}` ? m : undefined;
+    };
+    const bump = (map, m) => map.set(m, (map.get(m) ?? 0) + 1);
+    for (const line of out.split("\n")) {
+        if (!line.startsWith("{"))
+            continue;
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const addr = e.hook?.resource?.addr;
+        const m = moduleOf(addr);
+        if (e.type === "apply_start" && m)
+            bump(ev.started, m);
+        else if (e.type === "apply_complete" && m)
+            bump(ev.done, m);
+        else if (e.type === "apply_errored" && m && !ev.errored.has(m))
+            ev.errored.set(m, `${stripModule(addr)}: ${e.hook?.error ?? e["@message"] ?? "errored"}`);
+        else if (e.type === "diagnostic" && e.diagnostic?.severity === "error") {
+            const dm = moduleOf(e.diagnostic.address);
+            const text = `${e.diagnostic.summary ?? "Error"}${e.diagnostic.detail ? `: ${e.diagnostic.detail.split("\n")[0]}` : ""}`;
+            if (dm && !ev.errored.has(dm))
+                ev.errored.set(dm, `${stripModule(e.diagnostic.address)}: Error: ${text}`);
+            else if (!dm)
+                ev.other.push(text);
+        }
+    }
+    return ev;
+}
+/** How a member's part of the apply ended, from its planned changes and the events. */
+export function memberApply(m, planned, ev) {
+    const done = Math.min(ev.done.get(m) ?? 0, planned);
+    if (planned === 0)
+        return { apply: "no-changes", done: 0 };
+    if (done >= planned)
+        return { apply: "applied", done };
+    if (done > 0)
+        return { apply: "partial", done };
+    if (ev.errored.has(m) || (ev.started.get(m) ?? 0) > 0)
+        return { apply: "failed", done };
+    return { apply: "not-started", done };
+}
+/**
+ * Every member's outcome of a composed apply, by component, from the
+ * `apply -json` output and each member's planned changes
+ * (`PlanCounts.changes` of its slice).
+ */
+export function composedApplyOutcomes(c, planned, out) {
+    const ev = readApplyEvents(out, c.order.map((member) => c.modules.get(member)));
+    const members = {};
+    for (const member of c.order) {
+        const m = c.modules.get(member);
+        const { apply, done } = memberApply(m, planned.get(member) ?? 0, ev);
+        const error = ev.errored.get(m);
+        members[member] = { status: apply, done, ...(error && apply !== "applied" ? { error } : {}) };
+    }
+    return { members, other: ev.other };
+}

package/dist/compose/estate.d.ts

@@ -0,0 +1,194 @@
+/**
+ * The composed run of choudoufu estates (chant#4445, epic #4419): when every
+ * member runs choudoufu against a `live` estate (`Composition.estate`), one
+ * `choudoufu plan` and one `choudoufu apply` from a composed root of `module`
+ * calls (choudoufu#2059).
+ *
+ * An estate has no state file, so nothing is pulled, locked, split or
+ * written back: each resource's record goes to its own estate as it applies,
+ * and a `terraform_estate_outputs` read of another estate in the run is
+ * answered inside the run. The composed root is `writeEstateRoot`'s
+ * (./root.ts, #4441). The run takes the job's environment and assumes no
+ * role of its own: each estate's provider blocks name its role.
+ *
+ * choudoufu refuses a bare `show` under a `live` block, so the values the
+ * plan left unknown are read after the apply from a second plan of the
+ * composed root: its `prior_state`, sliced per module (./slice.ts, #4442) and
+ * read through `../applied-state`, the reader `chant terraform report` uses.
+ * The same plan says how far a failed apply got: a member whose part plans
+ * no change any more applied.
+ *
+ * Lifted from terragucci's `packages/terragucci/src/compose.ts` at c493e0e
+ * (`ComposedRun` with `estate` set: `plan`, `apply`, `finishEstate`,
+ * `showEstateMembers`, `composedEnv`). The state-backed run is #4444; this one
+ * has the same `plan()`, `apply()` and `release()` and returns the same
+ * shapes, and #4447 picks one by `Composition.estate`.
+ */
+import type { CapabilityGroupOutcome, CapabilityGroupPlan, GroupMemberOutcome } from "@intentius/chant/components/capability";
+import type { ComposeFallback, Composition } from "../compose.js";
+import type { TerraformConfig } from "../config.js";
+import { type StateResourceValues } from "../applied-state.js";
+import { type BinaryExec } from "../state/exec.js";
+import { type ApplyEvents, type MemberApply } from "./apply-events.js";
+import { type ComposedMemberPlan, type PlanCounts } from "./slice.js";
+/** What a composed run's `plan()` answers. Assignable to core's `CapabilityGroupPlan` (ws-107). */
+export interface ComposedRunPlan extends CapabilityGroupPlan {
+    /** Each member's part of the plan, by component. Empty when the run fell back or the plan failed. */
+    members: Record<string, ComposedMemberPlan>;
+    /** What the approval binds beside the members' own plans: the composed plan and the generated files. Empty when nothing planned. */
+    digest: string;
+    /** Why the run did not plan as one: the members plan wave by wave instead. Decided before anything planned. */
+    fallback?: ComposeFallback;
+    /** Why the composed plan failed: every member is plan-failed. */
+    error?: string;
+    /** The member {@link error} is about, when it is about one (a hook, an init, a lock). */
+    member?: string;
+    /** The composed plan's `show -json`. */
+    plan?: unknown;
+    /** The saved plan file `apply()` applies. */
+    planFile: string;
+    /** The composed plan's `show` text. */
+    text: string;
+    /** Each member's part of the `show` text, by component. */
+    texts: Record<string, string>;
+    /** sha256 of each generated file of the composed root, as `ComposedRoot.generated`. */
+    generated: [string, string][];
+    /** The whole run's counts. */
+    counts: PlanCounts;
+    /** The binary's `Plan:` line for the whole run. */
+    summary: string;
+}
+/** One member's outcome of a composed apply. Assignable to core's `GroupMemberOutcome` (ws-107). */
+export interface ComposedMemberOutcome extends GroupMemberOutcome {
+    status: MemberApply;
+    /** Its planned changes. */
+    planned: number;
+    /** Its planned changes that completed. */
+    done: number;
+    /** Each resource of its part of the state after the apply, by address with its module taken off. */
+    resources?: Map<string, StateResourceValues>;
+}
+/** What a composed run's `apply()` answers. Assignable to core's `CapabilityGroupOutcome` (ws-107). */
+export interface ComposedRunApply extends CapabilityGroupOutcome {
+    /** Every member applied or had no changes, and the binary exited 0. */
+    ok: boolean;
+    members: Record<string, ComposedMemberOutcome>;
+    /** `show -json` of the plan made after the apply. Absent when it could not be made. */
+    after?: unknown;
+}
+/** The surface #4447 drives, whichever run `Composition.estate` picks. */
+export interface ComposedRunner {
+    plan(): Promise<ComposedRunPlan>;
+    apply(): Promise<ComposedRunApply>;
+    release(): Promise<void>;
+}
+export interface EstateRunOptions {
+    /** The checkout's root: where `chant.config.*` was loaded from. `.chant-compose/` is written here. */
+    projectRoot: string;
+    /** What `compositionFor` answered, with `estate` set and two or more members. */
+    composition: Composition;
+    /** The config's `terraform` namespace: a root's `estate`. */
+    terraform: TerraformConfig;
+    /** The job's environment. The run adds no role to it. */
+    env: NodeJS.ProcessEnv;
+    /** The choudoufu binary, by name or path. Default `terraform.binary`, else `choudoufu`. */
+    binary?: string;
+    /** Where the plan files go. Default: a new directory under the system's temp directory. */
+    work?: string;
+    /** How the binary runs. Default {@link runBinary}; a test injects a fake. */
+    exec?: BinaryExec;
+    log?: (line: string) => void;
+}
+/**
+ * Why a choudoufu's `version` output cannot run a composed run of estates, or
+ * undefined when it can. A release older than
+ * {@link MIN_CHOUDOUFU_ESTATES_VERSION} falls back; a dev build names no
+ * release and passes.
+ */
+export declare function estateVersionFallback(versionOutput: string): ComposeFallback | undefined;
+/**
+ * What choudoufu's human `apply` output says of each module: the changes
+ * that completed (`<addr>: Creation complete`, `Modifications complete`,
+ * `Destruction complete`), started (`Creating...` and the rest) or errored
+ * (an `Error:` box naming `with <addr>,`). An estate's apply runs under live
+ * resource markers and prints no `-json` lines, so this reads the text.
+ */
+export declare function readEstateApplyText(out: string, modules: readonly string[]): ApplyEvents;
+/**
+ * Each member's outcome from its planned changes, what the apply printed, its
+ * exit code and, when the post-apply plan was made, the changes each member's
+ * part still plans. A clean exit means every planned change applied. After a
+ * failure, a member's changes left in the post-apply plan say how many of its
+ * planned changes applied; without that plan the printed completions do.
+ */
+export declare function estateOutcomes(c: Pick<Composition, "order" | "modules">, planned: ReadonlyMap<string, number>, out: string, code: number, remaining?: ReadonlyMap<string, number>): {
+    members: Record<string, {
+        status: MemberApply;
+        done: number;
+        planned: number;
+        error?: string;
+    }>;
+    other: string[];
+};
+/**
+ * One composed run of estates: `plan()`, then `apply()` once the approval is
+ * given, then `release()` whatever happened. No call reads, locks or writes
+ * a state.
+ */
+export declare class EstateRun implements ComposedRunner {
+    private readonly o;
+    private readonly exec;
+    private readonly binary;
+    private readonly composeDir;
+    private readonly work;
+    private readonly madeWork;
+    private planned?;
+    private root?;
+    constructor(o: EstateRunOptions);
+    private get c();
+    private log;
+    /**
+     * The composed root's environment: the job's, with no role added (each
+     * estate's provider blocks name its role) and its `-var-file` flags taken
+     * out. With a shared provider cache and no lock file to check a cached
+     * provider against, the cache may fill the lock file.
+     */
+    private env;
+    /** The estate each member's records go to: its root's `estate`, else its `live` block's. */
+    private estateOf;
+    private notPlanned;
+    /**
+     * Why this choudoufu cannot run the composition, or undefined. Runs
+     * `choudoufu version`; what #4447's `groupFallback` asks before planning.
+     */
+    fallback(): Promise<ComposeFallback | undefined>;
+    private writeRoot;
+    private restoreRoot;
+    /**
+     * Check the binary's version, write the composed root, init it and plan
+     * once, then cut the plan into each member's part. The composed root is
+     * taken away again before this returns.
+     */
+    plan(): Promise<ComposedRunPlan>;
+    /**
+     * Apply the saved plan from the composed root, then plan again and read
+     * each member's values from that plan's `prior_state`. A failed apply
+     * leaves what applied applied, and each member's outcome says how far its
+     * part got.
+     */
+    apply(): Promise<ComposedRunApply>;
+    /**
+     * `show -json` of a plan of the composed root made after the apply, whose
+     * `prior_state` choudoufu builds from the records and the live system.
+     * Undefined when it cannot be made: the values unknown at plan then stay
+     * unknown. Never fails the run.
+     */
+    private planAfter;
+    /**
+     * Take the composed root away if a call left it, with the binary's working
+     * files under `.chant-compose/`, and the plan files. There is no lock to
+     * let go of. Safe to call more than once.
+     */
+    release(): Promise<void>;
+}
+//# sourceMappingURL=estate.d.ts.map

package/dist/compose/estate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"estate.d.ts","sourceRoot":"","sources":["../../src/compose/estate.ts"],"names":[],"mappings":"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"}