@intentius/chant-lexicon-terraform 0.124.51 → 0.124.54

package/dist/components/compose-group.d.ts

@@ -0,0 +1,145 @@
+/**
+ * `terraform-apply`'s group methods (chant#4447, ws-107): core forms a group
+ * of `terraform-apply` components that read each other, and these plan it
+ * as one plan and apply it as one apply of a composed root, so a value one
+ * root creates reaches its readers inside that apply.
+ *
+ * - `groupReads` reports to core each member's `terraform_remote_state` and
+ *   `terraform_estate_outputs` reads of another, as the composition finds
+ *   them, so roots wired in HCL alone form a group. Nothing while
+ *   `terraform.compose.enabled` is unset.
+ * - `groupFallback` answers `off` while `terraform.compose.enabled` is unset,
+ *   else builds the {@link Composition} (#4438) from the files, the config
+ *   and each member's cloud identity, and answers its fallback, if any. A
+ *   member the composition leaves out is dropped with its own kind and
+ *   reason, and core forms the group again from the rest (#4419 ruling 1).
+ *   A composition of estates also asks `choudoufu version` (#4445).
+ *   Nothing plans.
+ * - `planGroup` builds the composition again, plans it once with
+ *   `ComposedRun` (#4444) or, for estates, `EstateRun` (#4445), and answers
+ *   each member's part (#4442): its change-set part, planned outputs and
+ *   shape, with its own plan's digest. The group's digest is the composed
+ *   plan's with the generated files. The run is released before it returns,
+ *   with no lock taken, so a plan that core then refuses or makes wait
+ *   leaves no lock held and no file changed.
+ * - `runGroup` plans once more, this time under each state's lock, and
+ *   applies only when that plan's digest is the one `planGroup` answered;
+ *   otherwise it throws a moved plan and nothing applies. Whatever happens,
+ *   it releases the run. Each member's outputs come from the run: its part
+ *   of the working state's `show -json` for roots with state, the post-apply
+ *   plan's `prior_state` for estates.
+ *
+ * Each member's identity is `ci.identity.cloud` resolved for its root as
+ * the target (`resolveTargetCloudIdentity`, #4332), by the root's key or its
+ * directory, whichever a rule's target glob matches, compared by
+ * `identityKey`, so members that apply under different identities do not
+ * compose (#4438's `identity`).
+ */
+import type { CapabilityGroupOutcome, CapabilityGroupPlan, GroupContext, GroupFallback, GroupMember, GroupRun, ReportedGroupRead } from "@intentius/chant/components/capability";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { type TargetCloudIdentityLookup } from "@intentius/chant/workspace/ci-cloud-identity";
+import { type Composition } from "../compose.js";
+import type { TerraformConfig } from "../config.js";
+import { type BinaryExec } from "../state/exec.js";
+import { type ComposedRunner } from "../compose/estate.js";
+/** The step input as the group methods read it; `TerraformApplyStepInput` in ./capability-plugin.ts. */
+interface StepInput {
+    root: string;
+    vars?: Record<string, unknown>;
+    cwd?: string;
+}
+/** The project a group's roots belong to. */
+export interface ComposeProject {
+    /** Where `chant.config.*` was found: roots resolve against it and `.chant-compose/` is written there. */
+    projectRoot: string;
+    terraform: TerraformConfig;
+}
+/** What a runner is built from. */
+export interface GroupRunnerOptions extends ComposeProject {
+    composition: Composition;
+    /** Take each state's lock: `runGroup` does, `planGroup` does not. */
+    lock: boolean;
+    /** Each member's step `vars` as written, by component. */
+    vars: Record<string, Record<string, unknown> | undefined>;
+    /** The outputs of components outside the group that a member's `vars` read. */
+    componentOutputs: Record<string, Record<string, unknown>>;
+    env: NodeJS.ProcessEnv;
+    /** A directory of the run's own, removed after the run is released. */
+    work: string;
+}
+/** What the group methods use, each replaceable in a test. */
+export interface ComposeGroupDeps {
+    /** The project's config. Default: `loadChantConfigUpward` from the current directory. */
+    project?: () => Promise<ComposeProject>;
+    /** The run for a composition. Default: `EstateRun` when `estate` is set, else `ComposedRun`. */
+    runner?: (o: GroupRunnerOptions) => ComposedRunner;
+    /**
+     * Each target's cloud identity for `env` (`resolveTargetCloudIdentity`,
+     * #4332), or undefined when there is no workspace to read. Default:
+     * `declaredTargetCloudIdentity` from the project root.
+     */
+    identity?: (projectRoot: string, env: string) => Promise<TargetCloudIdentityLookup | undefined>;
+    /** How `choudoufu version` runs. Default `runBinary`. */
+    exec?: BinaryExec;
+    /** A root's outputs as its state holds them, for a member whose part of the working state could not be shown. Default `terraformOutputs`. */
+    outputs?: (root: string) => Promise<Record<string, unknown>>;
+    env?: NodeJS.ProcessEnv;
+    log?: (line: string) => void;
+}
+/** The group methods `terraform-apply` declares. */
+export interface ComposeGroupMethods {
+    groupReads(ctx: GroupContext, members: readonly GroupMember<StepInput>[]): Promise<ReportedGroupRead[]>;
+    groupFallback(ctx: GroupContext, members: readonly GroupMember<StepInput>[]): Promise<GroupFallback | undefined>;
+    planGroup(ctx: GroupContext, members: readonly GroupMember<StepInput>[]): Promise<CapabilityGroupPlan>;
+    runGroup(ctx: GroupContext, run: GroupRun, members: readonly GroupMember<StepInput>[]): Promise<CapabilityGroupOutcome>;
+}
+/** The members as components, each deploying its one step, for `compositionIfEnabled`. */
+export declare function memberComponents(members: readonly GroupMember<StepInput>[]): DriverComponent[];
+/**
+ * Each member's identity as `compositionFor` compares it: `identityKey` of
+ * `lookup` for the member's root, which a rule's target globs match by the
+ * root's key in `terraform.roots` or by its directory relative to the
+ * project (the first declared rule that either matches wins). Undefined
+ * without a lookup, so no member falls back as `identity`.
+ */
+export declare function memberIdentity(project: ComposeProject, members: readonly GroupMember<StepInput>[], lookup: TargetCloudIdentityLookup | undefined): ((member: string) => string | undefined) | undefined;
+/**
+ * The composition of exactly the group's members (core has already formed the
+ * group), or undefined when `terraform.compose` is not enabled.
+ */
+export declare function groupComposition(project: ComposeProject, members: readonly GroupMember<StepInput>[], env: NodeJS.ProcessEnv, identity?: (member: string) => string | undefined): Composition | undefined;
+/**
+ * The members' HCL reads of each other (#4447): each `terraform_remote_state`
+ * block whose state is another member's backend, and each
+ * `terraform_estate_outputs` block naming another member's estate, as the
+ * composition finds them. Each output the reader's code takes off the block
+ * is one read, `<upstream>.<output>` as a `stackOutput()` read is named; a
+ * block whose outputs the code does not name one by one is one read with
+ * the block's address as `ref`. Core cannot see these in the step's `vars`.
+ */
+export declare function hclGroupReads(project: ComposeProject, members: readonly GroupMember<StepInput>[]): ReportedGroupRead[];
+/**
+ * What core is told of the group (#4419 ruling 1): the whole change's
+ * fallback when it is not `one-root`; else each member the composition left
+ * out as a drop with its own kind and reason, so core groups the rest
+ * again without them; else `one-root`. Undefined when every member
+ * composes.
+ */
+export declare function groupFallbackOf(c: Composition, members: readonly string[]): GroupFallback | undefined;
+/**
+ * The outputs of components outside the group that the members' `vars`
+ * read, recovered from each member's input, which core resolved against
+ * them: `writeComposedRoot` turns those reads into literals.
+ */
+export declare function outsideOutputs(members: readonly GroupMember<StepInput>[]): Record<string, Record<string, unknown>>;
+/** A composed plan that no longer matches the one approved. Core's moved-plan mark, so nothing applies and the command exits 3. */
+export declare class ComposedPlanMovedError extends Error {
+    readonly planMoved = true;
+    constructor(message: string);
+}
+/** The group methods, with `deps` in place of the defaults. */
+export declare function composeGroup(deps?: ComposeGroupDeps): ComposeGroupMethods;
+/** The group methods `terraform-apply` uses. */
+export declare const terraformComposeGroup: ComposeGroupMethods;
+export {};
+//# sourceMappingURL=compose-group.d.ts.map

