@noy-db/hub 0.1.0-pre.3

package/dist/chunk-XHFOENR2.js

@@ -0,0 +1,680 @@
+import {
+  canonicalJson,
+  hashEntry,
+  paddedIndex,
+  sha256Hex
+} from "./chunk-CIMZBAZB.js";
+import {
+  NOYDB_FORMAT_VERSION
+} from "./chunk-ZRG4V3F5.js";
+import {
+  decrypt,
+  encrypt
+} from "./chunk-MR4424N3.js";
+import {
+  ConflictError,
+  LedgerContentionError
+} from "./chunk-ACLDOTNQ.js";
+
+// src/history/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/history/ledger/constants.ts
+var LEDGER_COLLECTION = "_ledger";
+var LEDGER_DELTAS_COLLECTION = "_ledger_deltas";
+
+// 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));
+}
+
+export {
+  computePatch,
+  applyPatch,
+  LEDGER_COLLECTION,
+  LEDGER_DELTAS_COLLECTION,
+  LedgerStore
+};
+//# sourceMappingURL=chunk-XHFOENR2.js.map