@noy-db/hub 0.2.0-pre.4 → 0.2.0-pre.5

package/dist/chunk-6A4AMQ2H.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/history/ledger/patch.ts","../src/history/ledger/constants.ts","../src/history/ledger/store.ts"],"sourcesContent":["/**\n * RFC 6902 JSON Patch — compute + apply.\n *\n * This module is the \"delta history\" primitive: instead of\n * snapshotting the full record on every put (the behavior),\n * `Collection.put` computes a JSON Patch from the previous version to\n * the new version and stores only the patch in the ledger. To\n * reconstruct version N, we walk from the genesis snapshot forward\n * applying patches. Storage scales with **edit size**, not record\n * size — a 10 KB record edited 1000 times costs ~10 KB of deltas\n * instead of ~10 MB of snapshots.\n *\n * ## Why hand-roll instead of using a library?\n *\n * RFC 6902 has good libraries (`fast-json-patch`, `rfc6902`) but every\n * single one of them adds a runtime dependency to `@noy-db/core`. The\n * \"zero runtime dependencies\" promise is one of the core's load-bearing\n * features, and the patch surface we actually need is small enough\n * (~150 LoC) that vendoring is the right call.\n *\n * What we implement:\n *   - `add`     — insert a value at a path\n *   - `remove`  — delete the value at a path\n *   - `replace` — overwrite the value at a path\n *\n * What we deliberately skip (out of scope for the ledger use):\n *   - `move` and `copy` — optimizations; the diff algorithm doesn't\n *     emit them, so the apply path doesn't need them\n *   - `test` — used for transactional patches; we already have\n *     optimistic concurrency via `_v` at the envelope layer\n *   - Sophisticated array diffing (LCS, edit distance) — we treat\n *     arrays as atomic values and emit a single `replace` op when\n *     they differ. The accounting domain has small arrays where this\n *     is fine; if we ever need patch-level array diffing we can add\n *     it without changing the storage format.\n *\n * ## Path encoding (RFC 6902 §3)\n *\n * Paths look like `/foo/bar/0`. Each path segment is either an object\n * key or a numeric array index. Two characters need escaping inside\n * keys: `~` becomes `~0` and `/` becomes `~1`. We implement both.\n *\n * Empty path (`\"\"`) refers to the root document. Only `replace` makes\n * sense at the root, and our diff function emits it as a top-level\n * `replace` when `prev` and `next` differ in shape (object vs array,\n * primitive vs object, etc.).\n */\n\n/** A single JSON Patch operation. Subset of RFC 6902 — see file docstring. */\nexport type JsonPatchOp =\n  | { readonly op: 'add'; readonly path: string; readonly value: unknown }\n  | { readonly op: 'remove'; readonly path: string }\n  | { readonly op: 'replace'; readonly path: string; readonly value: unknown }\n\n/** A complete JSON Patch document — an array of operations. */\nexport type JsonPatch = readonly JsonPatchOp[]\n\n// ─── Compute (diff) ──────────────────────────────────────────────────\n\n/**\n * Compute a JSON Patch that, when applied to `prev`, produces `next`.\n *\n * The algorithm is a straightforward recursive object walk:\n *\n *   1. If both inputs are plain objects (and not arrays/null):\n *      - For each key in `prev`, recurse if `next` has it, else emit `remove`\n *      - For each key in `next` not in `prev`, emit `add`\n *   2. If both inputs are arrays AND structurally equal, no-op.\n *      Otherwise emit a single `replace` for the whole array.\n *   3. If both inputs are deeply equal primitives, no-op.\n *   4. Otherwise emit a `replace` at the current path.\n *\n * We do not minimize patches across move-like rearrangements — every\n * generated patch is straightforward enough to apply by hand if you\n * had to debug it.\n */\nexport function computePatch(prev: unknown, next: unknown): JsonPatch {\n  const ops: JsonPatchOp[] = []\n  diff(prev, next, '', ops)\n  return ops\n}\n\nfunction diff(\n  prev: unknown,\n  next: unknown,\n  path: string,\n  out: JsonPatchOp[],\n): void {\n  // Both null / both undefined → no-op (we don't differentiate them\n  // in JSON terms; canonicalJson would reject undefined anyway).\n  if (prev === next) return\n\n  // One side null, the other not → straight replace.\n  if (prev === null || next === null) {\n    out.push({ op: 'replace', path, value: next })\n    return\n  }\n\n  const prevIsArray = Array.isArray(prev)\n  const nextIsArray = Array.isArray(next)\n  const prevIsObject = typeof prev === 'object' && !prevIsArray\n  const nextIsObject = typeof next === 'object' && !nextIsArray\n\n  // Type changed (e.g., object → primitive, array → object). Replace.\n  if (prevIsArray !== nextIsArray || prevIsObject !== nextIsObject) {\n    out.push({ op: 'replace', path, value: next })\n    return\n  }\n\n  // Both arrays. We don't do clever LCS-based diffing — emit a single\n  // replace for the whole array if they differ. See file docstring for\n  // the rationale.\n  if (prevIsArray && nextIsArray) {\n    if (!arrayDeepEqual(prev as unknown[], next as unknown[])) {\n      out.push({ op: 'replace', path, value: next })\n    }\n    return\n  }\n\n  // Both plain objects. Recurse key by key.\n  if (prevIsObject && nextIsObject) {\n    const prevObj = prev as Record<string, unknown>\n    const nextObj = next as Record<string, unknown>\n    const prevKeys = Object.keys(prevObj)\n    const nextKeys = Object.keys(nextObj)\n\n    // Handle removes and overlapping recursions in one pass over prev.\n    for (const key of prevKeys) {\n      const childPath = path + '/' + escapePathSegment(key)\n      if (!(key in nextObj)) {\n        out.push({ op: 'remove', path: childPath })\n      } else {\n        diff(prevObj[key], nextObj[key], childPath, out)\n      }\n    }\n    // Handle adds.\n    for (const key of nextKeys) {\n      if (!(key in prevObj)) {\n        out.push({\n          op: 'add',\n          path: path + '/' + escapePathSegment(key),\n          value: nextObj[key],\n        })\n      }\n    }\n    return\n  }\n\n  // Two primitives that aren't strictly equal — replace.\n  out.push({ op: 'replace', path, value: next })\n}\n\nfunction arrayDeepEqual(a: unknown[], b: unknown[]): boolean {\n  if (a.length !== b.length) return false\n  for (let i = 0; i < a.length; i++) {\n    if (!deepEqual(a[i], b[i])) return false\n  }\n  return true\n}\n\nfunction deepEqual(a: unknown, b: unknown): boolean {\n  if (a === b) return true\n  if (a === null || b === null) return false\n  if (typeof a !== typeof b) return false\n  if (typeof a !== 'object') return false\n  const aArray = Array.isArray(a)\n  const bArray = Array.isArray(b)\n  if (aArray !== bArray) return false\n  if (aArray && bArray) return arrayDeepEqual(a, b as unknown[])\n  const aObj = a as Record<string, unknown>\n  const bObj = b as Record<string, unknown>\n  const aKeys = Object.keys(aObj)\n  const bKeys = Object.keys(bObj)\n  if (aKeys.length !== bKeys.length) return false\n  for (const key of aKeys) {\n    if (!(key in bObj)) return false\n    if (!deepEqual(aObj[key], bObj[key])) return false\n  }\n  return true\n}\n\n// ─── Apply ──────────────────────────────────────────────────────────\n\n/**\n * Apply a JSON Patch to a base document and return the result.\n *\n * The base document is **not mutated** — every op clones the parent\n * container before writing to it, so the caller's reference to `base`\n * stays untouched. This costs an extra allocation per op but makes\n * the apply pipeline reorderable and safe to interrupt.\n *\n * Throws on:\n *   - Removing a path that doesn't exist\n *   - Adding to a path whose parent doesn't exist\n *   - A path component that doesn't match the document shape (e.g.,\n *     trying to step into a primitive)\n *\n * Throwing is the right behavior for the ledger use case: a failed\n * apply means the chain is corrupted, which should be loud rather\n * than silently producing a wrong reconstruction.\n */\nexport function applyPatch<T = unknown>(base: T, patch: JsonPatch): T {\n  let result: unknown = clone(base)\n  for (const op of patch) {\n    result = applyOp(result, op)\n  }\n  return result as T\n}\n\nfunction applyOp(doc: unknown, op: JsonPatchOp): unknown {\n  // Empty path → operation targets the root. Only `replace` and `add`\n  // make sense at the root, but we handle `remove` for completeness\n  // (root removal returns null).\n  if (op.path === '') {\n    if (op.op === 'remove') return null\n    return clone(op.value)\n  }\n\n  const segments = parsePath(op.path)\n  return walkAndApply(doc, segments, op)\n}\n\nfunction walkAndApply(\n  doc: unknown,\n  segments: string[],\n  op: JsonPatchOp,\n): unknown {\n  if (segments.length === 0) {\n    // Should never happen — empty path is handled in applyOp().\n    throw new Error('walkAndApply: empty segments (internal error)')\n  }\n\n  const [head, ...rest] = segments\n  if (head === undefined) throw new Error('walkAndApply: undefined segment')\n\n  if (rest.length === 0) {\n    return applyAtTerminal(doc, head, op)\n  }\n\n  // Recurse into the child container, then rebuild the parent with\n  // the modified child.\n  if (Array.isArray(doc)) {\n    const idx = parseArrayIndex(head, doc.length)\n    const child = doc[idx]\n    const newChild = walkAndApply(child, rest, op)\n    const next = doc.slice()\n    next[idx] = newChild\n    return next\n  }\n  if (doc !== null && typeof doc === 'object') {\n    const obj = doc as Record<string, unknown>\n    if (!(head in obj)) {\n      throw new Error(`applyPatch: path segment \"${head}\" not found in object`)\n    }\n    const newChild = walkAndApply(obj[head], rest, op)\n    return { ...obj, [head]: newChild }\n  }\n  throw new Error(\n    `applyPatch: cannot step into ${typeof doc} at segment \"${head}\"`,\n  )\n}\n\nfunction applyAtTerminal(\n  doc: unknown,\n  segment: string,\n  op: JsonPatchOp,\n): unknown {\n  if (Array.isArray(doc)) {\n    const idx =\n      segment === '-' ? doc.length : parseArrayIndex(segment, doc.length + 1)\n    const next = doc.slice()\n    if (op.op === 'remove') {\n      next.splice(idx, 1)\n      return next\n    }\n    if (op.op === 'add') {\n      next.splice(idx, 0, clone(op.value))\n      return next\n    }\n    if (op.op === 'replace') {\n      if (idx >= doc.length) {\n        throw new Error(\n          `applyPatch: replace at out-of-bounds array index ${idx}`,\n        )\n      }\n      next[idx] = clone(op.value)\n      return next\n    }\n  }\n  if (doc !== null && typeof doc === 'object') {\n    const obj = doc as Record<string, unknown>\n    if (op.op === 'remove') {\n      if (!(segment in obj)) {\n        throw new Error(\n          `applyPatch: remove on missing key \"${segment}\"`,\n        )\n      }\n      const next = { ...obj }\n      delete next[segment]\n      return next\n    }\n    if (op.op === 'add') {\n      // RFC 6902: `add` on an existing key replaces it.\n      return { ...obj, [segment]: clone(op.value) }\n    }\n    if (op.op === 'replace') {\n      if (!(segment in obj)) {\n        throw new Error(\n          `applyPatch: replace on missing key \"${segment}\"`,\n        )\n      }\n      return { ...obj, [segment]: clone(op.value) }\n    }\n  }\n  throw new Error(\n    `applyPatch: cannot apply ${op.op} at terminal segment \"${segment}\"`,\n  )\n}\n\n// ─── Path encoding (RFC 6902 §3) ─────────────────────────────────────\n\n/**\n * Escape a single path segment per RFC 6902 §3:\n *   `~` → `~0`\n *   `/` → `~1`\n *\n * Order matters: `~` must be escaped first, otherwise the `~1` we\n * just emitted would be re-escaped to `~01`.\n */\nfunction escapePathSegment(segment: string): string {\n  return segment.replace(/~/g, '~0').replace(/\\//g, '~1')\n}\n\nfunction unescapePathSegment(segment: string): string {\n  return segment.replace(/~1/g, '/').replace(/~0/g, '~')\n}\n\nfunction parsePath(path: string): string[] {\n  if (!path.startsWith('/')) {\n    throw new Error(`applyPatch: path must start with '/', got \"${path}\"`)\n  }\n  return path\n    .slice(1)\n    .split('/')\n    .map(unescapePathSegment)\n}\n\nfunction parseArrayIndex(segment: string, max: number): number {\n  if (!/^\\d+$/.test(segment)) {\n    throw new Error(\n      `applyPatch: array index must be a non-negative integer, got \"${segment}\"`,\n    )\n  }\n  const idx = Number.parseInt(segment, 10)\n  if (idx < 0 || idx > max) {\n    throw new Error(\n      `applyPatch: array index ${idx} out of range [0, ${max}]`,\n    )\n  }\n  return idx\n}\n\n// ─── Cheap structural clone ─────────────────────────────────────────\n\n/**\n * Plain-JSON clone via JSON.parse(JSON.stringify(value)).\n *\n * Faster than `structuredClone` for our use because (a) we know our\n * inputs are JSON-compatible (no Dates, Maps, or BigInts — anything\n * else gets rejected by canonicalJson upstream), and (b) `structuredClone`\n * has overhead for handling arbitrary structured data we don't need.\n *\n * For tiny ledger entries (< 1 KB), the JSON round-trip is in the\n * single-digit microsecond range.\n */\nfunction clone<T>(value: T): T {\n  if (value === null || value === undefined) return value\n  if (typeof value !== 'object') return value\n  return JSON.parse(JSON.stringify(value)) as T\n}\n","/**\n * Ledger storage constants — pinned in their own leaf module so\n * always-on core code (vault.ts, dictionary.ts) can import them\n * without dragging the `LedgerStore` class into the bundle.\n *\n * `splitting: true` in tsup is not enough on its own: when a\n * source file exports both pure constants and a heavyweight class,\n * the bundler keeps the entire chunk reachable from any importer.\n * Extracting the constants lets the floor scenario import them\n * without paying for the class.\n *\n * @internal\n */\n\n/** The internal collection name used for ledger entry storage. */\nexport const LEDGER_COLLECTION = '_ledger'\n\n/**\n * The internal collection name used for delta payload storage.\n *\n * Deltas live in a sibling collection (not inside `_ledger`) for two\n * reasons:\n *\n *   1. **Listing efficiency.** `ledger.loadAllEntries()` calls\n *      `adapter.list(_ledger)` which would otherwise return every\n *      delta key alongside every entry key. Splitting them keeps the\n *      list small (one key per ledger entry) and the delta reads\n *      keyed by the entry's index.\n *\n *   2. **Prune-friendliness.** A future `pruneHistory()` will delete\n *      old deltas while keeping the ledger chain intact (folding old\n *      deltas into a base snapshot). Separating the storage makes\n *      that deletion a targeted operation on one collection instead\n *      of a filter across a mixed list.\n *\n * Both collections share the same ledger DEK — one DEK, two\n * internal collections, same zero-knowledge guarantees.\n */\nexport const LEDGER_DELTAS_COLLECTION = '_ledger_deltas'\n","/**\n * `LedgerStore` — read/write access to a compartment's hash-chained\n * audit log.\n *\n * The store is a thin wrapper around the adapter's `_ledger/` internal\n * collection. Every append:\n *\n *   1. Loads the current head (or treats an empty ledger as head = -1)\n *   2. Computes `prevHash` = sha256(canonicalJson(head))\n *   3. Builds the new entry with `index = head.index + 1`\n *   4. Encrypts the entry with the compartment's ledger DEK\n *   5. Writes the encrypted envelope to `_ledger/<paddedIndex>`\n *\n * `verify()` walks the chain from genesis forward and returns\n * `{ ok: true, head }` on success or `{ ok: false, divergedAt }` on the\n * first broken link.\n *\n * ## Thread / concurrency model\n *\n * For we assume a **single writer per vault**. Two\n * concurrent `append()` calls would race on the \"read head, write\n * head+1\" cycle and could produce a broken chain. The sync engine\n * is the primary concurrent-writer scenario, and it uses\n * optimistic-concurrency via `expectedVersion` on the adapter — but\n * the ledger path has no such guard today. Multi-writer hardening is a\n * follow-up.\n *\n * Single-writer usage IS safe, including across process restarts:\n * `head()` reads the adapter fresh each call, so a crash between the\n * adapter.put of a data record and the ledger append just means the\n * ledger is missing an entry for that record. `verify()` still\n * succeeds; a future `verifyIntegrity()` helper can cross-check the\n * ledger against the data collections to catch the gap.\n *\n * ## Why hide the ledger from `vault.collection()`?\n *\n * The `_ledger` name starts with `_`, matching the existing prefix\n * convention for internal collections (`_keyring`, `_sync`,\n * `_history`). The Vault's public `collection()` method already\n * returns entries for any name, but `loadAll()` filters out\n * underscore-prefixed collections so backups and exports don't leak\n * ledger metadata. We keep the ledger accessible ONLY via\n * `vault.ledger()` to enforce the hash-chain invariants — direct\n * puts via `collection('_ledger')` would bypass the `append()` logic.\n */\n\nimport type { NoydbStore, EncryptedEnvelope } from '../../types.js'\nimport { NOYDB_FORMAT_VERSION } from '../../types.js'\nimport { encrypt, decrypt } from '../../crypto.js'\nimport { ConflictError, LedgerContentionError } from '../../errors.js'\nimport {\n  canonicalJson,\n  hashEntry,\n  paddedIndex,\n  sha256Hex,\n  type LedgerEntry,\n} from './entry.js'\nimport type { JsonPatch } from './patch.js'\nimport { applyPatch } from './patch.js'\nimport { LEDGER_COLLECTION, LEDGER_DELTAS_COLLECTION } from './constants.js'\nimport { envelopePayloadHash } from './hash.js'\n\n/**\n * Maximum optimistic-CAS retries on the ledger head. Each failed\n * attempt invalidates the head cache, re-reads, and retries with a\n * fresh next-index. After N failures we surface\n * `LedgerContentionError` so the caller can decide whether to retry,\n * queue, or alert.\n */\nconst MAX_APPEND_ATTEMPTS = 8\n\n//  — re-export the constants + helper so any existing\n// `import { LEDGER_COLLECTION } from '...store.js'` paths keep\n// working. Internal core paths (vault.ts) import from the leaf\n// modules directly to avoid pulling this file's class into the\n// floor bundle.\nexport { LEDGER_COLLECTION, LEDGER_DELTAS_COLLECTION, envelopePayloadHash }\n\n/**\n * Input shape for `LedgerStore.append()`. The caller supplies the\n * operation metadata; the store fills in `index` and `prevHash`.\n */\nexport interface AppendInput {\n  op: LedgerEntry['op']\n  collection: string\n  id: string\n  version: number\n  actor: string\n  payloadHash: string\n  /**\n   * Optional JSON Patch representing the delta from the previous\n   * version to the new version. Present only for `put` operations\n   * that had a previous version; omitted for genesis puts and for\n   * deletes. When present, `LedgerStore.append` persists the patch\n   * in `_ledger_deltas/<paddedIndex>` and records its sha256 hash\n   * as the entry's `deltaHash` field.\n   */\n  delta?: JsonPatch\n  /**\n   * Present only for `op === 'amendment'` — structured audit\n   * payload for multi-record repair operations performed via\n   * `withTransactions(...)`. Carried through verbatim to the\n   * resulting ledger entry.\n   */\n  amendment?: LedgerEntry['amendment']\n  /**\n   * Optional human-readable tag describing why this mutation happened.\n   * Threaded from `collection.put(_, _, { reason })`.\n   * Carried verbatim onto the resulting ledger entry's `reason` field;\n   * omitted from canonical JSON when undefined.\n   */\n  reason?: string\n}\n\n/**\n * Result of `LedgerStore.verify()`. On success, `head` is the hash of\n * the last entry — the same value that should be published to any\n * external anchoring service (blockchain, OpenTimestamps, etc.). On\n * failure, `divergedAt` is the 0-based index of the first entry whose\n * recorded `prevHash` does not match the recomputed hash of its\n * predecessor. Entries at `divergedAt` and later are untrustworthy;\n * entries before that index are still valid.\n */\nexport type VerifyResult =\n  | { readonly ok: true; readonly head: string; readonly length: number }\n  | {\n      readonly ok: false\n      readonly divergedAt: number\n      readonly expected: string\n      readonly actual: string\n    }\n\n/**\n * A LedgerStore is bound to a single vault. Callers obtain one\n * via `vault.ledger()` — there is no public constructor to keep\n * the hash-chain invariants in one place.\n *\n * The class holds no mutable state beyond its dependencies (adapter,\n * vault name, DEK resolver, actor id). Every method reads the\n * adapter fresh so multiple instances against the same vault\n * see each other's writes immediately (at the cost of re-parsing the\n * ledger on every head() / verify() call; acceptable at scale).\n */\nexport class LedgerStore {\n  private readonly adapter: NoydbStore\n  private readonly vault: string\n  private readonly encrypted: boolean\n  private readonly getDEK: (collectionName: string) => Promise<CryptoKey>\n  private readonly actor: string\n\n  /**\n   * In-memory cache of the chain head — the most recently appended\n   * entry along with its precomputed hash. Without this, every\n   * `append()` would re-load every prior entry to recompute the\n   * prevHash, making N puts O(N²) — a 1K-record stress test goes from\n   * < 100ms to a multi-second timeout.\n   *\n   * The cache is populated on first read (`append`, `head`, `verify`)\n   * and updated in-place on every successful `append`. Single-writer\n   * usage (the assumption) keeps it consistent. A second\n   * LedgerStore instance writing to the same vault would not\n   * see the first instance's appends in its cached state — that's the\n   * concurrency caveat documented at the class level.\n   *\n   * Sentinel `undefined` means \"not yet loaded\"; an explicit `null`\n   * value means \"loaded and confirmed empty\" — distinguishing these\n   * matters because an empty ledger is a valid state (genesis prevHash\n   * is the empty string), and we don't want to re-scan the adapter\n   * just because the chain is freshly initialized.\n   */\n  private headCache: { entry: LedgerEntry; hash: string } | null | undefined = undefined\n\n  constructor(opts: {\n    adapter: NoydbStore\n    vault: string\n    encrypted: boolean\n    getDEK: (collectionName: string) => Promise<CryptoKey>\n    actor: string\n  }) {\n    this.adapter = opts.adapter\n    this.vault = opts.vault\n    this.encrypted = opts.encrypted\n    this.getDEK = opts.getDEK\n    this.actor = opts.actor\n  }\n\n  /**\n   * Lazily load (or return cached) the current chain head. The cache\n   * sentinel is `undefined` until first access; after the first call,\n   * the cache holds either a `{ entry, hash }` for non-empty ledgers\n   * or `null` for empty ones.\n   */\n  private async getCachedHead(): Promise<{ entry: LedgerEntry; hash: string } | null> {\n    if (this.headCache !== undefined) return this.headCache\n    const entries = await this.loadAllEntries()\n    const last = entries[entries.length - 1]\n    if (!last) {\n      this.headCache = null\n      return null\n    }\n    this.headCache = { entry: last, hash: await hashEntry(last) }\n    return this.headCache\n  }\n\n  /**\n   * Append a new entry to the ledger. Returns the full entry that was\n   * written (with its assigned index and computed prevHash) so the\n   * caller can use the hash for downstream purposes (e.g., embedding\n   * in a verifiable backup).\n   *\n   * This is the **only** way to add entries. Direct adapter writes to\n   * `_ledger/` would bypass the chain math and would be caught by the\n   * next `verify()` call as a divergence.\n   *\n   * ## Multi-writer correctness\n   *\n   * Append is implemented as an optimistic-CAS retry loop. On every\n   * attempt:\n   *\n   *   1. Read fresh head (cache invalidated on retry).\n   *   2. Compute `nextIndex = head.index + 1`, `prevHash = hash(head)`.\n   *   3. Encrypt delta payload IN MEMORY (no adapter write yet) so we\n   *      can compute `deltaHash` before claiming the chain slot.\n   *   4. Build + encrypt the entry envelope.\n   *   5. `adapter.put(_ledger, paddedIndex, envelope, expectedVersion: 0)`\n   *      — the `expectedVersion: 0` asserts \"this slot must not exist.\"\n   *      Stores with `casAtomic: true` honor the CAS check; under\n   *      contention the second writer's put throws `ConflictError`.\n   *   6. On `ConflictError`: invalidate the head cache, sleep with\n   *      bounded backoff + jitter, retry. After `MAX_APPEND_ATTEMPTS`\n   *      retries throw {@link LedgerContentionError}.\n   *   7. On success: write the delta envelope (if any) at the same\n   *      index. Update the head cache.\n   *\n   * Entry-first ordering matters: writing the delta first under\n   * contention would orphan delta records at indices the writer never\n   * actually claimed. The deltaHash is computed off the encrypted\n   * envelope's `_data` field, which doesn't require the envelope to\n   * be persisted.\n   *\n   * Stores with `casAtomic: false` (file, s3, r2 by default) silently\n   * accept the `expectedVersion: 0` argument and proceed without a\n   * CAS check. Concurrent appends against those stores remain\n   * best-effort — pair them with an advisory lock or with sync\n   * single-writer discipline.\n   */\n  async append(input: AppendInput): Promise<LedgerEntry> {\n    let lastConflict: ConflictError | undefined\n    for (let attempt = 0; attempt < MAX_APPEND_ATTEMPTS; attempt++) {\n      // Force a fresh head read on every retry. The first attempt may\n      // hit the cache; subsequent attempts must re-scan the adapter\n      // because the prior conflict means our cached state is stale.\n      if (attempt > 0) {\n        this.headCache = undefined\n      }\n      try {\n        return await this.appendOnce(input)\n      } catch (err) {\n        if (err instanceof ConflictError) {\n          lastConflict = err\n          if (attempt < MAX_APPEND_ATTEMPTS - 1) {\n            await sleepBackoff(attempt)\n          }\n          continue\n        }\n        throw err\n      }\n    }\n    void lastConflict\n    throw new LedgerContentionError(MAX_APPEND_ATTEMPTS)\n  }\n\n  /**\n   * One attempt at the append cycle. Throws `ConflictError` when the\n   * CAS check on the entry put fails — `append()` catches that and\n   * retries. Any other error propagates to the caller.\n   */\n  private async appendOnce(input: AppendInput): Promise<LedgerEntry> {\n    const cached = await this.getCachedHead()\n    const lastEntry = cached?.entry\n    const prevHash = cached?.hash ?? ''\n    const nextIndex = lastEntry ? lastEntry.index + 1 : 0\n\n    // Encrypt the delta in memory so we can compute deltaHash WITHOUT\n    // claiming the deltas slot yet — entry-put is the chain claim.\n    let deltaEnvelope: EncryptedEnvelope | undefined\n    let deltaHash: string | undefined\n    if (input.delta !== undefined) {\n      deltaEnvelope = await this.encryptDelta(input.delta)\n      deltaHash = await sha256Hex(deltaEnvelope._data)\n    }\n\n    // Build the entry. Conditionally include `deltaHash` so\n    // canonicalJson (which rejects undefined) never sees it when\n    // there's no delta.\n    const entryBase = {\n      index: nextIndex,\n      prevHash,\n      op: input.op,\n      collection: input.collection,\n      id: input.id,\n      version: input.version,\n      ts: new Date().toISOString(),\n      actor: input.actor === '' ? this.actor : input.actor,\n      payloadHash: input.payloadHash,\n    } as const\n    const entry: LedgerEntry = {\n      ...entryBase,\n      ...(deltaHash !== undefined ? { deltaHash } : {}),\n      ...(input.amendment !== undefined ? { amendment: input.amendment } : {}),\n      ...(input.reason !== undefined ? { reason: input.reason } : {}),\n    }\n\n    const envelope = await this.encryptEntry(entry)\n    // expectedVersion: 0 ≡ \"the slot must not yet exist.\" Honored by\n    // casAtomic stores; silently passed through by non-CAS stores.\n    await this.adapter.put(\n      this.vault,\n      LEDGER_COLLECTION,\n      paddedIndex(entry.index),\n      envelope,\n      0,\n    )\n\n    // Chain slot claimed. Now write the delta record (if any).\n    if (deltaEnvelope) {\n      await this.adapter.put(\n        this.vault,\n        LEDGER_DELTAS_COLLECTION,\n        paddedIndex(entry.index),\n        deltaEnvelope,\n        0,\n      )\n    }\n\n    // Update the head cache so the next append() doesn't re-scan the\n    // adapter.\n    this.headCache = { entry, hash: await hashEntry(entry) }\n    return entry\n  }\n\n  /**\n   * Load a delta payload by its entry index. Returns `null` if the\n   * entry at that index doesn't reference a delta (genesis puts and\n   * deletes leave the slot empty) or if the delta row is missing\n   * (possible after a `pruneHistory` fold).\n   *\n   * The caller is responsible for deciding what to do with a missing\n   * delta — `ledger.reconstruct()` uses it as a \"stop walking\n   * backward\" signal and falls back to the on-disk current value.\n   */\n  async loadDelta(index: number): Promise<JsonPatch | null> {\n    const envelope = await this.adapter.get(\n      this.vault,\n      LEDGER_DELTAS_COLLECTION,\n      paddedIndex(index),\n    )\n    if (!envelope) return null\n    if (!this.encrypted) {\n      return JSON.parse(envelope._data) as JsonPatch\n    }\n    const dek = await this.getDEK(LEDGER_COLLECTION)\n    const json = await decrypt(envelope._iv, envelope._data, dek)\n    return JSON.parse(json) as JsonPatch\n  }\n\n  /** Encrypt a JSON Patch into an envelope for storage. Mirrors encryptEntry. */\n  private async encryptDelta(patch: JsonPatch): Promise<EncryptedEnvelope> {\n    const json = JSON.stringify(patch)\n    if (!this.encrypted) {\n      return {\n        _noydb: NOYDB_FORMAT_VERSION,\n        _v: 1,\n        _ts: new Date().toISOString(),\n        _iv: '',\n        _data: json,\n        _by: this.actor,\n      }\n    }\n    const dek = await this.getDEK(LEDGER_COLLECTION)\n    const { iv, data } = await encrypt(json, dek)\n    return {\n      _noydb: NOYDB_FORMAT_VERSION,\n      _v: 1,\n      _ts: new Date().toISOString(),\n      _iv: iv,\n      _data: data,\n      _by: this.actor,\n    }\n  }\n\n  /**\n   * Read all entries in ascending-index order. Used internally by\n   * `append()`, `head()`, `verify()`, and `entries()`. Decryption is\n   * serial because the entries are tiny and the overhead of a Promise\n   * pool would dominate at realistic chain lengths (< 100K entries).\n   */\n  async loadAllEntries(): Promise<LedgerEntry[]> {\n    const keys = await this.adapter.list(this.vault, LEDGER_COLLECTION)\n    // Sort lexicographically, which matches numeric order because\n    // keys are zero-padded to 10 digits.\n    keys.sort()\n    const entries: LedgerEntry[] = []\n    for (const key of keys) {\n      const envelope = await this.adapter.get(\n        this.vault,\n        LEDGER_COLLECTION,\n        key,\n      )\n      if (!envelope) continue\n      entries.push(await this.decryptEntry(envelope))\n    }\n    return entries\n  }\n\n  /**\n   * Return the current head of the ledger: the last entry, its hash,\n   * and the total chain length. `null` on an empty ledger so callers\n   * can distinguish \"no history yet\" from \"empty history\".\n   */\n  async head(): Promise<\n    | { readonly entry: LedgerEntry; readonly hash: string; readonly length: number }\n    | null\n  > {\n    const cached = await this.getCachedHead()\n    if (!cached) return null\n    // `length` is `entry.index + 1` because indices are zero-based and\n    // contiguous. We don't need to re-scan the adapter to compute it.\n    return {\n      entry: cached.entry,\n      hash: cached.hash,\n      length: cached.entry.index + 1,\n    }\n  }\n\n  /**\n   * Return entries in the requested half-open range `[from, to)`.\n   * Defaults: `from = 0`, `to = length`. The indices are clipped to\n   * the valid range; no error is thrown for out-of-range queries.\n   */\n  async entries(opts: { from?: number; to?: number } = {}): Promise<LedgerEntry[]> {\n    const all = await this.loadAllEntries()\n    const from = Math.max(0, opts.from ?? 0)\n    const to = Math.min(all.length, opts.to ?? all.length)\n    return all.slice(from, to)\n  }\n\n  /**\n   * Reconstruct a record's state at a given historical version by\n   * walking the ledger's delta chain backward from the current state.\n   *\n   * ## Algorithm\n   *\n   * Ledger deltas are stored in **reverse** form — each entry's\n   * patch describes how to undo that put, transforming the new\n   * record back into the previous one. `reconstruct` exploits this\n   * by:\n   *\n   *   1. Finding every ledger entry for `(collection, id)` in the\n   *      chain, sorted by index ascending.\n   *   2. Starting from `current` (the present value of the record,\n   *      as held by the caller — typically fetched via\n   *      `Collection.get()`).\n   *   3. Walking entries in **descending** index order and applying\n   *      each entry's reverse patch, stopping when we reach the\n   *      entry whose version equals `atVersion`.\n   *\n   * The result is the record as it existed immediately AFTER the\n   * put at `atVersion`. To get the state at the genesis put\n   * (version 1), the walk runs all the way back through every put\n   * after the first.\n   *\n   * ## Caveats\n   *\n   * - **Delete entries** break the walk: once we see a delete, the\n   *   record didn't exist before that point, so there's nothing to\n   *   reconstruct. We return `null` in that case.\n   * - **Missing deltas** (e.g., after `pruneHistory` folds old\n   *   entries into a base snapshot) also stop the walk. does\n   *   not ship pruneHistory, so today this only happens if an entry\n   *   was deleted out-of-band.\n   * - The caller MUST pass the correct current value. Passing a\n   *   mutated object would corrupt the reconstruction — the patch\n   *   chain is only valid against the exact state that was in\n   *   effect when the most recent put happened.\n   *\n   * For, `reconstruct` is the only way to read a historical\n   * version via deltas. The legacy `_history` collection still\n   * holds full snapshots and `Collection.getVersion()` still reads\n   * from there — the two paths coexist until pruneHistory lands in\n   * a follow-up and delta becomes the default.\n   */\n  async reconstruct<T>(\n    collection: string,\n    id: string,\n    current: T,\n    atVersion: number,\n  ): Promise<T | null> {\n    const all = await this.loadAllEntries()\n    // Filter to entries for this (collection, id), in ascending index.\n    const matching = all.filter(\n      (e) => e.collection === collection && e.id === id,\n    )\n    if (matching.length === 0) {\n      // No ledger history at all; the current state IS version 1\n      // (or there's nothing), so the only valid atVersion is the\n      // current record's version. We can't verify that here, so\n      // return current if atVersion is plausible, null otherwise.\n      return null\n    }\n\n    // Walk entries in descending index order, applying each reverse\n    // delta until we reach the target version.\n    let state: T | null = current\n    for (let i = matching.length - 1; i >= 0; i--) {\n      const entry = matching[i]\n      if (!entry) continue\n\n      // Defensive: skip every non-put/non-delete op variant. The\n      // outer filter on `e.collection === collection && e.id === id`\n      // already excludes `amendment` entries (their collection/id are\n      // empty strings), but a top-of-loop guard keeps the walker\n      // robust if a future op variant slips through the filter.\n      if (entry.op !== 'put' && entry.op !== 'delete') continue\n\n      // Match check FIRST — before applying this entry's reverse\n      // patch. `state` at this point is the record state immediately\n      // after this entry's put (or before this entry's delete), so\n      // if the caller asked for this exact version, we're done.\n      if (entry.version === atVersion && entry.op !== 'delete') {\n        return state\n      }\n\n      if (entry.op === 'delete') {\n        // A delete erases the live state. If the caller asks for a\n        // version older than the delete we should continue walking\n        // (state becomes null and the next put resets it). But we\n        // can't reconstruct that pre-delete state from the current\n        // in-memory `state` — the delete has no reverse patch. So\n        // anything past this point is unreachable; return null.\n        return null\n      }\n\n      if (entry.deltaHash === undefined) {\n        // Genesis put — the earliest state for this lifecycle. We\n        // can't walk further back. If the caller asked for exactly\n        // this version, return the current state (we already failed\n        // the match check above because a fresh genesis after a\n        // delete can have version === atVersion). Otherwise the\n        // target is unreachable from here.\n        if (entry.version === atVersion) return state\n        return null\n      }\n\n      const patch = await this.loadDelta(entry.index)\n      if (!patch) {\n        // Delta row is missing (probably pruned). Stop walking.\n        return null\n      }\n\n      if (state === null) {\n        // We're trying to walk back across a delete range and there's\n        // nothing to apply a reverse patch to. Bail.\n        return null\n      }\n\n      state = applyPatch(state, patch)\n    }\n\n    // Ran off the end of the walk without matching. The target\n    // version doesn't exist in this record's chain.\n    return null\n  }\n\n  /**\n   * Walk the chain from genesis forward and verify every link.\n   *\n   * Returns `{ ok: true, head, length }` if every entry's `prevHash`\n   * matches the recomputed hash of its predecessor (and the genesis\n   * entry's `prevHash` is the empty string).\n   *\n   * Returns `{ ok: false, divergedAt, expected, actual }` on the first\n   * mismatch. `divergedAt` is the 0-based index of the BROKEN entry\n   * — entries before that index still verify cleanly; entries at and\n   * after `divergedAt` are untrustworthy.\n   *\n   * This method detects:\n   *   - Mutated entry content (fields changed)\n   *   - Reordered entries (if any adjacent pair swaps, the prevHash\n   *     of the second no longer matches)\n   *   - Inserted entries (the inserted entry's prevHash likely fails,\n   *     and the following entry's prevHash definitely fails)\n   *   - Deleted entries (the entry after the deletion sees a wrong\n   *     prevHash)\n   *\n   * It does NOT detect:\n   *   - Tampering with the DATA collections that bypassed the ledger\n   *     entirely (e.g., an attacker who modifies records without\n   *     appending matching ledger entries — this is why we also\n   *     plan a `verifyIntegrity()` helper in a follow-up)\n   *   - Truncation of the chain at the tail (dropping the last N\n   *     entries leaves a shorter but still consistent chain). External\n   *     anchoring of `head.hash` to a trusted service is the defense\n   *     against this.\n   */\n  async verify(): Promise<VerifyResult> {\n    const entries = await this.loadAllEntries()\n    let expectedPrevHash = ''\n    for (let i = 0; i < entries.length; i++) {\n      const entry = entries[i]\n      if (!entry) continue\n      if (entry.prevHash !== expectedPrevHash) {\n        return {\n          ok: false,\n          divergedAt: i,\n          expected: expectedPrevHash,\n          actual: entry.prevHash,\n        }\n      }\n      if (entry.index !== i) {\n        // An entry whose stored index doesn't match its position in\n        // the sorted list means someone rewrote the adapter keys.\n        // Treat as divergence.\n        return {\n          ok: false,\n          divergedAt: i,\n          expected: `index=${i}`,\n          actual: `index=${entry.index}`,\n        }\n      }\n      expectedPrevHash = await hashEntry(entry)\n    }\n    return {\n      ok: true,\n      head: expectedPrevHash,\n      length: entries.length,\n    }\n  }\n\n  // ─── Encryption plumbing ─────────────────────────────────────────\n\n  /**\n   * Serialize + encrypt a ledger entry into an EncryptedEnvelope. The\n   * envelope's `_v` field is set to `entry.index + 1` so the usual\n   * optimistic-concurrency machinery has a reasonable version number\n   * to compare against (the ledger is append-only, so concurrent\n   * writes should always bump the index).\n   */\n  private async encryptEntry(entry: LedgerEntry): Promise<EncryptedEnvelope> {\n    const json = canonicalJson(entry)\n    if (!this.encrypted) {\n      return {\n        _noydb: NOYDB_FORMAT_VERSION,\n        _v: entry.index + 1,\n        _ts: entry.ts,\n        _iv: '',\n        _data: json,\n        _by: entry.actor,\n      }\n    }\n    const dek = await this.getDEK(LEDGER_COLLECTION)\n    const { iv, data } = await encrypt(json, dek)\n    return {\n      _noydb: NOYDB_FORMAT_VERSION,\n      _v: entry.index + 1,\n      _ts: entry.ts,\n      _iv: iv,\n      _data: data,\n      _by: entry.actor,\n    }\n  }\n\n  /** Decrypt an envelope into a LedgerEntry. Throws on bad key / tamper. */\n  private async decryptEntry(envelope: EncryptedEnvelope): Promise<LedgerEntry> {\n    if (!this.encrypted) {\n      return JSON.parse(envelope._data) as LedgerEntry\n    }\n    const dek = await this.getDEK(LEDGER_COLLECTION)\n    const json = await decrypt(envelope._iv, envelope._data, dek)\n    return JSON.parse(json) as LedgerEntry\n  }\n}\n\n// `envelopePayloadHash` was moved to `./hash.ts` so it can be\n// imported by core code without dragging this file's `LedgerStore`\n// class into the floor bundle. The re-export at the top of this\n// file keeps the original `import { envelopePayloadHash } from '.../store.js'`\n// path working.\n\n/**\n * Exponential backoff with jitter for the append CAS retry loop.\n * Attempt 0 → ~5–10 ms, attempt 7 → ~640–1280 ms. Jitter avoids the\n * thundering-herd problem when multiple writers collide repeatedly.\n */\nfunction sleepBackoff(attempt: number): Promise<void> {\n  const base = 5 * Math.pow(2, attempt)\n  const jitter = Math.random() * base\n  return new Promise((resolve) => setTimeout(resolve, base + jitter))\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA4EO,SAAS,aAAa,MAAe,MAA0B;AACpE,QAAM,MAAqB,CAAC;AAC5B,OAAK,MAAM,MAAM,IAAI,GAAG;AACxB,SAAO;AACT;AAEA,SAAS,KACP,MACA,MACA,MACA,KACM;AAGN,MAAI,SAAS,KAAM;AAGnB,MAAI,SAAS,QAAQ,SAAS,MAAM;AAClC,QAAI,KAAK,EAAE,IAAI,WAAW,MAAM,OAAO,KAAK,CAAC;AAC7C;AAAA,EACF;AAEA,QAAM,cAAc,MAAM,QAAQ,IAAI;AACtC,QAAM,cAAc,MAAM,QAAQ,IAAI;AACtC,QAAM,eAAe,OAAO,SAAS,YAAY,CAAC;AAClD,QAAM,eAAe,OAAO,SAAS,YAAY,CAAC;AAGlD,MAAI,gBAAgB,eAAe,iBAAiB,cAAc;AAChE,QAAI,KAAK,EAAE,IAAI,WAAW,MAAM,OAAO,KAAK,CAAC;AAC7C;AAAA,EACF;AAKA,MAAI,eAAe,aAAa;AAC9B,QAAI,CAAC,eAAe,MAAmB,IAAiB,GAAG;AACzD,UAAI,KAAK,EAAE,IAAI,WAAW,MAAM,OAAO,KAAK,CAAC;AAAA,IAC/C;AACA;AAAA,EACF;AAGA,MAAI,gBAAgB,cAAc;AAChC,UAAM,UAAU;AAChB,UAAM,UAAU;AAChB,UAAM,WAAW,OAAO,KAAK,OAAO;AACpC,UAAM,WAAW,OAAO,KAAK,OAAO;AAGpC,eAAW,OAAO,UAAU;AAC1B,YAAM,YAAY,OAAO,MAAM,kBAAkB,GAAG;AACpD,UAAI,EAAE,OAAO,UAAU;AACrB,YAAI,KAAK,EAAE,IAAI,UAAU,MAAM,UAAU,CAAC;AAAA,MAC5C,OAAO;AACL,aAAK,QAAQ,GAAG,GAAG,QAAQ,GAAG,GAAG,WAAW,GAAG;AAAA,MACjD;AAAA,IACF;AAEA,eAAW,OAAO,UAAU;AAC1B,UAAI,EAAE,OAAO,UAAU;AACrB,YAAI,KAAK;AAAA,UACP,IAAI;AAAA,UACJ,MAAM,OAAO,MAAM,kBAAkB,GAAG;AAAA,UACxC,OAAO,QAAQ,GAAG;AAAA,QACpB,CAAC;AAAA,MACH;AAAA,IACF;AACA;AAAA,EACF;AAGA,MAAI,KAAK,EAAE,IAAI,WAAW,MAAM,OAAO,KAAK,CAAC;AAC/C;AAEA,SAAS,eAAe,GAAc,GAAuB;AAC3D,MAAI,EAAE,WAAW,EAAE,OAAQ,QAAO;AAClC,WAAS,IAAI,GAAG,IAAI,EAAE,QAAQ,KAAK;AACjC,QAAI,CAAC,UAAU,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,EAAG,QAAO;AAAA,EACrC;AACA,SAAO;AACT;AAEA,SAAS,UAAU,GAAY,GAAqB;AAClD,MAAI,MAAM,EAAG,QAAO;AACpB,MAAI,MAAM,QAAQ,MAAM,KAAM,QAAO;AACrC,MAAI,OAAO,MAAM,OAAO,EAAG,QAAO;AAClC,MAAI,OAAO,MAAM,SAAU,QAAO;AAClC,QAAM,SAAS,MAAM,QAAQ,CAAC;AAC9B,QAAM,SAAS,MAAM,QAAQ,CAAC;AAC9B,MAAI,WAAW,OAAQ,QAAO;AAC9B,MAAI,UAAU,OAAQ,QAAO,eAAe,GAAG,CAAc;AAC7D,QAAM,OAAO;AACb,QAAM,OAAO;AACb,QAAM,QAAQ,OAAO,KAAK,IAAI;AAC9B,QAAM,QAAQ,OAAO,KAAK,IAAI;AAC9B,MAAI,MAAM,WAAW,MAAM,OAAQ,QAAO;AAC1C,aAAW,OAAO,OAAO;AACvB,QAAI,EAAE,OAAO,MAAO,QAAO;AAC3B,QAAI,CAAC,UAAU,KAAK,GAAG,GAAG,KAAK,GAAG,CAAC,EAAG,QAAO;AAAA,EAC/C;AACA,SAAO;AACT;AAsBO,SAAS,WAAwB,MAAS,OAAqB;AACpE,MAAI,SAAkB,MAAM,IAAI;AAChC,aAAW,MAAM,OAAO;AACtB,aAAS,QAAQ,QAAQ,EAAE;AAAA,EAC7B;AACA,SAAO;AACT;AAEA,SAAS,QAAQ,KAAc,IAA0B;AAIvD,MAAI,GAAG,SAAS,IAAI;AAClB,QAAI,GAAG,OAAO,SAAU,QAAO;AAC/B,WAAO,MAAM,GAAG,KAAK;AAAA,EACvB;AAEA,QAAM,WAAW,UAAU,GAAG,IAAI;AAClC,SAAO,aAAa,KAAK,UAAU,EAAE;AACvC;AAEA,SAAS,aACP,KACA,UACA,IACS;AACT,MAAI,SAAS,WAAW,GAAG;AAEzB,UAAM,IAAI,MAAM,+CAA+C;AAAA,EACjE;AAEA,QAAM,CAAC,MAAM,GAAG,IAAI,IAAI;AACxB,MAAI,SAAS,OAAW,OAAM,IAAI,MAAM,iCAAiC;AAEzE,MAAI,KAAK,WAAW,GAAG;AACrB,WAAO,gBAAgB,KAAK,MAAM,EAAE;AAAA,EACtC;AAIA,MAAI,MAAM,QAAQ,GAAG,GAAG;AACtB,UAAM,MAAM,gBAAgB,MAAM,IAAI,MAAM;AAC5C,UAAM,QAAQ,IAAI,GAAG;AACrB,UAAM,WAAW,aAAa,OAAO,MAAM,EAAE;AAC7C,UAAM,OAAO,IAAI,MAAM;AACvB,SAAK,GAAG,IAAI;AACZ,WAAO;AAAA,EACT;AACA,MAAI,QAAQ,QAAQ,OAAO,QAAQ,UAAU;AAC3C,UAAM,MAAM;AACZ,QAAI,EAAE,QAAQ,MAAM;AAClB,YAAM,IAAI,MAAM,6BAA6B,IAAI,uBAAuB;AAAA,IAC1E;AACA,UAAM,WAAW,aAAa,IAAI,IAAI,GAAG,MAAM,EAAE;AACjD,WAAO,EAAE,GAAG,KAAK,CAAC,IAAI,GAAG,SAAS;AAAA,EACpC;AACA,QAAM,IAAI;AAAA,IACR,gCAAgC,OAAO,GAAG,gBAAgB,IAAI;AAAA,EAChE;AACF;AAEA,SAAS,gBACP,KACA,SACA,IACS;AACT,MAAI,MAAM,QAAQ,GAAG,GAAG;AACtB,UAAM,MACJ,YAAY,MAAM,IAAI,SAAS,gBAAgB,SAAS,IAAI,SAAS,CAAC;AACxE,UAAM,OAAO,IAAI,MAAM;AACvB,QAAI,GAAG,OAAO,UAAU;AACtB,WAAK,OAAO,KAAK,CAAC;AAClB,aAAO;AAAA,IACT;AACA,QAAI,GAAG,OAAO,OAAO;AACnB,WAAK,OAAO,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;AACnC,aAAO;AAAA,IACT;AACA,QAAI,GAAG,OAAO,WAAW;AACvB,UAAI,OAAO,IAAI,QAAQ;AACrB,cAAM,IAAI;AAAA,UACR,oDAAoD,GAAG;AAAA,QACzD;AAAA,MACF;AACA,WAAK,GAAG,IAAI,MAAM,GAAG,KAAK;AAC1B,aAAO;AAAA,IACT;AAAA,EACF;AACA,MAAI,QAAQ,QAAQ,OAAO,QAAQ,UAAU;AAC3C,UAAM,MAAM;AACZ,QAAI,GAAG,OAAO,UAAU;AACtB,UAAI,EAAE,WAAW,MAAM;AACrB,cAAM,IAAI;AAAA,UACR,sCAAsC,OAAO;AAAA,QAC/C;AAAA,MACF;AACA,YAAM,OAAO,EAAE,GAAG,IAAI;AACtB,aAAO,KAAK,OAAO;AACnB,aAAO;AAAA,IACT;AACA,QAAI,GAAG,OAAO,OAAO;AAEnB,aAAO,EAAE,GAAG,KAAK,CAAC,OAAO,GAAG,MAAM,GAAG,KAAK,EAAE;AAAA,IAC9C;AACA,QAAI,GAAG,OAAO,WAAW;AACvB,UAAI,EAAE,WAAW,MAAM;AACrB,cAAM,IAAI;AAAA,UACR,uCAAuC,OAAO;AAAA,QAChD;AAAA,MACF;AACA,aAAO,EAAE,GAAG,KAAK,CAAC,OAAO,GAAG,MAAM,GAAG,KAAK,EAAE;AAAA,IAC9C;AAAA,EACF;AACA,QAAM,IAAI;AAAA,IACR,4BAA4B,GAAG,EAAE,yBAAyB,OAAO;AAAA,EACnE;AACF;AAYA,SAAS,kBAAkB,SAAyB;AAClD,SAAO,QAAQ,QAAQ,MAAM,IAAI,EAAE,QAAQ,OAAO,IAAI;AACxD;AAEA,SAAS,oBAAoB,SAAyB;AACpD,SAAO,QAAQ,QAAQ,OAAO,GAAG,EAAE,QAAQ,OAAO,GAAG;AACvD;AAEA,SAAS,UAAU,MAAwB;AACzC,MAAI,CAAC,KAAK,WAAW,GAAG,GAAG;AACzB,UAAM,IAAI,MAAM,8CAA8C,IAAI,GAAG;AAAA,EACvE;AACA,SAAO,KACJ,MAAM,CAAC,EACP,MAAM,GAAG,EACT,IAAI,mBAAmB;AAC5B;AAEA,SAAS,gBAAgB,SAAiB,KAAqB;AAC7D,MAAI,CAAC,QAAQ,KAAK,OAAO,GAAG;AAC1B,UAAM,IAAI;AAAA,MACR,gEAAgE,OAAO;AAAA,IACzE;AAAA,EACF;AACA,QAAM,MAAM,OAAO,SAAS,SAAS,EAAE;AACvC,MAAI,MAAM,KAAK,MAAM,KAAK;AACxB,UAAM,IAAI;AAAA,MACR,2BAA2B,GAAG,qBAAqB,GAAG;AAAA,IACxD;AAAA,EACF;AACA,SAAO;AACT;AAeA,SAAS,MAAS,OAAa;AAC7B,MAAI,UAAU,QAAQ,UAAU,OAAW,QAAO;AAClD,MAAI,OAAO,UAAU,SAAU,QAAO;AACtC,SAAO,KAAK,MAAM,KAAK,UAAU,KAAK,CAAC;AACzC;;;AC5WO,IAAM,oBAAoB;AAuB1B,IAAM,2BAA2B;;;AC+BxC,IAAM,sBAAsB;AA0ErB,IAAM,cAAN,MAAkB;AAAA,EACN;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAsBT,YAAqE;AAAA,EAE7E,YAAY,MAMT;AACD,SAAK,UAAU,KAAK;AACpB,SAAK,QAAQ,KAAK;AAClB,SAAK,YAAY,KAAK;AACtB,SAAK,SAAS,KAAK;AACnB,SAAK,QAAQ,KAAK;AAAA,EACpB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAc,gBAAsE;AAClF,QAAI,KAAK,cAAc,OAAW,QAAO,KAAK;AAC9C,UAAM,UAAU,MAAM,KAAK,eAAe;AAC1C,UAAM,OAAO,QAAQ,QAAQ,SAAS,CAAC;AACvC,QAAI,CAAC,MAAM;AACT,WAAK,YAAY;AACjB,aAAO;AAAA,IACT;AACA,SAAK,YAAY,EAAE,OAAO,MAAM,MAAM,MAAM,UAAU,IAAI,EAAE;AAC5D,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EA4CA,MAAM,OAAO,OAA0C;AACrD,QAAI;AACJ,aAAS,UAAU,GAAG,UAAU,qBAAqB,WAAW;AAI9D,UAAI,UAAU,GAAG;AACf,aAAK,YAAY;AAAA,MACnB;AACA,UAAI;AACF,eAAO,MAAM,KAAK,WAAW,KAAK;AAAA,MACpC,SAAS,KAAK;AACZ,YAAI,eAAe,eAAe;AAChC,yBAAe;AACf,cAAI,UAAU,sBAAsB,GAAG;AACrC,kBAAM,aAAa,OAAO;AAAA,UAC5B;AACA;AAAA,QACF;AACA,cAAM;AAAA,MACR;AAAA,IACF;AACA,SAAK;AACL,UAAM,IAAI,sBAAsB,mBAAmB;AAAA,EACrD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAc,WAAW,OAA0C;AACjE,UAAM,SAAS,MAAM,KAAK,cAAc;AACxC,UAAM,YAAY,QAAQ;AAC1B,UAAM,WAAW,QAAQ,QAAQ;AACjC,UAAM,YAAY,YAAY,UAAU,QAAQ,IAAI;AAIpD,QAAI;AACJ,QAAI;AACJ,QAAI,MAAM,UAAU,QAAW;AAC7B,sBAAgB,MAAM,KAAK,aAAa,MAAM,KAAK;AACnD,kBAAY,MAAM,UAAU,cAAc,KAAK;AAAA,IACjD;AAKA,UAAM,YAAY;AAAA,MAChB,OAAO;AAAA,MACP;AAAA,MACA,IAAI,MAAM;AAAA,MACV,YAAY,MAAM;AAAA,MAClB,IAAI,MAAM;AAAA,MACV,SAAS,MAAM;AAAA,MACf,KAAI,oBAAI,KAAK,GAAE,YAAY;AAAA,MAC3B,OAAO,MAAM,UAAU,KAAK,KAAK,QAAQ,MAAM;AAAA,MAC/C,aAAa,MAAM;AAAA,IACrB;AACA,UAAM,QAAqB;AAAA,MACzB,GAAG;AAAA,MACH,GAAI,cAAc,SAAY,EAAE,UAAU,IAAI,CAAC;AAAA,MAC/C,GAAI,MAAM,cAAc,SAAY,EAAE,WAAW,MAAM,UAAU,IAAI,CAAC;AAAA,MACtE,GAAI,MAAM,WAAW,SAAY,EAAE,QAAQ,MAAM,OAAO,IAAI,CAAC;AAAA,IAC/D;AAEA,UAAM,WAAW,MAAM,KAAK,aAAa,KAAK;AAG9C,UAAM,KAAK,QAAQ;AAAA,MACjB,KAAK;AAAA,MACL;AAAA,MACA,YAAY,MAAM,KAAK;AAAA,MACvB;AAAA,MACA;AAAA,IACF;AAGA,QAAI,eAAe;AACjB,YAAM,KAAK,QAAQ;AAAA,QACjB,KAAK;AAAA,QACL;AAAA,QACA,YAAY,MAAM,KAAK;AAAA,QACvB;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAIA,SAAK,YAAY,EAAE,OAAO,MAAM,MAAM,UAAU,KAAK,EAAE;AACvD,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,MAAM,UAAU,OAA0C;AACxD,UAAM,WAAW,MAAM,KAAK,QAAQ;AAAA,MAClC,KAAK;AAAA,MACL;AAAA,MACA,YAAY,KAAK;AAAA,IACnB;AACA,QAAI,CAAC,SAAU,QAAO;AACtB,QAAI,CAAC,KAAK,WAAW;AACnB,aAAO,KAAK,MAAM,SAAS,KAAK;AAAA,IAClC;AACA,UAAM,MAAM,MAAM,KAAK,OAAO,iBAAiB;AAC/C,UAAM,OAAO,MAAM,QAAQ,SAAS,KAAK,SAAS,OAAO,GAAG;AAC5D,WAAO,KAAK,MAAM,IAAI;AAAA,EACxB;AAAA;AAAA,EAGA,MAAc,aAAa,OAA8C;AACvE,UAAM,OAAO,KAAK,UAAU,KAAK;AACjC,QAAI,CAAC,KAAK,WAAW;AACnB,aAAO;AAAA,QACL,QAAQ;AAAA,QACR,IAAI;AAAA,QACJ,MAAK,oBAAI,KAAK,GAAE,YAAY;AAAA,QAC5B,KAAK;AAAA,QACL,OAAO;AAAA,QACP,KAAK,KAAK;AAAA,MACZ;AAAA,IACF;AACA,UAAM,MAAM,MAAM,KAAK,OAAO,iBAAiB;AAC/C,UAAM,EAAE,IAAI,KAAK,IAAI,MAAM,QAAQ,MAAM,GAAG;AAC5C,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,IAAI;AAAA,MACJ,MAAK,oBAAI,KAAK,GAAE,YAAY;AAAA,MAC5B,KAAK;AAAA,MACL,OAAO;AAAA,MACP,KAAK,KAAK;AAAA,IACZ;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,iBAAyC;AAC7C,UAAM,OAAO,MAAM,KAAK,QAAQ,KAAK,KAAK,OAAO,iBAAiB;AAGlE,SAAK,KAAK;AACV,UAAM,UAAyB,CAAC;AAChC,eAAW,OAAO,MAAM;AACtB,YAAM,WAAW,MAAM,KAAK,QAAQ;AAAA,QAClC,KAAK;AAAA,QACL;AAAA,QACA;AAAA,MACF;AACA,UAAI,CAAC,SAAU;AACf,cAAQ,KAAK,MAAM,KAAK,aAAa,QAAQ,CAAC;AAAA,IAChD;AACA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,OAGJ;AACA,UAAM,SAAS,MAAM,KAAK,cAAc;AACxC,QAAI,CAAC,OAAQ,QAAO;AAGpB,WAAO;AAAA,MACL,OAAO,OAAO;AAAA,MACd,MAAM,OAAO;AAAA,MACb,QAAQ,OAAO,MAAM,QAAQ;AAAA,IAC/B;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,QAAQ,OAAuC,CAAC,GAA2B;AAC/E,UAAM,MAAM,MAAM,KAAK,eAAe;AACtC,UAAM,OAAO,KAAK,IAAI,GAAG,KAAK,QAAQ,CAAC;AACvC,UAAM,KAAK,KAAK,IAAI,IAAI,QAAQ,KAAK,MAAM,IAAI,MAAM;AACrD,WAAO,IAAI,MAAM,MAAM,EAAE;AAAA,EAC3B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EA+CA,MAAM,YACJ,YACA,IACA,SACA,WACmB;AACnB,UAAM,MAAM,MAAM,KAAK,eAAe;AAEtC,UAAM,WAAW,IAAI;AAAA,MACnB,CAAC,MAAM,EAAE,eAAe,cAAc,EAAE,OAAO;AAAA,IACjD;AACA,QAAI,SAAS,WAAW,GAAG;AAKzB,aAAO;AAAA,IACT;AAIA,QAAI,QAAkB;AACtB,aAAS,IAAI,SAAS,SAAS,GAAG,KAAK,GAAG,KAAK;AAC7C,YAAM,QAAQ,SAAS,CAAC;AACxB,UAAI,CAAC,MAAO;AAOZ,UAAI,MAAM,OAAO,SAAS,MAAM,OAAO,SAAU;AAMjD,UAAI,MAAM,YAAY,aAAa,MAAM,OAAO,UAAU;AACxD,eAAO;AAAA,MACT;AAEA,UAAI,MAAM,OAAO,UAAU;AAOzB,eAAO;AAAA,MACT;AAEA,UAAI,MAAM,cAAc,QAAW;AAOjC,YAAI,MAAM,YAAY,UAAW,QAAO;AACxC,eAAO;AAAA,MACT;AAEA,YAAM,QAAQ,MAAM,KAAK,UAAU,MAAM,KAAK;AAC9C,UAAI,CAAC,OAAO;AAEV,eAAO;AAAA,MACT;AAEA,UAAI,UAAU,MAAM;AAGlB,eAAO;AAAA,MACT;AAEA,cAAQ,WAAW,OAAO,KAAK;AAAA,IACjC;AAIA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAiCA,MAAM,SAAgC;AACpC,UAAM,UAAU,MAAM,KAAK,eAAe;AAC1C,QAAI,mBAAmB;AACvB,aAAS,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAAK;AACvC,YAAM,QAAQ,QAAQ,CAAC;AACvB,UAAI,CAAC,MAAO;AACZ,UAAI,MAAM,aAAa,kBAAkB;AACvC,eAAO;AAAA,UACL,IAAI;AAAA,UACJ,YAAY;AAAA,UACZ,UAAU;AAAA,UACV,QAAQ,MAAM;AAAA,QAChB;AAAA,MACF;AACA,UAAI,MAAM,UAAU,GAAG;AAIrB,eAAO;AAAA,UACL,IAAI;AAAA,UACJ,YAAY;AAAA,UACZ,UAAU,SAAS,CAAC;AAAA,UACpB,QAAQ,SAAS,MAAM,KAAK;AAAA,QAC9B;AAAA,MACF;AACA,yBAAmB,MAAM,UAAU,KAAK;AAAA,IAC1C;AACA,WAAO;AAAA,MACL,IAAI;AAAA,MACJ,MAAM;AAAA,MACN,QAAQ,QAAQ;AAAA,IAClB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,MAAc,aAAa,OAAgD;AACzE,UAAM,OAAO,cAAc,KAAK;AAChC,QAAI,CAAC,KAAK,WAAW;AACnB,aAAO;AAAA,QACL,QAAQ;AAAA,QACR,IAAI,MAAM,QAAQ;AAAA,QAClB,KAAK,MAAM;AAAA,QACX,KAAK;AAAA,QACL,OAAO;AAAA,QACP,KAAK,MAAM;AAAA,MACb;AAAA,IACF;AACA,UAAM,MAAM,MAAM,KAAK,OAAO,iBAAiB;AAC/C,UAAM,EAAE,IAAI,KAAK,IAAI,MAAM,QAAQ,MAAM,GAAG;AAC5C,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,IAAI,MAAM,QAAQ;AAAA,MAClB,KAAK,MAAM;AAAA,MACX,KAAK;AAAA,MACL,OAAO;AAAA,MACP,KAAK,MAAM;AAAA,IACb;AAAA,EACF;AAAA;AAAA,EAGA,MAAc,aAAa,UAAmD;AAC5E,QAAI,CAAC,KAAK,WAAW;AACnB,aAAO,KAAK,MAAM,SAAS,KAAK;AAAA,IAClC;AACA,UAAM,MAAM,MAAM,KAAK,OAAO,iBAAiB;AAC/C,UAAM,OAAO,MAAM,QAAQ,SAAS,KAAK,SAAS,OAAO,GAAG;AAC5D,WAAO,KAAK,MAAM,IAAI;AAAA,EACxB;AACF;AAaA,SAAS,aAAa,SAAgC;AACpD,QAAM,OAAO,IAAI,KAAK,IAAI,GAAG,OAAO;AACpC,QAAM,SAAS,KAAK,OAAO,IAAI;AAC/B,SAAO,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,OAAO,MAAM,CAAC;AACpE;","names":[]}

