@intentius/chant 0.33.1 → 0.34.1

package/dist/lifecycle/replay.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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 type { LiveObservation } from "../graph-ir.js";
+/**
+ * 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 declare function hasSnapshot(environment: string): Promise<boolean>;
+export declare function replaySnapshots(environment: string, ref: string, scopedStacks: Set<string>): Promise<{
+    observations: LiveObservation[];
+    commit: string;
+    timestamp: string;
+} | {
+    error: string;
+    hint?: string;
+}>;
+//# sourceMappingURL=replay.d.ts.map

package/dist/lifecycle/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../src/lifecycle/replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnD;;;;;;;;;;;;GAYG;AACH;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAMvE;AAED,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,GACxB,OAAO,CAAC;IAAE,YAAY,EAAE,eAAe,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAuFpH"}

package/dist/lifecycle/snapshot.d.ts

@@ -17,5 +17,11 @@ export interface TakeSnapshotResult {
 export declare function takeSnapshot(environment: string, plugins: ObservationLexicon[], buildResult: BuildResult, opts?: {
     cwd?: string;
     stack?: string;
+    region?: string;
+    deep?: boolean;
+    ambient?: boolean;
+    /** Kinds the PROJECT manages, not just this stack — a region whose stack
+     * declares no security group still has a default one (#1278). */
+    ambientKinds?: string[];
 }): Promise<TakeSnapshotResult>;
 //# sourceMappingURL=snapshot.d.ts.map

package/dist/lifecycle/snapshot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/lifecycle/snapshot.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAsC,MAAM,YAAY,CAAC;AACzF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AA6DjD,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,kBAAkB,EAAE,EAC7B,WAAW,EAAE,WAAW,EACxB,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACtC,OAAO,CAAC,kBAAkB,CAAC,CA0I7B"}
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/lifecycle/snapshot.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAsC,MAAM,YAAY,CAAC;AACzF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,OAAO,KAAK,EAAE,iBAAiB,EAAoB,MAAM,SAAS,CAAC;AAgEnE,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,kBAAkB,EAAE,EAC7B,WAAW,EAAE,WAAW,EACxB,IAAI,CAAC,EAAE;IACL,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;qEACiE;IACjE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB,GACA,OAAO,CAAC,kBAAkB,CAAC,CAmN7B"}

package/dist/lifecycle/types.d.ts

@@ -1,6 +1,22 @@
 import type { ResourceMetadata, ArtifactMetadata } from "../lexicon.js";
 import type { UnobservedEntity } from "../observation.js";
+import type { DeepResourceObservation } from "../deep-observation.js";
+import type { IREdge } from "../graph-ir.js";
 export type { ResourceMetadata, ArtifactMetadata } from "../lexicon.js";
+/**
+ * How much of each resource an observation actually read (#1267).
+ *
+ * `identity` is the thin path: logical name, type, physical id, status. It is
+ * what a snapshot recorded before deep reads existed, and it stays the default
+ * because a deep read costs more provider calls and a larger record.
+ *
+ * `deep` additionally carries each resource's normalized property tree, which
+ * is what a fold over topology needs — a subnet's route-table association, a
+ * security group's rules. A consumer must branch on this rather than assume:
+ * asking an `identity` snapshot a property question has no answer, and
+ * silently returning nothing would read as "no such resources".
+ */
+export type ObservationDepth = "identity" | "deep";
 /**
  * State snapshot for a single lexicon in an environment.
  */
@@ -26,6 +42,36 @@ export interface LifecycleSnapshot {
     unobserved?: Record<string, UnobservedEntity>;
     /** Artifact metadata keyed by server-side identifier (lexicon-specific). */
     artifacts?: Record<string, ArtifactMetadata>;
+    /**
+     * How much of each resource this snapshot read (#1267). Absent means
+     * `identity` — every snapshot written before deep reads existed was thin, and
+     * treating a missing field as unknown rather than as thin would invalidate
+     * them all.
+     */
+    depth?: ObservationDepth;
+    /**
+     * Normalized per-resource property trees, present only at `deep` depth and
+     * keyed by the same logical names as `resources`.
+     *
+     * Kept beside `resources` rather than merged into it so the thin record stays
+     * exactly what it always was: a reader that only wants identity does not have
+     * to learn a new shape, and an old snapshot and a new one parse the same way.
+     */
+    properties?: Record<string, DeepResourceObservation>;
+    /**
+     * Relationships observed between the recorded resources (#1266).
+     *
+     * `resources` says what existed; without this a snapshot cannot say how any
+     * of it connected, so a fold over topology has nothing to traverse when the
+     * snapshot is replayed. That is the difference between a snapshot answering
+     * "which instances exist" and answering "which are reachable from the
+     * internet" — and the second is the whole reason the graph is worth
+     * recording.
+     *
+     * Absent on every snapshot written before this, which is read as "no
+     * relationships recorded" rather than "no relationships existed".
+     */
+    edges?: IREdge[];
     /** Build digest at snapshot time — what was declared when this snapshot was taken */
     digest?: BuildDigest;
 }

