@intentius/chant 0.28.0 → 0.29.0

package/src/lifecycle/change-set.ts

@@ -13,11 +13,12 @@
  * load-bearing.
  */
 import { diffLive, type AttributeChange, type DiffLiveInput } from "./live-diff";
+import { unobservedReasonText, type UnobservedReason } from "../observation";
 
 /**
  * What the projection proposes for a single resource.
  *
- * - `create` — declared in source, absent from live.
+ * - `create` — declared in source, and the provider **confirmed** it absent.
  * - `update` — declared and live, but live config drifted.
  * - `delete` — a chant-owned resource that is live but no longer declared.
  *   Only emitted once ownership is known (#121); never inferred from the
@@ -25,8 +26,11 @@ import { diffLive, type AttributeChange, type DiffLiveInput } from "./live-diff"
  * - `adopt` — live but undeclared, ownership not established → a candidate to
  *   pull back into source, never an auto-delete.
  * - `noop` — declared and live with no drift, or already reconciled.
+ * - `unobserved` — declared, and the lexicon could not look (#1089). Not a
+ *   proposal at all: it is the plan admitting a hole. Never a create, never a
+ *   delete. Read `unobservedReason` for which hole.
  */
-export type ChangeAction = "create" | "update" | "delete" | "adopt" | "noop";
+export type ChangeAction = "create" | "update" | "delete" | "adopt" | "noop" | "unobserved";
 
 /**
  * Who answers "is this resource chant's?". `unknown` until a live ownership
@@ -47,13 +51,24 @@ export interface ChangeSetEntry {
     declared: boolean;
     /** Present in the last snapshot. */
     inSnapshot: boolean;
-    /** Observed in the live system right now. */
+    /** Observed present in the live system right now. */
     live: boolean;
+    /**
+     * The lexicon actually looked at this entity (#1089). `false` with
+     * `live: false` means "unknown", not "absent" — the distinction the whole
+     * change set now rests on. Absent-and-looked-at is `observed: true,
+     * live: false`.
+     */
+    observed: boolean;
   };
   /** Attribute-level changes, for `update`. */
   deltas?: AttributeChange[];
   /** Live-marker ownership. Defaults to `unknown`. */
   ownership: Ownership;
