@intentius/chant 0.28.0 → 0.30.0

package/src/index.ts

@@ -48,6 +48,8 @@ export * from "./lint/discover";
 export * from "./import/parser";
 export * from "./import/generator";
 export * from "./lexicon";
+export * from "./observation";
+export * from "./deep-observation";
 export * from "./lexicon-integrity";
 export * from "./lexicon-manifest";
 export * from "./lexicon-schema";

package/src/kubectl-context.ts

@@ -22,6 +22,7 @@
 
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
+import type { UnobservedReason } from "./observation";
 
 const execAsync = promisify(exec);
 
@@ -124,3 +125,83 @@ export async function resolveClusterTarget(
 
   return { context: bound, source: "bound" };
 }
+
+// ── kubectl read outcomes (#1089) ───────────────────────────────────────────
+
+/**
+ * What a failed `kubectl get` actually proved. Shared by the k8s and gcp
+ * lexicons, which read through the same kubectl path and used to collapse every
+ * non-zero exit into "not there" — so an expired token, a downed API server, or
+ * an uninstalled CRD all classified as `create`.
+ */
+export type KubectlReadOutcome =
+  /** The API server answered and the object is not there. Safe to plan a create. */
+  | { kind: "absent" }
+  /** The read proved nothing about the object's existence. */
+  | { kind: "unobserved"; reason: UnobservedReason; detail: string };
+
+/** Pull whatever the child process actually said out of an exec rejection. */
+function execErrorText(err: unknown): string {
+  if (typeof err === "object" && err !== null) {
+    const e = err as { stderr?: unknown; message?: unknown };
+    const stderr = typeof e.stderr === "string" ? e.stderr.trim() : "";
+    if (stderr) return stderr;
+    if (typeof e.message === "string") return e.message.trim();
+  }
+  return String(err);
+}
+
+/** Collapse kubectl's noise to one line for a plan/diff entry. */
+function firstLine(text: string, max = 200): string {
+  const line = text.split("\n").find((l) => l.trim().length > 0)?.trim() ?? text.trim();
+  return line.length > max ? `${line.slice(0, max - 3)}...` : line;
+}
+
+/**
+ * Classify a `kubectl get` failure into the observation tri-state (#1089).
+ *
+ * Only a genuine `NotFound` from the API server — or a kind the server does not
+ * serve at all, where no instance can exist — establishes absence. Auth,
+ * connectivity, and unresolvable contexts establish nothing, and must reach the
+ * change set as NOT-OBSERVED rather than as an empty result.
+ */
+export function classifyKubectlFailure(err: unknown): KubectlReadOutcome {
+  const text = execErrorText(err);
+  const lower = text.toLowerCase();
+
+  // The object was looked for and is not there.
+  if (lower.includes("notfound") || /error from server \(notfound\)/.test(lower) || lower.includes("not found")) {
+    return { kind: "absent" };
+  }
+  // The cluster serves no such kind, so no instance of it can exist there. The
+  // usual cause is a CRD this same plan has not applied yet — a real absence,
+  // and the case a create is for.
+  if (
+    lower.includes("the server doesn't have a resource type") ||
+    lower.includes("the server could not find the requested resource")
+  ) {
+    return { kind: "absent" };
+  }
+  if (
+    lower.includes("unauthorized") ||
+    lower.includes("forbidden") ||
+    lower.includes("you must be logged in") ||
+    lower.includes("invalid bearer token") ||
+    lower.includes("credentials")
+  ) {
+    return { kind: "unobserved", reason: "no-credentials", detail: firstLine(text) };
+  }
+  if (
+    lower.includes("unable to connect to the server") ||
+    lower.includes("connection refused") ||
+    lower.includes("no configuration has been provided") ||
+    lower.includes("did you specify the right host or port") ||
+    lower.includes("context was not found") ||
+    /context ".*" does not exist/.test(lower) ||
+    lower.includes("no such host") ||
+    lower.includes("i/o timeout")
+  ) {
+    return { kind: "unobserved", reason: "no-binding", detail: firstLine(text) };
+  }
+  return { kind: "unobserved", reason: "read-failed", detail: firstLine(text) };
+}

package/src/lexicon.ts

@@ -11,11 +11,38 @@ import type { DriverComponent } from "./components/driver";
 import type { EmulatorCapability } from "./op/emulator-lifecycle";
 import type { RuleMeta } from "./audit/catalog";
 import type { ReferenceCatalog } from "./graph-refs";
