@intentius/chant-lexicon-terraform 0.60.0 → 0.62.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";
@@ -67,6 +69,8 @@ import { cpSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterAll, describe, expect, it } from "vitest";
+import { loadActivities, loadProfiles, runOpLocally, type OpConfig } from "@intentius/chant/op";
+import { TerraformAdoptOp } from "./terraform-adopt-op";
 import { choudoufuAdopt, choudoufuLivePlan, terraformInit } from "../op/activities/terraform";
 
 function onPath(cmd: string): boolean {
@@ -78,18 +82,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 +90,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";
@@ -191,3 +179,66 @@ describe.skipIf(skipReason !== "")(
     );
   },
 );
+
+/**
+ * #2302: `TerraformAdoptOp` built with no Init phase reached its Ledger step
+ * with an empty `.terraform` on every checkout that had never run `init` —
+ * every fresh CI checkout, not a GitLab peculiarity. This drives the built Op
+ * itself through `runOpLocally`, the way `terraform-apply-op.acceptance.test.ts`
+ * does, over a project this test creates fresh and never initializes by hand:
+ * no `terraformInit` call anywhere in this block, unlike the suite above. The
+ * Op's own Init phase is what has to do that work, or the Ledger step fails
+ * the same way it failed in INTENTIUS/choudoufu#1026.
+ *
+ * `TerraformAdoptOp` gates unconditionally (no `gate: "never"`, unlike
+ * `TerraformApplyOp`), so a passing run here ends with `status: "gated"`
+ * right after the Ledger phase — "reaching its gate" is the pass, not a
+ * completed adoption. That is proof enough: the Ledger step needs the
+ * provider schema, and a run that reaches the gate is a run whose Ledger step
+ * already read it.
+ *
+ * Needs only a `choudoufu` on PATH and the emulator, not the `aws` CLI: this
+ * block creates no live resource and never reads `ledger.adoptions`, so a
+ * narrower gate than the suite above is correct instead of borrowed.
+ */
+const gateSkipReason = !onPath("choudoufu")
+  ? "no choudoufu binary on PATH"
+  : !emulatorEndpoint
+    ? "CHOUDOUFU_EMULATOR_ENDPOINT is not set (bring up choudoufu's `just smoke` emulator stack and export it)"
+    : "";
+
+describe.skipIf(gateSkipReason !== "")(
+  `TerraformAdoptOp reaches its gate on a checkout that has never run init${gateSkipReason ? ` (skipped: ${gateSkipReason})` : ""}`,
+  () => {
+    it(
+      "Init downloads the provider the Ledger step needs, and the run reaches its gate",
+      { timeout: 300_000 },
+      async () => {
+        const dir = project();
+
+        process.env.AWS_ENDPOINT_URL ??= emulatorEndpoint;
+        process.env.AWS_ACCESS_KEY_ID ??= "choudoufu-emulator";
+        process.env.AWS_SECRET_ACCESS_KEY ??= "choudoufu-emulator";
+        process.env.AWS_DEFAULT_REGION ??= "us-east-1";
+
+        // No `terraformInit` call here. `dir/root` is a fresh checkout: no
+        // `.terraform`, only the fixture's own `main.tf` and
+        // `estate.chdf.hcl` — exactly what `git clone` leaves behind, since
+        // `.terraform` is what every `.gitignore` in this ecosystem excludes.
+        const { op } = TerraformAdoptOp({ name: "gate-check-adopt", root: "estate", cwd: dir });
+
+        const activities = await loadActivities(["terraform"]);
+        const result = await runOpLocally((op as unknown as { props: OpConfig }).props, activities, await loadProfiles());
+
+        expect(result.status).toBe("gated");
+        expect(result.records.map((r) => `${r.phase}:${r.status}`)).toEqual([
+          "Init:ok",
+          "Check:ok",
+          "Ledger:ok",
+          "Gate:skipped",
+          "Adopt:skipped",
+        ]);
+      },
+    );
+  },
+);

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

