@intentius/chant-lexicon-terraform 0.60.0 → 0.62.0

package/src/hcl/edges.ts

@@ -0,0 +1,316 @@
+/**
+ * Resolve each block's references into graph edges (chant #2265).
+ *
+ * `chant graph --format ir` used to emit a complete, module-descended,
+ * fully-attributed node set for a Terraform estate and zero edges. Core's
+ * `collectEdges` walks a node's config bag for `AttrRef` objects and `Ref`
+ * intrinsics; a block body out of hcl2json holds `"${aws_vpc.main.id}"`, a
+ * string, so the walk found nothing and said so. This module supplies what
+ * that walk cannot see: the references, already resolved to the entity keys
+ * `blocksToEntities` minted, published on each entity as core's lexicon-neutral
+ * `EntityReference` (see `@intentius/chant/graph-ir`).
+ *
+ * ## Where the reference forms come from
+ *
+ * The `${...}` body is tokenized by hcl2json's own expression AST
+ * (`getReferencesInExpression`), never by a regex over the string. That is the
+ * same instrument `packages/core/src/terraform/parse.ts` uses for the carve-out
+ * advisor, and for the same reason: a quoted address used as a map key
+ * (`var.m["aws_s3_bucket.assets.arn"]`) and an escaped `$${...}` literal are
+ * not references, and no regex over the raw string can tell. `./references.ts`
+ * IS such a regex scan and stays one: it answers "is this declaration used
+ * anywhere", deliberately generously, for a report-only rule. An edge a
+ * renderer draws is a stricter claim and gets the stricter instrument.
+ *
+ * Each accessor the AST returns is classified by core's own `refFromAccessor`
+ * for the three forms it already knows (`<type>.<name>`, `module.<name>`,
+ * `data.<type>.<name>`), and here for the two it deliberately excludes as
+ * non-resources, `var.<name>` and `local.<name>`.
+ *
+ * ## Four decisions a renderer will draw
+ *
+ * **Which forms become edges.** All five: `resource`, `data`, `module`, `var`
+ * and `local`. The first three are uncontroversial. The last two are edges
+ * because this lexicon emits a NODE for every `variable` and every `locals`
+ * block, and on a real estate those are the majority of them (108 variables
+ * and 10 locals out of 247 nodes, on the estate the issue was filed against).
+ * Dropping their edges would leave nearly half the graph as unconnected cards,
+ * which is the same picture the zero-edge bug drew. "Which resources consume
+ * `var.region`" is also a question a reader of a root module actually asks,
+ * and `terraform graph` itself answers it.
+ *
+ * A `local.<name>` resolves to the `locals` BLOCK that declares that name,
+ * found by looking `name` up in each block's body, so two `locals` blocks in
+ * one scope resolve independently rather than both matching.
+ *
+ * `provider = aws.west` is NOT an edge. The reference names a `provider`
+ * block by type AND alias, and this lexicon's entity key for one is
+ * `provider.<type>` with the alias inside the body, so two aliased providers
+ * of one type key as `provider.aws` and `provider.aws~2` and the reference
+ * cannot be resolved to either without guessing. `./references.ts` still
+ * records it for TF020, where "is it used at all" is answerable without
+ * knowing which block.
+ *
+ * **`depends_on` is an edge.** It arrives from hcl2json as
+ * `["${aws_vpc.main}"]` under the key `depends_on`, so it resolves through the
+ * same path as any other reference and lands as `viaAttr: "depends_on"` with
+ * no `toAttr`, which is exactly what it is: an ordering edge with no attribute
+ * flowing along it.
+ *
+ * **`count` / `for_each` are block-to-block.** chant's entity is the block, so
+ * `count = 3` is one node and one edge, not three. The expansion itself is
+ * recorded on the entity (`props.expansion`, `./parse.ts`) rather than left to
+ * be inferred from a node count that never grows. A `count = length(var.x)`
+ * also yields a real edge to `var.x` through `viaAttr: "count"`, since the
+ * meta-argument is an expression like any other.
+ *
+ * **Attribute naming.** `viaAttr` is the consumer-side TOP-LEVEL attribute the
+ * reference sits under and `toAttr` the producer-side attribute it read, which
+ * is the same pair carve's `TfEdge` carries as `via` and `attrs` and the pair
+ * behold already renders. One edge per (consumer, producer, `viaAttr`), and
+ * `toAttr` is set only when that edge read exactly one producer attribute:
+ * `subnet_id = aws_subnet.a.id` gives `id`, while
+ * `tags = merge(aws_vpc.main.tags, { id = aws_vpc.main.id })` names two and
+ * gets none rather than an arbitrary one.
+ *
+ * ## Scope, and what is deliberately not resolved
+ *
+ * Resolution is bounded to the referring block's own module scope
+ * (`scopeOfKey`), which is Terraform's own namespace: a `var.region` inside
+ * `module.cdn` is the child module's variable and never the root's. That also
+ * means no edge ever crosses roots, which is correct and intended (#2265):
+ * separate roots read each other by NAME through a data source, never by
+ * reference, and a value-match pass over those is a consumer's job, not this
+ * one's.
+ */
+
+import { isResourceDeclarable, type Declarable } from "@intentius/chant/declarable";
+import type { EntityReference } from "@intentius/chant/graph-ir";
+import { loadHcl2json, type Hcl2Json } from "@intentius/chant/terraform/parse";
+import { refFromAccessor } from "@intentius/chant/terraform/graph";
+import { LOCALS_TYPE, scopeOfKey, type BlockBody, type TerraformEntity } from "./parse";
+
+/** An identifier as Terraform's grammar allows it. Same as `./references.ts`. */
+const NAME = "[A-Za-z_][A-Za-z0-9_-]*";
+
+/** `var.<name>` / `local.<name>` at the head of a traversal accessor. */
+const SCALAR_HEAD_RE = new RegExp(`^(var|local)\\.(${NAME})(?:\\.|$)`);
+
+/** One reference read out of a body, before it is resolved to an entity key. */
+interface RawReference {
+  /** The address in this lexicon's own vocabulary: `aws_vpc.main`, `var.region`, `local.tags`. */
+  address: string;
+  /** Producer-side attribute, when the accessor named one. */
+  attr?: string;
+  /** Consumer-side top-level attribute the reference sits under. */
+  via: string;
+}
+
+/**
+ * Classify one AST traversal accessor. `var`/`local` are handled here because
+ * core's `refFromAccessor` excludes them by design (they are not carvable
+ * resources); everything else defers to it, quoted map keys and numeric
+ * indexes included.
+ */
+export function referenceFromAccessor(accessor: string): { address: string; attr?: string } | undefined {
+  const scalar = SCALAR_HEAD_RE.exec(accessor);
+  if (scalar) return { address: `${scalar[1]}.${scalar[2]}` };
+  return refFromAccessor(accessor) ?? undefined;
+}
+
+/** Every `${...}` string in a body, paired with the top-level attribute it sits under. */
+function expressionsInBody(body: BlockBody): Array<{ via: string; expression: string }> {
+  const out: Array<{ via: string; expression: string }> = [];
+  const visit = (value: unknown, via: string, depth: number): void => {
+    if (depth > 8) return;
+    if (typeof value === "string") {
+      if (value.includes("${")) out.push({ via, expression: value });
+      return;
+    }
+    if (Array.isArray(value)) {
+      for (const item of value) visit(item, via, depth + 1);
+      return;
+    }
+    if (typeof value === "object" && value !== null) {
+      for (const [key, inner] of Object.entries(value as Record<string, unknown>)) {
+        visit(inner, depth === 0 ? key : via, depth + 1);
+      }
+    }
+  };
+  visit(body, "", 0);
+  return out;
+}
+
+/** The `${...}` strings of every entity in the map, deduplicated. */
+function allExpressions(entities: ReadonlyMap<string, Declarable>): string[] {
+  const seen = new Set<string>();
+  for (const entity of entities.values()) {
+    if (!isResourceDeclarable(entity)) continue;
+    const body = bodyOf(entity as TerraformEntity);
+    for (const { expression } of expressionsInBody(body)) seen.add(expression);
+  }
+  return [...seen];
+}
+
+function bodyOf(entity: TerraformEntity): BlockBody {
+  const props = entity.props as Partial<TerraformEntity["props"]>;
+  return (typeof props.body === "object" && props.body !== null ? props.body : {}) as BlockBody;
+}
+
+/**
+ * Resolve every expression once through the AST. An expression the parser
+ * refuses in isolation resolves to no references: fewer edges, never a phantom
+ * one, which is the same trade `resolveExpressionRefs` makes in core.
+ */
+async function resolveAccessors(
+  parser: Hcl2Json,
+  expressions: readonly string[],
+): Promise<Map<string, string[]>> {
+  const out = new Map<string, string[]>();
+  for (const expression of expressions) {
+    try {
+      const found = await parser.getReferencesInExpression("expression.tf", expression);
+      out.set(
+        expression,
+        found.map((r) => r.value),
+      );
+    } catch {
+      out.set(expression, []);
+    }
+  }
+  return out;
+}
+
+/** Address to entity key, and local name to the `locals` block declaring it, per module scope. */
+export interface ScopeIndex {
+  byAddress: Map<string, string>;
+  byLocal: Map<string, string>;
+}
+
+function buildScopeIndex(entities: ReadonlyMap<string, Declarable>): Map<string, ScopeIndex> {
+  const scopes = new Map<string, ScopeIndex>();
+  for (const [key, entity] of entities) {
+    if (!isResourceDeclarable(entity)) continue;
+    const te = entity as TerraformEntity;
+    const address = (te.props as Partial<TerraformEntity["props"]>).address;
+    if (typeof address !== "string") continue;
+    const scope = scopeOfKey(key);
+    let index = scopes.get(scope);
+    if (!index) {
+      index = { byAddress: new Map(), byLocal: new Map() };
+      scopes.set(scope, index);
+    }
+    // First key wins: two blocks that genuinely share an address are keyed
+    // `~2`, `~3` (`./parse.ts`), and a reference cannot say which it meant.
+    if (!index.byAddress.has(address)) index.byAddress.set(address, key);
+    if (te.entityType === LOCALS_TYPE) {
+      for (const name of Object.keys(bodyOf(te))) {
+        if (!index.byLocal.has(name)) index.byLocal.set(name, key);
+      }
+    }
+  }
+  return scopes;
+}
+
+/** The entity key an address names within one scope, or undefined. */
+function resolveAddress(address: string, index: ScopeIndex): string | undefined {
+  if (address.startsWith("local.")) return index.byLocal.get(address.slice("local.".length));
+  return index.byAddress.get(address);
+}
+
+/** Every reference in one body, as raw addresses paired with the attribute they sit under. */
+function rawReferences(body: BlockBody, accessors: ReadonlyMap<string, readonly string[]>): RawReference[] {
+  const out: RawReference[] = [];
+  for (const { via, expression } of expressionsInBody(body)) {
+    for (const accessor of accessors.get(expression) ?? []) {
+      const ref = referenceFromAccessor(accessor);
+      if (ref) out.push({ address: ref.address, ...(ref.attr ? { attr: ref.attr } : {}), via });
+    }
+  }
+  return out;
+}
+
+/**
+ * The references one block declares, resolved to entity keys and collapsed to
+ * one entry per (producer, `viaAttr`). Sorted, so the IR a build emits is
+ * byte-stable across runs.
+ */
+export function referencesOfEntity(
+  key: string,
+  entity: TerraformEntity,
+  scopes: ReadonlyMap<string, ScopeIndex>,
+  accessors: ReadonlyMap<string, readonly string[]>,
+): EntityReference[] {
+  const index = scopes.get(scopeOfKey(key));
+  if (!index) return [];
+
+  const grouped = new Map<string, { to: string; viaAttr: string; attrs: Set<string> }>();
+  for (const raw of rawReferences(bodyOf(entity), accessors)) {
+    const to = resolveAddress(raw.address, index);
+    if (!to || to === key) continue;
+    const groupKey = `${to}${raw.via}`;
+    let group = grouped.get(groupKey);
+    if (!group) {
+      group = { to, viaAttr: raw.via, attrs: new Set() };
+      grouped.set(groupKey, group);
+    }
+    if (raw.attr) group.attrs.add(raw.attr);
+  }
+
+  const out: EntityReference[] = [];
+  for (const { to, viaAttr, attrs } of grouped.values()) {
+    out.push({
+      to,
+      ...(viaAttr ? { viaAttr } : {}),
+      // Exactly one, or none: an edge carrying an arbitrary pick out of two
+      // would be a label a reader cannot trust.
+      ...(attrs.size === 1 ? { toAttr: [...attrs][0] } : {}),
+    });
+  }
+  return out.sort((a, b) => cmp(a.to, b.to) || cmp(a.viaAttr ?? "", b.viaAttr ?? ""));
+}
+
+/** Code-point ordering, so output does not depend on the machine's locale. */
+function cmp(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * Stamp `references` onto every terraform entity in `entities`, in place.
+ *
+ * Takes the whole build's entity map rather than one root's, because one
+ * shared expression cache across every root is what keeps this to one wasm
+ * call per DISTINCT expression instead of one per occurrence. Resolution is
+ * still per module scope, so pooling the parse pools no references.
+ *
+ * Best effort, like everything else on this path: a parser that cannot be
+ * loaded, or one that does not expose the expression AST, leaves every entity
+ * unreferenced rather than failing a build over a diagram.
+ */
+export async function resolveEntityReferences(
+  entities: Map<string, Declarable>,
+  hcl2json?: Hcl2Json,
+): Promise<void> {
+  const expressions = allExpressions(entities);
+  if (expressions.length === 0) return;
+
+  let parser: Hcl2Json;
+  try {
+    parser = hcl2json ?? (await loadHcl2json());
+  } catch {
+    return;
+  }
+  if (typeof parser.getReferencesInExpression !== "function") return;
+
+  const accessors = await resolveAccessors(parser, expressions);
+  const scopes = buildScopeIndex(entities);
+
+  for (const [key, entity] of entities) {
+    if (!isResourceDeclarable(entity)) continue;
+    const te = entity as TerraformEntity;
+    const references = referencesOfEntity(key, te, scopes, accessors);
+    if (references.length === 0) continue;
+    const stamped: TerraformEntity = { ...te, references };
+    entities.set(key, stamped);
+  }
+}

package/src/hcl/parse.ts

@@ -22,6 +22,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { loadHcl2json, type Hcl2Json } from "@intentius/chant/terraform/parse";
 import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import type { EntityReference } from "@intentius/chant/graph-ir";
 import type { SuppressionDirective } from "@intentius/chant/lint/suppressions";
 import type { TerraformDeleteMode } from "../config";
 import { scanSuppressions, directivesFor, type FileScan } from "./suppressions";
@@ -29,6 +30,18 @@ import { scanSuppressions, directivesFor, type FileScan } from "./suppressions";
 /** A parsed HCL block body, as `@cdktf/hcl2json` encodes it. */
 export type BlockBody = Record<string, unknown>;
 
+/**
+ * The meta-argument that expands a block into instances, when it carries one
+ * (chant #2265). Recorded because chant's entity is the BLOCK, one node
+ * whatever `count` evaluates to, so an edge out of an expanded block is
+ * block-to-block and says nothing about how many instances reference how many
+ * others. That is the honest shape for a read of the declaration alone, since
+ * the instance count is a plan-time answer and often a state-time one, but it
+ * is a shape a reader should be told rather than left to infer from a node
+ * count that never grows.
+ */
+export type TerraformExpansion = "count" | "for_each";
+
 /** Whether a root runs under choudoufu with a declared estate (#2103). */
 export type TerraformRootMode = "live" | "state";
 
@@ -99,7 +112,37 @@ export interface TerraformEntity extends Declarable {
      * quotes still exist. Empty when a caller built the entity by hand.
      */
     readonly source: string;
+    /**
+     * `count` or `for_each` when the block carries one (chant #2265). See
+     * {@link TerraformExpansion} for why one node still stands for the whole
+     * expansion.
+     */
+    readonly expansion?: TerraformExpansion;
   };
+  /**
+   * The deployable unit this entity belongs to: the root name, which is what
+   * one `terraform apply` runs against (chant #2266).
+   *
+   * Duplicates `props.root`, deliberately. `props` is what this lexicon's own
+   * checks and serializer read; `stack` is the lexicon-neutral field core's
+   * `buildGraphIr` reads to key `groups.byStack`, so a five-root project draws
+   * as five boundary boxes instead of one bucket named `terraform`. Core has
+   * no business reaching into a lexicon's `props` to find out, and this
+   * lexicon has no business knowing how the grouping is built, so the fact is
+   * said once in each vocabulary. A child module's blocks carry the calling
+   * ROOT's name, not the module's: the module is not separately applied.
+   */
+  readonly stack: string;
+  /**
+   * Every reference in this block, resolved to the entity keys it points at
+   * (chant #2265), in core's lexicon-neutral {@link EntityReference} shape.
+   *
+   * Absent until `./edges.ts` resolves it, which needs the whole root's entity
+   * set and so cannot happen inside the per-file parse below. An entity that
+   * never went through that pass carries none, which reads as "no references
+   * were resolved", never as "this block references nothing".
+   */
+  readonly references?: readonly EntityReference[];
   /**
    * `# chant-ignore`/`chant-ignore-file`/`chant-ignore-block` directives that
    * apply to this entity (chant #2111): the ones anchored to its own block,
@@ -126,6 +169,13 @@ export const LIVE_TYPE = "Terraform::Live";
 /** The sidecar filename choudoufu reads an estate declaration from when no in-block `live { }` is used. */
 export const LIVE_SIDECAR_FILENAME = "estate.chdf.hcl";
 
+/** The expansion meta-argument a block body carries, if any. `count` wins if both are present (Terraform rejects that combination anyway). */
+function expansionOf(body: BlockBody): TerraformExpansion | undefined {
+  if ("count" in body) return "count";
+  if ("for_each" in body) return "for_each";
+  return undefined;
+}
+
 /**
  * Build one entity. Written out rather than run through `createResource`
  * from `@intentius/chant/runtime`: that factory is for generated resource
@@ -145,11 +195,13 @@ export function terraformEntity(
   line?: number,
   suppressions?: readonly SuppressionDirective[],
 ): TerraformEntity {
+  const expansion = expansionOf(body);
   return {
     [DECLARABLE_MARKER]: true,
     lexicon: "terraform",
     entityType,
     kind: "resource",
+    stack: root,
     props: {
       address,
       body,
@@ -157,6 +209,7 @@ export function terraformEntity(
       root,
       source,
       line,
+      ...(expansion ? { expansion } : {}),
       ...(extra?.mode !== undefined ? { mode: extra.mode } : {}),
       ...(extra?.estate !== undefined ? { estate: extra.estate } : {}),
       ...(extra?.workspace !== undefined ? { workspace: extra.workspace } : {}),

package/src/hcl/roots.ts

@@ -18,6 +18,12 @@
  * local source is followed into its directory and parsed as a child scope of
  * the root (#2112). `./descend.ts` owns that walk and every refusal in it; the
  * refusals surface here as this render's warnings.
+ *
+ * One pass runs after every root has parsed: `./edges.ts` resolves each
+ * block's `${...}` references into the entity keys they name, so the graph IR
+ * has edges to draw (#2265). It runs here rather than inside the per-file
+ * parse because an edge's target may be a block in a file, or a child module,
+ * that has not been read yet.
  */
 
 import { existsSync } from "node:fs";
@@ -27,6 +33,7 @@ import type { Hcl2Json } from "@intentius/chant/terraform/parse";
 import type { TerraformRootConfig } from "../config";
 import { LIVE_TYPE, parseTerraformRootDir } from "./parse";
 import { descendModules, resolveCallModuleType, type CallModuleType } from "./descend";
+import { resolveEntityReferences } from "./edges";
 
 export interface TerraformRootsResult {
   entities: Map<string, Declarable>;
@@ -117,5 +124,12 @@ export async function renderTerraformRoots(
     }
   }
 
+  // Every root and every descended child module is parsed by now, which is
+  // what reference resolution needs: an edge points at an entity key, and the
+  // keys only all exist once the last descent has run (#2265). One pass over
+  // the whole map, one expression cache, resolution still bounded to each
+  // block's own module scope.
+  await resolveEntityReferences(entities, opts.hcl2json);
+
   return { entities, warnings };
 }