+import type { DescribeResourcesResult } from "./observation";
+import type { DeepNormalizationHooks, DeepObservationResult } from "./deep-observation";
 
 // Re-exported so lexicons can author a reference catalog (#778) from the same
 // `@intentius/chant/lexicon` entry they import the plugin contract from.
 export type { ReferenceCatalog, IdentityRule, RefRule } from "./graph-refs";
 
+// The observation contract (#1089), re-exported from the same entry so a
+// lexicon's `describeResources` can report NOT-OBSERVED without a second
+// import path. Runtime helpers live in `@intentius/chant/observation`.
+export type {
+  DescribeResourcesResult,
+  ObservationResult,
+  NormalizedObservation,
+  UnobservedEntity,
+  UnobservedReason,
+} from "./observation";
+
+// The deep observation contract (#1014), re-exported for the same reason: a
+// lexicon authoring `observeResourcesDeep` + its pruning/ordering hooks types
+// them from the same entry. Runtime helpers live in
+// `@intentius/chant/deep-observation`.
+export type {
+  DeepObservationResult,
+  DeepResourceObservation,
+  NormalizedDeepObservation,
+  DeepNormalizationHooks,
+  DeepNode,
+  DeepArrayElement,
+  DeepSide,
+} from "./deep-observation";
+
 /**
  * Manifest for a packaged lexicon — metadata embedded in the tarball.
  *
@@ -507,6 +534,27 @@ export interface LexiconPlugin {
    * Use this when each chant entity has a 1:1 cloud equivalent — e.g. an
    * AWS CFN resource, a K8s object, an ARM resource, a Temporal namespace.
    *
+   * **The observation contract (#1089).** Returning nothing for a declared
+   * entity is a claim, and there are two different claims to make. Either the
+   * provider was asked and reported the resource absent — which is what lets
+   * the change set propose `create` — or the lexicon never looked, which must
+   * not. An implementation that has a "did not look" case (no reader for the
+   * kind, the read errored, no credentials, no cluster binding) must return the
+   * {@link ObservationResult} envelope and name those entities in `unobserved`
+   * with a total {@link UnobservedReason}. Warning on stderr is not enough: a
+   * warning is invisible to `lifecycle plan`, which is where the wrong `create`
+   * gets proposed. Returning the bare `name → ResourceMetadata` map is still
+   * valid and means "everything I was asked about, I looked at".
+   *
+   * Throwing is the whole-lexicon failure (see the k8s cluster-binding refusal,
+   * #1100): core catches it and marks every declared entity NOT-OBSERVED with
+   * `read-failed`, so a failed read is never a list of creates.
+   *
+   * Ownership verdicts are total (#1089). When `owned` is requested and the
+   * lexicon has no marker channel on this path, it must stamp
+   * `ownership: "unknown"` on what it returns rather than degrading silently —
+   * the change set never escalates `unknown` to a `delete`.
+   *
    * `entities` carries the chant-side entity declarations for this lexicon,
    * keyed by chant entity name (e.g. the export name from a `*.ts` file).
    * Implementations that need to map cloud-side names back to chant entity
@@ -536,7 +584,51 @@ export interface LexiconPlugin {
      * everything.
      */
     owned?: boolean;
