@noy-db/core 0.3.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,7 +1341,7 @@ 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) {
@@ -549,7 +1365,7 @@ function diff(oldObj, newObj, basePath = "") {
       } else if (i >= newObj.length) {
         changes.push({ path: p, type: "removed", from: oldObj[i] });
       } else {
-        changes.push(...diff(oldObj[i], newObj[i], p));
+        changes.push(...diff2(oldObj[i], newObj[i], p));
       }
     }
     return changes;
@@ -564,7 +1380,7 @@ function diff(oldObj, newObj, basePath = "") {
     } else if (!(key in newRecord)) {
       changes.push({ path: p, type: "removed", from: oldRecord[key] });
     } else {
-      changes.push(...diff(oldRecord[key], newRecord[key], p));
+      changes.push(...diff2(oldRecord[key], newRecord[key], p));
     }
   }
   return changes;
@@ -1249,6 +2065,56 @@ var Collection = class {
    * 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;
@@ -1259,6 +2125,9 @@ 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) {
@@ -1305,6 +2174,12 @@ var Collection = class {
     if (!hasWritePermission(this.keyring, this.name)) {
       throw new ReadOnlyError();
     }
+    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);
@@ -1337,6 +2212,20 @@ var Collection = class {
     }
     const envelope = await this.encryptRecord(record, version);
     await this.adapter.put(this.compartment, this.name, id, envelope);
+    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 {
@@ -1356,14 +2245,17 @@ var Collection = class {
     if (!hasWritePermission(this.keyring, this.name)) {
       throw new ReadOnlyError();
     }
+    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 previousEnvelope = await this.adapter.get(this.compartment, this.name, id);
-        if (previousEnvelope) {
-          const previousRecord = await this.decryptRecord(previousEnvelope);
-          existing = { record: previousRecord, version: previousEnvelope._v };
+        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 {
@@ -1373,7 +2265,19 @@ var Collection = class {
       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);
+    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 {
@@ -1467,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,
@@ -1477,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,
@@ -1487,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) {
@@ -1505,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) {
@@ -1727,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);
+    }
+    if (this.schema !== void 0 && !opts.skipValidation) {
+      record = await validateSchemaOutput(
+        this.schema,
+        record,
+        `${this.name}@v${envelope._v}`
+      );
     }
-    const dek = await this.getDEK(this.name);
-    const json = await decrypt(envelope._iv, envelope._data, dek);
-    return JSON.parse(json);
+    return record;
   }
 };
 
@@ -1741,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;
@@ -1756,8 +2742,21 @@ 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);
       }
@@ -1775,6 +2774,10 @@ var Compartment = class {
    *   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.
@@ -1782,6 +2785,9 @@ var Compartment = class {
   collection(collectionName, options) {
     let coll = this.collectionCache.get(collectionName);
     if (!coll) {
+      if (options?.refs) {
+        this.refRegistry.register(collectionName, options.refs);
+      }
       const collOpts = {
         adapter: this.adapter,
         compartment: this.name,
@@ -1791,22 +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");
@@ -1817,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);
@@ -1841,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() {
@@ -2207,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;
@@ -2495,12 +3858,17 @@ 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,
@@ -2514,26 +3882,41 @@ export {
   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