@intentius/chant 0.28.0 → 0.30.0

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/observation-baseline.test.ts

@@ -0,0 +1,99 @@
+import { describe, test, expect } from "vitest";
+import {
+  acceptDeviations,
+  acceptedDeviation,
+  baselineForLexicon,
+  countAccepted,
+  emptyBaseline,
+  isObservationBaseline,
+  parseBaseline,
+  serializeBaseline,
+} from "./observation-baseline";
+
+describe("the baseline document", () => {
+  test("round-trips through serialize/parse", () => {
+    const b = acceptDeviations(emptyBaseline("prod"), "aws", [
+      { entity: "Assets", type: "AWS::S3::Bucket", path: "Tags[0].Value", value: "platform", note: "org policy" },
+    ], { now: "2026-07-27T00:00:00.000Z" });
+    const parsed = parseBaseline(serializeBaseline(b));
+    expect(parsed).toEqual(b);
+  });
+
+  test("serializes with sorted keys and a trailing newline, so the commit diff reads cleanly", () => {
+    const json = serializeBaseline(emptyBaseline("prod"));
+    expect(json.endsWith("\n")).toBe(true);
+    expect(JSON.parse(json)).toEqual({ baseline: "v1", environment: "prod", lexicons: {} });
+  });
+
+  test("refuses to read anything that is not a versioned baseline", () => {
+    expect(parseBaseline(null)).toBeNull();
+    expect(parseBaseline("")).toBeNull();
+    expect(parseBaseline("{ not json")).toBeNull();
+    expect(parseBaseline('{"baseline":"v2","lexicons":{}}')).toBeNull();
+    expect(parseBaseline('{"lexicons":{}}')).toBeNull();
+    expect(isObservationBaseline({ baseline: "v1", lexicons: {} })).toBe(true);
+  });
+});
+
+describe("acceptDeviations", () => {
+  const now = "2026-07-27T00:00:00.000Z";
+
+  test("records a deviation bound to the value that was accepted", () => {
+    const b = acceptDeviations(emptyBaseline("prod"), "aws", [
+      { entity: "Role", type: "AWS::IAM::Role", path: "MaxSessionDuration", value: 7200 },
+    ], { now });
+    expect(baselineForLexicon(b, "aws")).toEqual({
+      Role: {
+        type: "AWS::IAM::Role",
+        accepted: [{ path: "MaxSessionDuration", value: 7200, recordedAt: now }],
+      },
+    });
+    expect(b.updated).toBe(now);
+  });
+
+  test("does not mutate the input", () => {
+    const before = emptyBaseline("prod");
+    acceptDeviations(before, "aws", [{ entity: "R", path: "A", value: 1 }], { now });
+    expect(before.lexicons).toEqual({});
+  });
+
+  test("re-accepting the same path replaces the entry rather than appending a second", () => {
+    let b = acceptDeviations(emptyBaseline("prod"), "aws", [{ entity: "R", path: "A", value: 1 }], { now });
+    b = acceptDeviations(b, "aws", [{ entity: "R", path: "A", value: 2 }], { now });
+    expect(baselineForLexicon(b, "aws").R.accepted).toEqual([{ path: "A", value: 2, recordedAt: now }]);
+  });
+
+  test("keeps deviations from other entities and other lexicons", () => {
+    let b = acceptDeviations(emptyBaseline("prod"), "aws", [{ entity: "R1", path: "A", value: 1 }], { now });
+    b = acceptDeviations(b, "aws", [{ entity: "R2", path: "B", value: 2 }], { now });
+    b = acceptDeviations(b, "k8s", [{ entity: "D", path: "spec.replicas", value: 3 }], { now });
+    expect(Object.keys(baselineForLexicon(b, "aws")).sort()).toEqual(["R1", "R2"]);
+    expect(countAccepted(b)).toBe(3);
+  });
+
+  test("accepted paths sort, so the committed file is stable across runs", () => {
+    const b = acceptDeviations(emptyBaseline("prod"), "aws", [
+      { entity: "R", path: "Z", value: 1 },
+      { entity: "R", path: "A", value: 2 },
+    ], { now });
+    expect(baselineForLexicon(b, "aws").R.accepted.map((a) => a.path)).toEqual(["A", "Z"]);
+  });
+
+  test("an empty accept list is a no-op", () => {
+    const b = emptyBaseline("prod");
+    expect(acceptDeviations(b, "aws", [])).toBe(b);
+  });
+
+  test("lookup is by entity and path", () => {
+    const b = acceptDeviations(emptyBaseline("prod"), "aws", [{ entity: "R", path: "A", value: 1 }], { now });
+    const lex = baselineForLexicon(b, "aws");
+    expect(acceptedDeviation(lex, "R", "A")?.value).toBe(1);
+    expect(acceptedDeviation(lex, "R", "B")).toBeUndefined();
+    expect(acceptedDeviation(lex, "Other", "A")).toBeUndefined();
+  });
+
+  test("a missing baseline reads as nothing accepted", () => {
+    expect(baselineForLexicon(null, "aws")).toEqual({});
+    expect(countAccepted(null)).toBe(0);
+  });
+});

