@intentius/chant 0.32.0 → 0.33.1

package/src/graph-effective.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from "vitest";
+import { enrichEffectiveTopology } from "./graph-effective";
+import type { GraphIR } from "./graph-ir";
+
+function node(id: string, kind: string, attrs: Record<string, unknown> = {}) {
+  return { id, kind: `AWS::EC2::${kind}`, attrs };
+}
+const sshRule = { IpProtocol: "tcp", FromPort: 22, ToPort: 22, CidrIp: "0.0.0.0/0" };
+
+/**
+ * webServer:  direct SG with SSH-open, subnet routes to an IGW  → SSH-reachable
+ * ltServer:   SG via LAUNCH TEMPLATE, same public subnet        → SSH-reachable (the CLI-missed hop)
+ * westServer: public subnet (IGW) but its SG has NO ingress     → internet-facing, not SSH-open
+ * privServer: private subnet (no IGW route)                     → not internet-facing
+ */
+const ir: GraphIR = {
+  nodes: [
+    node("webServer", "Instance"),
+    node("ltServer", "Instance"),
+    node("westServer", "Instance"),
+    node("privServer", "Instance"),
+    node("webSg", "SecurityGroup", { SecurityGroupIngress: [sshRule, { IpProtocol: "tcp", FromPort: 80, ToPort: 80, CidrIp: "0.0.0.0/0" }] }),
+    node("westSg", "SecurityGroup", { SecurityGroupIngress: [] }),
+    node("lt", "LaunchTemplate"),
+    node("pubSubnet", "Subnet"),
+    node("westSubnet", "Subnet"),
+    node("privSubnet", "Subnet"),
+    node("pubRt", "RouteTable"),
+    node("westRt", "RouteTable"),
+    node("pubAssoc", "SubnetRouteTableAssociation"),
+    node("westAssoc", "SubnetRouteTableAssociation"),
+    node("pubRoute", "Route", { DestinationCidrBlock: "0.0.0.0/0" }),
+    node("westRoute", "Route", { DestinationCidrBlock: "0.0.0.0/0" }),
+    node("igw", "InternetGateway"),
+    node("westIgw", "InternetGateway"),
+  ] as never,
+  edges: [
+    { from: "webServer", to: "webSg", viaAttr: "SecurityGroupIds" },
+    { from: "webServer", to: "pubSubnet", viaAttr: "SubnetId" },
+    { from: "ltServer", to: "lt", viaAttr: "LaunchTemplate" },
+    { from: "lt", to: "webSg", viaAttr: "LaunchTemplateData" },
+    { from: "ltServer", to: "pubSubnet", viaAttr: "SubnetId" },
+    { from: "westServer", to: "westSg", viaAttr: "SecurityGroupIds" },
+    { from: "westServer", to: "westSubnet", viaAttr: "SubnetId" },
+    { from: "privServer", to: "privSubnet", viaAttr: "SubnetId" },
+    { from: "pubAssoc", to: "pubSubnet", viaAttr: "SubnetId" },
+    { from: "pubAssoc", to: "pubRt", viaAttr: "RouteTableId" },
+    { from: "pubRoute", to: "pubRt", viaAttr: "RouteTableId" },
+    { from: "pubRoute", to: "igw", viaAttr: "GatewayId" },
+    { from: "westAssoc", to: "westSubnet", viaAttr: "SubnetId" },
+    { from: "westAssoc", to: "westRt", viaAttr: "RouteTableId" },
+    { from: "westRoute", to: "westRt", viaAttr: "RouteTableId" },
+    { from: "westRoute", to: "westIgw", viaAttr: "GatewayId" },
+  ] as never,
+  groups: {},
+};
+
+describe("enrichEffectiveTopology", () => {
+  const enriched = enrichEffectiveTopology(ir);
+  const attrs = (id: string) => enriched.nodes.find((n) => n.id === id)!.attrs as Record<string, unknown>;
+
+  it("resolves the security group reached VIA a launch template (the CLI-missed hop)", () => {
+    expect(attrs("ltServer").effectiveIngress).toContain("tcp:22:0.0.0.0/0");
+  });
+
+  it("resolves a direct security group", () => {
+    expect(attrs("webServer").effectiveIngress).toContain("tcp:22:0.0.0.0/0");
+  });
+
+  it("marks instances whose subnet routes to an IGW as internetFacing", () => {
+    expect(attrs("webServer").internetFacing).toBe(true);
+    expect(attrs("ltServer").internetFacing).toBe(true);
+    expect(attrs("westServer").internetFacing).toBe(true);
+    expect(attrs("privServer").internetFacing).toBe(false);
+  });
+
+  it("keeps a live-supplied internetFacing (e.g. default VPC) even with no declared route", () => {
+    // A live enrichment marks an instance internetFacing; its subnet's routing
+    // is not in the declared graph (the account's default VPC). Enrichment
+    // must NOT overwrite that truth back to false.
+    const withLive: GraphIR = {
+      nodes: [node("defaultVpcServer", "Instance", { internetFacing: true })] as never,
+      edges: [] as never,
+      groups: {},
+    };
+    const out = enrichEffectiveTopology(withLive);
+    expect((out.nodes[0].attrs as Record<string, unknown>).internetFacing).toBe(true);
+  });
+
+  it("SSH-reachable = internetFacing AND effectiveIngress tcp:22:0.0.0.0/0 → only web + lt", () => {
+    const reachable = enriched.nodes.filter(
+      (n) => (n.attrs as Record<string, unknown>).internetFacing === true &&
+        ((n.attrs as Record<string, unknown>).effectiveIngress as string[] | undefined)?.includes("tcp:22:0.0.0.0/0"),
+    );
+    expect(reachable.map((n) => n.id).sort()).toEqual(["ltServer", "webServer"]);
+  });
+});

