@intentius/chant 0.33.1 → 0.34.0

package/src/codegen/release-wiring.test.ts

@@ -80,3 +80,95 @@ describe("release wiring: justfile tags vs publish.yml trigger", () => {
     expect(examples).toContain("lexicon-docker-v9.9.9");
   });
 });
+
+/**
+ * The body of one justfile recipe, up to the next top-level recipe header.
+ * Line-based on purpose: a recipe header sits at column 0 and every body line
+ * is indented, which a regex over the whole file gets wrong (`^` under /m
+ * matches the start of the slice too).
+ */
+const RECIPE_HEADER = /^[a-z_][a-z0-9_-]*(\s+[^:]*)?:/;
+
+function recipeBody(name: string): string {
+  const lines = readFileSync(join(repoRoot, "justfile"), "utf-8").split("\n");
+  const start = lines.findIndex((l) => new RegExp(`^${name}(\\s|:)`).test(l));
+  if (start === -1) throw new Error(`justfile: recipe "${name}" not found`);
+
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (RECIPE_HEADER.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join("\n");
+}
+
+/**
+ * #1255.2 — `just release` rewrites the `@intentius/*` peer ranges alongside
+ * `.version` (added in #411, because ranges frozen at `^0.1.0` break clean
+ * installs). `release-lexicon` only set `.version`, so a single-lexicon patch
+ * needing a newer core silently shipped a stale range.
+ *
+ * The two recipes pin to different things on purpose: a whole-repo release
+ * moves everything together so `^$next` is right, while a single-lexicon
+ * patch leaves core where it is, so the range must track the CURRENT core
+ * version. Pinning it to `$next` would demand a core that does not exist —
+ * which is why this asserts the mechanism, not a shared literal.
+ */
+describe("release wiring: peer ranges stay in lockstep (#1255)", () => {
+  it("the whole-repo release rewrites both @intentius peer ranges", () => {
+    const body = recipeBody("release");
+    expect(body).toMatch(/peerDependencies\["@intentius\/chant"\]/);
+    expect(body).toMatch(/peerDependencies\["@intentius\/chant-lexicon-github"\]/);
+  });
+
+  it("the single-lexicon release rewrites them too", () => {
+    const body = recipeBody("release-lexicon");
+    expect(
+      body.includes('peerDependencies["@intentius/chant"]'),
+      "release-lexicon sets .version without touching the @intentius/chant peer range — " +
+        "a lexicon patch that needs a newer core would ship a stale range (#411, #1255)",
+    ).toBe(true);
+    expect(body).toMatch(/peerDependencies\["@intentius\/chant-lexicon-github"\]/);
+  });
+
+  it("the single-lexicon release pins peers to core, not to its own new version", () => {
+    const body = recipeBody("release-lexicon");
+    // It reads the current core version rather than reusing $next.
+    expect(body).toMatch(/jq -r \.version packages\/core\/package\.json/);
+    expect(
+      /peerDependencies\["@intentius\/chant"\]\s*=\s*"\^"\s*\+\s*\$next/.test(body),
+      "release-lexicon must not pin the core peer range to the lexicon's own new version",
+    ).toBe(false);
+  });
+
+  it("both recipes keep the committed lockfile in step", () => {
+    for (const recipe of ["release", "release-lexicon"]) {
+      expect(recipeBody(recipe)).toMatch(/npm install --package-lock-only/);
+    }
+  });
+});
+
+/**
+ * #1255.3 — both recipes pushed the bump commit straight to main, bypassing
+ * branch protection, so a release tag could point at a commit CI never ran.
+ */
+describe("release wiring: preflight gates both recipes (#1255)", () => {
+  it("every release recipe runs the preflight before tagging", () => {
+    for (const recipe of ["release", "release-lexicon"]) {
+      const body = recipeBody(recipe);
+      expect(
+        body.includes("scripts/release-preflight.sh"),
+        `justfile recipe "${recipe}" tags and pushes without running the preflight — ` +
+          "it could release a commit CI never ran (#1255)",
+      ).toBe(true);
+      // Ordering matters: a check that runs after `git tag` proves nothing.
+      expect(body.indexOf("scripts/release-preflight.sh")).toBeLessThan(body.indexOf("git tag"));
+    }
+  });
+
+  it("the whole-repo release requires main, since it pushes main", () => {
+    expect(recipeBody("release")).toMatch(/release-preflight\.sh main/);
+  });
+});

package/src/graph-ir-live.test.ts

@@ -157,6 +157,34 @@ describe("sourceOverlayGraphs (#821 source-anchored overlay)", () => {
     expect(vpc.ownership).toBe("owned");
   });
 
+  it("carries observed attributes onto a managed declared node (#1279)", () => {
+    // Before this, the overlay copied identity but dropped everything observed
+    // ABOUT the resource, so a fact that only exists in the account — an
+    // instance's VpcId — was unreachable from the overlaid graph and
+    // `search --show VpcId` printed a blank column.
+    const observed: GraphIR = {
+      ...live,
+      nodes: live.nodes.map((x) => (x.id === "web-vpc" ? { ...x, attrs: { CidrBlock: "10.0.0.0/16" } } : x)),
+    };
+    const vpc = sourceOverlayGraphs(declared, observed).nodes.find((x) => x.id === "web-vpc")!;
+    expect(vpc.attrs.CidrBlock).toBe("10.0.0.0/16");
+  });
+
+  it("lets an observed value beat the declared one of the same name (#1279)", () => {
+    // The declared side holds an unresolved reference to another entity; the
+    // account holds the id it actually resolved to.
+    const withRef: GraphIR = {
+      ...declared,
+      nodes: declared.nodes.map((x) => (x.id === "web-vpc" ? { ...x, attrs: { VpcId: "${vpc.id}" } } : x)),
+    };
+    const observed: GraphIR = {
+      ...live,
+      nodes: live.nodes.map((x) => (x.id === "web-vpc" ? { ...x, attrs: { VpcId: "vpc-0a1b" } } : x)),
+    };
+    const vpc = sourceOverlayGraphs(withRef, observed).nodes.find((x) => x.id === "web-vpc")!;
+    expect(vpc.attrs.VpcId).toBe("vpc-0a1b");
+  });
+
   it("appends foreign nodes with their live edges, and keeps declared groups", () => {
     const ir = sourceOverlayGraphs(declared, live);
     expect(ir.nodes.map((x) => x.id)).toContain("rogue-sg");
@@ -208,3 +236,58 @@ describe("collectUnobserved (#1089)", () => {
     ).toEqual({ a: { reason: "read-failed" }, b: { reason: "no-binding" } });
   });
 });
