@noy-db/core 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -100,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;
@@ -279,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 {
@@ -756,6 +1726,56 @@ declare class Collection<T> {
      * 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;
@@ -779,6 +1799,33 @@ declare class Collection<T> {
          * 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>;
@@ -828,7 +1875,15 @@ declare class Collection<T> {
     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>;
@@ -919,6 +1974,21 @@ declare class Collection<T> {
     /** 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;
 }
 
@@ -926,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;
@@ -941,7 +2060,18 @@ declare class Compartment {
         emitter: NoydbEventEmitter;
         onDirty?: OnDirtyCallback | undefined;
         historyConfig?: HistoryConfig | undefined;
+        reloadKeyring?: (() => Promise<UnlockedKeyring>) | undefined;
     });
+    /**
+     * 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.
      *
@@ -953,6 +2083,10 @@ declare class Compartment {
      *   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.
@@ -961,13 +2095,143 @@ declare class Compartment {
         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>;
 }
@@ -1114,4 +2378,4 @@ declare function validatePassphrase(passphrase: string): void;
  */
 declare function estimateEntropy(passphrase: string): number;
 
-export { 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, InvalidKeyError, type KeyringFile, 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 RevokeOptions, type Role, SyncEngine, type SyncMetadata, type SyncStatus, TamperedError, type UserInfo, ValidationError, createNoydb, defineAdapter, diff, enrollBiometric, estimateEntropy, estimateRecordBytes, evaluateClause, evaluateFieldClause, executePlan, formatDiff, isBiometricAvailable, loadBiometric, parseBytes, readPath, 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 };