package/dist/components/compose-group.d.ts.map

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

package/dist/components/compose-group.js

@@ -0,0 +1,407 @@
+/**
+ * `terraform-apply`'s group methods (chant#4447, ws-107): core forms a group
+ * of `terraform-apply` components that read each other, and these plan it
+ * as one plan and apply it as one apply of a composed root, so a value one
+ * root creates reaches its readers inside that apply.
+ *
+ * - `groupReads` reports to core each member's `terraform_remote_state` and
+ *   `terraform_estate_outputs` reads of another, as the composition finds
+ *   them, so roots wired in HCL alone form a group. Nothing while
+ *   `terraform.compose.enabled` is unset.
+ * - `groupFallback` answers `off` while `terraform.compose.enabled` is unset,
+ *   else builds the {@link Composition} (#4438) from the files, the config
+ *   and each member's cloud identity, and answers its fallback, if any. A
+ *   member the composition leaves out is dropped with its own kind and
+ *   reason, and core forms the group again from the rest (#4419 ruling 1).
+ *   A composition of estates also asks `choudoufu version` (#4445).
+ *   Nothing plans.
+ * - `planGroup` builds the composition again, plans it once with
+ *   `ComposedRun` (#4444) or, for estates, `EstateRun` (#4445), and answers
+ *   each member's part (#4442): its change-set part, planned outputs and
+ *   shape, with its own plan's digest. The group's digest is the composed
+ *   plan's with the generated files. The run is released before it returns,
+ *   with no lock taken, so a plan that core then refuses or makes wait
+ *   leaves no lock held and no file changed.
+ * - `runGroup` plans once more, this time under each state's lock, and
+ *   applies only when that plan's digest is the one `planGroup` answered;
+ *   otherwise it throws a moved plan and nothing applies. Whatever happens,
+ *   it releases the run. Each member's outputs come from the run: its part
+ *   of the working state's `show -json` for roots with state, the post-apply
+ *   plan's `prior_state` for estates.
+ *
+ * Each member's identity is `ci.identity.cloud` resolved for its root as
+ * the target (`resolveTargetCloudIdentity`, #4332), by the root's key or its
+ * directory, whichever a rule's target glob matches, compared by
+ * `identityKey`, so members that apply under different identities do not
+ * compose (#4438's `identity`).
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { loadChantConfigUpward } from "@intentius/chant/config";
+import { wiringReferencesAt } from "@intentius/chant/components/driver";
+import { computePlanDigest } from "@intentius/chant/lifecycle/plan-digest";
+import { declaredTargetCloudIdentity } from "@intentius/chant/workspace/ci-cloud-identity";
+import { COMPOSE_STEP_KIND, composeOff, compositionIfEnabled, identityKey, rootHclReads } from "../compose.js";
+import { terraformBinary, terraformOutputs } from "../op/activities/terraform.js";
+import { runBinary } from "../state/exec.js";
+import { estateVersionFallback, EstateRun } from "../compose/estate.js";
+import { ComposedRun } from "../compose/run.js";
+import { relPath, rootTexts } from "../compose/hcl.js";
+async function loadProject() {
+    const start = resolve(process.cwd());
+    const { config, configPath } = await loadChantConfigUpward(start);
+    const projectRoot = configPath ? dirname(configPath) : start;
+    const terraform = config.terraform;
+    return { projectRoot, terraform: { ...(terraform ?? {}), roots: terraform?.roots ?? {} } };
+}
+function defaultRunner(o, log) {
+    if (o.composition.estate) {
+        return new EstateRun({ projectRoot: o.projectRoot, composition: o.composition, terraform: o.terraform, env: o.env, work: o.work, ...(log ? { log } : {}) });
+    }
+    return new ComposedRun({
+        projectRoot: o.projectRoot,
+        composition: o.composition,
+        terraform: o.terraform,
+        binary: { path: terraformBinary(o.terraform) },
+        env: o.env,
+        work: o.work,
+        lock: o.lock,
+        ...(o.env.GITHUB_RUN_ID ? { runId: `github-run-${o.env.GITHUB_RUN_ID}` } : {}),
+        vars: o.vars,
+        componentOutputs: o.componentOutputs,
+        // A state that could not be written is kept here when its backend cannot take it; it outlives the run's own directory.
+        reportDir: join(o.projectRoot, ".chant", "compose", "unwritten"),
+        ...(log ? { log } : {}),
+    });
+}
+/** The members as components, each deploying its one step, for `compositionIfEnabled`. */
+export function memberComponents(members) {
+    return members.map((m) => ({
+        name: m.component,
+        ...(m.dependsOn ? { dependsOn: [...m.dependsOn] } : {}),
+        deploy: [{ phase: "Apply", steps: [{ ...m.step, kind: COMPOSE_STEP_KIND }] }],
+    }));
+}
+/**
+ * Each member's identity as `compositionFor` compares it: `identityKey` of
+ * `lookup` for the member's root, which a rule's target globs match by the
+ * root's key in `terraform.roots` or by its directory relative to the
+ * project (the first declared rule that either matches wins). Undefined
+ * without a lookup, so no member falls back as `identity`.
+ */
+export function memberIdentity(project, members, lookup) {
+    if (!lookup)
+        return undefined;
+    const names = (root) => {
+        const dir = project.terraform.roots[root]?.dir;
+        if (dir === undefined)
+            return [root];
+        return [root, relPath(project.projectRoot, isAbsolute(dir) ? dir : resolve(project.projectRoot, dir))];
+    };
+    const keys = new Map(members.map((m) => [m.component, identityKey(lookup(names(m.step.root)))]));
+    return (member) => keys.get(member);
+}
+/**
+ * The composition of exactly the group's members (core has already formed the
+ * group), or undefined when `terraform.compose` is not enabled.
+ */
+export function groupComposition(project, members, env, identity) {
+    const targets = Object.fromEntries(members.flatMap((m) => (m.ctx.targets?.length ? [[m.component, m.ctx.targets]] : [])));
+    return compositionIfEnabled({
+        projectRoot: project.projectRoot,
+        terraform: project.terraform,
+        components: memberComponents(members),
+        selected: new Set(members.map((m) => m.component)),
+        env,
+        targets,
+        ...(identity ? { identity } : {}),
+    });
+}
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** The data source and the attribute that holds its outputs, for each kind of HCL read. */
+const HCL_READ = { "remote-state": ["terraform_remote_state", "outputs"], "estate-outputs": ["terraform_estate_outputs", "values"] };
+/** The outputs the texts read off `data.<type>.<name>.<field>`, by attribute or by index, sorted. */
+function outputsRead(texts, type, name, field) {
+    const re = new RegExp(`\\bdata\\.${type}\\.${escapeRe(name)}\\.${field}(?:\\.([A-Za-z_][\\w-]*)|\\[\\s*\\\\?"([^"\\\\]+)\\\\?"\\s*\\])`, "g");
+    const out = new Set();
+    for (const text of texts)
+        for (const m of text.matchAll(re))
+            out.add((m[1] ?? m[2]));
+    return [...out].sort();
+}
+/**
+ * The members' HCL reads of each other (#4447): each `terraform_remote_state`
+ * block whose state is another member's backend, and each
+ * `terraform_estate_outputs` block naming another member's estate, as the
+ * composition finds them. Each output the reader's code takes off the block
+ * is one read, `<upstream>.<output>` as a `stackOutput()` read is named; a
+ * block whose outputs the code does not name one by one is one read with
+ * the block's address as `ref`. Core cannot see these in the step's `vars`.
+ */
+export function hclGroupReads(project, members) {
+    const reads = rootHclReads({ projectRoot: project.projectRoot, terraform: project.terraform, components: memberComponents(members) });
+    const out = [];
+    for (const [reader, rs] of reads) {
+        const m = members.find((x) => x.component === reader);
+        const dir = m ? project.terraform.roots[m.step.root]?.dir : undefined;
+        const texts = dir === undefined ? [] : rootTexts(isAbsolute(dir) ? dir : resolve(project.projectRoot, dir), project.terraform.binary).map((t) => t.text);
+        for (const r of rs) {
+            if (r.via === "vars")
+                continue;
+            const [type, field] = HCL_READ[r.via];
+            const named = outputsRead(texts, type, r.name, field);
+            if (named.length === 0)
+                out.push({ reader, upstream: r.upstream, ref: `data.${type}.${r.name}` });
+            for (const output of named)
+                out.push({ reader, upstream: r.upstream, ref: `${r.upstream}.${output}`, output });
+        }
+    }
+    return out;
+}
+/**
+ * What core is told of the group (#4419 ruling 1): the whole change's
+ * fallback when it is not `one-root`; else each member the composition left
+ * out as a drop with its own kind and reason, so core groups the rest
+ * again without them; else `one-root`. Undefined when every member
+ * composes.
+ */
+export function groupFallbackOf(c, members) {
+    if (c.fallback && c.fallback.kind !== "one-root")
+        return { kind: c.fallback.kind, reason: c.fallback.reason };
+    const drop = c.fallbacks.flatMap((f) => (f.member !== undefined && members.includes(f.member) ? [{ component: f.member, kind: f.kind, reason: f.reason }] : []));
+    if (!c.fallback) {
+        const named = new Set(drop.map((d) => d.component));
+        for (const m of members) {
+            if (!named.has(m) && !c.members.includes(m))
+                drop.push({ component: m, kind: "path", reason: `\`${m}\` deploys no root the composition could read` });
+        }
+    }
+    if (drop.length > 0)
+        return { kind: drop[0].kind, reason: drop[0].reason, drop };
+    if (c.fallback)
+        return { kind: c.fallback.kind, reason: c.fallback.reason };
+    return undefined;
+}
+/** `value` at the JSON Pointer `at`. */
+function atPointer(value, at) {
+    if (at === "")
+        return value;
+    return at
+        .slice(1)
+        .split("/")
+        .map((p) => p.replace(/~1/g, "/").replace(/~0/g, "~"))
+        .reduce((acc, key) => (acc == null ? acc : acc[key]), value);
+}
+/** Set `value` at the dotted `path` of `target`. */
+function setPath(target, path, value) {
+    const keys = path.split(".");
+    let at = target;
+    for (const k of keys.slice(0, -1)) {
+        const next = at[k];
+        at = (next && typeof next === "object" ? next : (at[k] = {}));
+    }
+    at[keys[keys.length - 1]] = value;
+}
+/**
+ * The outputs of components outside the group that the members' `vars`
+ * read, recovered from each member's input, which core resolved against
+ * them: `writeComposedRoot` turns those reads into literals.
+ */
+export function outsideOutputs(members) {
+    var _a;
+    const inGroup = new Set(members.map((m) => m.component));
+    const out = {};
+    for (const m of members) {
+        for (const r of wiringReferencesAt(m.step)) {
+            if (inGroup.has(r.source))
+                continue;
+            const value = atPointer(m.input, r.at);
+            if (value !== undefined)
+                setPath((out[_a = r.source] ?? (out[_a] = {})), r.output, value);
+        }
+    }
+    return out;
+}
+/** The members' unresolved reads of components outside the group, by member. */
+function unresolvedOf(members) {
+    return new Map(members.flatMap((m) => (m.ctx.unresolvedInputs?.length ? [[m.component, [...m.ctx.unresolvedInputs].sort()]] : [])));
+}
+/**
+ * The group while a member reads an output of a component outside it that
+ * is not known yet: no member is planned, each gets a hole naming what the
+ * group waits on, and core plans the group again once those apply.
+ */
+function waitingGroup(ctx, members, unresolved) {
+    const waits = [...new Set([...unresolved.values()].flat())].sort();
+    const by = [...unresolved.keys()].sort();
+    const plans = {};
+    for (const m of members) {
+        const root = m.step.root;
+        const vars = Object.fromEntries(Object.entries((m.input?.vars ?? {})).map(([k, v]) => [k, v === undefined ? null : v]));
+        const planDigest = computePlanDigest("terraform-apply-group-unresolved", { env: ctx.env, root, vars, unresolved: waits });
+        const reason = by.length === 1 && by[0] === m.component
+            ? `inputs from ${waits.join(", ")}; planned again once they apply`
+            : `inputs from ${waits.join(", ")}, read by ${by.join(", ")} in its group; planned again once they apply`;
+        const changeSet = {
+            member: { member: root, lexicon: "terraform", planner: "chant", status: "planned", planDigest, holes: [{ address: root, type: "terraform_root", reason }] },
+            entries: [],
+        };
+        plans[m.component] = { member: root, planDigest, changeSet };
+    }
+    return { members: plans, digest: computePlanDigest("terraform-apply-group-unresolved", { components: ctx.components, unresolved: waits }) };
+}
+/** A composed plan that no longer matches the one approved. Core's moved-plan mark, so nothing applies and the command exits 3. */
+export class ComposedPlanMovedError extends Error {
+    constructor(message) {
+        super(message);
+        this.planMoved = true;
+        this.name = "ComposedPlanMovedError";
+    }
+}
+/** The group methods, with `deps` in place of the defaults. */
+export function composeGroup(deps = {}) {
+    const project = deps.project ?? loadProject;
+    const exec = deps.exec ?? runBinary;
+    const envOf = () => deps.env ?? process.env;
+    const log = deps.log ?? ((line) => console.error(line));
+    const readOutputs = deps.outputs ?? ((root) => terraformOutputs({ root }));
+    const identities = deps.identity ?? declaredTargetCloudIdentity;
+    /** The composition of `members` as `groupFallback` judges it, with each member's identity. */
+    async function compositionOf(ctx, p, members) {
+        const lookup = await identities(p.projectRoot, ctx.env);
+        const c = groupComposition(p, members, envOf(), memberIdentity(p, members, lookup));
+        if (!c)
+            throw new Error(composeOff(p.terraform)?.reason ?? "`terraform.compose` is not enabled");
+        return c;
+    }
+    /** The composition the group plans as, or throws when it does not compose. */
+    async function composed(ctx, members) {
+        const p = await project();
+        const off = composeOff(p.terraform);
+        if (off)
+            throw new Error(off.reason);
+        const c = await compositionOf(ctx, p, members);
+        const refused = groupFallbackOf(c, members.map((m) => m.component));
+        if (refused)
+            throw new Error(`the group no longer composes: ${refused.reason}`);
+        return { p, c };
+    }
+    /** Build a runner, run `fn` on it, and release it and its directory whatever happened. */
+    async function withRunner(p, c, members, lock, fn) {
+        const work = mkdtempSync(join(tmpdir(), "chant-compose-"));
+        const o = {
+            ...p,
+            composition: c,
+            lock,
+            vars: Object.fromEntries(members.map((m) => [m.component, m.step.vars])),
+            componentOutputs: outsideOutputs(members),
+            env: envOf(),
+            work,
+        };
+        const runner = deps.runner ? deps.runner(o) : defaultRunner(o, log);
+        try {
+            return await fn(runner);
+        }
+        finally {
+            try {
+                await runner.release();
+            }
+            finally {
+                rmSync(work, { recursive: true, force: true });
+            }
+        }
+    }
+    return {
+        async groupReads(_ctx, members) {
+            const p = await project();
+            if (composeOff(p.terraform))
+                return [];
+            return hclGroupReads(p, members);
+        },
+        async groupFallback(ctx, members) {
+            const p = await project();
+            const off = composeOff(p.terraform);
+            if (off)
+                return { kind: off.kind, reason: off.reason };
+            const c = await compositionOf(ctx, p, members);
+            // A member left out is dropped alone; core asks again with the rest, and the estate check runs then.
+            const refused = groupFallbackOf(c, members.map((m) => m.component));
+            if (refused)
+                return refused;
+            if (c.estate) {
+                const binary = p.terraform.binary ?? "choudoufu";
+                const v = await exec(binary, ["version"], p.projectRoot, envOf());
+                // A binary that cannot say its version is left to the plan, which says why it fails.
+                const old = v.code === 0 ? estateVersionFallback(v.stdout) : undefined;
+                if (old)
+                    return { kind: old.kind, reason: old.reason };
+            }
+            return undefined;
+        },
+        async planGroup(ctx, members) {
+            const unresolved = unresolvedOf(members);
+            if (unresolved.size > 0)
+                return waitingGroup(ctx, members, unresolved);
+            const { p, c } = await composed(ctx, members);
+            // Planned without locks and released at once: nothing stays held or changed if core refuses the plan or makes it wait.
+            const planned = await withRunner(p, c, members, false, (r) => r.plan());
+            if (planned.fallback)
+                throw new Error(`the group no longer composes: ${planned.fallback.reason}`);
+            if (planned.error)
+                throw new Error(planned.error);
+            const plans = {};
+            for (const m of members) {
+                const part = planned.members[m.component];
+                if (!part)
+                    throw new Error(`the composed plan has no part for ${m.component}`);
+                plans[m.component] = { member: part.member, planDigest: part.planDigest, changeSet: part.changeSet, outputs: part.outputs, shape: part.shape };
+            }
+            const artifact = { digest: planned.digest, estate: c.estate === true };
+            return { members: plans, digest: planned.digest, artifact };
+        },
+        async runGroup(ctx, run, members) {
+            if (unresolvedOf(members).size > 0)
+                throw new Error("the group reads outputs of components outside it that are not known yet, so it cannot apply");
+            const approved = run.artifact;
+            if (typeof approved?.digest !== "string" || approved.digest === "")
+                throw new Error("no composed plan of the group to apply");
+            const { p, c } = await composed(ctx, members);
+            const notStarted = (error) => ({
+                members: Object.fromEntries(members.map((m) => [m.component, { status: "not-started", error }])),
+                error,
+            });
+            const applied = await withRunner(p, c, members, true, async (r) => {
+                // The approved plan was made without locks; plan again under them, and apply only that same plan.
+                const planned = await r.plan();
+                if (planned.fallback)
+                    return notStarted(`the group no longer composes: ${planned.fallback.reason}`);
+                if (planned.error)
+                    return notStarted(planned.error);
+                if (planned.digest !== approved.digest) {
+                    throw new ComposedPlanMovedError(`the composed plan moved since it was approved (approved ${approved.digest}, planned now ${planned.digest}), so nothing applied`);
+                }
+                return r.apply();
+            });
+            const out = {};
+            for (const m of members) {
+                const o = applied.members[m.component];
+                if (!o) {
+                    out[m.component] = { status: "failed", error: applied.error ?? `the composed apply said nothing of ${m.component}` };
+                    continue;
+                }
+                let outputs = o.outputs;
+                // A root's state is written by now; read its outputs from there when its part of the working state could not be shown.
+                if (!outputs && !c.estate && (o.status === "applied" || o.status === "no-changes")) {
+                    outputs = await readOutputs(m.step.root).catch(() => undefined);
+                }
+                const held = o.lockHeld ? `its state was kept unwritten${o.kept ? ` at ${o.kept}` : ""}, and its lock stays held until a later run writes it` : undefined;
+                const error = [o.error, held].filter(Boolean).join("; ");
+                out[m.component] = { status: o.status, ...(outputs ? { outputs } : {}), ...(error ? { error } : {}) };
+            }
+            return { members: out, ...(applied.error ? { error: applied.error } : {}) };
+        },
+    };
+}
+/** The group methods `terraform-apply` uses. */
+export const terraformComposeGroup = composeGroup();