package/dist/{chunk-YDLAFP36.js → chunk-6HJ2ZALB.js}

@@ -882,4 +882,4 @@ export {
   OverlayNameCollisionError,
   OverlayIdMismatchError
 };
-//# sourceMappingURL=chunk-YDLAFP36.js.map
+//# sourceMappingURL=chunk-6HJ2ZALB.js.map

package/dist/chunk-6HJ2ZALB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts"],"sourcesContent":["/**\n * All NOYDB error classes — a single import surface for `catch` blocks and\n * `instanceof` checks.\n *\n * ## Class hierarchy\n *\n * ```\n * Error\n *  └─ NoydbError (code: string)\n *       ├─ Crypto errors\n *       │    ├─ DecryptionError        — AES-GCM tag failure\n *       │    ├─ TamperedError          — ciphertext modified after write\n *       │    └─ InvalidKeyError        — wrong passphrase / corrupt keyring\n *       ├─ Access errors\n *       │    ├─ NoAccessError          — no DEK for this collection\n *       │    ├─ ReadOnlyError          — ro permission, write attempted\n *       │    ├─ PermissionDeniedError  — role too low for operation\n *       │    ├─ PrivilegeEscalationError — grant wider than grantor holds\n *       │    └─ StoreCapabilityError   — optional store method missing\n *       ├─ Sync errors\n *       │    ├─ ConflictError          — optimistic-lock version mismatch\n *       │    ├─ BundleVersionConflictError — bundle push rejected by remote\n *       │    └─ NetworkError           — push/pull network failure\n *       ├─ Data errors\n *       │    ├─ NotFoundError          — get(id) on missing record\n *       │    ├─ ValidationError        — application-level guard failed\n *       │    └─ SchemaValidationError  — Standard Schema v1 rejection\n *       ├─ Query errors\n *       │    ├─ JoinTooLargeError      — join row ceiling exceeded\n *       │    ├─ DanglingReferenceError — strict ref() points at nothing\n *       │    ├─ GroupCardinalityError  — groupBy bucket cap exceeded\n *       │    ├─ IndexRequiredError      — lazy-mode query touches unindexed field\n *       │    └─ IndexWriteFailureError       — index side-car put/delete failed post-main\n *       ├─ i18n / Dictionary errors\n *       │    ├─ ReservedCollectionNameError\n *       │    ├─ DictKeyMissingError\n *       │    ├─ DictKeyInUseError\n *       │    ├─ MissingTranslationError\n *       │    ├─ LocaleNotSpecifiedError\n *       │    └─ TranslatorNotConfiguredError\n *       ├─ Backup errors\n *       │    ├─ BackupLedgerError      — hash-chain verification failed\n *       │    └─ BackupCorruptedError   — envelope hash mismatch in dump\n *       ├─ Bundle errors\n *       │    └─ BundleIntegrityError   — .noydb body sha256 mismatch\n *       └─ Session errors\n *            ├─ SessionExpiredError\n *            ├─ SessionNotFoundError\n *            └─ SessionPolicyError\n * ```\n *\n * ## Catching all NOYDB errors\n *\n * ```ts\n * import { NoydbError, InvalidKeyError, ConflictError } from '@noy-db/hub'\n *\n * try {\n *   await vault.unlock(passphrase)\n * } catch (e) {\n *   if (e instanceof InvalidKeyError) { showBadPassphraseUI(); return }\n *   if (e instanceof NoydbError) { logToSentry(e.code, e); return }\n *   throw e  // unexpected — re-throw\n * }\n * ```\n *\n * @module\n */\n\n/**\n * Base class for all NOYDB errors.\n *\n * Every error thrown by `@noy-db/hub` extends this class, so consumers can\n * catch all NOYDB errors in a single `catch (e) { if (e instanceof NoydbError) ... }`\n * block. The `code` field is a machine-readable string (e.g. `'DECRYPTION_FAILED'`)\n * suitable for `switch` statements and logging pipelines.\n */\nexport class NoydbError extends Error {\n  /** Machine-readable error code. Stable across library versions. */\n  readonly code: string\n\n  constructor(code: string, message: string) {\n    super(message)\n    this.name = 'NoydbError'\n    this.code = code\n  }\n}\n\n// ─── Crypto Errors ─────────────────────────────────────────────────────\n\n/**\n * Thrown when AES-GCM decryption fails.\n *\n * The most common cause is a wrong passphrase or a corrupted ciphertext.\n * A `DecryptionError` at the wrong passphrase level is caught internally\n * and re-thrown as `InvalidKeyError` — so in practice this surfaces for\n * per-record corruption rather than authentication failures.\n */\nexport class DecryptionError extends NoydbError {\n  constructor(message = 'Decryption failed') {\n    super('DECRYPTION_FAILED', message)\n    this.name = 'DecryptionError'\n  }\n}\n\n/**\n * Thrown when GCM tag verification fails, indicating the ciphertext was\n * modified after encryption.\n *\n * AES-256-GCM is authenticated encryption — the tag over the ciphertext\n * is checked on every decrypt. If any byte was flipped (accidental\n * corruption or deliberate tampering), decryption throws this error.\n * Treat it as a security alert: the stored bytes are not what NOYDB wrote.\n */\nexport class TamperedError extends NoydbError {\n  constructor(message = 'Data integrity check failed — record may have been tampered with') {\n    super('TAMPERED', message)\n    this.name = 'TamperedError'\n  }\n}\n\n/**\n * Thrown when key unwrapping fails, typically because the passphrase is wrong\n * or the keyring file is corrupted.\n *\n * NOYDB uses AES-KW (RFC 3394) to wrap DEKs with the KEK. If AES-KW\n * unwrapping fails, it means either the KEK was derived from the wrong\n * passphrase (PBKDF2 with 600K iterations) or the keyring bytes are\n * corrupted. This is the error shown to the user on a failed unlock attempt.\n */\nexport class InvalidKeyError extends NoydbError {\n  constructor(message = 'Invalid key — wrong passphrase or corrupted keyring') {\n    super('INVALID_KEY', message)\n    this.name = 'InvalidKeyError'\n  }\n}\n\n/**\n * Thrown when a keyring's wrapped-DEK set unwraps partially — at least\n * one DEK succeeds (proving the KEK is correct) but at least one fails.\n * The passphrase is right; the failed entries are corrupted.\n *\n * This is distinct from {@link InvalidKeyError} so that\n * `NoydbOptions.onInvalidKey: 'reset'` does NOT fire — resetting on\n * partial corruption would destroy the still-valid DEKs and the data\n * they protect, which is silent data loss in response to a feature\n * designed for stale-credential recovery.\n */\nexport class KeyringCorruptError extends NoydbError {\n  readonly failedCollections: readonly string[]\n  readonly intactCount: number\n  constructor(opts: { failedCollections: readonly string[]; intactCount: number; message?: string }) {\n    super(\n      'KEYRING_CORRUPT',\n      opts.message ??\n        `Keyring has ${opts.failedCollections.length} corrupted wrapped DEK(s) ` +\n          `(${opts.failedCollections.join(', ')}); ${opts.intactCount} other DEK(s) ` +\n          `unwrapped successfully — the passphrase is correct, the entries are damaged. ` +\n          `Do NOT use onInvalidKey: 'reset' here — that would destroy the intact DEKs.`,\n    )\n    this.name = 'KeyringCorruptError'\n    this.failedCollections = opts.failedCollections\n    this.intactCount = opts.intactCount\n  }\n}\n\n// ─── Access Errors ─────────────────────────────────────────────────────\n\n/**\n * Thrown when the authenticated user does not have a DEK for the requested\n * collection — i.e. the collection is not in their keyring at all.\n *\n * This is the \"no key for this door\" error. It is different from\n * `ReadOnlyError` (user has a key but it only grants ro) and from\n * `PermissionDeniedError` (user's role doesn't allow the operation).\n */\nexport class NoAccessError extends NoydbError {\n  constructor(message = 'No access — user does not have a key for this collection') {\n    super('NO_ACCESS', message)\n    this.name = 'NoAccessError'\n  }\n}\n\n/**\n * Thrown when a user with read-only (`ro`) permission attempts a write\n * operation (`put` or `delete`) on a collection.\n *\n * The user has a DEK for the collection (they can decrypt and read), but\n * their keyring grants only `ro`. To fix: re-grant the user with `rw`\n * permission, or do not attempt writes as a viewer/client role.\n */\nexport class ReadOnlyError extends NoydbError {\n  constructor(message = 'Read-only — user has ro permission on this collection') {\n    super('READ_ONLY', message)\n    this.name = 'ReadOnlyError'\n  }\n}\n\n/**\n * Thrown when a write is attempted against a historical view produced\n * by `vault.at(timestamp)`. Time-machine views are read-only by\n * contract — mutating the past would require either the shadow-vault\n * mechanism or a ledger-history rewrite (which breaks\n * the tamper-evidence guarantee).\n *\n * Distinct from {@link ReadOnlyError} (keyring-level) and\n * {@link PermissionDeniedError} (role-level): this error is about the\n * *view* being historical, independent of the caller's permissions.\n */\nexport class ReadOnlyAtInstantError extends NoydbError {\n  constructor(operation: string, timestamp: string) {\n    super(\n      'READ_ONLY_AT_INSTANT',\n      `Cannot ${operation}() on a vault view anchored at ${timestamp} — time-machine views are read-only`,\n    )\n    this.name = 'ReadOnlyAtInstantError'\n  }\n}\n\n/**\n * Thrown when a write is attempted against a shadow-vault frame\n * produced by `vault.frame()`. Frames are read-only by contract —\n * the use case is screen-sharing / demos / compliance review where\n * the operator wants to prevent accidental edits.\n *\n * Behavioural enforcement only — the underlying keyring still holds\n * write-capable DEKs. See {@link VaultFrame} for the full caveat.\n */\nexport class ReadOnlyFrameError extends NoydbError {\n  constructor(operation: string) {\n    super(\n      'READ_ONLY_FRAME',\n      `Cannot ${operation}() on a vault frame — frames are read-only presentations of the current vault`,\n    )\n    this.name = 'ReadOnlyFrameError'\n  }\n}\n\n/**\n * Thrown when the authenticated user's role does not permit the requested\n * operation — e.g. a `viewer` calling `grantAccess()`, or an `operator`\n * calling `rotateKeys()`.\n *\n * This is a role-level check (what the user's role allows), distinct from\n * `NoAccessError` (collection not in keyring) and `ReadOnlyError` (in\n * keyring, but write not allowed).\n */\nexport class PermissionDeniedError extends NoydbError {\n  constructor(message = 'Permission denied — insufficient role for this operation') {\n    super('PERMISSION_DENIED', message)\n    this.name = 'PermissionDeniedError'\n  }\n}\n\n/**\n * Thrown when an `@noy-db/as-*` export is attempted without the\n * required capability bit on the invoking keyring.\n *\n * Two sub-cases discriminated by the `tier` field:\n *\n * - `tier: 'plaintext'` — a plaintext-tier export (`as-xlsx`,\n *   `as-csv`, `as-blob`, `as-zip`, …) was attempted but the\n *   keyring's `exportCapability.plaintext` does not include the\n *   requested `format` (nor the `'*'` wildcard). Default for every\n *   role is `plaintext: []` — the owner must positively grant.\n * - `tier: 'bundle'` — an encrypted `as-noydb` bundle export was\n *   attempted but the keyring's `exportCapability.bundle` is\n *   `false`. Default for `owner`/`admin` is `true`; for\n *   `operator`/`viewer`/`client` it is `false`.\n *\n * Distinct from `PermissionDeniedError` (role-level check) and\n * `NoAccessError` (collection not readable). Surfaces separately so\n * UI layers can show a \"request the export capability from your\n * admin\" flow rather than a generic permission error.\n */\nexport class ExportCapabilityError extends NoydbError {\n  readonly tier: 'plaintext' | 'bundle'\n  readonly format?: string\n  readonly userId: string\n\n  constructor(opts: {\n    tier: 'plaintext' | 'bundle'\n    userId: string\n    format?: string\n    message?: string\n  }) {\n    const msg =\n      opts.message ??\n      (opts.tier === 'plaintext'\n        ? `Export capability denied — keyring \"${opts.userId}\" is not granted plaintext-export capability for format \"${opts.format ?? '<unknown>'}\". Ask a vault owner or admin to grant it via vault.grant({ exportCapability: { plaintext: ['${opts.format ?? '<format>'}'] } }).`\n        : `Export capability denied — keyring \"${opts.userId}\" is not granted encrypted-bundle export capability. Ask a vault owner or admin to grant it via vault.grant({ exportCapability: { bundle: true } }).`)\n    super('EXPORT_CAPABILITY', msg)\n    this.name = 'ExportCapabilityError'\n    this.tier = opts.tier\n    this.userId = opts.userId\n    if (opts.format !== undefined) this.format = opts.format\n  }\n}\n\n/**\n * Thrown when a keyring file's `expires_at` cutoff has passed.\n * Surfaced by `loadKeyring` before any DEK unwrap is attempted —\n * past the cutoff the slot refuses to open even with the right\n * passphrase. Distinct from PBKDF2 / unwrap errors so consumer code\n * can show a precise \"this bundle slot has expired\" message instead\n * of the generic decryption-failure UX.\n *\n * Used predominantly on `BundleRecipient` slots produced by\n * `writeNoydbBundle({ recipients: [...] })` to time-box audit access.\n */\nexport class KeyringExpiredError extends NoydbError {\n  readonly userId: string\n  readonly expiresAt: string\n  constructor(opts: { userId: string; expiresAt: string }) {\n    super(\n      'KEYRING_EXPIRED',\n      `Keyring \"${opts.userId}\" expired at ${opts.expiresAt}. ` +\n        'The slot refuses to unlock past its expiry timestamp.',\n    )\n    this.name = 'KeyringExpiredError'\n    this.userId = opts.userId\n    this.expiresAt = opts.expiresAt\n  }\n}\n\n/**\n * Thrown when an `@noy-db/as-*` import is attempted but the invoking\n * keyring lacks the required import-capability bit.\n *\n * - `tier: 'plaintext'` — a plaintext-tier import (`as-csv`, `as-json`,\n *   `as-ndjson`, `as-zip`, …) was attempted but the keyring's\n *   `importCapability.plaintext` does not include the requested\n *   `format` (nor the `'*'` wildcard).\n * - `tier: 'bundle'` — a `.noydb` bundle import was attempted but the\n *   keyring's `importCapability.bundle` is not `true`.\n *\n * Default for every role on every dimension is closed — owners and\n * admins must positively grant the capability. Distinct from\n * `PermissionDeniedError` and `NoAccessError` so UI layers can show a\n * specific \"request the import capability\" flow.\n */\nexport class ImportCapabilityError extends NoydbError {\n  readonly tier: 'plaintext' | 'bundle'\n  readonly format?: string\n  readonly userId: string\n\n  constructor(opts: {\n    tier: 'plaintext' | 'bundle'\n    userId: string\n    format?: string\n    message?: string\n  }) {\n    const msg =\n      opts.message ??\n      (opts.tier === 'plaintext'\n        ? `Import capability denied — keyring \"${opts.userId}\" is not granted plaintext-import capability for format \"${opts.format ?? '<unknown>'}\". Ask a vault owner or admin to grant it via vault.grant({ importCapability: { plaintext: ['${opts.format ?? '<format>'}'] } }).`\n        : `Import capability denied — keyring \"${opts.userId}\" is not granted encrypted-bundle import capability. Ask a vault owner or admin to grant it via vault.grant({ importCapability: { bundle: true } }).`)\n    super('IMPORT_CAPABILITY', msg)\n    this.name = 'ImportCapabilityError'\n    this.tier = opts.tier\n    this.userId = opts.userId\n    if (opts.format !== undefined) this.format = opts.format\n  }\n}\n\n/**\n * Thrown when a grant would give the grantee a permission the grantor\n * does not themselves hold — the \"admin cannot grant what admin cannot\n * do\" rule from the admin-delegation work.\n *\n * Distinct from `PermissionDeniedError` so callers can tell the two\n * cases apart in logs and tests:\n *\n *   - `PermissionDeniedError` — \"you are not allowed to perform this\n *     operation at all\" (wrong role).\n *   - `PrivilegeEscalationError` — \"you are allowed to grant, but not\n *     with these specific permissions\" (widening attempt).\n *\n * Under the admin model the grantee of an admin-grants-admin call\n * inherits the caller's entire DEK set by construction, so this error\n * is structurally unreachable in typical flows. The check and error\n * class exist so that future per-collection admin scoping cannot\n * accidentally bypass the subset rule — the guard is already wired in.\n *\n * `offendingCollection` carries the first collection name that failed\n * the subset check, to make the violation actionable in error output.\n */\n/**\n * Thrown when a caller invokes an API that requires an optional\n * store capability the active store does not implement.\n *\n * Today the only call site is `Noydb.listAccessibleVaults()`,\n * which depends on the optional `NoydbStore.listVaults()`\n * method. The error message names the missing method and the calling\n * API so consumers know exactly which combination is unsupported,\n * and the `capability` field is machine-readable so library code can\n * pattern-match in catch blocks (e.g. fall back to a candidate-list\n * shape).\n *\n * The class lives in `errors.ts` rather than as a generic\n * `ValidationError` because the diagnostic shape is different: a\n * `ValidationError` says \"the inputs you passed are wrong\"; this\n * error says \"the inputs are fine, but the store you wired up\n * doesn't support what you're asking for.\" Different fix, different\n * documentation.\n */\nexport class StoreCapabilityError extends NoydbError {\n  /** The store method/capability that was missing. */\n  readonly capability: string\n\n  constructor(capability: string, callerApi: string, storeName?: string) {\n    super(\n      'STORE_CAPABILITY',\n      `${callerApi} requires the optional store capability \"${capability}\" ` +\n        `but the active store${storeName ? ` (${storeName})` : ''} does not implement it. ` +\n        `Use a store that supports \"${capability}\" (store-memory, store-file) or pass an explicit ` +\n        `vault list to bypass enumeration.`,\n    )\n    this.name = 'StoreCapabilityError'\n    this.capability = capability\n  }\n}\n\nexport class PrivilegeEscalationError extends NoydbError {\n  readonly offendingCollection: string\n\n  constructor(offendingCollection: string, message?: string) {\n    super(\n      'PRIVILEGE_ESCALATION',\n      message ??\n        `Privilege escalation: grantor has no DEK for collection \"${offendingCollection}\" and cannot grant access to it.`,\n    )\n    this.name = 'PrivilegeEscalationError'\n    this.offendingCollection = offendingCollection\n  }\n}\n\n/**\n * Thrown by `Collection.put` / `.delete` when the target record's\n * envelope `_ts` falls within a closed accounting period.\n *\n * Distinct from `ReadOnlyError` (keyring-level), `ReadOnlyAtInstantError`\n * (historical view), and `ReadOnlyFrameError` (shadow vault): this\n * error is about the STORED RECORD being sealed by an operator call\n * to `vault.closePeriod()`, independent of caller permissions or\n * view type. The `periodName` and `endDate` fields name the sealing\n * period so audit UIs can surface a \"this record is locked in\n * FY2026-Q1 (closed 2026-03-31)\" message without parsing the error\n * string.\n *\n * To apply a correction after close, book a compensating entry in a\n * new period rather than unlocking the old one. Re-opening a closed\n * period is deliberately unsupported.\n */\nexport class PeriodClosedError extends NoydbError {\n  readonly periodName: string\n  readonly endDate: string\n  readonly recordTs: string\n\n  constructor(periodName: string, endDate: string, recordTs: string) {\n    super(\n      'PERIOD_CLOSED',\n      `Cannot modify record (last written ${recordTs}) — sealed by closed period ` +\n        `\"${periodName}\" (endDate: ${endDate}). Post a compensating entry in a ` +\n        `new period instead.`,\n    )\n    this.name = 'PeriodClosedError'\n    this.periodName = periodName\n    this.endDate = endDate\n    this.recordTs = recordTs\n  }\n}\n\n/**\n * Thrown when a `put()` or `delete()` is rejected by a guard's `check`\n * function. The `reason` is the message the guard supplied — typically a\n * short business description (e.g. \"invoice is issued\"). The full\n * collection + id are surfaced so audit UIs can link back to the record.\n */\nexport class RecordLockedError extends NoydbError {\n  readonly collection: string\n  readonly id: string\n  readonly reason: string\n\n  constructor(collection: string, id: string, reason: string) {\n    super(\n      'RECORD_LOCKED',\n      `Cannot modify ${collection}/${id} — locked by guard: ${reason}. ` +\n        `Use withTransactions({ amendment: true, reason }) with admin/owner role to override.`,\n    )\n    this.name = 'RecordLockedError'\n    this.collection = collection\n    this.id = id\n    this.reason = reason\n  }\n}\n\n/**\n * Thrown when a `put()` changes one or more fields that are frozen by a\n * `frozenFields` guard. The `fields` list contains the specific paths\n * that were detected as changed.\n */\nexport class FieldFrozenError extends NoydbError {\n  readonly collection: string\n  readonly id: string\n  readonly fields: readonly string[]\n\n  constructor(collection: string, id: string, fields: readonly string[]) {\n    super(\n      'FIELD_FROZEN',\n      `Cannot change frozen field(s) on ${collection}/${id}: ${fields.join(', ')}. ` +\n        `Use withTransactions({ amendment: true, reason }) with admin/owner role to override.`,\n    )\n    this.name = 'FieldFrozenError'\n    this.collection = collection\n    this.id = id\n    this.fields = fields\n  }\n}\n\n/**\n * Thrown by an amendment invariant when the proposed change-set violates\n * the declared business rule (e.g. disbursement total not preserved).\n * Triggers a full transaction rollback via the existing revert pass.\n */\nexport class InvariantError extends NoydbError {\n  constructor(message: string) {\n    super('INVARIANT_VIOLATED', message)\n    this.name = 'InvariantError'\n  }\n}\n\n/**\n * Thrown at `withTransactions({ amendment: true })` open if the caller's\n * role is not in the guard's allowed amendment roles. Fail-fast: thrown\n * before any writes are attempted.\n */\nexport class AmendmentForbiddenError extends NoydbError {\n  readonly userId: string\n  readonly role: string\n\n  constructor(userId: string, role: string) {\n    super(\n      'AMENDMENT_FORBIDDEN',\n      `User \"${userId}\" with role \"${role}\" cannot open an amendment transaction. ` +\n        `Amendments require admin or owner role.`,\n    )\n    this.name = 'AmendmentForbiddenError'\n    this.userId = userId\n    this.role = role\n  }\n}\n\n/**\n * Thrown by `listUsersWithEnvelopes` when the vault's user directory\n * has been disabled (via `db.setDirectoryEnabled(vault, false)`) and\n * the caller's role is neither `owner` nor `admin`. Owner/admin can\n * still enumerate users — the toggle is a UX privacy switch, not a\n * security boundary.\n *\n * Honest caveat: this is a UX flag, not a privacy guarantee. The\n * envelope ciphertext is still in the store, the keyring file is\n * still listed at `_keyring/*`, and anyone with direct store read\n * access can count keyrings without going through the hub. See\n * `docs/subsystems/user-envelope.md` → \"Directory visibility\".\n */\nexport class DirectoryDisabledError extends NoydbError {\n  readonly vault: string\n\n  constructor(vault: string) {\n    super(\n      'DIRECTORY_DISABLED',\n      `Vault \"${vault}\" has its user directory disabled. ` +\n        `Only owners and admins can call listUsersWithEnvelopes() here. ` +\n        `Use db.setDirectoryEnabled(vault, true) to re-enable.`,\n    )\n    this.name = 'DirectoryDisabledError'\n    this.vault = vault\n  }\n}\n\n// ─── Hierarchical Access Errors ─────────────────────\n\n/**\n * Thrown when a user tries to act at a tier they are not cleared for.\n *\n * This is the umbrella error for tier write refusals:\n *   - `put({ tier: N })` when the user's keyring lacks tier-N DEK.\n *   - `elevate(id, N)` when the caller cannot reach tier N.\n *\n * Distinct from `TierAccessDeniedError` which covers *read* refusals on\n * the invisibility/ghost path.\n */\nexport class TierNotGrantedError extends NoydbError {\n  readonly tier: number\n  readonly collection: string\n\n  constructor(collection: string, tier: number) {\n    super(\n      'TIER_NOT_GRANTED',\n      `User has no DEK for tier ${tier} in collection \"${collection}\"`,\n    )\n    this.name = 'TierNotGrantedError'\n    this.collection = collection\n    this.tier = tier\n  }\n}\n\n/**\n * Thrown when an elevated-handle operation runs after the elevation's\n * TTL expired. Reads continue at the original tier; only writes\n * through the scoped handle flip to throwing once expired.\n */\nexport class ElevationExpiredError extends NoydbError {\n  readonly tier: number\n  readonly expiresAt: number\n\n  constructor(opts: { tier: number; expiresAt: number }) {\n    super(\n      'ELEVATION_EXPIRED',\n      `Elevation to tier ${opts.tier} expired at ${new Date(opts.expiresAt).toISOString()}`,\n    )\n    this.name = 'ElevationExpiredError'\n    this.tier = opts.tier\n    this.expiresAt = opts.expiresAt\n  }\n}\n\n/**\n * Thrown by `vault.elevate(...)` when an elevation is already active\n * on the vault. Adopters must `release()` the existing handle before\n * starting a new elevation.\n */\nexport class AlreadyElevatedError extends NoydbError {\n  readonly activeTier: number\n\n  constructor(activeTier: number) {\n    super(\n      'ALREADY_ELEVATED',\n      `Vault is already elevated to tier ${activeTier}; release the existing handle first`,\n    )\n    this.name = 'AlreadyElevatedError'\n    this.activeTier = activeTier\n  }\n}\n\n/**\n * Thrown when `demote()` is called by someone who is not the original\n * elevator and not an owner.\n */\nexport class TierDemoteDeniedError extends NoydbError {\n  constructor(id: string, tier: number) {\n    super(\n      'TIER_DEMOTE_DENIED',\n      `Only the original elevator or an owner can demote record \"${id}\" from tier ${tier}`,\n    )\n    this.name = 'TierDemoteDeniedError'\n  }\n}\n\n/**\n * Thrown when `db.delegate()` is called against a user that has no\n * keyring in the target vault — the delegation token cannot be\n * constructed without the target user's KEK wrap.\n */\nexport class DelegationTargetMissingError extends NoydbError {\n  readonly toUser: string\n\n  constructor(toUser: string) {\n    super(\n      'DELEGATION_TARGET_MISSING',\n      `Delegation target user \"${toUser}\" has no keyring in this vault`,\n    )\n    this.name = 'DelegationTargetMissingError'\n    this.toUser = toUser\n  }\n}\n\n// ─── Sync Errors ───────────────────────────────────────────────────────\n\n/**\n * Thrown when a `put()` detects an optimistic concurrency conflict.\n *\n * NOYDB uses version numbers (`_v`) for optimistic locking. If a `put()`\n * is called with `expectedVersion: N` but the stored record is at version\n * `M ≠ N`, the write is rejected and the caller must re-read, re-apply their\n * change, and retry. The `version` field carries the actual stored version\n * so callers can decide whether to retry or surface the conflict to the user.\n */\nexport class ConflictError extends NoydbError {\n  /** The actual stored version at the time of conflict. */\n  readonly version: number\n\n  constructor(version: number, message = 'Version conflict') {\n    super('CONFLICT', message)\n    this.name = 'ConflictError'\n    this.version = version\n  }\n}\n\n/**\n * Thrown by `LedgerStore.append()` after exhausting its CAS retry\n * budget under multi-writer contention. Two browser tabs, a\n * web app + an offline mobile peer, or a server worker pool all\n * producing ledger entries against the same vault can race on the\n * \"read head, write head+1\" cycle; the optimistic-CAS retry loop\n * resolves the race for `casAtomic: true` stores, but pathological\n * contention (or a buggy peer) can still exhaust the budget. When\n * that happens, the chain is intact — the failed writer simply\n * couldn't claim a slot. Caller's choice whether to retry, queue,\n * or surface the failure to the user.\n */\nexport class LedgerContentionError extends NoydbError {\n  readonly attempts: number\n\n  constructor(attempts: number) {\n    super(\n      'LEDGER_CONTENTION',\n      `LedgerStore.append: failed to claim a chain slot after ${attempts} optimistic-CAS retries`,\n    )\n    this.name = 'LedgerContentionError'\n    this.attempts = attempts\n  }\n}\n\n/**\n * Thrown when a bundle push is rejected because the remote has been updated\n * since the local bundle was last pulled.\n *\n * Unlike `ConflictError` (per-record), this is a whole-bundle conflict —\n * the remote's bundle handle has changed. The caller must pull the new\n * bundle, merge, and re-push. `remoteVersion` is the handle of the newer\n * remote bundle for use in diagnostics.\n */\nexport class BundleVersionConflictError extends NoydbError {\n  /** The bundle handle of the newer remote version that rejected the push. */\n  readonly remoteVersion: string\n\n  constructor(remoteVersion: string, message = 'Bundle version conflict — remote has been updated') {\n    super('BUNDLE_VERSION_CONFLICT', message)\n    this.name = 'BundleVersionConflictError'\n    this.remoteVersion = remoteVersion\n  }\n}\n\n/**\n * Thrown when a sync operation (push or pull) fails due to a network error.\n *\n * NOYDB's offline-first design means network errors are expected during sync.\n * Callers should catch `NetworkError`, surface connectivity status in the UI,\n * and rely on the `SyncScheduler` to retry when connectivity is restored.\n */\nexport class NetworkError extends NoydbError {\n  constructor(message = 'Network error') {\n    super('NETWORK_ERROR', message)\n    this.name = 'NetworkError'\n  }\n}\n\n// ─── Data Errors ───────────────────────────────────────────────────────\n\n/**\n * Thrown when `collection.get(id)` is called with an ID that does not exist.\n *\n * NOYDB collections are memory-first, so this error is synchronous and cheap —\n * it does not make a network round-trip. Callers that expect the record to be\n * absent should use `collection.getOrNull(id)` instead.\n */\nexport class NotFoundError extends NoydbError {\n  constructor(message = 'Record not found') {\n    super('NOT_FOUND', message)\n    this.name = 'NotFoundError'\n  }\n}\n\n/**\n * Thrown when application-level validation fails before encryption.\n *\n * Distinct from `SchemaValidationError` (Standard Schema v1 validator)\n * and `MissingTranslationError` (i18nText). `ValidationError` is the\n * general-purpose validation base — use it for custom guards in `put()`\n * hooks or store middleware.\n */\nexport class ValidationError extends NoydbError {\n  constructor(message = 'Validation error') {\n    super('VALIDATION_ERROR', message)\n    this.name = 'ValidationError'\n  }\n}\n\n/**\n * Thrown when a Standard Schema v1 validator rejects a record on\n * `put()` (input validation) or on read (output validation). Carries\n * the raw issue list so callers can render field-level errors.\n *\n * `direction` distinguishes the two cases:\n *   - `'input'`: the user passed bad data into `put()`. This is a\n *     normal error case that application code should handle — typically\n *     by showing validation messages in the UI.\n *   - `'output'`: stored data does not match the current schema. This\n *     indicates a schema drift (the schema was changed without\n *     migrating the existing records) and should be treated as a bug\n *     — the application should not swallow it silently.\n *\n * The `issues` type is deliberately `readonly unknown[]` on this class\n * so that `errors.ts` doesn't need to import from `schema.ts` (and\n * create a dependency cycle). Callers who know they're holding a\n * `SchemaValidationError` can cast to the more precise\n * `readonly StandardSchemaV1Issue[]` from `schema.ts`.\n */\nexport class SchemaValidationError extends NoydbError {\n  readonly issues: readonly unknown[]\n  readonly direction: 'input' | 'output'\n\n  constructor(\n    message: string,\n    issues: readonly unknown[],\n    direction: 'input' | 'output',\n  ) {\n    super('SCHEMA_VALIDATION_FAILED', message)\n    this.name = 'SchemaValidationError'\n    this.issues = issues\n    this.direction = direction\n  }\n}\n\n/** Base for schema-evolution strategy rejections. */\nexport class SchemaUpdateError extends NoydbError {\n  constructor(code: string, message: string) {\n    super(code, message)\n    this.name = 'SchemaUpdateError'\n  }\n}\n\n/** A non-additive schema change was rejected by the `additiveOnly()` strategy. */\nexport class NonAdditiveSchemaChangeError extends SchemaUpdateError {\n  constructor(message: string) {\n    super('NON_ADDITIVE_SCHEMA_CHANGE', message)\n    this.name = 'NonAdditiveSchemaChangeError'\n  }\n}\n\n/** A schema change was rejected by the `lockSchema()` strategy. */\nexport class SchemaLockedError extends SchemaUpdateError {\n  constructor(message: string) {\n    super('SCHEMA_LOCKED', message)\n    this.name = 'SchemaLockedError'\n  }\n}\n\n/** Write attempted while a schema cutover fence is up (draining/migrating, or this collection has a pending cutover). */\nexport class SchemaFenceError extends SchemaUpdateError {\n  constructor(message: string) {\n    super('SCHEMA_FENCE', message)\n    this.name = 'SchemaFenceError'\n  }\n}\n\n/** Write attempted by a client whose generation snapshot is behind the live fence — reload required. */\nexport class MigrationRequiredError extends SchemaUpdateError {\n  constructor(message: string) {\n    super('MIGRATION_REQUIRED', message)\n    this.name = 'MigrationRequiredError'\n  }\n}\n\n/** A coordinated cutover timed out waiting for active clients to quiesce. */\nexport class QuiesceTimeoutError extends SchemaUpdateError {\n  constructor(message: string) {\n    super('QUIESCE_TIMEOUT', message)\n    this.name = 'QuiesceTimeoutError'\n  }\n}\n\n// ─── Query DSL Errors ─────────────────────────────────────────────────\n\n/**\n * Thrown when `.groupBy().aggregate()` produces more than the hard\n * cardinality cap (default 100_000 groups)..\n *\n * The cap exists because `.groupBy()` materializes one bucket per\n * distinct key value in memory, and runaway cardinality — a groupBy\n * on a high-uniqueness field like `id` or `createdAt` — is almost\n * always a query mistake rather than legitimate use. A hard error is\n * better than silent OOM: the consumer sees an actionable message\n * naming the field and the observed cardinality, with guidance to\n * either narrow the query with `.where()` or accept the ceiling\n * override.\n *\n * A separate one-shot warning fires at 10% of the cap (10_000\n * groups) so consumers get a heads-up before the hard error — same\n * pattern as `JoinTooLargeError` and the `.join()` row ceiling.\n *\n * **Not overridable in.** The 100k cap is a fixed constant so\n * the failure mode is consistent across the codebase; a\n * `{ maxGroups }` override can be added later without a break if a\n * real consumer asks.\n */\nexport class GroupCardinalityError extends NoydbError {\n  /** The field being grouped on. */\n  readonly field: string\n  /** Observed number of distinct groups at the moment the cap tripped. */\n  readonly cardinality: number\n  /** The cap that was exceeded. */\n  readonly maxGroups: number\n\n  constructor(field: string, cardinality: number, maxGroups: number) {\n    super(\n      'GROUP_CARDINALITY',\n      `.groupBy(\"${field}\") produced ${cardinality} distinct groups, ` +\n        `exceeding the ${maxGroups}-group ceiling. This is almost always a ` +\n        `query mistake — grouping on a high-uniqueness field like \"id\" or ` +\n        `\"createdAt\" produces one bucket per record. Narrow the query with ` +\n        `.where() before grouping, or group on a lower-cardinality field ` +\n        `(status, category, clientId). If you genuinely need high-cardinality ` +\n        `grouping, file an issue with your use case.`,\n    )\n    this.name = 'GroupCardinalityError'\n    this.field = field\n    this.cardinality = cardinality\n    this.maxGroups = maxGroups\n  }\n}\n\n/**\n * Thrown in lazy mode when a `.query()` / `.where()` / `.orderBy()` clause\n * references a field that does not have a declared index.\n *\n * Lazy-mode queries only work when every touched field is indexed.\n * This is deliberate — silent scan-fallback would hide the performance\n * cliff that lazy-mode indexes exist to prevent.\n *\n * Payload:\n * - `collection` — name of the collection queried\n * - `touchedFields` — every field referenced by the query (filter + order)\n * - `missingFields` — subset of `touchedFields` that have no declared index\n */\nexport class IndexRequiredError extends NoydbError {\n  readonly collection: string\n  readonly touchedFields: readonly string[]\n  readonly missingFields: readonly string[]\n\n  constructor(args: { collection: string; touchedFields: readonly string[]; missingFields: readonly string[] }) {\n    super(\n      'INDEX_REQUIRED',\n      `Collection \"${args.collection}\": query references unindexed fields in lazy mode ` +\n      `(missing: ${args.missingFields.join(', ')}). ` +\n      `Declare an index on each field, or use collection.scan() for non-indexed iteration.`,\n    )\n    this.name = 'IndexRequiredError'\n    this.collection = args.collection\n    this.touchedFields = [...args.touchedFields]\n    this.missingFields = [...args.missingFields]\n  }\n}\n\n/**\n * Thrown (or surfaced via the `index:write-partial` event) when one or more\n * per-indexed-field side-car writes fail after the main record write has\n * already succeeded.\n *\n * Not thrown out of `.put()` / `.delete()` directly — those succeed when the\n * main record succeeds. Instead, `IndexWriteFailureError` instances are collected\n * into the session-scoped reconcile queue and emitted on the Collection\n * emitter as `index:write-partial`.\n *\n * Payload:\n * - `recordId` — the id of the main record whose side-car writes failed\n * - `field` — the indexed field whose side-car write failed\n * - `op` — `'put'` or `'delete'`, indicating which mutation was in flight\n * - `cause` — the underlying error from the store\n */\nexport class IndexWriteFailureError extends NoydbError {\n  readonly recordId: string\n  readonly field: string\n  readonly op: 'put' | 'delete'\n  override readonly cause: unknown\n\n  constructor(args: { recordId: string; field: string; op: 'put' | 'delete'; cause: unknown }) {\n    super(\n      'INDEX_WRITE_FAILURE',\n      `Index side-car ${args.op} failed for field \"${args.field}\" on record \"${args.recordId}\"`,\n    )\n    this.name = 'IndexWriteFailureError'\n    this.recordId = args.recordId\n    this.field = args.field\n    this.op = args.op\n    this.cause = args.cause\n  }\n}\n\n// ─── Bundle Format Errors ─────────────────────────────────\n\n/**\n * Thrown by `readNoydbBundle()` when the body bytes don't match\n * the integrity hash declared in the bundle header — i.e. someone\n * modified the bytes between write and read.\n *\n * Distinct from a generic `Error` (which would be thrown for\n * format violations like a missing magic prefix or malformed\n * header JSON) so consumers can pattern-match the corruption case\n * and handle it differently from a producer bug. A\n * `BundleIntegrityError` indicates \"the bytes you got are not\n * what was written\"; a plain `Error` from `parsePrefixAndHeader`\n * indicates \"what was written wasn't a valid bundle in the first\n * place.\"\n *\n * Also thrown when decompression fails after the integrity hash\n * passed — that's a producer bug (the wrong algorithm byte was\n * written) but it surfaces with the same error class because the\n * end result is \"the body cannot be turned back into a dump.\"\n */\nexport class BundleIntegrityError extends NoydbError {\n  constructor(message: string) {\n    super('BUNDLE_INTEGRITY', `.noydb bundle integrity check failed: ${message}`)\n    this.name = 'BundleIntegrityError'\n  }\n}\n\n/**\n * Thrown by `readNoydbBundle` when the bundle carries\n * sealed per-user passphrases but no supplied `SealingKeyProvider`\n * has a `.id` (= `pid`) matching the sealed entry's `pid`.\n *\n * Carries the failing pid + the user id so the recipient can\n * surface an actionable prompt:\n *\n * ```\n * BundleSealMismatchError: bundle carries sealed passphrase for user \"alice\"\n *   under provider \"macos-keychain:com.acme.app/alice@acme.example\",\n *   but no registered provider matches that pid.\n * ```\n *\n * Three resolution paths the message names (per foundation §11.9.4):\n *\n * 1. Configure a provider matching the pid and retry import.\n * 2. Pass `attemptUnsealAcrossProviders: true` to try each\n *    registered provider regardless of pid.\n * 3. Inspect without unsealing — pass no `sealingProviders` to\n *    receive the sealed entries unmodified for offline analysis.\n */\nexport class BundleSealMismatchError extends NoydbError {\n  readonly userId: string\n  readonly pid: string\n  constructor(userId: string, pid: string) {\n    super(\n      'BUNDLE_SEAL_MISMATCH',\n      `bundle carries sealed passphrase for user \"${userId}\" under provider `\n      + `\"${pid}\", but no registered provider matches that pid.\\n\\n`\n      + 'Resolutions:\\n'\n      + '  1. Configure a provider matching the pid and retry import.\\n'\n      + '  2. Pass `attemptUnsealAcrossProviders: true` to try each registered\\n'\n      + '     provider regardless of pid (extra credential prompts may surface).\\n'\n      + '  3. Inspect the bundle without unsealing — pass no `sealingProviders`\\n'\n      + '     to receive the sealed entries unmodified for offline analysis.',\n    )\n    this.name = 'BundleSealMismatchError'\n    this.userId = userId\n    this.pid = pid\n  }\n}\n\n// ─── i18n / Dictionary Errors ──────────────────────────\n\n/**\n * Thrown when `vault.collection()` is called with a name that is\n * reserved for NOYDB internal use (any name starting with `_dict_`).\n *\n * Dictionary collections are accessed exclusively via\n * `vault.dictionary(name)` — attempting to open one as a regular\n * collection would bypass the dictionary invariants (ACL, rename\n * tracking, reserved-name policy).\n */\nexport class ReservedCollectionNameError extends NoydbError {\n  /** The rejected collection name. */\n  readonly collectionName: string\n\n  constructor(collectionName: string) {\n    super(\n      'RESERVED_COLLECTION_NAME',\n      `\"${collectionName}\" is a reserved collection name. ` +\n        `Use vault.dictionary(\"${collectionName.replace(/^_dict_/, '')}\") ` +\n        `to access dictionary collections.`,\n    )\n    this.name = 'ReservedCollectionNameError'\n    this.collectionName = collectionName\n  }\n}\n\n/**\n * Thrown by `DictionaryHandle.get()` and `DictionaryHandle.delete()` when\n * the requested key does not exist in the dictionary.\n *\n * Distinct from `NotFoundError` (which is for data records) so callers\n * can distinguish \"data record missing\" from \"dictionary key missing\"\n * without inspecting error messages.\n */\nexport class DictKeyMissingError extends NoydbError {\n  /** The dictionary name. */\n  readonly dictionaryName: string\n  /** The key that was not found. */\n  readonly key: string\n\n  constructor(dictionaryName: string, key: string) {\n    super(\n      'DICT_KEY_MISSING',\n      `Dictionary \"${dictionaryName}\" has no entry for key \"${key}\".`,\n    )\n    this.name = 'DictKeyMissingError'\n    this.dictionaryName = dictionaryName\n    this.key = key\n  }\n}\n\n/**\n * Thrown by `DictionaryHandle.delete()` in strict mode when the key to\n * be deleted is still referenced by one or more records.\n *\n * The caller must either rename the key first (the only sanctioned\n * mass-mutation path) or pass `{ mode: 'warn' }` to skip the check\n * (development only).\n */\nexport class DictKeyInUseError extends NoydbError {\n  /** The dictionary name. */\n  readonly dictionaryName: string\n  /** The key that is still referenced. */\n  readonly key: string\n  /** Name of the first collection found to reference this key. */\n  readonly usedBy: string\n  /** Number of records in `usedBy` that reference this key. */\n  readonly count: number\n\n  constructor(\n    dictionaryName: string,\n    key: string,\n    usedBy: string,\n    count: number,\n  ) {\n    super(\n      'DICT_KEY_IN_USE',\n      `Cannot delete key \"${key}\" from dictionary \"${dictionaryName}\": ` +\n        `${count} record(s) in \"${usedBy}\" still reference it. ` +\n        `Use dictionary.rename(\"${key}\", newKey) to rewrite references first.`,\n    )\n    this.name = 'DictKeyInUseError'\n    this.dictionaryName = dictionaryName\n    this.key = key\n    this.usedBy = usedBy\n    this.count = count\n  }\n}\n\n/**\n * Thrown by `Collection.put()` when an `i18nText` field is missing one\n * or more required translations.\n *\n * The `missing` array names each locale code that was absent from the\n * field value. The `field` property names the field so callers can\n * render a field-level error message without parsing the string.\n */\nexport class MissingTranslationError extends NoydbError {\n  /** The field name whose translation(s) are missing. */\n  readonly field: string\n  /** Locale codes that were required but absent. */\n  readonly missing: readonly string[]\n\n  constructor(field: string, missing: readonly string[], message?: string) {\n    super(\n      'MISSING_TRANSLATION',\n      message ??\n        `Field \"${field}\": missing required translation(s): ${missing.join(', ')}.`,\n    )\n    this.name = 'MissingTranslationError'\n    this.field = field\n    this.missing = missing\n  }\n}\n\n/**\n * Thrown when reading an `i18nText` field without specifying a locale —\n * either at the call site (`get(id, { locale })`) or on the vault\n * (`openVault(name, { locale })`).\n *\n * Also thrown when `resolveI18nText()` exhausts the fallback chain and\n * no translation is available for the requested locale.\n *\n * The `field` property names the field that triggered the error so the\n * caller can surface it in the UI.\n */\nexport class LocaleNotSpecifiedError extends NoydbError {\n  /** The field name that required a locale. */\n  readonly field: string\n\n  constructor(field: string, message?: string) {\n    super(\n      'LOCALE_NOT_SPECIFIED',\n      message ??\n        `Cannot read i18nText field \"${field}\" without a locale. ` +\n        `Pass { locale } to get()/list()/query() or set a default via ` +\n        `openVault(name, { locale }).`,\n    )\n    this.name = 'LocaleNotSpecifiedError'\n    this.field = field\n  }\n}\n\n// ─── Translator Errors ─────────────────────────────────────\n\n/**\n * Thrown when a collection has an `i18nText` field with\n * `autoTranslate: true` but no `plaintextTranslator` was configured\n * on `createNoydb()`.\n *\n * The error is raised at `put()` time (not at schema construction) so\n * the mis-configuration is surfaced by the first write rather than\n * silently at startup.\n */\nexport class TranslatorNotConfiguredError extends NoydbError {\n  /** The field that requested auto-translation. */\n  readonly field: string\n  /** The collection the put was targeting. */\n  readonly collection: string\n\n  constructor(field: string, collection: string) {\n    super(\n      'TRANSLATOR_NOT_CONFIGURED',\n      `Field \"${field}\" in collection \"${collection}\" has autoTranslate: true, ` +\n        `but no plaintextTranslator was configured on createNoydb(). ` +\n        `Either configure a plaintextTranslator or remove autoTranslate from the schema.`,\n    )\n    this.name = 'TranslatorNotConfiguredError'\n    this.field = field\n    this.collection = collection\n  }\n}\n\n// ─── Backup Errors ─────────────────────────────────────────\n\n/**\n * Thrown when `Vault.load()` finds that a backup's hash chain\n * doesn't verify, or that its embedded `ledgerHead.hash` doesn't\n * match the chain head reconstructed from the loaded entries.\n *\n * Distinct from `BackupCorruptedError` so callers can choose to\n * recover from one but not the other (e.g., a corrupted JSON file is\n * unrecoverable; a chain mismatch might mean the backup is from an\n * incompatible noy-db version).\n */\nexport class BackupLedgerError extends NoydbError {\n  /** First-broken-entry index, if known. */\n  readonly divergedAt?: number\n\n  constructor(message: string, divergedAt?: number) {\n    super('BACKUP_LEDGER', message)\n    this.name = 'BackupLedgerError'\n    if (divergedAt !== undefined) this.divergedAt = divergedAt\n  }\n}\n\n/**\n * Thrown when `Vault.load()` finds that the backup's data\n * collection content doesn't match the ledger's recorded\n * `payloadHash`es. This is the \"envelope was tampered with after\n * dump\" detection — the chain itself can be intact, but if any\n * encrypted record bytes were swapped, this check catches it.\n */\nexport class BackupCorruptedError extends NoydbError {\n  /** The (collection, id) pair whose envelope failed the hash check. */\n  readonly collection: string\n  readonly id: string\n\n  constructor(collection: string, id: string, message: string) {\n    super('BACKUP_CORRUPTED', message)\n    this.name = 'BackupCorruptedError'\n    this.collection = collection\n    this.id = id\n  }\n}\n\n/**\n * Thrown by partition-extraction primitives when the\n * transitive-closure walk fails — e.g. the FK graph is deeper than\n * `maxDepth`, signalling a runaway or unexpectedly cyclic graph.\n */\nexport class PartitionExtractionError extends NoydbError {\n  constructor(message: string) {\n    super('PARTITION_EXTRACTION', message)\n    this.name = 'PartitionExtractionError'\n  }\n}\n\n/**\n * Thrown by `adoptPartition` when the transfer seal can't be\n * opened — a wrong/short transfer key (AES-GCM auth-tag failure) or a\n * malformed sealed payload.\n */\nexport class TransferSealError extends NoydbError {\n  constructor(message: string) {\n    super('TRANSFER_SEAL', message)\n    this.name = 'TransferSealError'\n  }\n}\n\n/**\n * Thrown when an adoption-lifecycle precondition fails — re-adopting a\n * partition already consumed in this store, or owner-creation on a\n * vault that isn't in the adopted-unowned state.\n */\nexport class AdoptionStateError extends NoydbError {\n  constructor(message: string) {\n    super('ADOPTION_STATE', message)\n    this.name = 'AdoptionStateError'\n  }\n}\n\n// ─── Attestation Errors ────────────────────────────────────\n\n/** Document-attestation failures: undeclared field-schema, non-owner issue, missing field, signer failure. */\nexport class AttestationError extends NoydbError {\n  constructor(message: string) {\n    super('ATTESTATION', message)\n    this.name = 'AttestationError'\n  }\n}\n\n// ─── Session Errors ───────────────────────────────────────\n\n/**\n * Thrown by `resolveSession()` when the session token's `expiresAt`\n * timestamp is in the past. The session key is also removed from the\n * in-memory store when this is thrown, so retrying with the same sessionId\n * will produce `SessionNotFoundError`.\n *\n * Separate from `SessionNotFoundError` so callers can distinguish between\n * \"session is gone\" (key store cleared, tab reloaded) and \"session is\n * still in the store but has exceeded its lifetime\" (idle timeout, absolute\n * timeout, policy-driven expiry). The remediation differs: expired sessions\n * should prompt a fresh unlock; not-found sessions may indicate a bug or a\n * cross-tab scenario where the session was never established.\n */\nexport class SessionExpiredError extends NoydbError {\n  readonly sessionId: string\n\n  constructor(sessionId: string) {\n    super('SESSION_EXPIRED', `Session \"${sessionId}\" has expired. Re-unlock to continue.`)\n    this.name = 'SessionExpiredError'\n    this.sessionId = sessionId\n  }\n}\n\n/**\n * Thrown by `resolveSession()` when the session key cannot be found in\n * the module-level store. This happens when:\n *   - The session was explicitly revoked via `revokeSession()`.\n *   - The JS context was reloaded (tab navigation, page refresh, worker restart).\n *   - `Noydb.close()` was called (which calls `revokeAllSessions()`).\n *   - The sessionId is wrong or was generated by a different JS context.\n *\n * The session token (if the caller holds it) is permanently useless after\n * this error — the key is gone and cannot be recovered.\n */\nexport class SessionNotFoundError extends NoydbError {\n  readonly sessionId: string\n\n  constructor(sessionId: string) {\n    super('SESSION_NOT_FOUND', `Session key for \"${sessionId}\" not found. The session may have been revoked or the page reloaded.`)\n    this.name = 'SessionNotFoundError'\n    this.sessionId = sessionId\n  }\n}\n\n/**\n * Thrown when a session policy blocks an operation — for example,\n * `requireReAuthFor: ['export']` is set and the caller attempts to\n * call `exportStream()` without re-authenticating for this session.\n *\n * The `operation` field names the specific operation that was blocked\n * (e.g. `'export'`, `'grant'`, `'rotate'`) so the caller can surface\n * a targeted prompt (\"Please re-enter your passphrase to export data\").\n */\nexport class SessionPolicyError extends NoydbError {\n  readonly operation: string\n\n  constructor(operation: string, message?: string) {\n    super(\n      'SESSION_POLICY',\n      message ?? `Operation \"${operation}\" requires re-authentication per the active session policy.`,\n    )\n    this.name = 'SessionPolicyError'\n    this.operation = operation\n  }\n}\n\n// ─── Query / Join Errors ────────────────────────────────────\n\n/**\n * Thrown when a `.join()` would exceed its configured row ceiling on\n * either side. The ceiling defaults to 50,000 per side and can be\n * overridden via the `{ maxRows }` option on `.join()`.\n *\n * Carries both row counts so the error message can show which side\n * tripped the limit (e.g. \"left had 60,000 rows, right had 1,200,\n * max was 50,000\"). The `side` field is machine-readable so test\n * code and devtools can match on it without regex-parsing the\n * message.\n *\n * The row ceiling exists because joins are bounded in-memory\n * operations over materialized record sets. Consumers whose\n * collections genuinely exceed the ceiling should track \n * (streaming joins over `scan()`) or filter the left side further\n * with `where()` / `limit()` before joining.\n */\nexport class JoinTooLargeError extends NoydbError {\n  readonly leftRows: number\n  readonly rightRows: number\n  readonly maxRows: number\n  readonly side: 'left' | 'right'\n\n  constructor(opts: {\n    leftRows: number\n    rightRows: number\n    maxRows: number\n    side: 'left' | 'right'\n    message: string\n  }) {\n    super('JOIN_TOO_LARGE', opts.message)\n    this.name = 'JoinTooLargeError'\n    this.leftRows = opts.leftRows\n    this.rightRows = opts.rightRows\n    this.maxRows = opts.maxRows\n    this.side = opts.side\n  }\n}\n\n/**\n * Thrown by `.join()` in strict `ref()` mode when a left-side record\n * points at a right-side id that does not exist in the target\n * collection.\n *\n * Distinct from `RefIntegrityError` so test code can pattern-match\n * on the *read-time* dangling case without catching *write-time*\n * integrity violations. Both indicate \"ref points at nothing\" but\n * happen at different lifecycle phases and deserve different\n * remediation in documentation: a RefIntegrityError on `put()`\n * means the input is invalid; a DanglingReferenceError on `.join()`\n * means stored data has drifted and `vault.checkIntegrity()`\n * is the right tool to find the full set of orphans.\n */\nexport class DanglingReferenceError extends NoydbError {\n  readonly field: string\n  readonly target: string\n  readonly refId: string\n\n  constructor(opts: {\n    field: string\n    target: string\n    refId: string\n    message: string\n  }) {\n    super('DANGLING_REFERENCE', opts.message)\n    this.name = 'DanglingReferenceError'\n    this.field = opts.field\n    this.target = opts.target\n    this.refId = opts.refId\n  }\n}\n\n/**\n * Thrown by {@link sanitizeFilename} when an input filename cannot be\n * made safe — NUL byte, empty after normalization, missing\n * `opaqueId` for the opaque profile, `..` segment, or a `maxBytes`\n * cap too small to hold a single code point.\n */\nexport class FilenameSanitizationError extends NoydbError {\n  constructor(message: string) {\n    super('FILENAME_SANITIZATION', message)\n    this.name = 'FilenameSanitizationError'\n  }\n}\n\n/**\n * Thrown when a write target resolves OUTSIDE the requested\n * directory after sanitization — the canonical Zip-Slip class. The\n * sanitizer's job is to strip path-traversal segments; this error\n * is the defense-in-depth fallback at the FS write site.\n */\nexport class PathEscapeError extends NoydbError {\n  readonly attempted: string\n  readonly targetDir: string\n\n  constructor(opts: { attempted: string; targetDir: string }) {\n    super(\n      'PATH_ESCAPE',\n      `Sanitized filename \"${opts.attempted}\" resolves outside target dir \"${opts.targetDir}\"`,\n    )\n    this.name = 'PathEscapeError'\n    this.attempted = opts.attempted\n    this.targetDir = opts.targetDir\n  }\n}\n\n// ─── Derivation Errors ──────────────────────────────\n\n/**\n * Thrown at vault open if the derivation graph contains a cycle.\n * `path` is the offending chain (e.g. `['a', 'b', 'c', 'a']`).\n */\nexport class DerivationCycleError extends NoydbError {\n  readonly path: readonly string[]\n\n  constructor(path: readonly string[]) {\n    super(\n      'DERIVATION_CYCLE',\n      `Derivation graph contains a cycle: ${path.join(' → ')}. ` +\n        `Refusing to open vault — break the cycle before retrying.`,\n    )\n    this.name = 'DerivationCycleError'\n    this.path = path\n  }\n}\n\n/**\n * Thrown when a cascade of source → output → source → … exceeds the\n * configured `maxDepth` (default 5).\n */\nexport class DerivationDepthError extends NoydbError {\n  readonly limit: number\n  readonly attempted: number\n\n  constructor(limit: number, attempted: number) {\n    super(\n      'DERIVATION_DEPTH',\n      `Derivation cascade exceeded max depth ${limit} (attempted ${attempted}). ` +\n        `Pass lifecycle: { maxDepth: N } to raise the limit if intentional.`,\n    )\n    this.name = 'DerivationDepthError'\n    this.limit = limit\n    this.attempted = attempted\n  }\n}\n\n/**\n * Thrown at registration if a `withDerivation` strategy references an\n * output `collection` that isn't otherwise declared (no schema, no use\n * elsewhere). Surfacing this early catches typos in collection names.\n */\nexport class DerivationOutputUnknownError extends NoydbError {\n  readonly collection: string\n\n  constructor(collection: string) {\n    super(\n      'DERIVATION_OUTPUT_UNKNOWN',\n      `Derivation output collection \"${collection}\" is not declared on the vault. ` +\n        `Register the collection (e.g. via schema) before registering a derivation that writes to it.`,\n    )\n    this.name = 'DerivationOutputUnknownError'\n    this.collection = collection\n  }\n}\n\n/**\n * Thrown when the user's `derive` function returns a value that doesn't\n * match the declared output spec (e.g. wrong shape, wrong key set).\n */\nexport class DerivationOutputShapeError extends NoydbError {\n  readonly outputKey: string\n\n  constructor(outputKey: string, detail: string) {\n    super(\n      'DERIVATION_OUTPUT_SHAPE',\n      `Derivation output \"${outputKey}\" has invalid shape: ${detail}.`,\n    )\n    this.name = 'DerivationOutputShapeError'\n    this.outputKey = outputKey\n  }\n}\n\n/**\n * Thrown by array-shape derivations when the `derive` function\n * returns more rows than the output's `maxFanout` cap. The cap exists\n * to keep dispatch cost bounded — without it a single source-row\n * update could fan out to thousands of derived rows, dominating the\n * write path.\n *\n * Defaults to `maxFanout: 64`. Raise on the output spec for\n * carry-forward expansion cases (e.g. monthly rows across multi-year\n * contracts).\n */\nexport class DerivationCapExceededError extends NoydbError {\n  readonly outputKey: string\n  readonly returned: number\n  readonly maxFanout: number\n\n  constructor(outputKey: string, returned: number, maxFanout: number) {\n    super(\n      'DERIVATION_CAP_EXCEEDED',\n      `Derivation array output \"${outputKey}\" returned ${returned} rows, exceeding `\n      + `maxFanout=${maxFanout}. Raise \\`maxFanout\\` on the OutputSpec if this fanout `\n      + 'is intended (the cap exists to keep dispatch cost bounded).',\n    )\n    this.name = 'DerivationCapExceededError'\n    this.outputKey = outputKey\n    this.returned = returned\n    this.maxFanout = maxFanout\n  }\n}\n\n/**\n * Thrown at vault open if the materialized-view graph contains a\n * cycle. `path` is the offending chain (e.g. `['a-mv', 'b-mv', 'a-mv']`).\n * Detected by the same shared DFS that catches `DerivationCycleError`;\n * surfaces with a distinct error type so consumers can disambiguate.\n */\nexport class MaterializedViewCycleError extends NoydbError {\n  readonly path: readonly string[]\n\n  constructor(path: readonly string[]) {\n    super(\n      'MATERIALIZED_VIEW_CYCLE',\n      `Materialized-view graph contains a cycle: ${path.join(' → ')}. ` +\n        `Refusing to open vault — break the cycle before retrying.`,\n    )\n    this.name = 'MaterializedViewCycleError'\n    this.path = path\n  }\n}\n\n/**\n * Thrown at MV registration if the query references a source\n * collection that isn't declared on the vault. Surfacing this early\n * catches typos in collection names.\n */\nexport class MaterializedViewSourceUnknownError extends NoydbError {\n  readonly mvName: string\n  readonly collection: string\n\n  constructor(mvName: string, collection: string) {\n    super(\n      'MATERIALIZED_VIEW_SOURCE_UNKNOWN',\n      `Materialized view \"${mvName}\" references unknown source collection \"${collection}\". ` +\n        `Declare the collection (e.g. via schema or by writing to it once) before registering the MV.`,\n    )\n    this.name = 'MaterializedViewSourceUnknownError'\n    this.mvName = mvName\n    this.collection = collection\n  }\n}\n\n/**\n * Thrown by the MV executor when a refresh produces more rows than\n * the configured ceiling. Default ceiling is 100k rows; override\n * per-MV via `maxRows`. Mirrors `JoinTooLargeError` /\n * `GroupCardinalityError` from the query DSL — the explosion is\n * detected BEFORE writes hit the store, so the source-write\n * transaction can roll back cleanly via strict-mode.\n */\nexport class MaterializedViewTooLargeError extends NoydbError {\n  readonly mvName: string\n  readonly expected: number\n  readonly limit: number\n\n  constructor(mvName: string, expected: number, limit: number) {\n    super(\n      'MATERIALIZED_VIEW_TOO_LARGE',\n      `Materialized view \"${mvName}\" would emit ${expected} rows, exceeding the configured limit of ${limit}. ` +\n        `Override via { maxRows: N } on the MV strategy if intentional, or tighten the query's filter/groupBy.`,\n    )\n    this.name = 'MaterializedViewTooLargeError'\n    this.mvName = mvName\n    this.expected = expected\n    this.limit = limit\n  }\n}\n\n/**\n * Thrown by `withMaterializedView()` at registration time when the\n * strategy is structurally malformed. Distinct from\n * `MaterializedViewSourceUnknownError` (the source list is well-formed\n * but names a collection the vault doesn't know) and\n * `MaterializedViewCycleError` (the source graph has a cycle): this\n * error fires before either check, at the moment the spec is being\n * normalized.\n *\n * Today the trigger cases are all about the `query` / `unionSources`\n * dichotomy:\n *   - both `query` and `unionSources` were set (mutually exclusive),\n *   - neither `query` nor `unionSources` was set,\n *   - `unionSources` has fewer than 2 arms,\n *   - two arms in `unionSources` reference the same `collection`.\n *\n * The error message is prefixed with `[noy-db] withMaterializedView:`\n * so it's grep-friendly in logs and looks consistent with the existing\n * `ValidationError` messages from the same factory.\n */\nexport class MaterializedViewConfigError extends NoydbError {\n  constructor(message: string) {\n    super(\n      'MATERIALIZED_VIEW_CONFIG',\n      `[noy-db] withMaterializedView: ${message}`,\n    )\n    this.name = 'MaterializedViewConfigError'\n  }\n}\n\n/**\n * Thrown at vault open when a `withOverlayedView` declaration uses\n * another virtual-overlay name as its `base`. Multi-overlay stacking\n * is a v2 non-goal — the shallow expansion in\n * `QueryDependencyAnalyzer` would truncate at the inner overlay\n * name, leaving downstream MVs silently stale.\n */\nexport class OverlayBaseIsVirtualError extends NoydbError {\n  readonly overlayName: string\n  readonly base: string\n\n  constructor(overlayName: string, base: string) {\n    super(\n      'OVERLAY_BASE_IS_VIRTUAL',\n      `withOverlayedView \"${overlayName}\": base \"${base}\" is another overlay's virtual name. ` +\n        `Multi-overlay stacking is a v3 feature; base must reference a concrete collection (a real source or an MV output).`,\n    )\n    this.name = 'OverlayBaseIsVirtualError'\n    this.overlayName = overlayName\n    this.base = base\n  }\n}\n\n/**\n * Thrown at vault open when a `withOverlayedView`'s `overlay`\n * references an unknown collection or an MV-owned collection. The\n * overlay collection is user-writable; MV-owned collections aren't.\n */\nexport class OverlayCollectionUnavailableError extends NoydbError {\n  readonly overlayName: string\n  readonly overlay: string\n\n  constructor(overlayName: string, overlay: string) {\n    super(\n      'OVERLAY_COLLECTION_UNAVAILABLE',\n      `withOverlayedView \"${overlayName}\": overlay collection \"${overlay}\" is unavailable. ` +\n        `It must be a real vault-known collection that is NOT itself an MV output collection.`,\n    )\n    this.name = 'OverlayCollectionUnavailableError'\n    this.overlayName = overlayName\n    this.overlay = overlay\n  }\n}\n\n/**\n * Thrown at vault open when a `withOverlayedView`'s virtual `name`\n * collides with an MV output or a concrete source collection.\n */\nexport class OverlayNameCollisionError extends NoydbError {\n  readonly overlayName: string\n\n  constructor(overlayName: string) {\n    super(\n      'OVERLAY_NAME_COLLISION',\n      `withOverlayedView \"${overlayName}\": virtual name collides with an MV output or a concrete source collection. ` +\n        `Pick a unique name for the virtual collection.`,\n    )\n    this.name = 'OverlayNameCollisionError'\n    this.overlayName = overlayName\n  }\n}\n\n/**\n * Thrown by the virtual overlay's `put(id, record)` when the\n * consumer-supplied `id` doesn't match `rowKey(record)`. Catches\n * fat-finger separator typos that would otherwise silently produce\n * orphaned overlay rows. Direct writes to the underlying overlay\n * collection (bypass the virtual layer) skip this validation.\n */\nexport class OverlayIdMismatchError extends NoydbError {\n  readonly actual: string\n  readonly expected: string\n\n  constructor(actual: string, expected: string) {\n    super(\n      'OVERLAY_ID_MISMATCH',\n      `Overlay put(id, record): id \"${actual}\" does not match the base MV's rowKey(record) → \"${expected}\". ` +\n        `Pass the row directly via .put(record) to derive the id, or fix the id to match the base MV's rowKey output.`,\n    )\n    this.name = 'OverlayIdMismatchError'\n    this.actual = actual\n    this.expected = expected\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-GDTCGIPX.js → chunk-7TX7HN42.js}