-  }): Promise<Record<string, ResourceMetadata>>;
+  }): Promise<DescribeResourcesResult>;
+
+  /**
+   * Read the full live *property tree* for each declared entity (#1014). Opt-in,
+   * and strictly deeper than {@link describeResources}, which reports existence
+   * plus a handful of scrubbed outputs. A lexicon that implements neither, or
+   * only the thin one, is unaffected — `lifecycle diff --live` gains
+   * property-level entries only where this exists.
+   *
+   * The result is keyed by chant entity name, exactly like the thin read, and
+   * carries the same NOT-OBSERVED map. That is the composition rule with #1089:
+   * a deep read that fails for one entity says so with a total
+   * {@link UnobservedReason}. It never returns a thin-but-clean tree, because a
+   * clean tree is a claim that nothing drifted.
+   *
+   * Properties must be normalized before they are returned — run
+   * `normalizeDeepProperties` (../deep-observation.ts) with this lexicon's own
+   * {@link deepNormalizationHooks}, so the trees a consumer sees are already
+   * free of arns, timestamps, status subtrees and unstable orderings.
+   *
+   * Throwing is the whole-lexicon failure, same as the thin read: core turns it
+   * into `read-failed` for every declared entity.
+   */
+  observeResourcesDeep?(options: {
+    environment: string;
+    buildOutput: string;
+    entityNames: string[];
+    entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+    /** Deployed stack to observe, for a multi-stack project (see `stacks` in {@link ChantConfig}). */
+    stack?: string;
+    /** Restrict to chant-owned resources (#119). A lexicon with no marker channel on this path says so. */
+    owned?: boolean;
+  }): Promise<DeepObservationResult>;
+
+  /**
+   * This lexicon's noise rules for deep observation (#1014): which fields are
+   * read-only / server-populated / controller-managed / provider-defaulted, and
+   * which arrays are sets. Data, not a method — core applies the same rules to
+   * the *declared* tree, which no reader ever touches, and the two sides have
+   * to be normalized identically to be comparable.
+   *
+   * Ships alongside {@link observeResourcesDeep}; a reader without hooks
+   * produces a diff made almost entirely of noise.
+   */
+  deepNormalizationHooks?: DeepNormalizationHooks;
 
   /**
    * Report the live status of one deploy unit by its deployed name. Opt-in.
@@ -683,12 +775,14 @@ export interface ResourceMetadata {
   /** Cloud-assigned output properties */
   attributes?: Record<string, unknown>;
   /**
-   * Live ownership verdict from the resource's marker (#119/#120), when the
-   * lexicon could determine it. `owned` = carries chant's marker; `foreign` =
-   * no marker. Absent = the lexicon has no marker channel here. The change set
-   * reads this — never the snapshot — to decide whether an orphan is a delete.
+   * Live ownership verdict from the resource's marker (#119/#120). `owned` =
+   * carries chant's marker; `foreign` = no marker; `unknown` = the lexicon has
+   * no marker channel on this read path and says so rather than degrading
+   * silently (#1089 — verdicts are total). Absent is read as `unknown`. The
+   * change set reads this — never the snapshot — to decide whether an orphan is
+   * a delete, and never escalates `unknown` to one.
    */
