@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/dist/describe-resources.js

@@ -120,6 +120,14 @@
  * 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`.
+ * The precedence is core's `TERRAFORM_INSTANCE_ROLLUP` and the rollup is
+ * core's `rollupInstances` (`@intentius/chant/instance-nodes`, #4454), the
+ * one place it is written.
+ *
+ * The block's verdict is not the whole answer. A present block also carries
+ * each instance's own verdict on `instances`, keyed as Terraform prints it
+ * (`[0]`, `["a"]`), which the live graph draws as an instance node under the
+ * block node (#4454). The state read does the same with the rows it found.
  *
  * ## What is readable at all
  *
@@ -195,6 +203,31 @@
  * The cost is two refreshes of the estate per read, run one after the other
  * so they never share the root's cache file.
  *
+ * ## Engine facts on a live root (#4528)
+ *
+ * After `live-plan -json` answers, the same document is handed to `choudoufu
+ * live-graph -json -from-plan=<file>` (choudoufu#2285), which builds the
+ * root's graph from the configuration and that file alone: no second live
+ * read, so the facts and the verdicts above come from one refresh (choudoufu
+ * #1014, the #4520 ruling Q3). `<file>` is the `<root>.live-plan.json`
+ * written under {@link TERRAFORM_LIVE_PLAN_DIR_ENV} when the caller asked
+ * for it, and otherwise a copy in a temporary directory removed afterwards.
+ *
+ * The document's node ids are choudoufu's addresses (the ruling's Q2). A
+ * block node maps to its entity with {@link entityKeyFor}; an instance node
+ * (`instanceOf` set) maps to its block's entity, and its facts go on that
+ * block's `instances` entry of the same address, from which core's
+ * `observedInstanceNodeId` draws the instance node. Each node's `facts` land
+ * on `ResourceMetadata.facts` or `InstanceObservation.facts`, and edges with
+ * a grain land on the observation's `edges`, endpoints mapped the same way
+ * ({@link readEngineGraph}). Facts are never read for a decision: ownership
+ * and the change set keep reading the verdicts above.
+ *
+ * A choudoufu without the command, older than
+ * `MIN_CHOUDOUFU_GRAPH_VERSION`, answers with a usage error: `facts` stay
+ * absent, the root gets one note, and the rest of the read is unchanged. Any
+ * other failure of the graph read degrades the same way, with its own note.
+ *
  * ## Nothing from `values` is surfaced
  *
  * A state row's `values` are the resource's full attribute set, secrets
@@ -204,16 +237,20 @@
  * `id`, which is the physical id every observation carries.
  */
 import { mergeObservations, normalizeObservation, observation, observeEntities, } from "@intentius/chant/observation";
-import { mkdirSync, writeFileSync } from "node:fs";
+import { observedInstanceNodeId, rollupInstances, terraformInstancePath, TERRAFORM_INSTANCE_ROLLUP, } from "@intentius/chant/instance-nodes";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { isAbsolute, join } from "node:path";
-import { choudoufuLiveLs, choudoufuLivePlanDocument, terraformInit, terraformPlanRead, terraformShow, TerraformPlanReadError, } from "./op/activities/terraform.js";
+import { choudoufuLiveGraph, choudoufuLiveLs, choudoufuLivePlanDocument, MIN_CHOUDOUFU_GRAPH_VERSION, terraformInit, terraformPlanRead, terraformShow, TerraformPlanReadError, } from "./op/activities/terraform.js";
 import { blockAddressOf, indexPlan, planAttributesFor, plannedAttributesFor } from "./plan-observation.js";
+import { LIVE_PLAN_OMISSION_REASONS, readsAsCredentials } from "./live-plan-reasons.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";
+export { LIVE_PLAN_OMISSION_REASONS } from "./live-plan-reasons.js";
 function asRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value)
         ? value
@@ -273,12 +310,26 @@ export function indexStateResources(showJson) {
 export function classifyStateOwnership(address, index) {
     return index.rows.has(address) ? "owned" : "unknown";
 }
+/**
+ * True when `instance` is the module call `address` itself or sits beneath it,
+ * at any instance key. `address` is a declared module address with no keys
+ * (`module.app`, `module.outer.module.inner`); a state or live-plan address
+ * carries them (`module.app[0]`, `module.outer["a"].module.inner[1].aws_eip.x`),
+ * so the keys come off before the prefix test (#4513).
+ */
+function underModule(instance, address) {
+    const block = blockAddressOf(instance);
+    return block === address || block.startsWith(`${address}.`);
+}
 /** True when the state carries at least one resource beneath `module.<name>`. */
 function moduleIsLive(address, index) {
-    if (index.modules.has(address))
-        return true;
+    // A keyed call's child_modules[] entries are `module.app[0]`, never
+    // `module.app`, and so are its rows' prefixes (#4513).
+    for (const module of index.modules)
+        if (underModule(module, address))
+            return true;
     for (const key of index.rows.keys())
-        if (key.startsWith(`${address}.`))
+        if (underModule(key, address))
             return true;
     return false;
 }
@@ -370,39 +421,6 @@ export function indexLivePlan(document) {
     ].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";
@@ -416,11 +434,15 @@ function omissionVerdict(row) {
  * #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}[`));