+
+// #1271 — an observation can report relationships, not just existence. Without
+// these the live side of the graph has no edges, so a topology fold has nothing
+// to traverse and a lexicon has to compute derived answers itself.
+describe("observed edges (#1271)", () => {
+  const twoNodes = {
+    lexicon: "aws",
+    resources: {
+      "app-subnet": { type: "AWS::EC2::Subnet", status: "CREATE_COMPLETE", physicalId: "subnet-0c2d" },
+      "web-vpc": { type: "AWS::EC2::VPC", status: "CREATE_COMPLETE", physicalId: "vpc-0a1b" },
+    },
+  } satisfies LiveObservation;
+
+  it("projects an observed edge between two observed nodes", () => {
+    const ir = buildLiveGraphIr([
+      { ...twoNodes, edges: [{ from: "app-subnet", to: "web-vpc", kind: "ref", viaAttr: "VpcId" }] },
+    ]);
+    expect(ir.edges).toEqual([{ from: "app-subnet", to: "web-vpc", kind: "ref", viaAttr: "VpcId" }]);
+  });
+
+  it("no edges reported → no edges, unchanged from before", () => {
+    expect(buildLiveGraphIr([twoNodes]).edges).toEqual([]);
+  });
+
+  it("drops an edge whose endpoint was never observed", () => {
+    // A dangling reference would traverse to nothing during a fold, which reads
+    // as "no such relationship" rather than "the other end was not read".
+    const ir = buildLiveGraphIr([
+      { ...twoNodes, edges: [{ from: "app-subnet", to: "never-read", kind: "ref", viaAttr: "VpcId" }] },
+    ]);
+    expect(ir.edges).toEqual([]);
+  });
+
+  it("dedupes identical edges reported by more than one observation", () => {
+    const edge = { from: "app-subnet", to: "web-vpc", kind: "ref" as const, viaAttr: "VpcId" };
+    const ir = buildLiveGraphIr([
+      { ...twoNodes, edges: [edge] },
+      { ...twoNodes, edges: [edge] },
+    ]);
+    expect(ir.edges).toHaveLength(1);
+  });
+
+  it("orders edges deterministically — the IR is compared and committed", () => {
+    const ir = buildLiveGraphIr([
+      {
+        ...twoNodes,
+        edges: [
+          { from: "web-vpc", to: "app-subnet", kind: "ref", viaAttr: "Z" },
+          { from: "app-subnet", to: "web-vpc", kind: "ref", viaAttr: "A" },
+        ],
+      },
+    ]);
+    expect(ir.edges?.map((e) => e.from)).toEqual(["app-subnet", "web-vpc"]);
+  });
+});

