@intentius/chant 0.32.0 → 0.33.0

package/src/cli/handlers/search.ts

@@ -0,0 +1,263 @@
+import { resolve } from "node:path";
+import { build } from "../../build";
+import { buildGraphIr, buildLiveGraphIr, sourceOverlayGraphs, type GraphIR, type IRNode } from "../../graph-ir";
+import { buildDeclaredPerStack } from "../../graph-declared";
+import { enrichEffectiveTopology } from "../../graph-effective";
+import { discover } from "../../discovery/index";
+
+import { observeResources } from "../../lifecycle/observe";
+import { loadChantConfig } from "../../config";
+import { loadPlugins, resolveProjectLexicons } from "../plugins";
+import { formatError, formatWarning } from "../format";
+import type { CommandContext } from "../registry";
+
+/**
+ * `chant search <query> [--live --env <name>]` — answer an estate question with
+ * a COMPACT result instead of the whole graph. The point (measured on aws-bench,
+ * #1139): a small model shouldn't ingest a multi-thousand-token IR dump to answer
+ * "which instances are in public subnets" — it should query and get a few rows.
+ *
+ * Query grammar (space-separated terms, all must match — AND):
+ *   bare word            case-insensitive substring over id, kind, and attrs
+ *   kind:<substr>        node kind contains <substr> (e.g. kind:EC2::Instance)
+ *   tag:<key>=<val>      a Tags entry with Key=key and Value containing val
+ *   attr:<name>=<val>    attribute <name> equals/contains <val>
+ *   ->kind:X / ->attr:.. this node has an edge TO a node matching the right side
+ *   <-kind:X / <-attr:.. this node has an edge FROM a node matching the right side
+ *
+ * The edge operators are the point of "edge-aware" search (#1139): a small
+ * model shouldn't hand-join instance→subnet→public across many results — one
+ * query does the traversal. `kind:Instance ->attr:MapPublicIpOnLaunch=true`
+ * = instances that reference a public subnet.
+ *
+ * Output: one line per match — `<id>  <kind>  <key=val ...>` — with only the
+ * physical id and any attributes named in `attr:`/`--show`. Tens of tokens, not
+ * thousands.
+ */
+export async function runSearch(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const query = (args.path ?? "").trim();
+  if (!query) {
+    console.error(formatError({ message: "chant search needs a query: chant search \"<terms>\" [--live --env <name>]" }));
+    return 1;
+  }
+  const terms = parseQuery(query);
+  const show = parseShow(args);
+
+  const projectPath = resolve(".");
+  const { config } = await loadChantConfig(projectPath);
+
+  let ir: GraphIR;
+  if (args.live) {
+    const environment = args.env;
+    if (!environment) {
+      console.error(formatError({ message: "chant search --live needs an environment: --live --env <name>" }));
+      return 1;
+    }
+    if (config.environments && !config.environments.includes(environment)) {
+      console.error(formatError({ message: `Unknown environment "${environment}"` }));
+      return 1;
+    }
+    const plugins = ctx.plugins.length > 0 ? ctx.plugins : await loadPlugins(await resolveProjectLexicons(projectPath));
+    const buildResult = await build(resolve(args.src ?? config.sourceDir ?? "."), plugins.map((p) => p.serializer));
+    if (buildResult.errors.length > 0) {
+      console.error(formatError({ message: "Build failed — fix errors before searching live state" }));
+      return 1;
+    }
+    const observing = plugins.filter((p) => p.describeResources);
+    const stacks = (config.stacks ?? []).map((s) => ({ name: s.name, region: s.region, src: s.src }));
+    const { observations, errors } = await observeResources(environment, observing, buildResult, {
+      owned: true,
+      stacks,
+    });
+    for (const e of errors) console.error(formatWarning({ message: e }));
+    let live = buildLiveGraphIr(observations);
+    const liveAttrs: Record<string, Record<string, unknown>> = {};
+    for (const p of observing) {
+      if (!p.enrichLiveAttrs) continue;
+      try {
+        const enriched = await p.enrichLiveAttrs({ environment, owned: true, stacks });
+        for (const [id, a] of Object.entries(enriched)) liveAttrs[id] = { ...liveAttrs[id], ...a };
+        live = { ...live, nodes: live.nodes.map((n) => (enriched[n.id] ? { ...n, attrs: { ...n.attrs, ...enriched[n.id] } } : n)) };
+      } catch {
+        /* enrichment is best-effort; search still works on describe attrs */
+      }
+    }
+    // Overlay live identity onto the SOURCE graph (same as `graph --overlay`):
+    // the declared graph is the canvas — its edges carry the topology so ->/<-
+    // resolves, while the live side supplies physical ids.
+    //
+    // Multi-stack (#1162): build the declared graph PER STACK (scoped to each
+    // stack's src, the way it deploys) and stack-qualify node ids + edges as
+    // `${stack}::${id}` — matching how observation qualifies. A flat whole-
+    // project discovery would disambiguate colliding names by module path
+    // (UsEast1Src…), which never matches the observed bare LogicalResourceIds.
+    const declared =
+      stacks.length > 0
+        ? await buildDeclaredPerStack(stacks, projectPath)
+        : buildGraphIr((await discover(resolve(args.src ?? config.sourceDir ?? "."))).entities, projectPath);
+    ir = sourceOverlayGraphs(declared, live);
+    // Carry live-derived attrs onto the declared canvas — some facts only exist
+    // in live account state (e.g. `internetFacing` for an instance in the
+    // account's default VPC, whose route table chant does not model). The
+    // overlay copies physical identity but not attrs, so merge them here.
+    ir = { ...ir, nodes: ir.nodes.map((n) => (liveAttrs[n.id] ? { ...n, attrs: { ...n.attrs, ...liveAttrs[n.id] } } : n)) };
+  } else {
+    const discovered = await discover(resolve(args.src ?? config.sourceDir ?? "."));
+    ir = buildGraphIr(discovered.entities);
+  }
+
+  // Fold derived reachability facts (effectiveIngress, internetFacing) onto
+  // instance nodes so multi-hop/launch-template joins are one node predicate (#1139).
+  ir = enrichEffectiveTopology(ir);
+  const nodeById = new Map(ir.nodes.map((n) => [n.id, n]));
+  const matches = ir.nodes.filter((n) => terms.every((t) => matchTerm(n, t, ir, nodeById)));
+  if (matches.length === 0) {
+    console.log("(no matches)");
+    if (args.explain) explain(terms, matches, ir, nodeById, query);
+    return 0;
+  }
+  for (const n of matches) {
+    console.log(formatRow(n, show));
+  }
+  if (args.explain) explain(terms, matches, ir, nodeById, query);
+  return 0;
+}
+
+/**
+ * `--explain` footer (#1139): a compact, model-DERIVED summary that gives a
+ * small model a reason to trust the result instead of re-deriving it with a
+ * lossy CLI sweep. It reports the universe count ("4 of 6 Instances") — chant's
+ * structural edge, since the typed graph knows the denominator a live sweep
+ * doesn't — and, for the near-miss set, WHY each was excluded (which query term
+ * it fails). Everything here is a property of the query over the graph, not of
+ * any expected answer, so it stays a fair, question-agnostic capability.
+ */
+function explain(terms: Term[], matches: IRNode[], ir: GraphIR, byId: Map<string, IRNode>, query: string): void {
+  const kinds = new Set(matches.map((n) => n.kind).filter((k): k is string => !!k));
+  const universe = kinds.size > 0 ? ir.nodes.filter((n) => n.kind && kinds.has(n.kind)) : ir.nodes;
+  const matched = new Set(matches.map((n) => n.id));
+  const excluded = universe.filter((n) => !matched.has(n.id));
+  const kindLabel = kinds.size > 0 ? [...kinds].join("/") : "nodes";
+  console.log(`— ${matches.length} of ${universe.length} ${kindLabel} matched  (query: ${query})`);
+  // Inclusion evidence: for a derived fact a CLI can't easily re-verify
+  // (internetFacing, resolved across the default VPC's routing), name WHY each
+  // match qualifies, so the agent trusts the result instead of dropping it.
+  if (terms.some((t) => t.kind === "attr" && t.a === "internetFacing")) {
+    for (const n of matches) {
+      const via = (n.attrs as Record<string, unknown> | undefined)?.["internetFacingVia"];
+      const id = n.id.includes("::") ? n.id.slice(n.id.lastIndexOf("::") + 2) : n.id;
+      if (typeof via === "string") console.log(`  ✓ ${id} internet-facing via ${via}`);
+    }
+  }
+  const shown = excluded.slice(0, 8);
+  for (const n of shown) {
+    const failing = terms.find((t) => !matchTerm(n, t, ir, byId));
+    const id = n.id.includes("::") ? n.id.slice(n.id.lastIndexOf("::") + 2) : n.id;
+    console.log(`  · excluded ${id} — fails ${failing ? describeTerm(failing) : "(query)"}`);
+  }
+  if (excluded.length > shown.length) console.log(`  · …and ${excluded.length - shown.length} more excluded`);
+}
+
+function describeTerm(t: Term): string {
+  const leaf = (x: Term): string =>
+    x.kind === "kind" ? `kind:${x.a}` : x.kind === "attr" ? `attr:${x.a}${x.b !== undefined ? "=" + x.b : ""}`
+      : x.kind === "tag" ? `tag:${x.a}${x.b !== undefined ? "=" + x.b : ""}` : `"${x.a}"`;
+  if (t.kind === "edge" && t.sub) return `${t.dir === "out" ? "→" : "←"}${leaf(t.sub)} (no such edge)`;
+  return leaf(t);
+}
+
+interface Term {
+  kind: "word" | "kind" | "tag" | "attr" | "edge";
+  a: string;
+  b?: string;
+  /** For edge terms: the direction and the sub-predicate matched at the far end. */
+  dir?: "out" | "in";
+  sub?: Term;
+}
+
+function parseLeaf(tok: string): Term {
+  const m = /^(kind|tag|attr):(.*)$/i.exec(tok);
+  if (m) {
+    const key = m[1].toLowerCase() as Term["kind"];
+    const rest = m[2];
+    const eq = rest.indexOf("=");
+    if (eq >= 0) return { kind: key, a: rest.slice(0, eq), b: rest.slice(eq + 1) };
+    return { kind: key, a: rest };
+  }
+  return { kind: "word", a: tok };
+}
+
+function parseQuery(query: string): Term[] {
+  // Split on whitespace but keep quoted phrases together.
+  const tokens = query.match(/"[^"]*"|\S+/g) ?? [];
+  return tokens.map((raw) => {
+    const tok = raw.replace(/^"|"$/g, "");
+    if (tok.startsWith("->")) return { kind: "edge", a: "", dir: "out", sub: parseLeaf(tok.slice(2)) };
+    if (tok.startsWith("<-")) return { kind: "edge", a: "", dir: "in", sub: parseLeaf(tok.slice(2)) };
+    return parseLeaf(tok);
+  });
+}
+
+function parseShow(args: { show?: string }): string[] {
+  return args.show ? args.show.split(",").map((s) => s.trim()).filter(Boolean) : [];
+}
+
+function attrString(v: unknown): string {
+  if (v == null) return "";
+  if (typeof v === "object") {
+    // AttrRef placeholder ({$ref}) or nested — stringify shallowly.
+    return JSON.stringify(v);
+  }
+  return String(v);
+}
+
+function matchTerm(n: IRNode, t: Term, ir?: GraphIR, byId?: Map<string, IRNode>): boolean {
+  const attrs = n.attrs ?? {};
+  if (t.kind === "edge") {
+    if (!ir || !byId || !t.sub) return false;
+    // A node matches if it has an edge (out or in) to a node satisfying `sub`.
+    const edges = ir.edges ?? [];
+    const neighbors = edges
+      .filter((e) => (t.dir === "out" ? e.from === n.id : e.to === n.id))
+      .map((e) => byId.get(t.dir === "out" ? e.to : e.from))
+      .filter((x): x is IRNode => !!x);
+    return neighbors.some((m) => matchTerm(m, t.sub!, ir, byId));
+  }
+  if (t.kind === "kind") return (n.kind ?? "").toLowerCase().includes(t.a.toLowerCase());
+  if (t.kind === "attr") {
+    const val = attrString((attrs as Record<string, unknown>)[t.a]);
+    return t.b === undefined ? t.a in attrs : val.toLowerCase().includes(t.b.toLowerCase());
+  }
+  if (t.kind === "tag") {
+    const tags = (attrs as Record<string, unknown>)["Tags"];
+    if (!Array.isArray(tags)) return false;
+    return tags.some((tag) => {
+      const key = attrString((tag as Record<string, unknown>)?.Key);
+      const val = attrString((tag as Record<string, unknown>)?.Value);
+      return key.toLowerCase() === t.a.toLowerCase() && (t.b === undefined || val.toLowerCase().includes(t.b.toLowerCase()));
+    });
+  }
+  // bare word: substring over id, kind, and all attr values
+  const hay = [n.id, n.kind, ...Object.values(attrs).map(attrString)].join(" ").toLowerCase();
+  return hay.includes(t.a.toLowerCase());
+}
+
+function formatRow(n: IRNode, show: string[]): string {
+  const attrs = (n.attrs ?? {}) as Record<string, unknown>;
+  // Display the bare logical id, not the `${stack}::` qualification (#1162).
+  const displayId = n.id.includes("::") ? n.id.slice(n.id.lastIndexOf("::") + 2) : n.id;
+  const parts: string[] = [displayId, n.kind ?? ""];
+  // Prefer the node-level live physicalId (set by the overlay), then attrs;
+  // skip source-mode AttrRef placeholders (objects).
+  const physical = (n as { physicalId?: unknown }).physicalId ?? attrs["physicalId"] ?? attrs["InstanceId"] ?? attrs["Id"];
+  if (physical != null && typeof physical !== "object") parts.push(String(physical));
+  for (const key of show) {
+    const v = attrs[key];
+    if (v != null && typeof v !== "object") parts.push(`${key}=${attrString(v)}`);
+  }
+  return parts.filter(Boolean).join("  ");
+}
+
+/** Internals exposed for unit tests. */
+export const __searchInternals = { parseQuery, matchTerm, formatRow, explain, describeTerm };