+    // `blockAddressOf` strips every key, so an instance under an expanded
+    // module call (`module.app[0].aws_eip.pool[1]`) is the block's too (#4488).
+    return index.addresses.filter((a) => a === address || a.startsWith(`${address}[`) || blockAddressOf(a) === 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}[`));
+    // Keys stripped first, so a nested call under a keyed one
+    // (`module.outer[0].module.inner["a"].…`) is a member too (#4513).
+    return index.addresses.filter((a) => underModule(a, address));
 }
 /**
  * Classify one instance address against the document, `unowned[]` first: a
@@ -459,6 +481,53 @@ export function classifyLiveInstance(address, index) {
     }
     return { kind: "absent" };
 }
+/**
+ * Where one instance address of the declared block `address` sits: its own
+ * key and the expanded module path (`@intentius/chant/instance-nodes`), or
+ * undefined when it is the block's unexpanded address or another block's.
+ * An instance under an expanded module call carries `scope` (#4488), so the
+ * live graph draws it under the same id the declared graph lists.
+ */
+function instanceKeyAndScope(address, instance) {
+    if (instance === address || blockAddressOf(instance) !== address)
+        return undefined;
+    const path = terraformInstancePath(instance);
+    if (!path)
+        return undefined;
+    return { ...(path.key !== undefined ? { key: path.key } : {}), ...(path.scope !== undefined ? { scope: path.scope } : {}) };
+}
+/**
+ * Each instance's own verdict (#4454), keyed as Terraform prints it, for the
+ * block's `instances`. An instance under an expanded module call carries its
+ * module path as `scope` (#4488) and its own key when the block is expanded too.
+ */
+function liveInstanceObservations(address, instances, verdicts) {
+    const out = [];
+    instances.forEach((a, i) => {
+        const at = instanceKeyAndScope(address, a);
+        if (at === undefined)
+            return;
+        const v = verdicts[i];
+        switch (v.kind) {
+            case "owned":
+                out.push({ ...at, address: a, verdict: "present", ownership: "owned", status: "bound", ...(v.row.identity ? { physicalId: v.row.identity } : {}) });
+                break;
+            case "foreign":
+                out.push({ ...at, address: a, verdict: "present", ownership: "foreign", status: "unowned", ...(v.row.identity ? { physicalId: v.row.identity } : {}) });
+                break;
+            case "adoptable":
+                out.push({ ...at, address: a, verdict: "present", ownership: "unknown", status: "adoptable", ...(v.row.identity ? { physicalId: v.row.identity } : {}) });
+                break;
+            case "absent":
+                out.push({ ...at, address: a, verdict: "absent" });
+                break;
+            case "unobserved":
+                out.push({ ...at, address: a, verdict: "not-observed", reason: v.reason, detail: v.detail });
+                break;
+        }
+    });
+    return out;
+}
 /**
  * The declared block's verdict, aggregated over its instances in the
  * precedence the module doc states: not-observed, then foreign, then
@@ -473,16 +542,20 @@ function readLiveResource(entity, index, root, queried) {
         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)
+    const expanded = instances.length > 1 || instances[0] !== address;
+    if (expanded)
         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 perInstance = expanded ? liveInstanceObservations(address, instances, verdicts) : [];
+    const withInstances = perInstance.length > 0 ? { instances: perInstance } : {};
+    const top = rollupInstances(verdicts, TERRAFORM_INSTANCE_ROLLUP);
+    if (top?.kind === "unobserved") {
+        return { unobserved: { reason: top.reason, detail: top.detail }, queried };
     }
-    const foreign = verdicts.find((v) => v.kind === "foreign");
-    if (foreign && foreign.kind === "foreign") {
+    const foreign = top;
+    if (foreign?.kind === "foreign") {
         return {
             present: {
+                ...withInstances,
                 type: entity.type,
                 physicalId: foreign.row.identity ?? address,
                 status: "unowned",
@@ -496,8 +569,8 @@ function readLiveResource(entity, index, root, queried) {
             queried,
         };
     }
-    const adoptable = verdicts.find((v) => v.kind === "adoptable");
-    if (adoptable && adoptable.kind === "adoptable") {
+    const adoptable = top;
+    if (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
@@ -505,6 +578,7 @@ function readLiveResource(entity, index, root, queried) {
         // surfaced, because nothing was read off this resource: it carries none.
         return {
             present: {
+                ...withInstances,
                 type: entity.type,
                 physicalId: adoptable.row.identity ?? address,
                 status: "adoptable",
@@ -526,13 +600,14 @@ function readLiveResource(entity, index, root, queried) {
             queried,
         };
     }
-    const owned = verdicts.filter((v) => v.kind === "owned");
-    if (owned.length === 0)
+    if (top?.kind !== "owned")
         return { absent: true, queried };
+    const owned = verdicts.filter((v) => v.kind === "owned");
     const sources = [...new Set(owned.map((v) => v.row.source ?? "unknown"))].sort();
     const byMarker = sources.length === 1 && sources[0] === "marker";
     return {
         present: {
+            ...withInstances,
             type: entity.type,
             physicalId: owned.length === 1 ? (owned[0].row.identity ?? address) : address,
             status: "bound",
@@ -572,17 +647,23 @@ export const TERRAFORM_LIVE_PLAN_DIR_ENV = "CHANT_TERRAFORM_LIVE_PLAN_DIR";
 export function livePlanDocumentFile(root) {
     return `${root.replace(/[^A-Za-z0-9._-]/g, "_")}.live-plan.json`;
 }
-/** Write a live root's document where {@link TERRAFORM_LIVE_PLAN_DIR_ENV} asks, if it asks. */
+/**
+ * Write a live root's document where {@link TERRAFORM_LIVE_PLAN_DIR_ENV} asks,
+ * if it asks. The path written, or undefined when nothing was.
+ */
 function handLivePlanDocument(root, json) {
     const out = process.env[TERRAFORM_LIVE_PLAN_DIR_ENV];
     if (!out || !isAbsolute(out))
-        return;
+        return undefined;
     try {
         mkdirSync(out, { recursive: true });
-        writeFileSync(join(out, livePlanDocumentFile(root)), JSON.stringify(json));
+        const file = join(out, livePlanDocumentFile(root));
+        writeFileSync(file, JSON.stringify(json));
+        return file;
     }
     catch {
         // Best effort: the read's answer does not depend on the copy.
+        return undefined;
     }
 }
 /**
@@ -590,15 +671,20 @@ function handLivePlanDocument(root, json) {
  * the document. `terraform show` is never run here, and there is no state
  * file to run it over.
  */
-function liveAdapter(root, cwd, deps) {
+function liveAdapter(root, cwd, deps, handoff = {}) {
     const where = cwd ? { cwd } : {};
     let dir;
     return {
         async bind() {
             const planned = await deps.livePlan({ root, ...where });
             dir = planned.dir;
-            handLivePlanDocument(root, planned.json);
-            return indexLivePlan(planned.json);
+            const file = handLivePlanDocument(root, planned.json);
+            const index = indexLivePlan(planned.json);
+            handoff.json = planned.json;
+            handoff.estate = planned.estate ?? index.estate;
+            if (file)
+                handoff.file = file;
+            return index;
         },
         classifyBindFailure(err) {
             const message = err instanceof Error ? err.message.split("\n")[0] : String(err);
@@ -651,6 +737,189 @@ function liveAdapter(root, cwd, deps) {
         },
     };
 }
+const GRAINS = new Set(["block", "instance", "property"]);
+const OWNERSHIPS = new Set(["bound", "unowned", "pending", "foreign"]);
+const OWNED_BY = new Set(["marker", "record", "name"]);
+/**
+ * One node's `facts`, keeping only the fields of chant's `EngineFacts` and
+ * only values of the shape it declares. Undefined when nothing is left.
+ */
+function engineFactsOf(value) {
+    const f = asRecord(value);
+    const out = {};
+    const ownership = asString(f.ownership);
+    if (ownership && OWNERSHIPS.has(ownership))
+        out.ownership = ownership;
+    const ownedBy = asString(f.ownedBy);
+    if (ownedBy && OWNED_BY.has(ownedBy))
+        out.ownedBy = ownedBy;
+    const markers = asRecord(f.markers);
+    const encoding = asString(markers.encoding);
+    const source = asString(markers.source);
+    if ((encoding === "plain" || encoding === "escaped" || encoding === "digest") && (source === "live" || source === "record")) {
+        out.markers = {
+            ...(asString(markers.owner) ? { owner: asString(markers.owner) } : {}),
+            ...(asString(markers.address) ? { address: asString(markers.address) } : {}),
+            encoding,
+            source,
+        };
+    }
+    const cloudIds = asArray(f.cloudIds)
+        .map((c) => ({ kind: asString(asRecord(c).kind), value: asString(asRecord(c).value) }))
+        .filter((c) => c.value !== undefined && ["import-id", "arn", "provider-id", "self-link", "k8s-uid"].includes(c.kind ?? ""));
+    if (cloudIds.length > 0)
+        out.cloudIds = cloudIds;
+    const history = asRecord(f.recordVersions);
+    if (typeof history.kept === "boolean") {
+        out.recordVersions = {
+            kept: history.kept,
+            versions: asArray(history.versions).flatMap((v) => {
+                const r = asRecord(v);
+                const id = asString(r.id);
+                const writtenAt = asString(r.writtenAt);
+                return id && writtenAt ? [{ id, writtenAt, current: r.current === true, deleted: r.deleted === true }] : [];
+            }),
+        };
+    }
+    const observedAt = asString(f.observedAt);
+    if (observedAt)
+        out.observedAt = observedAt;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Read an engine graph document (`choudoufu live-graph -json`, chant#4527's
+ * schema) for one root into chant's id space. Node ids are choudoufu's
+ * addresses (the #4520 ruling, Q2): a block node is the entity
+ * {@link entityKeyFor} names; an instance node (`instanceOf`) belongs to its
+ * block's entity, and as an edge endpoint it is the live instance node id
+ * core's `observedInstanceNodeId` gives. A node with no address (an estate
+ * the configuration reads, `estate:<name>`) has no chant entity, so its
+ * edges are left out. Edges keep their grain; one without a grain is left out.
+ *
+ * Throws when the document is not an engine graph document.
+ */
+export function readEngineGraph(root, document) {
+    const doc = asRecord(document);
+    const engineGraph = asRecord(asRecord(doc.meta).engineGraph);
+    if (doc.version !== 1 || engineGraph.format !== 1 || !Array.isArray(doc.nodes)) {
+        throw new Error("not an engine graph document (want GraphIR version 1 with meta.engineGraph format 1)");
+    }
+    const blocks = new Map();
+    const instances = new Map();
+    const nodeIds = new Map();
+    for (const entry of doc.nodes) {
+        const node = asRecord(entry);
+        const id = asString(node.id);
+        const address = asString(asRecord(node.attrs).address);
+        if (!id || !address)
+            continue;
+        const facts = engineFactsOf(node.facts);
+        const instanceOf = asString(node.instanceOf);
+        if (instanceOf) {
+            const block = entityKeyFor(root, instanceOf);
+            const key = asString(node.instanceKey);
+            const scope = asString(node.instanceScope);
+            const liveId = observedInstanceNodeId(block, {
+                address: id,
+                ...(key !== undefined ? { key } : {}),
+                ...(scope !== undefined ? { scope } : {}),
+            });
+            if (liveId)
+                nodeIds.set(id, liveId);
+            if (facts) {
+                let byAddress = instances.get(block);
+                if (!byAddress)
+                    instances.set(block, (byAddress = new Map()));
+                byAddress.set(id, facts);
+            }
+            continue;
+        }
+        const key = entityKeyFor(root, id);
+        nodeIds.set(id, key);
+        if (facts)
+            blocks.set(key, facts);
+    }
+    const edges = [];
+    const seen = new Set();
+    for (const entry of asArray(doc.edges)) {
+        const edge = asRecord(entry);
+        const grain = asString(edge.grain);
+        if (!grain || !GRAINS.has(grain))
+            continue;
+        const from = nodeIds.get(asString(edge.from) ?? "");
+        const to = nodeIds.get(asString(edge.to) ?? "");
+        if (!from || !to || from === to)
+            continue;
+        const viaAttr = asString(edge.viaAttr);
+        const key = `${from}\0${to}\0${viaAttr ?? ""}\0${grain}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        edges.push({ from, to, kind: "ref", ...(viaAttr ? { viaAttr } : {}), grain: grain });
+    }
+    return { blocks, instances, edges };
+}
+/**
+ * `resources` with {@link readEngineGraph}'s facts on them: a block's on
+ * `ResourceMetadata.facts`, an instance's on its `instances` entry of the
+ * same address. Nothing else changes, and nothing is added for an entity the
+ * read did not return.
+ */
+export function withEngineFacts(resources, read) {
+    const out = {};
+    for (const [name, meta] of Object.entries(resources)) {
+        const facts = read.blocks.get(name);
+        const byAddress = read.instances.get(name);
+        const instances = byAddress && meta.instances
+            ? meta.instances.map((inst) => {
+                const f = byAddress.get(inst.address);
+                return f ? { ...inst, facts: f } : inst;
+            })
+            : meta.instances;
+        out[name] = {
+            ...meta,
+            ...(facts ? { facts } : {}),
+            ...(instances ? { instances } : {}),
+        };
+    }
+    return out;
+}
+/**
+ * Run `choudoufu live-graph -json -from-plan=<file>` over the document a
+ * live root's bind handed off, and read it (#4528). Never throws: facts are
+ * extra, so a failure is a note and no facts.
+ */
+async function engineGraphFor(root, cwd, deps, handoff) {
+    if (!deps.liveGraph || handoff.json === undefined)
+        return {};
+    let scratch;
+    try {
+        let file = handoff.file;
+        if (!file) {
+            scratch = mkdtempSync(join(tmpdir(), "chant-live-graph-"));
+            file = join(scratch, livePlanDocumentFile(root));
+            writeFileSync(file, JSON.stringify(handoff.json));
+        }
+        const graph = await deps.liveGraph({ root, ...(cwd ? { cwd } : {}), fromPlan: file, ...(handoff.estate ? { estate: handoff.estate } : {}) });
+        if (!graph.supported) {
+            return {
+                note: `terraform.roots.${root}: engine facts are absent: this choudoufu has no \`live-graph -from-plan\` ` +
+                    `(${graph.detail}), which needs v${MIN_CHOUDOUFU_GRAPH_VERSION} or later; the rest of the read is unchanged`,
+            };
+        }
+        return { read: readEngineGraph(root, graph.json) };
+    }
+    catch (err) {
+        const message = (err instanceof Error ? err.message : String(err)).split("\n")[0];
+        return {
+            note: `terraform.roots.${root}: engine facts are absent: \`choudoufu live-graph -json -from-plan\` failed (${message}); the rest of the read is unchanged`,
+        };
+    }
+    finally {
+        if (scratch)
+            rmSync(scratch, { recursive: true, force: true });
+    }
+}
 /** Parse a `live-ls -json` document. A missing section reads as empty, never as a throw. */
 export function readLiveLs(document) {
     const doc = asRecord(document);
@@ -731,7 +1000,8 @@ export function ambientKinds() {
     return [RESOURCE_TYPE];
 }
 /**
- * Every live root the project declares, in config order. Reads the project
+ * Every live root the project declares, in config order, leaving out a
+ * `signalOnly` one (#4484). Reads the project
  * config the same way the activities do, so `terraform.roots` is read once
  * and the same answer reaches both.
  */
@@ -748,6 +1018,9 @@ export async function liveRootNames(cwd) {
         return [];
     const live = [];
     for (const [name, root] of Object.entries(namespace.roots ?? {})) {
+        // A `signalOnly` root (#4484) is another project's: it only brings this one into a change.
+        if (root.signalOnly === true)
+            continue;
         const estate = detectLiveEstate(resolve(projectRoot, root.dir));
         if (estate !== undefined)
             live.push({ root: name, estate });
@@ -875,6 +1148,7 @@ const REAL_DEPS = {
     show: terraformShow,
     livePlan: choudoufuLivePlanDocument,
     liveLs: choudoufuLiveLs,
+    liveGraph: choudoufuLiveGraph,
     planRead: terraformPlanRead,
 };
 /**
@@ -965,6 +1239,22 @@ function blockRows(address, index) {
         return [exact];
     return [...index.rows.values()].filter((row) => blockAddressOf(row.address) === address);
 }
+/**
+ * Each row of an expanded block as an instance (#4454), keyed as Terraform
+ * prints it. A state row is a recorded instance, owned by membership. A row
+ * under an expanded module call carries its module path as `scope`, as on
+ * the live read (#4488).
+ */
+function stateInstanceObservations(address, rows) {
+    const out = [];
+    for (const r of rows) {
+        const at = instanceKeyAndScope(address, r.address);
+        if (at === undefined)
+            continue;
+        out.push({ ...at, address: r.address, verdict: "present", ownership: "owned", status: r.mode ?? "managed", ...(r.id ? { physicalId: r.id } : {}) });
+    }
+    return out.sort((a, b) => a.address.localeCompare(b.address));
+}
 /**
  * One declared entity against a state index: the state read's whole verdict,
  * and the plan depth's too, since a plan's `prior_state` is the same shape.
@@ -973,14 +1263,18 @@ function blockRows(address, index) {
 function readStateEntity(index, entity, root, queried, extra) {
     const { address } = entity;
     if (entity.type === RESOURCE_TYPE || entity.type === DATA_TYPE) {
-        // The exact row first, which is the state read's rule since #2087; the
-        // plan depth also finds a `count` or `for_each` block by its instances.
-        const rows = extra ? blockRows(address, index) : index.rows.get(address) ? [index.rows.get(address)] : [];
+        // The exact row first, which is the state read's rule since #2087, then
+        // a `count` or `for_each` block by its instances: the plan depth did
+        // that from the start, and the state read does since #4454, which is
+        // what gives a drift row for `aws_eip.pool[0]` a block to roll up to.
+        const rows = blockRows(address, index);
         if (rows.length === 0)
             return { absent: true, queried };
         const row = rows[0];
+        const instances = stateInstanceObservations(address, rows);
         return {
             present: {
+                ...(instances.length > 0 ? { instances } : {}),
                 type: entity.type,
                 physicalId: rows.length === 1 ? (row.id ?? address) : address,
                 status: row.mode ?? "managed",
@@ -1125,9 +1419,9 @@ function planAdapter(root, cwd, deps, outcome) {
  * read, unchanged, with the plan's attributes added to every block it bound.
  * See "On a live root" in the module doc.
  */
-function livePlanDepthAdapter(root, cwd, deps, outcome) {
+function livePlanDepthAdapter(root, cwd, deps, outcome, handoff = {}) {
     const where = cwd ? { cwd } : {};
-    const live = liveAdapter(root, cwd, deps);
+    const live = liveAdapter(root, cwd, deps, handoff);
     const planRead = deps.planRead ?? terraformPlanRead;
     const firstLine = (err) => (err instanceof Error ? err.message : String(err)).split("\n")[0];
     let command = "";
@@ -1241,6 +1535,17 @@ export async function describeResources(options, deps = REAL_DEPS) {
     // an overlay exists to prevent.
     const sources = {};
     const rootReads = {};
+    const edges = [];
+    // A live root's observation with the engine graph's facts and edges on it (#4528).
+    const withEngineGraph = async (root, handoff, observed) => {
+        const graph = await engineGraphFor(root, options.cwd, deps, handoff);
+        if (graph.note)
+            notes.push(graph.note);
+        if (!graph.read)
+            return observed;
+        edges.push(...graph.read.edges);
+        return { ...observed, resources: withEngineFacts(observed.resources, graph.read) };
+    };
     const depthOf = byRoot.size > 0 ? await observeDepths(options, notes) : () => "state";
     for (const [root, declared] of byRoot) {
         // One fact decides the whole read, and the parse already recorded it on
@@ -1255,19 +1560,22 @@ export async function describeResources(options, deps = REAL_DEPS) {
                 // Both reads (#4371): `live-plan` for ownership, the plan for the
                 // attributes on what it bound. `sources` is known only after the read.
                 const outcome = { answered: "live", note: "" };
-                const read = await observeEntities(declared, livePlanDepthAdapter(root, options.cwd, deps, outcome));
+                const handoff = {};
+                const read = await observeEntities(declared, livePlanDepthAdapter(root, options.cwd, deps, outcome, handoff));
                 for (const entity of declared)
                     sources[entity.name] = outcome.answered;
                 if (outcome.read)
                     rootReads[`terraform.roots.${root}`] = outcome.read;
                 if (outcome.note)
                     notes.push(outcome.note);
-                parts.push(normalizeObservation(read));
+                parts.push(await withEngineGraph(root, handoff, normalizeObservation(read)));
                 continue;
             }
             for (const entity of declared)
                 sources[entity.name] = "live";
-            parts.push(normalizeObservation(await observeEntities(declared, liveAdapter(root, options.cwd, deps))));
+            const handoff = {};
+            const read = await observeEntities(declared, liveAdapter(root, options.cwd, deps, handoff));
+            parts.push(await withEngineGraph(root, handoff, normalizeObservation(read)));
             continue;
         }
         if (depth === "plan") {
@@ -1319,5 +1627,5 @@ export async function describeResources(options, deps = REAL_DEPS) {
     }
     // A planned create's plan attributes (#4372) ride beside the verdict, never
     // in `resources`: the block stays absent.
-    return observation(resources, unobserved, merged.queried, merged.notes, undefined, sources, merged.annotations, rootReads);
+    return observation(resources, unobserved, merged.queried, merged.notes, undefined, sources, merged.annotations, rootReads, edges);
 }