@intentius/chant 0.124.51 → 0.124.54

package/dist/lifecycle/index-document.d.ts

@@ -0,0 +1,130 @@
+import type { GraphIR } from "../graph-ir.js";
+import type { UnobservedReason } from "../observation.js";
+/** The first chant that writes an index document to the store. */
+export declare const INDEX_DOCUMENT_FLOOR = "0.124.54";
+/** 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 declare function indexCoverageFor<E extends Pick<CoverageEntry, "listedType" | "location"> = CoverageEntry>(coverage: readonly E[], listedType: string, location: string): E | undefined;
+/** One index version. */
+export interface IndexDocument {
+    index: "v1";
+    stamp: IndexStamp;
+    coverage: CoverageEntry[];
+    graph: GraphIR;
+    notes?: IndexNote[];
+}
+/**
+ * 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 declare function canonicalScope(scope: IndexScope): IndexScope;
+/** JSON with object keys sorted at every level. Arrays keep their order. */
+export declare function canonicalIndexJson(value: unknown): string;
+/** The first 12 hex of sha256 over the canonical scope. */
+export declare function scopeDigest(scope: IndexScope): string;
+/** sha256 hex over the canonical `graph` and `coverage`, so an unchanged re-read is cheap to recognise. */
+export declare function indexDocumentDigest(doc: Pick<IndexDocument, "graph" | "coverage">): string;
+/** One path segment, percent-encoded so `/`, `:` and `%` in a name survive a git path and an S3 key. */
+export declare function encodeIndexSegment(segment: string): string;
+/** `cloud/<substrate>`, `engine/<engine>` or `chant`. */
+export declare function indexSourcePath(scope: IndexScope): string;
+/** The scope's identity segments, then its digest. */
+export declare function indexScopePath(scope: IndexScope): string;
+/** `<source path>/<scope path>`: what `stamp.scopeKey` holds and what the store lists under. */
+export declare function indexScopeKey(scope: IndexScope): string;
+/** `2026-10-26T09:14:03.120Z` as `20261026T091403Z`. */
+export declare function compactObservedAt(observedAt: string): string;
+/** `<observedAt>-<digest12>.json`. Names sort in time order. */
+export declare function indexVersionName(observedAt: string, digest: string): string;
+/** Whether a name in a scope path is a version (and not `scope.json`). */
+export declare function isIndexVersionName(name: string): boolean;
+/** The file beside the versions that holds the scope in full, so a person or `list` can read what a digest means. */
+export declare 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 declare function validateIndexDocument(doc: IndexDocument): void;
+//# sourceMappingURL=index-document.d.ts.map

package/dist/lifecycle/index-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-document.d.ts","sourceRoot":"","sources":["../../src/lifecycle/index-document.ts"],"names":[],"mappings":"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"}

package/dist/lifecycle/index-document.js

