@noy-db/core 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -21,7 +21,30 @@ interface EncryptedEnvelope {
 }
 /** All records across all collections for a compartment. */
 type CompartmentSnapshot = Record<string, Record<string, EncryptedEnvelope>>;
+/**
+ * Result of a single page fetch via the optional `listPage` adapter extension.
+ *
+ * `items` carries the actual encrypted envelopes (not just ids) so the
+ * caller can decrypt and emit a single record without an extra `get()`
+ * round-trip per id. `nextCursor` is `null` on the final page.
+ */
+interface ListPageResult {
+    /** Encrypted envelopes for this page, in adapter-defined order. */
+    items: Array<{
+        id: string;
+        envelope: EncryptedEnvelope;
+    }>;
+    /** Opaque cursor for the next page, or `null` if this was the last page. */
+    nextCursor: string | null;
+}
 interface NoydbAdapter {
+    /**
+     * Optional human-readable adapter name (e.g. 'memory', 'file', 'dynamo').
+     * Used in diagnostic messages and the listPage fallback warning. Adapters
+     * are encouraged to set this so logs are clearer about which backend is
+     * involved when something goes wrong.
+     */
+    name?: string;
     /** Get a single record. Returns null if not found. */
     get(compartment: string, collection: string, id: string): Promise<EncryptedEnvelope | null>;
     /** Put a record. Throws ConflictError if expectedVersion doesn't match. */
@@ -36,6 +59,26 @@ interface NoydbAdapter {
     saveAll(compartment: string, data: CompartmentSnapshot): Promise<void>;
     /** Optional connectivity check for sync engine. */
     ping?(): Promise<boolean>;
+    /**
+     * Optional pagination extension. Adapters that implement `listPage` get
+     * the streaming `Collection.scan()` fast path; adapters that don't are
+     * silently fallen back to a full `loadAll()` + slice (with a one-time
+     * console.warn).
+     *
+     * `cursor` is opaque to the core — each adapter encodes its own paging
+     * state (DynamoDB: base64 LastEvaluatedKey JSON; S3: ContinuationToken;
+     * memory/file/browser: numeric offset of a sorted id list). Pass
+     * `undefined` to start from the beginning.
+     *
+     * `limit` is a soft upper bound on `items.length`. Adapters MAY return
+     * fewer items even when more exist (e.g. if the underlying store has
+     * its own page size cap), and MUST signal "no more pages" by returning
+     * `nextCursor: null`.
+     *
+     * The 6-method core contract is unchanged — this is an additive
+     * extension discovered via `'listPage' in adapter`.
+     */
+    listPage?(compartment: string, collection: string, cursor?: string, limit?: number): Promise<ListPageResult>;
 }
 /** Type-safe helper for creating adapter factories. */
 declare function defineAdapter<TOptions>(factory: (options: TOptions) => NoydbAdapter): (options: TOptions) => NoydbAdapter;
@@ -57,6 +100,32 @@ interface CompartmentBackup {
     readonly _exported_by: string;
     readonly keyrings: Record<string, KeyringFile>;
     readonly collections: CompartmentSnapshot;
+    /**
+     * Internal collections (`_ledger`, `_ledger_deltas`, `_history`, `_sync`, …)
+     * captured alongside the data collections. Optional for backwards
+     * compat with v0.3 backups, which only stored data collections —
+     * loading a v0.3 backup leaves the ledger empty (and `verifyBackupIntegrity`
+     * skips the chain check, surfacing only a console warning).
+     */
+    readonly _internal?: CompartmentSnapshot;
+    /**
+     * Verifiable-backup metadata (v0.4 #46). Embeds the ledger head at
+     * dump time so `load()` can cross-check that the loaded chain matches
+     * exactly what was exported. A backup whose chain has been tampered
+     * with — either by modifying ledger entries or by modifying data
+     * envelopes that the chain references — fails this check.
+     *
+     * Optional for backwards compat with v0.3 backups; missing means
+     * "legacy backup, load with a warning, no integrity check".
+     */
+    readonly ledgerHead?: {
+        /** Hex sha256 of the canonical JSON of the last ledger entry. */
+        readonly hash: string;
+        /** Sequential index of the last ledger entry. */
+        readonly index: number;
+        /** ISO timestamp captured at dump time. */
+        readonly ts: string;
+    };
 }
 interface DirtyEntry {
     readonly compartment: string;
@@ -236,6 +305,950 @@ declare class NotFoundError extends NoydbError {
 declare class ValidationError extends NoydbError {
     constructor(message?: string);
 }
+/**
+ * Thrown when a Standard Schema v1 validator rejects a record on
+ * `put()` (input validation) or on read (output validation). Carries
+ * the raw issue list so callers can render field-level errors.
+ *
+ * `direction` distinguishes the two cases:
+ *   - `'input'`: the user passed bad data into `put()`. This is a
+ *     normal error case that application code should handle — typically
+ *     by showing validation messages in the UI.
+ *   - `'output'`: stored data does not match the current schema. This
+ *     indicates a schema drift (the schema was changed without
+ *     migrating the existing records) and should be treated as a bug
+ *     — the application should not swallow it silently.
+ *
+ * The `issues` type is deliberately `readonly unknown[]` on this class
+ * so that `errors.ts` doesn't need to import from `schema.ts` (and
+ * create a dependency cycle). Callers who know they're holding a
+ * `SchemaValidationError` can cast to the more precise
+ * `readonly StandardSchemaV1Issue[]` from `schema.ts`.
+ */
+declare class SchemaValidationError extends NoydbError {
+    readonly issues: readonly unknown[];
+    readonly direction: 'input' | 'output';
+    constructor(message: string, issues: readonly unknown[], direction: 'input' | 'output');
+}
+/**
+ * Thrown when `Compartment.load()` finds that a backup's hash chain
+ * doesn't verify, or that its embedded `ledgerHead.hash` doesn't
+ * match the chain head reconstructed from the loaded entries.
+ *
+ * Distinct from `BackupCorruptedError` so callers can choose to
+ * recover from one but not the other (e.g., a corrupted JSON file is
+ * unrecoverable; a chain mismatch might mean the backup is from an
+ * incompatible noy-db version).
+ */
+declare class BackupLedgerError extends NoydbError {
+    /** First-broken-entry index, if known. */
+    readonly divergedAt?: number;
+    constructor(message: string, divergedAt?: number);
+}
+/**
+ * Thrown when `Compartment.load()` finds that the backup's data
+ * collection content doesn't match the ledger's recorded
+ * `payloadHash`es. This is the "envelope was tampered with after
+ * dump" detection — the chain itself can be intact, but if any
+ * encrypted record bytes were swapped, this check catches it.
+ */
+declare class BackupCorruptedError extends NoydbError {
+    /** The (collection, id) pair whose envelope failed the hash check. */
+    readonly collection: string;
+    readonly id: string;
+    constructor(collection: string, id: string, message: string);
+}
+
+/**
+ * Standard Schema v1 integration.
+ *
+ * This file is the v0.4 entry point for **schema validation**. Any
+ * validator that implements the [Standard Schema v1
+ * protocol](https://standardschema.dev) — Zod, Valibot, ArkType, Effect
+ * Schema, etc. — can be attached to a `Collection` or `defineNoydbStore`
+ * and will:
+ *
+ *   1. Validate the record BEFORE encryption on `put()` — bad data is
+ *      rejected at the store boundary with a rich issue list.
+ *   2. Validate the record AFTER decryption on `get()`/`list()`/`query()`
+ *      — stored data that has drifted from the current schema throws
+ *      loudly instead of silently propagating garbage to the UI.
+ *
+ * ## Why vendor the types?
+ *
+ * Standard Schema is a protocol, not a library. The spec is <200 lines of
+ * TypeScript and has no runtime. There's an official `@standard-schema/spec`
+ * types package on npm, but pulling it in would add a dependency edge
+ * purely for type definitions. Vendoring the minimal surface keeps
+ * `@noy-db/core` at **zero runtime dependencies** and gives us freedom to
+ * evolve the helpers without a version-lock on the spec package.
+ *
+ * If the spec changes in a breaking way (unlikely — it's frozen at v1),
+ * we update this file and bump our minor.
+ *
+ * ## Why not just run `schema.parse(value)` directly?
+ *
+ * Because then we'd be locked to whichever validator happens to have
+ * `.parse`. Standard Schema's `'~standard'.validate` contract is the same
+ * across every implementation and includes a structured issues list,
+ * which is much more useful than a thrown error for programmatic error
+ * handling (e.g., rendering field-level messages in a Vue component).
+ */
+/**
+ * The Standard Schema v1 protocol. A schema is any object that exposes a
+ * `'~standard'` property with `version: 1` and a `validate` function.
+ *
+ * The type parameters are:
+ *   - `Input`  — the type accepted by `validate` (what the user passes in)
+ *   - `Output` — the type produced by `validate` (what we store/return,
+ *                may differ from Input if the schema transforms or coerces)
+ *
+ * In most cases `Input === Output`, but validators that transform
+ * (Zod's `.transform`, Valibot's `transform`, etc.) can narrow or widen.
+ *
+ * We intentionally keep the `types` field `readonly` and optional — the
+ * spec marks it as optional because it's only used for inference, and
+ * not every implementation bothers populating it at runtime.
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardSchemaV1SyncResult<Output> | Promise<StandardSchemaV1SyncResult<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        } | undefined;
+    };
+}
+/**
+ * The result of a single call to `schema['~standard'].validate`. Either
+ * `{ value }` on success or `{ issues }` on failure — never both.
+ *
+ * The spec allows `issues` to be undefined on success (and some
+ * validators leave it that way), so consumers should discriminate on
+ * `issues?.length` rather than on truthiness of `value`.
+ */
+type StandardSchemaV1SyncResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly value?: undefined;
+    readonly issues: readonly StandardSchemaV1Issue[];
+};
+/**
+ * A single validation issue. The `message` is always present; the `path`
+ * is optional and points at the offending field when the schema tracks
+ * it (virtually every validator does for object types).
+ *
+ * The path is deliberately permissive — both a plain `PropertyKey` and a
+ * `{ key }` wrapper are allowed so validators that wrap path segments in
+ * objects (Zod does this in some modes) don't need special handling.
+ */
+interface StandardSchemaV1Issue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | {
+        readonly key: PropertyKey;
+    }> | undefined;
+}
+/**
+ * Infer the output type of a Standard Schema. Consumers use this to
+ * pull the type out of a schema instance when they want to declare a
+ * Collection<T> or defineNoydbStore<T> with `T` derived from the schema.
+ *
+ * Example:
+ * ```ts
+ * const InvoiceSchema = z.object({ id: z.string(), amount: z.number() })
+ * type Invoice = InferOutput<typeof InvoiceSchema>
+ * ```
+ */
+type InferOutput<T extends StandardSchemaV1> = T extends StandardSchemaV1<unknown, infer O> ? O : never;
+/**
+ * Validate an input value against a schema. Throws
+ * `SchemaValidationError` if the schema rejects, with the rich issue
+ * list attached. Otherwise returns the (possibly transformed) output
+ * value.
+ *
+ * The `context` string is included in the thrown error's message so the
+ * caller knows where the failure happened (e.g. `"put(inv-001)"`) without
+ * every caller having to wrap the throw in a try/catch.
+ *
+ * This function is ALWAYS async because some validators (notably Effect
+ * Schema and Zod's `.refine` with async predicates) can return a
+ * Promise. We `await` the result unconditionally to normalize the
+ * contract — the extra microtask is free compared to the cost of an
+ * encrypt/decrypt round-trip.
+ */
+declare function validateSchemaInput<Output>(schema: StandardSchemaV1<unknown, Output>, value: unknown, context: string): Promise<Output>;
+/**
+ * Validate an already-stored value coming OUT of the collection. This
+ * is a distinct helper from `validateSchemaInput` because the error
+ * semantics differ: an output-validation failure means the data in
+ * storage has drifted from the current schema (an unexpected state),
+ * whereas an input-validation failure means the user passed bad data
+ * (an expected state for a UI that isn't guarding its inputs).
+ *
+ * We still throw — silently returning bad data would be worse — but
+ * the error carries `direction: 'output'` so upstream code (and a
+ * potential migrate hook) can distinguish the two cases.
+ */
+declare function validateSchemaOutput<Output>(schema: StandardSchemaV1<unknown, Output>, value: unknown, context: string): Promise<Output>;
+
+/**
+ * Ledger entry shape + canonical JSON + sha256 helpers.
+ *
+ * This file holds the PURE primitives used by the hash-chained ledger:
+ * the entry type, the deterministic (sort-stable) JSON encoder, and
+ * the sha256 hasher that produces `prevHash` and `ledger.head()`.
+ *
+ * Everything here is validator-free and side-effect free — the only
+ * runtime dep is Web Crypto's `subtle.digest` for the sha256 call,
+ * which we already use for every other hashing operation in the core.
+ *
+ * The hash chain property works like this:
+ *
+ *   hash(entry[i])       = sha256(canonicalJSON(entry[i]))
+ *   entry[i+1].prevHash  = hash(entry[i])
+ *
+ * Any modification to `entry[i]` (field values, field order, whitespace)
+ * produces a different `hash(entry[i])`, which means `entry[i+1]`'s
+ * stored `prevHash` no longer matches the recomputed hash, which means
+ * `verify()` returns `{ ok: false, divergedAt: i + 1 }`. The chain is
+ * append-only and tamper-evident without external anchoring.
+ */
+/**
+ * A single ledger entry in its plaintext form — what gets serialized,
+ * hashed, and then encrypted with the ledger DEK before being written
+ * to the `_ledger/` adapter collection.
+ *
+ * ## Why hash the ciphertext, not the plaintext?
+ *
+ * `payloadHash` is the sha256 of the record's ENCRYPTED envelope bytes,
+ * not its plaintext. This matters:
+ *
+ *   1. **Zero-knowledge preserved.** A user (or a third party) can
+ *      verify the ledger against the stored envelopes without any
+ *      decryption keys. The adapter layer already holds only
+ *      ciphertext, so hashing the ciphertext keeps the ledger at the
+ *      same privacy level as the adapter.
+ *
+ *   2. **Determinism.** Plaintext → ciphertext is randomized by the
+ *      fresh per-write IV, so `hash(plaintext)` would need extra
+ *      normalization. `hash(ciphertext)` is already deterministic and
+ *      unique per write.
+ *
+ *   3. **Detection property.** If an attacker modifies even one byte of
+ *      the stored ciphertext (trying to flip a record), the hash
+ *      changes, the ledger's recorded `payloadHash` no longer matches,
+ *      and a data-integrity check fails. We don't do that check in
+ *      `verify()` today (v0.4 only checks chain consistency), but the
+ *      hook is there for a future `verifyIntegrity()` follow-up.
+ *
+ * Fields marked `op`, `collection`, `id`, `version`, `ts`, `actor` are
+ * plaintext METADATA about the operation — NOT the record itself. The
+ * entry is still encrypted at rest via the ledger DEK, but adapters
+ * could theoretically infer operation patterns from the sizes and
+ * timestamps. This is an accepted trade-off for the tamper-evidence
+ * property; full ORAM-level privacy is out of scope for noy-db.
+ */
+interface LedgerEntry {
+    /**
+     * Zero-based sequential position of this entry in the chain. The
+     * canonical adapter key is this number zero-padded to 10 digits
+     * (`"0000000001"`) so lexicographic ordering matches numeric order.
+     */
+    readonly index: number;
+    /**
+     * Hex-encoded sha256 of the canonical JSON of the PREVIOUS entry.
+     * The genesis entry (index 0) has `prevHash === ''` — the first
+     * entry in a fresh compartment has nothing to point back to.
+     */
+    readonly prevHash: string;
+    /**
+     * Which kind of mutation this entry records. v0.4 only supports
+     * data operations (`put`, `delete`). Access-control operations
+     * (`grant`, `revoke`, `rotate`) will be added in a follow-up once
+     * the keyring write path is instrumented — that's tracked in the
+     * v0.4 epic issue.
+     */
+    readonly op: 'put' | 'delete';
+    /** The collection the mutation targeted. */
+    readonly collection: string;
+    /** The record id the mutation targeted. */
+    readonly id: string;
+    /**
+     * The record version AFTER this mutation. For `put` this is the
+     * newly assigned version; for `delete` this is the version that
+     * was deleted (the last version visible to reads).
+     */
+    readonly version: number;
+    /** ISO timestamp of the mutation. */
+    readonly ts: string;
+    /** User id of the actor who performed the mutation. */
+    readonly actor: string;
+    /**
+     * Hex-encoded sha256 of the encrypted envelope's `_data` field.
+     * For `put`, this is the hash of the new ciphertext. For `delete`,
+     * it's the hash of the last visible ciphertext at deletion time,
+     * or the empty string if nothing was there to delete. Hashing the
+     * ciphertext (not the plaintext) preserves zero-knowledge — see
+     * the file docstring.
+     */
+    readonly payloadHash: string;
+    /**
+     * Optional hex-encoded sha256 of the encrypted JSON Patch delta
+     * blob stored alongside this entry in `_ledger_deltas/`. Present
+     * only for `put` operations that had a previous version — the
+     * genesis put of a new record, and every `delete`, leave this
+     * field undefined.
+     *
+     * The delta payload itself lives in a sibling internal collection
+     * (`_ledger_deltas/<paddedIndex>`) and is encrypted with the
+     * ledger DEK. Callers use `ledger.loadDelta(index)` to decrypt and
+     * deserialize it when reconstructing a historical version.
+     *
+     * Why optional instead of always-present: the first put of a
+     * record has no previous version to diff against, so storing an
+     * empty patch would be noise. For deletes there's no "next" state
+     * to describe with a delta. Both cases set this field to undefined.
+     *
+     * Note: the canonical-JSON hasher treats `undefined` as invalid
+     * (it's one of the guard rails), so on the wire this field is
+     * either `{ deltaHash: '<hex>' }` or absent from the JSON
+     * entirely — never `{ deltaHash: undefined }`.
+     */
+    readonly deltaHash?: string;
+}
+/**
+ * Canonical (sort-stable) JSON encoder.
+ *
+ * This function is the load-bearing primitive of the hash chain:
+ * `sha256(canonicalJSON(entry))` must produce the same hex string
+ * every time, on every machine, for the same logical entry — otherwise
+ * `verify()` would return `{ ok: false }` on cross-platform reads.
+ *
+ * JavaScript's `JSON.stringify` is almost canonical, but NOT quite:
+ * it preserves the insertion order of object keys, which means
+ * `{a:1,b:2}` and `{b:2,a:1}` serialize differently. We fix this by
+ * recursively walking objects and sorting their keys before
+ * concatenation.
+ *
+ * Arrays keep their original order (reordering them would change
+ * semantics). Numbers, strings, booleans, and `null` use the default
+ * JSON encoding. `undefined` and functions are rejected — ledger
+ * entries are plain data, and silently dropping `undefined` would
+ * break the "same input → same hash" property if a caller forgot to
+ * omit a field.
+ *
+ * Performance: one pass per nesting level; O(n log n) for key sorting
+ * at each object. Entries are small (< 1 KB) so this is negligible
+ * compared to the sha256 call.
+ */
+declare function canonicalJson(value: unknown): string;
+/**
+ * Compute a hex-encoded sha256 of a string via Web Crypto's subtle API.
+ *
+ * We use hex (not base64) for hashes because hex is case-insensitive,
+ * fixed-length (64 chars), and easier to compare visually in debug
+ * output. Base64 would save a few bytes in storage but every encrypted
+ * ledger entry is already much larger than the hash itself.
+ */
+declare function sha256Hex(input: string): Promise<string>;
+/**
+ * Compute the canonical hash of a ledger entry. Short wrapper around
+ * `canonicalJson` + `sha256Hex`; callers use this instead of composing
+ * the two functions every time, so any future change to the hashing
+ * pipeline (e.g., adding a domain-separation prefix) lives in one place.
+ */
+declare function hashEntry(entry: LedgerEntry): Promise<string>;
+/**
+ * Pad an index to the canonical 10-digit form used as the adapter key.
+ * Ten digits is enough for ~10 billion ledger entries per compartment
+ * — far beyond any realistic use case, but cheap enough that the extra
+ * digits don't hurt storage.
+ */
+declare function paddedIndex(index: number): string;
+/** Parse a padded adapter key back into a number. Returns NaN on malformed input. */
+declare function parseIndex(key: string): number;
+
+/**
+ * RFC 6902 JSON Patch — compute + apply.
+ *
+ * This module is the v0.4 "delta history" primitive: instead of
+ * snapshotting the full record on every put (the v0.3 behavior),
+ * `Collection.put` computes a JSON Patch from the previous version to
+ * the new version and stores only the patch in the ledger. To
+ * reconstruct version N, we walk from the genesis snapshot forward
+ * applying patches. Storage scales with **edit size**, not record
+ * size — a 10 KB record edited 1000 times costs ~10 KB of deltas
+ * instead of ~10 MB of snapshots.
+ *
+ * ## Why hand-roll instead of using a library?
+ *
+ * RFC 6902 has good libraries (`fast-json-patch`, `rfc6902`) but every
+ * single one of them adds a runtime dependency to `@noy-db/core`. The
+ * "zero runtime dependencies" promise is one of the core's load-bearing
+ * features, and the patch surface we actually need is small enough
+ * (~150 LoC) that vendoring is the right call.
+ *
+ * What we implement:
+ *   - `add`     — insert a value at a path
+ *   - `remove`  — delete the value at a path
+ *   - `replace` — overwrite the value at a path
+ *
+ * What we deliberately skip (out of scope for the v0.4 ledger use):
+ *   - `move` and `copy` — optimizations; the diff algorithm doesn't
+ *     emit them, so the apply path doesn't need them
+ *   - `test` — used for transactional patches; we already have
+ *     optimistic concurrency via `_v` at the envelope layer
+ *   - Sophisticated array diffing (LCS, edit distance) — we treat
+ *     arrays as atomic values and emit a single `replace` op when
+ *     they differ. The accounting domain has small arrays where this
+ *     is fine; if we ever need patch-level array diffing we can add
+ *     it without changing the storage format.
+ *
+ * ## Path encoding (RFC 6902 §3)
+ *
+ * Paths look like `/foo/bar/0`. Each path segment is either an object
+ * key or a numeric array index. Two characters need escaping inside
+ * keys: `~` becomes `~0` and `/` becomes `~1`. We implement both.
+ *
+ * Empty path (`""`) refers to the root document. Only `replace` makes
+ * sense at the root, and our diff function emits it as a top-level
+ * `replace` when `prev` and `next` differ in shape (object vs array,
+ * primitive vs object, etc.).
+ */
+/** A single JSON Patch operation. Subset of RFC 6902 — see file docstring. */
+type JsonPatchOp = {
+    readonly op: 'add';
+    readonly path: string;
+    readonly value: unknown;
+} | {
+    readonly op: 'remove';
+    readonly path: string;
+} | {
+    readonly op: 'replace';
+    readonly path: string;
+    readonly value: unknown;
+};
+/** A complete JSON Patch document — an array of operations. */
+type JsonPatch = readonly JsonPatchOp[];
+/**
+ * Compute a JSON Patch that, when applied to `prev`, produces `next`.
+ *
+ * The algorithm is a straightforward recursive object walk:
+ *
+ *   1. If both inputs are plain objects (and not arrays/null):
+ *      - For each key in `prev`, recurse if `next` has it, else emit `remove`
+ *      - For each key in `next` not in `prev`, emit `add`
+ *   2. If both inputs are arrays AND structurally equal, no-op.
+ *      Otherwise emit a single `replace` for the whole array.
+ *   3. If both inputs are deeply equal primitives, no-op.
+ *   4. Otherwise emit a `replace` at the current path.
+ *
+ * We do not minimize patches across move-like rearrangements — every
+ * generated patch is straightforward enough to apply by hand if you
+ * had to debug it.
+ */
+declare function computePatch(prev: unknown, next: unknown): JsonPatch;
+/**
+ * Apply a JSON Patch to a base document and return the result.
+ *
+ * The base document is **not mutated** — every op clones the parent
+ * container before writing to it, so the caller's reference to `base`
+ * stays untouched. This costs an extra allocation per op but makes
+ * the apply pipeline reorderable and safe to interrupt.
+ *
+ * Throws on:
+ *   - Removing a path that doesn't exist
+ *   - Adding to a path whose parent doesn't exist
+ *   - A path component that doesn't match the document shape (e.g.,
+ *     trying to step into a primitive)
+ *
+ * Throwing is the right behavior for the ledger use case: a failed
+ * apply means the chain is corrupted, which should be loud rather
+ * than silently producing a wrong reconstruction.
+ */
+declare function applyPatch<T = unknown>(base: T, patch: JsonPatch): T;
+
+/**
+ * `LedgerStore` — read/write access to a compartment's hash-chained
+ * audit log.
+ *
+ * The store is a thin wrapper around the adapter's `_ledger/` internal
+ * collection. Every append:
+ *
+ *   1. Loads the current head (or treats an empty ledger as head = -1)
+ *   2. Computes `prevHash` = sha256(canonicalJson(head))
+ *   3. Builds the new entry with `index = head.index + 1`
+ *   4. Encrypts the entry with the compartment's ledger DEK
+ *   5. Writes the encrypted envelope to `_ledger/<paddedIndex>`
+ *
+ * `verify()` walks the chain from genesis forward and returns
+ * `{ ok: true, head }` on success or `{ ok: false, divergedAt }` on the
+ * first broken link.
+ *
+ * ## Thread / concurrency model
+ *
+ * For v0.4 we assume a **single writer per compartment**. Two
+ * concurrent `append()` calls would race on the "read head, write
+ * head+1" cycle and could produce a broken chain. The v0.3 sync engine
+ * is the primary concurrent-writer scenario, and it uses
+ * optimistic-concurrency via `expectedVersion` on the adapter — but
+ * the ledger path has no such guard today. Multi-writer hardening is a
+ * v0.5 follow-up.
+ *
+ * Single-writer usage IS safe, including across process restarts:
+ * `head()` reads the adapter fresh each call, so a crash between the
+ * adapter.put of a data record and the ledger append just means the
+ * ledger is missing an entry for that record. `verify()` still
+ * succeeds; a future `verifyIntegrity()` helper can cross-check the
+ * ledger against the data collections to catch the gap.
+ *
+ * ## Why hide the ledger from `compartment.collection()`?
+ *
+ * The `_ledger` name starts with `_`, matching the existing prefix
+ * convention for internal collections (`_keyring`, `_sync`,
+ * `_history`). The Compartment's public `collection()` method already
+ * returns entries for any name, but `loadAll()` filters out
+ * underscore-prefixed collections so backups and exports don't leak
+ * ledger metadata. We keep the ledger accessible ONLY via
+ * `compartment.ledger()` to enforce the hash-chain invariants — direct
+ * puts via `collection('_ledger')` would bypass the `append()` logic.
+ */
+
+/** The internal collection name used for ledger entry storage. */
+declare const LEDGER_COLLECTION = "_ledger";
+/**
+ * The internal collection name used for delta payload storage.
+ *
+ * Deltas live in a sibling collection (not inside `_ledger`) for two
+ * reasons:
+ *
+ *   1. **Listing efficiency.** `ledger.loadAllEntries()` calls
+ *      `adapter.list(_ledger)` which would otherwise return every
+ *      delta key alongside every entry key. Splitting them keeps the
+ *      list small (one key per ledger entry) and the delta reads
+ *      keyed by the entry's index.
+ *
+ *   2. **Prune-friendliness.** A future `pruneHistory()` will delete
+ *      old deltas while keeping the ledger chain intact (folding old
+ *      deltas into a base snapshot). Separating the storage makes
+ *      that deletion a targeted operation on one collection instead
+ *      of a filter across a mixed list.
+ *
+ * Both collections share the same ledger DEK — one DEK, two
+ * internal collections, same zero-knowledge guarantees.
+ */
+declare const LEDGER_DELTAS_COLLECTION = "_ledger_deltas";
+/**
+ * Input shape for `LedgerStore.append()`. The caller supplies the
+ * operation metadata; the store fills in `index` and `prevHash`.
+ */
+interface AppendInput {
+    op: LedgerEntry['op'];
+    collection: string;
+    id: string;
+    version: number;
+    actor: string;
+    payloadHash: string;
+    /**
+     * Optional JSON Patch representing the delta from the previous
+     * version to the new version. Present only for `put` operations
+     * that had a previous version; omitted for genesis puts and for
+     * deletes. When present, `LedgerStore.append` persists the patch
+     * in `_ledger_deltas/<paddedIndex>` and records its sha256 hash
+     * as the entry's `deltaHash` field.
+     */
+    delta?: JsonPatch;
+}
+/**
+ * Result of `LedgerStore.verify()`. On success, `head` is the hash of
+ * the last entry — the same value that should be published to any
+ * external anchoring service (blockchain, OpenTimestamps, etc.). On
+ * failure, `divergedAt` is the 0-based index of the first entry whose
+ * recorded `prevHash` does not match the recomputed hash of its
+ * predecessor. Entries at `divergedAt` and later are untrustworthy;
+ * entries before that index are still valid.
+ */
+type VerifyResult = {
+    readonly ok: true;
+    readonly head: string;
+    readonly length: number;
+} | {
+    readonly ok: false;
+    readonly divergedAt: number;
+    readonly expected: string;
+    readonly actual: string;
+};
+/**
+ * A LedgerStore is bound to a single compartment. Callers obtain one
+ * via `compartment.ledger()` — there is no public constructor to keep
+ * the hash-chain invariants in one place.
+ *
+ * The class holds no mutable state beyond its dependencies (adapter,
+ * compartment name, DEK resolver, actor id). Every method reads the
+ * adapter fresh so multiple instances against the same compartment
+ * see each other's writes immediately (at the cost of re-parsing the
+ * ledger on every head() / verify() call; acceptable at v0.4 scale).
+ */
+declare class LedgerStore {
+    private readonly adapter;
+    private readonly compartment;
+    private readonly encrypted;
+    private readonly getDEK;
+    private readonly actor;
+    /**
+     * In-memory cache of the chain head — the most recently appended
+     * entry along with its precomputed hash. Without this, every
+     * `append()` would re-load every prior entry to recompute the
+     * prevHash, making N puts O(N²) — a 1K-record stress test goes from
+     * < 100ms to a multi-second timeout.
+     *
+     * The cache is populated on first read (`append`, `head`, `verify`)
+     * and updated in-place on every successful `append`. Single-writer
+     * usage (the v0.4 assumption) keeps it consistent. A second
+     * LedgerStore instance writing to the same compartment would not
+     * see the first instance's appends in its cached state — that's the
+     * concurrency caveat documented at the class level.
+     *
+     * Sentinel `undefined` means "not yet loaded"; an explicit `null`
+     * value means "loaded and confirmed empty" — distinguishing these
+     * matters because an empty ledger is a valid state (genesis prevHash
+     * is the empty string), and we don't want to re-scan the adapter
+     * just because the chain is freshly initialized.
+     */
+    private headCache;
+    constructor(opts: {
+        adapter: NoydbAdapter;
+        compartment: string;
+        encrypted: boolean;
+        getDEK: (collectionName: string) => Promise<CryptoKey>;
+        actor: string;
+    });
+    /**
+     * Lazily load (or return cached) the current chain head. The cache
+     * sentinel is `undefined` until first access; after the first call,
+     * the cache holds either a `{ entry, hash }` for non-empty ledgers
+     * or `null` for empty ones.
+     */
+    private getCachedHead;
+    /**
+     * Append a new entry to the ledger. Returns the full entry that was
+     * written (with its assigned index and computed prevHash) so the
+     * caller can use the hash for downstream purposes (e.g., embedding
+     * in a verifiable backup).
+     *
+     * This is the **only** way to add entries. Direct adapter writes to
+     * `_ledger/` would bypass the chain math and would be caught by the
+     * next `verify()` call as a divergence.
+     */
+    append(input: AppendInput): Promise<LedgerEntry>;
+    /**
+     * Load a delta payload by its entry index. Returns `null` if the
+     * entry at that index doesn't reference a delta (genesis puts and
+     * deletes leave the slot empty) or if the delta row is missing
+     * (possible after a `pruneHistory` fold).
+     *
+     * The caller is responsible for deciding what to do with a missing
+     * delta — `ledger.reconstruct()` uses it as a "stop walking
+     * backward" signal and falls back to the on-disk current value.
+     */
+    loadDelta(index: number): Promise<JsonPatch | null>;
+    /** Encrypt a JSON Patch into an envelope for storage. Mirrors encryptEntry. */
+    private encryptDelta;
+    /**
+     * Read all entries in ascending-index order. Used internally by
+     * `append()`, `head()`, `verify()`, and `entries()`. Decryption is
+     * serial because the entries are tiny and the overhead of a Promise
+     * pool would dominate at realistic chain lengths (< 100K entries).
+     */
+    loadAllEntries(): Promise<LedgerEntry[]>;
+    /**
+     * Return the current head of the ledger: the last entry, its hash,
+     * and the total chain length. `null` on an empty ledger so callers
+     * can distinguish "no history yet" from "empty history".
+     */
+    head(): Promise<{
+        readonly entry: LedgerEntry;
+        readonly hash: string;
+        readonly length: number;
+    } | null>;
+    /**
+     * Return entries in the requested half-open range `[from, to)`.
+     * Defaults: `from = 0`, `to = length`. The indices are clipped to
+     * the valid range; no error is thrown for out-of-range queries.
+     */
+    entries(opts?: {
+        from?: number;
+        to?: number;
+    }): Promise<LedgerEntry[]>;
+    /**
+     * Reconstruct a record's state at a given historical version by
+     * walking the ledger's delta chain backward from the current state.
+     *
+     * ## Algorithm
+     *
+     * Ledger deltas are stored in **reverse** form — each entry's
+     * patch describes how to undo that put, transforming the new
+     * record back into the previous one. `reconstruct` exploits this
+     * by:
+     *
+     *   1. Finding every ledger entry for `(collection, id)` in the
+     *      chain, sorted by index ascending.
+     *   2. Starting from `current` (the present value of the record,
+     *      as held by the caller — typically fetched via
+     *      `Collection.get()`).
+     *   3. Walking entries in **descending** index order and applying
+     *      each entry's reverse patch, stopping when we reach the
+     *      entry whose version equals `atVersion`.
+     *
+     * The result is the record as it existed immediately AFTER the
+     * put at `atVersion`. To get the state at the genesis put
+     * (version 1), the walk runs all the way back through every put
+     * after the first.
+     *
+     * ## Caveats
+     *
+     * - **Delete entries** break the walk: once we see a delete, the
+     *   record didn't exist before that point, so there's nothing to
+     *   reconstruct. We return `null` in that case.
+     * - **Missing deltas** (e.g., after `pruneHistory` folds old
+     *   entries into a base snapshot) also stop the walk. v0.4 does
+     *   not ship pruneHistory, so today this only happens if an entry
+     *   was deleted out-of-band.
+     * - The caller MUST pass the correct current value. Passing a
+     *   mutated object would corrupt the reconstruction — the patch
+     *   chain is only valid against the exact state that was in
+     *   effect when the most recent put happened.
+     *
+     * For v0.4, `reconstruct` is the only way to read a historical
+     * version via deltas. The legacy `_history` collection still
+     * holds full snapshots and `Collection.getVersion()` still reads
+     * from there — the two paths coexist until pruneHistory lands in
+     * a follow-up and delta becomes the default.
+     */
+    reconstruct<T>(collection: string, id: string, current: T, atVersion: number): Promise<T | null>;
+    /**
+     * Walk the chain from genesis forward and verify every link.
+     *
+     * Returns `{ ok: true, head, length }` if every entry's `prevHash`
+     * matches the recomputed hash of its predecessor (and the genesis
+     * entry's `prevHash` is the empty string).
+     *
+     * Returns `{ ok: false, divergedAt, expected, actual }` on the first
+     * mismatch. `divergedAt` is the 0-based index of the BROKEN entry
+     * — entries before that index still verify cleanly; entries at and
+     * after `divergedAt` are untrustworthy.
+     *
+     * This method detects:
+     *   - Mutated entry content (fields changed)
+     *   - Reordered entries (if any adjacent pair swaps, the prevHash
+     *     of the second no longer matches)
+     *   - Inserted entries (the inserted entry's prevHash likely fails,
+     *     and the following entry's prevHash definitely fails)
+     *   - Deleted entries (the entry after the deletion sees a wrong
+     *     prevHash)
+     *
+     * It does NOT detect:
+     *   - Tampering with the DATA collections that bypassed the ledger
+     *     entirely (e.g., an attacker who modifies records without
+     *     appending matching ledger entries — this is why we also
+     *     plan a `verifyIntegrity()` helper in a follow-up)
+     *   - Truncation of the chain at the tail (dropping the last N
+     *     entries leaves a shorter but still consistent chain). External
+     *     anchoring of `head.hash` to a trusted service is the defense
+     *     against this.
+     */
+    verify(): Promise<VerifyResult>;
+    /**
+     * Serialize + encrypt a ledger entry into an EncryptedEnvelope. The
+     * envelope's `_v` field is set to `entry.index + 1` so the usual
+     * optimistic-concurrency machinery has a reasonable version number
+     * to compare against (the ledger is append-only, so concurrent
+     * writes should always bump the index).
+     */
+    private encryptEntry;
+    /** Decrypt an envelope into a LedgerEntry. Throws on bad key / tamper. */
+    private decryptEntry;
+}
+/**
+ * Compute the `payloadHash` value for an encrypted envelope. Pulled
+ * out as a standalone helper because both `put` (hash the new
+ * envelope's `_data`) and `delete` (hash the previous envelope's
+ * `_data`) need the same calculation, and the logic is small enough
+ * that duplicating it would be noise.
+ */
+declare function envelopePayloadHash(envelope: EncryptedEnvelope | null): Promise<string>;
+
+/**
+ * Foreign-key references — the v0.4 soft-FK mechanism.
+ *
+ * A collection declares its references as metadata at construction
+ * time:
+ *
+ * ```ts
+ * import { ref } from '@noy-db/core'
+ *
+ * const invoices = company.collection<Invoice>('invoices', {
+ *   refs: {
+ *     clientId: ref('clients'),            // default: strict
+ *     categoryId: ref('categories', 'warn'),
+ *     parentId:  ref('invoices', 'cascade'), // self-reference OK
+ *   },
+ * })
+ * ```
+ *
+ * Three modes:
+ *
+ *   - **strict** — the default. `put()` rejects records whose
+ *     reference target doesn't exist, and `delete()` of the target
+ *     rejects if any strict-referencing records still exist.
+ *     Matches SQL's default FK semantics.
+ *
+ *   - **warn** — both operations succeed unconditionally. Broken
+ *     references surface only through
+ *     `compartment.checkIntegrity()`, which walks every collection
+ *     and reports orphans. Use when you want soft validation for
+ *     imports from messy sources.
+ *
+ *   - **cascade** — `put()` is same as warn. `delete()` of the
+ *     target deletes every referencing record. Cycles are detected
+ *     and broken via an in-progress set, so mutual cascades
+ *     terminate instead of recursing forever.
+ *
+ * Cross-compartment refs are explicitly rejected: if the target
+ * name contains a `/`, `ref()` throws `RefScopeError`. Cross-
+ * compartment refs need an auth story (multi-keyring reads) that
+ * v0.4 doesn't ship — tracked for v0.5.
+ */
+
+/** The three enforcement modes. Default for new refs is `'strict'`. */
+type RefMode = 'strict' | 'warn' | 'cascade';
+/**
+ * Descriptor returned by `ref()`. Collections accept a
+ * `Record<string, RefDescriptor>` in their options. The key is the
+ * field name on the record (top-level only — dotted paths are out of
+ * scope for v0.4), the value describes which target collection the
+ * field references and under what mode.
+ *
+ * The descriptor carries only plain data so it can be serialized,
+ * passed around, and introspected without any class machinery.
+ */
+interface RefDescriptor {
+    readonly target: string;
+    readonly mode: RefMode;
+}
+/**
+ * Thrown when a strict reference is violated — either `put()` with a
+ * missing target id, or `delete()` of a target that still has
+ * strict-referencing records.
+ *
+ * Carries structured detail so UI code (and a potential future
+ * devtools panel) can render "client X cannot be deleted because
+ * invoices 1, 2, and 3 reference it" instead of a bare error string.
+ */
+declare class RefIntegrityError extends NoydbError {
+    readonly collection: string;
+    readonly id: string;
+    readonly field: string;
+    readonly refTo: string;
+    readonly refId: string | null;
+    constructor(opts: {
+        collection: string;
+        id: string;
+        field: string;
+        refTo: string;
+        refId: string | null;
+        message: string;
+    });
+}
+/**
+ * Thrown when `ref()` is called with a target name that looks like
+ * a cross-compartment reference (contains a `/`). Separate error
+ * class because the fix is different: RefIntegrityError means "data
+ * is wrong"; RefScopeError means "the ref declaration is wrong".
+ */
+declare class RefScopeError extends NoydbError {
+    constructor(target: string);
+}
+/**
+ * Helper constructor. Thin wrapper around the object literal so user
+ * code reads like `ref('clients')` instead of `{ target: 'clients',
+ * mode: 'strict' }` — this is the only ergonomics reason it exists.
+ *
+ * Validates the target name eagerly so a misconfigured ref declaration
+ * fails at collection construction time, not at the first put.
+ */
+declare function ref(target: string, mode?: RefMode): RefDescriptor;
+/**
+ * Per-compartment registry of reference declarations.
+ *
+ * The registry is populated by `Collection` constructors (which pass
+ * their `refs` option through the Compartment) and consulted by the
+ * Compartment on every `put` / `delete` and by `checkIntegrity`. A
+ * single instance lives on the Compartment for its lifetime; there's
+ * no global state.
+ *
+ * The data structure is two parallel maps:
+ *
+ *   - `outbound`: `collection → { field → RefDescriptor }` — what
+ *     refs does `collection` declare? Used on put to check
+ *     strict-target-exists and on checkIntegrity to walk each
+ *     collection's outbound refs.
+ *
+ *   - `inbound`:  `target → Array<{ collection, field, mode }>` —
+ *     which collections reference `target`? Used on delete to find
+ *     the records that might be affected by cascade / strict.
+ *
+ * The two views are kept in sync by `register()` and never mutated
+ * otherwise — refs can't be unregistered at runtime in v0.4.
+ */
+declare class RefRegistry {
+    private readonly outbound;
+    private readonly inbound;
+    /**
+     * Register the refs declared by a single collection. Idempotent in
+     * the happy path — calling twice with the same data is a no-op.
+     * Calling twice with DIFFERENT data throws, because silent
+     * overrides would be confusing ("I changed the ref and it doesn't
+     * update" vs "I declared the same collection twice with different
+     * refs and the second call won").
+     */
+    register(collection: string, refs: Record<string, RefDescriptor>): void;
+    /** Get the outbound refs declared by a collection (or `{}` if none). */
+    getOutbound(collection: string): Record<string, RefDescriptor>;
+    /** Get the inbound refs that target a given collection (or `[]`). */
+    getInbound(target: string): ReadonlyArray<{
+        collection: string;
+        field: string;
+        mode: RefMode;
+    }>;
+    /**
+     * Iterate every (collection → refs) pair that has at least one
+     * declared reference. Used by `checkIntegrity` to walk the full
+     * universe of outbound refs without needing to track collection
+     * names elsewhere.
+     */
+    entries(): Array<[string, Record<string, RefDescriptor>]>;
+    /** Clear the registry. Test-only escape hatch; never called from production code. */
+    clear(): void;
+}
+/**
+ * Shape of a single violation reported by `compartment.checkIntegrity()`.
+ *
+ * `refId` is the value we saw in the referencing field — it's the
+ * ID we expected to find in `refTo`, but didn't. Left as `unknown`
+ * because records are loosely typed at the integrity-check layer.
+ */
+interface RefViolation {
+    readonly collection: string;
+    readonly id: string;
+    readonly field: string;
+    readonly refTo: string;
+    readonly refId: unknown;
+    readonly mode: RefMode;
+}
 
 /** In-memory representation of an unlocked keyring. */
 interface UnlockedKeyring {
@@ -282,8 +1295,394 @@ declare function diff(oldObj: unknown, newObj: unknown, basePath?: string): Diff
 /** Format a diff as a human-readable string. */
 declare function formatDiff(changes: DiffEntry[]): string;
 
+/**
+ * Operator implementations for the query DSL.
+ *
+ * All predicates run client-side, AFTER decryption — they never see ciphertext.
+ * This file is dependency-free and tree-shakeable.
+ */
+/** Comparison operators supported by the where() builder. */
+type Operator = '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | 'contains' | 'startsWith' | 'between';
+/**
+ * A single field comparison clause inside a query plan.
+ * Plans are JSON-serializable, so this type uses primitives only.
+ */
+interface FieldClause {
+    readonly type: 'field';
+    readonly field: string;
+    readonly op: Operator;
+    readonly value: unknown;
+}
+/**
+ * A user-supplied predicate function escape hatch. Not serializable.
+ *
+ * The predicate accepts `unknown` at the type level so the surrounding
+ * Clause type can stay non-parametric — this keeps Collection<T> covariant
+ * in T at the public API surface. Builder methods cast user predicates
+ * (typed `(record: T) => boolean`) into this shape on the way in.
+ */
+interface FilterClause {
+    readonly type: 'filter';
+    readonly fn: (record: unknown) => boolean;
+}
+/** A logical group of clauses combined by AND or OR. */
+interface GroupClause {
+    readonly type: 'group';
+    readonly op: 'and' | 'or';
+    readonly clauses: readonly Clause[];
+}
+type Clause = FieldClause | FilterClause | GroupClause;
+/**
+ * Read a possibly nested field path like "address.city" from a record.
+ * Returns undefined if any segment is missing.
+ */
+declare function readPath(record: unknown, path: string): unknown;
+/**
+ * Evaluate a single field clause against a record.
+ * Returns false on type mismatches rather than throwing — query results
+ * exclude non-matching records by definition.
+ */
+declare function evaluateFieldClause(record: unknown, clause: FieldClause): boolean;
+/**
+ * Evaluate any clause (field / filter / group) against a record.
+ * The recursion depth is bounded by the user's query expression — no risk of
+ * blowing the stack on a 50K-record collection.
+ */
+declare function evaluateClause(record: unknown, clause: Clause): boolean;
+
+/**
+ * Secondary indexes for the query DSL.
+ *
+ * v0.3 ships **in-memory hash indexes**:
+ *   - Built during `Collection.ensureHydrated()` from the decrypted cache
+ *   - Maintained incrementally on `put` and `delete`
+ *   - Consulted by the query executor for `==` and `in` operators on
+ *     indexed fields, falling back to a linear scan otherwise
+ *   - Live entirely in memory — no adapter writes for the index itself
+ *
+ * Persistent encrypted index blobs (the spec's "store as a separate
+ * AES-256-GCM blob" note) are deferred to a follow-up issue. The reasons
+ * are documented in the v0.3 PR body — short version: at the v0.3 target
+ * scale of 1K–50K records, building the index during hydrate is free,
+ * so persistence buys nothing measurable.
+ */
+/**
+ * Index declaration accepted by `Collection`'s constructor.
+ *
+ * Today only single-field hash indexes are supported. Future shapes
+ * (composite, sorted, unique constraints) will land as additive variants
+ * of this discriminated union without breaking existing declarations.
+ */
+type IndexDef = string;
+/**
+ * Internal representation of a built hash index.
+ *
+ * Maps stringified field values to the set of record ids whose value
+ * for that field matches. Stringification keeps the index simple and
+ * works uniformly for primitives (`'open'`, `'42'`, `'true'`).
+ *
+ * Records whose indexed field is `undefined` or `null` are NOT inserted
+ * — `query().where('field', '==', undefined)` falls back to a linear
+ * scan, which is the conservative behavior.
+ */
+interface HashIndex {
+    readonly field: string;
+    readonly buckets: Map<string, Set<string>>;
+}
+/**
+ * Container for all indexes on a single collection.
+ *
+ * Methods are pure with respect to the in-memory `buckets` Map — they
+ * never touch the adapter or the keyring. The Collection class owns
+ * lifecycle (build on hydrate, maintain on put/delete).
+ */
+declare class CollectionIndexes {
+    private readonly indexes;
+    /**
+     * Declare an index. Subsequent record additions are tracked under it.
+     * Calling this twice for the same field is a no-op (idempotent).
+     */
+    declare(field: string): void;
+    /** True if the given field has a declared index. */
+    has(field: string): boolean;
+    /** All declared field names, in declaration order. */
+    fields(): string[];
+    /**
+     * Build all declared indexes from a snapshot of records.
+     * Called once per hydration. O(N × indexes.size).
+     */
+    build<T>(records: ReadonlyArray<{
+        id: string;
+        record: T;
+    }>): void;
+    /**
+     * Insert or update a single record across all indexes.
+     * Called by `Collection.put()` after the encrypted write succeeds.
+     *
+     * If `previousRecord` is provided, the record is removed from any old
+     * buckets first — this is the update path. Pass `null` for fresh adds.
+     */
+    upsert<T>(id: string, newRecord: T, previousRecord: T | null): void;
+    /**
+     * Remove a record from all indexes. Called by `Collection.delete()`
+     * (and as the first half of `upsert` for the update path).
+     */
+    remove<T>(id: string, record: T): void;
+    /** Drop all index data. Called when the collection is invalidated. */
+    clear(): void;
+    /**
+     * Equality lookup: return the set of record ids whose `field` matches
+     * the given value. Returns `null` if no index covers the field — the
+     * caller should fall back to a linear scan.
+     *
+     * The returned Set is a reference to the index's internal storage —
+     * callers must NOT mutate it.
+     */
+    lookupEqual(field: string, value: unknown): ReadonlySet<string> | null;
+    /**
+     * Set lookup: return the union of record ids whose `field` matches any
+     * of the given values. Returns `null` if no index covers the field.
+     */
+    lookupIn(field: string, values: readonly unknown[]): ReadonlySet<string> | null;
+}
+
+/**
+ * Chainable, immutable query builder.
+ *
+ * Each builder operation returns a NEW Query — the underlying plan is never
+ * mutated. This makes plans safe to share, cache, and serialize.
+ */
+
+interface OrderBy {
+    readonly field: string;
+    readonly direction: 'asc' | 'desc';
+}
+/**
+ * A complete query plan: zero-or-more clauses, optional ordering, pagination.
+ * Plans are JSON-serializable as long as no FilterClause is present.
+ *
+ * Plans are intentionally NOT parametric on T — see `predicate.ts` FilterClause
+ * for the variance reasoning. The public `Query<T>` API attaches the type tag.
+ */
+interface QueryPlan {
+    readonly clauses: readonly Clause[];
+    readonly orderBy: readonly OrderBy[];
+    readonly limit: number | undefined;
+    readonly offset: number;
+}
+/**
+ * Source of records that a query executes against.
+ *
+ * The interface is non-parametric to keep variance friendly: callers cast
+ * their typed source (e.g. `QuerySource<Invoice>`) into this opaque shape.
+ *
+ * `getIndexes` and `lookupById` are optional fast-path hooks. When both are
+ * present and a where clause matches an indexed field, the executor uses
+ * the index to skip a linear scan. Sources without these methods (or with
+ * `getIndexes` returning `null`) always fall back to a linear scan.
+ */
+interface QuerySource<T> {
+    /** Snapshot of all current records. The query never mutates this array. */
+    snapshot(): readonly T[];
+    /** Subscribe to mutations; returns an unsubscribe function. */
+    subscribe?(cb: () => void): () => void;
+    /** Index store for the indexed-fast-path. Optional. */
+    getIndexes?(): CollectionIndexes | null;
+    /** O(1) record lookup by id, used to materialize index hits. */
+    lookupById?(id: string): T | undefined;
+}
+/**
+ * The chainable builder. All methods return a new Query — the original
+ * remains unchanged. Terminal methods (`toArray`, `first`, `count`,
+ * `subscribe`) execute the plan against the source.
+ *
+ * Type parameter T flows through the public API for ergonomics, but the
+ * internal storage uses `unknown` so Collection<T> stays covariant.
+ */
+declare class Query<T> {
+    private readonly source;
+    private readonly plan;
+    constructor(source: QuerySource<T>, plan?: QueryPlan);
+    /** Add a field comparison. Multiple where() calls are AND-combined. */
+    where(field: string, op: Operator, value: unknown): Query<T>;
+    /**
+     * Logical OR group. Pass a callback that builds a sub-query.
+     * Each clause inside the callback is OR-combined; the group itself
+     * joins the parent plan with AND.
+     */
+    or(builder: (q: Query<T>) => Query<T>): Query<T>;
+    /**
+     * Logical AND group. Same shape as `or()` but every clause inside the group
+     * must match. Useful for explicit grouping inside a larger OR.
+     */
+    and(builder: (q: Query<T>) => Query<T>): Query<T>;
+    /** Escape hatch: add an arbitrary predicate function. Not serializable. */
+    filter(fn: (record: T) => boolean): Query<T>;
+    /** Sort by a field. Subsequent calls are tie-breakers. */
+    orderBy(field: string, direction?: 'asc' | 'desc'): Query<T>;
+    /** Cap the result size. */
+    limit(n: number): Query<T>;
+    /** Skip the first N matching records (after ordering). */
+    offset(n: number): Query<T>;
+    /** Execute the plan and return the matching records. */
+    toArray(): T[];
+    /** Return the first matching record, or null. */
+    first(): T | null;
+    /** Return the number of matching records (after where/filter, before limit). */
+    count(): number;
+    /**
+     * Re-run the query whenever the source notifies of changes.
+     * Returns an unsubscribe function. The callback receives the latest result.
+     * Throws if the source does not support subscriptions.
+     */
+    subscribe(cb: (result: T[]) => void): () => void;
+    /**
+     * Return the plan as a JSON-friendly object. FilterClause entries are
+     * stripped (their `fn` cannot be serialized) and replaced with
+     * { type: 'filter', fn: '[function]' } so devtools can still see them.
+     */
+    toPlan(): unknown;
+}
+/**
+ * Execute a plan against a snapshot of records.
+ * Pure function — same input, same output, no side effects.
+ *
+ * Records are typed as `unknown` because plans are non-parametric; callers
+ * cast the return type at the API surface (see `Query.toArray()`).
+ */
+declare function executePlan(records: readonly unknown[], plan: QueryPlan): unknown[];
+
+interface LruOptions {
+    /** Maximum number of entries before eviction. Required if `maxBytes` is unset. */
+    maxRecords?: number;
+    /** Maximum total bytes before eviction. Computed from per-entry `size`. */
+    maxBytes?: number;
+}
+interface LruStats {
+    /** Total cache hits since construction (or `resetStats()`). */
+    hits: number;
+    /** Total cache misses since construction (or `resetStats()`). */
+    misses: number;
+    /** Total entries evicted since construction (or `resetStats()`). */
+    evictions: number;
+    /** Current number of cached entries. */
+    size: number;
+    /** Current sum of cached entry sizes (in bytes, approximate). */
+    bytes: number;
+}
+/**
+ * O(1) LRU cache. Both `get()` and `set()` promote the touched entry to
+ * the most-recently-used end. Eviction happens after every insert and
+ * walks the front of the Map iterator dropping entries until both
+ * budgets are satisfied.
+ */
+declare class Lru<K, V> {
+    private readonly entries;
+    private readonly maxRecords;
+    private readonly maxBytes;
+    private currentBytes;
+    private hits;
+    private misses;
+    private evictions;
+    constructor(options: LruOptions);
+    /**
+     * Look up a key. Hits promote the entry to most-recently-used; misses
+     * return undefined. Both update the running stats counters.
+     */
+    get(key: K): V | undefined;
+    /**
+     * Insert or update a key. If the key already exists, its size is
+     * accounted for and the entry is promoted to MRU. After insertion,
+     * eviction runs to maintain both budgets.
+     */
+    set(key: K, value: V, size: number): void;
+    /**
+     * Remove a key without affecting hit/miss stats. Used by `Collection.delete()`.
+     * Returns true if the key was present.
+     */
+    remove(key: K): boolean;
+    /** True if the cache currently holds an entry for the given key. */
+    has(key: K): boolean;
+    /**
+     * Drop every entry. Stats counters survive — call `resetStats()` if you
+     * want a clean slate. Used by `Collection.invalidate()` on key rotation.
+     */
+    clear(): void;
+    /** Reset hit/miss/eviction counters to zero. Does NOT touch entries. */
+    resetStats(): void;
+    /** Snapshot of current cache statistics. Cheap — no copying. */
+    stats(): LruStats;
+    /**
+     * Iterate over all currently-cached values. Order is least-recently-used
+     * first. Used by tests and devtools — production callers should use
+     * `Collection.scan()` instead.
+     */
+    values(): IterableIterator<V>;
+    /**
+     * Walk the cache from the LRU end and drop entries until both budgets
+     * are satisfied. Called after every `set()`. Single pass — entries are
+     * never re-promoted during eviction.
+     */
+    private evictUntilUnderBudget;
+    private overBudget;
+}
+
+/**
+ * Cache policy helpers — parse human-friendly byte budgets into raw numbers.
+ *
+ * Accepted shapes (case-insensitive on suffix):
+ *   number       — interpreted as raw bytes
+ *   '1024'       — string of digits, raw bytes
+ *   '50KB'       — kilobytes (×1024)
+ *   '50MB'       — megabytes (×1024²)
+ *   '1GB'        — gigabytes (×1024³)
+ *
+ * Decimals are accepted (`'1.5GB'` → 1610612736 bytes).
+ *
+ * Anything else throws — better to fail loud at construction time than
+ * to silently treat a typo as 0 bytes (which would evict everything).
+ */
+/** Parse a byte budget into a positive integer number of bytes. */
+declare function parseBytes(input: number | string): number;
+/**
+ * Estimate the in-memory byte size of a decrypted record.
+ *
+ * Uses `JSON.stringify().length` as a stand-in for actual heap usage.
+ * It's a deliberate approximation: real V8 heap size includes pointer
+ * overhead, hidden classes, and string interning that we can't measure
+ * from JavaScript. The JSON length is a stable, monotonic proxy that
+ * costs O(record size) per insert — fine when records are typically
+ * < 1 KB and the cache eviction is the slow path anyway.
+ *
+ * Returns `0` (and the caller must treat it as 1 for accounting) if
+ * stringification throws on circular references; this is documented
+ * but in practice records always come from JSON-decoded envelopes.
+ */
+declare function estimateRecordBytes(record: unknown): number;
+
 /** Callback for dirty tracking (sync engine integration). */
 type OnDirtyCallback = (collection: string, id: string, action: 'put' | 'delete', version: number) => Promise<void>;
+/**
+ * Per-collection cache configuration. Only meaningful when paired with
+ * `prefetch: false` (lazy mode); eager mode keeps the entire decrypted
+ * cache in memory and ignores these bounds.
+ */
+interface CacheOptions {
+    /** Maximum number of records to keep in memory before LRU eviction. */
+    maxRecords?: number;
+    /**
+     * Maximum total decrypted byte size before LRU eviction. Accepts a raw
+     * number or a human-friendly string: `'50KB'`, `'50MB'`, `'1GB'`.
+     * Eviction picks the least-recently-used entry until both budgets
+     * (maxRecords AND maxBytes, if both are set) are satisfied.
+     */
+    maxBytes?: number | string;
+}
+/** Statistics exposed via `Collection.cacheStats()`. */
+interface CacheStats extends LruStats {
+    /** True if this collection is in lazy mode. */
+    lazy: boolean;
+}
 /** A typed collection of records within a compartment. */
 declare class Collection<T> {
     private readonly adapter;
@@ -297,6 +1696,86 @@ declare class Collection<T> {
     private readonly historyConfig;
     private readonly cache;
     private hydrated;
+    /**
+     * Lazy mode flag. `true` when constructed with `prefetch: false`.
+     * In lazy mode the cache is bounded by an LRU and `list()`/`query()`
+     * throw — callers must use `scan()` or per-id `get()` instead.
+     */
+    private readonly lazy;
+    /**
+     * LRU cache for lazy mode. Only allocated when `prefetch: false` is set.
+     * Stores `{ record, version }` entries the same shape as `this.cache`.
+     * Tree-shaking note: importing Collection without setting `prefetch:false`
+     * still pulls in the Lru class today; future bundle-size work could
+     * lazy-import the cache module.
+     */
+    private readonly lru;
+    /**
+     * In-memory secondary indexes for the query DSL.
+     *
+     * Built during `ensureHydrated()` and maintained on every put/delete.
+     * The query executor consults these for `==` and `in` operators on
+     * indexed fields, falling back to a linear scan for unindexed fields
+     * or unsupported operators.
+     *
+     * v0.3 ships in-memory only — persistence as encrypted blobs is a
+     * follow-up. See `query/indexes.ts` for the design rationale.
+     *
+     * Indexes are INCOMPATIBLE with lazy mode in v0.3 — the constructor
+     * rejects the combination because evicted records would silently
+     * disappear from the index without notification.
+     */
+    private readonly indexes;
+    /**
+     * Optional Standard Schema v1 validator. When set, every `put()` runs
+     * the input through `validateSchemaInput` before encryption, and every
+     * record coming OUT of `decryptRecord` runs through
+     * `validateSchemaOutput`. A rejected input throws
+     * `SchemaValidationError` with `direction: 'input'`; drifted stored
+     * data throws with `direction: 'output'`. Both carry the rich issue
+     * list from the validator so UI code can render field-level messages.
+     *
+     * The schema is stored as `StandardSchemaV1<unknown, T>` because the
+     * collection type parameter `T` is the OUTPUT type — whatever the
+     * validator produces after transforms and coercion. Users who pass a
+     * schema to `defineNoydbStore` (or `Collection.constructor`) get their
+     * `T` inferred automatically via `InferOutput<Schema>`.
+     */
+    private readonly schema;
+    /**
+     * Optional reference to the compartment-level hash-chained audit
+     * log. When present, every successful `put()` and `delete()` appends
+     * an entry to the ledger AFTER the adapter write succeeds (so a
+     * failed adapter write never produces an orphan ledger entry).
+     *
+     * The ledger is always a compartment-wide singleton — all
+     * collections in the same compartment share the same LedgerStore.
+     * Compartment.ledger() does the lazy init; this field just holds
+     * the reference so Collection doesn't need to reach back up to the
+     * compartment on every mutation.
+     *
+     * `undefined` means "no ledger attached" — supported for tests that
+     * construct a Collection directly without a compartment, and for
+     * future backwards-compat scenarios. Production usage always has a
+     * ledger because Compartment.collection() passes one through.
+     */
+    private readonly ledger;
+    /**
+     * Optional back-reference to the owning compartment's ref
+     * enforcer. When present, `Collection.put` calls
+     * `refEnforcer.enforceRefsOnPut(name, record)` before the adapter
+     * write, and `Collection.delete` calls
+     * `refEnforcer.enforceRefsOnDelete(name, id)` before its own
+     * adapter delete. The Compartment handles the actual registry
+     * lookup and cross-collection enforcement — Collection just
+     * notifies it at the right points in the lifecycle.
+     *
+     * Typed as a structural interface rather than `Compartment`
+     * directly to avoid a circular import. Compartment implements
+     * these two methods; any other object with the same shape would
+     * work too (used only in unit tests).
+     */
+    private readonly refEnforcer;
     constructor(opts: {
         adapter: NoydbAdapter;
         compartment: string;
@@ -307,6 +1786,46 @@ declare class Collection<T> {
         getDEK: (collectionName: string) => Promise<CryptoKey>;
         historyConfig?: HistoryConfig | undefined;
         onDirty?: OnDirtyCallback | undefined;
+        indexes?: IndexDef[] | undefined;
+        /**
+         * Hydration mode. `'eager'` (default) loads everything into memory on
+         * first access — matches v0.2 behavior exactly. `'lazy'` defers loads
+         * to per-id `get()` calls and bounds memory via the `cache` option.
+         */
+        prefetch?: boolean;
+        /**
+         * LRU cache options. Only meaningful when `prefetch: false`. At least
+         * one of `maxRecords` or `maxBytes` must be set in lazy mode — an
+         * unbounded lazy cache defeats the purpose.
+         */
+        cache?: CacheOptions | undefined;
+        /**
+         * Optional Standard Schema v1 validator (Zod, Valibot, ArkType,
+         * Effect Schema, etc.). When set, every `put()` is validated before
+         * encryption and every read is validated after decryption. See the
+         * `schema` field docstring for the error semantics.
+         */
+        schema?: StandardSchemaV1<unknown, T> | undefined;
+        /**
+         * Optional reference to the compartment's hash-chained ledger.
+         * When present, successful mutations append a ledger entry via
+         * `LedgerStore.append()`. Constructed at the Compartment level and
+         * threaded through — see the Compartment.collection() source for
+         * the wiring.
+         */
+        ledger?: LedgerStore | undefined;
+        /**
+         * Optional back-reference to the owning compartment's ref
+         * enforcer (v0.4 #45 — foreign-key references via `ref()`).
+         * Collection.put calls `enforceRefsOnPut` before the adapter
+         * write; Collection.delete calls `enforceRefsOnDelete` before
+         * its own adapter delete. See the `refEnforcer` field docstring
+         * for the full protocol.
+         */
+        refEnforcer?: {
+            enforceRefsOnPut(collectionName: string, record: unknown): Promise<void>;
+            enforceRefsOnDelete(collectionName: string, id: string): Promise<void>;
+        } | undefined;
     });
     /** Get a single record by ID. Returns null if not found. */
     get(id: string): Promise<T | null>;
@@ -314,13 +1833,57 @@ declare class Collection<T> {
     put(id: string, record: T): Promise<void>;
     /** Delete a record by ID. */
     delete(id: string): Promise<void>;
-    /** List all records in the collection. */
+    /**
+     * List all records in the collection.
+     *
+     * Throws in lazy mode — bulk listing defeats the purpose of lazy
+     * hydration. Use `scan()` to iterate over the full collection
+     * page-by-page without holding more than `pageSize` records in memory.
+     */
     list(): Promise<T[]>;
-    /** Filter records by a predicate. */
+    /**
+     * Build a chainable query against the collection. Returns a `Query<T>`
+     * builder when called with no arguments.
+     *
+     * Backward-compatible overload: passing a predicate function returns
+     * the filtered records directly (the v0.2 API). Prefer the chainable
+     * form for new code.
+     *
+     * @example
+     * ```ts
+     * // New chainable API:
+     * const overdue = invoices.query()
+     *   .where('status', '==', 'open')
+     *   .where('dueDate', '<', new Date())
+     *   .orderBy('dueDate')
+     *   .toArray();
+     *
+     * // Legacy predicate form (still supported):
+     * const drafts = invoices.query(i => i.status === 'draft');
+     * ```
+     */
+    query(): Query<T>;
     query(predicate: (record: T) => boolean): T[];
+    /**
+     * Cache statistics — useful for devtools, monitoring, and verifying
+     * that LRU eviction is happening as expected in lazy mode.
+     *
+     * In eager mode, returns size only (no hits/misses are tracked because
+     * every read is a cache hit by construction). In lazy mode, returns
+     * the full LRU stats: `{ hits, misses, evictions, size, bytes }`.
+     */
+    cacheStats(): CacheStats;
     /** Get version history for a record, newest first. */
     history(id: string, options?: HistoryOptions): Promise<HistoryEntry<T>[]>;
-    /** Get a specific past version of a record. */
+    /**
+     * Get a specific past version of a record.
+     *
+     * History reads intentionally **skip schema validation** — historical
+     * records predate the current schema by definition, so validating them
+     * against today's shape would be a false positive on any schema
+     * evolution. If a caller needs validated history, they should filter
+     * and re-put the records through the normal `put()` path.
+     */
     getVersion(id: string, version: number): Promise<T | null>;
     /** Revert a record to a past version. Creates a new version with the old content. */
     revert(id: string, version: number): Promise<void>;
@@ -337,15 +1900,95 @@ declare class Collection<T> {
     pruneRecordHistory(id: string | undefined, options: PruneOptions): Promise<number>;
     /** Clear all history for this collection (or a specific record). */
     clearHistory(id?: string): Promise<number>;
-    /** Count records in the collection. */
+    /**
+     * Count records in the collection.
+     *
+     * In eager mode this returns the in-memory cache size (instant). In
+     * lazy mode it asks the adapter via `list()` to enumerate ids — slower
+     * but still correct, and avoids loading any record bodies into memory.
+     */
     count(): Promise<number>;
+    /**
+     * Fetch a single page of records via the adapter's optional `listPage`
+     * extension. Returns the decrypted records for this page plus an opaque
+     * cursor for the next page.
+     *
+     * Pass `cursor: undefined` (or omit it) to start from the beginning.
+     * The final page returns `nextCursor: null`.
+     *
+     * If the adapter does NOT implement `listPage`, this falls back to a
+     * synthetic implementation: it loads all ids via `list()`, sorts them,
+     * and slices a window. The first call emits a one-time console.warn so
+     * developers can spot adapters that should opt into the fast path.
+     */
+    listPage(opts?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        items: T[];
+        nextCursor: string | null;
+    }>;
+    /**
+     * Stream every record in the collection page-by-page, yielding decrypted
+     * records as an `AsyncIterable<T>`. The whole point: process collections
+     * larger than RAM without ever holding more than `pageSize` records
+     * decrypted at once.
+     *
+     * @example
+     * ```ts
+     * for await (const record of invoices.scan({ pageSize: 500 })) {
+     *   await processOne(record)
+     * }
+     * ```
+     *
+     * Uses `adapter.listPage` when available; otherwise falls back to the
+     * synthetic pagination path with the same one-time warning.
+     */
+    scan(opts?: {
+        pageSize?: number;
+    }): AsyncIterableIterator<T>;
+    /** Decrypt a page of envelopes returned by `adapter.listPage`. */
+    private decryptPage;
     /** Load all records from adapter into memory cache. */
     private ensureHydrated;
     /** Hydrate from a pre-loaded snapshot (used by Compartment). */
     hydrateFromSnapshot(records: Record<string, EncryptedEnvelope>): Promise<void>;
+    /**
+     * Rebuild secondary indexes from the current in-memory cache.
+     *
+     * Called after any bulk hydration. Incremental put/delete updates
+     * are handled by `indexes.upsert()` / `indexes.remove()` directly,
+     * so this only fires for full reloads.
+     *
+     * Synchronous and O(N × indexes.size); for the v0.3 target scale of
+     * 1K–50K records this completes in single-digit milliseconds.
+     */
+    private rebuildIndexes;
+    /**
+     * Get the in-memory index store. Used by `Query` to short-circuit
+     * `==` and `in` lookups when an index covers the where clause.
+     *
+     * Returns `null` if no indexes are declared on this collection.
+     */
+    getIndexes(): CollectionIndexes | null;
     /** Get all records as encrypted envelopes (for dump). */
     dumpEnvelopes(): Promise<Record<string, EncryptedEnvelope>>;
     private encryptRecord;
+    /**
+     * Decrypt an envelope into a record of type `T`.
+     *
+     * When a schema is attached, the decrypted value is validated before
+     * being returned. A divergence between the stored bytes and the
+     * current schema throws `SchemaValidationError` with
+     * `direction: 'output'` — silently returning drifted data would
+     * propagate garbage into the UI and break the whole point of having
+     * a schema.
+     *
+     * `skipValidation` exists for history reads: when calling
+     * `getVersion()` the caller is explicitly asking for an old snapshot
+     * that may predate a schema change, so validating it would be a
+     * false positive. Every non-history read leaves this flag `false`.
+     */
     private decryptRecord;
 }
 
@@ -353,13 +1996,62 @@ declare class Collection<T> {
 declare class Compartment {
     private readonly adapter;
     private readonly name;
-    private readonly keyring;
+    /**
+     * The active in-memory keyring. NOT readonly because `load()`
+     * needs to refresh it after restoring a different keyring file —
+     * otherwise the in-memory DEKs (from the pre-load session) and
+     * the on-disk wrapped DEKs (from the loaded backup) drift apart
+     * and every subsequent decrypt fails with TamperedError.
+     */
+    private keyring;
     private readonly encrypted;
     private readonly emitter;
     private readonly onDirty;
     private readonly historyConfig;
-    private readonly getDEK;
+    private getDEK;
+    /**
+     * Optional callback that re-derives an UnlockedKeyring from the
+     * adapter using the active user's passphrase. Called by `load()`
+     * after the on-disk keyring file has been replaced — refreshes
+     * `this.keyring` so the next DEK access uses the loaded wrapped
+     * DEKs instead of the stale pre-load ones.
+     *
+     * Provided by Noydb at openCompartment() time. Tests that
+     * construct Compartment directly can pass `undefined`; load()
+     * skips the refresh in that case (which is fine for plaintext
+     * compartments — there's nothing to re-unwrap).
+     */
+    private readonly reloadKeyring;
     private readonly collectionCache;
+    /**
+     * Per-compartment ledger store. Lazy-initialized on first
+     * `collection()` call (which passes it through to the Collection)
+     * or on first `ledger()` call from user code.
+     *
+     * One LedgerStore is shared across all collections in a compartment
+     * because the hash chain is compartment-scoped: the chain head is a
+     * single "what did this compartment do last" identifier, not a
+     * per-collection one. Two collections appending concurrently is the
+     * single-writer concurrency concern documented in the LedgerStore
+     * docstring.
+     */
+    private ledgerStore;
+    /**
+     * Per-compartment foreign-key reference registry. Collections
+     * register their `refs` option here on construction; the
+     * compartment uses the registry on every put/delete/checkIntegrity
+     * call. One instance lives for the compartment's lifetime.
+     */
+    private readonly refRegistry;
+    /**
+     * Set of collection record-ids currently being deleted as part of
+     * a cascade. Populated on entry to `enforceRefsOnDelete` and
+     * drained on exit. Used to break mutual-cascade cycles: deleting
+     * A → cascade to B → cascade back to A would otherwise recurse
+     * forever, so we short-circuit when we see an already-in-progress
+     * delete on the same (collection, id) pair.
+     */
+    private readonly cascadeInProgress;
     constructor(opts: {
         adapter: NoydbAdapter;
         name: string;
@@ -368,15 +2060,178 @@ declare class Compartment {
         emitter: NoydbEventEmitter;
         onDirty?: OnDirtyCallback | undefined;
         historyConfig?: HistoryConfig | undefined;
+        reloadKeyring?: (() => Promise<UnlockedKeyring>) | undefined;
     });
-    /** Open a typed collection within this compartment. */
-    collection<T>(collectionName: string): Collection<T>;
+    /**
+     * Construct (or reconstruct) the lazy DEK resolver. Captures the
+     * CURRENT value of `this.keyring` and `this.adapter` in a closure,
+     * memoizing the inner getDEKFn after first use so subsequent
+     * lookups are O(1).
+     *
+     * `load()` calls this after refreshing `this.keyring` to discard
+     * the prior session's cached DEKs.
+     */
+    private makeGetDEK;
+    /**
+     * Open a typed collection within this compartment.
+     *
+     * - `options.indexes` declares secondary indexes for the query DSL.
+     *   Indexes are computed in memory after decryption; adapters never
+     *   see plaintext index data.
+     * - `options.prefetch` (default `true`) controls hydration. Eager mode
+     *   loads everything on first access; lazy mode (`prefetch: false`)
+     *   loads records on demand and bounds memory via the LRU cache.
+     * - `options.cache` configures the LRU bounds. Required in lazy mode.
+     *   Accepts `{ maxRecords, maxBytes: '50MB' | 1024 }`.
+     * - `options.schema` attaches a Standard Schema v1 validator (Zod,
+     *   Valibot, ArkType, Effect Schema, etc.). Every `put()` is validated
+     *   before encryption; every read is validated after decryption.
+     *   Failing records throw `SchemaValidationError`.
+     *
+     * Lazy mode + indexes is rejected at construction time — see the
+     * Collection constructor for the rationale.
+     */
+    collection<T>(collectionName: string, options?: {
+        indexes?: IndexDef[];
+        prefetch?: boolean;
+        cache?: CacheOptions;
+        schema?: StandardSchemaV1<unknown, T>;
+        refs?: Record<string, RefDescriptor>;
+    }): Collection<T>;
+    /**
+     * Enforce strict outbound refs on a `put()`. Called by Collection
+     * just before it writes to the adapter. For every strict ref
+     * declared on the collection, check that the target id exists in
+     * the target collection; throw `RefIntegrityError` if not.
+     *
+     * `warn` and `cascade` modes don't affect put semantics — they're
+     * enforced at delete time or via `checkIntegrity()`.
+     */
+    enforceRefsOnPut(collectionName: string, record: unknown): Promise<void>;
+    /**
+     * Enforce inbound ref modes on a `delete()`. Called by Collection
+     * just before it deletes from the adapter. Walks every inbound
+     * ref that targets this (collection, id) and:
+     *
+     *   - `strict`: throws if any referencing records exist
+     *   - `cascade`: deletes every referencing record
+     *   - `warn`:    no-op (checkIntegrity picks it up)
+     *
+     * Cascade cycles are broken via `cascadeInProgress` — re-entering
+     * for the same (collection, id) returns immediately so two
+     * mutually-cascading collections don't recurse forever.
+     */
+    enforceRefsOnDelete(collectionName: string, id: string): Promise<void>;
+    /**
+     * Walk every collection that has declared refs, load its records,
+     * and report any reference whose target id is missing. Modes are
+     * reported alongside each violation so the caller can distinguish
+     * "this is a warning the user asked for" from "this should never
+     * have happened" (strict violations produced by out-of-band
+     * writes).
+     *
+     * Returns `{ violations: [...] }` instead of throwing — the whole
+     * point of `checkIntegrity()` is to surface a list for display
+     * or repair, not to fail noisily.
+     */
+    checkIntegrity(): Promise<{
+        violations: RefViolation[];
+    }>;
+    /**
+     * Return this compartment's hash-chained audit log.
+     *
+     * The ledger is lazy-initialized on first access and cached for the
+     * lifetime of the Compartment instance. Every LedgerStore instance
+     * shares the same adapter and DEK resolver, so `compartment.ledger()`
+     * can be called repeatedly without performance cost.
+     *
+     * The LedgerStore itself is the public API: consumers call
+     * `.append()` (via Collection internals), `.head()`, `.verify()`,
+     * and `.entries({ from, to })`. See the LedgerStore docstring for
+     * the full surface and the concurrency caveats.
+     */
+    ledger(): LedgerStore;
     /** List all collection names in this compartment. */
     collections(): Promise<string[]>;
-    /** Dump compartment as encrypted JSON backup string. */
+    /**
+     * Dump compartment as a verifiable encrypted JSON backup string.
+     *
+     * v0.4 backups embed the current ledger head and the full
+     * `_ledger` + `_ledger_deltas` internal collections so the
+     * receiver can run `verifyBackupIntegrity()` after `load()` and
+     * detect any tampering between dump and restore. Pre-v0.4 callers
+     * who didn't have a ledger get a backup without these fields, and
+     * the corresponding `load()` skips the integrity check with a
+     * warning — both modes round-trip cleanly.
+     */
     dump(): Promise<string>;
-    /** Restore compartment from an encrypted JSON backup string. */
+    /**
+     * Restore a compartment from a verifiable backup.
+     *
+     * After loading, runs `verifyBackupIntegrity()` to confirm:
+     *   1. The hash chain is intact (no `prevHash` mismatches)
+     *   2. The chain head matches the embedded `ledgerHead.hash`
+     *      from the backup
+     *   3. Every data envelope's `payloadHash` matches the
+     *      corresponding ledger entry — i.e. nobody swapped
+     *      ciphertext between dump and restore
+     *
+     * On any failure, throws `BackupLedgerError` (chain or head
+     * mismatch) or `BackupCorruptedError` (data envelope mismatch).
+     * The compartment state on the adapter has already been written
+     * by the time we throw, so the caller is responsible for either
+     * accepting the suspect state or wiping it and trying a different
+     * backup.
+     *
+     * Pre-v0.4 backups (no `ledgerHead` field, no `_internal`) load
+     * with a console warning and skip the integrity check entirely
+     * — there's no chain to verify against.
+     */
     load(backupJson: string): Promise<void>;
+    /**
+     * End-to-end backup integrity check. Runs both:
+     *
+     *   1. `ledger.verify()` — walks the hash chain and confirms
+     *      every `prevHash` matches the recomputed hash of its
+     *      predecessor.
+     *
+     *   2. **Data envelope cross-check** — for every (collection, id)
+     *      that has a current value, find the most recent ledger
+     *      entry recording a `put` for that pair, recompute the
+     *      sha256 of the stored envelope's `_data`, and compare to
+     *      the entry's `payloadHash`. Any mismatch means an
+     *      out-of-band write modified the data without updating the
+     *      ledger.
+     *
+     * Returns a discriminated union so callers can handle the two
+     * failure modes differently:
+     *   - `{ ok: true, head, length }` — chain verified and all
+     *     data matches; safe to use.
+     *   - `{ ok: false, kind: 'chain', divergedAt, message }` — the
+     *     chain itself is broken at the given index.
+     *   - `{ ok: false, kind: 'data', collection, id, message }` —
+     *     a specific data envelope doesn't match its ledger entry.
+     *
+     * This method is exposed so users can call it any time, not just
+     * during `load()`. A scheduled background check is the simplest
+     * way to detect tampering of an in-place compartment.
+     */
+    verifyBackupIntegrity(): Promise<{
+        readonly ok: true;
+        readonly head: string;
+        readonly length: number;
+    } | {
+        readonly ok: false;
+        readonly kind: 'chain';
+        readonly divergedAt: number;
+        readonly message: string;
+    } | {
+        readonly ok: false;
+        readonly kind: 'data';
+        readonly collection: string;
+        readonly id: string;
+        readonly message: string;
+    }>;
     /** Export compartment as decrypted JSON (owner only). */
     export(): Promise<string>;
 }
@@ -523,4 +2378,4 @@ declare function validatePassphrase(passphrase: string): void;
  */
 declare function estimateEntropy(passphrase: string): number;
 
-export { type BiometricCredential, type ChangeEvent, type ChangeType, Collection, Compartment, type CompartmentBackup, type CompartmentSnapshot, type Conflict, ConflictError, type ConflictStrategy, DecryptionError, type DiffEntry, type DirtyEntry, type EncryptedEnvelope, type GrantOptions, type HistoryConfig, type HistoryEntry, type HistoryOptions, InvalidKeyError, type KeyringFile, NOYDB_BACKUP_VERSION, NOYDB_FORMAT_VERSION, NOYDB_KEYRING_VERSION, NOYDB_SYNC_VERSION, NetworkError, NoAccessError, NotFoundError, Noydb, type NoydbAdapter, NoydbError, type NoydbEventMap, type NoydbOptions, type Permission, PermissionDeniedError, type Permissions, type PruneOptions, type PullResult, type PushResult, ReadOnlyError, type RevokeOptions, type Role, SyncEngine, type SyncMetadata, type SyncStatus, TamperedError, type UserInfo, ValidationError, createNoydb, defineAdapter, diff, enrollBiometric, estimateEntropy, formatDiff, isBiometricAvailable, loadBiometric, removeBiometric, saveBiometric, unlockBiometric, validatePassphrase };
+export { type AppendInput, BackupCorruptedError, BackupLedgerError, type BiometricCredential, type CacheOptions, type CacheStats, type ChangeEvent, type ChangeType, type Clause, Collection, CollectionIndexes, Compartment, type CompartmentBackup, type CompartmentSnapshot, type Conflict, ConflictError, type ConflictStrategy, DecryptionError, type DiffEntry, type DirtyEntry, type EncryptedEnvelope, type FieldClause, type FilterClause, type GrantOptions, type GroupClause, type HashIndex, type HistoryConfig, type HistoryEntry, type HistoryOptions, type IndexDef, type InferOutput, InvalidKeyError, type JsonPatch, type JsonPatchOp, type KeyringFile, LEDGER_COLLECTION, LEDGER_DELTAS_COLLECTION, type LedgerEntry, LedgerStore, type ListPageResult, Lru, type LruOptions, type LruStats, NOYDB_BACKUP_VERSION, NOYDB_FORMAT_VERSION, NOYDB_KEYRING_VERSION, NOYDB_SYNC_VERSION, NetworkError, NoAccessError, NotFoundError, Noydb, type NoydbAdapter, NoydbError, type NoydbEventMap, type NoydbOptions, type Operator, type OrderBy, type Permission, PermissionDeniedError, type Permissions, type PruneOptions, type PullResult, type PushResult, Query, type QueryPlan, type QuerySource, ReadOnlyError, type RefDescriptor, RefIntegrityError, type RefMode, RefRegistry, RefScopeError, type RefViolation, type RevokeOptions, type Role, SchemaValidationError, type StandardSchemaV1, type StandardSchemaV1Issue, type StandardSchemaV1SyncResult, SyncEngine, type SyncMetadata, type SyncStatus, TamperedError, type UserInfo, ValidationError, type VerifyResult, applyPatch, canonicalJson, computePatch, createNoydb, defineAdapter, diff, enrollBiometric, envelopePayloadHash, estimateEntropy, estimateRecordBytes, evaluateClause, evaluateFieldClause, executePlan, formatDiff, hashEntry, isBiometricAvailable, loadBiometric, paddedIndex, parseBytes, parseIndex, readPath, ref, removeBiometric, saveBiometric, sha256Hex, unlockBiometric, validatePassphrase, validateSchemaInput, validateSchemaOutput };