@noy-db/hub 0.2.0-pre.30 → 0.2.0-pre.31

package/dist/history/index.cjs

@@ -1,1245 +0,0 @@
-"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/types.ts
-var NOYDB_FORMAT_VERSION = 1;
-
-// 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;
-}
-async function tombstoneHistory(adapter, vault, collection, recordId, actor) {
-  const allIds = await adapter.list(vault, HISTORY_COLLECTION);
-  const matchingIds = allIds.filter((id) => matchesPrefix(id, collection, recordId));
-  const now = (/* @__PURE__ */ new Date()).toISOString();
-  let count = 0;
-  for (const id of matchingIds) {
-    const env = await adapter.get(vault, HISTORY_COLLECTION, id);
-    if (!env) continue;
-    if (!env._data && env._cek === void 0) continue;
-    const tombstone = {
-      _noydb: NOYDB_FORMAT_VERSION,
-      _v: env._v,
-      _ts: now,
-      _iv: "",
-      _data: "",
-      ...actor ? { _by: actor } : {}
-    };
-    await adapter.put(vault, HISTORY_COLLECTION, id, tombstone);
-    count++;
-  }
-  return count;
-}
-
-// 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/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 = {
-      ...entryBase,
-      ...deltaHash !== void 0 ? { deltaHash } : {},
-      ...input.amendment !== void 0 ? { amendment: input.amendment } : {},
-      ...input.reason !== void 0 ? { reason: input.reason } : {}
-    };
-    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.op !== "put" && entry.op !== "delete") 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;
-      if (e.op === "amendment" || e.op === "lifecycle" || e.op === "forget") continue;
-      latest = { op: e.op === "migration" ? "put" : 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,
-    tombstoneHistory,
-    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