@@ -0,0 +1,189 @@
+/**
+ * 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 { NEXT_RELEASE } from "../release-floors.js";
+/** The first chant that writes an index document to the store. */
+export const INDEX_DOCUMENT_FLOOR = NEXT_RELEASE;
+/**
+ * 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(coverage, listedType, location) {
+    let best;
+    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;
+}
+const sortUnique = (xs) => [...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) {
+    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) {
+    return JSON.stringify(value, (_k, v) => {
+        if (v && typeof v === "object" && !Array.isArray(v)) {
+            return Object.fromEntries(Object.entries(v).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+        }
+        return v;
+    });
+}
+const sha256 = (s) => createHash("sha256").update(s, "utf8").digest("hex");
+/** The first 12 hex of sha256 over the canonical scope. */
+export function scopeDigest(scope) {
+    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) {
+    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) {
+    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) {
+    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) {
+    const digest = scopeDigest(scope);
+    let segments;
+    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) {
+    return `${indexSourcePath(scope)}/${indexScopePath(scope)}`;
+}
+/** `2026-10-26T09:14:03.120Z` as `20261026T091403Z`. */
+export function compactObservedAt(observedAt) {
+    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, digest) {
+    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) {
+    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) {
+    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/dist/lifecycle/index-drift.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Drift without a deploy (#4526, tier 2 of INTENTIUS/behold#1025): the deep
+ * diff of declared source against an index version, for source chant never
+ * applied. `chant lifecycle diff <env> --index <ref>` is the command.
+ *
+ * Three steps, all pure:
+ *
+ * 1. Every declared entity is joined to the index through its lexicon's
+ *    index match, with {@link joinDeclaredToIndex} (./index-join.ts, #4525).
+ *    `chant search --index` joins the same way, so a row that binds there
+ *    binds here.
+ * 2. A bound row's declared property tree is compared with its indexed
+ *    node's `attrs` by the live deep diff ({@link diffDeepObservation},
+ *    ./deep-observe.ts): both sides normalized with the lexicon's own hooks,
+ *    and the observation baseline (`.chant/observation-baseline/<env>.json`,
+ *    #4519) subtracted, value-bound. An accepted deviation stays quiet until
+ *    the indexed value moves again.
+ * 3. Every row becomes one drift record (`drift: "v1"`, ../drift-record.ts).
+ *
+ * A row that is not bound is reported with its join verdict and never
+ * diffed. The verdict rides in `evidence.engineCode`:
+ *
+ * - `absent`: the index's coverage listed the type and location and holds
+ *   no resource with the identity the declaration spells. The record is
+ *   `pending` (declared, confirmed absent). The rule is
+ *   {@link indexAbsence}, the one `chant index diff` reads "removed" by
+ *   (./index-diff.ts, #4533);
+ * - `not-observed`: the index did not look there (filtered, not reached, a
+ *   read failure), or the lexicon has no index match. An uncovered entity is
+ *   not observed, never drifted and never in sync;
+ * - `no-binding`: the declaration spells no identity to join on;
+ * - `ambiguous`: two or more indexed resources carry the identity, and chant
+ *   will not pick one.
+ *
+ * The last three are status `not-observed` with a reason from the
+ * observation contract's closed list. `not-observed` is also the index
+ * diff's word ({@link IndexChangeKind}), so the two comparisons against an
+ * index use one vocabulary.
+ *
+ * Every record's read is `live-read`, observed at the index's
+ * `stamp.observedAt`: an index version is a read of the provider, taken
+ * then. `evidence.command` names the index version that answered.
+ */
+import type { ChangeSetGraphNodes } from "../change-set-graph.js";
+import type { DeepNormalizationHooks } from "../deep-observation.js";
+import { type DriftDocument, type DriftRecord, type DriftStatus } from "../drift-record.js";
+import { type DeepDiffResult } from "./deep-diff.js";
+import { type DeclaredEntities } from "./deep-observe.js";
+import { type IndexChangeKind } from "./index-diff.js";
+import type { IndexDocument } from "./index-document.js";
+import { type IndexJoin, type JoinLexicon } from "./index-join.js";
+import { type ObservationBaseline } from "./observation-baseline.js";
+/** The status an unbound row takes when the index could not say: the index diff's word and the drift record's. */
+export declare const INDEX_NOT_OBSERVED: Extract<IndexChangeKind, DriftStatus>;
+/** What the drift read needs of a lexicon: its index match and its deep hooks. A `LexiconPlugin` is one. */
+export interface IndexDriftLexicon extends JoinLexicon {
+    deepNormalizationHooks?: DeepNormalizationHooks;
+}
+export interface IndexDriftInput {
+    /** The index version to compare against, as {@link readIndexRef} returned it. */
+    doc: IndexDocument;
+    /** Its version name, with or without `.json`. */
+    version: string;
+    /** Declared entities per lexicon, as the live deep diff takes them. */
+    entities: ReadonlyMap<string, DeclaredEntities>;
+    lexicons: readonly IndexDriftLexicon[];
+    /** The environment's accepted deviations, or null when none are recorded. */
+    baseline?: ObservationBaseline | null;
+    /** The drift record's `member`. */
+    member: string;
+    /** A stack of a multi-stack project: record addresses are `<stack>::<name>`, as search ids are. */
+    stack?: string;
+    /** The region the entities live in, from the stack (or the single stack) they belong to. */
+    region?: string;
+    /** The chant version, for `evidence.version` and the document's `chant`. */
+    chant?: string;
+    /** The member's graph, to place each record. Omit to leave `node` null. */
+    graph?: ChangeSetGraphNodes | null;
+}
+/** One lexicon's half of the read. */
+export interface IndexDriftLexiconResult {
+    /** Every declared entity's join verdict, by entity name. */
+    joins: Record<string, IndexJoin>;
+    /** The deep diff over the bound rows only. Unbound rows are never in it. */
+    deep: DeepDiffResult;
+}
+export interface IndexDriftCounts {
+    /** Declared entities compared. */
+    declared: number;
+    bound: number;
+    /** Reported property differences across every bound row. */
+    properties: number;
+    /** Bound rows with at least one reported difference. */
+    drifted: number;
+    /** Differences the baseline suppressed. */
+    accepted: number;
+    /** Rows the index listed the place of and does not hold. */
+    pending: number;
+    /** Rows the index could not say anything about. */
+    notObserved: number;
+}
+export interface IndexDriftResult {
+    /** `<scope key>@<version>`. */
+    ref: string;
+    observedAt: string;
+    byLexicon: Record<string, IndexDriftLexiconResult>;
+    /** One record per declared entity, sorted by address. */
+    records: DriftRecord[];
+    counts: IndexDriftCounts;
+}
+/** The command an index read's records name. */
+export declare function indexDriftCommand(ref: string): string;
+/**
+ * Compare every declared entity with the index version, lexicon by lexicon.
+ * Deterministic: the same index, declaration and baseline give the same
+ * records.
+ */
+export declare function diffDeclaredAgainstIndex(input: IndexDriftInput): IndexDriftResult;
+/** The records as one drift document. */
+export declare function indexDriftDocument(results: Iterable<IndexDriftResult>, chant?: string): DriftDocument;
+//# sourceMappingURL=index-drift.d.ts.map

package/dist/lifecycle/index-drift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-drift.d.ts","sourceRoot":"","sources":["../../src/lifecycle/index-drift.ts"],"names":[],"mappings":"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"}

package/dist/lifecycle/index-drift.js

@@ -0,0 +1,178 @@
+import { deepDiffDriftRecords, driftDocument, driftRecord, placeDriftRecord, } from "../drift-record.js";
+import { isUnobservedReason } from "../observation.js";
+import { countPropertyDrift } from "./deep-diff.js";
+import { diffDeepObservation } from "./deep-observe.js";
+import { indexAbsence } from "./index-diff.js";
+import { formatIndexRef, joinDeclaredToIndex } from "./index-join.js";
+import { baselineForLexicon } from "./observation-baseline.js";
+/** The status an unbound row takes when the index could not say: the index diff's word and the drift record's. */
+export const INDEX_NOT_OBSERVED = "not-observed";
+/** The command an index read's records name. */
+export function indexDriftCommand(ref) {
+    return `chant lifecycle diff --index ${ref}`;
+}
+function declaredGraph(lexicon, entities) {
+    const nodes = [...entities.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([name, e]) => ({ id: name, kind: e.entityType, lexicon, attrs: e.props ?? {} }));
+    return { nodes, edges: [], groups: { byLexicon: { [lexicon]: nodes.map((n) => n.id) } } };
+}
+function queriedOf(j) {
+    if (!j.listedType)
+        return undefined;
+    return `${j.listedType}${j.identifier !== undefined ? ` ${j.identifier}` : ""}${j.location ? ` @ ${j.location}` : ""}`;
+}
+/** An unbound row's status and why, from its verdict. Never diffed. */
+function unboundStatus(doc, j) {
+    const queried = queriedOf(j);
+    const q = queried ? { queried } : {};
+    switch (j.verdict) {
+        case "absent": {
+            // The join said absent from the index's coverage. Read it again with the
+            // index diff's rule, so "absent" means one thing in both comparisons.
+            const a = j.listedType && j.location ? indexAbsence(doc.coverage, j.listedType, j.location) : { kind: "removed" };
+            if (a.kind === "removed")
+                return { status: "pending" };
+            return {
+                status: INDEX_NOT_OBSERVED,
+                unobserved: {
+                    reason: isUnobservedReason(a.verdict) ? a.verdict : "not-reached",
+                    detail: a.detail ?? `the index's coverage says ${a.verdict} for ${j.listedType} at ${j.location}`,
+                    ...q,
+                },
+            };
+        }
+        case "not-observed":
+            return { status: INDEX_NOT_OBSERVED, unobserved: { reason: j.reason, detail: j.detail, ...q } };
+        case "no-binding":
+            return { status: INDEX_NOT_OBSERVED, unobserved: { reason: "no-binding", detail: j.detail, ...q } };
+        case "ambiguous":
+            return {
+                status: INDEX_NOT_OBSERVED,
+                unobserved: { reason: "no-binding", detail: `${j.detail} (candidates: ${j.candidates.join(", ")})`, ...q },
+            };
+    }
+}
+/**
+ * Compare every declared entity with the index version, lexicon by lexicon.
+ * Deterministic: the same index, declaration and baseline give the same
+ * records.
+ */
+export function diffDeclaredAgainstIndex(input) {
+    const { doc } = input;
+    const ref = formatIndexRef(doc.stamp.scopeKey, input.version.endsWith(".json") ? input.version : `${input.version}.json`);
+    const observedAt = doc.stamp.observedAt;
+    const command = indexDriftCommand(ref);
+    const address = (name) => (input.stack ? `${input.stack}::${name}` : name);
+    const indexed = new Map(doc.graph.nodes.map((n) => [n.id, n]));
+    const byLexicon = {};
+    const records = [];
+    const counts = { declared: 0, bound: 0, properties: 0, drifted: 0, accepted: 0, pending: 0, notObserved: 0 };
+    const adapter = {
+        member: input.member,
+        observedAt,
+        ...(input.graph !== undefined ? { graph: input.graph } : {}),
+        ...(input.chant ? { version: input.chant } : {}),
+    };
+    const evidence = (engineCode) => ({ tool: "chant", ...(input.chant ? { version: input.chant } : {}), command, ...(engineCode ? { engineCode } : {}) });
+    for (const lexicon of [...input.entities.keys()].sort()) {
+        const entities = input.entities.get(lexicon);
+        if (entities.size === 0)
+            continue;
+        const plugin = input.lexicons.find((l) => l.name === lexicon) ?? { name: lexicon };
+        const { joins } = joinDeclaredToIndex(declaredGraph(lexicon, entities), doc, [plugin], {
+            regionOf: () => input.region,
+        });
+        // The bound rows are the observed side, each its indexed node's tree.
+        const bound = new Map();
+        const resources = {};
+        for (const [name, entity] of entities) {
+            const j = joins[name];
+            if (j?.verdict !== "bound")
+                continue;
+            const hit = indexed.get(j.node);
+            if (!hit)
+                continue;
+            bound.set(name, entity);
+            resources[name] = { type: entity.entityType, physicalId: hit.physicalId ?? j.nativeId, properties: (hit.attrs ?? {}) };
+        }
+        const deep = diffDeepObservation(bound, { resources, unobserved: {} }, plugin.deepNormalizationHooks, baselineForLexicon(input.baseline, lexicon));
+        byLexicon[lexicon] = { joins, deep };
+        // Bound rows: the deep diff's records, and in-sync for a row whose every
+        // difference is accepted (the deep diff lists it under neither).
+        const deepRecords = new Map(deepDiffDriftRecords({ ...adapter, diff: deep, command }).map((r) => [r.address, r]));
+        for (const name of [...entities.keys()].sort()) {
+            const entity = entities.get(name);
+            const j = joins[name];
+            counts.declared++;
+            const at = { ...placeDriftRecord(adapter, "chant", address(name)) };
+            if (j?.verdict === "bound" && bound.has(name)) {
+                counts.bound++;
+                const r = deepRecords.get(name);
+                records.push(driftRecord({
+                    ...(r ?? {
+                        member: input.member,
+                        engine: "chant",
+                        address: name,
+                        observedAt,
+                        read: "live-read",
+                        status: "in-sync",
+                        evidence: evidence(),
+                    }),
+                    address: address(name),
+                    ...at,
+                    resourceType: entity.entityType,
+                }));
+                continue;
+            }
+            // Unbound: the verdict, never a diff.
+            const verdict = j ?? { verdict: "not-observed", reason: "not-reached", detail: "the join gave this row no verdict" };
+            if (verdict.verdict === "bound") {
+                // Bound to a node the index does not hold: the document disagrees with itself.
+                records.push(driftRecord({
+                    member: input.member,
+                    engine: "chant",
+                    address: address(name),
+                    ...at,
+                    resourceType: entity.entityType,
+                    observedAt,
+                    read: "live-read",
+                    status: INDEX_NOT_OBSERVED,
+                    unobserved: { reason: "read-failed", detail: `the index binds ${name} to ${verdict.node}, which its graph does not hold` },
+                    evidence: evidence("bound"),
+                }));
+                counts.notObserved++;
+                continue;
+            }
+            const s = unboundStatus(doc, verdict);
+            if (s.status === "pending")
+                counts.pending++;
+            else
+                counts.notObserved++;
+            records.push(driftRecord({
+                member: input.member,
+                engine: "chant",
+                address: address(name),
+                ...at,
+                resourceType: entity.entityType,
+                observedAt,
+                read: "live-read",
+                status: s.status,
+                ...(s.unobserved ? { unobserved: s.unobserved } : {}),
+                evidence: evidence(verdict.verdict),
+            }));
+        }
+        counts.properties += countPropertyDrift(deep);
+        counts.drifted += deep.drifted.length;
+        counts.accepted += deep.accepted.reduce((n, e) => n + e.changes.length, 0);
+    }
+    records.sort((a, b) => (a.address < b.address ? -1 : a.address > b.address ? 1 : 0));
+    return { ref, observedAt, byLexicon, records, counts };
+}
+/** The records as one drift document. */
+export function indexDriftDocument(results, chant) {
+    const records = [];
+    for (const r of results)
+        records.push(...r.records);
+    return driftDocument(records, chant ? { chant } : {});
+}