@intentius/chant 0.33.1 → 0.34.0

package/src/lifecycle/live-diff.ts

@@ -133,11 +133,31 @@ function compareMetadata(
   return changes;
 }
 
+/**
+ * Value equality that does not care what order a provider listed the keys in.
+ *
+ * This compared with `JSON.stringify`, which is key-order sensitive. That held
+ * while observed attributes were flat strings, and broke the moment they carried
+ * nested objects (#1279): a provider returning `{AvailabilityZone, Tenancy}` on
+ * one read and `{Tenancy, AvailabilityZone}` on the next made an unchanged
+ * instance drift on every single run. Order is not a fact about the resource,
+ * and reporting it as drift is exactly the noise this module exists to remove.
+ *
+ * Arrays stay order-sensitive — for a list, order is part of the value.
+ */
 function shallowEqual(a: unknown, b: unknown): boolean {
   if (a === b) return true;
   if (a == null || b == null) return false;
   if (typeof a !== "object" || typeof b !== "object") return false;
-  return JSON.stringify(a) === JSON.stringify(b);
+  return canonical(a) === canonical(b);
+}
+
+/** JSON with object keys sorted at every depth, so equal values stringify equally. */
+function canonical(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  const entries = Object.entries(value as Record<string, unknown>).sort(([x], [y]) => (x < y ? -1 : x > y ? 1 : 0));
+  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(",")}}`;
 }
 
 /** The delta between two saved snapshots (#822): a two-way observed diff. */
@@ -227,8 +247,28 @@ export function diffLive(input: DiffLiveInput): LiveDiffResult {
   // same as `unowned`/`foreign` — composing with #1168's tri-state precedent:
   // an incomplete read never earns the more confident classification.
   const runtimeChildNames = new Set<string>();
+  const dependencyNames = new Set<string>();
   for (const name of observedNowNames) {
     if (declared.has(name)) continue;
+    // A referenced dependency (#1273) is observed only because something
+    // declared points at it — an account's default VPC route table, a shared
+    // subnet. Offering it as a delete/adopt candidate is wrong: it is not
+    // yours, and it changes on its own, so counting it as drift is noise.
+    // Same treatment as a runtime child, for the same reason, arrived at from
+    // the other direction — a child is something declared created, a
+    // dependency is something declared relies on.
+    if ((observedNow[name]?.referencedBy?.length ?? 0) > 0) {
+      dependencyNames.add(name);
+      continue;
+    }
+    // Ambient (#1278): observed because it exists, not because anything points
+    // at it. Reported so a caller can ask about it — "which of these are
+    // unused" is the whole point — but never counted as drift, since chant
+    // neither created it nor tracks its changes.
+    if (observedNow[name]?.ambient) {
+      dependencyNames.add(name);
+      continue;
+    }
     const chain = observedNow[name]?.ownerChain;
     if (chain?.root === "declared") {
       runtimeChildNames.add(name);
@@ -256,7 +296,10 @@ export function diffLive(input: DiffLiveInput): LiveDiffResult {
   // happened to record the same name (e.g. a StatefulSet's stable pod
   // identity) must not turn its ordinary churn into `driftedSinceSnapshot`.
   for (const name of observedNowNames) {
-    if (runtimeChildNames.has(name)) continue;
+    // Referenced dependencies (#1273) are excluded for the same reason runtime
+    // children are: they are observed to complete the picture, not to be
+    // governed, and their ordinary churn is somebody else's.
+    if (runtimeChildNames.has(name) || dependencyNames.has(name)) continue;
     const now = observedNow[name];
     const then = observedThenMap[name];
     if (!then) {

package/src/lifecycle/observe.ts

@@ -14,7 +14,8 @@ 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 type { LiveObservation, IREdge } from "../graph-ir";
+import type { ResourceMetadata } from "../lexicon";
 import {
   mergeObservations,
   normalizeObservation,
@@ -73,10 +74,18 @@ export async function observeResources(
   environment: string,
   plugins: ObservationLexicon[],
   buildResult: BuildResult,
-  opts?: { owned?: boolean; stacks?: Array<string | { name: string; region?: string; src?: string }> },
+  opts?: {
+    owned?: boolean;
+    stacks?: Array<string | { name: string; region?: string; src?: string }>;
+    /** Also report resources of a managed kind that nothing declares or
+     * references (#1278). Opt-in: it asks the provider what exists rather than
+     * resolving out from what is declared. */
+    ambient?: boolean;
+  },
 ): Promise<ObserveResult> {
   const owned = opts?.owned ?? true;
   const stacks = (opts?.stacks ?? []).map((st) => (typeof st === "string" ? { name: st } : st));
+  const includeAmbient = opts?.ambient ?? false;
   // 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
@@ -177,7 +186,38 @@ export async function observeResources(
           }),
         );
       }
-      pushObservation(observations, warnings, plugin.name, observed, environment, entityNames.length);
+      // What the estate depends on but does not declare (#1273). Read after the
+      // managed resources, because the declared observation is the closure's
+      // roots — there is nothing to reference out from until it exists.
+      const dependencies = await collectDependencies(plugin, {
+        environment,
+        entities,
+        observed: observed.resources,
+        stacks,
+      });
+      for (const message of dependencies.warnings) warnings.push(message);
+      // Resources of a managed kind that nothing declares or references (#1278).
+      // Bounded by what this lexicon's declared entities actually are, so a
+      // project managing security groups is not made to enumerate the account.
+      const ambient = includeAmbient
+        ? await collectAmbient(plugin, {
+            environment,
+            kinds: [...new Set([...entities.values()].map((e) => e.entityType))],
+            observed: observed.resources,
+            stacks,
+            warnings,
+          })
+        : {};
+      for (const [id, meta] of Object.entries(ambient)) dependencies.resources[id] ??= meta;
+      pushObservation(
+        observations,
+        warnings,
+        plugin.name,
+        observed,
+        environment,
+        entityNames.length,
+        dependencies,
+      );
     } catch (err) {
       // A thrown read is the whole-lexicon failure: every declared entity is
       // NOT-OBSERVED, not absent (#1089). Emitting nothing here is what made a
@@ -201,6 +241,141 @@ export async function observeResources(
   return { observations, warnings, errors };
 }
 
+/**
+ * The subset of an observation belonging to one stack.
+ *
+ * A scoped stack's ids are qualified `${stack}::${id}` (#1162), so the prefix is
+ * the whole test. An unqualified observation — single-stack, or a bare-string
+ * stack sharing one id space — has no way to be split and is returned whole,
+ * which is what it already was.
+ */
+function scopeToStack(
+  resources: Record<string, ResourceMetadata>,
+  stack: string | undefined,
+): Record<string, ResourceMetadata> {
+  if (!stack) return resources;
+  const prefix = `${stack}::`;
+  const scoped = Object.fromEntries(
+    Object.entries(resources)
+      .filter(([id]) => id.startsWith(prefix))
+      .map(([id, meta]) => [id, meta] as const),
+  );
+  // No qualified ids at all means this observation was never stack-scoped.
+  return Object.keys(scoped).length > 0 ? scoped : resources;
+}
+
+/**
+ * Ask a lexicon what exists of the kinds it manages, beyond what is declared
+ * (#1278). Once per stack for the region, merged by physical id — the same
+ * ambient resource seen from two stacks is one resource.
+ */
+export async function collectAmbient(
+  plugin: ObservationLexicon,
+  opts: {
+    environment: string;
+    kinds: string[];
+    observed: Record<string, ResourceMetadata>;
+    stacks: Array<{ name: string; region?: string; src?: string }>;
+    warnings: string[];
+  },
+): Promise<Record<string, ResourceMetadata>> {
+  if (!plugin.observeAmbient || opts.kinds.length === 0) return {};
+  const found: Record<string, ResourceMetadata> = {};
+  const refs = opts.stacks.length > 0 ? opts.stacks : [{ name: undefined, region: undefined }];
+  for (const ref of refs) {
+    try {
+      const part = await plugin.observeAmbient({
+        environment: opts.environment,
+        kinds: opts.kinds,
+        observed: opts.observed,
+        ...(ref.name ? { stack: ref.name } : {}),
+        ...(ref.region ? { region: ref.region } : {}),
+      });
+      for (const [id, meta] of Object.entries(part)) found[id] ??= meta;
+    } catch (err) {
+      opts.warnings.push(
+        `${plugin.name}: ambient resources not read${ref.name ? ` for stack "${ref.name}"` : ""} — ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+  return found;
+}
+
+/** Dependencies collected across a lexicon's stacks, plus anything to report. */
+export interface CollectedDependencies {
+  resources: Record<string, ResourceMetadata>;
+  edges: IREdge[];
+  warnings: string[];
+}
+
+const NO_DEPENDENCIES: CollectedDependencies = { resources: {}, edges: [], warnings: [] };
+
+/**
+ * Ask a lexicon what its declared estate references but does not manage (#1273).
+ *
+ * Called once per stack, because the closure roots and the region differ per
+ * stack, and merged by key. Dependencies are keyed by physical id and are
+ * deliberately NOT stack-qualified: the account's default VPC route table is the
+ * same resource whichever stack routes through it, and qualifying it would
+ * produce one node per referrer and an edge to each.
+ *
+ * Best-effort. A lexicon that does not implement the hook, or one whose read
+ * fails, contributes nothing — the managed observation is already complete and
+ * useful on its own, and failing it because an ambient dependency could not be
+ * read would trade a whole answer for a partial one.
+ */
+export async function collectDependencies(
+  plugin: ObservationLexicon,
+  opts: {
+    environment: string;
+    entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+    observed: Record<string, ResourceMetadata>;
+    stacks: Array<{ name: string; region?: string; src?: string }>;
+  },
+): Promise<CollectedDependencies> {
+  if (!plugin.observeDependencies) return NO_DEPENDENCIES;
+
+  const resources: Record<string, ResourceMetadata> = {};
+  const edges: IREdge[] = [];
+  const warnings: string[] = [];
+  const refs = opts.stacks.length > 0 ? opts.stacks : [{ name: undefined, region: undefined }];
+
+  for (const ref of refs) {
+    // Only this stack's resources are the closure's roots. Handing a lexicon
+    // the whole estate makes it resolve out from resources that live somewhere
+    // else — for AWS that means `describe-instances` in one region with another
+    // region's instance ids, which fails outright with InvalidInstanceID and
+    // takes the whole read down with it.
+    const roots = scopeToStack(opts.observed, ref.name);
+    if (Object.keys(roots).length === 0) continue;
+    try {
+      const found = await plugin.observeDependencies({
+        environment: opts.environment,
+        entities: opts.entities,
+        observed: roots,
+        ...(ref.name ? { stack: ref.name } : {}),
+        ...(ref.region ? { region: ref.region } : {}),
+      });
+      for (const [id, meta] of Object.entries(found.resources)) {
+        // Merge referrers rather than overwrite: two stacks routing through the
+        // same table is one node reached twice, and the reason it is here is
+        // both of them.
+        const existing = resources[id];
+        resources[id] = existing
+          ? { ...existing, referencedBy: [...new Set([...(existing.referencedBy ?? []), ...(meta.referencedBy ?? [])])] }
+          : meta;
+      }
+      edges.push(...(found.edges ?? []));
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      warnings.push(
+        `${plugin.name}: dependencies not read${ref.name ? ` for stack "${ref.name}"` : ""} — ${message}`,
+      );
+    }
+  }
+  return { resources, edges, warnings };
+}
+
 /** Record one lexicon's observation, warning once per unobserved entity. */
 function pushObservation(
   observations: LiveObservation[],
@@ -209,6 +384,7 @@ function pushObservation(
   observed: NormalizedObservation,
   environment: string,
   declaredCount: number,
+  dependencies: CollectedDependencies = NO_DEPENDENCIES,
 ): void {
   const hasResources = Object.keys(observed.resources).length > 0;
   const unobservedNames = Object.keys(observed.unobserved);
@@ -225,9 +401,15 @@ function pushObservation(
     if (notice) warnings.push(notice);
     return;
   }
+  // Dependencies ride alongside the managed resources so they become nodes, and
+  // carry `referencedBy` so every consumer can still tell the two apart.
+  const hasDependencies = Object.keys(dependencies.resources).length > 0;
   observations.push({
     lexicon,
-    resources: observed.resources,
+    resources: hasDependencies
+      ? { ...observed.resources, ...dependencies.resources }
+      : observed.resources,
     ...(unobservedNames.length > 0 ? { unobserved: observed.unobserved } : {}),
+    ...(dependencies.edges.length > 0 ? { edges: dependencies.edges } : {}),
   });
 }

package/src/lifecycle/replay.ts

@@ -0,0 +1,141 @@
+/**
+ * Replay a recorded snapshot as if it had just been observed (#1266, #1279).
+ *
+ * Shared by `chant search --at` and `chant graph --at`. A snapshot already holds
+ * what an observation is — resources with their physical ids and attributes,
+ * and since #1266 the relationships between them — so turning it back into
+ * `LiveObservation[]` lets a replay rejoin the live path at `buildLiveGraphIr`.
+ * Every fold, overlay and edge reconstruction below that point is shared, and
+ * nothing downstream needs to know which source it got.
+ *
+ * That sharing is the reason this is a module rather than a helper inside one
+ * command: `graph` had no `--at` at all, so anyone wanting the raw IR of a
+ * recorded estate had to reach for the live endpoint, and a snapshot could
+ * answer most questions but never all of them.
+ */
+
+import { readEnvironmentSnapshots } from "./git";
+import type { LiveObservation } from "../graph-ir";
+import type { LifecycleSnapshot } from "./types";
+
+/**
+ * Rebuild observations from a recorded snapshot (#1266).
+ *
+ * A snapshot already holds what an observation is: resources with their
+ * physical ids and attributes, and — since #1266 — the relationships between
+ * them. Turning it back into `LiveObservation[]` means the replay rejoins the
+ * live path at `buildLiveGraphIr`, and every fold, overlay and query below that
+ * is shared. Nothing downstream needs to know which source it got.
+ *
+ * `latest` is the only ref for now. A specific commit is the natural extension
+ * and the storage already supports it (`readSnapshotAt`), but "answer from what
+ * is recorded" is the question worth settling first.
+ */
+/**
+ * Whether this environment has a recording, without reading one.
+ *
+ * Used to turn "the estate could not be read" into "the estate could not be
+ * read, and you already have a recording of it". Cheap and best-effort: a
+ * failure here means the caller says the plain version of the message, never
+ * that the command fails.
+ */
+export async function hasSnapshot(environment: string): Promise<boolean> {
+  try {
+    return (await readEnvironmentSnapshots(environment)).size > 0;
+  } catch {
+    return false;
+  }
+}
+
+export async function replaySnapshots(
+  environment: string,
+  ref: string,
+  scopedStacks: Set<string>,
+): Promise<{ observations: LiveObservation[]; commit: string; timestamp: string } | { error: string; hint?: string }> {
+  if (ref !== "latest" && ref !== "true") {
+    return {
+      error: `chant search --at only accepts "latest" for now, got "${ref}"`,
+      hint: "a specific snapshot commit is not wired up yet",
+    };
+  }
+  const stored = await readEnvironmentSnapshots(environment);
+  if (stored.size === 0) {
+    return {
+      error: `No snapshots found for environment "${environment}"`,
+      hint: `Record one first: chant lifecycle snapshot ${environment}`,
+    };
+  }
+  const observations: LiveObservation[] = [];
+  let commit = "";
+  let timestamp = "";
+  // Ambient and dependency resources are keyed by physical id and are
+  // account-level: the default security group three stacks each recorded is one
+  // group, not three. Managed resources are stack-qualified below and cannot
+  // collide, so only the unqualified ones need this.
+  const seenUnqualified = new Set<string>();
+  // A stack's snapshot could only exclude what THAT stack manages, so a stack
+  // declaring no security groups reported the neighbouring stack's as ambient.
+  // The union is only knowable here, with every snapshot in hand.
+  const managedPhysicalIds = new Set<string>();
+  for (const content of stored.values()) {
+    const snap = JSON.parse(content) as LifecycleSnapshot;
+    for (const meta of Object.values(snap.resources ?? {})) {
+      if (!meta.ambient && !meta.referencedBy?.length && meta.physicalId) {
+        managedPhysicalIds.add(meta.physicalId);
+      }
+    }
+  }
+  for (const [key, content] of stored) {
+    const snapshot = JSON.parse(content) as LifecycleSnapshot;
+    // The storage key is `<stack>__<lexicon>` for a multi-stack project; the
+    // snapshot carries its own lexicon, which is the one to trust.
+    const lexicon = snapshot.lexicon ?? key;
+    // A scoped stack's ids are qualified `${stack}::${id}` on the live path
+    // (#1162), because the same bare LogicalResourceId exists in every region's
+    // stack. A snapshot stores them bare, so a replay has to re-apply the same
+    // rule — otherwise `server` from us-west-1 and `server` from us-west-2
+    // collide, and none of them join the declared canvas, which qualifies.
+    const stack = snapshot.stack;
+    const qualify = stack !== undefined && scopedStacks.has(stack);
+    // Dependencies (#1273) are keyed by physical id and are account-level: the
+    // default VPC's route table is one resource however many stacks route
+    // through it. Qualifying those would split it per stack and break the
+    // edges into it.
+    const managed = (id: string, meta: { referencedBy?: string[]; ambient?: boolean }): string =>
+      qualify && !meta.ambient && !(meta.referencedBy && meta.referencedBy.length > 0)
+        ? `${stack}::${id}`
+        : id;
+    const resources: Record<string, (typeof snapshot.resources)[string]> = {};
+    for (const [id, meta] of Object.entries(snapshot.resources ?? {})) {
+      const key = managed(id, meta);
+      if (key === id) {
+        // Ambient means "nothing manages this". Another stack managing it makes
+        // that false, and reporting it twice would inflate any count over it.
+        if (meta.ambient && meta.physicalId && managedPhysicalIds.has(meta.physicalId)) continue;
+        // Unqualified: account-level, so first sighting wins and the rest are
+        // the same resource seen again from another stack's snapshot.
+        if (seenUnqualified.has(id)) continue;
+        seenUnqualified.add(id);
+      }
+      resources[key] = meta;
+    }
+    const known = new Set(Object.keys(snapshot.resources ?? {}));
+    const requalify = (id: string): string => {
+      const meta = (snapshot.resources ?? {})[id];
+      return known.has(id) && meta ? managed(id, meta) : id;
+    };
+    const edges = (snapshot.edges ?? []).map((e) => ({ ...e, from: requalify(e.from), to: requalify(e.to) }));
+    observations.push({
+      lexicon,
+      resources,
+      ...(edges.length > 0 ? { edges } : {}),
+    });
+    commit ||= snapshot.commit ?? "";
+    // Report the OLDEST timestamp across stacks: a caller asking how stale this
+    // answer is wants the weakest link, not the freshest one.
+    if (!timestamp || (snapshot.timestamp && snapshot.timestamp < timestamp)) {
+      timestamp = snapshot.timestamp ?? timestamp;
+    }
+  }
+  return { observations, commit, timestamp };
+}

package/src/lifecycle/snapshot.test.ts

@@ -1,6 +1,8 @@
 import { describe, test, expect, vi, beforeEach } from "vitest";
 import { createMockPlugin, staticDescribeResources, staticObservation, staticListArtifacts } from "@intentius/chant-test-utils";
 import type { BuildResult } from "../build";
+import type { DeepResourceObservation } from "../deep-observation";
+import type { UnobservedEntity } from "../observation";
 
 const writeSnapshotMock = vi.fn();
 const getHeadCommitMock = vi.fn();
@@ -83,6 +85,126 @@ describe("takeSnapshot", () => {
     expect(writeSnapshotMock.mock.calls[0][1]).toBe("loom-backend__aws");
   });
 
+  test("region option: the stack's own region reaches describeResources (#1261)", async () => {
+    let observedRegion: string | undefined = "unset";
+    const plugin = createMockPlugin({
+      name: "aws",
+      describeResources: async (options: { region?: string }) => {
+        observedRegion = options.region;
+        return { bucket: { type: "AWS::S3::Bucket", status: "CREATE_COMPLETE", physicalId: "b" } };
+      },
+    });
+    await takeSnapshot("prod", [plugin], makeBuildResult({ aws: ["bucket"] }), {
+      stack: "loom-us-west-2",
+      region: "us-west-2",
+    });
+    // Without this the reader falls back to the ambient region, and every stack
+    // outside it snapshots as "no valid resources or artifacts returned".
+    expect(observedRegion).toBe("us-west-2");
+  });
+
+  test("no region declared: describeResources keeps its ambient-region default", async () => {
+    let observedRegion: string | undefined = "unset";
+    const plugin = createMockPlugin({
+      name: "aws",
+      describeResources: async (options: { region?: string }) => {
+        observedRegion = options.region;
+        return { bucket: { type: "AWS::S3::Bucket", status: "CREATE_COMPLETE", physicalId: "b" } };
+      },
+    });
+    await takeSnapshot("prod", [plugin], makeBuildResult({ aws: ["bucket"] }));
+    expect(observedRegion).toBeUndefined();
+  });
+
+  // #1267 — a snapshot records identity by default; --deep also records each
+  // resource's property tree, which is what a fold over topology needs.
+  describe("deep snapshots (#1267)", () => {
+    const identity = { bucket: { type: "AWS::S3::Bucket", status: "CREATE_COMPLETE", physicalId: "b" } };
+
+    function deepPlugin(
+      resources: Record<string, DeepResourceObservation>,
+      unobserved: Record<string, UnobservedEntity> = {},
+    ) {
+      return createMockPlugin({
+        name: "aws",
+        describeResources: staticDescribeResources(identity),
+        observeResourcesDeep: async () => ({ deepObservation: "v1" as const, resources, unobserved }),
+      });
+    }
+
+    test("without --deep: identity only, and depth is not written", async () => {
+      const plugin = deepPlugin({
+        bucket: { type: "AWS::S3::Bucket", physicalId: "b", properties: { versioning: "Enabled" } },
+      });
+      const result = await takeSnapshot("prod", [plugin], makeBuildResult({ aws: ["bucket"] }));
+      // Absent, not "identity" — every snapshot written before #1267 is thin,
+      // and a reader must treat a missing field as thin rather than unknown.
+      expect(result.snapshots[0].depth).toBeUndefined();
+      expect(result.snapshots[0].properties).toBeUndefined();
+    });
+
+    test("with --deep: records the property trees alongside identity", async () => {
+      const plugin = deepPlugin({
+        bucket: { type: "AWS::S3::Bucket", physicalId: "b", properties: { versioning: "Enabled" } },
+      });
+      const result = await takeSnapshot("prod", [plugin], makeBuildResult({ aws: ["bucket"] }), { deep: true });
+      expect(result.snapshots[0].depth).toBe("deep");
+      expect(result.snapshots[0].properties?.bucket.properties).toEqual({ versioning: "Enabled" });
+      // Identity is still there — deep adds, it does not replace.
+      expect(result.snapshots[0].resources.bucket).toMatchObject({ type: "AWS::S3::Bucket" });
+    });
+
+    test("--deep against a lexicon with no deep reader: identity snapshot plus a warning", async () => {
+      const plugin = createMockPlugin({ name: "aws", describeResources: staticDescribeResources(identity) });
+      const result = await takeSnapshot("prod", [plugin], makeBuildResult({ aws: ["bucket"] }), { deep: true });
+      // Still a usable snapshot, but it must not claim a depth it does not have.
+      expect(result.snapshots).toHaveLength(1);
+      expect(result.snapshots[0].depth).toBeUndefined();
+      expect(result.warnings.join("\n")).toContain("no deep reader");
+    });
+
+    test("--deep returning nothing: downgrades to identity rather than discarding a good snapshot", async () => {
+      const plugin = deepPlugin({});
+      const result = await takeSnapshot("prod", [plugin], makeBuildResult({ aws: ["bucket"] }), { deep: true });
+      expect(result.snapshots).toHaveLength(1);
+      expect(result.snapshots[0].depth).toBeUndefined();
+      expect(result.warnings.join("\n")).toContain("deep read returned no properties");
+    });
+
+    test("--deep passes the stack's region to the deep reader (#1261 family)", async () => {
+      let seen: string | undefined = "unset";
+      const plugin = createMockPlugin({
+        name: "aws",
+        describeResources: staticDescribeResources(identity),
+        observeResourcesDeep: async (options: { region?: string }) => {
+          seen = options.region;
+          return {
+            deepObservation: "v1" as const,
+            resources: { bucket: { type: "AWS::S3::Bucket", physicalId: "b", properties: {} } },
+            unobserved: {},
+          };
+        },
+      });
+      await takeSnapshot("prod", [plugin], makeBuildResult({ aws: ["bucket"] }), {
+        stack: "app-us-west-2",
+        region: "us-west-2",
+        deep: true,
+      });
+      // Without this the deep read targets the ambient region and comes back
+      // empty, which downgrades a multi-region snapshot to identity silently.
+      expect(seen).toBe("us-west-2");
+    });
+
+    test("--deep reports entities the deep reader could not read", async () => {
+      const plugin = deepPlugin(
+        { bucket: { type: "AWS::S3::Bucket", physicalId: "b", properties: {} } },
+        { queue: { reason: "read-failed", detail: "boom" } },
+      );
+      const result = await takeSnapshot("prod", [plugin], makeBuildResult({ aws: ["bucket"] }), { deep: true });
+      expect(result.warnings.join("\n")).toContain("not observed deeply");
+    });
+  });
+
   test("plugin without describeResources is skipped", async () => {
     const plugin = createMockPlugin({ name: "aws" });
     const result = await takeSnapshot("prod", [plugin], makeBuildResult({ aws: ["x"] }));
@@ -231,3 +353,60 @@ describe("takeSnapshot", () => {
     expect(result.snapshots).toEqual([]);
   });
 });
+
+// #1266 — a snapshot that records only what it manages cannot answer a fold
+// question when it is replayed: the account's default VPC routing is not in it,
+// so `internetFacing` is unanswerable and `search --at` would be quietly weaker
+// than `search --live`.
+describe("dependencies and edges in a snapshot (#1266)", () => {
+  const identity = { webServer: { type: "AWS::EC2::Instance", status: "OK", physicalId: "i-1" } };
+
+  test("records the dependencies the estate references, and the edges to them", async () => {
+    const plugin = createMockPlugin({
+      name: "aws",
+      describeResources: staticDescribeResources(identity),
+      observeDependencies: async () => ({
+        resources: {
+          "rtb-default": {
+            type: "AWS::EC2::RouteTable",
+            status: "OBSERVED",
+            physicalId: "rtb-default",
+            referencedBy: ["webServer"],
+          },
+        },
+        edges: [{ from: "webServer", to: "rtb-default", kind: "ref" as const, viaAttr: "RouteTableId" }],
+      }),
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ aws: ["webServer"] }));
+    // Both, in one record: what exists and how it connects.
+    expect(result.snapshots[0].resources["rtb-default"]).toMatchObject({ referencedBy: ["webServer"] });
+    expect(result.snapshots[0].edges).toEqual([
+      { from: "webServer", to: "rtb-default", kind: "ref", viaAttr: "RouteTableId" },
+    ]);
+  });
+
+  test("a lexicon with no dependency reader snapshots exactly as before", async () => {
+    const plugin = createMockPlugin({ name: "aws", describeResources: staticDescribeResources(identity) });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ aws: ["webServer"] }));
+    expect(Object.keys(result.snapshots[0].resources)).toEqual(["webServer"]);
+    // Absent, not empty — "no relationships recorded", not "none existed".
+    expect(result.snapshots[0].edges).toBeUndefined();
+  });
+
+  test("a dependency read that fails warns and keeps the managed snapshot", async () => {
+    const plugin = createMockPlugin({
+      name: "aws",
+      describeResources: staticDescribeResources(identity),
+      observeDependencies: async () => {
+        throw new Error("route tables unreadable");
+      },
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ aws: ["webServer"] }));
+    // The managed observation is complete and useful on its own; losing it
+    // because an ambient dependency could not be read trades a whole answer
+    // for none.
+    expect(result.snapshots).toHaveLength(1);
+    expect(result.snapshots[0].resources.webServer).toBeDefined();
+    expect(result.warnings.join("\n")).toContain("dependencies not read");
+  });
+});