@noy-db/hub 0.1.0-pre.3

package/dist/periods/index.cjs

@@ -0,0 +1,1035 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+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/types.ts
+var NOYDB_FORMAT_VERSION;
+var init_types = __esm({
+  "src/types.ts"() {
+    "use strict";
+    NOYDB_FORMAT_VERSION = 1;
+  }
+});
+
+// src/errors.ts
+var NoydbError, DecryptionError, TamperedError, PeriodClosedError, ConflictError, LedgerContentionError, ValidationError;
+var init_errors = __esm({
+  "src/errors.ts"() {
+    "use strict";
+    NoydbError = class extends Error {
+      /** Machine-readable error code. Stable across library versions. */
+      code;
+      constructor(code, message) {
+        super(message);
+        this.name = "NoydbError";
+        this.code = code;
+      }
+    };
+    DecryptionError = class extends NoydbError {
+      constructor(message = "Decryption failed") {
+        super("DECRYPTION_FAILED", message);
+        this.name = "DecryptionError";
+      }
+    };
+    TamperedError = class extends NoydbError {
+      constructor(message = "Data integrity check failed \u2014 record may have been tampered with") {
+        super("TAMPERED", message);
+        this.name = "TamperedError";
+      }
+    };
+    PeriodClosedError = class extends NoydbError {
+      periodName;
+      endDate;
+      recordTs;
+      constructor(periodName, endDate, recordTs) {
+        super(
+          "PERIOD_CLOSED",
+          `Cannot modify record (last written ${recordTs}) \u2014 sealed by closed period "${periodName}" (endDate: ${endDate}). Post a compensating entry in a new period instead.`
+        );
+        this.name = "PeriodClosedError";
+        this.periodName = periodName;
+        this.endDate = endDate;
+        this.recordTs = recordTs;
+      }
+    };
+    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;
+      }
+    };
+    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;
+      }
+    };
+    ValidationError = class extends NoydbError {
+      constructor(message = "Validation error") {
+        super("VALIDATION_ERROR", message);
+        this.name = "ValidationError";
+      }
+    };
+  }
+});
+
+// src/crypto.ts
+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;
+}
+var IV_BYTES, subtle;
+var init_crypto = __esm({
+  "src/crypto.ts"() {
+    "use strict";
+    init_errors();
+    IV_BYTES = 12;
+    subtle = globalThis.crypto.subtle;
+  }
+});
+
+// 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);
+}
+var init_entry = __esm({
+  "src/history/ledger/entry.ts"() {
+    "use strict";
+  }
+});
+
+// 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));
+}
+var init_patch = __esm({
+  "src/history/ledger/patch.ts"() {
+    "use strict";
+  }
+});
+
+// src/history/ledger/constants.ts
+var LEDGER_COLLECTION, LEDGER_DELTAS_COLLECTION;
+var init_constants = __esm({
+  "src/history/ledger/constants.ts"() {
+    "use strict";
+    LEDGER_COLLECTION = "_ledger";
+    LEDGER_DELTAS_COLLECTION = "_ledger_deltas";
+  }
+});
+
+// src/history/ledger/hash.ts
+async function envelopePayloadHash(envelope) {
+  if (!envelope) return "";
+  return sha256Hex(envelope._data);
+}
+var init_hash = __esm({
+  "src/history/ledger/hash.ts"() {
+    "use strict";
+    init_entry();
+  }
+});
+
+// src/history/ledger/store.ts
+function sleepBackoff(attempt) {
+  const base = 5 * Math.pow(2, attempt);
+  const jitter = Math.random() * base;
+  return new Promise((resolve) => setTimeout(resolve, base + jitter));
+}
+var MAX_APPEND_ATTEMPTS, LedgerStore;
+var init_store = __esm({
+  "src/history/ledger/store.ts"() {
+    "use strict";
+    init_types();
+    init_crypto();
+    init_errors();
+    init_entry();
+    init_patch();
+    init_constants();
+    init_hash();
+    MAX_APPEND_ATTEMPTS = 8;
+    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);
+      }
+    };
+  }
+});
+
+// src/history/ledger/index.ts
+var ledger_exports = {};
+__export(ledger_exports, {
+  LEDGER_COLLECTION: () => LEDGER_COLLECTION,
+  LEDGER_DELTAS_COLLECTION: () => LEDGER_DELTAS_COLLECTION,
+  LedgerStore: () => LedgerStore,
+  applyPatch: () => applyPatch,
+  canonicalJson: () => canonicalJson,
+  computePatch: () => computePatch,
+  envelopePayloadHash: () => envelopePayloadHash,
+  hashEntry: () => hashEntry,
+  paddedIndex: () => paddedIndex,
+  parseIndex: () => parseIndex,
+  sha256Hex: () => sha256Hex
+});
+var init_ledger = __esm({
+  "src/history/ledger/index.ts"() {
+    "use strict";
+    init_store();
+    init_entry();
+    init_patch();
+  }
+});
+
+// src/periods/index.ts
+var periods_exports = {};
+__export(periods_exports, {
+  PERIODS_COLLECTION: () => PERIODS_COLLECTION,
+  appendPeriodLedgerEntry: () => appendPeriodLedgerEntry,
+  assertTsWritable: () => assertTsWritable,
+  chainAnchor: () => chainAnchor,
+  loadPeriods: () => loadPeriods,
+  validatePeriodName: () => validatePeriodName,
+  withPeriods: () => withPeriods
+});
+module.exports = __toCommonJS(periods_exports);
+
+// src/periods/periods.ts
+init_ledger();
+init_errors();
+var PERIODS_COLLECTION = "_periods";
+async function loadPeriods(adapter, vault, decrypt2) {
+  const ids = await adapter.list(vault, PERIODS_COLLECTION);
+  const records = [];
+  for (const id of ids) {
+    const env = await adapter.get(vault, PERIODS_COLLECTION, id);
+    if (env) records.push(await decrypt2(env));
+  }
+  records.sort((a, b) => a.closedAt.localeCompare(b.closedAt));
+  return records;
+}
+async function chainAnchor(records) {
+  const last = records[records.length - 1];
+  if (!last) return { priorPeriodHash: "" };
+  const hash = await sha256Hex(canonicalJson(last));
+  return { priorPeriodName: last.name, priorPeriodHash: hash };
+}
+function assertTsWritable(existing, incomingRecord, closedPeriods) {
+  for (const p of closedPeriods) {
+    if (p.kind !== "closed") continue;
+    if (p.dateField) {
+      const checkRecord = (label, r) => {
+        if (!r) return;
+        const v = r[p.dateField];
+        if (typeof v === "string" && v <= p.endDate) {
+          throw new PeriodClosedError(p.name, p.endDate, `${label}[${p.dateField}]=${v}`);
+        }
+      };
+      checkRecord("existing", existing?.record ?? null);
+      checkRecord("incoming", incomingRecord);
+      continue;
+    }
+    const existingTs = existing?.ts ?? null;
+    if (existingTs !== null && existingTs <= p.endDate) {
+      throw new PeriodClosedError(p.name, p.endDate, existingTs);
+    }
+  }
+}
+function validatePeriodName(name, existing) {
+  if (name.length === 0) {
+    throw new ValidationError("Period name cannot be empty.");
+  }
+  if (existing.some((p) => p.name === name)) {
+    throw new ValidationError(`Period "${name}" already exists.`);
+  }
+}
+async function appendPeriodLedgerEntry(ledger, actor, envelope, name) {
+  if (!ledger) return;
+  const { envelopePayloadHash: envelopePayloadHash2 } = await Promise.resolve().then(() => (init_ledger(), ledger_exports));
+  await ledger.append({
+    op: "put",
+    collection: PERIODS_COLLECTION,
+    id: name,
+    version: envelope._v,
+    actor,
+    payloadHash: await envelopePayloadHash2(envelope)
+  });
+}
+
+// src/periods/active.ts
+function withPeriods() {
+  return {
+    loadPeriods,
+    chainAnchor,
+    assertTsWritable,
+    validatePeriodName,
+    appendPeriodLedgerEntry
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PERIODS_COLLECTION,
+  appendPeriodLedgerEntry,
+  assertTsWritable,
+  chainAnchor,
+  loadPeriods,
+  validatePeriodName,
+  withPeriods
+});
+//# sourceMappingURL=index.cjs.map