@intentius/chant 0.33.1 → 0.34.0

package/src/lifecycle/snapshot.ts

@@ -5,8 +5,11 @@
 import type { ObservationLexicon, ResourceMetadata, ArtifactMetadata } from "../lexicon";
 import type { BuildResult } from "../build";
 import type { SerializerResult } from "../serializer";
-import type { LifecycleSnapshot } from "./types";
+import type { LifecycleSnapshot, ObservationDepth } from "./types";
+import { observeDeep } from "./deep-observe";
+import type { DeepResourceObservation } from "../deep-observation";
 import { computeBuildDigest } from "./digest";
+import { collectDependencies, collectAmbient } from "./observe";
 import { writeSnapshot, snapshotStorageKey, getHeadCommit, pushLifecycle } from "./git";
 import { sortedJsonReplacer } from "../utils";
 import { formatUnobserved, normalizeObservation, unobservedAll, type UnobservedEntity } from "../observation";
@@ -80,9 +83,24 @@ export async function takeSnapshot(
   environment: string,
   plugins: ObservationLexicon[],
   buildResult: BuildResult,
-  opts?: { cwd?: string; stack?: string },
+  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> {
   const stack = opts?.stack;
+  const depth: ObservationDepth = opts?.deep ? "deep" : "identity";
+  // A stack declares the region it deploys to (#1261). Passing it through is
+  // what lets a multi-region estate be observed at all: the reader targets the
+  // stack's own region rather than whichever one the shell happens to be set
+  // to, so out-of-region stacks stop coming back empty.
+  const region = opts?.region;
   const warnings: string[] = [];
   const errors: string[] = [];
   const snapshots: LifecycleSnapshot[] = [];
@@ -131,6 +149,7 @@ export async function takeSnapshot(
             entityNames,
             entities,
             stack,
+            region,
           }),
         );
         const { valid, dropped, warnings: validationWarnings } = validateResources(observed.resources);
@@ -149,6 +168,8 @@ export async function takeSnapshot(
       }
 
       if (plugin.listArtifacts) {
+        // No region: artifacts are registry/chart objects (docker, helm), not
+        // regional cloud resources, and `listArtifacts` takes no region.
         const raw = await plugin.listArtifacts({ environment, entities, stack });
         const { valid, dropped, warnings: validationWarnings } = validateResources(raw);
         warnings.push(...validationWarnings);
@@ -168,15 +189,79 @@ export async function takeSnapshot(
         continue;
       }
 
+      // The deep read is a second pass, after identity is known to be readable
+      // (#1267). Keeping it separate means a lexicon with no deep reader still
+      // snapshots exactly as before, and a deep read that comes back empty
+      // downgrades the record rather than discarding an identity snapshot that
+      // was already good.
+      let properties: Record<string, DeepResourceObservation> | undefined;
+      let recordedDepth: ObservationDepth = "identity";
+      if (depth === "deep") {
+        if (!plugin.observeResourcesDeep) {
+          warnings.push(
+            `${plugin.name}: no deep reader — recording an identity snapshot; property questions cannot be answered from it`,
+          );
+        } else {
+          const observed = await observeDeep(plugin, {
+            environment,
+            buildOutput,
+            entities,
+            ...(stack ? { stack } : {}),
+            ...(region ? { region } : {}),
+          });
+          for (const [name, entry] of Object.entries(observed.unobserved)) {
+            warnings.push(`${plugin.name}: not observed deeply — ${formatUnobserved(name, entry)}`);
+          }
+          if (Object.keys(observed.resources).length > 0) {
+            properties = observed.resources;
+            recordedDepth = "deep";
+          } else {
+            warnings.push(
+              `${plugin.name}: deep read returned no properties — recording an identity snapshot`,
+            );
+          }
+        }
+      }
+      // What this estate depends on but does not manage (#1273), recorded so a
+      // replayed snapshot can answer the same questions a live read can (#1266).
+      // Without them a snapshot holds the managed resources and no route to the
+      // account's default VPC, so `internetFacing` is unanswerable from it —
+      // which would make `search --at` quietly weaker than `search --live`.
+      const dependencies = await collectDependencies(plugin, {
+        environment,
+        entities,
+        observed: resources,
+        stacks: stack ? [{ name: stack, ...(region ? { region } : {}) }] : [],
+      });
+      for (const message of dependencies.warnings) warnings.push(message);
+      // Ambient resources (#1278) are recorded too when asked for, so a replayed
+      // snapshot can answer "which of these are unused" without a live read.
+      // Without this `search --at --ambient` filters a set that was never
+      // recorded and silently returns nothing.
+      const ambient = opts?.ambient
+        ? await collectAmbient(plugin, {
+            environment,
+            kinds: opts?.ambientKinds ?? [...new Set([...entities.values()].map((e) => e.entityType))],
+            observed: resources,
+            stacks: stack ? [{ name: stack, ...(region ? { region } : {}) }] : [],
+            warnings,
+          })
+        : {};
+      const withDependencies = { ...resources, ...dependencies.resources, ...ambient };
+
       const snapshot: LifecycleSnapshot = {
         lexicon: plugin.name,
         environment,
         ...(stack ? { stack } : {}),
         commit: headCommit,
         timestamp,
-        resources,
+        resources: withDependencies,
+        ...(dependencies.edges.length > 0 ? { edges: dependencies.edges } : {}),
         ...(Object.keys(unobserved).length > 0 && { unobserved }),
         ...(Object.keys(artifacts).length > 0 && { artifacts }),
+        // Only written when deep. An absent field means identity, which is what
+        // every snapshot taken before #1267 was.
+        ...(recordedDepth === "deep" && { depth: recordedDepth, properties }),
         digest,
       };
 

package/src/lifecycle/types.ts

@@ -1,8 +1,25 @@
 import type { ResourceMetadata, ArtifactMetadata } from "../lexicon";
 import type { UnobservedEntity } from "../observation";
+import type { DeepResourceObservation } from "../deep-observation";
+import type { IREdge } from "../graph-ir";
 
 export type { ResourceMetadata, ArtifactMetadata } from "../lexicon";
 
+/**
+ * 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.
  */
@@ -28,6 +45,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;
 }