@intentius/chant 0.124.51 → 0.124.54

package/src/lifecycle/index-document.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "vitest";
+import {
+  canonicalScope,
+  compactObservedAt,
+  encodeIndexSegment,
+  indexScopeKey,
+  indexVersionName,
+  isIndexVersionName,
+  scopeDigest,
+  validateIndexDocument,
+  type IndexDocument,
+  type IndexScope,
+} from "./index-document";
+
+// The store layout ruled on INTENTIUS/behold#1025 (2026-10-26), as #4519 builds it.
+describe("index keys", () => {
+  const cloud: IndexScope = { kind: "cloud", substrate: "aws", scopeId: "123456789012", locations: ["us-west-2", "us-east-1", "us-east-1"], types: "*" };
+
+  test("two reads with the same flags share a scope path, in any order", () => {
+    const reordered: IndexScope = { ...cloud, locations: ["us-east-1", "us-west-2"] };
+    expect(scopeDigest(cloud)).toBe(scopeDigest(reordered));
+    expect(indexScopeKey(cloud)).toBe(indexScopeKey(reordered));
+    expect(canonicalScope(cloud)).toEqual({ kind: "cloud", substrate: "aws", scopeId: "123456789012", locations: ["us-east-1", "us-west-2"], types: "*" });
+  });
+
+  test("other regions or types write under another scope path", () => {
+    expect(indexScopeKey({ ...cloud, locations: ["us-east-1"] })).not.toBe(indexScopeKey(cloud));
+    expect(indexScopeKey({ ...cloud, types: ["AWS::S3::Bucket"] })).not.toBe(indexScopeKey(cloud));
+  });
+
+  test("index/<source>/<scopeId>/<scope digest>, each segment percent-encoded", () => {
+    expect(indexScopeKey(cloud)).toMatch(/^cloud\/aws\/123456789012\/[0-9a-f]{12}$/);
+    const gcp: IndexScope = { kind: "cloud", substrate: "gcp", scopeId: "projects/p:1", locations: "*", types: "*" };
+    expect(indexScopeKey(gcp)).toMatch(/^cloud\/gcp\/projects%2Fp%3A1\/[0-9a-f]{12}$/);
+    expect(indexScopeKey({ kind: "engine", engine: "plunge", project: "web", stack: "prod" })).toMatch(/^engine\/plunge\/web\/prod\/[0-9a-f]{12}$/);
+    expect(indexScopeKey({ kind: "chant", member: ".", env: "prod", lexicon: "aws" })).toMatch(/^chant\/%2E\/prod\/-\/aws\/[0-9a-f]{12}$/);
+    expect(encodeIndexSegment("..")).toBe("%2E%2E");
+    expect(() => encodeIndexSegment("")).toThrow();
+  });
+
+  test("a version is <observedAt>-<digest12>.json and names sort in time order", () => {
+    const digest = "a".repeat(64);
+    expect(compactObservedAt("2026-10-26T09:14:03.120Z")).toBe("20261026T091403Z");
+    expect(indexVersionName("2026-10-26T09:14:03.120Z", digest)).toBe("20261026T091403Z-aaaaaaaaaaaa.json");
+    expect(indexVersionName("2026-10-26T09:14:03Z", `sha256:${"b".repeat(64)}`)).toBe("20261026T091403Z-bbbbbbbbbbbb.json");
+    expect(isIndexVersionName("20261026T091403Z-aaaaaaaaaaaa.json")).toBe(true);
+    expect(isIndexVersionName("scope.json")).toBe(false);
+    expect(indexVersionName("2026-10-26T09:00:00Z", digest) < indexVersionName("2026-10-26T10:00:00Z", digest)).toBe(true);
+    expect(() => indexVersionName("yesterday", digest)).toThrow();
+    expect(() => indexVersionName("2026-10-26T09:00:00Z", "nothex")).toThrow();
+  });
+
+  test("a stamp that disagrees with itself is refused", () => {
+    const doc = {
+      index: "v1",
+      stamp: { source: { kind: "cloud", name: "behold-lister" }, scope: cloud, scopeKey: indexScopeKey(cloud), observedAt: "2026-10-26T00:00:00Z", digest: "c".repeat(64) },
+      coverage: [],
+      graph: { version: 1, nodes: [], edges: [] },
+    } as unknown as IndexDocument;
+    expect(() => validateIndexDocument(doc)).not.toThrow();
+    expect(() => validateIndexDocument({ ...doc, stamp: { ...doc.stamp, scopeKey: "cloud/aws/x" } })).toThrow(/scopeKey/);
+    expect(() => validateIndexDocument({ ...doc, stamp: { ...doc.stamp, source: { kind: "engine", name: "plunge" } } })).toThrow(/source kind/);
+  });
+});

