@intentius/chant 0.124.52 → 0.124.54

package/src/engine-facts.guard.test.ts

@@ -0,0 +1,111 @@
+// Guard (#4527, ruled on #4520 Q1): engine facts are for people and for
+// readers that show the graph, never for a decision. Nothing under a change
+// set, the lifecycle or an Op names `EngineFacts` or imports
+// ./engine-facts.ts, so a delete, a plan or a gate cannot start reading a
+// fact without this test failing. The only files let through are the ones
+// CARRIES_FACTS_ONLY names, each with its reason. `IRNode.ownership` and
+// `ResourceMetadata.ownership` keep feeding the painters and the change set.
+import { describe, it, expect } from "vitest";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const coreSrc = dirname(fileURLToPath(import.meta.url));
+const repo = resolve(coreSrc, "..", "..", "..");
+
+/** What a decision path must not contain: the type's name, or an import of its module. */
+const FORBIDDEN = [/\bEngineFacts\b/, /["'][^"']*\/engine-facts(?:\.ts|\.js)?["']/];
+
+/** The offending lines of one file's text, as `line: text`. */
+export function engineFactsUses(text: string): string[] {
+  const hits: string[] = [];
+  text.split("\n").forEach((line, i) => {
+    if (FORBIDDEN.some((re) => re.test(line))) hits.push(`${i + 1}: ${line.trim()}`);
+  });
+  return hits;
+}
+
+function walk(dir: string, out: string[] = []): string[] {
+  for (const name of readdirSync(dir)) {
+    if (name === "node_modules" || name === "dist") continue;
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) walk(path, out);
+    else if (/\.(?:ts|mts|tsx|mjs|js)$/.test(name)) out.push(path);
+  }
+  return out;
+}
+
+/**
+ * Files under a decision path that carry engine facts without deciding on
+ * them, by repo-relative path, each with why. Adding one needs the same
+ * check: read the file and confirm no create, delete, adopt, plan or gate
+ * choice reads a fact. A file that does decide on facts gets its code fixed,
+ * never an entry here.
+ */
+const CARRIES_FACTS_ONLY: Readonly<Record<string, string>> = {
+  // #4521: types a cloud listing into index nodes. It copies the listing's
+  // markers, cloud ids and observedAt into IRNode.facts and returns the node;
+  // nothing in it branches on a fact's value. Pure, no I/O, and nothing it
+  // returns is an Op, a change set or a gate.
+  "packages/core/src/lifecycle/type-listing.ts":
+    "#4521 index typing: copies listed facts into IRNode.facts for the index and decides nothing on them",
+};
+
+/** Every source file on a decision path: core's change set, lifecycle and Ops, and each lexicon's Ops and change-set files. */
+function decisionPathFiles(): string[] {
+  const files = new Set<string>();
+  for (const f of walk(join(coreSrc, "lifecycle"))) files.add(f);
+  for (const f of walk(join(coreSrc, "op"))) files.add(f);
+  for (const f of walk(coreSrc)) if (/(?:^|[\\/])change-set[^\\/]*$/.test(relative(coreSrc, f))) files.add(f);
+  const lexicons = join(repo, "lexicons");
+  for (const lexicon of readdirSync(lexicons)) {
+    const src = join(lexicons, lexicon, "src");
+    let isDir = false;
+    try {
+      isDir = statSync(src).isDirectory();
+    } catch {
+      continue;
+    }
+    if (!isDir) continue;
+    for (const f of walk(src)) {
+      const rel = relative(src, f);
+      if (/^op[\\/]/.test(rel) || /(?:^|[\\/])change-set[^\\/]*$/.test(rel)) files.add(f);
+    }
+  }
+  return [...files].sort();
+}
+
+describe("engine facts never reach a decision path (#4527)", () => {
+  it("scans the change set, the lifecycle and the Ops", () => {
+    const files = decisionPathFiles().map((f) => relative(repo, f));
+    expect(files).toContain("packages/core/src/change-set.ts");
+    expect(files).toContain("packages/core/src/lifecycle/change-set.ts");
+    expect(files.some((f) => f.startsWith("packages/core/src/op/"))).toBe(true);
+    expect(files.some((f) => /^lexicons\/[^/]+\/src\/op\//.test(f))).toBe(true);
+  });
+
+  it("no file there names EngineFacts or imports engine-facts", () => {
+    const offenders: string[] = [];
+    for (const file of decisionPathFiles()) {
+      if (relative(repo, file) in CARRIES_FACTS_ONLY) continue;
+      for (const hit of engineFactsUses(readFileSync(file, "utf-8"))) offenders.push(`${relative(repo, file)}:${hit}`);
+    }
+    expect(offenders).toEqual([]);
+  });
+
+  it("each exemption names a file on a decision path that still uses engine facts", () => {
+    const files = new Set(decisionPathFiles().map((f) => relative(repo, f)));
+    for (const [file, reason] of Object.entries(CARRIES_FACTS_ONLY)) {
+      expect(files.has(file), `${file} is not on a decision path; drop its exemption`).toBe(true);
+      expect(engineFactsUses(readFileSync(join(repo, file), "utf-8")).length, `${file} no longer uses engine facts; drop its exemption`).toBeGreaterThan(0);
+      expect(reason.trim()).not.toBe("");
+    }
+  });
+
+  it("catches a BREAK: an import of the type, of the module, or a use by name", () => {
+    expect(engineFactsUses('import type { EngineFacts } from "../engine-facts";')).toHaveLength(1);
+    expect(engineFactsUses('import * as f from "../engine-facts.ts";')).toHaveLength(1);
+    expect(engineFactsUses("const x: import('../graph-ir').IRNode['facts'] = y as EngineFacts;")).toHaveLength(1);
+    expect(engineFactsUses('import type { IRNode } from "../graph-ir";')).toEqual([]);
+  });
+});

package/src/engine-facts.test.ts

@@ -0,0 +1,178 @@
+// Engine facts on graph nodes and edge grain (#4527, designed on #4520).
+import { describe, it, expect } from "vitest";
+import { buildGraphIr, buildLiveGraphIr, entityFacts, sourceOverlayGraphs, type GraphIR, type LiveObservation } from "./graph-ir";
+import { DECLARABLE_MARKER, type Declarable } from "./declarable";
+import { ENGINE_FACTS_FLOOR, type EngineFacts } from "./engine-facts";
+import { NEXT_RELEASE } from "./release-floors";
+
+const facts: EngineFacts = {
+  ownership: "bound",
+  ownedBy: "marker",
+  markers: { owner: "web", address: "aws_s3_bucket.logs", encoding: "escaped", source: "live" },
+  cloudIds: [{ kind: "import-id", value: "web-logs" }],
+  observedAt: "2026-10-26T12:00:00Z",
+};
+
+describe("buildLiveGraphIr: engine facts (#4527)", () => {
+  it("copies ResourceMetadata.facts onto the node beside physicalId", () => {
+    const ir = buildLiveGraphIr([
+      { lexicon: "terraform", resources: { "aws_s3_bucket.logs": { type: "aws_s3_bucket", status: "present", physicalId: "web-logs", facts } } },
+    ]);
+    const node = ir.nodes[0]!;
+    expect(node.physicalId).toBe("web-logs");
+    expect(node.facts).toEqual(facts);
+  });
+
+  it("leaves IRNode.ownership to the metadata's own verdict, whatever the facts say", () => {
+    const ir = buildLiveGraphIr([
+      {
+        lexicon: "terraform",
+        resources: { q: { type: "aws_sqs_queue", status: "present", ownership: "unknown", facts: { ownership: "foreign" } } },
+      },
+    ]);
+    expect(ir.nodes[0]!.ownership).toBeUndefined();
+    expect(ir.nodes[0]!.facts).toEqual({ ownership: "foreign" });
+  });
+
+  it("adds no facts field when the observation has none", () => {
+    const ir = buildLiveGraphIr([{ lexicon: "aws", resources: { b: { type: "AWS::S3::Bucket", status: "CREATE_COMPLETE" } } }]);
+    expect("facts" in ir.nodes[0]!).toBe(false);
+  });
+
+  it("copies an instance's facts onto its instance node", () => {
+    const instanceFacts: EngineFacts = { ownership: "bound", ownedBy: "record", cloudIds: [{ kind: "import-id", value: "eipalloc-1" }] };
+    const ir = buildLiveGraphIr([
+      {
+        lexicon: "terraform",
+        resources: {
+          "aws_eip.pool": {
+            type: "aws_eip",
+            status: "present",
+            instances: [
+              { key: "[0]", address: "aws_eip.pool[0]", verdict: "present", physicalId: "eipalloc-0", facts: { ownership: "pending" } },
+              { key: "[1]", address: "aws_eip.pool[1]", verdict: "present", physicalId: "eipalloc-1", facts: instanceFacts },
+              { key: "[2]", address: "aws_eip.pool[2]", verdict: "present" },
+            ],
+          },
+        },
+      },
+    ]);
+    const byId = new Map(ir.nodes.map((n) => [n.id, n]));
+    expect(byId.get("aws_eip.pool[0]")!.facts).toEqual({ ownership: "pending" });
+    expect(byId.get("aws_eip.pool[1]")!.facts).toEqual(instanceFacts);
+    expect("facts" in byId.get("aws_eip.pool[2]")!).toBe(false);
+    expect("facts" in byId.get("aws_eip.pool")!).toBe(false);
+  });
+});
+
+describe("buildLiveGraphIr: edge grain (#4527)", () => {
+  const pair = {
+    lexicon: "pulumi",
+    resources: {
+      policy: { type: "aws:s3/bucketPolicy:BucketPolicy", status: "present" },
+      bucket: { type: "aws:s3/bucketV2:BucketV2", status: "present" },
+    },
+  } satisfies LiveObservation;
+
+  it("passes grain through unchanged", () => {
+    const ir = buildLiveGraphIr([{ ...pair, edges: [{ from: "policy", to: "bucket", kind: "ref", viaAttr: "dependencies", grain: "instance" }] }]);
+    expect(ir.edges).toEqual([{ from: "policy", to: "bucket", kind: "ref", viaAttr: "dependencies", grain: "instance" }]);
+  });
+
+  it("keeps two edges between the same pair that differ only in grain", () => {
+    const ir = buildLiveGraphIr([
+      {
+        ...pair,
+        edges: [
+          { from: "policy", to: "bucket", kind: "ref", viaAttr: "dependencies", grain: "instance" },
+          { from: "policy", to: "bucket", kind: "ref", viaAttr: "dependencies", grain: "block" },
+          { from: "policy", to: "bucket", kind: "ref", viaAttr: "dependencies" },
+        ],
+      },
+    ]);
+    expect(ir.edges.map((e) => e.grain)).toEqual([undefined, "block", "instance"]);
+  });
+
+  it("still dedupes edges with the same grain", () => {
+    const edge = { from: "policy", to: "bucket", kind: "ref" as const, viaAttr: "dependencies", grain: "instance" as const };
+    const ir = buildLiveGraphIr([{ ...pair, edges: [edge] }, { ...pair, edges: [edge] }]);
+    expect(ir.edges).toHaveLength(1);
+  });
+});
+
+describe("sourceOverlayGraphs: engine facts and grain (#4527)", () => {
+  const n = (id: string) => ({ id, kind: "aws_s3_bucket", lexicon: "terraform", attrs: {} });
+  const declared: GraphIR = { nodes: [n("aws_s3_bucket.logs"), n("aws_s3_bucket.planned")], edges: [], groups: {} };
+  const live: GraphIR = {
+    nodes: [
+      { ...n("aws_s3_bucket.logs"), physicalId: "web-logs", facts },
+      { ...n("aws_s3_bucket.stray"), facts: { ownership: "unowned" } },
+    ],
+    edges: [
+      { from: "aws_s3_bucket.stray", to: "aws_s3_bucket.logs", kind: "ref", viaAttr: "dependencies", grain: "block" },
+      { from: "aws_s3_bucket.stray", to: "aws_s3_bucket.logs", kind: "ref", viaAttr: "dependencies", grain: "instance" },
+    ],
+    groups: {},
+  };
+
+  it("carries the observed facts onto the managed declared node, as it does physicalId", () => {
+    const ir = sourceOverlayGraphs(declared, live);
+    const logs = ir.nodes.find((x) => x.id === "aws_s3_bucket.logs")!;
+    expect(logs.physicalId).toBe("web-logs");
+    expect(logs.facts).toEqual(facts);
+    expect("facts" in ir.nodes.find((x) => x.id === "aws_s3_bucket.planned")!).toBe(false);
+  });
+
+  it("keeps a foreign node's facts and both grains of its live edges", () => {
+    const ir = sourceOverlayGraphs(declared, live);
+    expect(ir.nodes.find((x) => x.id === "aws_s3_bucket.stray")!.facts).toEqual({ ownership: "unowned" });
+    expect(ir.edges.map((e) => e.grain).sort()).toEqual(["block", "instance"]);
+  });
+});
+
+describe("buildGraphIr: an entity's facts and reference grain (#4529)", () => {
+  // The shape the pulumi lexicon's member read gives a plunge member's entity.
+  function entity(type: string, references: unknown[], withFacts?: EngineFacts): Declarable {
+    const e = { lexicon: "pulumi", entityType: type, kind: "resource", props: {}, references, [DECLARABLE_MARKER]: true };
+    if (withFacts) Object.defineProperty(e, "facts", { value: withFacts, enumerable: false });
+    return e as unknown as Declarable;
+  }
+
+  it("copies an entity's facts onto its node, and keeps them out of attrs", () => {
+    const ir = buildGraphIr(new Map([["m/a", entity("aws:s3/bucket:Bucket", [], facts)]]));
+    expect(ir.nodes[0]!.facts).toEqual(facts);
+    expect(ir.nodes[0]!.attrs).toEqual({});
+  });
+
+  it("keeps an enumerable facts field out of attrs too", () => {
+    const e = { ...(entity("aws:s3/bucket:Bucket", []) as unknown as Record<string, unknown>), facts };
+    const ir = buildGraphIr(new Map([["m/a", e as unknown as Declarable]]));
+    expect(ir.nodes[0]!.facts).toEqual(facts);
+    expect(ir.nodes[0]!.attrs).toEqual({});
+  });
+
+  it("adds no facts field to an entity with none", () => {
+    expect(entityFacts(entity("x", []))).toBeUndefined();
+    expect("facts" in buildGraphIr(new Map([["m/a", entity("x", [])]])).nodes[0]!).toBe(false);
+  });
+
+  it("passes a reference's grain to its edge, and two grains between one pair are two edges", () => {
+    const ir = buildGraphIr(
+      new Map([
+        ["m/a", entity("x", [{ to: "m/b", viaAttr: "bucket", grain: "property" }, { to: "m/b", viaAttr: "bucket", grain: "instance" }, { to: "m/b", viaAttr: "dependencies" }])],
+        ["m/b", entity("y", [{ to: "m/a", viaAttr: "parent", grain: "sideways" }])],
+      ]),
+    );
+    expect(ir.edges.map((e) => [e.from, e.viaAttr, e.grain ?? null])).toEqual([
+      ["m/a", "bucket", "instance"],
+      ["m/a", "bucket", "property"],
+      ["m/a", "dependencies", null],
+      // A grain outside the three is not carried.
+      ["m/b", "parent", null],
+    ]);
+  });
+
+  it("names its floor as the next release", () => {
+    expect(ENGINE_FACTS_FLOOR).toBe(NEXT_RELEASE);
+  });
+});

package/src/engine-facts.ts

@@ -0,0 +1,154 @@
+/**
+ * Engine facts on graph nodes, and the engine graph document (#4527, designed
+ * on #4520 and ruled there 2026-10-26).
+ *
+ * An ownership engine (choudoufu, plunge) prints one JSON document per read:
+ * a `GraphIR` at version 1 whose `meta.engineGraph` says which engine read
+ * what, and whose nodes carry {@link EngineFacts} under `facts`. behold#1027
+ * loads it as it is; chant's terraform and pulumi lexicons read the same
+ * document onto `ResourceMetadata.facts`, which `buildLiveGraphIr` copies to
+ * the node.
+ *
+ * Facts are for people and for readers that show the graph. Nothing in chant
+ * decides from them: no change set, lifecycle step or Op imports this module
+ * (./engine-facts.guard.test.ts), and `IRNode.ownership` keeps its own meaning.
+ *
+ * The JSON Schema in ./graph-schema/graph.schema.json is generated from these
+ * types and ./lifecycle/index-document.ts (`npm run generate:graph-schema`).
+ */
+import type { GraphIR } from "./graph-ir";
+import { NEXT_RELEASE } from "./release-floors";
+
+/** The format of {@link EngineGraphMeta}. Moves only for a change a reader could not ignore. */
+export const ENGINE_GRAPH_FORMAT = 1;
+
+/**
+ * The first chant whose graph carries `nodes[].facts` and `edges[].grain`
+ * (#4527, #4529, #4528): a live read through an engine (the terraform
+ * lexicon's read of `choudoufu live-graph -json -from-plan`, which writes
+ * `ResourceMetadata.facts` and the observation's `edges`), and a plunge
+ * member's checked-in `engine-graph.json` in the pulumi lexicon's member
+ * read. A reader treats a graph from an older chant as having neither. The
+ * engine side's floor for the terraform read is that lexicon's
+ * `MIN_CHOUDOUFU_GRAPH_VERSION`.
+ */
+export const ENGINE_FACTS_FLOOR = NEXT_RELEASE;
+
+/** The marker values an engine read or recorded for one node. */
+export interface EngineMarkers {
+  /** The estate name, or plunge's `<project>/<stack>`. A digest under encoding `digest`. */
+  owner?: string;
+  /** The tofu-address value, or plunge's URN without stack and project. Same encoding rule as `owner`. */
+  address?: string;
+  /** How `owner` and `address` are written on the object. */
+  encoding: "plain" | "escaped" | "digest";
+  /** `live`: read off the live object. `record`: what the engine's record says it wrote. */
+  source: "live" | "record";
+}
+
+/** One cloud identifier of a node. */
+export interface EngineCloudId {
+  kind: "import-id" | "arn" | "provider-id" | "self-link" | "k8s-uid";
+  value: string;
+}
+
+/** One version of a node's record. No record values. */
+export interface EngineRecordVersion {
+  id: string;
+  /** ISO 8601 UTC. */
+  writtenAt: string;
+  current: boolean;
+  deleted: boolean;
+}
+
+/** The versions of a node's record, when the run asked for them (`-history`, `--versions`). */
+export interface EngineRecordVersions {
+  /** False for a store that replaces records in place (local, Kubernetes). */
+  kept: boolean;
+  /** Newest first. */
+  versions: EngineRecordVersion[];
+}
+
+/**
+ * What an ownership engine observed about one node (#4520). Never read for a
+ * decision. Every field is optional: one the engine cannot supply is absent,
+ * never guessed, and a reader shows it as unknown.
+ */
+export interface EngineFacts {
+  /** The engine's ownership verdict. A node built from configuration alone has none. */
+  ownership?: "bound" | "unowned" | "pending" | "foreign";
+  markers?: EngineMarkers;
+  /** What bound the node: a marker, the engine's record, or its name. */
+  ownedBy?: "marker" | "record" | "name";
+  /** The node's cloud ids. The first is the primary one and equals `physicalId` when both are set. */
+  cloudIds?: EngineCloudId[];
+  recordVersions?: EngineRecordVersions;
+  /** ISO 8601 UTC, when this node's live facts were read. */
+  observedAt?: string;
+}
+
+/**
+ * What an edge joins (#4520): two blocks, two instances, or a property of one
+ * instance to another. Absent on an edge whose source does not say.
+ */
+export type EdgeGrain = "block" | "instance" | "property";
+
+/** The engine that printed the document. */
+export interface EngineGraphEngine {
+  /** `choudoufu` or `plunge`. */
+  name: string;
+  version?: string;
+}
+
+/** What the read covered: a choudoufu estate or a plunge stack. */
+export type EngineGraphScope =
+  | { kind: "estate"; estate: string }
+  | { kind: "stack"; project: string; stack: string };
+
+/** The marker keys and encodings the engine passes into its sweep packages, printed once per document. */
+export interface EngineMarkerScheme {
+  ownerKey: string;
+  addressKey: string;
+  /** Keys a long value continues into (`tofu-slot`, `plunge-urn-2`). */
+  continuationKeys?: string[];
+  encoding: {
+    tags: "plain" | "escaped" | "digest";
+    labels: "plain" | "escaped" | "digest";
+  };
+}
+
+/** A node the engine could not describe, and why. */
+export interface EngineGraphGap {
+  address: string;
+  reason: string;
+  detail?: string;
+}
+
+/** `meta.engineGraph` on an engine graph document. */
+export interface EngineGraphMeta {
+  /** {@link ENGINE_GRAPH_FORMAT}. */
+  format: 1;
+  engine: EngineGraphEngine;
+  scope: EngineGraphScope;
+  /** ISO 8601 UTC, when the read started. Absent when nothing was read live. */
+  observedAt?: string;
+  markerScheme?: EngineMarkerScheme;
+  gaps?: EngineGraphGap[];
+}
+
+/** The open `meta` bag of an engine graph document, holding `engineGraph`. */
+export interface EngineGraphDocumentMeta {
+  engineGraph: EngineGraphMeta;
+  [key: string]: unknown;
+}
+
+/**
+ * The one JSON document `choudoufu live-graph -json` and `plunge graph --json`
+ * print. A `GraphIR` at version 1: node ids are the engine's own addresses
+ * (choudoufu's instance address, plunge's URN), and readers map them with
+ * `entityKeyFor`, `observedInstanceNodeId` and `pulumiNodeKey`.
+ */
+export interface EngineGraphDocument extends Omit<GraphIR, "version" | "meta"> {
+  version: 1;
+  meta: EngineGraphDocumentMeta;
+}

package/src/gated-waves-bundle.test.ts

@@ -47,6 +47,8 @@ describe("the gated-wave bundle", () => {
       "packages/core/src/gated-waves.ts",
       "packages/core/src/intrinsic.ts",
       "packages/core/src/lifecycle/plan-digest.ts",
+      // The next-release floor constant (#4480): no imports.
+      "packages/core/src/release-floors.ts",
     ]);
     expect(bytes).toBeLessThan(24 * 1024);
   });