package/dist/lifecycle/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lifecycle/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB;;gFAE4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC5C;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC9C,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC7C,qFAAqF;IACrF,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC1C,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACvC,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/E,iCAAiC;IACjC,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,wCAAwC;IACxC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,wCAAwC;IACxC,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lifecycle/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAErE;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,MAAM,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB;;gFAE4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC5C;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC9C,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC7C;;;;;OAKG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;IACrD;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,qFAAqF;IACrF,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC1C,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACvC,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/E,iCAAiC;IACjC,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,wCAAwC;IACxC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,wCAAwC;IACxC,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.33.1",
+  "version": "0.34.1",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/cli/commands/onboard.ts

@@ -171,40 +171,25 @@ function patchCiWorkflow(root: string, name: string): { patched: boolean; reason
 }
 
 /**
- * Patch publish.yml: add prepack line in test job + publish step.
+ * Patch publish.yml: add the prepack line to the test job.
+ *
+ * No publish step is added. scripts/publish-packages.sh enumerates every
+ * non-private workspace package at run time, so a new lexicon is published
+ * the moment it exists — that is deliberate. Hand-maintained publish steps
+ * were how k8s-client (#1177) and fountain (#1253) each shipped a package
+ * the release pipeline could not publish.
  */
 function patchPublishWorkflow(root: string, name: string): { patched: boolean; reason?: string } {
   const filePath = join(root, ".github/workflows/publish.yml");
   if (!existsSync(filePath)) return { patched: false, reason: "publish.yml not found" };
 
   const content = readFileSync(filePath, "utf-8");
-  if (content.includes(`working-directory: lexicons/${name}`)) {
-    return { patched: false, reason: `publish step for ${name} already present` };
+  if (content.includes(`lexicons/${name} prepack`)) {
+    return { patched: false, reason: `prepack for ${name} already present` };
   }
 
   const lines = content.split("\n");
-
-  // Insert prepack line in test job
   insertPrepackAfterEach(lines, name);
-
-  // Add publish step after the last existing publish step
-  let lastPublishRunIdx = -1;
-  for (let i = 0; i < lines.length; i++) {
-    if (lines[i].includes("npm publish --access public")) {
-      lastPublishRunIdx = i;
-    }
-  }
-
-  if (lastPublishRunIdx > 0) {
-    const block = [
-      "",
-      `      - name: Publish @intentius/chant-lexicon-${name}`,
-      `        working-directory: lexicons/${name}`,
-      "        run: npm publish --access public",
-    ];
-    lines.splice(lastPublishRunIdx + 1, 0, ...block);
-  }
-
   writeFileSync(filePath, lines.join("\n"));
   return { patched: true };
 }
@@ -246,7 +231,7 @@ export function onboardCommand(options: OnboardOptions): OnboardResult {
 
   // 3. Publish workflow
   const pubResult = patchPublishWorkflow(root, options.name);
-  if (pubResult.patched) patched.push("publish.yml (prepack + publish step)");
+  if (pubResult.patched) patched.push("publish.yml (prepack)");
   else skipped.push(`publish.yml: ${pubResult.reason}`);
 
   // 4. Dockerfiles

package/src/cli/handlers/graph.test.ts

@@ -43,6 +43,13 @@ vi.mock("../plugins", () => ({
   resolveProjectLexicons: (...a: unknown[]) => resolveLexMock(...a),
 }));
 const observeMock = vi.fn();
+const replayMock = vi.fn();
+const hasSnapshotMock = vi.fn((..._a: unknown[]) => Promise.resolve(false));
+vi.mock("../../lifecycle/replay", () => ({
+  replaySnapshots: (...a: unknown[]) => replayMock(...a),
+  hasSnapshot: (...a: unknown[]) => hasSnapshotMock(...a),
+}));
+
 vi.mock("../../lifecycle/observe", () => ({
   observeResources: (...a: unknown[]) => observeMock(...a),
 }));
@@ -435,6 +442,73 @@ describe("runGraph", () => {
       expect(out).toContain("web-vpc");
     });
 
+    // #1279 — `graph` had no `--at`, so anyone wanting the raw IR of a recorded
+    // estate had to reach for the live endpoint. A snapshot could answer most
+    // questions and never all of them.
+    test("--at graphs the recorded snapshot without reading the estate", async () => {
+      resolveLexMock.mockResolvedValue(["aws"]);
+      loadPluginsMock.mockResolvedValue([
+        { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}),
+          enrichLiveAttrs: () => Promise.reject(new Error("must not be called on a replay")) },
+      ]);
+      replayMock.mockResolvedValue({
+        observations: [{ lexicon: "aws", resources: {
+          web: { type: "AWS::EC2::Instance", status: "OBSERVED", physicalId: "i-1" },
+        } }],
+        commit: "abc1234def",
+        timestamp: "2026-07-31T00:00:00.000Z",
+      });
+      const exit = await runGraph({ args: makeArgs({ format: "ir", at: "latest", env: "prod" }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      expect(observeMock).not.toHaveBeenCalled();
+      expect(replayMock).toHaveBeenCalled();
+      expect(stdoutBuf.join("\n")).toContain("i-1");
+    });
+
+    // Denied the network, agents read the empty graph as an empty estate and
+    // spent their turns retrying --live. The per-entity warnings describe the
+    // same failure N times and never name the thing that would answer.
+    test("an unreadable estate names the recorded snapshot", async () => {
+      observeMock.mockClear();
+      hasSnapshotMock.mockResolvedValue(true);
+      resolveLexMock.mockResolvedValue(["aws"]);
+      loadPluginsMock.mockResolvedValue([
+        { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}) },
+      ]);
+      observeMock.mockResolvedValue({ observations: [], errors: ["could not connect"], warnings: [] });
+      const errs: string[] = [];
+      const spy = vi.spyOn(console, "error").mockImplementation((s: string) => { errs.push(s); });
+      await runGraph({ args: makeArgs({ format: "ir", live: true, env: "prod" }), plugins: [], serializers: [] });
+      spy.mockRestore();
+      hasSnapshotMock.mockResolvedValue(false);
+      expect(errs.join("\n")).toContain("--at latest");
+    });
+
+    test("says nothing about a snapshot when there is none to name", async () => {
+      observeMock.mockClear();
+      hasSnapshotMock.mockResolvedValue(false);
+      resolveLexMock.mockResolvedValue(["aws"]);
+      loadPluginsMock.mockResolvedValue([
+        { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}) },
+      ]);
+      observeMock.mockResolvedValue({ observations: [], errors: ["could not connect"], warnings: [] });
+      const errs: string[] = [];
+      const spy = vi.spyOn(console, "error").mockImplementation((s: string) => { errs.push(s); });
+      await runGraph({ args: makeArgs({ format: "ir", live: true, env: "prod" }), plugins: [], serializers: [] });
+      spy.mockRestore();
+      expect(errs.join("\n")).not.toContain("--at latest");
+    });
+
+    test("--at and --live together is refused rather than guessed at", async () => {
+      observeMock.mockClear();
+      replayMock.mockClear();
+      resolveLexMock.mockResolvedValue(["aws"]);
+      const exit = await runGraph({ args: makeArgs({ format: "ir", at: "latest", live: true, env: "prod" }), plugins: [], serializers: [] });
+      expect(exit).toBe(1);
+      expect(observeMock).not.toHaveBeenCalled();
+      expect(replayMock).not.toHaveBeenCalled();
+    });
+
     // Regression for #57: a single-stack project (no `*.component.ts` files —
     // discoverComponents returns an empty map) must observe exactly as before,
     // no `stacks` collected.

