@intentius/chant-lexicon-terraform 0.124.51 → 0.124.54

package/src/describe-resources.ts

@@ -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
@@ -223,11 +256,23 @@ import {
   type UnobservedReason,
 } from "@intentius/chant/observation";
 import type { OwnershipMarker } from "@intentius/chant/ownership";
-import { mkdirSync, writeFileSync } from "node:fs";
+import {
+  observedInstanceNodeId,
+  rollupInstances,
+  terraformInstancePath,
+  TERRAFORM_INSTANCE_ROLLUP,
+  type InstanceObservation,
+} from "@intentius/chant/instance-nodes";
+import type { EdgeGrain, EngineFacts } from "@intentius/chant/engine-facts";
+import type { IREdge } from "@intentius/chant/graph-ir";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import {
+  choudoufuLiveGraph,
   choudoufuLiveLs,
   choudoufuLivePlanDocument,
+  MIN_CHOUDOUFU_GRAPH_VERSION,
   terraformInit,
   terraformPlanRead,
   terraformShow,
@@ -235,6 +280,7 @@ import {
 } from "./op/activities/terraform";
 import { blockAddressOf, indexPlan, planAttributesFor, plannedAttributesFor, type PlanIndex } from "./plan-observation";
 import type { TerraformObserveDepth } from "./config";
+import { LIVE_PLAN_OMISSION_REASONS, readsAsCredentials } from "./live-plan-reasons";
 import { DATA_TYPE, MODULE_TYPE, RESOURCE_TYPE, callersOfKey } from "./hcl/parse";
 
 // The channel keys live in their own module so `plugin.ts` can declare
@@ -242,6 +288,7 @@ import { DATA_TYPE, MODULE_TYPE, RESOURCE_TYPE, callersOfKey } from "./hcl/parse
 // this is where they are used.
 export { TERRAFORM_STATE_OWNERSHIP_KEYS } from "./state-ownership";
 export { TERRAFORM_LIVE_MARKER_KEYS } from "./live-ownership";
+export { LIVE_PLAN_OMISSION_REASONS } from "./live-plan-reasons";
 
 /** One row out of `values.root_module.resources[]`, at any module depth. */
 export interface StateResourceRow {
@@ -329,10 +376,24 @@ export function classifyStateOwnership(address: string, index: StateIndex): "own
   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: string, address: string): boolean {
+  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: string, index: StateIndex): boolean {
-  if (index.modules.has(address)) return true;
-  for (const key of index.rows.keys()) if (key.startsWith(`${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 (underModule(key, address)) return true;
   return false;
 }
 
@@ -500,43 +561,6 @@ export function indexLivePlan(document: unknown): LivePlanIndex {
   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: Readonly<Record<string, UnobservedReason | "absent">> = {
-  // 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: string): boolean {
-  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: LivePlanOmissionRow): UnobservedReason | "absent" {
   const mapped = LIVE_PLAN_OMISSION_REASONS[row.reason] ?? "read-failed";
@@ -550,14 +574,16 @@ function omissionVerdict(row: LivePlanOmissionRow): UnobservedReason | "absent"
  * #2360), which places the same blocks against the same document.
  */
 export function instancesOf(address: string, index: LivePlanIndex): string[] {
-  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: string, index: LivePlanIndex): string[] {
-  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));
 }
 
 /** One instance's verdict, before a block aggregates its instances. */
@@ -608,6 +634,52 @@ export function classifyLiveInstance(address: string, index: LivePlanIndex): Ins
   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: string, instance: string): { key?: string; scope?: string } | undefined {
+  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: string, instances: readonly string[], verdicts: readonly InstanceVerdict[]): InstanceObservation[] {
+  const out: InstanceObservation[] = [];
+  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
@@ -627,17 +699,22 @@ function readLiveResource(
 
   const verdicts = instances.map((a) => classifyLiveInstance(a, index));
   const attributes: Record<string, unknown> = { address, root, estate: index.estate };
-  if (instances.length > 1 || instances[0] !== address) attributes.instances = instances;
+  const expanded = instances.length > 1 || instances[0] !== address;
+  if (expanded) attributes.instances = instances;
+  const perInstance = expanded ? liveInstanceObservations(address, instances, verdicts) : [];
+  const withInstances = perInstance.length > 0 ? { instances: perInstance } : {};
 
-  const unobserved = verdicts.find((v) => v.kind === "unobserved");
-  if (unobserved && unobserved.kind === "unobserved") {
-    return { unobserved: { reason: unobserved.reason, detail: unobserved.detail }, queried };
+  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",
@@ -652,8 +729,8 @@ function readLiveResource(
     };
   }
 
-  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
@@ -661,6 +738,7 @@ function readLiveResource(
     // surfaced, because nothing was read off this resource: it carries none.
     return {
       present: {
+        ...withInstances,
         type: entity.type,
         physicalId: adoptable.row.identity ?? address,
         status: "adoptable",
@@ -683,13 +761,14 @@ function readLiveResource(
     };
   }
 
+  if (top?.kind !== "owned") return { absent: true, queried };
   const owned = verdicts.filter((v) => v.kind === "owned") as Array<{ kind: "owned"; row: LivePlanBoundRow }>;
-  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: {
+      ...withInstances,
       type: entity.type,
       physicalId: owned.length === 1 ? (owned[0]!.row.identity ?? address) : address,
       status: "bound",
@@ -732,24 +811,46 @@ export function livePlanDocumentFile(root: string): string {
   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. */
-function handLivePlanDocument(root: string, json: unknown): void {
+/**
+ * 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: string, json: unknown): string | undefined {
   const out = process.env[TERRAFORM_LIVE_PLAN_DIR_ENV];
-  if (!out || !isAbsolute(out)) return;
+  if (!out || !isAbsolute(out)) 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;
   }
 }
 
+/**
+ * What a live root's bind leaves for the engine graph read (#4528): the
+ * `live-plan -json` document it indexed, the file it was handed to under
+ * {@link TERRAFORM_LIVE_PLAN_DIR_ENV} if any, and the estate.
+ */
+interface LivePlanHandoff {
+  json?: unknown;
+  file?: string;
+  estate?: string;
+}
+
 /**
  * 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: string, cwd: string | undefined, deps: TerraformReadDeps): ObserverAdapter<LivePlanIndex> {
+function liveAdapter(
+  root: string,
+  cwd: string | undefined,
+  deps: TerraformReadDeps,
+  handoff: LivePlanHandoff = {},
+): ObserverAdapter<LivePlanIndex> {
   const where = cwd ? { cwd } : {};
   let dir: string | undefined;
 
@@ -757,8 +858,12 @@ function liveAdapter(root: string, cwd: string | undefined, deps: TerraformReadD
     async bind(): Promise<LivePlanIndex> {
       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) {
@@ -817,6 +922,204 @@ function liveAdapter(root: string, cwd: string | undefined, deps: TerraformReadD
   };
 }
 
+/* ─────────────────────── engine facts (#4528) ──────────────────────────── */
+
+/** {@link readEngineGraph}'s answer: facts and edges keyed in chant's id space. */
+export interface EngineGraphRead {
+  /** Facts of a block node, by entity key. */
+  blocks: Map<string, EngineFacts>;
+  /** Facts of an instance node, by its block's entity key, then by the instance address. */
+  instances: Map<string, Map<string, EngineFacts>>;
+  /** Edges with a grain, endpoints as live graph node ids. */
+  edges: IREdge[];
+}
+
+const GRAINS: ReadonlySet<string> = new Set<EdgeGrain>(["block", "instance", "property"]);
+const OWNERSHIPS: ReadonlySet<string> = new Set(["bound", "unowned", "pending", "foreign"]);
+const OWNED_BY: ReadonlySet<string> = 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: unknown): EngineFacts | undefined {
+  const f = asRecord(value);
+  const out: EngineFacts = {};
+  const ownership = asString(f.ownership);
+  if (ownership && OWNERSHIPS.has(ownership)) out.ownership = ownership as EngineFacts["ownership"];
+  const ownedBy = asString(f.ownedBy);
+  if (ownedBy && OWNED_BY.has(ownedBy)) out.ownedBy = ownedBy as EngineFacts["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 is NonNullable<EngineFacts["cloudIds"]>[number] =>
+      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: string, document: unknown): EngineGraphRead {
+  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<string, EngineFacts>();
+  const instances = new Map<string, Map<string, EngineFacts>>();
+  const nodeIds = new Map<string, string>();
+
+  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: IREdge[] = [];
+  const seen = new Set<string>();
+  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 as EdgeGrain });
+  }
+  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: Record<string, ResourceMetadata>,
+  read: EngineGraphRead,
+): Record<string, ResourceMetadata> {
+  const out: Record<string, ResourceMetadata> = {};
+  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: string,
+  cwd: string | undefined,
+  deps: TerraformReadDeps,
+  handoff: LivePlanHandoff,
+): Promise<{ read?: EngineGraphRead; note?: string }> {
+  if (!deps.liveGraph || handoff.json === undefined) return {};
+  let scratch: string | undefined;
+  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 });
+  }
+}
+
 /* ──────────────────── the estate beyond the declaration ─────────────────── */
 
 /** One `items[]` entry of a `live-ls -json` listing. */
@@ -944,7 +1247,8 @@ export interface LiveEstateOptions {
 }
 
 /**
- * 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.
  */
@@ -956,12 +1260,14 @@ export async function liveRootNames(cwd?: string): Promise<Array<{ root: string;
   const start = resolve(cwd ?? process.cwd());
   const { config, configPath } = await loadChantConfigUpward(start);
   const projectRoot = configPath ? dirname(configPath) : start;
-  const namespace = (config as { terraform?: { binary?: string; roots?: Record<string, { dir: string }> } })
+  const namespace = (config as { terraform?: { binary?: string; roots?: Record<string, { dir: string; signalOnly?: boolean }> } })
     .terraform;
   if (namespace?.binary !== "choudoufu") return [];
 
   const live: Array<{ root: string; estate: string }> = [];
   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 });
   }
@@ -1105,6 +1411,12 @@ export interface TerraformReadDeps {
   /** The document alone (chant #2498): this reader indexes it and never reads the human render. */
   livePlan: typeof choudoufuLivePlanDocument;
   liveLs: typeof choudoufuLiveLs;
+  /**
+   * The engine graph read on a live root (#4528). Optional so a test that
+   * never asks for facts need not stub it; omitted, no facts are read and no
+   * note is added.
+   */
+  liveGraph?: typeof choudoufuLiveGraph;
   /**
    * The plan depth's read (#4358). Optional so a test that never asks for the
    * plan depth need not stub it; omitted, the real activity runs.
@@ -1117,6 +1429,7 @@ const REAL_DEPS: TerraformReadDeps = {
   show: terraformShow,
   livePlan: choudoufuLivePlanDocument,
   liveLs: choudoufuLiveLs,
+  liveGraph: choudoufuLiveGraph,
   planRead: terraformPlanRead,
 };
 
@@ -1222,6 +1535,22 @@ function blockRows(address: string, index: StateIndex): StateResourceRow[] {
   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: string, rows: readonly StateResourceRow[]): InstanceObservation[] {
+  const out: InstanceObservation[] = [];
+  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.
@@ -1237,13 +1566,17 @@ function readStateEntity(
   const { address } = entity as TerraformDeclared;
 
   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",
@@ -1423,9 +1756,10 @@ function livePlanDepthAdapter(
   cwd: string | undefined,
   deps: TerraformReadDeps,
   outcome: { answered: LivePlanDepthAnswer; note: string; read?: RootRead },
+  handoff: LivePlanHandoff = {},
 ): ObserverAdapter<LivePlanDepthIndex> {
   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: unknown): string => (err instanceof Error ? err.message : String(err)).split("\n")[0]!;
   let command = "";
@@ -1571,6 +1905,15 @@ export async function describeResources(
   // an overlay exists to prevent.
   const sources: Record<string, string> = {};
   const rootReads: Record<string, RootRead> = {};
+  const edges: IREdge[] = [];
+  // A live root's observation with the engine graph's facts and edges on it (#4528).
+  const withEngineGraph = async (root: string, handoff: LivePlanHandoff, observed: ReturnType<typeof normalizeObservation>) => {
+    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" as const;
   for (const [root, declared] of byRoot) {
     // One fact decides the whole read, and the parse already recorded it on
@@ -1587,15 +1930,18 @@ export async function describeResources(
         // 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: LivePlanDepthAnswer; note: string; read?: RootRead } = { answered: "live", note: "" };
-        const read = await observeEntities(declared, livePlanDepthAdapter(root, options.cwd, deps, outcome));
+        const handoff: LivePlanHandoff = {};
+        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: LivePlanHandoff = {};
+      const read = await observeEntities(declared, liveAdapter(root, options.cwd, deps, handoff));
+      parts.push(await withEngineGraph(root, handoff, normalizeObservation(read)));
       continue;
     }
     if (depth === "plan") {
@@ -1646,5 +1992,5 @@ export async function describeResources(
 
   // 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);
 }