@@ -1,7 +1,7 @@
 import {
   MaterializedViewCycleError,
   MaterializedViewSourceUnknownError
-} from "./chunk-YDLAFP36.js";
+} from "./chunk-6HJ2ZALB.js";
 
 // src/materialized-views/dependency-analyzer.ts
 function analyzeDependencies(query) {
@@ -293,4 +293,4 @@ export {
   MaterializedViewRegistry,
   wrapDbWithPredicates
 };
-//# sourceMappingURL=chunk-GDTCGIPX.js.map
+//# sourceMappingURL=chunk-7TX7HN42.js.map

package/dist/chunk-7TX7HN42.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/materialized-views/dependency-analyzer.ts","../src/materialized-views/query-hash.ts","../src/materialized-views/registry.ts"],"sourcesContent":["import type { Query, QueryPlan } from '../query/builder.js'\nimport type { JoinContext } from '../query/join.js'\nimport type { MaterializedViewStrategy } from './types.js'\n\n/**\n * Walks a `Query<T>` plan and returns the set of source collection\n * names that any source-write should trigger a refresh on.\n *\n * Handles:\n *   - root collection (the one the query was built from)\n *   - FK join targets (`.join(field, { as })`)\n *\n * Deferred:\n *   - `.crossJoin()` — v3 cross-join spec (separate primitive)\n *   - `.wherePredicate(name)` — v2 predicate primitive\n *   - Overlay-name expansion to {base, overlay}\n *\n * The set is materialized at MV registration time. The MV registry\n * uses it to (a) dispatch `onSourceWrite` only to MVs that actually\n * care, and (b) contribute edges to the shared cycle-detection graph.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function analyzeDependencies(query: Query<any>): Set<string> {\n  const deps = new Set<string>()\n  const plan = query._plan()\n  const ctx = query._joinContext()\n\n  // The root collection is always a dependency.\n  if (ctx?.leftCollection) {\n    deps.add(ctx.leftCollection)\n  }\n\n  // FK join targets contribute additional sources.\n  for (const leg of plan.joins) {\n    deps.add(leg.target)\n  }\n\n  // Sub-plans inside OR clauses can carry nested joins. Walk them.\n  // (Today only top-level `.join()` populates `plan.joins`, but the\n  // OR-group machinery permits sub-plans, so we recurse defensively.)\n  walkClausesForJoins(plan, deps, ctx)\n\n  return deps\n}\n\nfunction walkClausesForJoins(\n  plan: QueryPlan,\n  deps: Set<string>,\n  ctx: JoinContext | undefined,\n): void {\n  void ctx\n  // Today `plan.joins` carries all join legs at top level. Sub-plans\n  // inside OR groups don't currently support nested joins, so the loop\n  // below is a no-op safety net for future builder extensions.\n  for (const clause of plan.clauses) {\n    if (clause.type === 'group') {\n      // Group clauses don't (yet) carry their own joins; this is a\n      // forward-compat anchor for when OR-groups support nested\n      // sources.\n    }\n  }\n}\n\n/**\n * Convenience: produce a stable string summary of the query plan\n * suitable for `queryHash` derivation. Captures everything the\n * dependency analyzer reads + the where/orderBy/limit/offset\n * structure that affects materialized rows.\n *\n * `joinContext` is intentionally NOT included — the join-resolution\n * function references would defeat hash determinism. The set of join\n * TARGETS (collection names) IS included via the plan.joins legs.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function summarizeQueryPlan(query: Query<any>): string {\n  const plan = query._plan()\n  const ctx = query._joinContext()\n  return JSON.stringify({\n    root: ctx?.leftCollection ?? null,\n    clauses: plan.clauses,\n    orderBy: plan.orderBy,\n    limit: plan.limit ?? null,\n    offset: plan.offset,\n    joins: plan.joins.map(j => ({ field: j.field, as: j.as, target: j.target, mode: j.mode })),\n  })\n}\n\n/**\n * Canonical string description of a UNION MV's plan, used as input to\n * `computeQueryHash`.\n *\n * Asymmetry note:\n *   - Arm collection names are NOT sorted. Declaration order is\n *     semantically meaningful for the dedup-only UNION path —\n *     `materializeUnionResult` iterates `spec.unionSources` in\n *     declaration order and keeps the first-seen row per composite key\n *     (tie-break precedence). If we sorted arms here, a consumer who\n *     reordered `unionSources` to change precedence would compute the\n *     same `queryHash`, refresh would be a no-op, and stale MV rows\n *     would persist. Hashing in declaration order makes any reorder\n *     trigger a refresh.\n *   - `groupBy` fields ARE sorted. Multi-key groupBy buckets are\n *     commutative (`canonicalGroupKey` produces the same composite key\n *     regardless of field order in the input spec).\n *   - `aggregate` keys ARE sorted. Reducer-spec keys are independent\n *     of each other — order of declaration doesn't change output.\n *\n * Per-arm `map` functions are NOT fingerprinted; consumers must bump\n * the MV's `name` (or rely on application-level cache busting) when\n * `map` semantics change non-equivalently.\n */\nexport function summarizeUnionPlan<T extends Record<string, unknown>>(\n  spec: MaterializedViewStrategy<T>,\n): string {\n  const arms = (spec.unionSources ?? [])\n    .map(s => s.collection)\n    .join(',')\n  const groupBy: string = Array.isArray(spec.groupBy)\n    ? [...spec.groupBy].sort().join(',')\n    : typeof spec.groupBy === 'string'\n      ? spec.groupBy\n      : ''\n  const aggKeys = spec.aggregate ? Object.keys(spec.aggregate).sort().join(',') : ''\n  return `union(${arms})|groupBy(${groupBy})|aggregate(${aggKeys})`\n}\n","/**\n * Deterministic hash of a materialized view strategy's \"shape\": MV\n * name + canonical query-plan summary + sorted dependency-set.\n *\n * Used to detect strategy drift: a row whose `_materializedFrom.queryHash`\n * doesn't match the current strategy is considered stale.\n *\n * Web Crypto SHA-256 — no extra deps. Mirrors the v1\n * `computeStrategyHash` pattern.\n */\nexport async function computeQueryHash(\n  mvName: string,\n  /**\n   * Source-collection set the query depends on. Sorted before\n   * canonicalization so set iteration order doesn't affect the hash.\n   */\n  dependencies: ReadonlySet<string>,\n  /**\n   * Stringified query-plan summary. The caller produces this from the\n   * `Query<T>` builder — concretely: a JSON serialization of clauses +\n   * orderBy + limit + offset + joins. Function bodies inside\n   * `wherePredicate` are NOT included here (those carry their own\n   * `predicateHash` to be folded in by a later sub-issue).\n   */\n  queryPlanSummary: string,\n): Promise<string> {\n  const canonical = JSON.stringify({\n    mvName,\n    dependencies: [...dependencies].sort(),\n    queryPlanSummary,\n  })\n  const bytes = new TextEncoder().encode(canonical)\n  const digest = await crypto.subtle.digest('SHA-256', bytes)\n  return Array.from(new Uint8Array(digest))\n    .map(b => b.toString(16).padStart(2, '0'))\n    .join('')\n}\n\n/**\n * Canonicalize a query plan for hashing. Walks the plan structure\n * with sorted keys so insertion order doesn't perturb the result.\n * Lives here rather than in `query/builder.ts` to keep that module\n * stable across MV-specific evolutions.\n *\n * @internal exported for testing\n */\nexport function canonicalizeQueryPlan(plan: unknown): string {\n  return JSON.stringify(plan, (_key, value) => {\n    if (value && typeof value === 'object' && !Array.isArray(value)) {\n      const sorted: Record<string, unknown> = {}\n      for (const k of Object.keys(value as Record<string, unknown>).sort()) {\n        sorted[k] = (value as Record<string, unknown>)[k]\n      }\n      return sorted\n    }\n    return value\n  })\n}\n","import { MaterializedViewCycleError, MaterializedViewSourceUnknownError } from '../errors.js'\nimport type { DerivationRegistry } from '../derivations/registry.js'\nimport type { Clause, FieldClause } from '../query/predicate.js'\nimport type { DeclaredPredicate } from '../query/builder.js'\nimport { analyzeDependencies, summarizeQueryPlan, summarizeUnionPlan } from './dependency-analyzer.js'\nimport { computeQueryHash } from './query-hash.js'\nimport type { MaterializedViewStrategy, MVQueryContext } from './types.js'\n\n/**\n * One registered MV strategy alongside its derived metadata. Stored\n * type-erased on `TRow` so the registry can hold heterogeneous MVs.\n */\nexport interface RegisteredMV {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  readonly spec: MaterializedViewStrategy<any>\n  /** Output collection name (`spec.output?.collection ?? spec.name`). */\n  readonly outputCollection: string\n  /** Set of source collections; populated at registration via the analyzer. */\n  readonly dependencies: ReadonlySet<string>\n  /** Canonical `queryHash` — `_materializedFrom.queryHash` for every emitted row. */\n  readonly queryHash: string\n  /**\n   * Top-level FieldClauses on the partition field, captured at\n   * registration time. Used by the cycle detector to resolve\n   * same-collection-as-source edges via the partition-discriminator\n   * check. Empty when `spec.output?.partition` is undefined.\n   */\n  readonly partitionClauses: readonly FieldClause[]\n}\n\n/**\n * Vault-internal registry of MV strategies. Owned by `Vault`; not\n * exported. Parallel to v1's `DerivationRegistry`; the two graphs share\n * a single cycle-detection pass at vault open (see `validate`).\n *\n * @internal\n */\nexport class MaterializedViewRegistry {\n  /** Keyed by `spec.name`. */\n  private readonly _byName = new Map<string, RegisteredMV>()\n  /** Keyed by dependency source-collection → MVs that depend on it. */\n  private readonly _bySource = new Map<string, RegisteredMV[]>()\n\n  /**\n   * Register an MV. Invokes `spec.query()` once at registration time to\n   * read the plan + join context; the resulting `Query<T>` is discarded\n   * after dependency extraction. `vault.collection(...)` must therefore\n   * be functional by the time this runs — typically wired from\n   * `Vault._initMaterializedViews` after collection bootstrap.\n   *\n   * Throws `MaterializedViewSourceUnknownError` if the analyzer\n   * surfaces a dependency the vault doesn't know about (when a\n   * `knownCollections` checker is supplied).\n   */\n  async register(\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    spec: MaterializedViewStrategy<any>,\n    db: MVQueryContext,\n    options?: { knownCollections?: (name: string) => boolean },\n  ): Promise<void> {\n    // Build a predicate-aware db wrapper. If `spec.predicates` is\n    // declared, the wrapper intercepts `.collection().query()` and\n    // attaches the predicates map to the resulting Query<T>. With no\n    // predicates declared, the wrapper is the original db unchanged.\n    const dbForQuery = spec.predicates ? wrapDbWithPredicates(db, spec.predicates) : db\n\n    // Invoke the query callback once to inspect its plan / dependencies.\n    // For Query<T> shapes the analyzer extracts deps + plan summary\n    // automatically. Aggregation / GroupedAggregation shapes don't\n    // expose the underlying Query, so the spec must declare `sources`\n    // explicitly. `partitionClauses` are only populated for Query<T>\n    // since same-collection-partition is a non-aggregate concern.\n    // UNION-form strategies: dependencies and plan summary come\n    // straight off the strategy — no `query` callback to introspect.\n    // The dependency-analyzer + summarizer are bypassed entirely; the\n    // executor handles materialization via `materializeUnionResult`.\n    let dependencies: Set<string>\n    let queryPlanSummary: string\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    let qAny: any = null\n    let isQuery = false\n    if (spec.unionSources) {\n      dependencies = new Set(spec.unionSources.map(s => s.collection))\n      queryPlanSummary = summarizeUnionPlan(spec)\n    } else {\n      const q = spec.query!(dbForQuery)\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      qAny = q as any\n      isQuery = typeof qAny._plan === 'function'\n      if (isQuery) {\n        dependencies = analyzeDependencies(q)\n        queryPlanSummary = summarizeQueryPlan(q)\n        // Fold `.wherePredicate(name, ctx)` references into the plan\n        // summary so predicate function or ctx changes (signalled by\n        // bumping `hash` or supplying a different ctx) propagate into\n        // `queryHash` and force refresh on next visit.\n        const predicateRefs = extractPredicateRefs(qAny._plan())\n        if (predicateRefs.length > 0) {\n          queryPlanSummary = JSON.stringify({ plan: queryPlanSummary, predicates: predicateRefs })\n        }\n        // If `sources` is ALSO declared, take the union (consumer's\n        // explicit list extends the auto-analyzed set).\n        if (spec.sources) for (const s of spec.sources) dependencies.add(s)\n      } else {\n        // Aggregate shape: require explicit `sources`.\n        if (!spec.sources || spec.sources.length === 0) {\n          throw new Error(\n            `withMaterializedView \"${spec.name}\": query() returned an aggregate ` +\n              `(Aggregation or GroupedAggregation) but no \\`sources\\` field is declared. ` +\n              `The dependency analyzer cannot walk through groupBy().aggregate() ` +\n              `back to the source — declare sources: [...] explicitly.`,\n          )\n        }\n        dependencies = new Set(spec.sources)\n        // Aggregate plans don't carry a chainable query plan for summary\n        // purposes; the dep-set + spec.name serve as the queryHash inputs.\n        queryPlanSummary = JSON.stringify({ aggregate: true, sources: [...spec.sources].sort() })\n      }\n    }\n\n    // Sanity-check declared dependencies against the vault's known\n    // collections. Optional — when the checker isn't supplied (test\n    // wiring, in-process composition) the registration succeeds and\n    // any typo surfaces at first onSourceWrite as a no-op.\n    if (options?.knownCollections) {\n      for (const dep of dependencies) {\n        if (!options.knownCollections(dep)) {\n          throw new MaterializedViewSourceUnknownError(spec.name, dep)\n        }\n      }\n    }\n\n    const outputCollection = spec.output?.collection ?? spec.name\n    const queryHash = await computeQueryHash(spec.name, dependencies, queryPlanSummary)\n    // For same-collection-as-source MVs, capture the where-clauses on\n    // the partition field so cycle detection can prove disjointness.\n    // Only applicable to Query<T> shapes — aggregate MVs don't carry\n    // a chainable plan to inspect (and same-collection aggregation\n    // doesn't make sense for same-collection aggregation).\n    const partitionClauses: FieldClause[] = []\n    const partitionField = spec.output?.partition?.field\n    if (partitionField !== undefined && isQuery) {\n      const plan = qAny._plan()\n      for (const clause of plan.clauses) {\n        if (isFieldClauseOnField(clause, partitionField)) partitionClauses.push(clause)\n      }\n    }\n    const reg: RegisteredMV = { spec, outputCollection, dependencies, queryHash, partitionClauses }\n\n    this._byName.set(spec.name, reg)\n    for (const dep of dependencies) {\n      const arr = this._bySource.get(dep)\n      if (arr) arr.push(reg)\n      else this._bySource.set(dep, [reg])\n    }\n  }\n\n  /** All MVs that depend on `source`, in registration order. */\n  mvsForSource(source: string): ReadonlyArray<RegisteredMV> {\n    return this._bySource.get(source) ?? []\n  }\n\n  /** Single MV by name, or `undefined`. */\n  byName(name: string): RegisteredMV | undefined {\n    return this._byName.get(name)\n  }\n\n  /** Iterate over every registered MV. */\n  all(): ReadonlyArray<RegisteredMV> {\n    return [...this._byName.values()]\n  }\n\n  /**\n   * Cycle detection over the combined derivation + MV graph. Edges:\n   *   - Derivation: derivation.source → output.collection (each output)\n   *   - MV: every dep in MV.dependencies → MV.outputCollection\n   *\n   * Throws `MaterializedViewCycleError` if the cycle's terminal node\n   * is an MV output collection; otherwise (a pure-derivation cycle)\n   * the caller's `DerivationRegistry.validate()` will surface\n   * `DerivationCycleError` separately at vault open.\n   *\n   * Call AFTER all `register()` calls complete.\n   */\n  validate(derivationRegistry?: DerivationRegistry | null): void {\n    const visited = new Set<string>()\n    const stack: string[] = []\n    const mvOutputs = new Set<string>()\n    for (const reg of this._byName.values()) mvOutputs.add(reg.outputCollection)\n\n    const edges = new Map<string, string[]>()\n\n    // MV edges: every dep → output. Same-collection edges (dep ===\n    // outputCollection) are skipped IFF the MV declares an\n    // `output.partition` discriminator AND the query has a where-clause\n    // that provably excludes the partition value. Otherwise the cycle\n    // detector treats the edge as real — naïve same-collection MVs\n    // surface as `MaterializedViewCycleError`.\n    for (const reg of this._byName.values()) {\n      for (const dep of reg.dependencies) {\n        if (dep === reg.outputCollection && partitionDisjoint(reg)) continue\n        const arr = edges.get(dep)\n        if (arr) arr.push(reg.outputCollection)\n        else edges.set(dep, [reg.outputCollection])\n      }\n    }\n\n    // Derivation edges: source → output collections\n    if (derivationRegistry) {\n      // The shared DerivationRegistry exposes its edges via the same\n      // `strategiesForSource` API its own `validate()` uses. We don't\n      // duplicate cycle detection — we add MV nodes to the graph and\n      // run the unified DFS, attributing cycles that touch an MV\n      // output to `MaterializedViewCycleError`.\n      for (const reg of this._byName.values()) {\n        // Walk every dependency through derivation edges too: a\n        // derivation whose output we depend on is itself a source.\n        void reg\n      }\n      // Pull derivation edges by scanning every MV dep + every MV\n      // output as potential derivation sources.\n      const sourcesToScan = new Set<string>()\n      for (const reg of this._byName.values()) {\n        for (const dep of reg.dependencies) sourcesToScan.add(dep)\n        sourcesToScan.add(reg.outputCollection)\n      }\n      for (const src of sourcesToScan) {\n        const strategies = derivationRegistry.strategiesForSource(src)\n        if (strategies.length === 0) continue\n        for (const s of strategies) {\n          for (const key of Object.keys(s.spec.outputs)) {\n            const o = s.spec.outputs[key]\n            if (!o) continue\n            const arr = edges.get(src)\n            if (arr) arr.push(o.collection)\n            else edges.set(src, [o.collection])\n          }\n        }\n      }\n    }\n\n    const visit = (node: string): void => {\n      if (stack.includes(node)) {\n        const cycle = stack.slice(stack.indexOf(node)).concat(node)\n        // If any node on the cycle is an MV output, attribute as MV\n        // cycle. Otherwise let DerivationRegistry.validate() surface it.\n        if (cycle.some(n => mvOutputs.has(n))) {\n          throw new MaterializedViewCycleError(cycle)\n        }\n        // Pure-derivation cycle — caller's DerivationRegistry.validate()\n        // will catch it separately. Don't double-report.\n        return\n      }\n      if (visited.has(node)) return\n      stack.push(node)\n      const outs = edges.get(node)\n      if (outs) for (const o of outs) visit(o)\n      stack.pop()\n      visited.add(node)\n    }\n\n    for (const node of edges.keys()) visit(node)\n  }\n}\n\n/**\n * Type guard: is the clause a top-level `FieldClause` on the given\n * field? Used by the partition-disjoint check.\n *\n * @internal\n */\nfunction isFieldClauseOnField(clause: Clause, field: string): clause is FieldClause {\n  return clause.type === 'field' && clause.field === field\n}\n\n/**\n * Wrap an `MVQueryContext` so its `.collection().query()` returns a\n * Query<T> with the MV's declared predicates attached. Bare Queries\n * (outside of any MV) don't gain `.wherePredicate()` — only Queries\n * obtained through this wrapped db do.\n *\n * @internal\n */\nexport function wrapDbWithPredicates(\n  db: MVQueryContext,\n  predicates: NonNullable<MaterializedViewStrategy<Record<string, unknown>>['predicates']>,\n): MVQueryContext {\n  // Build the predicate map once — the fn signature in the MV spec\n  // is row-typed but the QueryBuilder casts to unknown, so we widen\n  // here for the Map.\n  const map = new Map<string, DeclaredPredicate>()\n  for (const [name, decl] of Object.entries(predicates)) {\n    map.set(name, {\n      hash: decl.hash,\n      fn: decl.fn as (record: unknown, ctx?: unknown) => boolean,\n    })\n  }\n  return {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    collection<T extends Record<string, unknown>>(name: string): any {\n      const c = db.collection<T>(name)\n      // Return an object that delegates everything to `c` but\n      // overrides `.query()` to attach predicates via the new\n      // `Query._withPredicates()` accessor.\n      return new Proxy(c, {\n        get(target, prop, receiver) {\n          if (prop === 'query') {\n            return (...args: unknown[]) => {\n              // eslint-disable-next-line @typescript-eslint/no-explicit-any\n              const q = (target.query as any)(...args)\n              // For non-aggregate Query<T>, attach predicates. For\n              // legacy predicate-arg overload that returns T[] (sync\n              // filter), pass through unchanged.\n               \n              if (q && typeof q._withPredicates === 'function') {\n                return q._withPredicates(map)\n              }\n              return q\n            }\n          }\n          return Reflect.get(target, prop, receiver)\n        },\n      })\n    },\n  }\n}\n\n/**\n * Walk a QueryPlan's clauses and collect predicate-reference markers\n * for `queryHash` derivation. Returns a sorted array (deterministic\n * order) of `{ name, predicateHash, ctxHash }` tuples — these are the\n * hashable identity of each `.wherePredicate()` call site.\n *\n * @internal\n */\nfunction extractPredicateRefs(\n  plan: { clauses: readonly Clause[] },\n): Array<{ name: string; predicateHash: string; ctxHash: string }> {\n  const refs: Array<{ name: string; predicateHash: string; ctxHash: string }> = []\n  const walk = (clauses: readonly Clause[]): void => {\n    for (const c of clauses) {\n      if (c.type === 'wherePredicate') {\n        refs.push({ name: c.name, predicateHash: c.predicateHash, ctxHash: c.ctxHash })\n      } else if (c.type === 'group') {\n        walk(c.clauses)\n      }\n    }\n  }\n  walk(plan.clauses)\n  // Stable-sort by (name, predicateHash, ctxHash) — same predicate\n  // appearing twice with different ctx hashes both flow through.\n  refs.sort((a, b) => {\n    if (a.name !== b.name) return a.name < b.name ? -1 : 1\n    if (a.predicateHash !== b.predicateHash) return a.predicateHash < b.predicateHash ? -1 : 1\n    return a.ctxHash < b.ctxHash ? -1 : a.ctxHash > b.ctxHash ? 1 : 0\n  })\n  return refs\n}\n\n/**\n * Provability check for the same-collection partition-discriminator\n * (spec § Same-collection-as-source MV). Returns `true` when\n * the captured partition clauses on the MV's query provably exclude\n * the partition's value — meaning the input filter and the output\n * partition are disjoint and the same-collection edge isn't really a\n * cycle.\n *\n * Supported provability shapes (narrow on purpose — DERIV-PP30-001\n * is the load-bearing case):\n *\n * - `.where(field, '==', X)` where X !== partition.value → disjoint\n * - `.where(field, '!=', partition.value)` → disjoint\n * - `.where(field, 'in', [...])` where partition.value NOT in list → disjoint\n *\n * Anything else (no clause on the partition field, an 'in' list that\n * contains partition.value, unsupported operators) → not disjoint,\n * the cycle detector surfaces `MaterializedViewCycleError`.\n *\n * @internal\n */\nfunction partitionDisjoint(reg: RegisteredMV): boolean {\n  const partition = reg.spec.output?.partition\n  if (partition === undefined) return false\n  const value = partition.value\n  // The OR-semantics of multiple where-clauses on the same field\n  // would muddy this check. v2 only treats AND-chained clauses;\n  // any clause that proves disjoint is sufficient.\n  for (const c of reg.partitionClauses) {\n    if (c.op === '==' && c.value !== value) return true\n    if (c.op === '!=' && c.value === value) return true\n    if (c.op === 'in' && Array.isArray(c.value)) {\n      const list = c.value as readonly unknown[]\n      if (!list.includes(value)) return true\n    }\n  }\n  return false\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-EPK6A3WJ.js → chunk-A3JMGXPG.js}

@@ -13,7 +13,7 @@ var GuardRegistry = class {
   guardsFor(collection) {
     return this._byCollection.get(collection) ?? [];
   }
-  /** Per-collection guard counts, for introspection (#229). */
+  /** Per-collection guard counts, for introspection. */
   summary() {
     return [...this._byCollection.entries()].map(([collection, guards]) => ({
       collection,
@@ -122,4 +122,4 @@ var GuardRegistry = class {
 export {
   GuardRegistry
 };
-//# sourceMappingURL=chunk-EPK6A3WJ.js.map
+//# sourceMappingURL=chunk-A3JMGXPG.js.map

package/dist/chunk-A3JMGXPG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/guards/registry.ts"],"sourcesContent":["import type { GuardStrategy, GuardContext, GuardChange } from './types.js'\n\n/**\n * Per-record metadata attached to every entry in an amendment's\n * change-set. Carried in a parallel map alongside `_amendmentChanges`\n * so the public {@link GuardChange} shape (`{ before, after }`) stays\n * clean for invariant authors — the audit ledger reads this side\n * structure to produce the `{ collection, id, vBefore, vAfter }`\n * tuples for the amendment entry.\n *\n * @internal\n */\nexport interface AmendmentChangeMeta {\n  readonly id: string\n  readonly vBefore: number\n  readonly vAfter: number\n}\n\n/**\n * Vault-internal singleton that holds the guard graph and dispatches\n * per-collection guard execution. Owned by `Vault`; not exported.\n *\n * @internal\n */\n// Internal storage alias — guards are heterogeneous in their record type T,\n// so the registry stores them at the upper bound of GuardStrategy's T constraint.\ntype AnyGuard = GuardStrategy<Record<string, unknown>>\ntype AnyChange = GuardChange<Record<string, unknown>>\n\nexport class GuardRegistry {\n  private readonly _byCollection = new Map<string, AnyGuard[]>()\n  private _amendmentChanges: Map<string, AnyChange[]> | null = null\n  private _amendmentMeta: Map<string, AmendmentChangeMeta[]> | null = null\n\n  /** Register a guard. Multiple guards per collection are allowed. */\n  register<T extends Record<string, unknown>>(spec: GuardStrategy<T>): void {\n    const existing = this._byCollection.get(spec.collection)\n    if (existing) existing.push(spec as unknown as AnyGuard)\n    else this._byCollection.set(spec.collection, [spec as unknown as AnyGuard])\n  }\n\n  /** All guards registered against `collection` in registration order. */\n  guardsFor(collection: string): ReadonlyArray<AnyGuard> {\n    return this._byCollection.get(collection) ?? []\n  }\n\n  /** Per-collection guard counts, for introspection. */\n  summary(): { collection: string; count: number }[] {\n    return [...this._byCollection.entries()].map(([collection, guards]) => ({\n      collection,\n      count: guards.length,\n    }))\n  }\n\n  /**\n   * Run every guard's `check` for this collection. First throw wins —\n   * remaining guards are not invoked. Guards without a `check` skip.\n   */\n  async runChecks<T>(\n    collection: string,\n    incoming: T,\n    ctx: GuardContext<T>,\n  ): Promise<void> {\n    const guards = this._byCollection.get(collection)\n    if (!guards) return\n    for (const g of guards) {\n      if (g.check) {\n        await g.check(\n          incoming as unknown as Record<string, unknown>,\n          ctx as unknown as GuardContext<Record<string, unknown>>,\n        )\n      }\n    }\n  }\n\n  /**\n   * Run every guard's `onDelete` for this collection. First throw wins —\n   * remaining guards are not invoked. Guards without an `onDelete` skip.\n   * Mirrors {@link runChecks} but for the delete path.\n   */\n  async runOnDelete<T>(\n    collection: string,\n    existing: T,\n    ctx: GuardContext<T>,\n  ): Promise<void> {\n    const guards = this._byCollection.get(collection)\n    if (!guards) return\n    for (const g of guards) {\n      if (g.onDelete) {\n        await g.onDelete(\n          existing as unknown as Record<string, unknown>,\n          ctx as unknown as GuardContext<Record<string, unknown>>,\n        )\n      }\n    }\n  }\n\n  /** True if any guard for `collection` declares an `amendment` block. */\n  hasAmendment(collection: string): boolean {\n    const guards = this._byCollection.get(collection)\n    if (!guards) return false\n    return guards.some(g => g.amendment !== undefined)\n  }\n\n  /** Open a new amendment change-collection window. */\n  beginAmendment(): void {\n    this._amendmentChanges = new Map()\n    this._amendmentMeta = new Map()\n  }\n\n  /** True iff we're currently inside an amendment transaction. */\n  isAmendmentActive(): boolean {\n    return this._amendmentChanges !== null\n  }\n\n  /**\n   * Record a {before, after} pair for the active amendment. `vBefore`\n   * and `vAfter` are stored in a parallel meta structure so the public\n   * {@link GuardChange} shape handed to invariant callbacks stays\n   * `{ before, after }` only — the audit ledger reads version metadata\n   * via {@link consumeMeta}.\n   */\n  collectChange<T>(\n    collection: string,\n    id: string,\n    before: T | null,\n    after: T,\n    vBefore = 0,\n    vAfter = 0,\n  ): void {\n    if (this._amendmentChanges === null || this._amendmentMeta === null) {\n      throw new Error('GuardRegistry.collectChange called outside an amendment')\n    }\n    const list = this._amendmentChanges.get(collection)\n    const entry = { before, after } as unknown as AnyChange\n    if (list) list.push(entry)\n    else this._amendmentChanges.set(collection, [entry])\n\n    const metaList = this._amendmentMeta.get(collection)\n    const metaEntry: AmendmentChangeMeta = { id, vBefore, vAfter }\n    if (metaList) metaList.push(metaEntry)\n    else this._amendmentMeta.set(collection, [metaEntry])\n  }\n\n  /**\n   * Drain the change-set and close the amendment window. The caller\n   * (transaction commit) feeds these to each affected guard's invariant.\n   */\n  consumeChanges(): ReadonlyMap<string, ReadonlyArray<AnyChange>> {\n    const out = this._amendmentChanges ?? new Map()\n    this._amendmentChanges = null\n    return out\n  }\n\n  /**\n   * Drain the parallel id/version metadata captured during the\n   * amendment. Returned as a flat list with `collection` denormalised\n   * so the audit ledger can emit one `{ collection, id, vBefore,\n   * vAfter }` tuple per record. Must be called AFTER\n   * {@link consumeChanges} (or independently) — calling it closes the\n   * meta window in the same way.\n   */\n  consumeMeta(): ReadonlyArray<{ collection: string; id: string; vBefore: number; vAfter: number }> {\n    const out: { collection: string; id: string; vBefore: number; vAfter: number }[] = []\n    if (this._amendmentMeta) {\n      for (const [collection, list] of this._amendmentMeta) {\n        for (const m of list) {\n          out.push({ collection, id: m.id, vBefore: m.vBefore, vAfter: m.vAfter })\n        }\n      }\n    }\n    this._amendmentMeta = null\n    return out\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-75QDHSE4.js → chunk-A4JNVBPF.js}

@@ -1,19 +1,19 @@
 import {
   ATTESTATIONS_COLLECTION,
   loadOrCreateSigner
-} from "./chunk-ZUMGGHRB.js";
+} from "./chunk-OPD3PZOG.js";
 import {
   generateULID
 } from "./chunk-FZU343FL.js";
 import {
   NOYDB_FORMAT_VERSION
-} from "./chunk-FXQYZNOW.js";
+} from "./chunk-5OVIFUQE.js";
 import {
   encrypt
-} from "./chunk-UOF74WQY.js";
+} from "./chunk-EKTOYEZ3.js";
 import {
   AttestationError
-} from "./chunk-YDLAFP36.js";
+} from "./chunk-6HJ2ZALB.js";
 
 // src/attestation/issue.ts
 import {
@@ -56,4 +56,4 @@ async function issueAttestationCore(ctx, args) {
 export {
   issueAttestationCore
 };
-//# sourceMappingURL=chunk-75QDHSE4.js.map
+//# sourceMappingURL=chunk-A4JNVBPF.js.map

package/dist/{chunk-IS5HWQO7.js → chunk-ARZAHCCF.js}

@@ -1,9 +1,9 @@
 import {
   decrypt
-} from "./chunk-UOF74WQY.js";
+} from "./chunk-EKTOYEZ3.js";
 import {
   ReadOnlyAtInstantError
-} from "./chunk-YDLAFP36.js";
+} from "./chunk-6HJ2ZALB.js";
 
 // src/history/history.ts
 var HISTORY_COLLECTION = "_history";
@@ -309,4 +309,4 @@ export {
   diff,
   formatDiff
 };
-//# sourceMappingURL=chunk-IS5HWQO7.js.map
+//# sourceMappingURL=chunk-ARZAHCCF.js.map