@intentius/chant 0.33.0 → 0.34.0

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

@@ -1 +1 @@
-{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/lifecycle/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAI5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAUnD,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,kBAAkB,EAAE,EAC7B,WAAW,EAAE,WAAW,EACxB,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,GACnG,OAAO,CAAC,aAAa,CAAC,CA6HxB"}
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/lifecycle/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAI5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAUnD,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,kBAAkB,EAAE,EAC7B,WAAW,EAAE,WAAW,EACxB,IAAI,CAAC,EAAE;IACL,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzE;;8CAE0C;IAC1C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GACA,OAAO,CAAC,aAAa,CAAC,CA6JxB;AAyBD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,kBAAkB,EAC1B,IAAI,EAAE;IACJ,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC3C,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/D,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,GACA,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAqB3C;AAED,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC5C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,kBAAkB,EAC1B,IAAI,EAAE;IACJ,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC3C,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChE,GACA,OAAO,CAAC,qBAAqB,CAAC,CA0ChC"}

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/dist/observation.d.ts

@@ -120,4 +120,75 @@ export declare function mergeObservations(parts: Iterable<NormalizedObservation>
 export declare function unobservedReasonText(reason: UnobservedReason): string;
 /** `name — reason (detail)`, the shared rendering for CLI and plan output. */
 export declare function formatUnobserved(name: string, entry: UnobservedEntity): string;
+/** One declared entity handed to the harness. */
+export interface DeclaredEntity {
+    /** chant entity name — the key every outcome is filed under. */
+    name: string;
+    /** Declared entity type (e.g. `AWS::EC2::VPC`). */
+    type: string;
+    /** Declared properties, for the adapter to derive a physical address from. */
+    props: Record<string, unknown>;
+}
+/**
+ * The outcome of reading one entity, mapped onto the tri-state:
+ * - `present` — a key in `resources`.
+ * - `absent` — in neither map (the provider was asked and reported it missing).
+ * - `unobserved` — a typed NOT-OBSERVED (unsupported kind, filtered, read error).
+ */
+export type EntityObservation = {
+    present: ResourceMetadata;
+} | {
+    absent: true;
+} | {
+    unobserved: {
+        reason: UnobservedReason;
+        detail?: string;
+    };
+};
+/** What a lexicon supplies to drive the harness. `Client` is its transport handle. */
+export interface ObserverAdapter<Client> {
+    /**
+     * Reach the provider on the applier's transport. Throw for a whole-lexicon
+     * failure; {@link classifyBindFailure} decides what the throw means.
+     */
+    bind(): Promise<Client>;
+    /**
+     * Map a `bind()` throw to a typed whole-lexicon reason (every entity becomes
+     * NOT-OBSERVED with it), or `"rethrow"` for a loud refusal that must not be
+     * swallowed — a context/subscription mismatch, which core turns into an
+     * honest hole per entity at a higher layer.
+     */
+    classifyBindFailure(err: unknown): {
+        reason: UnobservedReason;
+        detail?: string;
+    } | "rethrow";
+    /** Read one declared entity. A throw here is caught and recorded `read-failed`. */
+    read(client: Client, entity: DeclaredEntity): Promise<EntityObservation>;
+    /**
+     * Run `fn` over `items` concurrently. Supply the transport's own bounded pool
+     * (the k8s client's `concurrently`, say); when omitted the harness uses
+     * {@link boundedConcurrently}, so "N entities is not N serial spawns" holds
+     * for every lexicon whether or not its transport ships a pool.
+     */
+    concurrently?<T>(items: readonly T[], fn: (item: T) => Promise<void>): Promise<void>;
+}
+/** Default concurrency for {@link boundedConcurrently} when a transport ships no pool. */
+export declare const DEFAULT_OBSERVE_CONCURRENCY = 16;
+/**
+ * Run `fn` over `items` with at most `limit` in flight. A rejected `fn` rejects
+ * the whole run (the harness wraps per-entity reads so this stays for genuinely
+ * unexpected faults).
+ */
+export declare function boundedConcurrently<T>(items: readonly T[], fn: (item: T) => Promise<void>, limit?: number): Promise<void>;
+/**
+ * The shared observer control flow (#1201). Binds via the adapter, reads every
+ * declared entity concurrently, and assembles the tri-state {@link ObservationResult}.
+ *
+ * A `bind()` throw becomes NOT-OBSERVED for every entity (typed by
+ * {@link ObserverAdapter.classifyBindFailure}) unless the adapter asks to
+ * rethrow. A per-entity `read()` throw the adapter did not itself map becomes
+ * `read-failed` for that one entity — never a silent absence, which would
+ * classify as a spurious `create`.
+ */
+export declare function observeEntities<Client>(declared: readonly DeclaredEntity[], adapter: ObserverAdapter<Client>): Promise<ObservationResult>;
 //# sourceMappingURL=observation.d.ts.map

package/dist/observation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observation.d.ts","sourceRoot":"","sources":["../src/observation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,gBAAgB,GACxB,aAAa,GACb,gBAAgB,GAChB,YAAY,GACZ,kBAAkB,GAClB,UAAU,CAAC;AAEf,mFAAmF;AACnF,eAAO,MAAM,kBAAkB,EAAE,SAAS,gBAAgB,EAMzD,CAAC;AAEF,6DAA6D;AAC7D,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAE5E;AAED,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B,kGAAkG;IAClG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qBAAqB;IACrB,MAAM,EAAE,gBAAgB,CAAC;IACzB,qGAAqG;IACrG,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,2GAA2G;IAC3G,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC5C,+GAA+G;IAC/G,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC/C;AAED;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,iBAAiB,CAAC;AAE3F,2EAA2E;AAC3E,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC5C,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC9C;AAED,6EAA6E;AAC7E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAM9E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,EAC3C,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAC5C,iBAAiB,CAMnB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,uBAAuB,GAAG,SAAS,GAAG,qBAAqB,CAMtG;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,EACvB,MAAM,EAAE,gBAAgB,EACxB,MAAM,CAAC,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACnE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAYlC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,qBAAqB,CAAC,GAAG,qBAAqB,CAW/F;AAED,2DAA2D;AAC3D,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAarE;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAG9E"}
+{"version":3,"file":"observation.d.ts","sourceRoot":"","sources":["../src/observation.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "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)", () => {