@intentius/chant-lexicon-terraform 0.59.0 → 0.61.0

package/src/composites/terraform-adopt-op.acceptance.test.ts

@@ -5,11 +5,12 @@
  * `terraform-adopt-op.test.ts` next door proves the shape chant emits.
  * `choudoufu.test.ts` proves the activities' contract against a stubbed child
  * process. This proves the shape does the thing: create an unmarked VPC
- * directly against choudoufu's pinned emulator, so it is a live resource this
- * estate does not own at an identity this root's configuration declares; run
- * the Ledger step and expect exactly one adoptable match with the two marker
- * values on it; run the Adopt step and let it write them; re-plan and expect
- * the estate to own the same VPC, with nothing left adoptable.
+ * directly against choudoufu's pinned emulator at the cidr this root declares,
+ * so it is a live resource this estate does not own and the sweep can match to
+ * a declaration by content; run the Ledger step and expect exactly one
+ * adoptable match with the two marker values on it; run the Adopt step and let
+ * it write them; re-plan and expect the estate to own the same VPC, with
+ * nothing left adoptable.
  *
  * The Op's phases are not run through `runOpLocally` here, deliberately.
  * `TerraformAdoptOp` always emits a gate — adoption moves the estate's
@@ -20,38 +21,39 @@
  * hand-off, which is the part a real binary can falsify. `choudoufu.acceptance.test.ts` takes the same approach for the same
  * reason.
  *
- * ## Why this still skips on choudoufu v0.14.0
+ * ## What this suite needed, and when it arrived
  *
- * Not #894 any more. v0.14.0 (choudoufu PR 915) made `live-plan -json`
- * reachable on a configuration that names its own estate, and this suite was
- * run against it on 2026-09-07 for the first time. It got as far as the
- * document and stopped there: `ledger.adoptions` came back empty, because the
- * #788 document carries no adoptable-by-content section at all.
+ * It had never passed on any binary until choudoufu v0.15.0.
  *
  * The document's `unowned[]` is the resources found at an identity the