package/src/lifecycle/index-document.ts

@@ -0,0 +1,299 @@
+/**
+ * An index document and where the index store keeps it (#4519, layout ruled
+ * on INTENTIUS/behold#1025, 2026-10-26).
+ *
+ * An index is an observed graph: a chant snapshot, a cloud listing typed
+ * through the lexicons (behold#1029, #4521), or a graph an engine prints
+ * (choudoufu, plunge). Every index is derived, stamped, never read for a
+ * decision and safe to lose. A document is a `GraphIR` inside a stamped
+ * envelope, never a second graph format.
+ *
+ * This module is pure: types, the canonical scope digest and the store key.
+ * ./snapshot-store.ts maps the keys onto a medium.
+ *
+ * Store key of an index version, relative to the store's `index` family:
+ *
+ *     <source path>/<scope path>/<observedAt>-<digest12>.json
+ *
+ * - source path: `cloud/<substrate>`, `engine/<engine>`, or `chant`;
+ * - scope path: the scope's identity segments, then the first 12 hex of the
+ *   scope digest: `<scopeId>/<scope digest>` for a cloud read,
+ *   `<estate>/<scope digest>` or `<project>/<stack>/<scope digest>` for an
+ *   engine, `<member>/<env>/<stack or ->/<lexicon>/<scope digest>` for chant.
+ *   Each segment is percent-encoded, so `/` and `:` in a name survive a git
+ *   path and an S3 key;
+ * - version: the read's start as `yyyymmddThhmmssZ` and the first 12 hex of
+ *   the document digest. A version is written once and never overwritten.
+ *
+ * Two reads with the same scope write under one scope path, and a read with
+ * other regions, types or filters writes under another, so a reader refuses a
+ * scope mismatch by comparing one string (`stamp.scopeKey`).
+ */
+import { createHash } from "node:crypto";
+import type { GraphIR } from "../graph-ir";
+import type { UnobservedReason } from "../observation";
+import { NEXT_RELEASE } from "../release-floors";
+
+/** The first chant that writes an index document to the store. */
+export const INDEX_DOCUMENT_FLOOR = NEXT_RELEASE;
+
+/** Who produced an index. */
+export type IndexSourceKind = "cloud" | "engine" | "chant";
+
+/** A direct cloud read (behold#1029). Lists are sorted and deduplicated by {@link canonicalScope}. */
+export interface CloudIndexScope {
+  kind: "cloud";
+  substrate: "aws" | "azure" | "gcp" | "kubernetes";
+  /** The account, subscription, project or cluster. */
+  scopeId: string;
+  /** Regions or locations, or `"*"` for every one. */
+  locations: readonly string[] | "*";
+  /** Listed types, or `"*"` for every one. */
+  types: readonly string[] | "*";
+  /** A tag or label filter, when the read had one. */
+  tagFilter?: Readonly<Record<string, string>>;
+}
+
+/** A graph an engine printed (choudoufu, plunge). */
+export interface EngineIndexScope {
+  kind: "engine";
+  engine: string;
+  /** choudoufu's estate. */
+  estate?: string;
+  /** plunge's project and stack. */
+  project?: string;
+  stack?: string;
+  /** The backend URL, with any credentials stripped before it reaches here. */
+  backend?: string;
+}
+
+/** A chant source: a snapshot or `chant graph --format ir`. Today's snapshot key, unchanged. */
+export interface ChantIndexScope {
+  kind: "chant";
+  /** `.` for a project outside a workspace. */
+  member: string;
+  env: string;
+  stack?: string;
+  lexicon: string;
+}
+
+export type IndexScope = CloudIndexScope | EngineIndexScope | ChantIndexScope;
+
+export interface IndexSource {
+  kind: IndexSourceKind;
+  /** `behold-lister`, `choudoufu`, `plunge`, `chant`. */
+  name: string;
+  version?: string;
+}
+
+export interface IndexStamp {
+  source: IndexSource;
+  scope: IndexScope;
+  /** The store path the scope maps to ({@link indexScopeKey}): a reader refuses a mismatch by comparing it. */
+  scopeKey: string;
+  /** When the read started, ISO UTC. */
+  observedAt: string;
+  /** When the last call returned, ISO UTC. */
+  completedAt?: string;
+  /** The source repository commit, when there is one. */
+  commit?: string;
+  /** sha256 hex of the canonical `graph` and `coverage` ({@link indexDocumentDigest}). */
+  digest: string;
+}
+
+/**
+ * What a read looked at, per type and location. A node can be absent only
+ * where this says `listed`. `"*"` in `listedType` or `location` means every
+ * type or every location (behold#1029's lister writes it for a run with
+ * `types` or `locations` of `"*"`); {@link indexCoverageFor} honours it.
+ */
+export interface CoverageEntry {
+  listedType: string;
+  location: string;
+  verdict: "listed" | UnobservedReason;
+  detail?: string;
+}
+
+/** A type with no lister, a lexicon with no catalog, a disabled API. */
+export interface IndexNote {
+  kind: string;
+  message: string;
+  listedType?: string;
+  location?: string;
+  /** A command the person can run themselves, never run by the source (a GCP API to enable). */
+  command?: string;
+}
+
+/**
+ * The coverage entry that speaks for one (type, location), or undefined when
+ * none does (not observed). An exact entry wins over a wildcard one, and a
+ * wildcard on one side over a wildcard on both.
+ */
+export function indexCoverageFor<E extends Pick<CoverageEntry, "listedType" | "location"> = CoverageEntry>(coverage: readonly E[], listedType: string, location: string): E | undefined {
+  let best: E | undefined;
+  let bestScore = -1;
+  for (const e of coverage) {
+    const typeHit = e.listedType === listedType ? 2 : e.listedType === "*" ? 0 : -1;
+    const locHit = e.location === location ? 1 : e.location === "*" ? 0 : -1;
+    if (typeHit < 0 || locHit < 0) continue;
+    const score = typeHit + locHit;
+    if (score > bestScore) {
+      best = e;
+      bestScore = score;
+    }
+  }
+  return best;
+}
+
+/** One index version. */
+export interface IndexDocument {
+  index: "v1";
+  stamp: IndexStamp;
+  coverage: CoverageEntry[];
+  graph: GraphIR;
+  notes?: IndexNote[];
+}
+
+const sortUnique = (xs: readonly string[]): string[] => [...new Set(xs)].sort();
+
+/**
+ * The scope with every list sorted and deduplicated and every absent field
+ * left out, so two reads with the same flags give the same digest.
+ */
+export function canonicalScope(scope: IndexScope): IndexScope {
+  switch (scope.kind) {
+    case "cloud":
+      return {
+        kind: "cloud",
+        substrate: scope.substrate,
+        scopeId: scope.scopeId,
+        locations: scope.locations === "*" ? "*" : sortUnique(scope.locations),
+        types: scope.types === "*" ? "*" : sortUnique(scope.types),
+        ...(scope.tagFilter && Object.keys(scope.tagFilter).length > 0
+          ? { tagFilter: Object.fromEntries(Object.entries(scope.tagFilter).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) }
+          : {}),
+      };
+    case "engine":
+      return {
+        kind: "engine",
+        engine: scope.engine,
+        ...(scope.estate !== undefined ? { estate: scope.estate } : {}),
+        ...(scope.project !== undefined ? { project: scope.project } : {}),
+        ...(scope.stack !== undefined ? { stack: scope.stack } : {}),
+        ...(scope.backend !== undefined ? { backend: scope.backend } : {}),
+      };
+    case "chant":
+      return {
+        kind: "chant",
+        member: scope.member,
+        env: scope.env,
+        ...(scope.stack !== undefined ? { stack: scope.stack } : {}),
+        lexicon: scope.lexicon,
+      };
+  }
+}
+
+/** JSON with object keys sorted at every level. Arrays keep their order. */
+export function canonicalIndexJson(value: unknown): string {
+  return JSON.stringify(value, (_k, v: unknown) => {
+    if (v && typeof v === "object" && !Array.isArray(v)) {
+      return Object.fromEntries(Object.entries(v as Record<string, unknown>).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+    }
+    return v;
+  });
+}
+
+const sha256 = (s: string): string => createHash("sha256").update(s, "utf8").digest("hex");
+
+/** The first 12 hex of sha256 over the canonical scope. */
+export function scopeDigest(scope: IndexScope): string {
+  return sha256(canonicalIndexJson(canonicalScope(scope))).slice(0, 12);
+}
+
+/** sha256 hex over the canonical `graph` and `coverage`, so an unchanged re-read is cheap to recognise. */
+export function indexDocumentDigest(doc: Pick<IndexDocument, "graph" | "coverage">): string {
+  return sha256(canonicalIndexJson({ coverage: doc.coverage, graph: doc.graph }));
+}
+
+/** One path segment, percent-encoded so `/`, `:` and `%` in a name survive a git path and an S3 key. */
+export function encodeIndexSegment(segment: string): string {
+  if (segment === "") throw new Error("an index key segment is never empty");
+  const encoded = encodeURIComponent(segment).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+  // `.` and `..` are valid components to encodeURIComponent and meaningful to a filesystem.
+  return encoded === "." ? "%2E" : encoded === ".." ? "%2E%2E" : encoded;
+}
+
+/** `cloud/<substrate>`, `engine/<engine>` or `chant`. */
+export function indexSourcePath(scope: IndexScope): string {
+  switch (scope.kind) {
+    case "cloud":
+      return `cloud/${encodeIndexSegment(scope.substrate)}`;
+    case "engine":
+      return `engine/${encodeIndexSegment(scope.engine)}`;
+    case "chant":
+      return "chant";
+  }
+}
+
+/** The scope's identity segments, then its digest. */
+export function indexScopePath(scope: IndexScope): string {
+  const digest = scopeDigest(scope);
+  let segments: string[];
+  switch (scope.kind) {
+    case "cloud":
+      segments = [scope.scopeId];
+      break;
+    case "engine":
+      segments = scope.estate !== undefined ? [scope.estate] : [scope.project ?? "-", scope.stack ?? "-"];
+      break;
+    case "chant":
+      segments = [scope.member, scope.env, scope.stack ?? "-", scope.lexicon];
+      break;
+  }
+  return [...segments.map(encodeIndexSegment), digest].join("/");
+}
+
+/** `<source path>/<scope path>`: what `stamp.scopeKey` holds and what the store lists under. */
+export function indexScopeKey(scope: IndexScope): string {
+  return `${indexSourcePath(scope)}/${indexScopePath(scope)}`;
+}
+
+/** `2026-10-26T09:14:03.120Z` as `20261026T091403Z`. */
+export function compactObservedAt(observedAt: string): string {
+  const t = new Date(observedAt);
+  if (Number.isNaN(t.getTime())) throw new Error(`observedAt "${observedAt}" is not a time`);
+  return t.toISOString().replace(/[-:]|\.\d{3}/g, "");
+}
+
+/** `<observedAt>-<digest12>.json`. Names sort in time order. */
+export function indexVersionName(observedAt: string, digest: string): string {
+  const hex = digest.replace(/^sha256:/, "");
+  if (!/^[0-9a-f]{12,}$/.test(hex)) throw new Error(`digest "${digest}" is not sha256 hex`);
+  return `${compactObservedAt(observedAt)}-${hex.slice(0, 12)}.json`;
+}
+
+/** Whether a name in a scope path is a version (and not `scope.json`). */
+export function isIndexVersionName(name: string): boolean {
+  return /^\d{8}T\d{6}Z-[0-9a-f]{12}\.json$/.test(name);
+}
+
+/** The file beside the versions that holds the scope in full, so a person or `list` can read what a digest means. */
+export const INDEX_SCOPE_FILE = "scope.json";
+
+/**
+ * Refuse a document whose stamp disagrees with itself: a `scopeKey` that is
+ * not its scope's, or a source kind that is not its scope's kind. The store
+ * writes only a document that passes, so a path always means its scope.
+ */
+export function validateIndexDocument(doc: IndexDocument): void {
+  if (doc.index !== "v1") throw new Error(`index document version "${String(doc.index)}" is not v1`);
+  const { stamp } = doc;
+  if (stamp.source.kind !== stamp.scope.kind) {
+    throw new Error(`index stamp source kind "${stamp.source.kind}" does not match its scope kind "${stamp.scope.kind}"`);
+  }
+  const expected = indexScopeKey(stamp.scope);
+  if (stamp.scopeKey !== expected) {
+    throw new Error(`index stamp scopeKey "${stamp.scopeKey}" is not its scope's key "${expected}"`);
+  }
+  indexVersionName(stamp.observedAt, stamp.digest);
+}

package/src/lifecycle/index-drift.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, test } from "vitest";
+import { parseDriftDocument, type DriftRecord } from "../drift-record";
+import type { DeclaredEntities } from "./deep-observe";
+import type { DeclaredIdentity, IndexIdentity } from "./identity-match";
+import { diffDeclaredAgainstIndex, indexDriftDocument, INDEX_NOT_OBSERVED, type IndexDriftLexicon } from "./index-drift";
+import { indexVersionName } from "./index-document";
+import { acceptDeviations, emptyBaseline } from "./observation-baseline";
+import { typeListing, type ListedResource, type ListingLexicon, type ListingResult } from "./type-listing";
+
+// #4526: `chant lifecycle diff <env> --index <ref>`, the deep diff of declared
+// source against an index version, over fixture indexes typed the way
+// behold#1026 writes one (#4521's typeListing), joined as #4525 joins them.
+
+const IDENTITY: Record<string, { parts?: string[]; serverAssigned?: boolean; global?: boolean }> = {
+  "Store::Bucket": { parts: ["BucketName"] },
+  "Iam::Role": { parts: ["RoleName"], global: true },
+  "Queue::Queue": { parts: ["QueueUrl"], serverAssigned: true },
+  "Kv::Table": { parts: ["TableName"] },
+};
+
+const identity: IndexIdentity = {
+  substrate: "aws",
+  declaredIdentity(entityType, props): DeclaredIdentity {
+    const row = IDENTITY[entityType];
+    if (!row?.parts) return { kind: "unmatchable", reason: "unsupported-kind", detail: `${entityType} has no primary identifier on record` };
+    if (row.serverAssigned) return { kind: "unmatchable", reason: "no-binding", detail: `${entityType} is assigned by the service` };
+    const values: string[] = [];
+    for (const p of row.parts) {
+      const v = props[p];
+      if (typeof v !== "string" || v === "") return { kind: "unmatchable", reason: "no-binding", detail: "identity is not in the declaration" };
+      values.push(v);
+    }
+    return { kind: "identifier", listedType: entityType, identifier: values.join("|"), global: row.global === true };
+  },
+};
+
+const typing: ListingLexicon[] = [{ name: "fake", listedTypes: { substrate: "aws", kindFor: (t) => (t in IDENTITY ? t : undefined) } }];
+const lexicons: IndexDriftLexicon[] = [{ name: "fake", indexIdentity: identity }, { name: "other" }];
+
+const r = (listedType: string, location: string, nativeId: string, properties: Record<string, unknown> = {}): ListedResource => ({
+  listedType,
+  location,
+  nativeId,
+  cloudIds: [{ kind: "import-id", value: nativeId }],
+  tags: {},
+  properties,
+  observedAt: "2026-10-26T09:00:01.000Z",
+});
+
+function listing(resources: ListedResource[], startedAt = "2026-10-26T09:00:00.000Z"): ListingResult {
+  return {
+    listing: "v1",
+    source: { name: "behold-lister", version: "0.0.0-test" },
+    // Kv::Table is outside the scope: the index never looked for one.
+    scope: { substrate: "aws", scopeId: "000000000000", locations: ["us-east-1"], types: ["Store::Bucket", "Iam::Role", "Queue::Queue"] },
+    startedAt,
+    completedAt: startedAt.replace(":00.000Z", ":04.000Z"),
+    resources,
+    coverage: [
+      { listedType: "Store::Bucket", location: "us-east-1", verdict: "listed" },
+      { listedType: "Iam::Role", location: "global", verdict: "listed" },
+      { listedType: "Queue::Queue", location: "us-east-1", verdict: "listed" },
+    ],
+    notes: [],
+  };
+}
+
+const bucket = (status: string) => ({ BucketName: "shop-assets", Arn: "arn:aws:s3:::shop-assets", VersioningConfiguration: { Status: status } });
+
+/** The index `chant import --index` read: what source was written from. */
+const atImport = typeListing(listing([r("Store::Bucket", "us-east-1", "shop-assets", bucket("Enabled")), r("Iam::Role", "global", "app-runner", { RoleName: "app-runner" })]), typing);
+
+/** A later read, after somebody set versioning to Suspended in the console. */
+const afterConsole = typeListing(
+  listing([r("Store::Bucket", "us-east-1", "shop-assets", bucket("Suspended")), r("Iam::Role", "global", "app-runner", { RoleName: "app-runner" })], "2026-10-27T10:00:00.000Z"),
+  typing,
+);
+
+const versionOf = (doc: typeof atImport) => indexVersionName(doc.stamp.observedAt, doc.stamp.digest);
+
+/** Source as the import wrote it: no read-only Arn, every other property as indexed. */
+function declared(extra: Array<[string, string, Record<string, unknown>]> = [], lexicon = "fake"): Map<string, DeclaredEntities> {
+  const fake: DeclaredEntities = new Map([
+    ["assets", { entityType: "Store::Bucket", props: { BucketName: "shop-assets", VersioningConfiguration: { Status: "Enabled" } } }],
+    ["runner", { entityType: "Iam::Role", props: { RoleName: "app-runner" } }],
+  ]);
+  const out = new Map<string, DeclaredEntities>([[lexicon, fake]]);
+  for (const [name, type, props] of extra) fake.set(name, { entityType: type, props });
+  return out;
+}
+
+const run = (doc: typeof atImport, entities = declared(), more: Partial<Parameters<typeof diffDeclaredAgainstIndex>[0]> = {}) =>
+  diffDeclaredAgainstIndex({ doc, version: versionOf(doc), entities, lexicons, member: "shop", region: "us-east-1", ...more });
+
+const record = (records: DriftRecord[], address: string) => records.find((x) => x.address === address)!;
+
+describe("diffDeclaredAgainstIndex", () => {
+  test("source imported from an index reads back with no drift against that index", () => {
+    const res = run(atImport);
+    expect(res.counts).toMatchObject({ declared: 2, bound: 2, properties: 0, drifted: 0, pending: 0, notObserved: 0 });
+    expect(res.records.map((x) => [x.address, x.status])).toEqual([
+      ["assets", "in-sync"],
+      ["runner", "in-sync"],
+    ]);
+    // The read-only Arn is indexed and never declared: somebody else's field, not drift.
+    expect(res.byLexicon.fake.deep.unclaimed).toEqual([expect.objectContaining({ name: "assets", fields: [expect.objectContaining({ path: "Arn" })] })]);
+  });
+
+  test("a property changed in the console between import and a later read is drift on that declared property", () => {
+    const res = run(afterConsole);
+    expect(res.counts).toMatchObject({ bound: 2, properties: 1, drifted: 1 });
+    const assets = record(res.records, "assets");
+    expect(assets).toMatchObject({
+      status: "drifted",
+      read: "live-read",
+      resourceType: "Store::Bucket",
+      observedAt: afterConsole.stamp.observedAt,
+      attributes: [{ path: "VersioningConfiguration.Status", before: "Enabled", after: "Suspended" }],
+    });
+    expect(assets.evidence.command).toBe(`chant lifecycle diff --index ${afterConsole.stamp.scopeKey}@${versionOf(afterConsole).replace(/\.json$/, "")}`);
+    expect(record(res.records, "runner").status).toBe("in-sync");
+  });
+
+  test("an accepted deviation is quiet until the indexed value moves again", () => {
+    const baseline = acceptDeviations(emptyBaseline("dev"), "fake", [{ entity: "assets", type: "Store::Bucket", path: "VersioningConfiguration.Status", value: "Suspended" }], {
+      now: "2026-10-27T11:00:00.000Z",
+    });
+    const quiet = run(afterConsole, declared(), { baseline });
+    expect(quiet.counts).toMatchObject({ properties: 0, drifted: 0, accepted: 1 });
+    expect(record(quiet.records, "assets").status).toBe("in-sync");
+    expect(quiet.byLexicon.fake.deep.accepted).toEqual([expect.objectContaining({ name: "assets" })]);
+
+    const movedAgain = typeListing(
+      listing([r("Store::Bucket", "us-east-1", "shop-assets", { ...bucket("Enabled"), VersioningConfiguration: { Status: "Disabled" } })], "2026-10-28T10:00:00.000Z"),
+      typing,
+    );
+    const loud = run(movedAgain, declared(), { baseline });
+    expect(loud.byLexicon.fake.deep.drifted[0]?.changes[0]).toMatchObject({ path: "VersioningConfiguration.Status", declared: "Enabled", live: "Disabled", baseline: "Suspended" });
+    expect(record(loud.records, "assets")).toMatchObject({ status: "drifted", attributes: [{ path: "VersioningConfiguration.Status", before: "Enabled", after: "Disabled" }] });
+  });
+
+  test("an entity whose resource the index did not cover is not observed, never diffed", () => {
+    const res = run(afterConsole, declared([["sessions", "Kv::Table", { TableName: "sessions", BillingMode: "PAY_PER_REQUEST" }]]));
+    const sessions = record(res.records, "sessions");
+    expect(sessions).toMatchObject({ status: INDEX_NOT_OBSERVED, unobserved: { reason: "filtered" }, evidence: { engineCode: "not-observed" } });
+    expect(sessions.attributes).toBeUndefined();
+    expect(res.byLexicon.fake.deep.drifted.map((d) => d.name)).toEqual(["assets"]);
+    expect(res.byLexicon.fake.deep.unchanged).not.toContain("sessions");
+    expect(res.counts.notObserved).toBe(1);
+  });
+
+  test("absent where the index listed the type and location is pending, with the verdict", () => {
+    const res = run(atImport, declared([["archive", "Store::Bucket", { BucketName: "never-made" }]]));
+    expect(record(res.records, "archive")).toMatchObject({ status: "pending", evidence: { engineCode: "absent" } });
+    expect(res.counts.pending).toBe(1);
+  });
+
+  test("a row with no identity to join on, or two candidates, is reported with its verdict and never diffed", () => {
+    const res = run(atImport, declared([["orders", "Queue::Queue", { QueueName: "orders" }]]));
+    expect(record(res.records, "orders")).toMatchObject({ status: "not-observed", unobserved: { reason: "no-binding" }, evidence: { engineCode: "no-binding" } });
+
+    const twice = typeListing(
+      {
+        ...listing([r("Store::Bucket", "us-east-1", "shop-assets", bucket("Enabled")), r("Store::Bucket", "us-west-2", "shop-assets", bucket("Enabled"))]),
+        scope: { substrate: "aws", scopeId: "000000000000", locations: ["us-east-1", "us-west-2"], types: ["Store::Bucket"] },
+      },
+      typing,
+    );
+    const amb = diffDeclaredAgainstIndex({ doc: twice, version: versionOf(twice), entities: declared(), lexicons, member: "shop" });
+    expect(record(amb.records, "assets")).toMatchObject({ status: "not-observed", unobserved: { reason: "no-binding", detail: expect.stringContaining("none is bound") }, evidence: { engineCode: "ambiguous" } });
+    expect(amb.byLexicon.fake.deep.drifted).toEqual([]);
+  });
+
+  test("a lexicon with no index match is not observed on every row", () => {
+    const res = run(atImport, declared([], "other"));
+    expect(res.records.every((x) => x.status === "not-observed" && x.unobserved?.reason === "unsupported-kind")).toBe(true);
+    expect(res.counts).toMatchObject({ declared: 2, bound: 0, notObserved: 2 });
+  });
+
+  test("a stack's records are addressed as search ids are, and the records are one drift document v1", () => {
+    const res = run(afterConsole, declared([["sessions", "Kv::Table", { TableName: "sessions" }]]), { stack: "east" });
+    expect(res.records.map((x) => x.address)).toEqual(["east::assets", "east::runner", "east::sessions"]);
+    const doc = indexDriftDocument([res], "0.0.0-test");
+    expect(doc).toMatchObject({ drift: "v1", chant: "0.0.0-test", counts: { drifted: 1, "in-sync": 1, "not-observed": 1 } });
+    expect(parseDriftDocument(JSON.parse(JSON.stringify(doc)))).toEqual(doc);
+  });
+
+  test("the same index, source and baseline give the same records", () => {
+    expect(JSON.stringify(run(afterConsole).records)).toBe(JSON.stringify(run(afterConsole).records));
+  });
+});