@intentius/chant 0.124.46 → 0.124.49

package/src/stage-hooks-bundle.test.ts

@@ -31,6 +31,7 @@ describe("the stage-hooks bundle", () => {
       "packages/core/src/op/gate-quorum.ts",
       "packages/core/src/op/op-waves.ts",
       "packages/core/src/op/stage-hooks.ts",
+      "packages/core/src/wave-blocked.ts",
       "packages/core/src/wave-layout.ts",
     ]);
     expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(48 * 1024);

package/src/terraform/carve.ts

@@ -13,8 +13,9 @@
 
 import { inboundEdges, outboundEdges } from "./graph";
 import { foldParentOf, resolveTier } from "./tier-map";
-import { scoreEstate, type ScoreOptions } from "./score";
-import type { TfGraph } from "./types";
+import { scoreEstate, type Peelability, type ScoreOptions } from "./score";
+import { adjacencyOf, type Adjacency } from "../graph-walk";
+import type { TfEdge, TfGraph, TfNode } from "./types";
 
 /** One resource in the carve set (the selected node plus its folded sub-resources). */
 export interface CarveMember {
@@ -85,24 +86,53 @@ export interface CarveReport {
  * that fold into it (same name, a `foldParentOf` child type whose parent is the
  * selection). Those are carried along and inlined, not left behind.
  */
-export function resolveCarveSet(graph: TfGraph, target: string): CarveMember[] {
-  const byAddress = new Map(graph.nodes.map((n) => [n.address, n]));
+export function resolveCarveSet(graph: TfGraph, target: string, index?: BoundaryIndex): CarveMember[] {
+  const { byAddress, foldChildren } = index ?? boundaryIndex(graph);
   const selected = byAddress.get(target);
   if (!selected) return [];
 
   const members: CarveMember[] = [{ address: selected.address, type: selected.type }];
   if (selected.kind === "resource" && selected.type) {
-    for (const node of graph.nodes) {
-      if (node.kind !== "resource" || !node.type) continue;
-      const parentType = foldParentOf(node.type);
-      if (parentType === selected.type && node.name === selected.name) {
-        members.push({ address: node.address, type: node.type, foldedInto: selected.address });
-      }
+    for (const node of foldChildren.get(foldKey(selected.type, selected.name)) ?? []) {
+      members.push({ address: node.address, type: node.type, foldedInto: selected.address });
     }
   }
   return members;
 }
 
+const foldKey = (parentType: string, name: string): string => `${parentType}\u001f${name}`;
+
+/**
+ * What `boundaryReport` looks up per target, built once per graph: nodes by
+ * address, the edges by both ends, and each fold parent's children in graph
+ * order. Without it each report scans the node and edge lists itself, which
+ * over a whole estate is O(V·E) (#4391).
+ */
+export interface BoundaryIndex {
+  byAddress: Map<string, TfNode>;
+  adjacency: Adjacency<TfEdge>;
+  /** `foldKey(parent type, name)` → resource nodes that fold into that parent. */
+  foldChildren: Map<string, TfNode[]>;
+}
+
+export function boundaryIndex(graph: TfGraph): BoundaryIndex {
+  const foldChildren = new Map<string, TfNode[]>();
+  for (const node of graph.nodes) {
+    if (node.kind !== "resource" || !node.type) continue;
+    const parentType = foldParentOf(node.type);
+    if (!parentType) continue;
+    const key = foldKey(parentType, node.name);
+    const list = foldChildren.get(key);
+    if (list) list.push(node);
+    else foldChildren.set(key, [node]);
+  }
+  return {
+    byAddress: new Map(graph.nodes.map((n) => [n.address, n])),
+    adjacency: adjacencyOf(graph.edges),
+    foldChildren,
+  };
+}
+
 /**
  * Which source the graph came from, and so which vocabulary its bridge patches
  * are named in. Terraform is the default; `cdk` is the read-only cloud-assembly
@@ -115,6 +145,13 @@ export interface BoundaryOptions {
   dialect?: CarveDialect;
   /** Scoring hooks, so `peelability` is the same number the ranking reported. */
   score?: ScoreOptions;
+  /**
+   * The target's score, when the caller already holds it (`carve advise`).
+   * Without it the estate is scored to find it (#4391).
+   */
+  peelability?: Pick<Peelability, "score">;
+  /** `boundaryIndex(graph)`, shared across calls on one graph. */
+  index?: BoundaryIndex;
 }
 
 /** The bridge patch an inbound cut needs, per source. */
@@ -131,7 +168,7 @@ function inboundBridge(dialect: CarveDialect, fromOutput: boolean): BoundaryEdge
  */
 export function boundaryReport(graph: TfGraph, target: string, opts: BoundaryOptions = {}): CarveReport | null {
   const dialect = opts.dialect ?? "terraform";
-  const carveSet = resolveCarveSet(graph, target);
+  const carveSet = resolveCarveSet(graph, target, opts.index);
   if (carveSet.length === 0) return null;
   const inSet = new Set(carveSet.map((m) => m.address));
 
@@ -139,7 +176,7 @@ export function boundaryReport(graph: TfGraph, target: string, opts: BoundaryOpt
   const outbound: BoundaryEdge[] = [];
 
   for (const member of carveSet) {
-    for (const e of inboundEdges(graph, member.address)) {
+    for (const e of (opts.index ? (opts.index.adjacency.in.get(member.address) ?? []) : inboundEdges(graph, member.address))) {
       if (inSet.has(e.from)) continue; // internal edge
       inbound.push({
         direction: "inbound",
@@ -152,7 +189,7 @@ export function boundaryReport(graph: TfGraph, target: string, opts: BoundaryOpt
         ...(e.crossStack ? { crossStack: true } : {}),
       });
     }
-    for (const e of outboundEdges(graph, member.address)) {
+    for (const e of (opts.index ? (opts.index.adjacency.out.get(member.address) ?? []) : outboundEdges(graph, member.address))) {
       if (inSet.has(e.to)) continue; // internal edge
       outbound.push({
         direction: "outbound",
@@ -167,13 +204,13 @@ export function boundaryReport(graph: TfGraph, target: string, opts: BoundaryOpt
     }
   }
 
-  const score = scoreEstate(graph, opts.score).find((r) => r.address === target);
+  const score = opts.peelability ?? scoreEstate(graph, { ...opts.score, radius: false }).find((r) => r.address === target);
   const diagnostics: string[] = [];
   const tierOf = opts.score?.tierOf ?? resolveTier;
   if (
     carveSet[0].type &&
     tierOf(carveSet[0].type) === null &&
-    graph.nodes.find((n) => n.address === target)?.kind === "resource"
+    (opts.index?.byAddress ?? new Map(graph.nodes.map((n) => [n.address, n]))).get(target)?.kind === "resource"
   ) {
     diagnostics.push(`No known native mapping for ${carveSet[0].type} — emit will have no target type.`);
   }

package/src/terraform/cuts.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, test } from "vitest";
+import { join } from "path";
+import { loadHcl2json, parseTerraformDir } from "./parse";
+import { closure, components, cuts } from "./cuts";
+import type { TfEdge, TfGraph, TfNode } from "./types";
+
+/**
+ * #3909: cuts and reference-closed sets. The proof runs against depth-estate
+ * (#2323) as `parseTerraformDir` builds it; several components, a cycle, a
+ * straddling output and cross-stack edges are on hand-built graphs.
+ */
+let parserAvailable = false;
+try {
+  await loadHcl2json();
+  parserAvailable = true;
+} catch {
+  parserAvailable = false;
+}
+
+const ESTATE = join(__dirname, "__fixtures__", "depth-estate");
+const ends = (edges: TfEdge[]): string[] => edges.map((e) => `${e.from} -> ${e.to}`);
+
+const node = (address: string, extra: Partial<TfNode> = {}): TfNode => {
+  const [type, name] = address.split(".");
+  return { address, kind: "resource", type, name, instances: 1, hasDynamic: false, ...extra };
+};
+const edge = (from: string, to: string, extra: Partial<TfEdge> = {}): TfEdge => ({ from, to, attrs: [], via: [], ...extra });
+
+const DEPTH_ESTATE_BLOCKS = [
+  "aws_cloudwatch_log_group.api",
+  "aws_db_subnet_group.main",
+  "aws_kms_key.data",
+  "aws_lambda_function.api",
+  "aws_lb.public",
+  "aws_lb_listener.https",
+  "aws_lb_target_group.app",
+  "aws_rds_cluster.main",
+  "aws_rds_cluster_instance.one",
+  "aws_s3_bucket.assets",
+  "aws_s3_bucket_versioning.assets",
+  "aws_security_group.app",
+  "aws_security_group.db",
+  "aws_subnet.a",
+  "aws_subnet.b",
+  "aws_subnet.private",
+  "aws_vpc.main",
+  "module.platform",
+];
+
+describe("against depth-estate", () => {
+  test("components match the pinned list: one, with the module and the count hiding what it holds", async () => {
+    if (!parserAvailable) return;
+    const graph = await parseTerraformDir(ESTATE);
+    expect(components(graph)).toEqual([
+      {
+        resources: DEPTH_ESTATE_BLOCKS,
+        outputs: ["output.db_endpoint", "output.lb_dns"],
+        instances: "unknown",
+        hiddenBy: ["aws_subnet.private", "module.platform"],
+      },
+    ]);
+  });
+
+  test("cuts of a hand-picked set name each crossing edge with its direction", async () => {
+    if (!parserAvailable) return;
+    const graph = await parseTerraformDir(ESTATE);
+    const c = cuts(graph, ["aws_rds_cluster.main", "aws_rds_cluster_instance.one"]);
+    expect(ends(c.inbound)).toEqual([
+      "aws_lambda_function.api -> aws_rds_cluster.main",
+      "output.db_endpoint -> aws_rds_cluster.main",
+    ]);
+    expect(ends(c.outbound)).toEqual([
+      "aws_rds_cluster.main -> aws_db_subnet_group.main",
+      "aws_rds_cluster.main -> aws_kms_key.data",
+      "aws_rds_cluster.main -> aws_security_group.db",
+    ]);
+    expect(c.counts).toEqual({
+      inbound: { resources: 1, outputs: 1, crossStack: 0 },
+      outbound: { resources: 3, outputs: 0, crossStack: 0 },
+    });
+    expect(c.bothWays).toBe(true);
+  });
+
+  test("closure from a leaf with outbound allowed leaves only outbound cuts", async () => {
+    if (!parserAvailable) return;
+    const graph = await parseTerraformDir(ESTATE);
+    const leaf = closure(graph, ["aws_rds_cluster_instance.one"], "outbound");
+    expect(leaf.resources).toEqual(["aws_rds_cluster_instance.one"]);
+    expect(leaf.inbound).toEqual([]);
+    expect(ends(leaf.outbound)).toEqual(["aws_rds_cluster_instance.one -> aws_rds_cluster.main"]);
+
+    // A seed with dependents takes them all, outputs included.
+    const key = closure(graph, ["aws_kms_key.data"], "outbound");
+    expect(key.resources).toEqual(["aws_kms_key.data", "aws_lambda_function.api", "aws_rds_cluster.main", "aws_rds_cluster_instance.one"]);
+    expect(key.outputs).toEqual(["output.db_endpoint"]);
+    expect(key.inbound).toEqual([]);
+    expect(key.outbound.length).toBeGreaterThan(0);
+    expect(key.instances).toBe(4);
+  });
+
+  test("closure with inbound allowed takes what the seed depends on, and leaves only inbound cuts", async () => {
+    if (!parserAvailable) return;
+    const graph = await parseTerraformDir(ESTATE);
+    const c = closure(graph, ["aws_rds_cluster_instance.one"], "inbound");
+    expect(c.outbound).toEqual([]);
+    expect(c.resources).toContain("aws_vpc.main");
+    expect(c.inbound.every((e) => !c.resources.includes(e.from))).toBe(true);
+  });
+
+  test("closure with none allowed returns the leaf's whole component", async () => {
+    if (!parserAvailable) return;
+    const graph = await parseTerraformDir(ESTATE);
+    const c = closure(graph, ["aws_rds_cluster_instance.one"], "none");
+    expect(c.resources).toEqual(DEPTH_ESTATE_BLOCKS);
+    expect(c.outputs).toEqual(["output.db_endpoint", "output.lb_dns"]);
+    expect([...c.inbound, ...c.outbound]).toEqual([]);
+    expect(c.instances).toBe("unknown");
+  });
+
+  test("a set that splits a fold is contracted before its cuts are counted", async () => {
+    if (!parserAvailable) return;
+    const graph = await parseTerraformDir(ESTATE);
+    const child = cuts(graph, ["aws_s3_bucket_versioning.assets"]);
+    const parent = cuts(graph, ["aws_s3_bucket.assets"]);
+    expect(child).toEqual(parent);
+    expect(parent.resources).toEqual(["aws_s3_bucket.assets", "aws_s3_bucket_versioning.assets"]);
+    expect(ends(parent.inbound)).toEqual(["aws_lambda_function.api -> aws_s3_bucket.assets"]);
+    expect(parent.outbound).toEqual([]);
+  });
+});
+
+describe("on hand-built graphs", () => {
+  test("separate components stay separate, and an output never joins them", () => {
+    const graph: TfGraph = {
+      nodes: [node("aws_sqs_queue.a"), node("aws_sqs_queue.b"), node("aws_sns_topic.c")],
+      edges: [
+        edge("aws_sqs_queue.b", "aws_sqs_queue.a"),
+        edge("output.both", "aws_sqs_queue.a", { fromKind: "output" }),
+        edge("output.both", "aws_sns_topic.c", { fromKind: "output" }),
+      ],
+    };
+    expect(components(graph)).toEqual([
+      { resources: ["aws_sns_topic.c"], outputs: ["output.both"], instances: 1 },
+      { resources: ["aws_sqs_queue.a", "aws_sqs_queue.b"], outputs: ["output.both"], instances: 2 },
+    ]);
+    // The straddling output stays outside a none-closure, its read left as a cut.
+    const c = closure(graph, ["aws_sqs_queue.a"], "none");
+    expect(c.outputs).toEqual([]);
+    expect(ends(c.inbound)).toEqual(["output.both -> aws_sqs_queue.a"]);
+  });
+
+  test("a depends_on cycle terminates in every closure", () => {
+    const graph: TfGraph = {
+      nodes: [node("aws_sqs_queue.a"), node("aws_sqs_queue.b"), node("aws_sqs_queue.c")],
+      edges: [edge("aws_sqs_queue.a", "aws_sqs_queue.b"), edge("aws_sqs_queue.b", "aws_sqs_queue.c"), edge("aws_sqs_queue.c", "aws_sqs_queue.a")],
+    };
+    for (const allow of ["inbound", "outbound", "none"] as const) {
+      expect(closure(graph, ["aws_sqs_queue.a"], allow).resources).toEqual(["aws_sqs_queue.a", "aws_sqs_queue.b", "aws_sqs_queue.c"]);
+    }
+  });
+
+  test("crossStack cuts are counted apart", () => {
+    const graph: TfGraph = {
+      nodes: [node("Data/Bucket"), node("App/Fn")],
+      edges: [edge("App/Fn", "Data/Bucket", { crossStack: true })],
+    };
+    expect(cuts(graph, ["Data/Bucket"]).counts.inbound).toEqual({ resources: 1, outputs: 0, crossStack: 1 });
+  });
+
+  test("an address the graph does not hold is an error", () => {
+    expect(() => cuts({ nodes: [], edges: [] }, ["aws_vpc.nope"])).toThrow(/not a resource, module or output/);
+  });
+});

package/src/terraform/cuts.ts

@@ -0,0 +1,188 @@
+/**
+ * Cuts and reference-closed sets over the carve graph (#3909).
+ *
+ * `carve advise` scores one block at a time. A consumer splitting one root into
+ * several (terragucci's estate carving) needs the same question for a set:
+ * which edges cross its boundary and which way, and the smallest set around a
+ * seed whose crossings all run a way the caller allows. These are pure
+ * functions over `TfGraph`, on the index and walk in `reach.ts`, so the rules
+ * there hold here too: folds contract first, outputs are terminal and counted
+ * apart, modules and unresolved `count` are named as hiding their contents, a
+ * `depends_on` cycle terminates, and `crossStack` edges are counted apart.
+ *
+ * Nothing here ranks sets, reads state or plan times, writes HCL, or knows
+ * about roots or backends; that stays with the consumer.
+ */
+
+import { carveIndex, cmp, hidesContents, isOutputAddress, walkFrom, weigh, type CarveIndex } from "./reach";
+import type { TfEdge, TfGraph } from "./types";
+
+/** Cut edges of one direction, counted. */
+export interface CutCount {
+  /** Edges whose reading side is a resource or module block. */
+  resources: number;
+  /** Edges whose reading side is an `output` block. */
+  outputs: number;
+  /** Of all of them, the `crossStack` edges (a CDK `Fn::ImportValue`). */
+  crossStack: number;
+}
+
+/** A set of blocks, as the walks see it. */
+export interface BlockSet {
+  /** Resource and module addresses, each fold parent with the blocks folded into it. Sorted. */
+  resources: string[];
+  /** `output.<name>` pseudo-addresses in the set. Sorted. */
+  outputs: string[];
+}
+
+export interface Cuts extends BlockSet {
+  /** Edges where something outside reads something inside, as the graph holds them. */
+  inbound: TfEdge[];
+  /** Edges where something inside reads something outside. */
+  outbound: TfEdge[];
+  counts: { inbound: CutCount; outbound: CutCount };
+  /** Cuts run in both directions: the set can move only with wiring both ways. */
+  bothWays: boolean;
+}
+
+/** The cut directions a closure may leave: `inbound` (outside may read in), `outbound` (inside may read out), or `none`. */
+export type CutAllowance = "inbound" | "outbound" | "none";
+
+export interface Closure extends Cuts {
+  /** The seeds as the walk saw them, folds contracted. */
+  seeds: string[];
+  allow: CutAllowance;
+  /**
+   * How many resource instances the set stands for: each block once, or its
+   * instance count once `--state` resolved it. `"unknown"` where a module or an
+   * unresolved `count`/`for_each` hides how much it holds; `hiddenBy` names them.
+   */
+  instances: number | "unknown";
+  hiddenBy?: string[];
+}
+
+export interface Component extends BlockSet {
+  /** As {@link Closure.instances}. */
+  instances: number | "unknown";
+  hiddenBy?: string[];
+}
+
+/**
+ * The graph's weakly connected components (#3909): blocks joined by a
+ * reference either way, fold-contracted, each module one node. An output never
+ * joins two components, since outputs are terminal; it is listed in every
+ * component it reads into. Components are sorted by their first address.
+ */
+export function components(graph: TfGraph): Component[] {
+  const index = carveIndex(graph);
+  const assigned = new Set<string>();
+  const found: Component[] = [];
+  for (const address of [...index.nodes.keys()].sort(cmp)) {
+    const start = index.rep(address);
+    if (assigned.has(start)) continue;
+    const reached = walkFrom(index, [start], "both");
+    const reps = [start, ...[...reached.keys()].filter((a) => !isOutputAddress(a))];
+    for (const rep of reps) assigned.add(rep);
+    found.push({ ...blockSet(index, reps, [...reached.keys()].filter(isOutputAddress)), ...holdings(index, reps) });
+  }
+  return found;
+}
+
+/**
+ * Every edge crossing the boundary of `addresses` (#3909). A folded block in
+ * the set brings its parent and siblings, and a fold parent its folded blocks,
+ * before anything is counted, so an edge inside one fold is never a cut. An
+ * `output.<name>` in the set is inside it like any block.
+ *
+ * Throws when an address is not a block of the graph.
+ */
+export function cuts(graph: TfGraph, addresses: Iterable<string>): Cuts {
+  const index = carveIndex(graph);
+  return cutsOf(index, contract(index, addresses));
+}
+
+/**
+ * The smallest superset of `seeds` whose remaining cuts all run in the
+ * direction `allow` permits, plus those cuts (#3909).
+ *
+ *  - `outbound`: nothing outside may read in, so the set takes every
+ *    dependent of the seeds, outputs included.
+ *  - `inbound`: nothing inside may read out, so the set takes everything the
+ *    seeds depend on.
+ *  - `none`: the seeds' whole components, with each output that reads only
+ *    into them.
+ *
+ * Outputs are terminal, so none of these walks passes through one. An output
+ * that reads both the set and something outside it is therefore a cut no
+ * closure removes: under `none` it stays outside and its read into the set is
+ * left as an inbound cut, for the caller to wire.
+ */
+export function closure(graph: TfGraph, seeds: Iterable<string>, allow: CutAllowance): Closure {
+  const index = carveIndex(graph);
+  const start = contract(index, seeds);
+  const direction = allow === "outbound" ? "in" : allow === "inbound" ? "out" : "both";
+  const members = new Set([...start, ...walkFrom(index, start, direction).keys()]);
+  if (allow === "none") {
+    for (const address of [...members]) {
+      if (!isOutputAddress(address) || start.has(address)) continue;
+      const reads = (index.adj.out.get(address) ?? []).map((e) => e.to);
+      if (!reads.every((to) => members.has(to))) members.delete(address);
+    }
+  }
+  const found = cutsOf(index, members);
+  return {
+    ...found,
+    seeds: [...start].sort(cmp),
+    allow,
+    ...holdings(index, [...members].filter((a) => !isOutputAddress(a))),
+  };
+}
+
+/** The addresses as the walks see them: each fold child replaced by its parent. Throws on an unknown address. */
+function contract(index: CarveIndex, addresses: Iterable<string>): Set<string> {
+  const out = new Set<string>();
+  for (const address of addresses) {
+    const known = index.nodes.has(address) || (isOutputAddress(address) && index.adj.out.has(address));
+    if (!known) throw new Error(`carve: ${address} is not a resource, module or output in this graph`);
+    out.add(index.rep(address));
+  }
+  return out;
+}
+
+function cutsOf(index: CarveIndex, members: ReadonlySet<string>): Cuts {
+  const inbound: TfEdge[] = [];
+  const outbound: TfEdge[] = [];
+  for (const address of members) {
+    for (const e of index.adj.in.get(address) ?? []) if (!members.has(e.from)) inbound.push(e.edge);
+    for (const e of index.adj.out.get(address) ?? []) if (!members.has(e.to)) outbound.push(e.edge);
+  }
+  const byEnds = (a: TfEdge, b: TfEdge): number => cmp(a.from, b.from) || cmp(a.to, b.to);
+  inbound.sort(byEnds);
+  outbound.sort(byEnds);
+  const reps = [...members];
+  return {
+    ...blockSet(index, reps.filter((a) => !isOutputAddress(a)), reps.filter(isOutputAddress)),
+    inbound,
+    outbound,
+    counts: { inbound: countOf(inbound), outbound: countOf(outbound) },
+    bothWays: inbound.length > 0 && outbound.length > 0,
+  };
+}
+
+function countOf(edges: readonly TfEdge[]): CutCount {
+  const outputs = edges.filter((e) => e.fromKind === "output").length;
+  return { resources: edges.length - outputs, outputs, crossStack: edges.filter((e) => e.crossStack).length };
+}
+
+function blockSet(index: CarveIndex, reps: readonly string[], outputs: readonly string[]): BlockSet {
+  return {
+    resources: reps.flatMap((rep) => index.membersOf(rep)).sort(cmp),
+    outputs: [...outputs].sort(cmp),
+  };
+}
+
+function holdings(index: CarveIndex, reps: readonly string[]): { instances: number | "unknown"; hiddenBy?: string[] } {
+  const instances = weigh(index, reps);
+  if (instances !== "unknown") return { instances };
+  return { instances, hiddenBy: reps.filter((a) => hidesContents(index.nodes.get(a)!)).sort(cmp) };
+}

package/src/terraform/folds.ts

@@ -0,0 +1,44 @@
+/**
+ * Fold detection for the carve graph, shared by the scorer and the walks.
+ *
+ * A sub-resource whose type inlines into a parent (`foldParentOf`) carves with
+ * that parent when the parent is in the estate under the same name:
+ * `aws_s3_bucket_versioning.assets` goes with `aws_s3_bucket.assets`. The
+ * scorer drops it from the ranking and discounts its edge to the parent; the
+ * walks in `reach.ts` contract it into the parent before stepping, since an
+ * uncontracted walk counts the child as a separate dependent (#2325 measured a
+ * 100% overstatement on the sample estate). It lived privately in `score.ts`
+ * until the walks needed it.
+ */
+
+import { foldParentOf } from "./tier-map";
+import type { TfGraph } from "./types";
+
+export interface Folds {
+  /** Every address that folds into a parent present in the estate. */
+  folded: Set<string>;
+  /** Parent address → the addresses folded into it. */
+  childrenOf: Map<string, Set<string>>;
+}
+
+/**
+ * Build the set of addresses that fold into a parent present in the estate, plus
+ * the reverse lookup (parent → its folded children), so a parent can discount
+ * inbound edges coming from its own folded sub-resources.
+ */
+export function computeFolds(graph: TfGraph): Folds {
+  const byAddress = new Map(graph.nodes.map((n) => [n.address, n]));
+  const folded = new Set<string>();
+  const childrenOf = new Map<string, Set<string>>();
+  for (const node of graph.nodes) {
+    if (node.kind !== "resource" || !node.type) continue;
+    const parentType = foldParentOf(node.type);
+    if (!parentType) continue;
+    const parentAddress = `${parentType}.${node.name}`;
+    if (!byAddress.has(parentAddress)) continue; // sub-resource without its parent → score it on its own
+    folded.add(node.address);
+    if (!childrenOf.has(parentAddress)) childrenOf.set(parentAddress, new Set());
+    childrenOf.get(parentAddress)!.add(node.address);
+  }
+  return { folded, childrenOf };
+}

package/src/terraform/graph.ts

@@ -270,6 +270,13 @@ function blockHasMeta(block: unknown, key: string): boolean {
   return !!block && typeof block === "object" && key in (block as Record<string, unknown>);
 }
 
+/** Which expansion meta-argument a block carries, as a spreadable `TfNode` field (#2325). */
+function expansionOf(block: unknown): { expansion?: "count" | "for_each" } {
+  if (blockHasMeta(block, "count")) return { expansion: "count" };
+  if (blockHasMeta(block, "for_each")) return { expansion: "for_each" };
+  return {};
+}
+
 /**
  * The literal string at a dotted path into a block, or undefined when the path
  * misses or lands on an interpolation. A dotted path walks nested blocks —
@@ -366,6 +373,7 @@ export function buildGraph(tree: Hcl2JsonTree, exprRefs: ExpressionRefs): TfGrap
         name,
         instances: 1,
         hasDynamic: dynamic || touchesData,
+        ...expansionOf(block),
         identity: literalIdentity(block, type),
         dataSourceValues: dataSourceValues(block, type),
       });
@@ -386,6 +394,7 @@ export function buildGraph(tree: Hcl2JsonTree, exprRefs: ExpressionRefs): TfGrap
       name,
       instances: 1,
       hasDynamic: dynamic || touchesData,
+      ...expansionOf(block),
     });
   }
 

package/src/terraform/radius.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, test } from "vitest";
+import { join } from "path";
+import { carveAdvise, carveJson, formatCarveReport } from "../cli/commands/carve";
+import { loadHcl2json } from "./parse";
+import { blastRadius } from "./reach";
+import { scoreEstate } from "./score";
+import type { TfEdge, TfGraph, TfNode } from "./types";
+
+/** #2326: blast radius on advise, its own axis beside the score. */
+let parserAvailable = false;
+try {
+  await loadHcl2json();
+  parserAvailable = true;
+} catch {
+  parserAvailable = false;
+}
+
+const ESTATE = join(__dirname, "__fixtures__", "depth-estate");
+const STATE = join(ESTATE, "terraform.tfstate");
+
+const node = (address: string, extra: Partial<TfNode> = {}): TfNode => {
+  const [type, name] = address.split(".");
+  return { address, kind: "resource", type, name, instances: 1, hasDynamic: false, ...extra };
+};
+const edge = (from: string, to: string, extra: Partial<TfEdge> = {}): TfEdge => ({ from, to, attrs: [], via: [], ...extra });
+
+describe("radius on carve advise against depth-estate", () => {
+  test("each resource carries its radius in the JSON, and the score still sums from its penalties", async () => {
+    if (!parserAvailable) return;
+    const result = await carveAdvise({ from: ESTATE, statePath: STATE });
+    const byAddress = new Map(carveJson(result).resources.map((r) => [r.address, r]));
+    expect(byAddress.get("aws_db_subnet_group.main")?.radius).toEqual({ resources: 3, outputs: 1, depth: 2 });
+    expect(byAddress.get("aws_lambda_function.api")?.radius).toEqual({ resources: 0, outputs: 0, depth: 0 });
+    for (const r of byAddress.values()) {
+      if (r.breakdown.tier === null) continue;
+      const sum = 100 + Object.values(r.breakdown.penalties).reduce((a, b) => a + b, 0);
+      expect(r.score).toBe(Math.max(0, Math.min(100, sum)));
+    }
+  });
+
+  test("the subnet group outranks the cluster on peelability and out-reaches it on radius", async () => {
+    if (!parserAvailable) return;
+    const result = await carveAdvise({ from: ESTATE });
+    const group = result.results!.find((r) => r.address === "aws_db_subnet_group.main")!;
+    const cluster = result.results!.find((r) => r.address === "aws_rds_cluster.main")!;
+    expect(group.score).toBeGreaterThan(cluster.score);
+    expect(group.radius!.resources).toBeGreaterThan(cluster.radius!.resources as number);
+  });
+
+  test("a module or an unresolved count makes the resource count unknown, and says which", async () => {
+    if (!parserAvailable) return;
+    const bare = await carveAdvise({ from: ESTATE });
+    const vpc = bare.results!.find((r) => r.address === "aws_vpc.main")!;
+    expect(vpc.radius).toEqual({ resources: "unknown", outputs: 2, depth: 3, hiddenBy: ["aws_subnet.private", "module.platform"] });
+    const withState = await carveAdvise({ from: ESTATE, statePath: STATE });
+    expect(withState.results!.find((r) => r.address === "aws_vpc.main")!.radius!.hiddenBy).toEqual(["module.platform"]);
+  });
+
+  test("the human report prints the radius as a column", async () => {
+    if (!parserAvailable) return;
+    const text = formatCarveReport(await carveAdvise({ from: ESTATE }));
+    expect(text).toMatch(/ 80 {2}3\+1 d2 {2}aws_db_subnet_group\.main /);
+    expect(text).toMatch(/\?\+2 d3 {2}aws_vpc\.main /);
+    expect(text).toMatch(/ - {7}aws_lambda_function\.api /);
+    expect(text).toContain("Radius: resources+outputs");
+  });
+});
+
+describe("radius on hand-built graphs", () => {
+  test("instances weight the count once state resolved them, and only then", () => {
+    const graph = (resolved: boolean): TfGraph => ({
+      nodes: [
+        node("aws_vpc.main"),
+        node("aws_subnet.private", { expansion: "count", hasDynamic: true, instances: resolved ? 3 : 1, ...(resolved ? { instancesFrom: "state" as const } : {}) }),
+      ],
+      edges: [edge("aws_subnet.private", "aws_vpc.main")],
+    });
+    expect(blastRadius(graph(true), "aws_vpc.main")).toEqual({ resources: 3, outputs: 0, depth: 1 });
+    expect(blastRadius(graph(false), "aws_vpc.main")).toEqual({ resources: "unknown", outputs: 0, depth: 1, hiddenBy: ["aws_subnet.private"] });
+  });
+
+  test("on a graph with crossStack edges the radius splits off what sits across a stack boundary", () => {
+    const graph: TfGraph = {
+      nodes: [node("Data/Bucket"), node("Data/Reader"), node("App/Fn"), node("App/Alarm")],
+      edges: [edge("Data/Reader", "Data/Bucket"), edge("App/Fn", "Data/Bucket", { crossStack: true }), edge("App/Alarm", "App/Fn")],
+    };
+    const bucket = scoreEstate(graph, { tierOf: () => ({ tier: 1, mapsTo: "AWS::S3::Bucket" }) }).find((r) => r.address === "Data/Bucket")!;
+    expect(bucket.radius).toEqual({ resources: 3, outputs: 0, depth: 2, crossStack: 2 });
+  });
+});