package/src/cli/handlers/graph.ts

@@ -6,6 +6,7 @@ import { buildGraphIr, buildLiveGraphIr, collectUnobserved, overlayGraphs, sourc
 import { buildDeclaredPerStack } from "../../graph-declared";
 import { reconstructEdges, mergeCatalogs, containmentGroups, type ReferenceCatalog, type ContainmentPair } from "../../graph-refs";
 import { observeResources } from "../../lifecycle/observe";
+import { replaySnapshots, hasSnapshot } from "../../lifecycle/replay";
 import { loadChantConfig, environmentNames } from "../../config";
 import { applyLiveEndpoint } from "../../live-endpoint";
 import { applyDetail, type DetailLevel } from "../../graph-detail";
@@ -47,9 +48,18 @@ export async function runGraph(ctx: CommandContext): Promise<number> {
     }));
     return 1;
   }
+  // `--at` graphs a recorded observation instead of reading the estate (#1279).
+  // Two different observations with no rule for which wins, so not both.
+  if (ctx.args.at && ctx.args.live) {
+    console.error(formatError({
+      message: "chant graph takes --live or --at, not both",
+      hint: "--live reads the estate now; --at graphs a recorded snapshot",
+    }));
+    return 1;
+  }
   // `--live` graphs the provisioned (observed) infrastructure, not the declared
   // source (epic #776). It only makes sense as a view format; default to `ir`.
