@noy-db/hub 0.3.0-pre.9 → 0.3.0

package/dist/chunk-WNA6T3MA.js

@@ -1,686 +0,0 @@
-import {
-  LEDGER_COLLECTION,
-  LEDGER_DELTAS_COLLECTION
-} from "./chunk-I7FD46FF.js";
-import {
-  canonicalJson,
-  hashEntry,
-  paddedIndex,
-  sha256Hex
-} from "./chunk-MSVY7ULZ.js";
-import {
-  openEnvelopeJson
-} from "./chunk-XHD3L3JO.js";
-import {
-  encrypt
-} from "./chunk-AUR7MRHA.js";
-import {
-  NOYDB_FORMAT_VERSION
-} from "./chunk-UNJU345Q.js";
-import {
-  ConflictError,
-  LedgerContentionError
-} from "./chunk-CU62BBRB.js";
-
-// src/with-commit/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/with-commit/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 openEnvelopeJson(envelope, 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 openEnvelopeJson(envelope, 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,
-  LedgerStore
-};
-//# sourceMappingURL=chunk-WNA6T3MA.js.map