package/src/graph-ir-live.test.ts

@@ -333,3 +333,95 @@ describe("observed edges (#1271)", () => {
     expect(ir.edges?.map((e) => e.from)).toEqual(["app-subnet", "web-vpc"]);
   });
 });
+
+// #4488: the live graph builds instance ids with the planned graph's rule
+// (#4486), so a live instance under an expanded module call lands on the
+// node the declared graph lists for it.
+describe("buildLiveGraphIr: instances under an expanded module call (#4488)", () => {
+  const block = "estate/module.app/aws_eip.pool";
+  const call = "estate/module.app";
+  const live = buildLiveGraphIr([
+    {
+      lexicon: "terraform",
+      resources: {
+        [block]: {
+          type: "resource",
+          status: "bound",
+          ownership: "owned",
+          instances: [
+            { key: "[0]", scope: "module.app[0]", address: "module.app[0].aws_eip.pool[0]", verdict: "present", ownership: "owned", status: "bound" },
+            { key: "[1]", scope: "module.app[1]", address: "module.app[1].aws_eip.pool[1]", verdict: "present", ownership: "owned", status: "bound" },
+            { key: "[0]", scope: "module.app[1]", address: "module.app[1].aws_eip.pool[0]", verdict: "absent" },
+          ],
+        },
+        "estate/module.app/aws_eip.single": {
+          type: "resource",
+          status: "bound",
+          ownership: "owned",
+          instances: [{ scope: "module.app[0]", address: "module.app[0].aws_eip.single", verdict: "present", ownership: "owned" }],
+        },
+        [call]: {
+          type: "module",
+          status: "bound",
+          ownership: "owned",
+          instances: [{ key: "[0]", address: "module.app[0]", verdict: "present", ownership: "owned" }],
+        },
+      },
+    },
+  ]);
+  const byId = new Map(live.nodes.map((n) => [n.id, n]));
+
+  it("puts the module key on the call segment and the block's own key at the end", () => {
+    const n = byId.get("estate/module.app[0]/aws_eip.pool[0]");
+    expect(n).toMatchObject({ instanceOf: block, instanceKey: "[0]", instanceScope: "module.app[0]", ownership: "owned" });
+    expect(byId.get("estate/module.app[1]/aws_eip.pool[1]")).toMatchObject({ instanceOf: block, instanceScope: "module.app[1]" });
+    expect(byId.has(`${block}[0]`)).toBe(false);
+  });
+
+  it("draws no node for an absent instance", () => {
+    expect(byId.has("estate/module.app[1]/aws_eip.pool[0]")).toBe(false);
+  });
+
+  it("leaves instanceKey off an instance only the module call expands", () => {
+    const n = byId.get("estate/module.app[0]/aws_eip.single")!;
+    expect(n.instanceOf).toBe("estate/module.app/aws_eip.single");
+    expect(n.instanceScope).toBe("module.app[0]");
+    expect(n.instanceKey).toBeUndefined();
+  });
+
+  it("keeps the <block><key> rule with no module call expanded", () => {
+    expect(byId.get("estate/module.app[0]")).toMatchObject({ instanceOf: call, instanceKey: "[0]" });
+    expect(byId.get("estate/module.app[0]")!.instanceScope).toBeUndefined();
+  });
+
+  it("matches the declared instance node in the overlay", () => {
+    const declared: GraphIR = {
+      nodes: [
+        { id: block, kind: "resource", lexicon: "terraform", attrs: {} },
+        { id: "estate/module.app[0]/aws_eip.pool[0]", kind: "resource", lexicon: "terraform", attrs: {}, instanceOf: block, instanceKey: "[0]", instanceScope: "module.app[0]" },
+        { id: "estate/module.app[1]/aws_eip.pool[0]", kind: "resource", lexicon: "terraform", attrs: {}, instanceOf: block, instanceKey: "[0]", instanceScope: "module.app[1]" },
+      ],
+      edges: [],
+      groups: {},
+    };
+    const out = new Map(overlayGraphs(live, declared).nodes.map((n) => [n.id, n.attrs._status]));
+    expect(out.get("estate/module.app[0]/aws_eip.pool[0]")).toBe("good");
+    expect(out.get("estate/module.app[1]/aws_eip.pool[0]")).toBe("accent");
+  });
+
+  it("keeps the member prefix in a workspace", () => {
+    const ws = buildLiveGraphIr([
+      {
+        lexicon: "terraform",
+        resources: {
+          [`net/${block}`]: {
+            type: "resource",
+            status: "bound",
+            instances: [{ key: "[2]", scope: "module.app[\"x\"]", address: "module.app[\"x\"].aws_eip.pool[2]", verdict: "present" }],
+          },
+        },
+      },
+    ]);
+    expect(ws.nodes.map((n) => n.id)).toContain('net/estate/module.app["x"]/aws_eip.pool[2]');
+  });
+});