package/src/graph-effective.ts

@@ -0,0 +1,116 @@
+import type { GraphIR, IRNode } from "./graph-ir";
+
+/**
+ * Fold DERIVED reachability facts onto EC2 instance nodes so a single-node query
+ * can answer questions that are otherwise a multi-hop join with a union (#1139).
+ *
+ * Two facts, both things a live AWS-CLI sweep gets wrong because it can't cheaply
+ * resolve the topology:
+ *
+ *  - `effectiveIngress` — the union of security-group ingress rules reachable
+ *    from the instance, BOTH directly (`SecurityGroupIds`) AND through its launch
+ *    template (`LaunchTemplate → LaunchTemplateData → SecurityGroupIds`). The
+ *    launch-template hop is exactly what a CLI agent misses (it under-counts
+ *    SSH-reachable instances). Each rule is normalized to `proto:port:cidr`
+ *    (e.g. `tcp:22:0.0.0.0/0`) so it is precisely queryable.
+ *  - `internetFacing` — whether the instance's subnet routes to an Internet
+ *    Gateway (`subnet ← SubnetRouteTableAssociation → RouteTable ← Route →
+ *    InternetGateway`). "Public subnet" means an IGW route, not
+ *    `MapPublicIpOnLaunch`.
+ *
+ * With these, "instances SSH-reachable from the internet" is one predicate:
+ *   `kind:EC2::Instance attr:internetFacing=true attr:effectiveIngress=tcp:22:0.0.0.0/0`
+ * — no hand-joined CLI sweep, no over/under-counting.
+ */
+export function enrichEffectiveTopology(ir: GraphIR): GraphIR {
+  const byId = new Map(ir.nodes.map((n) => [n.id, n]));
+  const edges = ir.edges ?? [];
+  const kind = (n?: IRNode): string => n?.kind ?? "";
+  const isKind = (n: IRNode | undefined, suffix: string): boolean =>
+    !!n && (kind(n) === suffix || kind(n).endsWith("::" + suffix));
+  const via = (...names: string[]) => (v: string): boolean => names.includes(v);
+
+  /** Out-neighbours of `id` (edges from → to), optionally filtered by viaAttr. */
+  const out = (id: string, pred?: (v: string) => boolean): IRNode[] =>
+    edges
+      .filter((e) => e.from === id && (!pred || pred(e.viaAttr ?? e.kind ?? "")))
+      .map((e) => byId.get(e.to))
+      .filter((x): x is IRNode => !!x);
+  /** In-neighbours of `id` (edges to ← from), optionally filtered by viaAttr. */
+  const incoming = (id: string, pred?: (v: string) => boolean): IRNode[] =>
+    edges
+      .filter((e) => e.to === id && (!pred || pred(e.viaAttr ?? e.kind ?? "")))
+      .map((e) => byId.get(e.from))
+      .filter((x): x is IRNode => !!x);
+
+  const normalizeIngress = (sg: IRNode): string[] => {
+    const rules = (sg.attrs as Record<string, unknown> | undefined)?.["SecurityGroupIngress"];
+    if (!Array.isArray(rules)) return [];
+    return rules.map((r) => {
+      const rule = r as Record<string, unknown>;
+      const proto = String(rule.IpProtocol ?? "-1");
+      const from = rule.FromPort as number | undefined;
+      const to = rule.ToPort as number | undefined;
+      const port = from == null ? "all" : from === to ? `${from}` : `${from}-${to}`;
+      const cidr =
+        (rule.CidrIp as string | undefined) ??
+        (rule.CidrIpv6 as string | undefined) ??
+        (rule.SourceSecurityGroupId ? `sg:${String(rule.SourceSecurityGroupId)}` : "?");
+      return `${proto}:${port}:${cidr}`;
+    });
+  };
+
+  /** Security groups reachable from an instance — direct and via launch template. */
+  const effectiveSgs = (inst: IRNode): IRNode[] => {
+    const direct = out(inst.id, via("SecurityGroupIds", "SecurityGroupId"));
+    const templates = out(inst.id, via("LaunchTemplate", "LaunchTemplateId"));
+    const viaTemplate = templates
+      .flatMap((lt) => out(lt.id, via("LaunchTemplateData", "SecurityGroupIds", "SecurityGroupId")))
+      .filter((n) => isKind(n, "SecurityGroup"));
+    const all = [...direct.filter((n) => isKind(n, "SecurityGroup")), ...viaTemplate];
+    return [...new Map(all.map((s) => [s.id, s])).values()];
+  };
+
+  /** The IGW an instance's subnet routes to (evidence), or undefined. */
+  const internetFacingVia = (inst: IRNode): string | undefined => {
+    for (const subnet of out(inst.id, via("SubnetId")).filter((n) => isKind(n, "Subnet"))) {
+      const assocs = incoming(subnet.id, via("SubnetId")).filter((a) => isKind(a, "SubnetRouteTableAssociation"));
+      const routeTables = assocs.flatMap((a) => out(a.id, via("RouteTableId")).filter((n) => isKind(n, "RouteTable")));
+      for (const rt of routeTables) {
+        const routes = incoming(rt.id, via("RouteTableId")).filter((n) => isKind(n, "Route"));
+        for (const route of routes) {
+          const dest = (route.attrs as Record<string, unknown> | undefined)?.["DestinationCidrBlock"];
+          const igw = out(route.id, via("GatewayId")).find((g) => isKind(g, "InternetGateway"));
+          if (igw && (dest == null || dest === "0.0.0.0/0")) {
+            const id = igw.id.includes("::") ? igw.id.slice(igw.id.lastIndexOf("::") + 2) : igw.id;
+            return `${rt.id.includes("::") ? rt.id.slice(rt.id.lastIndexOf("::") + 2) : rt.id} → ${id}`;
+          }
+        }
+      }
+    }
+    return undefined;
+  };
+
+  const nodes = ir.nodes.map((n) => {
+    if (!isKind(n, "Instance")) return n;
+    const effectiveIngress = effectiveSgs(n).flatMap(normalizeIngress);
+    // A live enrichment may already have set internetFacing (+ its evidence) for
+    // a subnet chant doesn't model declaratively (e.g. the account's default
+    // VPC). Keep that truth; otherwise derive it from the declared route topology.
+    const attrs = (n.attrs ?? {}) as Record<string, unknown>;
+    const liveFacing = attrs["internetFacing"] === true;
+    const declaredVia = internetFacingVia(n);
+    const via = (attrs["internetFacingVia"] as string | undefined) ?? declaredVia;
+    return {
+      ...n,
+      attrs: { ...attrs, effectiveIngress, internetFacing: liveFacing || !!declaredVia, ...(via ? { internetFacingVia: via } : {}) },
+    };
+  });
+  // Record what this pass computed, so a caller can report the graph's derived surface
+  // without hardcoding attribute names. Only kinds actually enriched are listed.
+  const enriched = nodes.some((n) => isKind(n, "Instance"));
+  const derivedAttrs = enriched
+    ? { ...(ir.derivedAttrs ?? {}), Instance: ["internetFacing", "effectiveIngress"] }
+    : ir.derivedAttrs;
+  return { ...ir, nodes, ...(derivedAttrs ? { derivedAttrs } : {}) };
+}

