@noy-db/core 0.2.0 → 0.4.0

package/dist/index.js

@@ -78,6 +78,74 @@ var ValidationError = class extends NoydbError {
     this.name = "ValidationError";
   }
 };
+var SchemaValidationError = class extends NoydbError {
+  issues;
+  direction;
+  constructor(message, issues, direction) {
+    super("SCHEMA_VALIDATION_FAILED", message);
+    this.name = "SchemaValidationError";
+    this.issues = issues;
+    this.direction = direction;
+  }
+};
+var BackupLedgerError = class extends NoydbError {
+  /** First-broken-entry index, if known. */
+  divergedAt;
+  constructor(message, divergedAt) {
+    super("BACKUP_LEDGER", message);
+    this.name = "BackupLedgerError";
+    if (divergedAt !== void 0) this.divergedAt = divergedAt;
+  }
+};
+var BackupCorruptedError = class extends NoydbError {
+  /** The (collection, id) pair whose envelope failed the hash check. */
+  collection;
+  id;
+  constructor(collection, id, message) {
+    super("BACKUP_CORRUPTED", message);
+    this.name = "BackupCorruptedError";
+    this.collection = collection;
+    this.id = id;
+  }
+};
+
+// src/schema.ts
+async function validateSchemaInput(schema, value, context) {
+  const result = await schema["~standard"].validate(value);
+  if (result.issues !== void 0 && result.issues.length > 0) {
+    throw new SchemaValidationError(
+      `Schema validation failed on ${context}: ${summarizeIssues(result.issues)}`,
+      result.issues,
+      "input"
+    );
+  }
+  return result.value;
+}
+async function validateSchemaOutput(schema, value, context) {
+  const result = await schema["~standard"].validate(value);
+  if (result.issues !== void 0 && result.issues.length > 0) {
+    throw new SchemaValidationError(
+      `Stored data for ${context} does not match the current schema \u2014 schema drift? ${summarizeIssues(result.issues)}`,
+      result.issues,
+      "output"
+    );
+  }
+  return result.value;
+}
+function summarizeIssues(issues) {
+  const shown = issues.slice(0, 3).map((issue) => {
+    const pathStr = formatPath(issue.path);
+    return `${pathStr}: ${issue.message}`;
+  });
+  const suffix = issues.length > 3 ? ` (+${issues.length - 3} more)` : "";
+  return shown.join("; ") + suffix;
+}
+function formatPath(path) {
+  if (!path || path.length === 0) return "root";
+  return path.map(
+    (segment) => typeof segment === "object" && segment !== null ? String(segment.key) : String(segment)
+  ).join(".");
+}
 
 // src/crypto.ts
 var PBKDF2_ITERATIONS = 6e5;
@@ -188,6 +256,749 @@ function base64ToBuffer(base64) {
   return bytes;
 }
 