package/src/lifecycle/observation-baseline.ts

@@ -0,0 +1,217 @@
+/**
+ * The accepted-observation baseline (#1014) — a committed record of deviations
+ * somebody looked at and accepted, so they stop re-alerting.
+ *
+ * Deep observation reports every property that differs between source and
+ * cloud, including properties nobody ever declared. Some of those are real
+ * findings. Many are permanent facts of the account — a platform team's
+ * mandatory tag, a bucket setting an org policy flips on, a role an operator
+ * attached by hand and everyone agreed to keep. Without somewhere to record
+ * "yes, we know, leave it", a deep diff is a report nobody reads twice.
+ *
+ * The model is cdk-real-drift's `.cdkrd`: a snapshot of accepted *undeclared*
+ * values that the diff subtracts. Accepting is an explicit act with a git
+ * commit behind it, and the acceptance is value-bound — accept
+ * `VersioningConfiguration.Status = Enabled` and a later change to `Suspended`
+ * is drift again, because what was accepted was that value, not that path.
+ *
+ * ## What this is not
+ *
+ * Not state. The baseline never tells a deploy what to do and is never read on
+ * the write path; deleting it costs you noise suppression and nothing else.
+ * Which is also why it is safe for it to be incomplete or stale.
+ *
+ * ## Where it lives
+ *
+ * `<environment>/observation-baseline.json` on the `chant/lifecycle` orphan
+ * branch — the epic's named candidate home, and the same storage the snapshots
+ * (`<env>/<lexicon>.json`), the release ledger (`<env>/releases.jsonl`) and the
+ * build archive (`_builds/<digest>.json`) already use, through the same
+ * `writeBlobToPath`/`readBlobFromPath` plumbing. One env-keyed namespace for
+ * everything chant records *about* an environment rather than *for* it.
+ *
+ * The parse/serialize/update half below is pure and storage-free, so the
+ * decision is one function call deep if a repo-committed file (`.chant/`) turns
+ * out to be the better review surface.
+ */
+
+import { readBlobFromPath, writeBlobToPath } from "./git";
+import { sortedJsonReplacer } from "../utils";
+
+/** The file name under `<environment>/` on the orphan branch. */
+export const OBSERVATION_BASELINE_FILE = "observation-baseline.json";
+
+/** One deviation somebody accepted, bound to the value they accepted. */
+export interface AcceptedDeviation {
+  /** Property path within the entity's normalized tree (`Tags[0].Value`, `Policy.Statement[1].Effect`). */
+  path: string;
+  /** The live value at the moment of acceptance. A different live value later is drift again. */
+  value: unknown;
+  /** Free-text justification, written by whoever accepted it. */
+  note?: string;
+  /** ISO timestamp of acceptance. */
+  recordedAt?: string;
+}
+
+/** Every accepted deviation for one declared entity. */
+export interface BaselineEntity {
+  /** Entity type at acceptance time, for readability in the committed file. */
+  type?: string;
+  accepted: AcceptedDeviation[];
+}
+
+/** Accepted deviations for one lexicon, keyed by chant entity name. */
+export type BaselineLexicon = Record<string, BaselineEntity>;
+
+/** The committed baseline document for one environment. */
+export interface ObservationBaseline {
+  /** Discriminant + wire version. */
+  readonly baseline: "v1";
+  environment: string;
+  /** ISO timestamp of the last `--update-baseline`. */
+  updated?: string;
+  /** lexicon → entity → accepted deviations. */
+  lexicons: Record<string, BaselineLexicon>;
+}
+
+/** An environment with nothing accepted yet. */
+export function emptyBaseline(environment: string): ObservationBaseline {
+  return { baseline: "v1", environment, lexicons: {} };
+}
+
+/** True when `value` is a well-formed {@link ObservationBaseline}. */
+export function isObservationBaseline(value: unknown): value is ObservationBaseline {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { baseline?: unknown }).baseline === "v1" &&
+    typeof (value as { lexicons?: unknown }).lexicons === "object" &&
+    (value as { lexicons?: unknown }).lexicons !== null
+  );
+}
+
+/**
+ * Parse a baseline document. Returns `null` for unparseable or unrecognized
+ * content — a corrupt baseline degrades to "nothing is accepted", which is
+ * noisy but never wrong. Silently treating garbage as a baseline would
+ * suppress real drift.
+ */
+export function parseBaseline(content: string | null | undefined): ObservationBaseline | null {
+  if (!content) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return null;
+  }
+  if (!isObservationBaseline(parsed)) return null;
+  return parsed;
+}
+
+/** Deterministic on-disk form: sorted keys, trailing newline, reviewable diff. */
+export function serializeBaseline(baseline: ObservationBaseline): string {
+  return `${JSON.stringify(baseline, sortedJsonReplacer, 2)}\n`;
+}
+
+/** The accepted deviations for one lexicon, or an empty map. */
+export function baselineForLexicon(
+  baseline: ObservationBaseline | null | undefined,
+  lexicon: string,
+): BaselineLexicon {
+  return baseline?.lexicons?.[lexicon] ?? {};
+}
+
+/** Look up one accepted deviation by entity + path. */
+export function acceptedDeviation(
+  lexiconBaseline: BaselineLexicon,
+  entity: string,
+  path: string,
+): AcceptedDeviation | undefined {
+  return lexiconBaseline[entity]?.accepted.find((a) => a.path === path);
+}
+
+/** One deviation to record as accepted. */
+export interface DeviationToAccept {
+  entity: string;
+  type?: string;
+  path: string;
+  /** The live value being accepted. */
+  value: unknown;
+  note?: string;
+}
+
+/**
+ * Record deviations as accepted, returning a new baseline (the input is not
+ * mutated). An existing acceptance for the same entity+path is replaced — that
+ * is how re-accepting after a deliberate change works, and it keeps the file
+ * from growing a second entry for every value a path has ever held.
+ */
+export function acceptDeviations(
+  baseline: ObservationBaseline,
+  lexicon: string,
+  deviations: readonly DeviationToAccept[],
+  opts?: { now?: string },
+): ObservationBaseline {
+  if (deviations.length === 0) return baseline;
+  const now = opts?.now ?? new Date().toISOString();
+  const lexicons: Record<string, BaselineLexicon> = { ...baseline.lexicons };
+  const entities: BaselineLexicon = { ...(lexicons[lexicon] ?? {}) };
+
+  for (const dev of deviations) {
+    const existing = entities[dev.entity];
+    const accepted = (existing?.accepted ?? []).filter((a) => a.path !== dev.path);
+    accepted.push({
+      path: dev.path,
+      value: dev.value,
+      ...(dev.note ? { note: dev.note } : {}),
+      recordedAt: now,
+    });
+    accepted.sort((a, b) => a.path.localeCompare(b.path));
+    entities[dev.entity] = {
+      ...(dev.type ?? existing?.type ? { type: dev.type ?? existing?.type } : {}),
+      accepted,
+    };
+  }
+
+  lexicons[lexicon] = entities;
+  return { baseline: "v1", environment: baseline.environment, updated: now, lexicons };
+}
+
+/** Total accepted deviations across every lexicon — for the "N accepted" line. */
+export function countAccepted(baseline: ObservationBaseline | null | undefined): number {
+  if (!baseline) return 0;
+  let n = 0;
+  for (const entities of Object.values(baseline.lexicons)) {
+    for (const entity of Object.values(entities)) n += entity.accepted.length;
+  }
+  return n;
+}
+
+// ── Storage (chant/lifecycle orphan branch) ─────────────────────────────────
+
+/**
+ * Read the accepted baseline for an environment. Returns `null` when the branch,
+ * the environment, or the file does not exist — every one of which means
+ * "nothing accepted yet", the normal state before anyone runs
+ * `--update-baseline`.
+ */
+export async function readObservationBaseline(
+  environment: string,
+  opts?: { cwd?: string },
+): Promise<ObservationBaseline | null> {
+  return parseBaseline(await readBlobFromPath(environment, OBSERVATION_BASELINE_FILE, opts));
+}
+
+/** Write the accepted baseline to the orphan branch. Returns the new commit SHA. */
+export async function writeObservationBaseline(
+  baseline: ObservationBaseline,
+  opts?: { cwd?: string },
+): Promise<string> {
+  return writeBlobToPath(
+    baseline.environment,
+    OBSERVATION_BASELINE_FILE,
+    serializeBaseline(baseline),
+    "Accepted observation baseline",
+    opts,
+  );
+}

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 } : {}),
+  });
+}