package/src/index.ts

@@ -66,6 +66,7 @@ export {
   renderAdoptionLedger,
   type AdoptionCandidate,
   type AdoptionLedger,
+  type AdoptionMatch,
 } from "./op/adoption";
 
 // The Init/Plan/Gate/Apply composite (#2086).

package/src/op/activities/choudoufu.test.ts

@@ -277,10 +277,10 @@ describe("isOlderVersion / parseChoudoufuVersion (#2103)", () => {
 // ── The version check, wired into every activity via resolveRoot ───────────
 
 describe("choudoufu version check (#2103)", () => {
-  test("refuses a binary older than the floor, which the -json document moved to v0.14.0", async () => {
+  test("refuses a binary older than the floor, which the adoptable section moved to v0.15.0", async () => {
     const dir = liveProject();
-    replies.push({ match: "version", reply: { stdout: "choudoufu v0.13.0 (based on OpenTofu v1.13.0)\n", stderr: "" } });
-    await expect(choudoufuLiveCheck({ root: "estate", cwd: dir })).rejects.toThrow(/older than.*v0\.14\.0/);
+    replies.push({ match: "version", reply: { stdout: "choudoufu v0.14.0 (based on OpenTofu v1.13.0)\n", stderr: "" } });
+    await expect(choudoufuLiveCheck({ root: "estate", cwd: dir })).rejects.toThrow(/older than.*v0\.15\.0/);
   });
 
   test("passes at exactly the minimum version", async () => {

package/src/op/activities/terraform.ts

@@ -81,11 +81,20 @@ export const DEFAULT_LIVE_PLAN_DOCUMENT_FILE = "chant.live-plan.json";
  * estate ([choudoufu #894](https://github.com/INTENTIUS/choudoufu/issues/894),
  * PR 915), which is the shape every chant live root has: before it,
  * {@link choudoufuLivePlan} could not produce the document for a real root at
- * all. {@link terraformApply} depends on the exit-3 refusal and
- * `describeResources()` and both document-reading Ops depend on the document,
- * so the floor is the release that shipped the later of the two.
+ * all. v0.15.0 brought the document's `adoptable` section and the `swept`
+ * list beside it
+ * ([choudoufu #962](https://github.com/INTENTIUS/choudoufu/issues/962), PR
+ * 963), which is the only place a content match reaches a machine: before it,
+ * a declared resource whose identity the provider assigns could never be
+ * adopted through the document at all, and `TerraformAdoptOp`'s own
+ * acceptance suite had never passed on any binary (#2241).
+ *
+ * {@link terraformApply} depends on the exit-3 refusal, `describeResources()`
+ * and both document-reading Ops depend on the document, and the adopt path
+ * depends on the `adoptable` section, so the floor is the release that
+ * shipped the last of the three.
  */
-export const MIN_CHOUDOUFU_VERSION = "0.14.0";
+export const MIN_CHOUDOUFU_VERSION = "0.15.0";
 
 /**
  * choudoufu's own refusal summary for `-out` on the `live-plan -estate`
@@ -185,6 +194,12 @@ export interface ChoudoufuLivePlanArgs extends TerraformRootArgs {
    * cost is that the second read asks the estate-wide sweep the account-bounded
    * question ("which live resources carry no ownership marker at all"), so it
    * is slower than the ordinary render, not faster.
+   *
+   * Since #2241 the flag also puts `TOFU_LIVE_COLLECT_UNCLAIMED=1` on the
+   * `-json` run, so the document carries the same sweep's answer as its
+   * `adoptable` and `swept` sections rather than only the render carrying it.
+   * That is what an adoption reads: the render's rows are prose, and the
+   * document's are addresses, marker values and a tagging command.
    */
   adoptionOnly?: boolean;
 }
@@ -276,11 +291,22 @@ export interface TerraformApplyResult {
   refusal?: string;
 }
 
-/** Counts projected out of `live-plan -json`'s `unowned` section. */
+/** Counts projected out of `live-plan -json`'s `unowned` and `adoptable` sections. */
 export interface LivePlanUnownedCounts {
-  /** Live resources at a declared identity carrying no ownership marker for this estate. */
+  /**
+   * `unowned[]`'s length: live resources sitting at an identity this
+   * configuration declares, carrying no ownership marker for this estate.
+   */
   unowned: number;
-  /** Of those, how many an exact content match makes adoptable. */
+  /**
+   * Every live resource this run could claim with a tag write, from both
+   * sections: the `unowned[]` rows choudoufu offered marker values for, plus
+   * the `adoptable[]` rows the estate-wide sweep content-matched to a
+   * declaration that carries no identity of its own (choudoufu #962). Those
+   * two sections are disjoint, so this is a sum and never a double count.
+   * `adoptable[]` is populated only on an adoption run (#2241), so an
+   * observation read's document contributes nothing to it.
+   */
   adoptable: number;
 }
 
@@ -306,7 +332,10 @@ export interface LivePlanUnownedCounts {
 export interface ChoudoufuLivePlanResult extends LivePlanUnownedCounts, PlanChangeCounts {
   /** `true` when `-detailed-exitcode` reported exit 2: the live plan proposes changes. */
   drift: boolean;
-  /** GitHub issue #788's JSON document (`bound`, `omissions`, `unowned`), captured whole. */
+  /**
+   * GitHub issue #788's JSON document (`bound`, `omissions`, `unowned`, and
+   * since choudoufu v0.15.0 `adoptable` and `swept`), captured whole.
+   */
   json: unknown;
   /**
    * The human-readable plan, from a second `live-plan` run without `-json`
@@ -334,6 +363,13 @@ export interface ChoudoufuLivePlanResult extends LivePlanUnownedCounts, PlanChan
   contested: AdoptionCandidate[];
   /** How many declared addresses are contested — the count `contested` above spells out. */
   ambiguous: number;
+  /**
+   * `swept[]`: the resource types the estate-wide sweep listed in full on this
+   * run. Empty on any run that did not ask for the sweep, which is every run
+   * without {@link ChoudoufuLivePlanArgs.adoptionOnly}, so an empty
+   * `adoptions` beside an empty `swept` means the question was never put.
+   */
+  swept: string[];
   /** Absolute path of the root module directory. */
   dir: string;
   /** Where the JSON document was written, relative to `dir`; {@link DEFAULT_LIVE_PLAN_DOCUMENT_FILE} unless overridden. */
@@ -549,14 +585,14 @@ export function choudoufuLiveCheckCommand(opts: { binary: string }): string {
  * (`adopt_tofu_estate`/`adopt_tofu_address` present).
  */
 export function countLivePlanUnowned(document: unknown): LivePlanUnownedCounts {
-  const unowned = (document as { unowned?: unknown } | null | undefined)?.unowned;
-  if (!Array.isArray(unowned)) return { unowned: 0, adoptable: 0 };
-  let adoptable = 0;
-  for (const entry of unowned) {
+  const doc = (document ?? {}) as { unowned?: unknown; adoptable?: unknown };
+  const unowned = Array.isArray(doc.unowned) ? doc.unowned : [];
+  const claimable = (entry: unknown): boolean => {
     const e = entry as { adopt_tofu_estate?: unknown; adopt_tofu_address?: unknown } | null | undefined;
-    if (e?.adopt_tofu_estate || e?.adopt_tofu_address) adoptable++;
-  }
-  return { unowned: unowned.length, adoptable };
+    return Boolean(e?.adopt_tofu_estate || e?.adopt_tofu_address);
+  };
+  const matched = Array.isArray(doc.adoptable) ? doc.adoptable.filter(claimable).length : 0;
+  return { unowned: unowned.length, adoptable: unowned.filter(claimable).length + matched };
 }
 
 /**
@@ -665,8 +701,8 @@ async function ensureChoudoufuVersion(binary: string, signal?: AbortSignal): Pro
     if (isOlderVersion(version, MIN_CHOUDOUFU_VERSION)) {
       throw new Error(
         `choudoufu ${version} is older than the minimum supported version v${MIN_CHOUDOUFU_VERSION} ` +
-          "(needed for live-plan -json, live-ls, live-check -json, and the approval artifact `plan -out` / " +
-          "`apply <planfile>` pair). Upgrade choudoufu.",
+          "(needed for live-plan -json, live-ls, live-check -json, the approval artifact `plan -out` / " +
+          "`apply <planfile>` pair, and the document's adoptable section). Upgrade choudoufu.",
       );
     }
   })();
@@ -1011,8 +1047,17 @@ export async function choudoufuLivePlan(
   let drift: boolean;
   let jsonStdout: string;
   const planCmd = choudoufuLivePlanCommand({ binary, ...estateFlag, json: true });
+  // The document's `adoptable` and `swept` sections are populated only on a
+  // run that asked the estate-wide sweep the account-bounded question, which
+  // `-adoption-only` implies and a `-json` run does not
+  // (`internal/command/live_collect_unclaimed.go`). `-adoption-only` cannot
+  // ride the `-json` invocation, so the env var is how a document-producing
+  // run asks for the same thing. Set only under `adoptionOnly`: the sweep is
+  // an account-wide list per admitted type, and an observation read has no use
+  // for it.
+  const planEnv = args.adoptionOnly ? { ...env, TOFU_LIVE_COLLECT_UNCLAIMED: "1" } : env;
   try {
-    const { stdout, stderr } = await run(planCmd, dir, env, signal);
+    const { stdout, stderr } = await run(planCmd, dir, planEnv, signal);
     report(stdout, stderr);
     drift = false;
     jsonStdout = stdout;
@@ -1069,9 +1114,12 @@ export async function choudoufuLivePlan(
 
   writeFileSync(join(dir, documentPath), document);
 
-  // The adoption commands only exist in the `-adoption-only` render, so a
-  // candidate off an ordinary run carries the two marker values and no
-  // command — which is the whole ownership contract either way.
+  // An `adoptable[]` row carries its own tagging command in the document
+  // (choudoufu #962). An `unowned[]` row does not, and the render is the only
+  // place one is printed for it, so the parse still runs on an adoption run
+  // and the map still feeds that half. A candidate off an ordinary run carries
+  // the two marker values and no command, which is the whole ownership
+  // contract either way.
   const ledger = readAdoptionLedger(json, args.adoptionOnly ? parseAdoptionCommands(text) : undefined);
   const ledgerText = renderAdoptionLedger(ledger, estate);
 
@@ -1084,6 +1132,7 @@ export async function choudoufuLivePlan(
     adoptions: ledger.adoptions,
     contested: ledger.contested,
     ambiguous: ledger.ambiguous,
+    swept: ledger.swept,
     dir,
     documentPath,
     estate,