@noy-db/hub 0.1.0-pre.3

package/dist/history/index.cjs

@@ -0,0 +1,1215 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/history/index.ts
+var history_exports = {};
+__export(history_exports, {
+  CollectionInstant: () => CollectionInstant,
+  LEDGER_COLLECTION: () => LEDGER_COLLECTION,
+  LEDGER_DELTAS_COLLECTION: () => LEDGER_DELTAS_COLLECTION,
+  LedgerStore: () => LedgerStore,
+  VaultInstant: () => VaultInstant,
+  applyPatch: () => applyPatch,
+  canonicalJson: () => canonicalJson,
+  clearHistory: () => clearHistory,
+  computePatch: () => computePatch,
+  diff: () => diff,
+  envelopePayloadHash: () => envelopePayloadHash,
+  formatDiff: () => formatDiff,
+  getHistory: () => getHistory,
+  getVersionEnvelope: () => getVersionEnvelope,
+  hashEntry: () => hashEntry,
+  paddedIndex: () => paddedIndex,
+  parseIndex: () => parseIndex,
+  pruneHistory: () => pruneHistory,
+  saveHistory: () => saveHistory,
+  sha256Hex: () => sha256Hex,
+  withHistory: () => withHistory
+});
+module.exports = __toCommonJS(history_exports);
+
+// src/history/history.ts
+var HISTORY_COLLECTION = "_history";
+var VERSION_PAD = 10;
+function historyId(collection, recordId, version) {
+  return `${collection}:${recordId}:${String(version).padStart(VERSION_PAD, "0")}`;
+}
+function matchesPrefix(id, collection, recordId) {
+  if (recordId) {
+    return id.startsWith(`${collection}:${recordId}:`);
+  }
+  return id.startsWith(`${collection}:`);
+}
+async function saveHistory(adapter, vault, collection, recordId, envelope) {
+  const id = historyId(collection, recordId, envelope._v);
+  await adapter.put(vault, HISTORY_COLLECTION, id, envelope);
+}
+async function getHistory(adapter, vault, collection, recordId, options) {
+  const allIds = await adapter.list(vault, HISTORY_COLLECTION);
+  const matchingIds = allIds.filter((id) => matchesPrefix(id, collection, recordId)).sort().reverse();
+  const entries = [];
+  for (const id of matchingIds) {
+    const envelope = await adapter.get(vault, HISTORY_COLLECTION, id);
+    if (!envelope) continue;
+    if (options?.from && envelope._ts < options.from) continue;
+    if (options?.to && envelope._ts > options.to) continue;
+    entries.push(envelope);
+    if (options?.limit && entries.length >= options.limit) break;
+  }
+  return entries;
+}
+async function getVersionEnvelope(adapter, vault, collection, recordId, version) {
+  const id = historyId(collection, recordId, version);
+  return adapter.get(vault, HISTORY_COLLECTION, id);
+}
+async function pruneHistory(adapter, vault, collection, recordId, options) {
+  const allIds = await adapter.list(vault, HISTORY_COLLECTION);
+  const matchingIds = allIds.filter((id) => recordId ? matchesPrefix(id, collection, recordId) : matchesPrefix(id, collection)).sort();
+  let toDelete = [];
+  if (options.keepVersions !== void 0) {
+    const keep = options.keepVersions;
+    if (matchingIds.length > keep) {
+      toDelete = matchingIds.slice(0, matchingIds.length - keep);
+    }
+  }
+  if (options.beforeDate) {
+    for (const id of matchingIds) {
+      if (toDelete.includes(id)) continue;
+      const envelope = await adapter.get(vault, HISTORY_COLLECTION, id);
+      if (envelope && envelope._ts < options.beforeDate) {
+        toDelete.push(id);
+      }
+    }
+  }
+  const uniqueDeletes = [...new Set(toDelete)];
+  for (const id of uniqueDeletes) {
+    await adapter.delete(vault, HISTORY_COLLECTION, id);
+  }
+  return uniqueDeletes.length;
+}
+async function clearHistory(adapter, vault, collection, recordId) {
+  const allIds = await adapter.list(vault, HISTORY_COLLECTION);
+  let toDelete;
+  if (collection && recordId) {
+    toDelete = allIds.filter((id) => matchesPrefix(id, collection, recordId));
+  } else if (collection) {
+    toDelete = allIds.filter((id) => matchesPrefix(id, collection));
+  } else {
+    toDelete = allIds;
+  }
+  for (const id of toDelete) {
+    await adapter.delete(vault, HISTORY_COLLECTION, id);
+  }
+  return toDelete.length;
+}
+
+// src/history/diff.ts
+function diff(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 (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(...diff(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(...diff(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/types.ts
+var NOYDB_FORMAT_VERSION = 1;
+
+// src/errors.ts
+var NoydbError = class extends Error {
+  /** Machine-readable error code. Stable across library versions. */
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "NoydbError";
+    this.code = code;
+  }
+};
+var DecryptionError = class extends NoydbError {
+  constructor(message = "Decryption failed") {
+    super("DECRYPTION_FAILED", message);
+    this.name = "DecryptionError";
+  }
+};
+var TamperedError = class extends NoydbError {
+  constructor(message = "Data integrity check failed \u2014 record may have been tampered with") {
+    super("TAMPERED", message);
+    this.name = "TamperedError";
+  }
+};
+var ReadOnlyAtInstantError = class extends NoydbError {
+  constructor(operation, timestamp) {
+    super(
+      "READ_ONLY_AT_INSTANT",
+      `Cannot ${operation}() on a vault view anchored at ${timestamp} \u2014 time-machine views are read-only`
+    );
+    this.name = "ReadOnlyAtInstantError";
+  }
+};
+var ConflictError = class extends NoydbError {
+  /** The actual stored version at the time of conflict. */
+  version;
+  constructor(version, message = "Version conflict") {
+    super("CONFLICT", message);
+    this.name = "ConflictError";
+    this.version = version;
+  }
+};
+var LedgerContentionError = class extends NoydbError {
+  attempts;
+  constructor(attempts) {
+    super(
+      "LEDGER_CONTENTION",
+      `LedgerStore.append: failed to claim a chain slot after ${attempts} optimistic-CAS retries`
+    );
+    this.name = "LedgerContentionError";
+    this.attempts = attempts;
+  }
+};
+
+// src/crypto.ts
+var IV_BYTES = 12;
+var subtle = globalThis.crypto.subtle;
+async function encrypt(plaintext, dek) {
+  const iv = generateIV();
+  const encoded = new TextEncoder().encode(plaintext);
+  const ciphertext = await subtle.encrypt(
+    { name: "AES-GCM", iv },
+    dek,
+    encoded
+  );
+  return {
+    iv: bufferToBase64(iv),
+    data: bufferToBase64(ciphertext)
+  };
+}
+async function decrypt(ivBase64, dataBase64, dek) {
+  const iv = base64ToBuffer(ivBase64);
+  const ciphertext = base64ToBuffer(dataBase64);
+  try {
+    const plaintext = await subtle.decrypt(
+      { name: "AES-GCM", iv },
+      dek,
+      ciphertext
+    );
+    return new TextDecoder().decode(plaintext);
+  } catch (err) {
+    if (err instanceof Error && err.name === "OperationError") {
+      throw new TamperedError();
+    }
+    throw new DecryptionError(
+      err instanceof Error ? err.message : "Decryption failed"
+    );
+  }
+}
+function generateIV() {
+  return globalThis.crypto.getRandomValues(new Uint8Array(IV_BYTES));
+}
+function bufferToBase64(buffer) {
+  const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+function base64ToBuffer(base64) {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+// src/history/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/history/ledger/patch.ts
+function computePatch(prev, next) {
+  const ops = [];
+  diff2(prev, next, "", ops);
+  return ops;
+}
+function diff2(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 {
+        diff2(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/history/ledger/constants.ts
+var LEDGER_COLLECTION = "_ledger";
+var LEDGER_DELTAS_COLLECTION = "_ledger_deltas";
+
+// src/history/ledger/hash.ts
+async function envelopePayloadHash(envelope) {
+  if (!envelope) return "";
+  return sha256Hex(envelope._data);
+}
+
+// src/history/ledger/store.ts
+var MAX_APPEND_ATTEMPTS = 8;
+var LedgerStore = class {
+  adapter;
+  vault;
+  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 assumption) keeps it consistent. A second
+   * LedgerStore instance writing to the same vault 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.vault = opts.vault;
+    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.
+   *
+   * ## Multi-writer correctness
+   *
+   * Append is implemented as an optimistic-CAS retry loop. On every
+   * attempt:
+   *
+   *   1. Read fresh head (cache invalidated on retry).
+   *   2. Compute `nextIndex = head.index + 1`, `prevHash = hash(head)`.
+   *   3. Encrypt delta payload IN MEMORY (no adapter write yet) so we
+   *      can compute `deltaHash` before claiming the chain slot.
+   *   4. Build + encrypt the entry envelope.
+   *   5. `adapter.put(_ledger, paddedIndex, envelope, expectedVersion: 0)`
+   *      — the `expectedVersion: 0` asserts "this slot must not exist."
+   *      Stores with `casAtomic: true` honor the CAS check; under
+   *      contention the second writer's put throws `ConflictError`.
+   *   6. On `ConflictError`: invalidate the head cache, sleep with
+   *      bounded backoff + jitter, retry. After `MAX_APPEND_ATTEMPTS`
+   *      retries throw {@link LedgerContentionError}.
+   *   7. On success: write the delta envelope (if any) at the same
+   *      index. Update the head cache.
+   *
+   * Entry-first ordering matters: writing the delta first under
+   * contention would orphan delta records at indices the writer never
+   * actually claimed. The deltaHash is computed off the encrypted
+   * envelope's `_data` field, which doesn't require the envelope to
+   * be persisted.
+   *
+   * Stores with `casAtomic: false` (file, s3, r2 by default) silently
+   * accept the `expectedVersion: 0` argument and proceed without a
+   * CAS check. Concurrent appends against those stores remain
+   * best-effort — pair them with an advisory lock or with sync
+   * single-writer discipline.
+   */
+  async append(input) {
+    let lastConflict;
+    for (let attempt = 0; attempt < MAX_APPEND_ATTEMPTS; attempt++) {
+      if (attempt > 0) {
+        this.headCache = void 0;
+      }
+      try {
+        return await this.appendOnce(input);
+      } catch (err) {
+        if (err instanceof ConflictError) {
+          lastConflict = err;
+          if (attempt < MAX_APPEND_ATTEMPTS - 1) {
+            await sleepBackoff(attempt);
+          }
+          continue;
+        }
+        throw err;
+      }
+    }
+    void lastConflict;
+    throw new LedgerContentionError(MAX_APPEND_ATTEMPTS);
+  }
+  /**
+   * One attempt at the append cycle. Throws `ConflictError` when the
+   * CAS check on the entry put fails — `append()` catches that and
+   * retries. Any other error propagates to the caller.
+   */
+  async appendOnce(input) {
+    const cached = await this.getCachedHead();
+    const lastEntry = cached?.entry;
+    const prevHash = cached?.hash ?? "";
+    const nextIndex = lastEntry ? lastEntry.index + 1 : 0;
+    let deltaEnvelope;
+    let deltaHash;
+    if (input.delta !== void 0) {
+      deltaEnvelope = await this.encryptDelta(input.delta);
+      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.vault,
+      LEDGER_COLLECTION,
+      paddedIndex(entry.index),
+      envelope,
+      0
+    );
+    if (deltaEnvelope) {
+      await this.adapter.put(
+        this.vault,
+        LEDGER_DELTAS_COLLECTION,
+        paddedIndex(entry.index),
+        deltaEnvelope,
+        0
+      );
+    }
+    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.vault,
+      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.vault, LEDGER_COLLECTION);
+    keys.sort();
+    const entries = [];
+    for (const key of keys) {
+      const envelope = await this.adapter.get(
+        this.vault,
+        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. 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, `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);
+  }
+};
+function sleepBackoff(attempt) {
+  const base = 5 * Math.pow(2, attempt);
+  const jitter = Math.random() * base;
+  return new Promise((resolve) => setTimeout(resolve, base + jitter));
+}
+
+// src/history/time-machine.ts
+var VaultInstant = class {
+  constructor(engine, timestamp) {
+    this.engine = engine;
+    this.timestamp = timestamp;
+  }
+  engine;
+  timestamp;
+  /** Get a point-in-time view of a collection. */
+  collection(name) {
+    return new CollectionInstant(this.engine, this.timestamp, name);
+  }
+};
+var CollectionInstant = class {
+  constructor(engine, targetTs, name) {
+    this.engine = engine;
+    this.targetTs = targetTs;
+    this.name = name;
+  }
+  engine;
+  targetTs;
+  name;
+  /**
+   * Return the record as it existed at the target timestamp, or
+   * `null` if the record had not been created yet or had already been
+   * deleted by then.
+   */
+  async get(id) {
+    const envelope = await this.resolveEnvelope(id);
+    if (!envelope) return null;
+    const plaintext = this.engine.encrypted ? await decrypt(envelope._iv, envelope._data, await this.engine.getDEK(this.name)) : envelope._data;
+    return JSON.parse(plaintext);
+  }
+  /**
+   * IDs of records that existed (had at least one `put` and were not
+   * subsequently deleted) at the target timestamp.
+   *
+   * Implemented as a linear scan over history + ledger. Performance
+   * is bounded by total history size (not live-vault size), so the
+   * memory-first vault-scale cap (1K–50K records × average history
+   * depth) still applies.
+   */
+  async list() {
+    const historyIds = await collectHistoryIds(this.engine.adapter, this.engine.name, this.name);
+    const liveIds = await this.engine.adapter.list(this.engine.name, this.name);
+    const candidateIds = /* @__PURE__ */ new Set([...historyIds, ...liveIds]);
+    const alive = [];
+    for (const id of candidateIds) {
+      const env = await this.resolveEnvelope(id);
+      if (env) alive.push(id);
+    }
+    return alive.sort();
+  }
+  // ── write guards ───────────────────────────────────────────────────
+  async put(_id, _record) {
+    throw new ReadOnlyAtInstantError("put", this.targetTs);
+  }
+  async delete(_id) {
+    throw new ReadOnlyAtInstantError("delete", this.targetTs);
+  }
+  async update(_id, _patch) {
+    throw new ReadOnlyAtInstantError("update", this.targetTs);
+  }
+  // ── internals ─────────────────────────────────────────────────────
+  /**
+   * Return the envelope that represents the record's state at
+   * `targetTs`, accounting for deletes. `null` if the record didn't
+   * exist at that instant.
+   *
+   * ## Why we use the ledger as the authoritative timeline
+   *
+   * The per-version history snapshots saved by `saveHistory()` do
+   * carry a `_ts` field, but that timestamp is the moment the
+   * snapshot was *captured* (i.e. the instant right before the
+   * subsequent overwrite), not the original write time. The ledger,
+   * by contrast, records `ts` at the moment of each `put` / `delete`
+   * — it's the only source that tracks the real timeline. So:
+   *
+   *   1. Walk the ledger; find the latest entry for `(collection, id)`
+   *      with `ts ≤ targetTs`.
+   *   2. If that entry is a `delete`, the record was gone at the
+   *      target instant — return null.
+   *   3. Otherwise it's a `put` with a specific `version`. Load the
+   *      envelope for that version from history, falling back to the
+   *      live collection for the most recent version.
+   *
+   * ## Fallback when the ledger is disabled
+   *
+   * If the vault has history disabled, `getLedger()` returns null and
+   * we fall back to comparing envelope `_ts` fields. This is
+   * approximate and gets the *last write* right but may confuse the
+   * intermediate versions; adopters needing accurate time-machine
+   * reads should leave history enabled.
+   */
+  async resolveEnvelope(id) {
+    const ledger = this.engine.getLedger();
+    if (ledger) {
+      return this.resolveViaLedger(id, ledger);
+    }
+    return this.resolveViaEnvelopeTs(id);
+  }
+  async resolveViaLedger(id, ledger) {
+    const entries = await ledger.entries();
+    let latest = null;
+    for (const e of entries) {
+      if (e.collection !== this.name || e.id !== id) continue;
+      if (e.ts > this.targetTs) break;
+      latest = { op: e.op, version: e.version };
+    }
+    if (!latest) return null;
+    if (latest.op === "delete") return null;
+    return this.loadVersion(id, latest.version);
+  }
+  async resolveViaEnvelopeTs(id) {
+    const history = await getHistory(
+      this.engine.adapter,
+      this.engine.name,
+      this.name,
+      id
+    );
+    const live = await this.engine.adapter.get(this.engine.name, this.name, id);
+    const byVersion = /* @__PURE__ */ new Map();
+    for (const e of history) byVersion.set(e._v, e);
+    if (live) byVersion.set(live._v, live);
+    const sorted = [...byVersion.values()].sort(
+      (a, b) => a._ts < b._ts ? 1 : a._ts > b._ts ? -1 : 0
+    );
+    return sorted.find((e) => e._ts <= this.targetTs) ?? null;
+  }
+  /**
+   * Fetch the envelope for a specific version. The live record (most
+   * recent put) lives in the main collection; prior versions live in
+   * `_history`. We check live first because the common case after a
+   * delete is that we're trying to load the last-live version from
+   * history, and skipping live for the current-version case avoids a
+   * redundant lookup.
+   */
+  async loadVersion(id, version) {
+    const live = await this.engine.adapter.get(this.engine.name, this.name, id);
+    if (live && live._v === version) return live;
+    const historyId2 = `${this.name}:${id}:${String(version).padStart(10, "0")}`;
+    return await this.engine.adapter.get(this.engine.name, "_history", historyId2);
+  }
+};
+async function collectHistoryIds(adapter, vault, collection) {
+  const all = await adapter.list(vault, "_history");
+  const prefix = `${collection}:`;
+  const seen = /* @__PURE__ */ new Set();
+  for (const key of all) {
+    if (!key.startsWith(prefix)) continue;
+    const lastColon = key.lastIndexOf(":");
+    if (lastColon <= prefix.length) continue;
+    const middle = key.slice(prefix.length, lastColon);
+    seen.add(middle);
+  }
+  return [...seen];
+}
+
+// src/history/active.ts
+function withHistory() {
+  return {
+    saveHistory,
+    getHistoryEntries: getHistory,
+    getVersionEnvelope,
+    pruneHistory,
+    clearHistory,
+    envelopePayloadHash,
+    computePatch,
+    diff,
+    buildLedger(opts) {
+      return new LedgerStore({
+        adapter: opts.adapter,
+        vault: opts.vault,
+        encrypted: opts.encrypted,
+        getDEK: opts.getDEK,
+        actor: opts.actor
+      });
+    },
+    buildVaultInstant(engine, timestamp) {
+      return new VaultInstant(engine, timestamp);
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CollectionInstant,
+  LEDGER_COLLECTION,
+  LEDGER_DELTAS_COLLECTION,
+  LedgerStore,
+  VaultInstant,
+  applyPatch,
+  canonicalJson,
+  clearHistory,
+  computePatch,
+  diff,
+  envelopePayloadHash,
+  formatDiff,
+  getHistory,
+  getVersionEnvelope,
+  hashEntry,
+  paddedIndex,
+  parseIndex,
+  pruneHistory,
+  saveHistory,
+  sha256Hex,
+  withHistory
+});
+//# sourceMappingURL=index.cjs.map