package/dist/components/placeholder-preview.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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).
+ */
+import type { ChangeSetHole } from "@intentius/chant/change-set";
+/** The marker every string stand-in carries, so a reader can tell it from a real value. */
+export declare const TERRAFORM_UNKNOWN_MARK = "known-after-apply";
+/**
+ * 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 declare function terraformPlaceholder(type: string | undefined): unknown;
+/** The variables a preview gives stand-ins, and the `vars` it plans with. */
+export interface PlaceholderVars {
+    /** The variable names given a stand-in, sorted. */
+    placeholders: string[];
+    /** The step's `vars` with each of them replaced by its stand-in. */
+    vars: Record<string, unknown>;
+}
+/**
+ * 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 declare function placeholderVars(vars: Record<string, unknown> | undefined, declared: ReadonlyMap<string, {
+    type?: string;
+}>): PlaceholderVars | string;
+/** What {@link markPlaceholderDriven} returns. */
+export type MarkedPlan = {
+    plan: unknown;
+} | {
+    refused: string;
+};
+/**
+ * `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 declare function markPlaceholderDriven(planJson: unknown, placeholders: readonly string[]): MarkedPlan;
+/** The hole a root keeps when its preview is not possible: the old reason, and why there is no preview. */
+export declare function waitingHole(root: string, unresolved: readonly string[], why?: string): ChangeSetHole;
+//# sourceMappingURL=placeholder-preview.d.ts.map

package/dist/components/placeholder-preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholder-preview.d.ts","sourceRoot":"","sources":["../../src/components/placeholder-preview.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEjE,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAgC1D;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CA2BtE;AAKD,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,mDAAmD;IACnD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAAE,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,eAAe,GAAG,MAAM,CAgBrJ;AAiED,kDAAkD;AAClD,MAAM,MAAM,UAAU,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjE;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,UAAU,CAiCpG;AAED,2GAA2G;AAC3G,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,aAAa,CAMpG"}