package/src/graph-ir.ts

@@ -191,6 +191,13 @@ export interface GraphIR {
   imports?: IRImport[];
   /** The CI/pipeline projection alongside the component graph (#989) — see {@link IRPipeline}. */
   pipeline?: IRPipeline;
+  /**
+   * Attributes chant computed rather than read back from the provider, keyed by the kind
+   * they were folded onto. An enrichment pass records what it derived here so callers can
+   * report the graph's own surface without knowing any attribute name — the set is whatever
+   * the passes produced, not a list maintained by hand.
+   */
+  derivedAttrs?: Record<string, string[]>;
 }
 
 /** A node is anything that serializes to a resource — not a property or output. */

package/src/lexicon.ts

@@ -608,6 +608,9 @@ export interface LexiconPlugin {
      * convention (AWS: the stack named after `environment`).
      */
     stack?: string;
+    /** AWS region the stack is in (multi-region). When set, the observation
+     * targets this region instead of the ambient one (#1161 follow-up). */
+    region?: string;
     /**
      * Restrict the result to chant-owned resources (those carrying the
      * ownership marker, #119). Where a lexicon has no durable marker channel,
@@ -695,7 +698,7 @@ export interface LexiconPlugin {
    * thin to carry references (e.g. AWS CloudFormation, where it's sourced from
    * the fuller `exportResources` config).
    */
-  enrichLiveAttrs?(options: { environment: string; stack?: string; owned?: boolean }): Promise<Record<string, Record<string, unknown>>>;
+  enrichLiveAttrs?(options: { environment: string; stack?: string; stacks?: Array<string | { name: string; region?: string }>; owned?: boolean }): Promise<Record<string, Record<string, unknown>>>;
 
   /**
    * List runtime artifacts in the given environment. Opt-in.
@@ -748,6 +751,8 @@ export interface LexiconPlugin {
      * keeps its single-stack convention (AWS: the stack named after
      * `environment`). */
     stack?: string;
+    /** AWS region the stack is in (multi-region estates). */
+    region?: string;
     selector?: ResourceSelector;
     owned?: boolean;
     verbatim?: boolean;

package/src/lifecycle/observe.test.ts

@@ -1,9 +1,25 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi } from "vitest";
 import { observeResources } from "./observe";
 import { observation } from "../observation";
 import type { ObservationLexicon, ResourceMetadata } from "../lexicon";
 import type { BuildResult } from "../build";
 