@@ -26,15 +26,37 @@ const isActivity = (s: StepDefinition): s is ActivityStep => s.kind === "activit
 const steps = (op: OpConfig): ActivityStep[] => op.phases.flatMap((p) => p.steps.filter(isActivity));
 const base = { name: "estate-adopt", root: "estate" };
 
-describe("TerraformAdoptOp phases (#2105)", () => {
-  test("Check, Ledger, Gate, Adopt, in that order", () => {
+describe("TerraformAdoptOp phases (#2105, #2302)", () => {
+  test("Init, Check, Ledger, Gate, Adopt, in that order", () => {
     const op = props(base);
-    expect(phaseNames(op)).toEqual(["Check", "Ledger", "Gate", "Adopt"]);
-    expect(steps(op).map((s) => s.fn)).toEqual(["choudoufuLiveCheck", "choudoufuLivePlan", "choudoufuAdopt"]);
+    expect(phaseNames(op)).toEqual(["Init", "Check", "Ledger", "Gate", "Adopt"]);
+    expect(steps(op).map((s) => s.fn)).toEqual([
+      "terraformInit",
+      "choudoufuLiveCheck",
+      "choudoufuLivePlan",
+      "choudoufuAdopt",
+    ]);
+  });
+
+  // #2302: the Ledger step's `live-plan` needs the provider schema to
+  // discover markers, which a checkout that has never run `init` does not
+  // have — every fresh CI checkout, not a GitLab peculiarity. Without this
+  // phase `live-plan` fails outright: "Error: Provider unavailable for
+  // marker discovery".
+  test("Init runs terraform init first, the same shape TerraformApplyOp and TerraformWatchOp use", () => {
+    const init = props(base).phases[0].steps[0] as ActivityStep;
+    expect(init.fn).toBe("terraformInit");
+    expect(init.args?.root).toBe("estate");
+    expect(init.args && "upgrade" in init.args).toBe(false);
+  });
+
+  test("upgrade rides the Init step only, the same option name as the other two Ops", () => {
+    const init = props({ ...base, upgrade: true }).phases[0].steps[0] as ActivityStep;
+    expect(init.args?.upgrade).toBe(true);
   });
 
-  test("Check runs live-check first, and reports whether the root was refused", () => {
-    const check = props(base).phases[0].steps[0] as ActivityStep;
+  test("Check runs live-check second, and reports whether the root was refused", () => {
+    const check = props(base).phases[1].steps[0] as ActivityStep;
     expect(check.fn).toBe("choudoufuLiveCheck");
     expect(check.outcomeAttribute).toEqual({ name: "Refused", from: "refused" });
     // No cloud calls, so this is the cheapest place to learn the root cannot
@@ -43,7 +65,7 @@ describe("TerraformAdoptOp phases (#2105)", () => {
   });
 
   test("Ledger is the -adoption-only live plan, and publishes both counts", () => {
-    const ledger = props(base).phases[1].steps[0] as ActivityStep;
+    const ledger = props(base).phases[2].steps[0] as ActivityStep;
     expect(ledger.fn).toBe("choudoufuLivePlan");
     expect(ledger.id).toBe("ledger");
     expect(ledger.args?.adoptionOnly).toBe(true);
@@ -64,14 +86,14 @@ describe("TerraformAdoptOp phases (#2105)", () => {
 
   test("an explicit estate rides the Ledger step only", () => {
     const op = props({ ...base, estate: "prod-networking" });
-    expect((op.phases[1].steps[0] as ActivityStep).args?.estate).toBe("prod-networking");
-    expect((op.phases[0].steps[0] as ActivityStep).args?.estate).toBeUndefined();
+    expect((op.phases[2].steps[0] as ActivityStep).args?.estate).toBe("prod-networking");
+    expect((op.phases[1].steps[0] as ActivityStep).args?.estate).toBeUndefined();
   });
 });
 
 describe("TerraformAdoptOp gates on the ledger (#2105)", () => {
   const gateOf = (op: OpConfig): GateStep => {
-    const step = op.phases[2].steps[0];
+    const step = op.phases[3].steps[0];
     expect(step.kind).toBe("gate");
     return step as GateStep;
   };
@@ -107,7 +129,7 @@ describe("TerraformAdoptOp gates on the ledger (#2105)", () => {
 });
 
 describe("TerraformAdoptOp adopts the ledger's matches and nothing else (#2105)", () => {
-  const adoptStep = (op: OpConfig): ActivityStep => op.phases[3].steps[0] as ActivityStep;
+  const adoptStep = (op: OpConfig): ActivityStep => op.phases[4].steps[0] as ActivityStep;
 
   test("the Adopt step takes the ledger's adoptable set by reference", () => {
     const adopt = adoptStep(props(base));

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

@@ -13,8 +13,18 @@
  * the two values that would claim it. Cloud-to-code here is "claim what the
  * configuration already describes" — a tag write, not a regeneration.
  *
- * Phases: Check, Ledger, Gate, Adopt.
+ * Phases: Init, Check, Ledger, Gate, Adopt.
  *
+ *   - **Init** runs `terraform init`, the same step `TerraformApplyOp` and
+ *     `TerraformWatchOp` open with. The Ledger step's `live-plan` needs the
+ *     provider schema to discover markers on the live resources it reads, and
+ *     a checkout that has never run `init` has no `.terraform` directory to
+ *     read one from — which is every fresh CI checkout, not a GitLab
+ *     peculiarity (#2302). Without this phase `live-plan` fails outright:
+ *     `Error: Provider unavailable for marker discovery`. This composite had
+ *     no Init phase because nothing had ever run `live-adopt` before
+ *     INTENTIUS/choudoufu#1026 did, so the gap survived every guard that only
+ *     read the generated YAML.
  *   - **Check** runs `live-check`, which makes no cloud calls and says whether
  *     this configuration can move under markers at all. It runs first because
  *     a root that `live-check` refuses will produce an adoption ledger that
@@ -83,6 +93,7 @@
 
 import { Op, phase, gate, activity, OpResource } from "@intentius/chant/op";
 import {
+  terraformInit as initStep,
   choudoufuLiveCheck as checkStep,
   choudoufuLivePlan as ledgerStep,
   choudoufuAdopt as adoptStep,
@@ -110,6 +121,12 @@ export interface TerraformAdoptOpConfig {
   gateTimeout?: string;
   /** Override the gate description shown to the approver. */
   gateDescription?: string;
+  /**
+   * `-upgrade` on the Init step: re-resolve provider and module versions.
+   * Same field, same meaning, as `TerraformApplyOpConfig.upgrade` and
+   * `TerraformWatchOpConfig.upgrade`.
+   */
+  upgrade?: boolean;
   /**
    * Directory each step starts the `chant.config.*` search from, which is what
    * `terraform.roots` and the root's relative `dir` resolve against. Default:
@@ -130,7 +147,7 @@ export interface TerraformAdoptOpConfig {
 }
 
 export interface TerraformAdoptOpResources {
-  /** Op resource. Generates the Check/Ledger/Gate/Adopt workflow. */
+  /** Op resource. Generates the Init/Check/Ledger/Gate/Adopt workflow. */
   op: InstanceType<typeof OpResource>;
 }
 
@@ -178,6 +195,7 @@ export function TerraformAdoptOp(config: TerraformAdoptOpConfig): TerraformAdopt
       TerraformMode: "live",
     },
     phases: [
+      phase("Init", [initStep(config.root, { ...where, ...(config.upgrade ? { upgrade: true } : {}) })]),
       phase("Check", [check]),
       phase("Ledger", [ledger]),
       phase("Gate", [

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();