package/src/cli/main.ts

@@ -25,6 +25,7 @@ import { runCarveApply } from "./handlers/carve-apply";
 import { runLifecycleSnapshot, runLifecycleShow, runLifecycleDiff, runLifecycleRollback, runLifecyclePlan, runLifecycleAffected, runLifecycleLog, runLifecycleUnknown } from "./handlers/lifecycle";
 import { runComponentsStatus, runComponentsReleaseRecord, runComponentsUnknown } from "./handlers/components";
 import { runGraph } from "./handlers/graph";
+import { runSearch } from "./handlers/search";
 import { runOp, runOpList, runOpStatus, runOpSignal, runOpCancel, runOpLog } from "./handlers/run";
 import { runEmulator } from "./handlers/emulator";
 import { splitJoinedFlags, dispatchCommandGroup, collectCommandGroups, formatCommandGroupsHelp, type CommandGroup } from "./command-group";
@@ -49,6 +50,7 @@ const BOOLEAN_FLAGS = new Set([
   "--verbose",
   "--live",
   "--overlay",
+  "--explain",
   "--owned",
   "--verbatim",
   "--apply-rewrites",
@@ -241,6 +243,10 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.detail = Number(args[++i]);
     } else if (arg === "--lens") {
       result.lens = args[++i];
+    } else if (arg === "--explain") {
+      result.explain = true;
+    } else if (arg === "--show") {
+      result.show = args[++i];
     } else if (arg === "--up") {
       result.up = true;
     } else if (arg === "--down") {
@@ -662,6 +668,7 @@ const registry: CommandDef[] = [
   { name: "lint", handler: runLint },
   { name: "list", handler: runList },
   { name: "describe", handler: runDescribe },
+  { name: "search", handler: runSearch },
   { name: "import", handler: runImport },
   { name: "audit", handler: runAudit },
   { name: "migrate", handler: runMigrate },

package/src/cli/registry.ts

@@ -95,6 +95,10 @@ export interface ParsedArgs {
   detail?: number;
   /** `chant graph --lens <kind>:<target>` — focus the graph IR on a slice */
   lens?: string;
+  /** `chant search --show a,b` — extra attributes to include per matched row (#1139). */
+  show?: string;
+  /** `chant search --explain` — append a footer: universe count + why non-matches were excluded (#1139). */
+  explain?: boolean;
   /** `chant graph --lens blast:<node> --up` — include upstream producers */
   up?: boolean;
   /** `chant graph --lens blast:<node> --down` — include downstream dependents */

package/src/config.ts

@@ -172,6 +172,9 @@ export interface ChantConfig {
     name: string;
     /** Source directory to build for this stack, relative to the project root. */
     src: string;
+    /** AWS region this stack is deployed in (multi-region estates). When set,
+     * observation/enrichment target this region instead of the ambient one. */
+    region?: string;
   }>;
 
   /** Lint configuration (rules, extends, overrides, plugins) */

package/src/graph-declared.ts

@@ -0,0 +1,33 @@
+import { resolve } from "node:path";
+import { discover } from "./discovery/index";
+import { buildGraphIr, type GraphIR, type IRNode } from "./graph-ir";
+
+/**
+ * Build the DECLARED graph for a multi-stack project, scoped per stack (#1162).
+ *
+ * A whole-project discovery disambiguates colliding logical names by module path
+ * (two `server`s become `UsEast1Srcserver` / `UsWest1Srcserver`) — names that
+ * never appear in any deployed template, because each stack deploys its OWN
+ * scoped source with BARE LogicalResourceIds. Observation therefore keys live
+ * nodes by `${stack}::${logicalId}` (bare id). To make the declared side join
+ * that live side, build each stack's `src` in isolation and qualify its node ids
+ * and edge endpoints the same way. Stacks are merged into one graph.
+ *
+ * A stack without `src` contributes nothing here — it has no declared source to
+ * scope to (its live nodes still show as foreign in the overlay).
+ */
+export async function buildDeclaredPerStack(
+  stacks: Array<{ name: string; src?: string }>,
+  projectPath: string,
+): Promise<GraphIR> {
+  const nodes: IRNode[] = [];
+  const edges: GraphIR["edges"] = [];
+  for (const st of stacks) {
+    if (!st.src) continue;
+    const g = buildGraphIr((await discover(resolve(projectPath, st.src))).entities, projectPath);
+    const q = (id: string) => `${st.name}::${id}`;
+    for (const n of g.nodes) nodes.push({ ...n, id: q(n.id) });
+    for (const e of g.edges) edges.push({ ...e, from: q(e.from), to: q(e.to) });
+  }
+  return { nodes, edges, groups: {} };
+}

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,110 @@
+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 } : {}) },
+    };
+  });
+  return { ...ir, nodes };
+}

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;