- * configuration itself declares. A `aws_cloudwatch_log_group` has one (its
- * name is in the block), so an unmarked live one comes back in `unowned[]`
- * with `adopt_tofu_estate`/`adopt_tofu_address` on it, which is exactly what
- * `../__fixtures__/live-plan.json` recorded and what `readAdoptionLedger`
- * reads. An `aws_vpc` has none: EC2 assigns the id, so the document reports
- * `omissions[].reason = "NEEDS_DISCOVERY"` and leaves `unowned[]` empty. The
- * VPC is matched instead by choudoufu's content matcher during the
- * estate-wide unclaimed sweep, and that match is printed only in the human
- * render's "Adoptable" section. `views.LivePlanDocument` has no field for it,
- * `-adoption-only` is refused alongside `-json` ("-adoption-only and -json
- * cannot be combined"), and `TOFU_LIVE_COLLECT_UNCLAIMED=1` on the `-json`
- * run makes no difference: the text render then prints "Adoptable: 1 live
- * resource matches a declared resource" and the document beside it still says
- * `"unowned": []`.
+ * configuration itself declares. An `aws_cloudwatch_log_group` has one (its
+ * name is in the block), so an unmarked live one comes back there with
+ * `adopt_tofu_estate`/`adopt_tofu_address` on it. An `aws_vpc` has none: EC2
+ * assigns the id, so the document reports `omissions[].reason =
+ * "NEEDS_DISCOVERY"` and `unowned[]` stays empty. The live VPC is matched
+ * instead by choudoufu's content matcher during the estate-wide sweep, and
+ * until v0.15.0 that match was printed only in the human `-adoption-only`
+ * render, which choudoufu refuses alongside `-json`. chant #2168 ran this
+ * block against v0.14.0 on 2026-09-07, reached the document and stopped, with
+ * `ledger.adoptions` empty, and filed
+ * [choudoufu #962](https://github.com/INTENTIUS/choudoufu/issues/962).
  *
- * So `choudoufuLivePlan` cannot produce a ledger for a provider-assigned
- * identity on any binary that exists today, and this suite is what would
- * prove it can. Filed upstream as
- * [choudoufu #962](https://github.com/INTENTIUS/choudoufu/issues/962); the
- * measurements are there and on chant #2168.
+ * choudoufu PR 963 answered it: the document now carries the match as an
+ * `adoptable[]` section, with `swept[]` beside it, and each row carries the
+ * two marker values, the arguments the match rested on, and the tagging
+ * command. `choudoufuLivePlan` puts `TOFU_LIVE_COLLECT_UNCLAIMED=1` on the
+ * `-json` run under `adoptionOnly` so the section is populated at all
+ * (choudoufu's `-json` run asks no sweep of its own), and
+ * `readAdoptionLedger` reads both sections. Which is what this suite exists
+ * to falsify, so the gate that named #962 is gone and only the three ordinary
+ * dependencies remain.
  *
- * The gate below names that, alongside the three ordinary dependencies: a
- * `choudoufu`, an `aws` CLI, and the emulator's endpoint.
+ * The fixture stays an `aws_vpc` deliberately. A log group would make the
+ * block pass off `unowned[]` alone and would stop it proving the
+ * content-matcher path, which is the only thing it exists to prove.
+ *
+ * The gate below is those three: a `choudoufu`, an `aws` CLI, and the
+ * emulator's endpoint.
  *
  * Gating copied from `./terraform-apply-op.acceptance.test.ts` (`onPath`),
  * which in turn copies `lexicons/k3s/src/serializer.acceptance.test.ts`'s
@@ -59,7 +61,7 @@
  * failing when the real dependency is absent.
  *
  * `../__fixtures__/ACCEPTANCE.md` records what this block has last passed
- * against, which is still nothing, and why the reason changed.
+ * against, and the whole history of why it could not before.
  */
 
 import { execSync } from "node:child_process";
@@ -78,18 +80,6 @@ function onPath(cmd: string): boolean {
   }
 }
 
-/**
- * `true` while `live-plan -json`'s document carries no adoptable-by-content
- * section, so a provider-assigned identity like an `aws_vpc` never reaches
- * `readAdoptionLedger`. Filed upstream as
- * [choudoufu #962](https://github.com/INTENTIUS/choudoufu/issues/962), with
- * the measurements against the v0.14.0 release binary on 2026-09-07; flip to
- * `false` when a choudoufu release puts the content matcher's "Adoptable"
- * rows in the document, either in `unowned[]` or in a sibling array.
- * choudoufu #894, which gated this block before, is fixed and gone.
- */
-const CHOUDOUFU_ADOPTABLE_NOT_IN_DOCUMENT = true;
-
 const emulatorEndpoint = process.env.CHOUDOUFU_EMULATOR_ENDPOINT;
 
 const skipReason = !onPath("choudoufu")
@@ -98,11 +88,7 @@ const skipReason = !onPath("choudoufu")
     ? "no aws CLI on PATH (the unmarked resource is created with it, and adopted through it)"
     : !emulatorEndpoint
       ? "CHOUDOUFU_EMULATOR_ENDPOINT is not set (bring up choudoufu's `just smoke` emulator stack and export it)"
-      : CHOUDOUFU_ADOPTABLE_NOT_IN_DOCUMENT
-        ? "choudoufu#962: live-plan -json's document carries no adoptable-by-content section, so the " +
-          "fixture's unmarked aws_vpc reaches omissions[NEEDS_DISCOVERY] and never unowned[]; " +
-          "measured on choudoufu v0.14.0"
-        : "";
+      : "";
 
 const FIXTURE = join(import.meta.dirname, "..", "__fixtures__", "live-adopt");
 const ESTATE = "chant-adopt-fixture";

package/src/composites/terraform-apply-op.acceptance.test.ts

@@ -160,9 +160,11 @@ describe.skipIf(skipReason !== "")(
  *     the approval artifact
  *     ([choudoufu #878](https://github.com/INTENTIUS/choudoufu/issues/878),
  *     PR 889), before which `plan -out` was refused under a live block and
- *     this Op could not be built the way it is built now, and v0.14.0 moved
+ *     this Op could not be built the way it is built now; v0.14.0 moved
  *     the floor again for the document the other two Ops read
  *     ([choudoufu #894](https://github.com/INTENTIUS/choudoufu/issues/894)),
+ *     and v0.15.0 moved it once more for that document's adoptable section
+ *     ([choudoufu #962](https://github.com/INTENTIUS/choudoufu/issues/962)),
  *   - `CHOUDOUFU_EMULATOR_ENDPOINT` unset (bring up choudoufu's `just smoke`
  *     docker compose stack and export `http://localhost:<mapped port>`).
  *
@@ -218,7 +220,7 @@ const liveSkipReason: string = !onPath("choudoufu")
   : choudoufuVersion === undefined
     ? "the choudoufu on PATH reports no release version (a dev build), so the approval artifact cannot be assumed"
     : isOlderVersion(choudoufuVersion, MIN_CHOUDOUFU_VERSION)
-      ? `choudoufu ${choudoufuVersion} is older than v${MIN_CHOUDOUFU_VERSION}, the lexicon's floor (choudoufu #878's approval artifact in v0.13.0, #894's -json document in v0.14.0)`
+      ? `choudoufu ${choudoufuVersion} is older than v${MIN_CHOUDOUFU_VERSION}, the lexicon's floor (choudoufu #878's approval artifact in v0.13.0, #894's -json document in v0.14.0, #962's adoptable section in v0.15.0)`
       : !emulatorEndpoint
         ? "CHOUDOUFU_EMULATOR_ENDPOINT is not set (bring up choudoufu's `just smoke` emulator stack and export it)"
         : "";

package/src/describe-resources.live.test.ts

@@ -8,9 +8,10 @@
  *
  * The live side is real too. `src/__fixtures__/live-plan.json` and
  * `src/__fixtures__/live-ls.json` were recorded from that same configuration
- * by a choudoufu built from source, running against choudoufu's own pinned
- * floci emulator; `src/__fixtures__/live-estate/README.md` is the recording
- * log, including the two ways the recording could not be a chant live root.
+ * by the choudoufu v0.15.0 release binary, running against choudoufu's own
+ * pinned floci emulator; `src/__fixtures__/live-estate/README.md` is the
+ * recording log, including what the recording still cannot do as a chant live
+ * root would and what the v0.15.0 re-recording (#2241) changed.
  *
  * Nothing here runs choudoufu: the activities are injected, and the stock
  * `show` activity throws if the reader ever reaches for it.
@@ -102,6 +103,10 @@ function deps(overrides?: Partial<TerraformReadDeps>): TerraformReadDeps {
       adoptions: [],
       contested: [],
       ambiguous: 0,
+      // The sweep's type list (#2241), likewise a projection this reader never
+      // touches: `describeResources` asks for no sweep, so a real document off
+      // this path carries an empty one too.
+      swept: [],
       // Plan change counts (#2106), likewise unread here.
       adds: 0,
       changes: 0,
@@ -154,6 +159,20 @@ describe("the live fixture root is what buildRoots() calls live (#2103)", () =>
 describe("indexLivePlan (#2104)", () => {
   const index = indexLivePlan(PLAN);
 
+  it("indexes the adoptable section and the sweep's type list", () => {
+    expect([...index.adoptable.keys()]).toEqual(["aws_vpc.adoptable"]);
+    expect(index.adoptable.get("aws_vpc.adoptable")).toMatchObject({
+      type: "aws_vpc",
+      adoptEstate: ESTATE,
+      adoptAddress: "aws_vpc.adoptable",
+      matched: [{ attribute: "cidr_block", value: "10.88.0.0/16" }],
+    });
+    // The types the sweep listed in full. An empty `adoptable` is read against
+    // this: nothing found, or nothing asked.
+    expect(index.swept).toContain("aws_vpc");
+    expect(indexLivePlan({}).swept).toEqual([]);
+  });
+
   it("indexes every section of the recorded document by address", () => {
     expect(index.estate).toBe(ESTATE);
     expect([...index.bound.keys()].sort()).toEqual([
@@ -215,7 +234,7 @@ describe("terraform describeResources on a live root (#2104)", () => {
     const { resources } = normalizeObservation(await describeResources(await options(), deps()));
     expect(resources["estate/aws_vpc.main"]).toMatchObject({
       type: "Terraform::Resource",
-      physicalId: "vpc-c1733cf7",
+      physicalId: "vpc-dc8685c5",
       status: "bound",
       ownership: "owned",
       marker: { stack: ESTATE },
@@ -260,6 +279,23 @@ describe("terraform describeResources on a live root (#2104)", () => {
     expect(adoptable.marker).toBeUndefined();
   });
 
+  it("reports a content-matched VPC adoptable, with the cidr the sweep matched on", async () => {
+    // The declaration carries no identity at all (EC2 assigns a VPC id), so
+    // the document's omission for it says NEEDS_DISCOVERY, which on its own
+    // reads as unsupported-kind. The `adoptable[]` section is what turns that
+    // into a real verdict (choudoufu #962, chant #2241).
+    const { resources } = normalizeObservation(await describeResources(await options(), deps()));
+    const vpc = resources["estate/aws_vpc.adoptable"];
+    expect(vpc).toMatchObject({ status: "adoptable", ownership: "unknown" });
+    expect(vpc.physicalId).toMatch(/^vpc-/);
+    expect(vpc.attributes).toMatchObject({
+      adoptTofuEstate: ESTATE,
+      adoptTofuAddress: "aws_vpc.adoptable",
+      matchedOn: ["cidr_block=10.88.0.0/16"],
+    });
+    expect(vpc.marker).toBeUndefined();
+  });
+
   it("reports an unowned resource at a declared identity foreign, naming who holds it", async () => {
     const { resources } = normalizeObservation(await describeResources(await options(), deps()));
     const held = resources["estate/aws_cloudwatch_log_group.held_elsewhere"];
@@ -310,6 +346,42 @@ describe("terraform describeResources on a live root (#2104)", () => {
   });
 });
 
+describe("which read answered, on a live root (#2267)", () => {
+  it("says `live` for every declared entity of the root, whatever the verdict was", async () => {
+    // The sibling assertion on a stock root is in `./describe-resources.test.ts`.
+    // Together they are the whole of the claim: a renderer joining observations
+    // to nodes can tell a read of the account from a read of a state file, and
+    // so never paints the second one as drift.
+    const opts = await options();
+    const observed = normalizeObservation(await describeResources(opts, deps()));
+    expect(Object.keys(observed.sources).sort()).toEqual([...opts.entityNames].sort());
+    for (const value of Object.values(observed.sources)) expect(value).toBe("live");
+  });
+
+  it("still says `live` when live-plan failed", async () => {
+    const opts = await options();
+    const observed = normalizeObservation(
+      await describeResources(
+        opts,
+        deps({
+          livePlan: (async () => {
+            throw new Error("no valid credential sources found");
+          }) as TerraformReadDeps["livePlan"],
+        }),
+      ),
+    );
+    for (const value of Object.values(observed.sources)) expect(value).toBe("live");
+  });
+
+  it("is the same value the declared entity already carries on props.mode", async () => {
+    const opts = await options();
+    const { sources } = normalizeObservation(await describeResources(opts, deps()));
+    for (const [name, entity] of opts.entities) {
+      expect(sources[name]).toBe((entity.props as { mode?: string }).mode);
+    }
+  });
+});
+
 describe("terraform describeResources live-root failures (#2104)", () => {
   it("reports every declared entity of the root not-observed, never absent", async () => {
     const opts = await options();

package/src/describe-resources.test.ts

@@ -264,6 +264,41 @@ describe("terraform describeResources (#2087)", () => {
   });
 });
 
+describe("which read answered, on a stock root (#2267)", () => {
+  it("says `state` for every declared entity of the root, whatever the verdict was", async () => {
+    const opts = await options();
+    const observed = normalizeObservation(await describeResources(opts, deps()));
+    // Present, absent and unsupported-kind all appear in this fixture, and the
+    // claim is about the read that was attempted, not about what it found.
+    expect(Object.keys(observed.sources).sort()).toEqual([...opts.entityNames].sort());
+    for (const value of Object.values(observed.sources)) expect(value).toBe("state");
+    // `null_resource.third` is declared and not in state, so it is OBSERVED-ABSENT:
+    // in neither map, and this is the only place it can say how it was read.
+    expect(observed.resources["app/null_resource.third"]).toBeUndefined();
+    expect(observed.unobserved["app/null_resource.third"]).toBeUndefined();
+    expect(observed.sources["app/null_resource.third"]).toBe("state");
+  });
+
+  it("still says `state` when the read failed, since a failure is a state read that failed", async () => {
+    const opts = await options();
+    const observed = normalizeObservation(
+      await describeResources(opts, deps({ show: failing("Error acquiring the state lock") })),
+    );
+    expect(Object.keys(observed.sources).sort()).toEqual([...opts.entityNames].sort());
+    for (const value of Object.values(observed.sources)) expect(value).toBe("state");
+  });
+
+  it("is the same value the declared entity already carries on props.mode", async () => {
+    // The documented join key (#2267): one fact decides both, so a consumer
+    // holding the declared graph and no observation can label from `mode`.
+    const opts = await options();
+    const { sources } = normalizeObservation(await describeResources(opts, deps()));
+    for (const [name, entity] of opts.entities) {
+      expect(sources[name]).toBe((entity.props as { mode?: string }).mode);
+    }
+  });
+});
+
 describe("terraform describeResources failed reads (#2087)", () => {
   it("a failed show reports every declared entity of that root read-failed, naming the root", async () => {
     const opts = await options();

package/src/describe-resources.ts

@@ -13,6 +13,34 @@
  * 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
@@ -54,6 +82,7 @@
  * | `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
@@ -282,6 +311,27 @@ export interface LivePlanUnownedRow {
   adoptAddress?: string;
 }
 
+/**
+ * One `adoptable[]` entry: a live resource the estate-wide sweep matched to a
+ * declared instance by content rather than by reading a declared identity
+ * (choudoufu #962). The declaration names no identity at all, so this is the
+ * only row the document has for it and the paired omission says
+ * `NEEDS_DISCOVERY`.
+ *
+ * Same fields as {@link LivePlanUnownedRow} minus `heldBy`, which cannot
+ * apply: a row here carries no marker for any estate, or the sweep would have
+ * called it foreign instead of unclaimed.
+ */
+export interface LivePlanAdoptableRow {
+  addr: string;
+  type?: string;
+  identity?: string;
+  adoptEstate?: string;
+  adoptAddress?: string;
+  /** `matched[]`: the arguments the declaration and the live resource agreed on exactly. */
+  matched?: Array<{ attribute: string; value: string }>;
+}
+
 /** A `live-plan -json` document, indexed by declared instance address. */
 export interface LivePlanIndex {
   /** `estate`: the estate every section was computed against. */
@@ -289,6 +339,13 @@ export interface LivePlanIndex {
   bound: Map<string, LivePlanBoundRow>;
   omissions: Map<string, LivePlanOmissionRow>;
   unowned: Map<string, LivePlanUnownedRow>;
+  adoptable: Map<string, LivePlanAdoptableRow>;
+  /**
+   * `swept[]`: the resource types the estate-wide sweep listed in full. Empty
+   * on every observation read, which asks for no sweep, so an empty
+   * `adoptable` beside it says nothing was asked rather than nothing found.
+   */
+  swept: string[];
   /** Every address any section named, so a block can find its own instances. */
   addresses: string[];
   /** `diagnostics[]` summaries, for the observation's run-level notes. */
@@ -307,6 +364,8 @@ export function indexLivePlan(document: unknown): LivePlanIndex {
     bound: new Map(),
     omissions: new Map(),
     unowned: new Map(),
+    adoptable: new Map(),
+    swept: asArray(doc.swept).filter((t): t is string => typeof t === "string"),
     addresses: [],
     diagnostics: [],
   };
@@ -348,6 +407,24 @@ export function indexLivePlan(document: unknown): LivePlanIndex {
     });
   }
 
+  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);
@@ -355,7 +432,12 @@ export function indexLivePlan(document: unknown): LivePlanIndex {
   }
 
   index.addresses = [
-    ...new Set([...index.bound.keys(), ...index.omissions.keys(), ...index.unowned.keys()]),
+    ...new Set([
+      ...index.bound.keys(),
+      ...index.omissions.keys(),
+      ...index.unowned.keys(),
+      ...index.adoptable.keys(),
+    ]),
   ].sort();
   return index;
 }
@@ -419,7 +501,7 @@ function liveModuleMembers(address: string, index: LivePlanIndex): string[] {
 /** One instance's verdict, before a block aggregates its instances. */
 type InstanceVerdict =
   | { kind: "owned"; row: LivePlanBoundRow }
-  | { kind: "adoptable"; row: LivePlanUnownedRow }
+  | { kind: "adoptable"; row: LivePlanAdoptableRow }
   | { kind: "foreign"; row: LivePlanUnownedRow }
   | { kind: "absent" }
   | { kind: "unobserved"; reason: UnobservedReason; detail: string };
@@ -428,6 +510,11 @@ type InstanceVerdict =
  * 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).
  */
 function classifyLiveInstance(address: string, index: LivePlanIndex): InstanceVerdict {
   const unowned = index.unowned.get(address);
@@ -440,6 +527,11 @@ function classifyLiveInstance(address: string, index: LivePlanIndex): InstanceVe
   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);
@@ -516,6 +608,13 @@ function readLiveResource(
           ...(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,
@@ -1091,12 +1190,20 @@ export async function describeResources(
 
   const parts = [];
   const notes: string[] = [];
+  // 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: Record<string, string> = {};
   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`,
@@ -1136,5 +1243,5 @@ export async function describeResources(
     }
   }
 
-  return observation(resources, unobserved, merged.queried, merged.notes);
+  return observation(resources, unobserved, merged.queried, merged.notes, undefined, sources);
 }