@intentius/chant-lexicon-terraform 0.124.31 → 0.124.32

package/dist/describe-resources.js

@@ -0,0 +1,984 @@
+/**
+ * Live observation for declared terraform entities (#2087, #2104).
+ *
+ * `buildRoots()` turns each configured root module into one entity per HCL
+ * block, keyed `<root>/<address>` (`./hcl/parse.ts`). This reader answers the
+ * lifecycle question for those entities, and how it answers depends on one
+ * fact the parse already recorded on every entity: the root's `mode`.
+ *
+ * A **stock** root is read with `terraform show -json` over its state, and
+ * state membership is the ownership answer. A **live** root, meaning
+ * `terraform.binary` is `"choudoufu"` and the root declares an estate
+ * (#2103), has no state to show: it is read with `choudoufu live-plan -json`,
+ * and the marker on the resource is the ownership answer. The two halves are
+ * two adapters over the same `observeEntities` harness, picked per root.
+ *
+ * ## Which of the two answered is on the wire (#2267)
+ *
+ * They are different claims. `terraform show -json` says what the last apply
+ * recorded; `choudoufu live-plan -json` says what the account holds now. A
+ * renderer that paints an observation as drift and cannot tell them apart
+ * paints a state read green, which reads as "the account matches" when all it
+ * says is "the apply finished". For an estate that has decided state is never
+ * the system of record, a state-backed observation is not a weaker answer, it
+ * is a different one.
+ *
+ * So the returned `ObservationResult` carries `sources`, keyed by chant entity
+ * name, with one of exactly two values:
+ *
+ * - `"state"` — this entity's root was read with `terraform show -json`.
+ * - `"live"` — this entity's root was read with `choudoufu live-plan -json`.
+ *
+ * Three guarantees a consumer may rely on. Every entity `describeResources`
+ * was asked about that belongs to a root has an entry, whatever verdict it
+ * came back with: present, absent and not-observed alike, because which read
+ * was attempted is a fact independent of what it found. The value equals the
+ * declared entity's own `props.mode` (`./hcl/parse.ts`), since one fact
+ * decides both, so `props.mode` is also a valid join key for a consumer
+ * holding the declared graph and no observation. And a project mixing stock
+ * and live roots gets both values in one document, which is why this is a map
+ * and not a field on the result as a whole.
+ *
+ * An entity with no root gets no entry, for the same reason it gets no read.
+ *
+ * ## The state file is the ownership answer, on a stock root
+ *
+ * Every other lexicon in chant stamps a tag or a label at synthesis and reads
+ * it back off the live resource. Terraform stamps nothing, and there is
+ * nowhere to stamp: a resource's provider-side tags are the practitioner's
+ * own, and writing chant's marker into them would edit an estate this lexicon
+ * promises never to write. What terraform has instead is the thing chant
+ * elsewhere refuses to host, a trusted state file that already records
+ * exactly which addresses this configuration manages.
+ *
+ * So the answer here is state membership. An address `terraform show -json`
+ * returns is `owned`; anything else is `unknown`. Concretely that makes a
+ * declared `module` block `unknown`: the state carries the module's
+ * resources, never a row for the block itself, so chant can see the block is
+ * live without the state ever saying that block is managed. `unknown` never
+ * escalates to a delete, which is the correct posture for a thing chant did
+ * not read a verdict for.
+ *
+ * That places a stock terraform root on the trusted-state-file row of the
+ * third axis in docs/src/content/docs/concepts/lifecycle-models.mdx, where
+ * chant elsewhere sits on the live-marker row. `docs/pages/observation.mdx`
+ * is the reader's version of this paragraph.
+ *
+ * ## The marker is the ownership answer, on a live root
+ *
+ * choudoufu keeps no authoritative state file. Every taggable resource it
+ * manages carries `tofu-estate` and `tofu-address` tags written in the create
+ * call, prior state is rebuilt from the live system each run, and the state
+ * file, where one exists at all, is a disposable cache. So a live root is on
+ * the live-marker row, the row every other chant lexicon sits in.
+ *
+ * chant does not re-derive that verdict from the tags. `live-plan -json`
+ * (choudoufu issue #788) already splits every declared instance four ways,
+ * and those four are the classification:
+ *
+ * | live-plan section | chant |
+ * |---|---|
+ * | `bound[]`, `source: "marker"` | present, `owned`; the marker named this estate and this address, and it is surfaced as `ResourceMetadata.marker` |
+ * | `bound[]`, any other source | present, `owned` by derivation, record, or cache; noted as such, and no marker is surfaced because none was read |
+ * | `unowned[]` with `adopt_*` | present, `unknown`; an adoptable match, carrying the exact two tag values #2105 would write |
+ * | `unowned[]` without | present, `foreign`; a live resource is in the way at a declared identity and the plan will not touch it |
+ * | `adoptable[]` | present, `unknown`; the same adoptable verdict, for a live resource the sweep content-matched to a declaration that carries no identity of its own (choudoufu #962, chant #2241) |
+ * | `omissions[]` | not-observed, `ABSENT` excepted (see below) |
+ *
+ * The ownership channel this declares is `./live-ownership.ts`'s
+ * `TERRAFORM_LIVE_MARKER_KEYS`, and its module doc holds the record of why
+ * the keys are declared while the verdicts are set here by hand rather than
+ * core's `OwnershipChannel` growing a classifier for them.
+ *
+ * ### `ABSENT` is absence, and the rest of the omissions are not
+ *
+ * An omission is choudoufu saying an instance is missing from prior state,
+ * with a reason. Most of those reasons are claims of ignorance and become
+ * NOT-OBSERVED, which is what the tri-state exists for. One is not:
+ * `ABSENT` means "the instance has a usable import identity and the provider
+ * reported, normally, that no such object exists", which is exactly chant's
+ * OBSERVED-ABSENT, spelled "in neither map". Reporting it as not-observed
+ * instead would mean a live root could never propose a create for a resource
+ * that genuinely is not there yet, which is the opposite of the honesty the
+ * contract is for. `UNOWNED` is the other exception, in the other direction:
+ * the `unowned[]` section answers for that address with a real verdict, so
+ * the paired omission is never read on its own.
+ *
+ * ### A block's instances, aggregated
+ *
+ * chant's entity is the HCL block, `aws_eip.pool`; the document's rows are
+ * instances, `aws_eip.pool[0]`. So a block's verdict is the aggregate of its
+ * instances, in this precedence: any instance not-observed makes the block
+ * not-observed, then foreign, then adoptable, then owned, and a block whose
+ * instances are all absent is absent. Partial knowledge is not knowledge,
+ * which is the same rule choudoufu applies to its own `INCOMPLETE_BLOCK`.
+ *
+ * ## What is readable at all
+ *
+ * `values.root_module.resources[]` (and, recursively, `child_modules[]`)
+ * carries `resource` and `data` blocks. A `terraform`, `provider`, `variable`,
+ * `output` or `locals` block has no row there and reads `unsupported-kind`.
+ * That is honest, not a gap to close by inventing an address for something
+ * that has none.
+ *
+ * A live root reads one block narrower. `live-plan`'s document is prior state
+ * for managed resources, so a `data` block has no row in it either and reads
+ * `unsupported-kind` there, where the stock reader can answer for it.
+ *
+ * ## Tri-state (#1089)
+ *
+ * A root whose `init` or `show` fails, or whose `live-plan` fails, reports
+ * EVERY entity declared in that root as not-observed with the mapped reason
+ * and the root named, never absent. A failed read must never render as a list
+ * of creates. Roots are read independently and merged (`mergeObservations`),
+ * so one broken backend does not un-observe a root that answered.
+ *
+ * ## Beyond the declared estate, on a live root
+ *
+ * `live-ls -estate -json` lists the whole estate off the Resource Groups
+ * Tagging API with no configuration read at all, which is a question a state
+ * file cannot answer: what does this estate hold that nothing declares? That
+ * is what makes `ambientKinds()`, `observeAmbient()` and `teardownOwned()`
+ * implementable on this lexicon for the first time. `-consistent` is always
+ * passed, because that index lags a tag write by about a minute
+ * (`live-ls`'s own help text) and a listing taken right after an apply can
+ * otherwise show a resource under both its old and new estate, or neither.
+ *
+ * ## Nothing from `values` is surfaced
+ *
+ * A state row's `values` are the resource's full attribute set, secrets
+ * included, and `sensitive_values` describes only what the configuration
+ * declared sensitive. So the attributes reported here are the row's identity
+ * (address, type, mode, provider, root) and nothing from `values` except the
+ * `id`, which is the physical id every observation carries.
+ */
+import { mergeObservations, normalizeObservation, observation, observeEntities, } from "@intentius/chant/observation";
+import { choudoufuLiveLs, choudoufuLivePlanDocument, terraformInit, terraformShow, } from "./op/activities/terraform.js";
+import { DATA_TYPE, MODULE_TYPE, RESOURCE_TYPE, callersOfKey } from "./hcl/parse.js";
+// The channel keys live in their own module so `plugin.ts` can declare
+// `ownershipChannel` without loading this reader. Re-exported here because
+// this is where they are used.
+export { TERRAFORM_STATE_OWNERSHIP_KEYS } from "./state-ownership.js";
+export { TERRAFORM_LIVE_MARKER_KEYS } from "./live-ownership.js";
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function asString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/**
+ * Index a `terraform show -json` document by address.
+ *
+ * Terraform already writes fully qualified addresses inside `child_modules`
+ * (`module.cdn.null_resource.edge`, as `src/__fixtures__/show-state.json`
+ * records), so the module prefix is applied only when a row's own address is
+ * missing it. Belt and braces for an older `format_version`, never a second
+ * `module.cdn.` on top of the first.
+ */
+export function indexStateResources(showJson) {
+    const rows = new Map();
+    const modules = new Set();
+    const walk = (module, prefix) => {
+        const node = asRecord(module);
+        for (const entry of asArray(node.resources)) {
+            const row = asRecord(entry);
+            const raw = asString(row.address);
+            if (!raw)
+                continue;
+            const address = prefix && !raw.startsWith(`${prefix}.`) ? `${prefix}.${raw}` : raw;
+            rows.set(address, {
+                address,
+                ...(asString(row.mode) ? { mode: asString(row.mode) } : {}),
+                ...(asString(row.type) ? { type: asString(row.type) } : {}),
+                ...(asString(row.provider_name) ? { providerName: asString(row.provider_name) } : {}),
+                ...(asString(asRecord(row.values).id) ? { id: asString(asRecord(row.values).id) } : {}),
+            });
+        }
+        for (const entry of asArray(node.child_modules)) {
+            const child = asRecord(entry);
+            const address = asString(child.address) ?? prefix;
+            if (address)
+                modules.add(address);
+            walk(child, address ?? "");
+        }
+    };
+    walk(asRecord(asRecord(showJson).values).root_module, "");
+    return { rows, modules };
+}
+/**
+ * The ownership verdict for one declared address: `owned` when the state
+ * carries a row for it, `unknown` otherwise. Exported because it is the whole
+ * of terraform's ownership channel, and a channel with one rule deserves one
+ * function to point at.
+ */
+export function classifyStateOwnership(address, index) {
+    return index.rows.has(address) ? "owned" : "unknown";
+}
+/** True when the state carries at least one resource beneath `module.<name>`. */
+function moduleIsLive(address, index) {
+    if (index.modules.has(address))
+        return true;
+    for (const key of index.rows.keys())
+        if (key.startsWith(`${address}.`))
+            return true;
+    return false;
+}
+/**
+ * Index choudoufu issue #788's document. Unknown fields are ignored and a
+ * missing section reads as empty: a document from a newer choudoufu must
+ * degrade to "this section said nothing", never to a throw.
+ */
+export function indexLivePlan(document) {
+    const doc = asRecord(document);
+    const index = {
+        estate: asString(doc.estate) ?? "",
+        bound: new Map(),
+        omissions: new Map(),
+        unowned: new Map(),
+        adoptable: new Map(),
+        swept: asArray(doc.swept).filter((t) => typeof t === "string"),
+        addresses: [],
+        diagnostics: [],
+    };
+    for (const entry of asArray(doc.bound)) {
+        const row = asRecord(entry);
+        const addr = asString(row.addr);
+        if (!addr)
+            continue;
+        index.bound.set(addr, {
+            addr,
+            ...(asString(row.type) ? { type: asString(row.type) } : {}),
+            ...(asString(row.identity) ? { identity: asString(row.identity) } : {}),
+            ...(asString(row.source) ? { source: asString(row.source) } : {}),
+        });
+    }
+    for (const entry of asArray(doc.omissions)) {
+        const row = asRecord(entry);
+        const addr = asString(row.addr);
+        if (!addr)
+            continue;
+        index.omissions.set(addr, {
+            addr,
+            reason: asString(row.reason) ?? "",
+            detail: asString(row.detail) ?? "",
+        });
+    }
+    for (const entry of asArray(doc.unowned)) {
+        const row = asRecord(entry);
+        const addr = asString(row.addr);
+        if (!addr)
+            continue;
+        index.unowned.set(addr, {
+            addr,
+            ...(asString(row.type) ? { type: asString(row.type) } : {}),
+            ...(asString(row.identity) ? { identity: asString(row.identity) } : {}),
+            ...(asString(row.tofu_estate) ? { heldBy: asString(row.tofu_estate) } : {}),
+            ...(asString(row.adopt_tofu_estate) ? { adoptEstate: asString(row.adopt_tofu_estate) } : {}),
+            ...(asString(row.adopt_tofu_address) ? { adoptAddress: asString(row.adopt_tofu_address) } : {}),
+        });
+    }
+    for (const entry of asArray(doc.adoptable)) {
+        const row = asRecord(entry);
+        const addr = asString(row.addr);
+        if (!addr)
+            continue;
+        const matched = asArray(row.matched)
+            .map((m) => asRecord(m))
+            .filter((m) => asString(m.attribute))
+            .map((m) => ({ attribute: asString(m.attribute), value: asString(m.value) ?? "" }));
+        index.adoptable.set(addr, {
+            addr,
+            ...(asString(row.type) ? { type: asString(row.type) } : {}),
+            ...(asString(row.identity) ? { identity: asString(row.identity) } : {}),
+            ...(asString(row.adopt_tofu_estate) ? { adoptEstate: asString(row.adopt_tofu_estate) } : {}),
+            ...(asString(row.adopt_tofu_address) ? { adoptAddress: asString(row.adopt_tofu_address) } : {}),
+            ...(matched.length > 0 ? { matched } : {}),
+        });
+    }
+    for (const entry of asArray(doc.diagnostics)) {
+        const row = asRecord(entry);
+        const summary = asString(row.summary);
+        if (summary)
+            index.diagnostics.push(`${asString(row.severity) ?? "warning"}: ${summary}`);
+    }
+    index.addresses = [
+        ...new Set([
+            ...index.bound.keys(),
+            ...index.omissions.keys(),
+            ...index.unowned.keys(),
+            ...index.adoptable.keys(),
+        ]),
+    ].sort();
+    return index;
+}
+/**
+ * choudoufu's omission reason codes, mapped onto chant's total vocabulary
+ * (`internal/live/projection/result.go`). `"absent"` is not an
+ * {@link UnobservedReason}: it is the tri-state's OBSERVED-ABSENT, the one
+ * omission that is a claim of knowledge rather than of ignorance.
+ *
+ * A code this table does not know maps to `read-failed`, which is the safe
+ * direction: no NOT-OBSERVED verdict ever becomes a create or a delete.
+ */
+export const LIVE_PLAN_OMISSION_REASONS = {
+    // The provider was asked and reported, normally, that nothing is there.
+    ABSENT: "absent",
+    // The provider errored, or could not be reached in a usable order.
+    FAILED: "read-failed",
+    PARENT_UNAVAILABLE: "read-failed",
+    CYCLE: "read-failed",
+    INCOMPLETE_BLOCK: "read-failed",
+    LISTED_NOT_IMPORTABLE: "read-failed",
+    // Something exists at the identity and does not carry this estate's marker.
+    // Normally answered by the `unowned[]` section before this table is read;
+    // this entry is what happens if a document ever carries the omission alone.
+    UNOWNED: "read-failed",
+    // The mode cannot name, list or tag this instance at all: a server-assigned
+    // identity with no marker to find it by, a resource with no cloud object to
+    // read, or an address another declared instance has taken over.
+    NEEDS_DISCOVERY: "unsupported-kind",
+    UNREADABLE: "unsupported-kind",
+    SUPERSEDED: "unsupported-kind",
+};
+/** Does this text name a credentials or authorization failure rather than any other error? */
+function readsAsCredentials(text) {
+    return /\b(no valid credential|credentials?|not authorized|unauthorized|accessdenied|access denied|expiredtoken|invalidclienttokenid|signature)\b/i.test(text);
+}
+/** The chant verdict for one omission: `no-credentials` when its detail says so. */
+function omissionVerdict(row) {
+    const mapped = LIVE_PLAN_OMISSION_REASONS[row.reason] ?? "read-failed";
+    if (mapped === "read-failed" && readsAsCredentials(row.detail))
+        return "no-credentials";
+    return mapped;
+}
+/**
+ * Every instance address in the document belonging to the declared block
+ * `address`. Exported for the behaviour request builder (`./behaviour/`,
+ * #2360), which places the same blocks against the same document.
+ */
+export function instancesOf(address, index) {
+    return index.addresses.filter((a) => a === address || a.startsWith(`${address}[`));
+}
+/** True when the document names any instance under `module.<name>`, at any depth. */
+function liveModuleMembers(address, index) {
+    return index.addresses.filter((a) => a === address || a.startsWith(`${address}.`) || a.startsWith(`${address}[`));
+}
+/**
+ * Classify one instance address against the document, `unowned[]` first: a
+ * declared instance that also carries a `UNOWNED` omission is answered by the
+ * section that has the verdict, not by the one that has the apology.
+ * `adoptable[]` sits under `bound[]` for the same reason, one rung further
+ * down: a content match is the answer for an instance nothing else could
+ * answer for, and its paired omission is always `NEEDS_DISCOVERY`, which on
+ * its own would read as unsupported-kind and hide a real, actionable verdict
+ * (choudoufu #962, chant #2241).
+ */
+export function classifyLiveInstance(address, index) {
+    const unowned = index.unowned.get(address);
+    if (unowned) {
+        return unowned.adoptEstate || unowned.adoptAddress
+            ? { kind: "adoptable", row: unowned }
+            : { kind: "foreign", row: unowned };
+    }
+    const bound = index.bound.get(address);
+    if (bound)
+        return { kind: "owned", row: bound };
+    const matched = index.adoptable.get(address);
+    if (matched && (matched.adoptEstate || matched.adoptAddress)) {
+        return { kind: "adoptable", row: matched };
+    }
+    const omission = index.omissions.get(address);
+    if (omission) {
+        const verdict = omissionVerdict(omission);
+        if (verdict === "absent")
+            return { kind: "absent" };
+        return {
+            kind: "unobserved",
+            reason: verdict,
+            detail: `${address}: ${omission.reason}${omission.detail ? ` — ${omission.detail}` : ""}`,
+        };
+    }
+    return { kind: "absent" };
+}
+/**
+ * The declared block's verdict, aggregated over its instances in the
+ * precedence the module doc states: not-observed, then foreign, then
+ * adoptable, then owned, and all-absent last. A block whose instances are
+ * only partly known is not partly owned; it is unknown, which never becomes
+ * a delete.
+ */
+function readLiveResource(entity, index, root, queried) {
+    const { address } = entity;
+    const instances = instancesOf(address, index);
+    if (instances.length === 0)
+        return { absent: true, queried };
+    const verdicts = instances.map((a) => classifyLiveInstance(a, index));
+    const attributes = { address, root, estate: index.estate };
+    if (instances.length > 1 || instances[0] !== address)
+        attributes.instances = instances;
+    const unobserved = verdicts.find((v) => v.kind === "unobserved");
+    if (unobserved && unobserved.kind === "unobserved") {
+        return { unobserved: { reason: unobserved.reason, detail: unobserved.detail }, queried };
+    }
+    const foreign = verdicts.find((v) => v.kind === "foreign");
+    if (foreign && foreign.kind === "foreign") {
+        return {
+            present: {
+                type: entity.type,
+                physicalId: foreign.row.identity ?? address,
+                status: "unowned",
+                ownership: "foreign",
+                attributes: {
+                    ...attributes,
+                    ...(foreign.row.type ? { resourceType: foreign.row.type } : {}),
+                    ...(foreign.row.heldBy ? { heldBy: foreign.row.heldBy } : {}),
+                },
+            },
+            queried,
+        };
+    }
+    const adoptable = verdicts.find((v) => v.kind === "adoptable");
+    if (adoptable && adoptable.kind === "adoptable") {
+        // `unknown`, not `foreign`: the resource matches the declaration and one
+        // tag write claims it. The two values that write carries are the whole
+        // adoption proposal #2105 builds its Op on, so they ride the metadata
+        // rather than being re-derived from the address there. No `marker` is
+        // surfaced, because nothing was read off this resource: it carries none.
+        return {
+            present: {
+                type: entity.type,
+                physicalId: adoptable.row.identity ?? address,
+                status: "adoptable",
+                ownership: "unknown",
+                attributes: {
+                    ...attributes,
+                    ...(adoptable.row.type ? { resourceType: adoptable.row.type } : {}),
+                    ...(adoptable.row.adoptEstate ? { adoptTofuEstate: adoptable.row.adoptEstate } : {}),
+                    ...(adoptable.row.adoptAddress ? { adoptTofuAddress: adoptable.row.adoptAddress } : {}),
+                    // Present only on a content match: the arguments the sweep compared,
+                    // which is the whole evidence for a match nobody read an identity
+                    // for, and the thing an operator checks before letting a tag write
+                    // claim the resource.
+                    ...(adoptable.row.matched?.length
+                        ? { matchedOn: adoptable.row.matched.map((m) => `${m.attribute}=${m.value}`) }
+                        : {}),
+                },
+            },
+            queried,
+        };
+    }
+    const owned = verdicts.filter((v) => v.kind === "owned");
+    if (owned.length === 0)
+        return { absent: true, queried };
+    const sources = [...new Set(owned.map((v) => v.row.source ?? "unknown"))].sort();
+    const byMarker = sources.length === 1 && sources[0] === "marker";
+    return {
+        present: {
+            type: entity.type,
+            physicalId: owned.length === 1 ? (owned[0].row.identity ?? address) : address,
+            status: "bound",
+            ownership: "owned",
+            // The marker is surfaced only where one was actually read. A `derived`
+            // bind computed the identity from the configuration and looked at no
+            // tag, so claiming a marker for it would be a guess.
+            ...(byMarker ? { marker: { stack: index.estate } } : {}),
+            attributes: {
+                ...attributes,
+                ...(owned[0].row.type ? { resourceType: owned[0].row.type } : {}),
+                boundBy: sources.join(","),
+            },
+        },
+        queried,
+    };
+}
+/**
+ * One live root's reader: `live-plan -json`, then address matching against
+ * the document. `terraform show` is never run here, and there is no state
+ * file to run it over.
+ */
+function liveAdapter(root, cwd, deps) {
+    const where = cwd ? { cwd } : {};
+    let dir;
+    return {
+        async bind() {
+            const planned = await deps.livePlan({ root, ...where });
+            dir = planned.dir;
+            return indexLivePlan(planned.json);
+        },
+        classifyBindFailure(err) {
+            const message = err instanceof Error ? err.message.split("\n")[0] : String(err);
+            const full = err instanceof Error ? err.message : String(err);
+            return {
+                reason: readsAsCredentials(full) ? "no-credentials" : "read-failed",
+                detail: `terraform.roots.${root}${dir ? ` (${dir})` : ""}: ${message}`,
+            };
+        },
+        async read(index, entity) {
+            const declared = entity;
+            const { address } = declared;
+            const queried = `choudoufu live-plan -json (root "${root}", estate "${index.estate}", address "${address}")`;
+            if (entity.type === RESOURCE_TYPE)
+                return readLiveResource(declared, index, root, queried);
+            if (entity.type === DATA_TYPE) {
+                return {
+                    unobserved: {
+                        reason: "unsupported-kind",
+                        detail: "live-plan's document is prior state for managed resources; a data block has no row in bound, omissions or unowned",
+                    },
+                    queried,
+                };
+            }
+            if (entity.type === MODULE_TYPE) {
+                const members = liveModuleMembers(address, index);
+                if (members.length === 0)
+                    return { absent: true, queried };
+                // Same shape as the stock reader's module answer, for the same
+                // reason: the document names the module's resources and never the
+                // block itself, so the ownership channel has nothing to say about it.
+                return {
+                    present: {
+                        type: entity.type,
+                        physicalId: address,
+                        status: "module",
+                        ownership: "unknown",
+                        attributes: { address, root, estate: index.estate, instances: members },
+                    },
+                    queried,
+                };
+            }
+            return {
+                unobserved: {
+                    reason: "unsupported-kind",
+                    detail: `${entity.type} has no row in a live-plan document: only resource blocks do`,
+                },
+                queried,
+            };
+        },
+    };
+}
+/** Parse a `live-ls -json` document. A missing section reads as empty, never as a throw. */
+export function readLiveLs(document) {
+    const doc = asRecord(document);
+    const items = [];
+    for (const entry of asArray(doc.items)) {
+        const row = asRecord(entry);
+        const id = asString(row.id);
+        const type = asString(row.type);
+        if (!id || !type)
+            continue;
+        const tags = {};
+        for (const [key, value] of Object.entries(asRecord(row.tags))) {
+            if (typeof value === "string")
+                tags[key] = value;
+        }
+        items.push({
+            id,
+            type,
+            ...(asString(row.address) ? { address: asString(row.address) } : {}),
+            ...(asString(row.slot) ? { slot: asString(row.slot) } : {}),
+            declared: row.declared === true,
+            ...(asString(row.source) ? { source: asString(row.source) } : {}),
+            tags,
+        });
+    }
+    const gaps = [];
+    for (const entry of asArray(doc.gaps)) {
+        const row = asRecord(entry);
+        const address = asString(row.address);
+        if (!address)
+            continue;
+        gaps.push({
+            address,
+            type: asString(row.type) ?? "",
+            rung: asString(row.rung) ?? "",
+            detail: asString(row.detail) ?? "",
+        });
+    }
+    return { estate: asString(doc.estate) ?? "", items, gaps };
+}
+/**
+ * A live-ls gap's rung, mapped onto chant's vocabulary. Both rungs mean the
+ * same thing to a reader of the listing: this instance can never appear in
+ * it, because the mechanism the listing uses cannot reach it. That is
+ * `unsupported-kind`, not a failure and not an absence.
+ */
+function gapReason() {
+    return "unsupported-kind";
+}
+/**
+ * The entity key `buildRoots()` would have produced for a live resource's
+ * address.
+ *
+ * A live address is fully qualified with dots, `module.cdn.null_resource.edge`;
+ * the build keys a descended child module's block with a slash per call,
+ * `app/module.cdn/null_resource.edge` (#2112). Splitting the `module.<name>.`
+ * prefixes back out is what keeps a live row and the block that declared it
+ * on the same key.
+ */
+export function entityKeyFor(root, address) {
+    const parts = address.split(".");
+    const segments = [];
+    let i = 0;
+    while (i + 1 < parts.length && parts[i] === "module") {
+        segments.push(`module.${parts[i + 1]}`);
+        i += 2;
+    }
+    segments.push(parts.slice(i).join("."));
+    return [root, ...segments].join("/");
+}
+/**
+ * The entity types this lexicon can enumerate beyond the declared estate
+ * (#1278). One: a `resource` block, whose live counterparts `live-ls` lists
+ * off the tag index. A `data`, `module` or `provider` block has no live
+ * counterpart to enumerate at all.
+ */
+export function ambientKinds() {
+    return [RESOURCE_TYPE];
+}
+/**
+ * Every live root the project declares, in config order. Reads the project
+ * config the same way the activities do, so `terraform.roots` is read once
+ * and the same answer reaches both.
+ */
+export async function liveRootNames(cwd) {
+    const { loadChantConfigUpward } = await import("@intentius/chant/config");
+    const { detectLiveEstate } = await import("./op/activities/live-detect.js");
+    const { dirname, resolve } = await import("node:path");
+    const start = resolve(cwd ?? process.cwd());
+    const { config, configPath } = await loadChantConfigUpward(start);
+    const projectRoot = configPath ? dirname(configPath) : start;
+    const namespace = config
+        .terraform;
+    if (namespace?.binary !== "choudoufu")
+        return [];
+    const live = [];
+    for (const [name, root] of Object.entries(namespace.roots ?? {})) {
+        const estate = detectLiveEstate(resolve(projectRoot, root.dir));
+        if (estate !== undefined)
+            live.push({ root: name, estate });
+    }
+    return live;
+}
+/**
+ * Report the resources this estate owns that nothing declares (#1278) — the
+ * owned-orphan set, which is `live-ls`'s `declared: false` rows.
+ *
+ * This is the question a state file cannot answer at all, because a state
+ * file knows only what it created. The tag index knows what the estate holds,
+ * whether or not any configuration still mentions it.
+ */
+export async function observeAmbient(options, deps = REAL_DEPS) {
+    // The bound #1278 asks for: a project that declares no terraform resources
+    // is never made to enumerate an estate.
+    if (!options.kinds.includes(RESOURCE_TYPE))
+        return {};
+    const out = {};
+    for (const { root, estate } of await liveRoots(options)) {
+        const listed = await deps.liveLs({
+            root,
+            consistent: true,
+            ...(options.cwd ? { cwd: options.cwd } : {}),
+        });
+        const listing = readLiveLs(listed.json);
+        for (const item of listing.items) {
+            if (item.declared)
+                continue; // declared is `describeResources`'s business, not this one's
+            const address = item.address ?? item.id;
+            const name = entityKeyFor(root, address);
+            if (options.observed[name])
+                continue;
+            out[name] = {
+                type: RESOURCE_TYPE,
+                physicalId: item.id,
+                status: "orphan",
+                ownership: "owned",
+                marker: { stack: listing.estate || estate },
+                ambient: true,
+                attributes: {
+                    address,
+                    root,
+                    estate: listing.estate || estate,
+                    resourceType: item.type,
+                    ...(item.slot ? { slot: item.slot } : {}),
+                    ...(item.source ? { listedBy: item.source } : {}),
+                    tags: item.tags,
+                },
+            };
+        }
+    }
+    return out;
+}
+/**
+ * Name what a teardown of this environment would remove from every live root
+ * (#1222): the estate's owned orphans, which are exactly the set choudoufu's
+ * own default `policy` verb (`undeclared_tagged = "delete"`) removes on the
+ * next apply.
+ *
+ * Candidates carry the requested identity verbatim, because that identity is
+ * what selected them: the roots enumerated here are this project's own, and
+ * their estates are what `terraform.roots` declares for this environment.
+ * The estate that actually answered rides `name`, so a reviewer of the plan
+ * can see which one it was.
+ *
+ * `live-ls`'s own `gaps[]` become holes rather than silence, per #1089: a
+ * declared instance the tag index can never serve is unknown, not clean.
+ */
+export async function teardownOwned(options, deps = REAL_DEPS) {
+    const candidates = [];
+    const holes = [];
+    for (const { root, estate } of await liveRoots(options)) {
+        let listing;
+        try {
+            const listed = await deps.liveLs({
+                root,
+                consistent: true,
+                ...(options.cwd ? { cwd: options.cwd } : {}),
+            });
+            listing = readLiveLs(listed.json);
+        }
+        catch (err) {
+            // Nothing was read, so nothing is known about this root's estate. A
+            // hole, never an empty candidate list, which would read as "clean".
+            holes.push({
+                name: `terraform.roots.${root}`,
+                reason: "read-failed",
+                detail: `choudoufu live-ls (estate "${estate}"): ${err instanceof Error ? err.message : String(err)}`,
+            });
+            continue;
+        }
+        for (const item of listing.items) {
+            if (item.declared)
+                continue;
+            candidates.push({
+                name: entityKeyFor(root, item.address ?? item.id),
+                type: RESOURCE_TYPE,
+                physicalId: item.id,
+                marker: options.marker,
+            });
+        }
+        for (const gap of listing.gaps) {
+            holes.push({
+                name: entityKeyFor(root, gap.address),
+                type: RESOURCE_TYPE,
+                reason: gapReason(),
+                detail: `${gap.rung}: ${gap.detail}`,
+            });
+        }
+    }
+    return { candidates, ...(holes.length > 0 ? { holes } : {}) };
+}
+/** The live roots an estate-wide read runs over: the caller's list, or every one declared. */
+async function liveRoots(options) {
+    const declared = await liveRootNames(options.cwd);
+    if (!options.roots)
+        return declared;
+    const wanted = new Set(options.roots);
+    return declared.filter((entry) => wanted.has(entry.root));
+}
+const REAL_DEPS = {
+    init: terraformInit,
+    show: terraformShow,
+    livePlan: choudoufuLivePlanDocument,
+    liveLs: choudoufuLiveLs,
+};
+/**
+ * Split a `<root>/<address>` entity key, or a descended child module's
+ * `<root>/module.<name>/<address>` (#2112). Only a fallback: `buildRoots()`
+ * records the root, the address and the call chain on `props`, and a
+ * duplicated address is keyed `…~2` there, so the props are the reliable
+ * source.
+ */
+function fromEntityName(name) {
+    const slash = name.indexOf("/");
+    if (slash === -1)
+        return { root: "", address: name, callers: [] };
+    const last = name.lastIndexOf("/");
+    return {
+        root: name.slice(0, slash),
+        address: name.slice(last + 1).replace(/~\d+$/, ""),
+        callers: callersOfKey(name),
+    };
+}
+/**
+ * The address the live system knows a block by. For a root-module block that
+ * is the block's own address; for one inside a child module it is what
+ * `terraform show -json` writes in `child_modules[]` and what choudoufu's
+ * markers carry, the call chain and the address joined with dots:
+ * `module.cdn.null_resource.edge` (#2112). The entity KEY keeps its slashes
+ * (`app/module.cdn/null_resource.edge`), so what a build declares and what a
+ * read observes still line up one to one.
+ */
+export function qualifiedAddress(address, callers) {
+    return callers.length === 0 ? address : `${callers.join(".")}.${address}`;
+}
+/**
+ * The root, qualified address and mode of one declared entity, from what
+ * `buildRoots()` recorded on its props. Exported for the behaviour request
+ * builder (#2360), which groups entities by root the same way.
+ */
+export function declaredOf(name, entity) {
+    const props = entity?.props ?? {};
+    const fallback = fromEntityName(name);
+    const callers = Array.isArray(props.callers)
+        ? props.callers.filter((c) => typeof c === "string")
+        : fallback.callers;
+    return {
+        name,
+        type: entity?.entityType ?? "",
+        props,
+        root: asString(props.root) ?? fallback.root,
+        address: qualifiedAddress(asString(props.address) ?? fallback.address, callers),
+        ...(asString(props.mode) ? { mode: asString(props.mode) } : {}),
+    };
+}
+/** One root's reader: `init`, then `show` over state, then address matching. */
+function adapter(root, cwd, deps) {
+    const where = cwd ? { cwd } : {};
+    let dir;
+    return {
+        async bind() {
+            // `init` first: `show` against an uninitialized root reports no state at
+            // all, which would read as "everything is absent", the exact failure
+            // the tri-state exists to prevent.
+            const initialized = await deps.init({ root, ...where });
+            dir = initialized.dir;
+            const shown = await deps.show({ root, ...where });
+            dir = shown.dir;
+            return indexStateResources(shown.json);
+        },
+        classifyBindFailure(err) {
+            const message = err instanceof Error ? err.message.split("\n")[0] : String(err);
+            return {
+                reason: "read-failed",
+                detail: `terraform.roots.${root}${dir ? ` (${dir})` : ""}: ${message}`,
+            };
+        },
+        async read(index, entity) {
+            const { address } = entity;
+            const queried = `terraform show -json (root "${root}", address "${address}")`;
+            if (entity.type === RESOURCE_TYPE || entity.type === DATA_TYPE) {
+                const row = index.rows.get(address);
+                if (!row)
+                    return { absent: true, queried };
+                return {
+                    present: {
+                        type: entity.type,
+                        physicalId: row.id ?? address,
+                        status: row.mode ?? "managed",
+                        ownership: classifyStateOwnership(address, index),
+                        attributes: {
+                            address,
+                            root,
+                            ...(row.type ? { resourceType: row.type } : {}),
+                            ...(row.mode ? { mode: row.mode } : {}),
+                            ...(row.providerName ? { provider: row.providerName } : {}),
+                        },
+                    },
+                    queried,
+                };
+            }
+            if (entity.type === MODULE_TYPE) {
+                if (!moduleIsLive(address, index))
+                    return { absent: true, queried };
+                // The state has resources under this module but no row for the block
+                // itself, so state membership, which is the whole ownership channel
+                // here, has nothing to say about it. See the module doc.
+                return {
+                    present: {
+                        type: entity.type,
+                        physicalId: address,
+                        status: "module",
+                        ownership: classifyStateOwnership(address, index),
+                        attributes: { address, root },
+                    },
+                    queried,
+                };
+            }
+            return {
+                unobserved: {
+                    reason: "unsupported-kind",
+                    detail: `${entity.type} has no row in terraform state: only resource and data blocks do`,
+                },
+                queried,
+            };
+        },
+    };
+}
+/**
+ * Observe every declared terraform entity, one `init` + `show` per configured
+ * root. Roots are read independently, so a broken backend on one never
+ * un-observes another (`mergeObservations`).
+ */
+export async function describeResources(options, deps = REAL_DEPS) {
+    const byRoot = new Map();
+    const rootless = [];
+    for (const name of options.entityNames) {
+        const declared = declaredOf(name, options.entities.get(name));
+        if (!declared.root) {
+            rootless.push(declared);
+            continue;
+        }
+        const bucket = byRoot.get(declared.root);
+        if (bucket)
+            bucket.push(declared);
+        else
+            byRoot.set(declared.root, [declared]);
+    }
+    const parts = [];
+    const notes = [];
+    // Which of the two reads answered, per entity (#2267). Filled for every
+    // entity of the root before the read runs, so the answer is on the wire
+    // whatever the verdict came back as: present, absent, or not-observed. A
+    // renderer joins observations to nodes, and painting `terraform show -json`
+    // over state the same green as a live read of the account is the drift lie
+    // an overlay exists to prevent.
+    const sources = {};
+    for (const [root, declared] of byRoot) {
+        // One fact decides the whole read, and the parse already recorded it on
+        // every entity of the root (#2103). A root is live when its binary is
+        // choudoufu AND it declares an estate, so a single entity carrying
+        // `mode: "live"` settles it for the root.
+        const live = declared.some((entity) => entity.mode === "live");
+        for (const entity of declared)
+            sources[entity.name] = live ? "live" : "state";
+        if (live) {
+            notes.push(`terraform.roots.${root} is a live root: ownership came from choudoufu's tofu-estate/tofu-address markers via \`live-plan -json\`, not from a state file`);
+        }
+        const read = live
+            ? await observeEntities(declared, liveAdapter(root, options.cwd, deps))
+            : await observeEntities(declared, adapter(root, options.cwd, deps));
+        parts.push(normalizeObservation(read));
+    }
+    const merged = mergeObservations(parts);
+    merged.notes.push(...notes);
+    const resources = { ...merged.resources };
+    const unobserved = { ...merged.unobserved };
+    // An entity carrying no root came from somewhere other than `buildRoots()`;
+    // there is no state file to look it up in, and saying so is not absence.
+    for (const entity of rootless) {
+        unobserved[entity.name] = {
+            ...(entity.type ? { type: entity.type } : {}),
+            reason: "unsupported-kind",
+            detail: "no `terraform.roots` entry on this entity, so there is no root module state to read it from",
+        };
+    }
+    if (options.owned) {
+        for (const [name, meta] of Object.entries(merged.resources)) {
+            if (meta.ownership === "owned")
+                continue;
+            delete resources[name];
+            unobserved[name] = {
+                type: meta.type,
+                reason: "filtered",
+                detail: `this address read \`${meta.ownership ?? "unknown"}\` on the root's ownership channel (its state file, or its live markers) and --owned was requested`,
+                ...(merged.queried[name] ? { queried: merged.queried[name] } : {}),
+            };
+        }
+    }
+    return observation(resources, unobserved, merged.queried, merged.notes, undefined, sources);
+}