+// src/ledger/entry.ts
+function canonicalJson(value) {
+  if (value === null) return "null";
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error(
+        `canonicalJson: refusing to encode non-finite number ${String(value)}`
+      );
+    }
+    return JSON.stringify(value);
+  }
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "bigint") {
+    throw new Error("canonicalJson: BigInt is not JSON-serializable");
+  }
+  if (typeof value === "undefined" || typeof value === "function") {
+    throw new Error(
+      `canonicalJson: refusing to encode ${typeof value} \u2014 include all fields explicitly`
+    );
+  }
+  if (Array.isArray(value)) {
+    return "[" + value.map((v) => canonicalJson(v)).join(",") + "]";
+  }
+  if (typeof value === "object") {
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    const parts = [];
+    for (const key of keys) {
+      parts.push(JSON.stringify(key) + ":" + canonicalJson(obj[key]));
+    }
+    return "{" + parts.join(",") + "}";
+  }
+  throw new Error(`canonicalJson: unexpected value type: ${typeof value}`);
+}
+async function sha256Hex(input) {
+  const bytes = new TextEncoder().encode(input);
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+  return bytesToHex(new Uint8Array(digest));
+}
+async function hashEntry(entry) {
+  return sha256Hex(canonicalJson(entry));
+}
+function bytesToHex(bytes) {
+  const hex = new Array(bytes.length);
+  for (let i = 0; i < bytes.length; i++) {
+    hex[i] = (bytes[i] ?? 0).toString(16).padStart(2, "0");
+  }
+  return hex.join("");
+}
+function paddedIndex(index) {
+  return String(index).padStart(10, "0");
+}
+function parseIndex(key) {
+  return Number.parseInt(key, 10);
+}
+
+// src/ledger/patch.ts
+function computePatch(prev, next) {
+  const ops = [];
+  diff(prev, next, "", ops);
+  return ops;
+}
+function diff(prev, next, path, out) {
+  if (prev === next) return;
+  if (prev === null || next === null) {
+    out.push({ op: "replace", path, value: next });
+    return;
+  }
+  const prevIsArray = Array.isArray(prev);
+  const nextIsArray = Array.isArray(next);
+  const prevIsObject = typeof prev === "object" && !prevIsArray;
+  const nextIsObject = typeof next === "object" && !nextIsArray;
+  if (prevIsArray !== nextIsArray || prevIsObject !== nextIsObject) {
+    out.push({ op: "replace", path, value: next });
+    return;
+  }
+  if (prevIsArray && nextIsArray) {
+    if (!arrayDeepEqual(prev, next)) {
+      out.push({ op: "replace", path, value: next });
+    }
+    return;
+  }
+  if (prevIsObject && nextIsObject) {
+    const prevObj = prev;
+    const nextObj = next;
+    const prevKeys = Object.keys(prevObj);
+    const nextKeys = Object.keys(nextObj);
+    for (const key of prevKeys) {
+      const childPath = path + "/" + escapePathSegment(key);
+      if (!(key in nextObj)) {
+        out.push({ op: "remove", path: childPath });
+      } else {
+        diff(prevObj[key], nextObj[key], childPath, out);
+      }
+    }
+    for (const key of nextKeys) {
+      if (!(key in prevObj)) {
+        out.push({
+          op: "add",
+          path: path + "/" + escapePathSegment(key),
+          value: nextObj[key]
+        });
+      }
+    }
+    return;
+  }
+  out.push({ op: "replace", path, value: next });
+}
+function arrayDeepEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (!deepEqual(a[i], b[i])) return false;
+  }
+  return true;
+}
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== "object") return false;
+  const aArray = Array.isArray(a);
+  const bArray = Array.isArray(b);
+  if (aArray !== bArray) return false;
+  if (aArray && bArray) return arrayDeepEqual(a, b);
+  const aObj = a;
+  const bObj = b;
+  const aKeys = Object.keys(aObj);
+  const bKeys = Object.keys(bObj);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    if (!(key in bObj)) return false;
+    if (!deepEqual(aObj[key], bObj[key])) return false;
+  }
+  return true;
+}
+function applyPatch(base, patch) {
+  let result = clone(base);
+  for (const op of patch) {
+    result = applyOp(result, op);
+  }
+  return result;
+}
+function applyOp(doc, op) {
+  if (op.path === "") {
+    if (op.op === "remove") return null;
+    return clone(op.value);
+  }
+  const segments = parsePath(op.path);
+  return walkAndApply(doc, segments, op);
+}
+function walkAndApply(doc, segments, op) {
+  if (segments.length === 0) {
+    throw new Error("walkAndApply: empty segments (internal error)");
+  }
+  const [head, ...rest] = segments;
+  if (head === void 0) throw new Error("walkAndApply: undefined segment");
+  if (rest.length === 0) {
+    return applyAtTerminal(doc, head, op);
+  }
+  if (Array.isArray(doc)) {
+    const idx = parseArrayIndex(head, doc.length);
+    const child = doc[idx];
+    const newChild = walkAndApply(child, rest, op);
+    const next = doc.slice();
+    next[idx] = newChild;
+    return next;
+  }
+  if (doc !== null && typeof doc === "object") {
+    const obj = doc;
+    if (!(head in obj)) {
+      throw new Error(`applyPatch: path segment "${head}" not found in object`);
+    }
+    const newChild = walkAndApply(obj[head], rest, op);
+    return { ...obj, [head]: newChild };
+  }
+  throw new Error(
+    `applyPatch: cannot step into ${typeof doc} at segment "${head}"`
+  );
+}
+function applyAtTerminal(doc, segment, op) {
+  if (Array.isArray(doc)) {
+    const idx = segment === "-" ? doc.length : parseArrayIndex(segment, doc.length + 1);
+    const next = doc.slice();
+    if (op.op === "remove") {
+      next.splice(idx, 1);
+      return next;
+    }
+    if (op.op === "add") {
+      next.splice(idx, 0, clone(op.value));
+      return next;
+    }
+    if (op.op === "replace") {
+      if (idx >= doc.length) {
+        throw new Error(
+          `applyPatch: replace at out-of-bounds array index ${idx}`
+        );
+      }
+      next[idx] = clone(op.value);
+      return next;
+    }
+  }
+  if (doc !== null && typeof doc === "object") {
+    const obj = doc;
+    if (op.op === "remove") {
+      if (!(segment in obj)) {
+        throw new Error(
+          `applyPatch: remove on missing key "${segment}"`
+        );
+      }
+      const next = { ...obj };
+      delete next[segment];
+      return next;
+    }
+    if (op.op === "add") {
+      return { ...obj, [segment]: clone(op.value) };
+    }
+    if (op.op === "replace") {
+      if (!(segment in obj)) {
+        throw new Error(
+          `applyPatch: replace on missing key "${segment}"`
+        );
+      }
+      return { ...obj, [segment]: clone(op.value) };
+    }
+  }
+  throw new Error(
+    `applyPatch: cannot apply ${op.op} at terminal segment "${segment}"`
+  );
+}
+function escapePathSegment(segment) {
+  return segment.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+function unescapePathSegment(segment) {
+  return segment.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+function parsePath(path) {
+  if (!path.startsWith("/")) {
+    throw new Error(`applyPatch: path must start with '/', got "${path}"`);
+  }
+  return path.slice(1).split("/").map(unescapePathSegment);
+}
+function parseArrayIndex(segment, max) {
+  if (!/^\d+$/.test(segment)) {
+    throw new Error(
+      `applyPatch: array index must be a non-negative integer, got "${segment}"`
+    );
+  }
+  const idx = Number.parseInt(segment, 10);
+  if (idx < 0 || idx > max) {
+    throw new Error(
+      `applyPatch: array index ${idx} out of range [0, ${max}]`
+    );
+  }
+  return idx;
+}
+function clone(value) {
+  if (value === null || value === void 0) return value;
+  if (typeof value !== "object") return value;
+  return JSON.parse(JSON.stringify(value));
+}
+
+// src/ledger/store.ts
+var LEDGER_COLLECTION = "_ledger";
+var LEDGER_DELTAS_COLLECTION = "_ledger_deltas";
+var LedgerStore = class {
+  adapter;
+  compartment;
+  encrypted;
+  getDEK;
+  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.
+   */
+  headCache = void 0;
+  constructor(opts) {
+    this.adapter = opts.adapter;
+    this.compartment = opts.compartment;
+    this.encrypted = opts.encrypted;
+    this.getDEK = opts.getDEK;
+    this.actor = opts.actor;
+  }
+  /**
+   * 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.
+   */
+  async getCachedHead() {
+    if (this.headCache !== void 0) return this.headCache;
+    const entries = await this.loadAllEntries();
+    const last = entries[entries.length - 1];
+    if (!last) {
+      this.headCache = null;
+      return null;
+    }
+    this.headCache = { entry: last, hash: await hashEntry(last) };
+    return this.headCache;
+  }
+  /**
+   * 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.
+   */
+  async append(input) {
+    const cached = await this.getCachedHead();
+    const lastEntry = cached?.entry;
+    const prevHash = cached?.hash ?? "";
+    const nextIndex = lastEntry ? lastEntry.index + 1 : 0;
+    let deltaHash;
+    if (input.delta !== void 0) {
+      const deltaEnvelope = await this.encryptDelta(input.delta);
+      await this.adapter.put(
+        this.compartment,
+        LEDGER_DELTAS_COLLECTION,
+        paddedIndex(nextIndex),
+        deltaEnvelope
+      );
+      deltaHash = await sha256Hex(deltaEnvelope._data);
+    }
+    const entryBase = {
+      index: nextIndex,
+      prevHash,
+      op: input.op,
+      collection: input.collection,
+      id: input.id,
+      version: input.version,
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      actor: input.actor === "" ? this.actor : input.actor,
+      payloadHash: input.payloadHash
+    };
+    const entry = deltaHash !== void 0 ? { ...entryBase, deltaHash } : entryBase;
+    const envelope = await this.encryptEntry(entry);
+    await this.adapter.put(
+      this.compartment,
+      LEDGER_COLLECTION,
+      paddedIndex(entry.index),
+      envelope
+    );
+    this.headCache = { entry, hash: await hashEntry(entry) };
+    return entry;
+  }
+  /**
+   * 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.
+   */
+  async loadDelta(index) {
+    const envelope = await this.adapter.get(
+      this.compartment,
+      LEDGER_DELTAS_COLLECTION,
+      paddedIndex(index)
+    );
+    if (!envelope) return null;
+    if (!this.encrypted) {
+      return JSON.parse(envelope._data);
+    }
+    const dek = await this.getDEK(LEDGER_COLLECTION);
+    const json = await decrypt(envelope._iv, envelope._data, dek);
+    return JSON.parse(json);
+  }
+  /** Encrypt a JSON Patch into an envelope for storage. Mirrors encryptEntry. */
+  async encryptDelta(patch) {
+    const json = JSON.stringify(patch);
+    if (!this.encrypted) {
+      return {
+        _noydb: NOYDB_FORMAT_VERSION,
+        _v: 1,
+        _ts: (/* @__PURE__ */ new Date()).toISOString(),
+        _iv: "",
+        _data: json,
+        _by: this.actor
+      };
+    }
+    const dek = await this.getDEK(LEDGER_COLLECTION);
+    const { iv, data } = await encrypt(json, dek);
+    return {
+      _noydb: NOYDB_FORMAT_VERSION,
+      _v: 1,
+      _ts: (/* @__PURE__ */ new Date()).toISOString(),
+      _iv: iv,
+      _data: data,
+      _by: this.actor
+    };
+  }
+  /**
+   * 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).
+   */
+  async loadAllEntries() {
+    const keys = await this.adapter.list(this.compartment, LEDGER_COLLECTION);
+    keys.sort();
+    const entries = [];
+    for (const key of keys) {
+      const envelope = await this.adapter.get(
+        this.compartment,
+        LEDGER_COLLECTION,
+        key
+      );
+      if (!envelope) continue;
+      entries.push(await this.decryptEntry(envelope));
+    }
+    return entries;
+  }
+  /**
+   * 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".
+   */
+  async head() {
+    const cached = await this.getCachedHead();
+    if (!cached) return null;
+    return {
+      entry: cached.entry,
+      hash: cached.hash,
+      length: cached.entry.index + 1
+    };
+  }
+  /**
+   * 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.
+   */
+  async entries(opts = {}) {
+    const all = await this.loadAllEntries();
+    const from = Math.max(0, opts.from ?? 0);
+    const to = Math.min(all.length, opts.to ?? all.length);
+    return all.slice(from, to);
+  }
+  /**
+   * 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.
+   */
+  async reconstruct(collection, id, current, atVersion) {
+    const all = await this.loadAllEntries();
+    const matching = all.filter(
+      (e) => e.collection === collection && e.id === id
+    );
+    if (matching.length === 0) {
+      return null;
+    }
+    let state = current;
+    for (let i = matching.length - 1; i >= 0; i--) {
+      const entry = matching[i];
+      if (!entry) continue;
+      if (entry.version === atVersion && entry.op !== "delete") {
+        return state;
+      }
+      if (entry.op === "delete") {
+        return null;
+      }
+      if (entry.deltaHash === void 0) {
+        if (entry.version === atVersion) return state;
+        return null;
+      }
+      const patch = await this.loadDelta(entry.index);
+      if (!patch) {
+        return null;
+      }
+      if (state === null) {
+        return null;
+      }
+      state = applyPatch(state, patch);
+    }
+    return 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.
+   */
+  async verify() {
+    const entries = await this.loadAllEntries();
+    let expectedPrevHash = "";
+    for (let i = 0; i < entries.length; i++) {
+      const entry = entries[i];
+      if (!entry) continue;
+      if (entry.prevHash !== expectedPrevHash) {
+        return {
+          ok: false,
+          divergedAt: i,
+          expected: expectedPrevHash,
+          actual: entry.prevHash
+        };
+      }
+      if (entry.index !== i) {
+        return {
+          ok: false,
+          divergedAt: i,
+          expected: `index=${i}`,
+          actual: `index=${entry.index}`
+        };
+      }
+      expectedPrevHash = await hashEntry(entry);
+    }
+    return {
+      ok: true,
+      head: expectedPrevHash,
+      length: entries.length
+    };
+  }
+  // ─── Encryption plumbing ─────────────────────────────────────────
+  /**
+   * 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).
+   */
+  async encryptEntry(entry) {
+    const json = canonicalJson(entry);
+    if (!this.encrypted) {
+      return {
+        _noydb: NOYDB_FORMAT_VERSION,
+        _v: entry.index + 1,
+        _ts: entry.ts,
+        _iv: "",
+        _data: json,
+        _by: entry.actor
+      };
+    }
+    const dek = await this.getDEK(LEDGER_COLLECTION);
+    const { iv, data } = await encrypt(json, dek);
+    return {
+      _noydb: NOYDB_FORMAT_VERSION,
+      _v: entry.index + 1,
+      _ts: entry.ts,
+      _iv: iv,
+      _data: data,
+      _by: entry.actor
+    };
+  }
+  /** Decrypt an envelope into a LedgerEntry. Throws on bad key / tamper. */
+  async decryptEntry(envelope) {
+    if (!this.encrypted) {
+      return JSON.parse(envelope._data);
+    }
+    const dek = await this.getDEK(LEDGER_COLLECTION);
+    const json = await decrypt(envelope._iv, envelope._data, dek);
+    return JSON.parse(json);
+  }
+};
+async function envelopePayloadHash(envelope) {
+  if (!envelope) return "";
+  return sha256Hex(envelope._data);
+}
+
+// src/refs.ts
+var RefIntegrityError = class extends NoydbError {
+  collection;
+  id;
+  field;
+  refTo;
+  refId;
+  constructor(opts) {
+    super("REF_INTEGRITY", opts.message);
+    this.name = "RefIntegrityError";
+    this.collection = opts.collection;
+    this.id = opts.id;
+    this.field = opts.field;
+    this.refTo = opts.refTo;
+    this.refId = opts.refId;
+  }
+};
+var RefScopeError = class extends NoydbError {
+  constructor(target) {
+    super(
+      "REF_SCOPE",
+      `Cross-compartment references are not supported in v0.4 \u2014 got target "${target}". Use a simple collection name (e.g. "clients"), not a path. Cross-compartment refs are tracked for a future release.`
+    );
+    this.name = "RefScopeError";
+  }
+};
+function ref(target, mode = "strict") {
+  if (target.includes("/")) {
+    throw new RefScopeError(target);
+  }
+  if (!target || target.startsWith("_")) {
+    throw new Error(
+      `ref(): target collection name must be non-empty and cannot start with '_' (reserved for internal collections). Got "${target}".`
+    );
+  }
+  return { target, mode };
+}
+var RefRegistry = class {
+  outbound = /* @__PURE__ */ new Map();
+  inbound = /* @__PURE__ */ new Map();
+  /**
+   * 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, refs) {
+    const existing = this.outbound.get(collection);
+    if (existing) {
+      const existingKeys = Object.keys(existing).sort();
+      const newKeys = Object.keys(refs).sort();
+      if (existingKeys.join(",") !== newKeys.join(",")) {
+        throw new Error(
+          `RefRegistry: conflicting ref declarations for collection "${collection}"`
+        );
+      }
+      for (const k of existingKeys) {
+        const a = existing[k];
+        const b = refs[k];
+        if (!a || !b || a.target !== b.target || a.mode !== b.mode) {
+          throw new Error(
+            `RefRegistry: conflicting ref declarations for collection "${collection}" field "${k}"`
+          );
+        }
+      }
+      return;
+    }
+    this.outbound.set(collection, { ...refs });
+    for (const [field, desc] of Object.entries(refs)) {
+      const list = this.inbound.get(desc.target) ?? [];
+      list.push({ collection, field, mode: desc.mode });
+      this.inbound.set(desc.target, list);
+    }
+  }
+  /** Get the outbound refs declared by a collection (or `{}` if none). */
+  getOutbound(collection) {
+    return this.outbound.get(collection) ?? {};
+  }
+  /** Get the inbound refs that target a given collection (or `[]`). */
+  getInbound(target) {
+    return this.inbound.get(target) ?? [];
+  }
+  /**
+   * 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() {
+    return [...this.outbound.entries()];
+  }
+  /** Clear the registry. Test-only escape hatch; never called from production code. */
+  clear() {
+    this.outbound.clear();
+    this.inbound.clear();
+  }
+};
+
 // src/keyring.ts
 var GRANTABLE_BY_ADMIN = ["operator", "viewer", "client"];
 function canGrant(callerRole, targetRole) {
@@ -272,6 +1083,11 @@ async function grant(adapter, compartment, callerKeyring, options) {
       }
     }
   }
+  for (const [collName, dek] of callerKeyring.deks) {
+    if (collName.startsWith("_") && !(collName in wrappedDeks)) {
+      wrappedDeks[collName] = await wrapKey(dek, newKek);
+    }
+  }
   const keyringFile = {
     _noydb_keyring: NOYDB_KEYRING_VERSION,
     user_id: options.userId,
@@ -525,65 +1341,685 @@ async function clearHistory(adapter, compartment, collection, recordId) {
 }
 
 // src/diff.ts
-function diff(oldObj, newObj, basePath = "") {
+function diff2(oldObj, newObj, basePath = "") {
   const changes = [];
   if (oldObj === newObj) return changes;
   if (oldObj == null && newObj != null) {
     return [{ path: basePath || "(root)", type: "added", to: newObj }];
   }
-  if (oldObj != null && newObj == null) {
-    return [{ path: basePath || "(root)", type: "removed", from: oldObj }];
+  if (oldObj != null && newObj == null) {
+    return [{ path: basePath || "(root)", type: "removed", from: oldObj }];
+  }
+  if (typeof oldObj !== typeof newObj) {
+    return [{ path: basePath || "(root)", type: "changed", from: oldObj, to: newObj }];
+  }
+  if (typeof oldObj !== "object") {
+    return [{ path: basePath || "(root)", type: "changed", from: oldObj, to: newObj }];
+  }
+  if (Array.isArray(oldObj) && Array.isArray(newObj)) {
+    const maxLen = Math.max(oldObj.length, newObj.length);
+    for (let i = 0; i < maxLen; i++) {
+      const p = basePath ? `${basePath}[${i}]` : `[${i}]`;
+      if (i >= oldObj.length) {
+        changes.push({ path: p, type: "added", to: newObj[i] });
+      } else if (i >= newObj.length) {
+        changes.push({ path: p, type: "removed", from: oldObj[i] });
+      } else {
+        changes.push(...diff2(oldObj[i], newObj[i], p));
+      }
+    }
+    return changes;
+  }
+  const oldRecord = oldObj;
+  const newRecord = newObj;
+  const allKeys = /* @__PURE__ */ new Set([...Object.keys(oldRecord), ...Object.keys(newRecord)]);
+  for (const key of allKeys) {
+    const p = basePath ? `${basePath}.${key}` : key;
+    if (!(key in oldRecord)) {
+      changes.push({ path: p, type: "added", to: newRecord[key] });
+    } else if (!(key in newRecord)) {
+      changes.push({ path: p, type: "removed", from: oldRecord[key] });
+    } else {
+      changes.push(...diff2(oldRecord[key], newRecord[key], p));
+    }
+  }
+  return changes;
+}
+function formatDiff(changes) {
+  if (changes.length === 0) return "(no changes)";
+  return changes.map((c) => {
+    switch (c.type) {
+      case "added":
+        return `+ ${c.path}: ${JSON.stringify(c.to)}`;
+      case "removed":
+        return `- ${c.path}: ${JSON.stringify(c.from)}`;
+      case "changed":
+        return `~ ${c.path}: ${JSON.stringify(c.from)} \u2192 ${JSON.stringify(c.to)}`;
+    }
+  }).join("\n");
+}
+
+// src/query/predicate.ts
+function readPath(record, path) {
+  if (record === null || record === void 0) return void 0;
+  if (!path.includes(".")) {
+    return record[path];
+  }
+  const segments = path.split(".");
+  let cursor = record;
+  for (const segment of segments) {
+    if (cursor === null || cursor === void 0) return void 0;
+    cursor = cursor[segment];
+  }
+  return cursor;
+}
+function evaluateFieldClause(record, clause) {
+  const actual = readPath(record, clause.field);
+  const { op, value } = clause;
+  switch (op) {
+    case "==":
+      return actual === value;
+    case "!=":
+      return actual !== value;
+    case "<":
+      return isComparable(actual, value) && actual < value;
+    case "<=":
+      return isComparable(actual, value) && actual <= value;
+    case ">":
+      return isComparable(actual, value) && actual > value;
+    case ">=":
+      return isComparable(actual, value) && actual >= value;
+    case "in":
+      return Array.isArray(value) && value.includes(actual);
+    case "contains":
+      if (typeof actual === "string") return typeof value === "string" && actual.includes(value);
+      if (Array.isArray(actual)) return actual.includes(value);
+      return false;
+    case "startsWith":
+      return typeof actual === "string" && typeof value === "string" && actual.startsWith(value);
+    case "between": {
+      if (!Array.isArray(value) || value.length !== 2) return false;
+      const [lo, hi] = value;
+      if (!isComparable(actual, lo) || !isComparable(actual, hi)) return false;
+      return actual >= lo && actual <= hi;
+    }
+    default: {
+      const _exhaustive = op;
+      void _exhaustive;
+      return false;
+    }
+  }
+}
+function isComparable(a, b) {
+  if (typeof a === "number" && typeof b === "number") return true;
+  if (typeof a === "string" && typeof b === "string") return true;
+  if (a instanceof Date && b instanceof Date) return true;
+  return false;
+}
+function evaluateClause(record, clause) {
+  switch (clause.type) {
+    case "field":
+      return evaluateFieldClause(record, clause);
+    case "filter":
+      return clause.fn(record);
+    case "group":
+      if (clause.op === "and") {
+        for (const child of clause.clauses) {
+          if (!evaluateClause(record, child)) return false;
+        }
+        return true;
+      } else {
+        for (const child of clause.clauses) {
+          if (evaluateClause(record, child)) return true;
+        }
+        return false;
+      }
+  }
+}
+
+// src/query/builder.ts
+var EMPTY_PLAN = {
+  clauses: [],
+  orderBy: [],
+  limit: void 0,
+  offset: 0
+};
+var Query = class _Query {
+  source;
+  plan;
+  constructor(source, plan = EMPTY_PLAN) {
+    this.source = source;
+    this.plan = plan;
+  }
+  /** Add a field comparison. Multiple where() calls are AND-combined. */
+  where(field, op, value) {
+    const clause = { type: "field", field, op, value };
+    return new _Query(this.source, {
+      ...this.plan,
+      clauses: [...this.plan.clauses, clause]
+    });
+  }
+  /**
+   * 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) {
+    const sub = builder(new _Query(this.source));
+    const group = {
+      type: "group",
+      op: "or",
+      clauses: sub.plan.clauses
+    };
+    return new _Query(this.source, {
+      ...this.plan,
+      clauses: [...this.plan.clauses, group]
+    });
+  }
+  /**
+   * 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) {
+    const sub = builder(new _Query(this.source));
+    const group = {
+      type: "group",
+      op: "and",
+      clauses: sub.plan.clauses
+    };
+    return new _Query(this.source, {
+      ...this.plan,
+      clauses: [...this.plan.clauses, group]
+    });
+  }
+  /** Escape hatch: add an arbitrary predicate function. Not serializable. */
+  filter(fn) {
+    const clause = {
+      type: "filter",
+      fn
+    };
+    return new _Query(this.source, {
+      ...this.plan,
+      clauses: [...this.plan.clauses, clause]
+    });
+  }
+  /** Sort by a field. Subsequent calls are tie-breakers. */
+  orderBy(field, direction = "asc") {
+    return new _Query(this.source, {
+      ...this.plan,
+      orderBy: [...this.plan.orderBy, { field, direction }]
+    });
+  }
+  /** Cap the result size. */
+  limit(n) {
+    return new _Query(this.source, { ...this.plan, limit: n });
+  }
+  /** Skip the first N matching records (after ordering). */
+  offset(n) {
+    return new _Query(this.source, { ...this.plan, offset: n });
+  }
+  /** Execute the plan and return the matching records. */
+  toArray() {
+    return executePlanWithSource(this.source, this.plan);
+  }
+  /** Return the first matching record, or null. */
+  first() {
+    const result = executePlanWithSource(this.source, { ...this.plan, limit: 1 });
+    return result[0] ?? null;
+  }
+  /** Return the number of matching records (after where/filter, before limit). */
+  count() {
+    const { candidates, remainingClauses } = candidateRecords(this.source, this.plan.clauses);
+    if (remainingClauses.length === 0) return candidates.length;
+    return filterRecords(candidates, remainingClauses).length;
+  }
+  /**
+   * 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) {
+    if (!this.source.subscribe) {
+      throw new Error("Query source does not support subscriptions. Pass a source with a subscribe() method.");
+    }
+    cb(this.toArray());
+    return this.source.subscribe(() => cb(this.toArray()));
+  }
+  /**
+   * 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() {
+    return serializePlan(this.plan);
+  }
+};
+function executePlanWithSource(source, plan) {
+  const { candidates, remainingClauses } = candidateRecords(source, plan.clauses);
+  let result = remainingClauses.length === 0 ? [...candidates] : filterRecords(candidates, remainingClauses);
+  if (plan.orderBy.length > 0) {
+    result = sortRecords(result, plan.orderBy);
+  }
+  if (plan.offset > 0) {
+    result = result.slice(plan.offset);
+  }
+  if (plan.limit !== void 0) {
+    result = result.slice(0, plan.limit);
+  }
+  return result;
+}
+function candidateRecords(source, clauses) {
+  const indexes = source.getIndexes?.();
+  if (!indexes || !source.lookupById || clauses.length === 0) {
+    return { candidates: source.snapshot(), remainingClauses: clauses };
+  }
+  const lookupById = (id) => source.lookupById?.(id);
+  for (let i = 0; i < clauses.length; i++) {
+    const clause = clauses[i];
+    if (clause.type !== "field") continue;
+    if (!indexes.has(clause.field)) continue;
+    let ids = null;
+    if (clause.op === "==") {
+      ids = indexes.lookupEqual(clause.field, clause.value);
+    } else if (clause.op === "in" && Array.isArray(clause.value)) {
+      ids = indexes.lookupIn(clause.field, clause.value);
+    }
+    if (ids !== null) {
+      const remaining = [];
+      for (let j = 0; j < clauses.length; j++) {
+        if (j !== i) remaining.push(clauses[j]);
+      }
+      return {
+        candidates: materializeIds(ids, lookupById),
+        remainingClauses: remaining
+      };
+    }
+  }
+  return { candidates: source.snapshot(), remainingClauses: clauses };
+}
+function materializeIds(ids, lookupById) {
+  const out = [];
+  for (const id of ids) {
+    const record = lookupById(id);
+    if (record !== void 0) out.push(record);
+  }
+  return out;
+}
+function executePlan(records, plan) {
+  let result = filterRecords(records, plan.clauses);
+  if (plan.orderBy.length > 0) {
+    result = sortRecords(result, plan.orderBy);
+  }
+  if (plan.offset > 0) {
+    result = result.slice(plan.offset);
+  }
+  if (plan.limit !== void 0) {
+    result = result.slice(0, plan.limit);
+  }
+  return result;
+}
+function filterRecords(records, clauses) {
+  if (clauses.length === 0) return [...records];
+  const out = [];
+  for (const r of records) {
+    let matches = true;
+    for (const clause of clauses) {
+      if (!evaluateClause(r, clause)) {
+        matches = false;
+        break;
+      }
+    }
+    if (matches) out.push(r);
+  }
+  return out;
+}
+function sortRecords(records, orderBy) {
+  return [...records].sort((a, b) => {
+    for (const { field, direction } of orderBy) {
+      const av = readField(a, field);
+      const bv = readField(b, field);
+      const cmp = compareValues(av, bv);
+      if (cmp !== 0) return direction === "asc" ? cmp : -cmp;
+    }
+    return 0;
+  });
+}
+function readField(record, field) {
+  if (record === null || record === void 0) return void 0;
+  if (!field.includes(".")) {
+    return record[field];
+  }
+  const segments = field.split(".");
+  let cursor = record;
+  for (const segment of segments) {
+    if (cursor === null || cursor === void 0) return void 0;
+    cursor = cursor[segment];
+  }
+  return cursor;
+}
+function compareValues(a, b) {
+  if (a === void 0 || a === null) return b === void 0 || b === null ? 0 : 1;
+  if (b === void 0 || b === null) return -1;
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  if (typeof a === "string" && typeof b === "string") return a < b ? -1 : a > b ? 1 : 0;
+  if (a instanceof Date && b instanceof Date) return a.getTime() - b.getTime();
+  return 0;
+}
+function serializePlan(plan) {
+  return {
+    clauses: plan.clauses.map(serializeClause),
+    orderBy: plan.orderBy,
+    limit: plan.limit,
+    offset: plan.offset
+  };
+}
+function serializeClause(clause) {
+  if (clause.type === "filter") {
+    return { type: "filter", fn: "[function]" };
+  }
+  if (clause.type === "group") {
+    return {
+      type: "group",
+      op: clause.op,
+      clauses: clause.clauses.map(serializeClause)
+    };
+  }
+  return clause;
+}
+
+// src/query/indexes.ts
+var CollectionIndexes = class {
+  indexes = /* @__PURE__ */ new Map();
+  /**
+   * Declare an index. Subsequent record additions are tracked under it.
+   * Calling this twice for the same field is a no-op (idempotent).
+   */
+  declare(field) {
+    if (this.indexes.has(field)) return;
+    this.indexes.set(field, { field, buckets: /* @__PURE__ */ new Map() });
+  }
+  /** True if the given field has a declared index. */
+  has(field) {
+    return this.indexes.has(field);
+  }
+  /** All declared field names, in declaration order. */
+  fields() {
+    return [...this.indexes.keys()];
+  }
+  /**
+   * Build all declared indexes from a snapshot of records.
+   * Called once per hydration. O(N × indexes.size).
+   */
+  build(records) {
+    for (const idx of this.indexes.values()) {
+      idx.buckets.clear();
+      for (const { id, record } of records) {
+        addToIndex(idx, id, record);
+      }
+    }
+  }
+  /**
+   * 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(id, newRecord, previousRecord) {
+    if (this.indexes.size === 0) return;
+    if (previousRecord !== null) {
+      this.remove(id, previousRecord);
+    }
+    for (const idx of this.indexes.values()) {
+      addToIndex(idx, id, newRecord);
+    }
+  }
+  /**
+   * Remove a record from all indexes. Called by `Collection.delete()`
+   * (and as the first half of `upsert` for the update path).
+   */
+  remove(id, record) {
+    if (this.indexes.size === 0) return;
+    for (const idx of this.indexes.values()) {
+      removeFromIndex(idx, id, record);
+    }
+  }
+  /** Drop all index data. Called when the collection is invalidated. */
+  clear() {
+    for (const idx of this.indexes.values()) {
+      idx.buckets.clear();
+    }
+  }
+  /**
+   * 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, value) {
+    const idx = this.indexes.get(field);
+    if (!idx) return null;
+    const key = stringifyKey(value);
+    return idx.buckets.get(key) ?? EMPTY_SET;
+  }
+  /**
+   * 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, values) {
+    const idx = this.indexes.get(field);
+    if (!idx) return null;
+    const out = /* @__PURE__ */ new Set();
+    for (const value of values) {
+      const key = stringifyKey(value);
+      const bucket = idx.buckets.get(key);
+      if (bucket) {
+        for (const id of bucket) out.add(id);
+      }
+    }
+    return out;
+  }
+};
+var EMPTY_SET = /* @__PURE__ */ new Set();
+function stringifyKey(value) {
+  if (value === null || value === void 0) return "\0NULL\0";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (value instanceof Date) return value.toISOString();
+  return "\0OBJECT\0";
+}
+function addToIndex(idx, id, record) {
+  const value = readPath(record, idx.field);
+  if (value === null || value === void 0) return;
+  const key = stringifyKey(value);
+  let bucket = idx.buckets.get(key);
+  if (!bucket) {
+    bucket = /* @__PURE__ */ new Set();
+    idx.buckets.set(key, bucket);
+  }
+  bucket.add(id);
+}
+function removeFromIndex(idx, id, record) {
+  const value = readPath(record, idx.field);
+  if (value === null || value === void 0) return;
+  const key = stringifyKey(value);
+  const bucket = idx.buckets.get(key);
+  if (!bucket) return;
+  bucket.delete(id);
+  if (bucket.size === 0) idx.buckets.delete(key);
+}
+
+// src/cache/lru.ts
+var Lru = class {
+  entries = /* @__PURE__ */ new Map();
+  maxRecords;
+  maxBytes;
+  currentBytes = 0;
+  hits = 0;
+  misses = 0;
+  evictions = 0;
+  constructor(options) {
+    if (options.maxRecords === void 0 && options.maxBytes === void 0) {
+      throw new Error("Lru: must specify maxRecords, maxBytes, or both");
+    }
+    this.maxRecords = options.maxRecords;
+    this.maxBytes = options.maxBytes;
+  }
+  /**
+   * Look up a key. Hits promote the entry to most-recently-used; misses
+   * return undefined. Both update the running stats counters.
+   */
+  get(key) {
+    const entry = this.entries.get(key);
+    if (!entry) {
+      this.misses++;
+      return void 0;
+    }
+    this.entries.delete(key);
+    this.entries.set(key, entry);
+    this.hits++;
+    return entry.value;
+  }
+  /**
+   * 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, value, size) {
+    const existing = this.entries.get(key);
+    if (existing) {
+      this.currentBytes -= existing.size;
+      this.entries.delete(key);
+    }
+    this.entries.set(key, { value, size });
+    this.currentBytes += size;
+    this.evictUntilUnderBudget();
+  }
+  /**
+   * Remove a key without affecting hit/miss stats. Used by `Collection.delete()`.
+   * Returns true if the key was present.
+   */
+  remove(key) {
+    const existing = this.entries.get(key);
+    if (!existing) return false;
+    this.currentBytes -= existing.size;
+    this.entries.delete(key);
+    return true;
+  }
+  /** True if the cache currently holds an entry for the given key. */
+  has(key) {
+    return this.entries.has(key);
   }
-  if (typeof oldObj !== typeof newObj) {
-    return [{ path: basePath || "(root)", type: "changed", from: oldObj, to: newObj }];
+  /**
+   * Drop every entry. Stats counters survive — call `resetStats()` if you
+   * want a clean slate. Used by `Collection.invalidate()` on key rotation.
+   */
+  clear() {
+    this.entries.clear();
+    this.currentBytes = 0;
+  }
+  /** Reset hit/miss/eviction counters to zero. Does NOT touch entries. */
+  resetStats() {
+    this.hits = 0;
+    this.misses = 0;
+    this.evictions = 0;
+  }
+  /** Snapshot of current cache statistics. Cheap — no copying. */
+  stats() {
+    return {
+      hits: this.hits,
+      misses: this.misses,
+      evictions: this.evictions,
+      size: this.entries.size,
+      bytes: this.currentBytes
+    };
   }
-  if (typeof oldObj !== "object") {
-    return [{ path: basePath || "(root)", type: "changed", from: oldObj, to: newObj }];
+  /**
+   * 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() {
+    for (const entry of this.entries.values()) yield entry.value;
   }
-  if (Array.isArray(oldObj) && Array.isArray(newObj)) {
-    const maxLen = Math.max(oldObj.length, newObj.length);
-    for (let i = 0; i < maxLen; i++) {
-      const p = basePath ? `${basePath}[${i}]` : `[${i}]`;
-      if (i >= oldObj.length) {
-        changes.push({ path: p, type: "added", to: newObj[i] });
-      } else if (i >= newObj.length) {
-        changes.push({ path: p, type: "removed", from: oldObj[i] });
-      } else {
-        changes.push(...diff(oldObj[i], newObj[i], p));
-      }
+  /**
+   * 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.
+   */
+  evictUntilUnderBudget() {
+    while (this.overBudget()) {
+      const oldest = this.entries.keys().next();
+      if (oldest.done) return;
+      const key = oldest.value;
+      const entry = this.entries.get(key);
+      if (entry) this.currentBytes -= entry.size;
+      this.entries.delete(key);
+      this.evictions++;
     }
-    return changes;
   }
-  const oldRecord = oldObj;
-  const newRecord = newObj;
-  const allKeys = /* @__PURE__ */ new Set([...Object.keys(oldRecord), ...Object.keys(newRecord)]);
-  for (const key of allKeys) {
-    const p = basePath ? `${basePath}.${key}` : key;
-    if (!(key in oldRecord)) {
-      changes.push({ path: p, type: "added", to: newRecord[key] });
-    } else if (!(key in newRecord)) {
-      changes.push({ path: p, type: "removed", from: oldRecord[key] });
-    } else {
-      changes.push(...diff(oldRecord[key], newRecord[key], p));
+  overBudget() {
+    if (this.maxRecords !== void 0 && this.entries.size > this.maxRecords) return true;
+    if (this.maxBytes !== void 0 && this.currentBytes > this.maxBytes) return true;
+    return false;
+  }
+};
+
+// src/cache/policy.ts
+var UNITS = {
+  "": 1,
+  "B": 1,
+  "KB": 1024,
+  "MB": 1024 * 1024,
+  "GB": 1024 * 1024 * 1024
+  // 'TB' deliberately not supported — if you need it, you're not using NOYDB.
+};
+function parseBytes(input) {
+  if (typeof input === "number") {
+    if (!Number.isFinite(input) || input <= 0) {
+      throw new Error(`parseBytes: numeric input must be a positive finite number, got ${String(input)}`);
     }
+    return Math.floor(input);
   }
-  return changes;
+  const trimmed = input.trim();
+  if (trimmed === "") {
+    throw new Error("parseBytes: empty string is not a valid byte budget");
+  }
+  const match = /^([0-9]+(?:\.[0-9]+)?)\s*([A-Za-z]*)$/.exec(trimmed);
+  if (!match) {
+    throw new Error(`parseBytes: invalid byte budget "${input}". Expected format: "1024", "50KB", "50MB", "1GB"`);
+  }
+  const value = parseFloat(match[1]);
+  const unit = (match[2] ?? "").toUpperCase();
+  if (!(unit in UNITS)) {
+    throw new Error(`parseBytes: unknown unit "${match[2]}" in "${input}". Supported: B, KB, MB, GB`);
+  }
+  const bytes = Math.floor(value * UNITS[unit]);
+  if (bytes <= 0) {
+    throw new Error(`parseBytes: byte budget must be > 0, got ${bytes} from "${input}"`);
+  }
+  return bytes;
 }
-function formatDiff(changes) {
-  if (changes.length === 0) return "(no changes)";
-  return changes.map((c) => {
-    switch (c.type) {
-      case "added":
-        return `+ ${c.path}: ${JSON.stringify(c.to)}`;
-      case "removed":
-        return `- ${c.path}: ${JSON.stringify(c.from)}`;
-      case "changed":
-        return `~ ${c.path}: ${JSON.stringify(c.from)} \u2192 ${JSON.stringify(c.to)}`;
-    }
-  }).join("\n");
+function estimateRecordBytes(record) {
+  try {
+    return JSON.stringify(record).length;
+  } catch {
+    return 0;
+  }
 }
 
 // src/collection.ts
+var fallbackWarned = /* @__PURE__ */ new Set();
+function warnOnceFallback(adapterName) {
+  if (fallbackWarned.has(adapterName)) return;
+  fallbackWarned.add(adapterName);
+  if (typeof process !== "undefined" && process.env["NODE_ENV"] === "test") return;
+  console.warn(
+    `[noy-db] Adapter "${adapterName}" does not implement listPage(); Collection.scan()/listPage() are using a synthetic fallback (slower). Add a listPage method to opt into the streaming fast path.`
+  );
+}
 var Collection = class {
   adapter;
   compartment;
@@ -594,9 +2030,91 @@ var Collection = class {
   getDEK;
   onDirty;
   historyConfig;
-  // In-memory cache of decrypted records
+  // In-memory cache of decrypted records (eager mode only). Lazy mode
+  // uses `lru` instead. Both fields exist so a single Collection instance
+  // doesn't need a runtime branch on every cache access.
   cache = /* @__PURE__ */ new Map();
   hydrated = false;
+  /**
+   * 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.
+   */
+  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.
+   */
+  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.
+   */
+  indexes = new CollectionIndexes();
+  /**
+   * 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>`.
+   */
+  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.
+   */
+  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).
+   */
+  refEnforcer;
   constructor(opts) {
     this.adapter = opts.adapter;
     this.compartment = opts.compartment;
@@ -607,9 +2125,46 @@ var Collection = class {
     this.getDEK = opts.getDEK;
     this.onDirty = opts.onDirty;
     this.historyConfig = opts.historyConfig ?? { enabled: true };
+    this.schema = opts.schema;
+    this.ledger = opts.ledger;
+    this.refEnforcer = opts.refEnforcer;
+    this.lazy = opts.prefetch === false;
+    if (this.lazy) {
+      if (opts.indexes && opts.indexes.length > 0) {
+        throw new Error(
+          `Collection "${this.name}": secondary indexes are not supported in lazy mode (prefetch: false). Either remove the indexes option or use prefetch: true. Index + lazy support is tracked as a v0.4 follow-up.`
+        );
+      }
+      if (!opts.cache || opts.cache.maxRecords === void 0 && opts.cache.maxBytes === void 0) {
+        throw new Error(
+          `Collection "${this.name}": lazy mode (prefetch: false) requires a cache option with maxRecords and/or maxBytes. An unbounded lazy cache defeats the purpose.`
+        );
+      }
+      const lruOptions = {};
+      if (opts.cache.maxRecords !== void 0) lruOptions.maxRecords = opts.cache.maxRecords;
+      if (opts.cache.maxBytes !== void 0) lruOptions.maxBytes = parseBytes(opts.cache.maxBytes);
+      this.lru = new Lru(lruOptions);
+      this.hydrated = true;
+    } else {
+      this.lru = null;
+      if (opts.indexes) {
+        for (const def of opts.indexes) {
+          this.indexes.declare(def);
+        }
+      }
+    }
   }
   /** Get a single record by ID. Returns null if not found. */
   async get(id) {
+    if (this.lazy && this.lru) {
+      const cached = this.lru.get(id);
+      if (cached) return cached.record;
+      const envelope = await this.adapter.get(this.compartment, this.name, id);
+      if (!envelope) return null;
+      const record = await this.decryptRecord(envelope);
+      this.lru.set(id, { record, version: envelope._v }, estimateRecordBytes(record));
+      return record;
+    }
     await this.ensureHydrated();
     const entry = this.cache.get(id);
     return entry ? entry.record : null;
@@ -619,8 +2174,26 @@ var Collection = class {
     if (!hasWritePermission(this.keyring, this.name)) {
       throw new ReadOnlyError();
     }
-    await this.ensureHydrated();
-    const existing = this.cache.get(id);
+    if (this.schema !== void 0) {
+      record = await validateSchemaInput(this.schema, record, `put(${id})`);
+    }
+    if (this.refEnforcer !== void 0) {
+      await this.refEnforcer.enforceRefsOnPut(this.name, record);
+    }
+    let existing;
+    if (this.lazy && this.lru) {
+      existing = this.lru.get(id);
+      if (!existing) {
+        const previousEnvelope = await this.adapter.get(this.compartment, this.name, id);
+        if (previousEnvelope) {
+          const previousRecord = await this.decryptRecord(previousEnvelope);
+          existing = { record: previousRecord, version: previousEnvelope._v };
+        }
+      }
+    } else {
+      await this.ensureHydrated();
+      existing = this.cache.get(id);
+    }
     const version = existing ? existing.version + 1 : 1;
     if (existing && this.historyConfig.enabled !== false) {
       const historyEnvelope = await this.encryptRecord(existing.record, existing.version);
@@ -639,7 +2212,26 @@ var Collection = class {
     }
     const envelope = await this.encryptRecord(record, version);
     await this.adapter.put(this.compartment, this.name, id, envelope);
-    this.cache.set(id, { record, version });
+    if (this.ledger) {
+      const appendInput = {
+        op: "put",
+        collection: this.name,
+        id,
+        version,
+        actor: this.keyring.userId,
+        payloadHash: await envelopePayloadHash(envelope)
+      };
+      if (existing) {
+        appendInput.delta = computePatch(record, existing.record);
+      }
+      await this.ledger.append(appendInput);
+    }
+    if (this.lazy && this.lru) {
+      this.lru.set(id, { record, version }, estimateRecordBytes(record));
+    } else {
+      this.cache.set(id, { record, version });
+      this.indexes.upsert(id, record, existing ? existing.record : null);
+    }
     await this.onDirty?.(this.name, id, "put", version);
     this.emitter.emit("change", {
       compartment: this.compartment,
@@ -653,13 +2245,47 @@ var Collection = class {
     if (!hasWritePermission(this.keyring, this.name)) {
       throw new ReadOnlyError();
     }
-    const existing = this.cache.get(id);
+    if (this.refEnforcer !== void 0) {
+      await this.refEnforcer.enforceRefsOnDelete(this.name, id);
+    }
+    let existing;
+    if (this.lazy && this.lru) {
+      existing = this.lru.get(id);
+      if (!existing && this.historyConfig.enabled !== false) {
+        const previousEnvelope2 = await this.adapter.get(this.compartment, this.name, id);
+        if (previousEnvelope2) {
+          const previousRecord = await this.decryptRecord(previousEnvelope2);
+          existing = { record: previousRecord, version: previousEnvelope2._v };
+        }
+      }
+    } else {
+      existing = this.cache.get(id);
+    }
     if (existing && this.historyConfig.enabled !== false) {
       const historyEnvelope = await this.encryptRecord(existing.record, existing.version);
       await saveHistory(this.adapter, this.compartment, this.name, id, historyEnvelope);
     }
+    const previousEnvelope = await this.adapter.get(this.compartment, this.name, id);
+    const previousPayloadHash = await envelopePayloadHash(previousEnvelope);
     await this.adapter.delete(this.compartment, this.name, id);
-    this.cache.delete(id);
+    if (this.ledger) {
+      await this.ledger.append({
+        op: "delete",
+        collection: this.name,
+        id,
+        version: existing?.version ?? 0,
+        actor: this.keyring.userId,
+        payloadHash: previousPayloadHash
+      });
+    }
+    if (this.lazy && this.lru) {
+      this.lru.remove(id);
+    } else {
+      this.cache.delete(id);
+      if (existing) {
+        this.indexes.remove(id, existing.record);
+      }
+    }
     await this.onDirty?.(this.name, id, "delete", existing?.version ?? 0);
     this.emitter.emit("change", {
       compartment: this.compartment,
@@ -668,14 +2294,70 @@ var Collection = class {
       action: "delete"
     });
   }
-  /** 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.
+   */
   async list() {
+    if (this.lazy) {
+      throw new Error(
+        `Collection "${this.name}": list() is not available in lazy mode (prefetch: false). Use collection.scan({ pageSize }) to iterate over the full collection.`
+      );
+    }
     await this.ensureHydrated();
     return [...this.cache.values()].map((e) => e.record);
   }
-  /** Filter records by a predicate. */
   query(predicate) {
-    return [...this.cache.values()].map((e) => e.record).filter(predicate);
+    if (this.lazy) {
+      throw new Error(
+        `Collection "${this.name}": query() is not available in lazy mode (prefetch: false). Use collection.scan({ pageSize }) and filter the streamed records with a regular for-await loop. Streaming queries land in v0.4.`
+      );
+    }
+    if (predicate !== void 0) {
+      return [...this.cache.values()].map((e) => e.record).filter(predicate);
+    }
+    const source = {
+      snapshot: () => [...this.cache.values()].map((e) => e.record),
+      subscribe: (cb) => {
+        const handler = (event) => {
+          if (event.compartment === this.compartment && event.collection === this.name) {
+            cb();
+          }
+        };
+        this.emitter.on("change", handler);
+        return () => this.emitter.off("change", handler);
+      },
+      // Index-aware fast path for `==` and `in` operators on indexed
+      // fields. The Query builder consults these when present and falls
+      // back to a linear scan otherwise.
+      getIndexes: () => this.getIndexes(),
+      lookupById: (id) => this.cache.get(id)?.record
+    };
+    return new Query(source);
+  }
+  /**
+   * 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() {
+    if (this.lazy && this.lru) {
+      return { ...this.lru.stats(), lazy: true };
+    }
+    return {
+      hits: 0,
+      misses: 0,
+      evictions: 0,
+      size: this.cache.size,
+      bytes: 0,
+      lazy: false
+    };
   }
   // ─── History Methods ────────────────────────────────────────────
   /** Get version history for a record, newest first. */
@@ -689,7 +2371,7 @@ var Collection = class {
     );
     const entries = [];
     for (const env of envelopes) {
-      const record = await this.decryptRecord(env);
+      const record = await this.decryptRecord(env, { skipValidation: true });
       entries.push({
         version: env._v,
         timestamp: env._ts,
@@ -699,7 +2381,15 @@ var Collection = class {
     }
     return entries;
   }
-  /** 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.
+   */
   async getVersion(id, version) {
     const envelope = await getVersionEnvelope(
       this.adapter,
@@ -709,7 +2399,7 @@ var Collection = class {
       version
     );
     if (!envelope) return null;
-    return this.decryptRecord(envelope);
+    return this.decryptRecord(envelope, { skipValidation: true });
   }
   /** Revert a record to a past version. Creates a new version with the old content. */
   async revert(id, version) {
@@ -727,7 +2417,7 @@ var Collection = class {
   async diff(id, versionA, versionB) {
     const recordA = versionA === 0 ? null : await this.resolveVersion(id, versionA);
     const recordB = versionB === void 0 || versionB === 0 ? versionB === 0 ? null : await this.resolveCurrentOrVersion(id) : await this.resolveVersion(id, versionB);
-    return diff(recordA, recordB);
+    return diff2(recordA, recordB);
   }
   /** Resolve a version: try history first, then check if it's the current version. */
   async resolveVersion(id, version) {
@@ -766,11 +2456,105 @@ var Collection = class {
     return clearHistory(this.adapter, this.compartment, this.name, id);
   }
   // ─── Core Methods ─────────────────────────────────────────────
-  /** 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.
+   */
   async count() {
+    if (this.lazy) {
+      const ids = await this.adapter.list(this.compartment, this.name);
+      return ids.length;
+    }
     await this.ensureHydrated();
     return this.cache.size;
   }
+  // ─── Pagination & Streaming ───────────────────────────────────
+  /**
+   * 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.
+   */
+  async listPage(opts = {}) {
+    const limit = opts.limit ?? 100;
+    if (this.adapter.listPage) {
+      const result = await this.adapter.listPage(this.compartment, this.name, opts.cursor, limit);
+      const decrypted = [];
+      for (const { record, version, id } of await this.decryptPage(result.items)) {
+        if (!this.lazy && !this.cache.has(id)) {
+          this.cache.set(id, { record, version });
+        }
+        decrypted.push(record);
+      }
+      return { items: decrypted, nextCursor: result.nextCursor };
+    }
+    warnOnceFallback(this.adapter.name ?? "unknown");
+    const ids = (await this.adapter.list(this.compartment, this.name)).slice().sort();
+    const start = opts.cursor ? parseInt(opts.cursor, 10) : 0;
+    const end = Math.min(start + limit, ids.length);
+    const items = [];
+    for (let i = start; i < end; i++) {
+      const id = ids[i];
+      const envelope = await this.adapter.get(this.compartment, this.name, id);
+      if (envelope) {
+        const record = await this.decryptRecord(envelope);
+        items.push(record);
+        if (!this.lazy && !this.cache.has(id)) {
+          this.cache.set(id, { record, version: envelope._v });
+        }
+      }
+    }
+    return {
+      items,
+      nextCursor: end < ids.length ? String(end) : 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.
+   */
+  async *scan(opts = {}) {
+    const pageSize = opts.pageSize ?? 100;
+    let page = await this.listPage({ limit: pageSize });
+    while (true) {
+      for (const item of page.items) {
+        yield item;
+      }
+      if (page.nextCursor === null) return;
+      page = await this.listPage({ cursor: page.nextCursor, limit: pageSize });
+    }
+  }
+  /** Decrypt a page of envelopes returned by `adapter.listPage`. */
+  async decryptPage(items) {
+    const out = [];
+    for (const { id, envelope } of items) {
+      const record = await this.decryptRecord(envelope);
+      out.push({ id, record, version: envelope._v });
+    }
+    return out;
+  }
   // ─── Internal ──────────────────────────────────────────────────
   /** Load all records from adapter into memory cache. */
   async ensureHydrated() {
@@ -784,6 +2568,7 @@ var Collection = class {
       }
     }
     this.hydrated = true;
+    this.rebuildIndexes();
   }
   /** Hydrate from a pre-loaded snapshot (used by Compartment). */
   async hydrateFromSnapshot(records) {
@@ -792,6 +2577,34 @@ var Collection = class {
       this.cache.set(id, { record, version: envelope._v });
     }
     this.hydrated = true;
+    this.rebuildIndexes();
+  }
+  /**
+   * 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.
+   */
+  rebuildIndexes() {
+    if (this.indexes.fields().length === 0) return;
+    const snapshot = [];
+    for (const [id, entry] of this.cache) {
+      snapshot.push({ id, record: entry.record });
+    }
+    this.indexes.build(snapshot);
+  }
+  /**
+   * 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() {
+    return this.indexes.fields().length > 0 ? this.indexes : null;
   }
   /** Get all records as encrypted envelopes (for dump). */
   async dumpEnvelopes() {
@@ -826,13 +2639,38 @@ var Collection = class {
       _by: by
     };
   }
-  async decryptRecord(envelope) {
+  /**
+   * 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`.
+   */
+  async decryptRecord(envelope, opts = {}) {
+    let record;
     if (!this.encrypted) {
-      return JSON.parse(envelope._data);
+      record = JSON.parse(envelope._data);
+    } else {
+      const dek = await this.getDEK(this.name);
+      const json = await decrypt(envelope._iv, envelope._data, dek);
+      record = JSON.parse(json);
     }
-    const dek = await this.getDEK(this.name);
-    const json = await decrypt(envelope._iv, envelope._data, dek);
-    return JSON.parse(json);
+    if (this.schema !== void 0 && !opts.skipValidation) {
+      record = await validateSchemaOutput(
+        this.schema,
+        record,
+        `${this.name}@v${envelope._v}`
+      );
+    }
+    return record;
   }
 };
 
@@ -840,13 +2678,62 @@ var Collection = class {
 var Compartment = class {
   adapter;
   name;
+  /**
+   * 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.
+   */
   keyring;
   encrypted;
   emitter;
   onDirty;
   historyConfig;
   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).
+   */
+  reloadKeyring;
   collectionCache = /* @__PURE__ */ new Map();
+  /**
+   * 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.
+   */
+  ledgerStore = null;
+  /**
+   * 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.
+   */
+  refRegistry = new 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.
+   */
+  cascadeInProgress = /* @__PURE__ */ new Set();
   constructor(opts) {
     this.adapter = opts.adapter;
     this.name = opts.name;
@@ -855,19 +2742,53 @@ var Compartment = class {
     this.emitter = opts.emitter;
     this.onDirty = opts.onDirty;
     this.historyConfig = opts.historyConfig ?? { enabled: true };
+    this.reloadKeyring = opts.reloadKeyring;
+    this.getDEK = this.makeGetDEK();
+  }
+  /**
+   * 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.
+   */
+  makeGetDEK() {
     let getDEKFn = null;
-    this.getDEK = async (collectionName) => {
+    return async (collectionName) => {
       if (!getDEKFn) {
         getDEKFn = await ensureCollectionDEK(this.adapter, this.name, this.keyring);
       }
       return getDEKFn(collectionName);
     };
   }
-  /** Open a typed collection within this compartment. */
-  collection(collectionName) {
+  /**
+   * 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(collectionName, options) {
     let coll = this.collectionCache.get(collectionName);
     if (!coll) {
-      coll = new Collection({
+      if (options?.refs) {
+        this.refRegistry.register(collectionName, options.refs);
+      }
+      const collOpts = {
         adapter: this.adapter,
         compartment: this.name,
         name: collectionName,
@@ -876,18 +2797,205 @@ var Compartment = class {
         emitter: this.emitter,
         getDEK: this.getDEK,
         onDirty: this.onDirty,
-        historyConfig: this.historyConfig
-      });
+        historyConfig: this.historyConfig,
+        ledger: this.ledger(),
+        refEnforcer: this
+      };
+      if (options?.indexes !== void 0) collOpts.indexes = options.indexes;
+      if (options?.prefetch !== void 0) collOpts.prefetch = options.prefetch;
+      if (options?.cache !== void 0) collOpts.cache = options.cache;
+      if (options?.schema !== void 0) collOpts.schema = options.schema;
+      coll = new Collection(collOpts);
       this.collectionCache.set(collectionName, coll);
     }
     return coll;
   }
+  /**
+   * 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()`.
+   */
+  async enforceRefsOnPut(collectionName, record) {
+    const outbound = this.refRegistry.getOutbound(collectionName);
+    if (Object.keys(outbound).length === 0) return;
+    if (!record || typeof record !== "object") return;
+    const obj = record;
+    for (const [field, descriptor] of Object.entries(outbound)) {
+      if (descriptor.mode !== "strict") continue;
+      const rawId = obj[field];
+      if (rawId === null || rawId === void 0) continue;
+      if (typeof rawId !== "string" && typeof rawId !== "number") {
+        throw new RefIntegrityError({
+          collection: collectionName,
+          id: obj["id"] ?? "<unknown>",
+          field,
+          refTo: descriptor.target,
+          refId: null,
+          message: `Ref field "${collectionName}.${field}" must be a string or number, got ${typeof rawId}.`
+        });
+      }
+      const refId = String(rawId);
+      const target = this.collection(descriptor.target);
+      const exists = await target.get(refId);
+      if (!exists) {
+        throw new RefIntegrityError({
+          collection: collectionName,
+          id: obj["id"] ?? "<unknown>",
+          field,
+          refTo: descriptor.target,
+          refId,
+          message: `Strict ref "${collectionName}.${field}" \u2192 "${descriptor.target}" cannot be satisfied: target id "${refId}" not found in "${descriptor.target}".`
+        });
+      }
+    }
+  }
+  /**
+   * 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.
+   */
+  async enforceRefsOnDelete(collectionName, id) {
+    const key = `${collectionName}/${id}`;
+    if (this.cascadeInProgress.has(key)) return;
+    this.cascadeInProgress.add(key);
+    try {
+      const inbound = this.refRegistry.getInbound(collectionName);
+      for (const rule of inbound) {
+        const fromCollection = this.collection(rule.collection);
+        const allRecords = await fromCollection.list();
+        const matches = allRecords.filter((rec) => {
+          const raw = rec[rule.field];
+          if (typeof raw !== "string" && typeof raw !== "number") return false;
+          return String(raw) === id;
+        });
+        if (matches.length === 0) continue;
+        if (rule.mode === "strict") {
+          const first = matches[0];
+          throw new RefIntegrityError({
+            collection: rule.collection,
+            id: first?.["id"] ?? "<unknown>",
+            field: rule.field,
+            refTo: collectionName,
+            refId: id,
+            message: `Cannot delete "${collectionName}"/"${id}": ${matches.length} record(s) in "${rule.collection}" still reference it via strict ref "${rule.field}".`
+          });
+        }
+        if (rule.mode === "cascade") {
+          for (const match of matches) {
+            const matchId = match["id"] ?? null;
+            if (matchId === null) continue;
+            await fromCollection.delete(matchId);
+          }
+        }
+      }
+    } finally {
+      this.cascadeInProgress.delete(key);
+    }
+  }
+  /**
+   * 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.
+   */
+  async checkIntegrity() {
+    const violations = [];
+    for (const [collectionName, refs] of this.refRegistry.entries()) {
+      const coll = this.collection(collectionName);
+      const records = await coll.list();
+      for (const record of records) {
+        const recId = record["id"] ?? "<unknown>";
+        for (const [field, descriptor] of Object.entries(refs)) {
+          const rawId = record[field];
+          if (rawId === null || rawId === void 0) continue;
+          if (typeof rawId !== "string" && typeof rawId !== "number") {
+            violations.push({
+              collection: collectionName,
+              id: recId,
+              field,
+              refTo: descriptor.target,
+              refId: rawId,
+              mode: descriptor.mode
+            });
+            continue;
+          }
+          const refId = String(rawId);
+          const target = this.collection(descriptor.target);
+          const exists = await target.get(refId);
+          if (!exists) {
+            violations.push({
+              collection: collectionName,
+              id: recId,
+              field,
+              refTo: descriptor.target,
+              refId: rawId,
+              mode: descriptor.mode
+            });
+          }
+        }
+      }
+    }
+    return { violations };
+  }
+  /**
+   * 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() {
+    if (!this.ledgerStore) {
+      this.ledgerStore = new LedgerStore({
+        adapter: this.adapter,
+        compartment: this.name,
+        encrypted: this.encrypted,
+        getDEK: this.getDEK,
+        actor: this.keyring.userId
+      });
+    }
+    return this.ledgerStore;
+  }
   /** List all collection names in this compartment. */
   async collections() {
     const snapshot = await this.adapter.loadAll(this.name);
     return Object.keys(snapshot);
   }
-  /** 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.
+   */
   async dump() {
     const snapshot = await this.adapter.loadAll(this.name);
     const keyringIds = await this.adapter.list(this.name, "_keyring");
@@ -898,17 +3006,58 @@ var Compartment = class {
         keyrings[keyringId] = JSON.parse(envelope._data);
       }
     }
+    const internalSnapshot = {};
+    for (const internalName of [LEDGER_COLLECTION, LEDGER_DELTAS_COLLECTION]) {
+      const ids = await this.adapter.list(this.name, internalName);
+      if (ids.length === 0) continue;
+      const records = {};
+      for (const id of ids) {
+        const envelope = await this.adapter.get(this.name, internalName, id);
+        if (envelope) records[id] = envelope;
+      }
+      internalSnapshot[internalName] = records;
+    }
+    const head = await this.ledger().head();
     const backup = {
       _noydb_backup: NOYDB_BACKUP_VERSION,
       _compartment: this.name,
       _exported_at: (/* @__PURE__ */ new Date()).toISOString(),
       _exported_by: this.keyring.userId,
       keyrings,
-      collections: snapshot
+      collections: snapshot,
+      ...Object.keys(internalSnapshot).length > 0 ? { _internal: internalSnapshot } : {},
+      ...head ? {
+        ledgerHead: {
+          hash: head.hash,
+          index: head.entry.index,
+          ts: head.entry.ts
+        }
+      } : {}
     };
     return JSON.stringify(backup);
   }
-  /** 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.
+   */
   async load(backupJson) {
     const backup = JSON.parse(backupJson);
     await this.adapter.saveAll(this.name, backup.collections);
@@ -922,7 +3071,124 @@ var Compartment = class {
       };
       await this.adapter.put(this.name, "_keyring", userId, envelope);
     }
+    if (backup._internal) {
+      for (const [internalName, records] of Object.entries(backup._internal)) {
+        for (const [id, envelope] of Object.entries(records)) {
+          await this.adapter.put(this.name, internalName, id, envelope);
+        }
+      }
+    }
+    if (this.reloadKeyring) {
+      this.keyring = await this.reloadKeyring();
+      this.getDEK = this.makeGetDEK();
+    }
     this.collectionCache.clear();
+    this.ledgerStore = null;
+    if (!backup.ledgerHead) {
+      console.warn(
+        `[noy-db] Loaded a legacy backup with no ledgerHead \u2014 verifiable-backup integrity check skipped. Re-export with v0.4+ to get tamper detection.`
+      );
+      return;
+    }
+    const result = await this.verifyBackupIntegrity();
+    if (!result.ok) {
+      if (result.kind === "data") {
+        throw new BackupCorruptedError(
+          result.collection,
+          result.id,
+          result.message
+        );
+      }
+      throw new BackupLedgerError(result.message, result.divergedAt);
+    }
+    if (result.head !== backup.ledgerHead.hash) {
+      throw new BackupLedgerError(
+        `Backup ledger head mismatch: embedded "${backup.ledgerHead.hash}" but reconstructed "${result.head}".`
+      );
+    }
+  }
+  /**
+   * 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.
+   */
+  async verifyBackupIntegrity() {
+    const chainResult = await this.ledger().verify();
+    if (!chainResult.ok) {
+      return {
+        ok: false,
+        kind: "chain",
+        divergedAt: chainResult.divergedAt,
+        message: `Ledger chain diverged at index ${chainResult.divergedAt}: expected prevHash "${chainResult.expected}" but found "${chainResult.actual}".`
+      };
+    }
+    const ledger = this.ledger();
+    const allEntries = await ledger.loadAllEntries();
+    const seen = /* @__PURE__ */ new Set();
+    const latest = /* @__PURE__ */ new Map();
+    for (let i = allEntries.length - 1; i >= 0; i--) {
+      const entry = allEntries[i];
+      if (!entry) continue;
+      const key = `${entry.collection}/${entry.id}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      if (entry.op === "delete") continue;
+      latest.set(key, {
+        collection: entry.collection,
+        id: entry.id,
+        expectedHash: entry.payloadHash
+      });
+    }
+    for (const { collection, id, expectedHash } of latest.values()) {
+      const envelope = await this.adapter.get(this.name, collection, id);
+      if (!envelope) {
+        return {
+          ok: false,
+          kind: "data",
+          collection,
+          id,
+          message: `Ledger expects data record "${collection}/${id}" to exist, but the adapter has no envelope for it.`
+        };
+      }
+      const actualHash = await sha256Hex(envelope._data);
+      if (actualHash !== expectedHash) {
+        return {
+          ok: false,
+          kind: "data",
+          collection,
+          id,
+          message: `Data envelope "${collection}/${id}" has been tampered with: expected payloadHash "${expectedHash}", got "${actualHash}".`
+        };
+      }
+    }
+    return {
+      ok: true,
+      head: chainResult.head,
+      length: chainResult.length
+    };
   }
   /** Export compartment as decrypted JSON (owner only). */
   async export() {
@@ -1288,7 +3554,23 @@ var Noydb = class {
       encrypted: this.options.encrypt !== false,
       emitter: this.emitter,
       onDirty: syncEngine ? (coll, id, action, version) => syncEngine.trackChange(coll, id, action, version) : void 0,
-      historyConfig: this.options.history
+      historyConfig: this.options.history,
+      // Refresh callback used by Compartment.load() to re-derive
+      // the in-memory keyring from a freshly-loaded keyring file.
+      // Encrypted compartments need this so post-load decrypts work
+      // against the loaded session's wrapped DEKs; plaintext
+      // compartments leave it null and load() skips the refresh.
+      reloadKeyring: this.options.encrypt !== false && this.options.secret ? async () => {
+        this.keyringCache.delete(name);
+        const refreshed = await loadKeyring(
+          this.options.adapter,
+          name,
+          this.options.user,
+          this.options.secret
+        );
+        this.keyringCache.set(name, refreshed);
+        return refreshed;
+      } : void 0
     });
     this.compartmentCache.set(name, comp);
     return comp;
@@ -1576,11 +3858,18 @@ function estimateEntropy(passphrase) {
   return Math.floor(passphrase.length * Math.log2(charsetSize));
 }
 export {
+  BackupCorruptedError,
+  BackupLedgerError,
   Collection,
+  CollectionIndexes,
   Compartment,
   ConflictError,
   DecryptionError,
   InvalidKeyError,
+  LEDGER_COLLECTION,
+  LEDGER_DELTAS_COLLECTION,
+  LedgerStore,
+  Lru,
   NOYDB_BACKUP_VERSION,
   NOYDB_FORMAT_VERSION,
   NOYDB_KEYRING_VERSION,
@@ -1591,21 +3880,43 @@ export {
   Noydb,
   NoydbError,
   PermissionDeniedError,
+  Query,
   ReadOnlyError,
+  RefIntegrityError,
+  RefRegistry,
+  RefScopeError,
+  SchemaValidationError,
   SyncEngine,
   TamperedError,
   ValidationError,
+  applyPatch,
+  canonicalJson,
+  computePatch,
   createNoydb,
   defineAdapter,
-  diff,
+  diff2 as diff,
   enrollBiometric,
+  envelopePayloadHash,
   estimateEntropy,
+  estimateRecordBytes,
+  evaluateClause,
+  evaluateFieldClause,
+  executePlan,
   formatDiff,
+  hashEntry,
   isBiometricAvailable,
   loadBiometric,
+  paddedIndex,
+  parseBytes,
+  parseIndex,
+  readPath,
+  ref,
   removeBiometric,
   saveBiometric,
+  sha256Hex,
   unlockBiometric,
-  validatePassphrase
+  validatePassphrase,
+  validateSchemaInput,
+  validateSchemaOutput
 };
 //# sourceMappingURL=index.js.map