package/src/graph-ir.ts

@@ -489,6 +489,20 @@ export interface LiveObservation {
    * overlay must not paint them "pending". See {@link sourceOverlayGraphs}.
    */
   unobserved?: Record<string, UnobservedEntity>;
+  /**
+   * Relationships the lexicon observed between the resources it read (#1271).
+   *
+   * Without these an observation can only say what exists, never how it
+   * connects — so a fold over topology has nothing to traverse on the live side
+   * and a lexicon has to compute derived answers itself and inject them as
+   * attributes. Reporting the edges instead lets the one graph fold in
+   * {@link import("./graph-effective").enrichEffectiveTopology} do the work,
+   * for every lexicon, over live and recorded observations alike.
+   *
+   * `from`/`to` are node ids in the same space as {@link LiveObservation.resources}
+   * keys, so an edge can only reference something the observation also reported.
+   */
+  edges?: IREdge[];
 }
 
 /**
@@ -540,7 +554,31 @@ export function buildLiveGraphIr(observations: LiveObservation[]): GraphIR {
   if (Object.keys(byLexicon).length) groups.byLexicon = sortKeys(byLexicon);
   if (Object.keys(byStack).length) groups.byStack = sortKeys(byStack);
 
-  return { nodes, edges: [], groups };
+  // Observed relationships (#1271). An edge whose endpoints were not both
+  // observed is dropped rather than kept as a dangling reference: the fold
+  // resolves ids to nodes, and a half-edge would silently traverse to nothing.
+  // Deduped and sorted for the same reason nodes are — the IR is compared and
+  // committed, so it has to be stable across reads.
+  const observedIds = new Set(nodes.map((n) => n.id));
+  const seen = new Set<string>();
+  const edges: IREdge[] = [];
+  for (const observation of observations) {
+    for (const edge of observation.edges ?? []) {
+      if (!observedIds.has(edge.from) || !observedIds.has(edge.to)) continue;
+      const key = `${edge.from}${edge.to}${edge.viaAttr ?? ""}${edge.toAttr ?? ""}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      edges.push(edge);
+    }
+  }
+  edges.sort(
+    (a, b) =>
+      a.from.localeCompare(b.from) ||
+      a.to.localeCompare(b.to) ||
+      (a.viaAttr ?? "").localeCompare(b.viaAttr ?? ""),
+  );
+
+  return { nodes, edges, groups };
 }
 
 /** How an overlay learns which declared nodes were never looked at (#1089). */
@@ -647,6 +685,18 @@ export function sourceOverlayGraphs(declared: GraphIR, live: GraphIR, opts?: Ove
     const merged: IRNode = { ...n }; // managed — carry the observed identity
     if (obs.physicalId) merged.physicalId = obs.physicalId;
     if (obs.ownership) merged.ownership = obs.ownership;
+    // ...and what was observed ABOUT it (#1279). The declared canvas holds what
+    // the source says; the observation holds what the account says, and a fact
+    // like `VpcId` exists only on the second. Dropping it here made every
+    // observed property invisible to anything reading the overlaid graph —
+    // `search --show VpcId` printed six blank columns, which reads as an estate
+    // with no VPCs rather than a read that never happened.
+    //
+    // Observed wins a collision. The declared value for something like `VpcId`
+    // is an unresolved reference to another entity, not an id — the account has
+    // the id. Same precedence `enrichLiveAttrs` already uses when it folds live
+    // facts onto this graph, so both paths agree on what a name means.
+    if (obs.attrs && Object.keys(obs.attrs).length > 0) merged.attrs = { ...n.attrs, ...obs.attrs };
     return tagStatus(merged, "good");
   });
   for (const n of live.nodes) {

package/src/graph-refs.test.ts

@@ -129,3 +129,62 @@ describe("mergeCatalogs", () => {
     expect(m.refs).toHaveLength(1);
   });
 });