+  /** Why the entity could not be observed, for `action: "unobserved"` (#1089). */
+  unobservedReason?: UnobservedReason;
+  /** Human-readable backing for `unobservedReason` (the failing command, the missing binding). */
+  unobservedDetail?: string;
 }
 
 export interface ChangeSet {
@@ -67,11 +82,16 @@ export interface ChangeSet {
  * `create`/`update` are precise from declared-vs-live. `delete` is never
  * emitted here — an undeclared live resource classifies as `adopt` until
  * ownership is known.
+ *
+ * A declared entity the lexicon could not observe (`input.unobserved`, #1089)
+ * classifies as `unobserved` and nothing else: no `create` is ever synthesized
+ * from a read that did not happen.
  */
 export function buildChangeSet(env: string, input: DiffLiveInput): ChangeSet {
   const diff = diffLive(input);
   const { declared, observedNow } = input;
   const observedThen = input.observedThen ?? {};
+  const unobservedInput = input.unobserved ?? {};
 
   const driftByName = new Map(
     diff.driftedSinceSnapshot.map((d) => [d.name, d.changes] as const),
@@ -81,6 +101,7 @@ export function buildChangeSet(env: string, input: DiffLiveInput): ChangeSet {
     ...declared,
     ...Object.keys(observedNow),
     ...Object.keys(observedThen),
+    ...Object.keys(unobservedInput),
   ]);
 
   const entries: ChangeSetEntry[] = [];
@@ -88,8 +109,11 @@ export function buildChangeSet(env: string, input: DiffLiveInput): ChangeSet {
     const isDeclared = declared.has(name);
     const live = Object.prototype.hasOwnProperty.call(observedNow, name);
     const inSnapshot = Object.prototype.hasOwnProperty.call(observedThen, name);
-    const type = observedNow[name]?.type ?? observedThen[name]?.type;
-    const evidence = { declared: isDeclared, inSnapshot, live };
+    // A returned resource was observed by definition; `unobserved` only counts
+    // for entities the lexicon did not return.
+    const unobservedEntry = live ? undefined : unobservedInput[name];
+    const type = observedNow[name]?.type ?? observedThen[name]?.type ?? unobservedEntry?.type;
+    const evidence = { declared: isDeclared, inSnapshot, live, observed: !unobservedEntry };
 
     // Ownership comes from the LIVE marker only (carried on observedNow), never
     // from the snapshot. This is the invariant that keeps the snapshot from
@@ -100,8 +124,13 @@ export function buildChangeSet(env: string, input: DiffLiveInput): ChangeSet {
     let action: ChangeAction;
     let deltas: AttributeChange[] | undefined;
 
-    if (isDeclared && !live) {
-      // Declared in source, not in the cloud → create.
+    if (unobservedEntry) {
+      // The lexicon never looked. Absence is not established, so neither a
+      // create (declared) nor a delete/adopt (undeclared) can be proposed —
+      // the entry exists to say the plan has a hole here.
+      action = "unobserved";
+    } else if (isDeclared && !live) {
+      // Declared in source, and the provider confirmed it absent → create.
       action = "create";
     } else if (isDeclared && live) {
       const drift = driftByName.get(name);
@@ -120,14 +149,27 @@ export function buildChangeSet(env: string, input: DiffLiveInput): ChangeSet {
       action = "noop";
     }
 
-    entries.push({ name, type, action, evidence, deltas, ownership });
+    entries.push({
+      name,
+      type,
+      action,
+      evidence,
+      deltas,
+      ownership,
+      ...(unobservedEntry
+        ? {
+            unobservedReason: unobservedEntry.reason,
+            ...(unobservedEntry.detail ? { unobservedDetail: unobservedEntry.detail } : {}),
+          }
+        : {}),
+    });
   }
 
   entries.sort((a, b) => a.name.localeCompare(b.name));
   return { env, entries };
 }
 
-const ACTION_ORDER: ChangeAction[] = ["create", "update", "delete", "adopt", "noop"];
+const ACTION_ORDER: ChangeAction[] = ["create", "update", "delete", "adopt", "noop", "unobserved"];
 
 /** Count entries per action. */
 export function summarize(cs: ChangeSet): Record<ChangeAction, number> {
@@ -137,6 +179,7 @@ export function summarize(cs: ChangeSet): Record<ChangeAction, number> {
     delete: 0,
     adopt: 0,
     noop: 0,
+    unobserved: 0,
   };
   for (const e of cs.entries) counts[e.action]++;
   return counts;
@@ -148,8 +191,10 @@ export function summarize(cs: ChangeSet): Record<ChangeAction, number> {
  * GitLab renders an `artifacts:reports:terraform` artifact in the merge-request
  * UI as "N to add, M to change, K to delete". The format is generic — any tool
  * that emits this JSON gets the widget — and the chant plan maps onto it
- * directly. Only the mutating actions count: `adopt` and `noop` are excluded,
- * since the widget has no column for "live but undeclared" or "no change".
+ * directly. Only the mutating actions count: `adopt`, `noop` and `unobserved`
+ * are excluded, since the widget has no column for "live but undeclared", "no
+ * change", or "could not look" (#1089). The widget is therefore a floor, not a
+ * complete plan: read the full change set when entities are unobserved.
  *
  * The widget label reads "Terraform" regardless of producer; that is GitLab's
  * fixed string, not a claim chant makes.
@@ -175,10 +220,17 @@ export function renderChangeSet(cs: ChangeSet): string {
   for (const action of ACTION_ORDER) {
     const group = cs.entries.filter((e) => e.action === action);
     if (group.length === 0) continue;
-    lines.push(`\n${action.toUpperCase()}:`);
+    lines.push(
+      action === "unobserved"
+        ? "\nUNOBSERVED (declared; chant could not read live state — no action proposed):"
+        : `\n${action.toUpperCase()}:`,
+    );
     for (const e of group) {
       const own = e.ownership === "unknown" ? "" : ` [${e.ownership}]`;
-      lines.push(`  ${e.name}${e.type ? ` (${e.type})` : ""}${own}`);
+      const why = e.unobservedReason
+        ? ` — ${unobservedReasonText(e.unobservedReason)}${e.unobservedDetail ? `: ${e.unobservedDetail}` : ""}`
+        : "";
+      lines.push(`  ${e.name}${e.type ? ` (${e.type})` : ""}${own}${why}`);
       for (const d of e.deltas ?? []) {
         lines.push(`      ${d.path}: ${fmt(d.oldValue)} → ${fmt(d.newValue)}`);
       }

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

@@ -23,6 +23,7 @@ describe("diffLive", () => {
       newlyObserved: [],
       driftedSinceSnapshot: [],
       unchanged: [],
+      unobserved: [],
     });
   });
 
@@ -112,6 +113,44 @@ describe("diffLive", () => {
     expect(result.driftedSinceSnapshot.map((d) => d.name)).toEqual(["c"]);
     expect(result.unchanged).toEqual(["b"]);
   });
+
+  // ── The observation tri-state (#1089) ─────────────────────────────────────
+
+  test("declared and not observed → unobserved, not missing", () => {
+    const result = diffLive({
+      declared: new Set(["crd", "gone"]),
+      observedNow: {},
+      observedThen: undefined,
+      unobserved: { crd: { type: "K8s::X::Widget", reason: "unsupported-kind", detail: "no reader" } },
+    });
+    expect(result.missing).toEqual(["gone"]);
+    expect(result.unobserved).toEqual([
+      { name: "crd", type: "K8s::X::Widget", reason: "unsupported-kind", detail: "no reader" },
+    ]);
+  });
+
+  test("an unobserved entity in the last snapshot has not disappeared", () => {
+    const result = diffLive({
+      declared: new Set(["crd"]),
+      observedNow: {},
+      observedThen: { crd: meta() },
+      unobserved: { crd: { reason: "no-credentials" } },
+    });
+    expect(result.disappeared).toEqual([]);
+    expect(result.missing).toEqual([]);
+    expect(result.unobserved.map((u) => u.name)).toEqual(["crd"]);
+  });
+
+  test("a resource that was returned is never also unobserved", () => {
+    const result = diffLive({
+      declared: new Set(["a"]),
+      observedNow: { a: meta() },
+      observedThen: undefined,
+      unobserved: { a: { reason: "read-failed" } },
+    });
+    expect(result.unobserved).toEqual([]);
+    expect(result.newlyObserved).toEqual(["a"]);
+  });
 });
 
 describe("diffLiveArtifacts", () => {

package/src/lifecycle/live-diff.ts

@@ -13,6 +13,7 @@
  *                        outside chant's entity model)
  */
 import type { ResourceMetadata, ArtifactMetadata } from "../lexicon";
+import type { UnobservedEntity, UnobservedReason } from "../observation";
 
 export interface AttributeChange {
   /** Attribute path (e.g. "status", "physicalId", "attributes.tags.env"). */
@@ -27,8 +28,20 @@ export interface ResourceDrift {
   changes: AttributeChange[];
 }
 
+/** A declared entity the lexicon could not observe, as reported by the diff (#1089). */
+export interface UnobservedResource {
+  name: string;
+  type?: string;
+  reason: UnobservedReason;
+  detail?: string;
+}
+
 export interface LiveDiffResult {
-  /** Declared in current build, but not observed in cloud right now. */
+  /**
+   * Declared in current build, and the provider reported it absent. Entities
+   * the lexicon could not observe are NOT here — they are in `unobserved`
+   * (#1089), so "missing" keeps meaning "confirmed not there".
+   */
   missing: string[];
   /** Observed in cloud right now, but not declared. */
   orphan: string[];
@@ -40,6 +53,12 @@ export interface LiveDiffResult {
   driftedSinceSnapshot: ResourceDrift[];
   /** Observed both then and now; metadata identical. */
   unchanged: string[];
+  /**
+   * Declared, and the lexicon could not look (#1089) — no reader for the kind,
+   * the read failed, no credentials, no binding. Not drift, not absence: a hole
+   * in the observation. Sorted by name.
+   */
+  unobserved: UnobservedResource[];
 }
 
 export interface DiffLiveInput {
@@ -49,6 +68,12 @@ export interface DiffLiveInput {
   observedNow: Record<string, ResourceMetadata>;
   /** Resources captured by the previous snapshot, if any. */
   observedThen: Record<string, ResourceMetadata> | undefined;
+  /**
+   * Declared entities `describeResources()` reported as NOT-OBSERVED (#1089),
+   * keyed by entity name. Absent/empty means every declared entity was looked
+   * at, so absence from `observedNow` is a confirmed absence.
+   */
+  unobserved?: Record<string, UnobservedEntity>;
 }
 
 const TRACKED_FIELDS: Array<keyof ResourceMetadata> = [
@@ -135,6 +160,12 @@ export function diffLive(input: DiffLiveInput): LiveDiffResult {
   const observedThenMap = observedThen ?? {};
   const observedNowNames = new Set(Object.keys(observedNow));
   const observedThenNames = new Set(Object.keys(observedThenMap));
+  // A resource the lexicon returned is observed, whatever it also said about
+  // it — present beats not-observed.
+  const unobservedMap = input.unobserved ?? {};
+  const unobservedNames = new Set(
+    Object.keys(unobservedMap).filter((n) => !observedNowNames.has(n)),
+  );
 
   const missing: string[] = [];
   const orphan: string[] = [];
@@ -142,10 +173,23 @@ export function diffLive(input: DiffLiveInput): LiveDiffResult {
   const newlyObserved: string[] = [];
   const driftedSinceSnapshot: ResourceDrift[] = [];
   const unchanged: string[] = [];
+  const unobserved: UnobservedResource[] = [];
+
+  for (const name of unobservedNames) {
+    const entry = unobservedMap[name];
+    unobserved.push({
+      name,
+      ...(entry.type ? { type: entry.type } : {}),
+      reason: entry.reason,
+      ...(entry.detail ? { detail: entry.detail } : {}),
+    });
+  }
 
-  // Declared but not observed in cloud right now → missing
+  // Declared, looked at, and the provider said it isn't there → missing.
+  // Declared but never looked at is `unobserved`, not missing — the whole point
+  // of #1089: "we didn't check" must not read as "it isn't there".
   for (const name of declared) {
-    if (!observedNowNames.has(name)) {
+    if (!observedNowNames.has(name) && !unobservedNames.has(name)) {
       missing.push(name);
     }
   }
@@ -157,9 +201,10 @@ export function diffLive(input: DiffLiveInput): LiveDiffResult {
     }
   }
 
-  // In previous snapshot but not observed now → disappeared
+  // In previous snapshot but not observed now → disappeared. An entity nobody
+  // could look at has not disappeared; it is unobserved.
   for (const name of observedThenNames) {
-    if (!observedNowNames.has(name)) {
+    if (!observedNowNames.has(name) && !unobservedNames.has(name)) {
       disappeared.push(name);
     }
   }
@@ -194,6 +239,7 @@ export function diffLive(input: DiffLiveInput): LiveDiffResult {
     newlyObserved: newlyObserved.sort(),
     driftedSinceSnapshot: driftedSinceSnapshot.sort((a, b) => a.name.localeCompare(b.name)),
     unchanged: unchanged.sort(),
+    unobserved: unobserved.sort((a, b) => a.name.localeCompare(b.name)),
   };
 }
 

package/src/lifecycle/observe.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from "vitest";
 import { observeResources } from "./observe";
+import { observation } from "../observation";
 import type { ObservationLexicon, ResourceMetadata } from "../lexicon";
 import type { BuildResult } from "../build";
 
@@ -47,13 +48,20 @@ describe("observeResources", () => {
     expect(names).toEqual(["web-vpc"]);
   });
 
-  it("collects a throwing plugin into errors instead of failing the whole graph", async () => {
+  it("collects a throwing plugin into errors instead of failing the whole graph, and reports its entities unobserved (#1089)", async () => {
     const plugins = [
       awsPlugin(() => { throw new Error("access denied"); }),
     ];
-    const { observations, errors } = await observeResources("prod", plugins, mockBuild());
-    expect(observations).toEqual([]);
+    const { observations, errors, warnings } = await observeResources("prod", plugins, mockBuild());
     expect(errors).toEqual(["aws: access denied"]);
+    // The failed read is a hole, not an empty environment: every declared
+    // entity comes back NOT-OBSERVED so nothing downstream reads it as absent.
+    expect(observations).toHaveLength(1);
+    expect(observations[0].resources).toEqual({});
+    expect(observations[0].unobserved).toEqual({
+      "web-vpc": { reason: "read-failed", type: "AWS::EC2::VPC", detail: "access denied" },
+    });
+    expect(warnings.join("\n")).toContain("web-vpc");
   });
 
   it("skips plugins with no describeResources and drops empty results", async () => {
@@ -63,6 +71,69 @@ describe("observeResources", () => {
     expect(observations).toEqual([]);
   });
 
+  // #1166 — this is exactly the "wrong endpoint" shape: AWS's stackDoesNotExist
+  // branch returns an empty map (bare `{}`, no #1089 envelope) for a declared
+  // entity nobody could actually observe. Before the fix this vanished with
+  // neither an observation nor a warning; now it must say so.
+  it("warns when a lexicon with declared entities observes zero resources and nothing is unobserved either (#1166)", async () => {
+    const empty = awsPlugin(() => ({}));
+    const { observations, warnings } = await observeResources("prod", [empty], mockBuild());
+    expect(observations).toEqual([]); // still no observation pushed — nothing to graph
+    expect(warnings).toEqual([
+      'aws: 0 live resources for env "prod" (1 declared) — check the endpoint/credentials',
+    ]);
+  });
+
+  it("does not warn about zero resources when the lexicon declares no entities at all", async () => {
+    const empty = awsPlugin(() => ({}));
+    const noEntities: BuildResult = { outputs: new Map(), entities: new Map(), errors: [] } as unknown as BuildResult;
+    const { warnings } = await observeResources("prod", [empty], noEntities);
+    expect(warnings).toEqual([]);
+  });
+
+  it("does not double-warn when the emptiness is already explained by #1089 unobserved", async () => {
+    const plugin = {
+      name: "aws",
+      serializer: {} as ObservationLexicon["serializer"],
+      describeResources: async () =>
+        observation({}, { "web-vpc": { type: "AWS::EC2::VPC", reason: "no-binding" } }),
+    } as unknown as ObservationLexicon;
+    const { warnings } = await observeResources("prod", [plugin], mockBuild());
+    // Only the #1089 per-entity warning — no separate "0 live resources" line.
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain("no binding for this environment");
+  });
+
+  it("carries a plugin's own unobserved entities through (#1089)", async () => {
+    const plugin = {
+      name: "aws",
+      serializer: {} as ObservationLexicon["serializer"],
+      describeResources: async () =>
+        observation({}, { "web-vpc": { type: "AWS::EC2::VPC", reason: "unsupported-kind" } }),
+    } as unknown as ObservationLexicon;
+    const { observations, warnings, errors } = await observeResources("prod", [plugin], mockBuild());
+    expect(errors).toEqual([]);
+    expect(observations[0].unobserved).toEqual({
+      "web-vpc": { type: "AWS::EC2::VPC", reason: "unsupported-kind" },
+    });
+    expect(warnings[0]).toContain("no reader for this resource kind");
+  });
+
+  it("merges multi-stack reads with present > not-observed > absent (#1089)", async () => {
+    const stacks = ["a", "b"];
+    const plugin = {
+      name: "aws",
+      serializer: {} as ObservationLexicon["serializer"],
+      describeResources: async (opts: { stack?: string }) =>
+        opts.stack === "a"
+          ? observation({}, { "web-vpc": { reason: "read-failed", detail: "stack a unreadable" } })
+          : observation({ "web-vpc": { type: "AWS::EC2::VPC", status: "CREATE_COMPLETE" } }),
+    } as unknown as ObservationLexicon;
+    const { observations } = await observeResources("prod", [plugin], mockBuild(), { stacks });
+    expect(Object.keys(observations[0].resources)).toEqual(["web-vpc"]);
+    expect(observations[0].unobserved).toBeUndefined();
+  });
+
   it("with no stacks: calls describeResources exactly once with no `stack` key (unchanged single-stack path)", async () => {
     const calls: Array<{ stack?: string }> = [];
     const plugins = [

package/src/lifecycle/observe.ts

@@ -9,10 +9,18 @@
  * side effects. Snapshotting keeps its own copy for now; a future refactor can
  * fold both onto this primitive.
  */
-import type { ObservationLexicon, ResourceMetadata } from "../lexicon";
+import type { ObservationLexicon } from "../lexicon";
 import type { BuildResult } from "../build";
 import type { SerializerResult } from "../serializer";
 import type { LiveObservation } from "../graph-ir";
+import {
+  mergeObservations,
+  normalizeObservation,
+  unobservedAll,
+  formatUnobserved,
+  type NormalizedObservation,
+} from "../observation";
+import { zeroResourcesWarning } from "../live-endpoint";
 
 export interface ObserveResult {
   observations: LiveObservation[];
@@ -25,8 +33,10 @@ export interface ObserveResult {
  * `environment`. `owned` (default true for the managed-only diagram, epic #776)
  * restricts to resources carrying chant's ownership marker; a lexicon with no
  * marker channel logs and returns everything (its own contract). Plugins that
- * throw are collected into `errors` and skipped — one failing lexicon never
- * sinks the whole graph.
+ * throw are collected into `errors` — one failing lexicon never sinks the whole
+ * graph — and every entity they were asked about is recorded as NOT-OBSERVED
+ * (`read-failed`, #1089) rather than dropped, so a failed read is visibly a
+ * hole instead of a silent absence.
  *
  * `stacks` (#57) is for a multi-stack, per-component project (e.g. loomster)
  * where there is no single stack named after the environment — AWS's
@@ -77,36 +87,86 @@ export async function observeResources(
     }
 
     try {
-      let resources: Record<string, ResourceMetadata>;
+      let observed: NormalizedObservation;
       if (stacks.length > 0) {
-        resources = {};
+        const parts: NormalizedObservation[] = [];
         for (const stack of stacks) {
-          const perStack = await plugin.describeResources({
+          parts.push(
+            normalizeObservation(
+              await plugin.describeResources({
+                environment,
+                buildOutput,
+                entityNames,
+                entities,
+                owned,
+                stack,
+              }),
+            ),
+          );
+        }
+        observed = mergeObservations(parts);
+      } else {
+        observed = normalizeObservation(
+          await plugin.describeResources({
             environment,
             buildOutput,
             entityNames,
             entities,
             owned,
-            stack,
-          });
-          Object.assign(resources, perStack);
-        }
-      } else {
-        resources = await plugin.describeResources({
-          environment,
-          buildOutput,
-          entityNames,
-          entities,
-          owned,
-        });
-      }
-      if (Object.keys(resources).length > 0) {
-        observations.push({ lexicon: plugin.name, resources });
+          }),
+        );
       }
+      pushObservation(observations, warnings, plugin.name, observed, environment, entityNames.length);
     } catch (err) {
-      errors.push(`${plugin.name}: ${err instanceof Error ? err.message : String(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
+      // failed read look like "none of these exist" to every consumer.
+      const message = err instanceof Error ? err.message : String(err);
+      errors.push(`${plugin.name}: ${message}`);
+      pushObservation(
+        observations,
+        warnings,
+        plugin.name,
+        {
+          resources: {},
+          unobserved: unobservedAll(entityNames, "read-failed", message, entities),
+        },
+        environment,
+        entityNames.length,
+      );
     }
   }
 
   return { observations, warnings, errors };
 }
+
+/** Record one lexicon's observation, warning once per unobserved entity. */
+function pushObservation(
+  observations: LiveObservation[],
+  warnings: string[],
+  lexicon: string,
+  observed: NormalizedObservation,
+  environment: string,
+  declaredCount: number,
+): void {
+  const hasResources = Object.keys(observed.resources).length > 0;
+  const unobservedNames = Object.keys(observed.unobserved);
+  for (const name of unobservedNames) {
+    warnings.push(`${lexicon}: not observed — ${formatUnobserved(name, observed.unobserved[name])}`);
+  }
+  if (!hasResources && unobservedNames.length === 0) {
+    // #1166 — this is exactly the "wrong endpoint" shape (AWS's
+    // stackDoesNotExist branch returns an empty map with no #1089 hole): a
+    // declared entity list with nothing observed and nothing explained.
+    // Previously this fell straight through with neither an observation nor a
+    // warning — silently indistinguishable from "nothing is deployed yet".
+    const notice = zeroResourcesWarning(lexicon, environment, declaredCount, observed);
+    if (notice) warnings.push(notice);
+    return;
+  }
+  observations.push({
+    lexicon,
+    resources: observed.resources,
+    ...(unobservedNames.length > 0 ? { unobserved: observed.unobserved } : {}),
+  });
+}

package/src/lifecycle/snapshot.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect, vi, beforeEach } from "vitest";
-import { createMockPlugin, staticDescribeResources, staticListArtifacts } from "@intentius/chant-test-utils";
+import { createMockPlugin, staticDescribeResources, staticObservation, staticListArtifacts } from "@intentius/chant-test-utils";
 import type { BuildResult } from "../build";
 
 const writeSnapshotMock = vi.fn();
@@ -114,6 +114,44 @@ describe("takeSnapshot", () => {
     expect(result.errors.some((e) => e.includes("aws") && e.includes("no valid"))).toBe(true);
   });
 
+  // #1089 — a snapshot is evidence of what was seen. An entity nobody could
+  // read must be recorded as a hole, not omitted (which the next diff would
+  // read back as "was not there").
+  test("records unobserved entities alongside the resources", async () => {
+    const plugin = createMockPlugin({
+      name: "k8s",
+      describeResources: staticObservation(
+        { web: { type: "K8s::Apps::Deployment", status: "READY" } },
+        { widget: { type: "K8s::X::Widget", reason: "unsupported-kind", detail: "no reader" } },
+      ),
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ k8s: ["web", "widget"] }));
+    expect(result.snapshots[0].unobserved).toEqual({
+      widget: { type: "K8s::X::Widget", reason: "unsupported-kind", detail: "no reader" },
+    });
+    expect(result.warnings.some((w) => w.includes("widget") && w.includes("not observed"))).toBe(true);
+  });
+
+  test("an entirely unreadable environment is not snapshotted as empty", async () => {
+    const plugin = createMockPlugin({
+      name: "k8s",
+      describeResources: staticObservation({}, { web: { reason: "no-credentials" } }),
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ k8s: ["web"] }));
+    expect(result.snapshots).toEqual([]);
+    expect(result.errors.some((e) => e.includes("could not be read"))).toBe(true);
+  });
+
+  test("a throwing plugin reports each declared entity as unobserved in the warnings", async () => {
+    const plugin = createMockPlugin({
+      name: "k8s",
+      describeResources: async () => { throw new Error("kubeconfig missing"); },
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ k8s: ["web"] }));
+    expect(result.snapshots).toEqual([]);
+    expect(result.warnings.some((w) => w.includes("web") && w.includes("kubeconfig missing"))).toBe(true);
+  });
+
   test("resources missing required type/status are dropped with warning", async () => {
     const plugin = createMockPlugin({
       name: "aws",