+// The per-stack scoped build (#1162) resolves each stack's `src` through the
+// real `build`. Mock it so the test controls what each src yields — a stack
+// whose src is scoped reports BARE entity names, matching the deployed
+// LogicalResourceIds, not the whole-project build's disambiguated names.
+const scopedBuilds: Record<string, string[]> = {};
+vi.mock("../build", () => ({
+  build: async (src: string): Promise<BuildResult> => {
+    const names = scopedBuilds[src] ?? [];
+    return {
+      outputs: new Map<string, string>([["aws", "{}"]]),
+      entities: new Map(names.map((n) => [n, { lexicon: "aws", entityType: "AWS::EC2::Instance", props: {} }])),
+      errors: [],
+    } as unknown as BuildResult;
+  },
+}));
+
 function mockBuild(): BuildResult {
   return {
     outputs: new Map<string, string>([["aws", "{}"]]),
@@ -154,7 +170,11 @@ describe("observeResources", () => {
       awsPlugin((opts) => {
         const stack = (opts as { stack?: string }).stack;
         calls.push(stack);
-        // Different resources per stack — the multi-stack, per-component case.
+        // Different resources per stack — the multi-stack, per-component case
+        // (#57 loomster). Bare-string stacks keep BARE ids (no `src` scope), so
+        // the union is `db-a`+`db-b`, not stack-qualified: per-component ids are
+        // already unique and behold reads them bare. Qualification is a scoped
+        // (`src`) feature — see the per-stack src test below.
         const resources: Record<string, ResourceMetadata> =
           stack === "s1"
             ? { "db-a": { type: "AWS::RDS::DBInstance", status: "AVAILABLE" } }
@@ -169,6 +189,50 @@ describe("observeResources", () => {
     expect(Object.keys(observations[0].resources).sort()).toEqual(["db-a", "db-b"]);
   });
 
+  it("with per-stack src (#1162): describeResources gets each stack's SCOPED bare names, not the whole-project build's names", async () => {
+    const { resolve } = await import("node:path");
+    // The whole-project build disambiguates colliding names by module path;
+    // each stack's scoped src reports the bare names it actually deploys.
+    scopedBuilds[resolve("east/src")] = ["server", "vpc"];
+    scopedBuilds[resolve("west/src")] = ["server", "vpc"];
+
+    const seen: Record<string, string[]> = {};
+    const plugins = [
+      awsPlugin((opts) => {
+        const o = opts as { stack?: string; entityNames: string[] };
+        seen[o.stack ?? "?"] = o.entityNames;
+        // Echo one resource keyed by a bare name the deployed stack owns.
+        return { server: { type: "AWS::EC2::Instance", status: "AVAILABLE", physicalId: `i-${o.stack}` } };
+      }),
+    ];
+    // The whole-project buildResult carries DISAMBIGUATED names — proving the
+    // scoped path overrides them rather than falling through to these.
+    const wholeProject = {
+      outputs: new Map<string, string>([["aws", "{}"]]),
+      entities: new Map([
+        ["EastServer", { lexicon: "aws", entityType: "AWS::EC2::Instance", props: {} }],
+        ["WestServer", { lexicon: "aws", entityType: "AWS::EC2::Instance", props: {} }],
+      ]),
+      errors: [],
+    } as unknown as BuildResult;
+
+    const { observations } = await observeResources("floci", plugins, wholeProject, {
+      stacks: [
+        { name: "east", src: "east/src" },
+        { name: "west", src: "west/src" },
+      ],
+    });
+
+    // Each stack saw its own scoped bare names (matching deployed ids).
+    expect(seen["east"]).toEqual(["server", "vpc"]);
+    expect(seen["west"]).toEqual(["server", "vpc"]);
+    // Observed nodes are stack-qualified, so the colliding `server` id is
+    // distinct per stack and each carries its own physical id.
+    expect(Object.keys(observations[0].resources).sort()).toEqual(["east::server", "west::server"]);
+    expect(observations[0].resources["east::server"].physicalId).toBe("i-east");
+    expect(observations[0].resources["west::server"].physicalId).toBe("i-west");
+  });
+
   it("with an empty stacks array — falls back to the single unstacked call", async () => {
     const calls: Array<{ stack?: string }> = [];
     const plugins = [

package/src/lifecycle/observe.ts

@@ -11,6 +11,8 @@
  */
 import type { ObservationLexicon } from "../lexicon";
 import type { BuildResult } from "../build";
+import { build as buildProject } from "../build";
+import { resolve as resolvePath } from "node:path";
 import type { SerializerResult } from "../serializer";
 import type { LiveObservation } from "../graph-ir";
 import {
@@ -28,6 +30,19 @@ export interface ObserveResult {
   errors: string[];
 }
 
+/**
+ * Re-key a normalized observation's entities by `${stack}::${id}` (#1162) so a
+ * bare LogicalResourceId shared across stacks (e.g. `vpc`) stays unambiguous
+ * once the per-stack results are merged. The declared canvas qualifies the same
+ * way (`buildDeclaredPerStack`), so the overlay join lines up. Applies to both
+ * the OBSERVED-PRESENT and NOT-OBSERVED maps of the tri-state (#1089).
+ */
+function qualifyObservation(obs: NormalizedObservation, stackName: string): NormalizedObservation {
+  const q = <T>(m: Record<string, T>): Record<string, T> =>
+    Object.fromEntries(Object.entries(m).map(([k, v]) => [`${stackName}::${k}`, v]));
+  return { resources: q(obs.resources), unobserved: q(obs.unobserved) };
+}
+
 /**
  * Query every plugin that implements `describeResources` for its resources in
  * `environment`. `owned` (default true for the managed-only diagram, epic #776)
@@ -44,20 +59,39 @@ export interface ObserveResult {
  * absent an explicit `stack`) queries a stack that simply doesn't exist there,
  * so the single-call path always observes zero nodes. When `stacks` is
  * present and non-empty, each observing plugin's `describeResources` is
- * called once per stack (same `environment`/`entities`/`entityNames`, only
- * `stack` varies) and the returned resource maps are unioned — a resource
- * appears under whichever stack contains its logical id. When `stacks` is
- * absent or empty, behavior is exactly the single call of before (no `stack`
- * key at all), so a single-stack project is unaffected.
+ * called once per stack and the returned observations are merged. A stack entry
+ * may be a bare name or `{ name, region?, src? }` (#1162): `src` is built
+ * SCOPED so the deployed BARE LogicalResourceIds match (the whole-project build
+ * disambiguates colliding names to `UsWest1Src…`, which the live ids never
+ * carry), and a scoped stack's observed ids are qualified `${stack}::${id}` so
+ * the same bare id in two stacks stays distinct. A bare-string stack keeps its
+ * bare ids and the tri-state merge (#57). When `stacks` is absent or empty, behavior is
+ * exactly the single call of before (no `stack` key at all), so a single-stack
+ * project is unaffected.
  */
 export async function observeResources(
   environment: string,
   plugins: ObservationLexicon[],
   buildResult: BuildResult,
-  opts?: { owned?: boolean; stacks?: string[] },
+  opts?: { owned?: boolean; stacks?: Array<string | { name: string; region?: string; src?: string }> },
 ): Promise<ObserveResult> {
   const owned = opts?.owned ?? true;
-  const stacks = opts?.stacks ?? [];
+  const stacks = (opts?.stacks ?? []).map((st) => (typeof st === "string" ? { name: st } : st));
+  // A stack's `src` (multi-stack, #1162) is built SCOPED to recover that stack's
+  // BARE entity names — the names it actually deploys. Matching deployed bare
+  // LogicalResourceIds against the whole-project build's DISAMBIGUATED names
+  // (UsWest1Src…) misses every colliding resource. Cached per src.
+  const serializers = plugins.map((p) => p.serializer);
+  const scopedBuildCache = new Map<string, BuildResult>();
+  const scopedBuild = async (src: string): Promise<BuildResult> => {
+    const key = resolvePath(src);
+    let r = scopedBuildCache.get(key);
+    if (!r) {
+      r = await buildProject(key, serializers);
+      scopedBuildCache.set(key, r);
+    }
+    return r;
+  };
   const observations: LiveObservation[] = [];
   const warnings: string[] = [];
   const errors: string[] = [];
@@ -91,18 +125,45 @@ export async function observeResources(
       if (stacks.length > 0) {
         const parts: NormalizedObservation[] = [];
         for (const stack of stacks) {
-          parts.push(
-            normalizeObservation(
-              await plugin.describeResources({
-                environment,
-                buildOutput,
-                entityNames,
-                entities,
-                owned,
-                stack,
-              }),
-            ),
+          // Use this stack's scoped build (bare entity names) when it has a src,
+          // so describeResources matches the deployed bare LogicalResourceIds.
+          let stackEntityNames = entityNames;
+          let stackBuildOutput = buildOutput;
+          let stackEntities = entities;
+          if (stack.src) {
+            const sb = await scopedBuild(stack.src);
+            stackEntityNames = [];
+            stackEntities = new Map();
+            for (const [name, entity] of sb.entities) {
+              if (entity.lexicon !== plugin.name) continue;
+              stackEntityNames.push(name);
+              stackEntities.set(name, {
+                entityType: entity.entityType,
+                props: ("props" in entity && entity.props != null ? entity.props : {}) as Record<string, unknown>,
+              });
+            }
+            const raw = sb.outputs.get(plugin.name);
+            stackBuildOutput = raw === undefined ? "" : typeof raw === "string" ? raw : (raw as SerializerResult).primary;
+          }
+          const norm = normalizeObservation(
+            await plugin.describeResources({
+              environment,
+              buildOutput: stackBuildOutput,
+              entityNames: stackEntityNames,
+              entities: stackEntities,
+              owned,
+              stack: stack.name,
+              region: stack.region,
+            }),
           );
+          // Qualify ids by stack ONLY for a scoped (`src`) stack (#1162): that
+          // is the multi-region case where the SAME bare LogicalResourceId
+          // (e.g. `vpc`) exists in every stack, so a bare union would collide.
+          // A bare-string stack (#57 loomster) has unique per-component ids and
+          // is asked the whole-project entity set, so it keeps the bare-id
+          // tri-state merge (present > not-observed > absent) that behold and
+          // other consumers read.
+          parts.push(stack.src ? qualifyObservation(norm, stack.name) : norm);
         }
         observed = mergeObservations(parts);
       } else {

package/src/observation.test.ts

@@ -5,14 +5,19 @@
 import { describe, test, expect } from "vitest";
 import {
   UNOBSERVED_REASONS,
+  boundedConcurrently,
   formatUnobserved,
   isObservationResult,
   isUnobservedReason,
   mergeObservations,
   normalizeObservation,
   observation,
+  observeEntities,
   unobservedAll,
   unobservedReasonText,
+  type DeclaredEntity,
+  type EntityObservation,
+  type ObserverAdapter,
 } from "./observation";
 import type { ResourceMetadata } from "./lexicon";
 
@@ -94,3 +99,133 @@ describe("reason totality", () => {
     ).toBe("widget (K8s::X::Widget) — no reader for this resource kind: no mapping");
   });
 });
+
+describe("boundedConcurrently", () => {
+  test("processes every item", async () => {
+    const seen: number[] = [];
+    await boundedConcurrently([1, 2, 3, 4, 5], async (n) => {
+      seen.push(n);
+    }, 2);
+    expect([...seen].sort((a, b) => a - b)).toEqual([1, 2, 3, 4, 5]);
+  });
+
+  test("never exceeds the limit in flight", async () => {
+    let inFlight = 0;
+    let peak = 0;
+    await boundedConcurrently(Array.from({ length: 20 }, (_, i) => i), async () => {
+      inFlight += 1;
+      peak = Math.max(peak, inFlight);
+      await new Promise((r) => setTimeout(r, 1));
+      inFlight -= 1;
+    }, 4);
+    expect(peak).toBeLessThanOrEqual(4);
+    expect(peak).toBeGreaterThan(1); // it did run concurrently, not serially
+  });
+
+  test("an empty list is a no-op", async () => {
+    await expect(boundedConcurrently([], async () => {})).resolves.toBeUndefined();
+  });
+});
+
+describe("observeEntities harness (#1201)", () => {
+  const entity = (name: string, type = "Fake::Resource"): DeclaredEntity => ({ name, type, props: {} });
+
+  /** A fake adapter whose `read` is table-driven by entity name. */
+  const adapterOf = (
+    reads: Record<string, EntityObservation | (() => Promise<EntityObservation>)>,
+    over: Partial<ObserverAdapter<{ ok: true }>> = {},
+  ): ObserverAdapter<{ ok: true }> => ({
+    bind: async () => ({ ok: true }),
+    classifyBindFailure: () => ({ reason: "read-failed" }),
+    read: async (_client, e) => {
+      const r = reads[e.name];
+      if (typeof r === "function") return r();
+      if (!r) throw new Error(`no fake read for ${e.name}`);
+      return r;
+    },
+    ...over,
+  });
+
+  test("routes the tri-state: present -> resources, absent -> neither, unobserved -> unobserved", async () => {
+    const result = await observeEntities(
+      [entity("a"), entity("b"), entity("c", "Fake::Odd")],
+      adapterOf({
+        a: { present: meta({ physicalId: "id-a" }) },
+        b: { absent: true },
+        c: { unobserved: { reason: "unsupported-kind", detail: "no reader" } },
+      }),
+    );
+    expect(Object.keys(result.resources)).toEqual(["a"]);
+    expect(result.resources.a.physicalId).toBe("id-a");
+    // absent 'b' is in neither map
+    expect(result.unobserved).toEqual({
+      c: { type: "Fake::Odd", reason: "unsupported-kind", detail: "no reader" },
+    });
+  });
+
+  test("a bind failure marks every entity NOT-OBSERVED with the typed reason and declared type", async () => {
+    const result = await observeEntities(
+      [entity("a", "AWS::S3::Bucket"), entity("b", "AWS::S3::Bucket")],
+      adapterOf(
+        {},
+        {
+          bind: async () => {
+            throw new Error("no creds");
+          },
+          classifyBindFailure: () => ({ reason: "no-credentials", detail: "token expired" }),
+        },
+      ),
+    );
+    expect(result.resources).toEqual({});
+    expect(result.unobserved).toEqual({
+      a: { reason: "no-credentials", type: "AWS::S3::Bucket", detail: "token expired" },
+      b: { reason: "no-credentials", type: "AWS::S3::Bucket", detail: "token expired" },
+    });
+  });
+
+  test("a loud refusal rethrows instead of degrading to a hole", async () => {
+    await expect(
+      observeEntities(
+        [entity("a")],
+        adapterOf(
+          {},
+          {
+            bind: async () => {
+              throw new Error("context mismatch");
+            },
+            classifyBindFailure: () => "rethrow",
+          },
+        ),
+      ),
+    ).rejects.toThrow("context mismatch");
+  });
+
+  test("a per-entity read throw degrades to read-failed for that one entity, not an absence", async () => {
+    const result = await observeEntities(
+      [entity("a"), entity("b")],
+      adapterOf({
+        a: () => Promise.reject(new Error("boom")),
+        b: { present: meta() },
+      }),
+    );
+    expect(Object.keys(result.resources)).toEqual(["b"]);
+    expect(result.unobserved?.a).toEqual({ type: "Fake::Resource", reason: "read-failed", detail: "boom" });
+  });
+
+  test("uses the adapter's own concurrency pool when it supplies one", async () => {
+    let usedPool = false;
+    await observeEntities(
+      [entity("a")],
+      adapterOf(
+        { a: { present: meta() } },
+        {
+          concurrently: async (items, fn) => {
+            usedPool = true;
+            for (const it of items) await fn(it);
+          },
+        },
+      ),
+    );
+    expect(usedPool).toBe(true);
+  });
+});