+
+// #1275 — `viaAttr` defaulted to `label ?? path`, which serves a renderer and
+// starves a traversal: the catalog's labels are human-facing ("sg", "via")
+// while a fold matches provider attribute names ("SecurityGroupIds").
+describe("traversal name vs rendering label (#1275)", () => {
+  const nodes: IRNode[] = [
+    { id: "web", kind: "AWS::EC2::Instance", lexicon: "aws", attrs: { SubnetId: "subnet-1", SecurityGroups: [{ GroupId: "sg-1" }] } },
+    { id: "sub", kind: "AWS::EC2::Subnet", lexicon: "aws", attrs: { SubnetId: "subnet-1" } },
+    { id: "sg", kind: "AWS::EC2::SecurityGroup", lexicon: "aws", attrs: { GroupId: "sg-1" } },
+  ];
+  const identities = [
+    { kind: "AWS::EC2::Subnet", ids: ["SubnetId"] },
+    { kind: "AWS::EC2::SecurityGroup", ids: ["GroupId"] },
+  ];
+
+  it("viaAttr wins over label, so the fold can match the attribute name", () => {
+    const { edges } = reconstructEdges(nodes, {
+      identities,
+      refs: [
+        { from: "AWS::EC2::Instance", path: "SecurityGroups[].GroupId", targetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg", viaAttr: "SecurityGroupIds" },
+      ],
+    });
+    expect(edges).toEqual([{ from: "web", to: "sg", kind: "ref", viaAttr: "SecurityGroupIds" }]);
+  });
+
+  it("without viaAttr the label still wins, unchanged", () => {
+    const { edges } = reconstructEdges(nodes, {
+      identities,
+      refs: [
+        { from: "AWS::EC2::Instance", path: "SecurityGroups[].GroupId", targetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg" },
+      ],
+    });
+    expect(edges[0].viaAttr).toBe("sg");
+  });
+
+  it("a containment rule with viaAttr yields both the boundary pair and a traversable edge", () => {
+    // An instance is *in* a subnet — a boundary for the picture, and the first
+    // hop of internetFacing. It has to be both without being drawn twice.
+    const { edges, containment } = reconstructEdges(nodes, {
+      identities,
+      refs: [
+        { from: "AWS::EC2::Instance", path: "SubnetId", targetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet", viaAttr: "SubnetId" },
+      ],
+    });
+    expect(containment).toEqual([{ child: "web", parent: "sub", label: "in subnet" }]);
+    expect(edges).toEqual([{ from: "web", to: "sub", kind: "ref", viaAttr: "SubnetId" }]);
+  });
+
+  it("a containment rule without viaAttr stays a boundary hint only", () => {
+    const { edges, containment } = reconstructEdges(nodes, {
+      identities,
+      refs: [
+        { from: "AWS::EC2::Instance", path: "SubnetId", targetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet" },
+      ],
+    });
+    expect(containment).toHaveLength(1);
+    expect(edges).toEqual([]);
+  });
+});

package/src/graph-refs.ts

@@ -40,6 +40,25 @@ export interface RefRule {
   relation: "reference" | "containment";
   /** Edge / containment label (e.g. "in VPC", "sg", "targets"). */
   label?: string;
+  /**
+   * What the reconstructed edge's `viaAttr` should be, when traversal needs a
+   * different string than rendering does (#1275).
+   *
+   * `viaAttr` defaulted to `label ?? path`, which serves a renderer well and a
+   * traversal badly. The labels here are human-facing — "sg", "via", "in VPC" —
+   * while a fold like `enrichEffectiveTopology` matches provider attribute
+   * names: `SecurityGroupIds`, `SubnetId`, `LaunchTemplateId`. One field could
+   * not be both, so a rule that is traversed declares the name explicitly and
+   * keeps its label for the picture.
+   *
+   * On a `containment` rule this additionally opts the relation into producing
+   * an edge, on top of the boundary pair it already produces. Containment is
+   * not an edge by default and should not become one — but a fold's first hop
+   * is sometimes exactly a containment relation (an instance is *in* a subnet),
+   * and that hop has to be traversable without duplicating the rule as a
+   * reference and drawing the line twice.
+   */
+  viaAttr?: string;
 }
 
 /** A lexicon's reference knowledge — its identity map and reference rules. */
@@ -154,17 +173,29 @@ export function reconstructEdges(nodes: IRNode[], catalog: ReferenceCatalog): Re
           continue;
         }
         if (match.id === node.id) continue; // self-reference (e.g. an SG rule to its own group)
-        if (rule.relation === "containment") {
-          const k = `${node.id}|${match.id}`;
-          if (seenCont.has(k)) continue;
-          seenCont.add(k);
-          containment.push({ child: node.id, parent: match.id, ...(rule.label ? { label: rule.label } : {}) });
-        } else {
-          const via = rule.label ?? rule.path;
+        const pushEdge = (via: string): void => {
           const k = `${node.id}|${match.id}|${via}`;
-          if (seenEdge.has(k)) continue;
+          if (seenEdge.has(k)) return;
           seenEdge.add(k);
           edges.push({ from: node.id, to: match.id, kind: "ref", viaAttr: via });
+        };
+        if (rule.relation === "containment") {
+          const k = `${node.id}|${match.id}`;
+          if (!seenCont.has(k)) {
+            seenCont.add(k);
+            containment.push({ child: node.id, parent: match.id, ...(rule.label ? { label: rule.label } : {}) });
+          }
+          // A containment relation is a boundary hint, not an edge — unless the
+          // rule declares a traversal name (#1275). A fold's first hop is
+          // sometimes exactly a containment ("an instance is in a subnet"), and
+          // it must be traversable without duplicating the rule as a reference
+          // and drawing the line twice.
+          if (rule.viaAttr) pushEdge(rule.viaAttr);
+        } else {
+          // Traversal name wins over the rendering label: the labels are
+          // human-facing ("sg", "via"), and a fold matches provider attribute
+          // names (#1275).
+          pushEdge(rule.viaAttr ?? rule.label ?? rule.path);
         }
       }
     }

package/src/lexicon.ts

@@ -11,6 +11,7 @@ import type { DriverComponent } from "./components/driver";
 import type { EmulatorCapability } from "./op/emulator-lifecycle";
 import type { RuleMeta } from "./audit/catalog";
 import type { ReferenceCatalog } from "./graph-refs";
+import type { IREdge } from "./graph-ir";
 import type { DescribeResourcesResult } from "./observation";
 import type { DeepNormalizationHooks, DeepObservationResult } from "./deep-observation";
 import type { OwnerChainVerdict } from "./owner-chain";
@@ -24,6 +25,10 @@ export type { CommandGroup, CommandGroupCommand, CommandGroupContext } from "./c
 // `@intentius/chant/lexicon` entry they import the plugin contract from.
 export type { ReferenceCatalog, IdentityRule, RefRule } from "./graph-refs";
 
+// An observation can report relationships (#1271/#1273), so a lexicon needs the
+// edge type from the same entry it imports the plugin contract from.
+export type { IREdge } from "./graph-ir";
+
 // The observation contract (#1089), re-exported from the same entry so a
 // lexicon's `describeResources` can report NOT-OBSERVED without a second
 // import path. Runtime helpers live in `@intentius/chant/observation`.
@@ -641,6 +646,84 @@ export interface LexiconPlugin {
    * Throwing is the whole-lexicon failure, same as the thin read: core turns it
    * into `read-failed` for every declared entity.
    */
+  /**
+   * Report the undeclared resources this estate *depends on* (#1273), as
+   * opposed to the ones it manages.
+   *
+   * `describeResources` is scoped to what the stack declares. Anything the
+   * estate references but does not declare — an account's default VPC route
+   * tables, a shared subnet, networking owned by another team — is invisible to
+   * it, so it never becomes a node, so no edge can reach it and no fold can
+   * traverse it. That is why derived facts about un-modelled topology have had
+   * to be computed inside lexicons and injected as attributes.
+   *
+   * The closure rule is depth one by reference, plus whatever chains this
+   * lexicon's {@link referenceCatalog} declares as meaningful — so AWS follows
+   * `SubnetId` → `RouteTableId` → `GatewayId` because the catalog says those
+   * references matter, not because they happen to be reachable. Without a rule
+   * a VPC transitively reaches most of an account.
+   *
+   * Every returned resource must carry {@link ResourceMetadata.referencedBy},
+   * naming the nodes that pulled it in. A dependency with no referrer is
+   * unbounded discovery, which is what the closure rule exists to prevent.
+   *
+   * Optional and additive. A lexicon that does not implement it behaves exactly
+   * as before, and a consumer that ignores dependencies sees what it always saw.
+   */
+  observeDependencies?(options: {
+    environment: string;
+    /** Declared entities, for a lexicon that resolves references from source. */
+    entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+    /** What {@link describeResources} just found — the roots of the closure. */
+    observed: Record<string, ResourceMetadata>;
+    stack?: string;
+    region?: string;
+  }): Promise<DependencyObservation>;
+
+  /**
+   * Report resources of a kind this estate manages that exist in the account
+   * without being declared or referenced (#1278).
+   *
+   * `describeResources` answers "what do I manage" and `observeDependencies`
+   * answers "what do I rely on". Neither can see a resource that is simply
+   * *there* — an unattached security group, an orphaned volume — because both
+   * resolve outward from the declared estate and an unused resource is reached
+   * by nothing.
+   *
+   * That is a real question with no other answer: "which of my security groups
+   * are unused" cannot be resolved from a state file at all, because a state
+   * file knows only what it created. A lexicon that can enumerate a kind can
+   * answer it.
+   *
+   * `kinds` bounds the scan to types the project actually declares, so a
+   * project managing security groups is not made to enumerate the account. A
+   * lexicon returns resources marked {@link ResourceMetadata.ambient}, and must
+   * exclude anything already in `observed` — those are managed, not ambient.
+   *
+   * Optional and opt-in. A lexicon that does not implement it, or a caller that
+   * does not ask, sees exactly what it saw before.
+   */
+  /**
+   * Kinds this lexicon can enumerate beyond the declared estate (#1278).
+   *
+   * Declared separately from {@link observeAmbient} so a caller can say that
+   * ambient resources of a kind are POSSIBLE without paying for a scan to find
+   * out. `chant search` uses it to point out that `--ambient` is relevant to
+   * the kind just queried — an agent asking which security groups are unused
+   * has no way to know that some are not in the answer at all.
+   */
+  ambientKinds?(): string[];
+
+  observeAmbient?(options: {
+    environment: string;
+    /** Entity types the project declares — the bound on what to enumerate. */
+    kinds: string[];
+    /** Already-observed managed resources, to exclude. */
+    observed: Record<string, ResourceMetadata>;
+    stack?: string;
+    region?: string;
+  }): Promise<Record<string, ResourceMetadata>>;
+
   observeResourcesDeep?(options: {
     environment: string;
     buildOutput: string;
@@ -648,6 +731,10 @@ export interface LexiconPlugin {
     entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
     /** Deployed stack to observe, for a multi-stack project (see `stacks` in {@link ChantConfig}). */
     stack?: string;
+    /** Region the stack is deployed in (#1267), mirroring the thin path's
+     * `describeResources` (#1261). When omitted, an implementation keeps its
+     * ambient-region default. */
+    region?: string;
     /** Restrict to chant-owned resources (#119). A lexicon with no marker channel on this path says so. */
     owned?: boolean;
   }): Promise<DeepObservationResult>;
@@ -799,6 +886,31 @@ export type ExportedTemplate = TemplateIR & {
 /**
  * Metadata about a deployed resource, returned by describeResources.
  */
+/**
+ * What a lexicon saw outside its declared estate (#1273): the resources
+ * something declared references, and how they connect.
+ *
+ * Kept as its own result rather than folded into `describeResources` so every
+ * consumer downstream can tell "what I manage" from "what I depend on" without
+ * disentangling them — the same reason the change set separates `orphan` from
+ * `runtimeChildren`.
+ */
+export interface DependencyObservation {
+  /**
+   * Undeclared resources, keyed by a stable id. Physical id is the natural
+   * choice: these have no logical name, and the key has to match between a live
+   * read and a snapshot replay or an overlay double-counts them.
+   */
+  resources: Record<string, ResourceMetadata>;
+  /**
+   * Relationships among the dependencies and back to the declared nodes that
+   * reached them. Reported rather than reconstructed, because a reference
+   * catalog can only resolve what it has an identity index for, and part of the
+   * point here is expressing a hop the catalog does not model.
+   */
+  edges?: IREdge[];
+}
+
 export interface ResourceMetadata {
   /** Entity type (e.g. AWS::S3::Bucket, K8s::Apps::Deployment) */
   type: string;
@@ -832,6 +944,39 @@ export interface ResourceMetadata {
    * undeclared live resource stays `orphan`.
    */
   ownerChain?: OwnerChainVerdict;
+  /**
+   * The declared node ids that reference this resource (#1273), set on an
+   * undeclared resource observed only because something declared points at it —
+   * the account's default VPC route table an instance routes through, a shared
+   * subnet, a network someone else owns.
+   *
+   * A third kind of observed-but-undeclared resource, beside {@link ownership}
+   * and {@link ownerChain}. Not an orphan: nobody is going to adopt or delete
+   * the account's default VPC, so offering it as a delete candidate is wrong.
+   * Not a runtime child either — nothing declared created it. It gets a runtime
+   * child's drift treatment for the same reason: it is not yours, it changes on
+   * its own, and alerting on it is noise.
+   *
+   * Carries the referrers rather than a bare flag so the reason a resource was
+   * pulled in is answerable, and so a closure can be walked back to the declared
+   * entity that justified it.
+   */
+  referencedBy?: string[];
+  /**
+   * Observed in the account, of a kind this estate manages, but neither
+   * declared nor referenced by anything declared (#1278).
+   *
+   * The third and last category of observed-but-undeclared resource, after
+   * {@link ownerChain}'s runtime children and {@link referencedBy}'s
+   * dependencies. A default security group AWS creates per VPC is the type
+   * case: nothing declares it, nothing points at it, and it is exactly what
+   * "which of my security groups are unused" is asking about.
+   *
+   * Opt-in, because finding these means asking the provider what exists rather
+   * than resolving out from what is declared, which is a broader read and a
+   * different claim about what an observation is.
+   */
+  ambient?: boolean;
 }
 
 /**

package/src/lifecycle/deep-observe.ts

@@ -39,6 +39,10 @@ export interface DeepObserveOptions {
   entities: DeclaredEntities;
   /** Deployed stack for a multi-stack project (#932). */
   stack?: string;
+  /** Region that stack is deployed in (#1267). Same contract as the thin path
+   * (#1261): a multi-region estate reads each stack in its own region, not in
+   * whichever one the shell is set to. */
+  region?: string;
   /** Component projects deploy one stack per component; read them all and merge. */
   componentStacks?: string[];
   owned?: boolean;
@@ -80,6 +84,7 @@ export async function observeDeep(
     buildOutput: opts.buildOutput,
     entityNames,
     entities: opts.entities,
+    ...(opts.region ? { region: opts.region } : {}),
     ...(opts.owned !== undefined ? { owned: opts.owned } : {}),
   };
   try {

package/src/lifecycle/live-diff.test.ts

@@ -336,3 +336,41 @@ describe("diffSnapshots (#822)", () => {
     expect(d.added).toEqual(["a", "b"]);
   });
 });
+
+describe("attribute comparison is key-order insensitive (#1279)", () => {
+  const inst = (attributes: Record<string, unknown>): ResourceMetadata => ({
+    type: "AWS::EC2::Instance",
+    status: "OBSERVED",
+    physicalId: "i-1",
+    attributes,
+  });
+
+  test("does not drift when a provider reorders the keys of a nested object", () => {
+    // Exactly what AWS did between two reads of the same untouched instance.
+    const result = diffLive({
+      declared: new Set(["one"]),
+      observedNow: { one: inst({ Placement: { Tenancy: "default", AvailabilityZone: "us-east-1c" } }) },
+      observedThen: { one: inst({ Placement: { AvailabilityZone: "us-east-1c", Tenancy: "default" } }) },
+    });
+    expect(result.driftedSinceSnapshot).toEqual([]);
+    expect(result.unchanged).toEqual(["one"]);
+  });
+
+  test("still reports a real change to a nested value", () => {
+    const result = diffLive({
+      declared: new Set(["one"]),
+      observedNow: { one: inst({ Placement: { AvailabilityZone: "us-east-1d" } }) },
+      observedThen: { one: inst({ Placement: { AvailabilityZone: "us-east-1c" } }) },
+    });
+    expect(result.driftedSinceSnapshot.map((d) => d.changes[0].path)).toEqual(["attributes.Placement"]);
+  });
+
+  test("keeps array order significant — for a list, order is part of the value", () => {
+    const result = diffLive({
+      declared: new Set(["one"]),
+      observedNow: { one: inst({ Rules: [{ p: 80 }, { p: 22 }] }) },
+      observedThen: { one: inst({ Rules: [{ p: 22 }, { p: 80 }] }) },
+    });
+    expect(result.driftedSinceSnapshot).toHaveLength(1);
+  });
+});