-  ownership?: "owned" | "foreign";
+  ownership?: "owned" | "foreign" | "unknown";
 }
 
 /**

package/src/lifecycle/change-set.test.ts

@@ -17,7 +17,7 @@ describe("buildChangeSet (#118)", () => {
     });
     const e = cs.entries.find((x) => x.name === "bucket")!;
     expect(e.action).toBe("create");
-    expect(e.evidence).toEqual({ declared: true, inSnapshot: false, live: false });
+    expect(e.evidence).toEqual({ declared: true, inSnapshot: false, live: false, observed: true });
     expect(e.ownership).toBe("unknown");
   });
 
@@ -187,3 +187,95 @@ describe("gitlabMrReport (#329)", () => {
     expect(gitlabMrReport(cs)).toEqual({ create: 0, update: 0, delete: 0 });
   });
 });
+
+// ── The observation tri-state (#1089) ───────────────────────────────────────
+
+describe("buildChangeSet: not-observed is not absent (#1089)", () => {
+  test("declared and not observed → unobserved, never create", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["crd-widget"]),
+      observedNow: {},
+      observedThen: undefined,
+      unobserved: {
+        "crd-widget": {
+          type: "K8s::Example::Widget",
+          reason: "unsupported-kind",
+          detail: "no kubectl mapping",
+        },
+      },
+    });
+    const e = cs.entries.find((x) => x.name === "crd-widget")!;
+    expect(e.action).toBe("unobserved");
+    expect(e.evidence).toEqual({ declared: true, inSnapshot: false, live: false, observed: false });
+    expect(e.unobservedReason).toBe("unsupported-kind");
+    expect(e.type).toBe("K8s::Example::Widget");
+  });
+
+  test("the same entity, confirmed absent, still classifies as create", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["crd-widget"]),
+      observedNow: {},
+      observedThen: undefined,
+    });
+    expect(cs.entries.find((x) => x.name === "crd-widget")!.action).toBe("create");
+  });
+
+  test("a returned resource wins over an unobserved claim for the same name", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["queue"]),
+      observedNow: { queue: meta() },
+      observedThen: undefined,
+      unobserved: { queue: { reason: "read-failed" } },
+    });
+    const e = cs.entries.find((x) => x.name === "queue")!;
+    expect(e.action).toBe("noop");
+    expect(e.evidence.observed).toBe(true);
+  });
+
+  test("an unobserved entity that is in the snapshot is not read as gone", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["queue"]),
+      observedNow: {},
+      observedThen: { queue: meta() },
+      unobserved: { queue: { reason: "no-credentials" } },
+    });
+    const e = cs.entries.find((x) => x.name === "queue")!;
+    expect(e.action).toBe("unobserved");
+    expect(e.evidence.inSnapshot).toBe(true);
+  });
+
+  test("an unobserved entity is never a delete, even with an owned marker in the snapshot", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(),
+      observedNow: {},
+      observedThen: { legacy: meta({ ownership: "owned" }) },
+      unobserved: { legacy: { reason: "read-failed" } },
+    });
+    expect(cs.entries.find((x) => x.name === "legacy")!.action).toBe("unobserved");
+  });
+
+  test("summarize and render surface the hole", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["a"]),
+      observedNow: {},
+      observedThen: undefined,
+      unobserved: { a: { reason: "no-binding", detail: "no kubectl context for prod" } },
+    });
+    expect(summarize(cs).unobserved).toBe(1);
+    expect(summarize(cs).create).toBe(0);
+    const out = renderChangeSet(cs);
+    expect(out).toContain("UNOBSERVED");
+    expect(out).toContain("no binding for this environment");
+    expect(out).toContain("no kubectl context for prod");
+  });
+
+  test("the GitLab widget excludes unobserved — its three columns cannot express a hole", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["a"]),
+      observedNow: {},
+      observedThen: undefined,
+      unobserved: { a: { reason: "read-failed" } },
+    });
+    expect(gitlabMrReport(cs)).toEqual({ create: 0, update: 0, delete: 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/deep-diff.test.ts

@@ -0,0 +1,157 @@
+import { describe, test, expect } from "vitest";
+import { countPropertyDrift, diffDeep } from "./deep-diff";
+import { UNRESOLVED, type NormalizedDeepObservation } from "../deep-observation";
+import type { BaselineLexicon } from "./observation-baseline";
+
+const live = (
+  resources: Record<string, { type: string; properties: Record<string, unknown> }>,
+  unobserved: NormalizedDeepObservation["unobserved"] = {},
+): NormalizedDeepObservation => ({ resources, unobserved });
+
+describe("diffDeep", () => {
+  test("identical trees are unchanged", () => {
+    const result = diffDeep({
+      declared: { b: { type: "AWS::S3::Bucket", properties: { BucketName: "x" } } },
+      live: live({ b: { type: "AWS::S3::Bucket", properties: { BucketName: "x" } } }),
+    });
+    expect(result.unchanged).toEqual(["b"]);
+    expect(result.drifted).toEqual([]);
+  });
+
+  test("a changed property reports declared and live", () => {
+    const result = diffDeep({
+      declared: { b: { type: "AWS::S3::Bucket", properties: { Versioning: { Status: "Enabled" } } } },
+      live: live({ b: { type: "AWS::S3::Bucket", properties: { Versioning: { Status: "Suspended" } } } }),
+    });
+    expect(result.drifted).toEqual([
+      {
+        name: "b",
+        type: "AWS::S3::Bucket",
+        changes: [{ path: "Versioning.Status", kind: "changed", declared: "Enabled", live: "Suspended" }],
+      },
+    ]);
+    expect(countPropertyDrift(result)).toBe(1);
+  });
+
+  test("a property only the cloud has is undeclared drift", () => {
+    const result = diffDeep({
+      declared: { b: { type: "T", properties: {} } },
+      live: live({ b: { type: "T", properties: { LoggingConfiguration: { TargetBucket: "logs" } } } }),
+    });
+    expect(result.drifted[0].changes).toEqual([
+      { path: "LoggingConfiguration.TargetBucket", kind: "undeclared", live: "logs" },
+    ]);
+  });
+
+  test("a declared property the cloud does not carry is absent", () => {
+    const result = diffDeep({
+      declared: { b: { type: "T", properties: { A: 1 } } },
+      live: live({ b: { type: "T", properties: {} } }),
+    });
+    expect(result.drifted[0].changes).toEqual([{ path: "A", kind: "absent", declared: 1 }]);
+  });
+
+  test("an unevaluated intrinsic on the declared side is never drift", () => {
+    const result = diffDeep({
+      declared: { b: { type: "T", properties: { BucketName: UNRESOLVED, Other: "x" } } },
+      live: live({ b: { type: "T", properties: { BucketName: "prod-data", Other: "x" } } }),
+    });
+    expect(result.drifted).toEqual([]);
+    expect(result.unchanged).toEqual(["b"]);
+  });
+
+  test("an entity the deep read could not look at is a hole, not drift", () => {
+    const result = diffDeep({
+      declared: { b: { type: "T", properties: { A: 1 } } },
+      live: live({}, { b: { type: "T", reason: "unsupported-kind", detail: "no reader" } }),
+    });
+    expect(result.drifted).toEqual([]);
+    expect(result.unobserved).toEqual([
+      { name: "b", type: "T", reason: "unsupported-kind", detail: "no reader" },
+    ]);
+  });
+
+  test("present beats not-observed", () => {
+    const result = diffDeep({
+      declared: { b: { type: "T", properties: { A: 1 } } },
+      live: live({ b: { type: "T", properties: { A: 1 } } }, { b: { reason: "read-failed" } }),
+    });
+    expect(result.unobserved).toEqual([]);
+  });
+
+  test("an entity absent from the deep read reports no property drift at all", () => {
+    // The thin diff already calls this `missing`; restating every declared
+    // property as `absent` would bury that one line.
+    const result = diffDeep({
+      declared: { b: { type: "T", properties: { A: 1, B: 2 } } },
+      live: live({}),
+    });
+    expect(result.drifted).toEqual([]);
+    expect(result.unchanged).toEqual([]);
+  });
+
+  test("a live entity nobody declared is reported separately", () => {
+    const result = diffDeep({
+      declared: {},
+      live: live({ ghost: { type: "T", properties: { A: 1 } } }),
+    });
+    expect(result.undeclaredEntities).toEqual(["ghost"]);
+    expect(result.drifted).toEqual([]);
+  });
+});
+
+describe("diffDeep with an accepted baseline", () => {
+  const baseline: BaselineLexicon = {
+    b: {
+      type: "AWS::S3::Bucket",
+      accepted: [{ path: "Tags[0].Value", value: "platform", note: "set by the platform team" }],
+    },
+  };
+
+  test("an accepted deviation is not drift", () => {
+    const result = diffDeep({
+      declared: { b: { type: "AWS::S3::Bucket", properties: {} } },
+      live: live({ b: { type: "AWS::S3::Bucket", properties: { Tags: [{ Value: "platform" }] } } }),
+      baseline,
+    });
+    expect(result.drifted).toEqual([]);
+    expect(result.accepted[0].changes[0]).toEqual({
+      path: "Tags[0].Value",
+      kind: "undeclared",
+      live: "platform",
+      baseline: "platform",
+    });
+  });
+
+  test("a value that moved away from the accepted one is drift again, and shows all three axes", () => {
+    const result = diffDeep({
+      declared: { b: { type: "AWS::S3::Bucket", properties: {} } },
+      live: live({ b: { type: "AWS::S3::Bucket", properties: { Tags: [{ Value: "someone-else" }] } } }),
+      baseline,
+    });
+    expect(result.drifted[0].changes[0]).toEqual({
+      path: "Tags[0].Value",
+      kind: "undeclared",
+      live: "someone-else",
+      baseline: "platform",
+    });
+  });
+
+  test("an entity with only accepted deviations is not counted as unchanged", () => {
+    const result = diffDeep({
+      declared: { b: { type: "AWS::S3::Bucket", properties: {} } },
+      live: live({ b: { type: "AWS::S3::Bucket", properties: { Tags: [{ Value: "platform" }] } } }),
+      baseline,
+    });
+    expect(result.unchanged).toEqual([]);
+  });
+
+  test("the baseline never suppresses a different path", () => {
+    const result = diffDeep({
+      declared: { b: { type: "AWS::S3::Bucket", properties: {} } },
+      live: live({ b: { type: "AWS::S3::Bucket", properties: { Tags: [{ Value: "platform" }], Extra: 1 } } }),
+      baseline,
+    });
+    expect(result.drifted[0].changes.map((c) => c.path)).toEqual(["Extra"]);
+  });
+});