-  if (ctx.args.live) {
+  if (ctx.args.live || ctx.args.at) {
     return runGraphLive(ctx, isViewFormat ? (ctx.args.format as (typeof viewFormats)[number]) : "ir");
   }
   if (isViewFormat) {
@@ -136,50 +146,81 @@ async function runGraphLive(
       }
     }
   } else {
-    console.error(formatWarning({ message: "component discovery failed — observing the single-stack convention instead" }));
-  }
-  // ChantConfig.stacks (with optional per-stack region) — multi-region estates.
-  for (const declared of config.stacks ?? []) {
-    if (!seenStacks.has(declared.name)) { seenStacks.add(declared.name); stacks.push({ name: declared.name, region: declared.region, src: declared.src }); }
-  }
+      console.error(formatWarning({ message: "component discovery failed — observing the single-stack convention instead" }));
+    }
+    // ChantConfig.stacks (with optional per-stack region) — multi-region estates.
+    for (const declared of config.stacks ?? []) {
+      if (!seenStacks.has(declared.name)) { seenStacks.add(declared.name); stacks.push({ name: declared.name, region: declared.region, src: declared.src }); }
+    }
 
-  // #1166 — an environment can declare its own endpoint (a local emulator like
-  // Floci), so this read is self-sufficient even when the ambient shell never
-  // exported e.g. AWS_ENDPOINT_URL. Ambient always wins when it's already set.
-  // Scoped to just this describe/enrich pass — restored in `finally` so it
-  // never leaks into a later invocation in the same process.
-  const endpointResult = applyLiveEndpoint(config.environments, environment, observing.map((p) => p.name));
-  if (endpointResult.notice) console.error(formatWarning({ message: endpointResult.notice }));
+    // #1166 — an environment can declare its own endpoint (a local emulator like
+    // Floci), so this read is self-sufficient even when the ambient shell never
+    // exported e.g. AWS_ENDPOINT_URL. Ambient always wins when it's already set.
+    // Scoped to just this describe/enrich pass — restored in `finally` so it
+    // never leaks into a later invocation in the same process.
+    const endpointResult = applyLiveEndpoint(config.environments, environment, observing.map((p) => p.name));
+    if (endpointResult.notice) console.error(formatWarning({ message: endpointResult.notice }));
+
+    let ir: GraphIR;
+    let observations: LiveObservation[];
+    // A replay is a graph of what was recorded, so it must not reach the provider
+    // at all — not for observation and not for enrichment. Anything that quietly
+    // called out would make `--at` a live read with an older label on it.
+    const replaying = !!args.at && !args.live;
+    try {
+      if (replaying) {
+        const scoped = new Set(stacks.filter((st) => st.src).map((st) => st.name));
+        const replay = await replaySnapshots(environment, String(args.at), scoped);
+        if ("error" in replay) {
+          console.error(formatError({ message: replay.error, ...(replay.hint ? { hint: replay.hint } : {}) }));
+          return 1;
+        }
+        observations = replay.observations;
+        console.error(formatWarning({
+          message: `graphing snapshot ${replay.commit.slice(0, 7)} taken ${replay.timestamp} — the estate was not read`,
+        }));
+      } else {
+      const observeResult = await observeResources(environment, observing, buildResult, {
+        owned: true,
+        stacks: [...stacks],
+      });
+      observations = observeResult.observations;
+      const { errors, warnings } = observeResult;
+      for (const e of errors) console.error(formatWarning({ message: e }));
+      // Unobserved entities (#1089) arrive as warnings — a node missing from the
+      // live graph because nobody looked is a different fact from one that isn't
+      // deployed, and the diagram alone cannot say which. Capped: an estate with no
+      // ownership markers can produce one per declared entity, and a wall of them
+      // buries the graph output. The full list is `lifecycle diff --live`.
+      const WARN_CAP = 5;
+      for (const w of warnings.slice(0, WARN_CAP)) console.error(formatWarning({ message: w }));
+      if (warnings.length > WARN_CAP) {
+        console.error(formatWarning({
+          message: `... and ${warnings.length - WARN_CAP} more entity(ies) not observed — run \`chant lifecycle diff ${environment} --live\` for the full list`,
+        }));
+    }
+    }
 
-  let ir: GraphIR;
-  let observations: LiveObservation[];
-  try {
-    const observeResult = await observeResources(environment, observing, buildResult, {
-      owned: true,
-      stacks: [...stacks],
-    });
-    observations = observeResult.observations;
-    const { errors, warnings } = observeResult;
-    for (const e of errors) console.error(formatWarning({ message: e }));
-    // Unobserved entities (#1089) arrive as warnings — a node missing from the
-    // live graph because nobody looked is a different fact from one that isn't
-    // deployed, and the diagram alone cannot say which. Capped: an estate with no
-    // ownership markers can produce one per declared entity, and a wall of them
-    // buries the graph output. The full list is `lifecycle diff --live`.
-    const WARN_CAP = 5;
-    for (const w of warnings.slice(0, WARN_CAP)) console.error(formatWarning({ message: w }));
-    if (warnings.length > WARN_CAP) {
+    // Both paths land here: a replay rejoins the live pipeline at exactly this
+    // point, which is what makes every fold and overlay below shared.
+    ir = buildLiveGraphIr(observations);
+
+    // The estate was asked for and nothing came back. Say that once, and say
+    // that a recording exists — the per-entity warnings above describe the same
+    // failure N times without ever naming the thing that would answer. Agents
+    // denied the network read the empty graph as an empty estate and spent
+    // their turns retrying `--live`.
+    if (!replaying && ir.nodes.length === 0 && (await hasSnapshot(environment))) {
       console.error(formatWarning({
-        message: `... and ${warnings.length - WARN_CAP} more entity(ies) not observed — run \`chant lifecycle diff ${environment} --live\` for the full list`,
+        message: `could not read the estate for "${environment}" — a snapshot of it is recorded; graph that instead with --at latest`,
       }));
     }
 
-    ir = buildLiveGraphIr(observations);
-
     // Enrich node attrs from the fuller live config (#784) so references are
     // present for edge reconstruction — describeResources metadata alone is often
     // too thin (e.g. AWS returns stack outputs, not per-resource references).
-    for (const p of observing) {
+    // Live-only: enrichment is a provider call, so a replay must skip it.
+    for (const p of replaying ? [] : observing) {
       if (!p.enrichLiveAttrs) continue;
       try {
         const enriched = await p.enrichLiveAttrs({ environment, owned: true, stacks });

package/src/cli/handlers/lifecycle.test.ts

@@ -734,6 +734,92 @@ describe("runLifecycleSnapshot", () => {
     expect(takeSnapshotMock).toHaveBeenCalledTimes(1);
   });
 
+  // #1261 — each stack declares the region it deploys to. Dropping it here
+  // observed every stack against the ambient region, so a multi-region estate
+  // snapshotted only the stacks that shared it and reported the rest as
+  // "no valid resources or artifacts returned".
+  test("multi-stack: each stack's declared region reaches takeSnapshot", async () => {
+    buildMock.mockResolvedValue(makeBuildResult({ aws: ["bucket"] }));
+    takeSnapshotMock.mockResolvedValue({
+      snapshots: [{ lexicon: "aws", environment: "prod", resources: { bucket: meta() } }],
+      commit: "sha",
+      warnings: [],
+      errors: [],
+    });
+    loadChantConfigMock.mockResolvedValue({ config: { environments: ["prod"], stacks: [
+      { name: "app-us-east-1", src: "src/us-east-1", region: "us-east-1" },
+      { name: "app-us-west-2", src: "src/us-west-2", region: "us-west-2" },
+    ] } });
+    const plugins: LexiconPlugin[] = [
+      createMockPlugin({ name: "aws", describeResources: staticDescribeResources({ bucket: meta() }) }),
+    ];
+
+    const exit = await runLifecycleSnapshot({
+      args: makeArgs({ command: "state", path: "snapshot", extraPositional: "prod" }),
+      plugins,
+      serializers: plugins.map((p) => p.serializer),
+    });
+
+    expect(exit).toBe(0);
+    // toMatchObject, not toEqual: this test is about region reaching the
+    // snapshot, and pinning the whole options object makes it fail whenever an
+    // unrelated option is added.
+    const opts = takeSnapshotMock.mock.calls.map((c) => c[3]);
+    expect(opts[0]).toMatchObject({ stack: "app-us-east-1", region: "us-east-1" });
+    expect(opts[1]).toMatchObject({ stack: "app-us-west-2", region: "us-west-2" });
+  });
+
+  // #1267 — --deep is opt-in and reaches takeSnapshot; without it the snapshot
+  // stays thin, which is what every pre-#1267 snapshot was.
+  test("--deep reaches takeSnapshot; absent means identity", async () => {
+    buildMock.mockResolvedValue(makeBuildResult({ aws: ["bucket"] }));
+    takeSnapshotMock.mockResolvedValue({
+      snapshots: [{ lexicon: "aws", environment: "prod", resources: { bucket: meta() } }],
+      commit: "sha",
+      warnings: [],
+      errors: [],
+    });
+    const plugins: LexiconPlugin[] = [
+      createMockPlugin({ name: "aws", describeResources: staticDescribeResources({ bucket: meta() }) }),
+    ];
+    const ctx = (deep?: boolean) => ({
+      args: makeArgs({ command: "state", path: "snapshot", extraPositional: "prod", ...(deep ? { deep: true } : {}) }),
+      plugins,
+      serializers: plugins.map((p) => p.serializer),
+    });
+
+    await runLifecycleSnapshot(ctx(true));
+    expect(takeSnapshotMock.mock.calls[0][3]).toMatchObject({ deep: true });
+
+    takeSnapshotMock.mockClear();
+    await runLifecycleSnapshot(ctx());
+    expect(takeSnapshotMock.mock.calls[0][3]).toMatchObject({ deep: undefined });
+  });
+
+  test("stack without a declared region: region stays undefined", async () => {
+    buildMock.mockResolvedValue(makeBuildResult({ aws: ["bucket"] }));
+    takeSnapshotMock.mockResolvedValue({
+      snapshots: [{ lexicon: "aws", environment: "prod", resources: { bucket: meta() } }],
+      commit: "sha",
+      warnings: [],
+      errors: [],
+    });
+    loadChantConfigMock.mockResolvedValue({ config: { environments: ["prod"], stacks: [
+      { name: "app", src: "src/app" },
+    ] } });
+    const plugins: LexiconPlugin[] = [
+      createMockPlugin({ name: "aws", describeResources: staticDescribeResources({ bucket: meta() }) }),
+    ];
+
+    await runLifecycleSnapshot({
+      args: makeArgs({ command: "state", path: "snapshot", extraPositional: "prod" }),
+      plugins,
+      serializers: plugins.map((p) => p.serializer),
+    });
+
+    expect(takeSnapshotMock.mock.calls[0][3]).toMatchObject({ stack: "app", region: undefined });
+  });
+
   // #1166 — a snapshot is always a live read, so a declared environment
   // endpoint applies here too, unless the ambient shell already set it.
   describe("declared endpoint (#1166)", () => {

package/src/cli/handlers/lifecycle.ts

@@ -62,6 +62,11 @@ interface StackTarget {
   /** Build root to synthesize this stack from, scoped so its logical ids match
    * what the stack actually deploys. */
   root: string;
+  /** Region the stack is deployed in, from `stacks[].region` (#1261). Without
+   * it every stack is observed against the ambient region, so a multi-region
+   * estate snapshots only the stacks that happen to share it and reports the
+   * rest as "no valid resources or artifacts returned". */
+  region?: string;
 }
 
 /**
@@ -75,7 +80,7 @@ interface StackTarget {
 function resolveStackTargets(args: ParsedArgs, config: ChantConfig): StackTarget[] {
   if (args.src) return [{ root: resolve(args.src) }];
   if (config.stacks && config.stacks.length > 0) {
-    return config.stacks.map((s) => ({ stack: s.name, root: resolve(s.src) }));
+    return config.stacks.map((s) => ({ stack: s.name, root: resolve(s.src), region: s.region }));
   }
   return [{ root: resolveBuildRoot(args, config) }];
 }
@@ -133,19 +138,39 @@ export async function runLifecycleSnapshot(ctx: CommandContext): Promise<number>
   const endpointResult = applyLiveEndpoint(config.environments, environment, observingPlugins.map((p) => p.name));
   if (endpointResult.notice) console.error(formatWarning({ message: endpointResult.notice }));
 
+  // Build every stack first, so the ambient scan (#1278) can be bounded by the
+  // kinds the PROJECT manages rather than the ones this stack happens to
+  // declare. "Which of my security groups are unused" is a question about the
+  // estate; a region whose stack declares no security group still has a default
+  // one, and scoping the bound per stack silently drops it.
+  const built: Array<{ target: (typeof targets)[number]; buildResult: Awaited<ReturnType<typeof build>> }> = [];
+  for (const target of targets) {
+    const label = target.stack ? `stack "${target.stack}"` : "project";
+    const buildResult = await build(target.root, targetSerializers);
+    if (buildResult.errors.length > 0) {
+      console.error(formatError({ message: `Build failed for ${label} — fix errors before taking a snapshot` }));
+      anyHardError = true;
+      continue;
+    }
+    built.push({ target, buildResult });
+  }
+  const projectKinds = [
+    ...new Set(built.flatMap(({ buildResult }) => [...buildResult.entities.values()].map((e) => e.entityType))),
+  ];
+
   try {
-    for (const target of targets) {
+    for (const { target, buildResult } of built) {
       const label = target.stack ? `stack "${target.stack}"` : "project";
-      const buildResult = await build(target.root, targetSerializers);
-      if (buildResult.errors.length > 0) {
-        console.error(formatError({ message: `Build failed for ${label} — fix errors before taking a snapshot` }));
-        anyHardError = true;
-        continue;
-      }
 
       let result;
       try {
-        result = await takeSnapshot(environment, observingPlugins, buildResult, { stack: target.stack });
+        result = await takeSnapshot(environment, observingPlugins, buildResult, {
+          stack: target.stack,
+          region: target.region,
+          deep: args.deep,
+          ambient: args.ambient,
+          ambientKinds: projectKinds,
+        });
       } catch (err) {
         if (err instanceof StaleLifecycleBranchError) {
           console.error(formatError({
@@ -214,7 +239,15 @@ export async function runLifecycleShow(ctx: CommandContext): Promise<number> {
 
     for (const [lexicon, content] of snapshots) {
       const snapshot: LifecycleSnapshot = JSON.parse(content);
-      console.log(`\n${formatBold(`${environment}/${lexicon}`)} — ${Object.keys(snapshot.resources).length} resources — ${snapshot.timestamp}`);
+      // Depth is stated, not inferred (#1267). An identity snapshot cannot
+      // answer a property question, and a reader that assumes otherwise reads
+      // "no properties recorded" as "no such properties".
+      const depth = snapshot.depth ?? "identity";
+      const depthNote =
+        depth === "deep"
+          ? ` — deep (${Object.keys(snapshot.properties ?? {}).length} property trees)`
+          : " — identity only";
+      console.log(`\n${formatBold(`${environment}/${lexicon}`)} — ${Object.keys(snapshot.resources).length} resources${depthNote} — ${snapshot.timestamp}`);
       printSnapshotTable(snapshot);
     }
   }