@noy-db/hub 0.1.0-pre.3

package/dist/chunk-ZRG4V3F5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\n * Core types — the {@link NoydbStore} interface, envelope format, roles, and\n * all configuration shapes consumed by {@link createNoydb}.\n *\n * ## What lives here\n *\n * - **{@link NoydbStore}** — the 6-method contract every backend must implement\n *   (`get`, `put`, `delete`, `list`, `loadAll`, `saveAll`).\n * - **{@link EncryptedEnvelope}** — the wire format stored by backends:\n *   `{ _noydb, _v, _ts, _iv, _data }`. Backends only ever see this shape.\n * - **{@link Role} / {@link Permission}** — the access-control vocabulary\n *   (`owner`, `admin`, `operator`, `viewer`, `client`).\n * - **{@link NoydbOptions}** — the full configuration object passed to\n *   {@link createNoydb}.\n *\n * ## Extending the store interface\n *\n * All optional store capabilities (`ping`, `listPage`, `listSince`,\n * `presencePublish`, `presenceSubscribe`, `listVaults`) are additive extensions\n * discovered via `'method' in store`. Implementing them unlocks features but\n * is never required — core always falls back to the 6-method baseline.\n *\n * @module\n */\n\nimport type { StandardSchemaV1 } from './schema.js'\nimport type { SyncPolicy } from './store/sync-policy.js'\nimport type { BlobStrategy } from './blobs/strategy.js'\nimport type { IndexStrategy } from './indexing/strategy.js'\nimport type { AggregateStrategy } from './aggregate/strategy.js'\nimport type { CrdtStrategy } from './crdt/strategy.js'\nimport type { ConsentStrategy } from './consent/strategy.js'\nimport type { PeriodsStrategy } from './periods/strategy.js'\nimport type { ShadowStrategy } from './shadow/strategy.js'\nimport type { TxStrategy } from './tx/strategy.js'\nimport type { HistoryStrategy } from './history/strategy.js'\nimport type { I18nStrategy } from './i18n/strategy.js'\nimport type { SessionStrategy } from './session/strategy.js'\nimport type { SyncStrategy } from './team/sync-strategy.js'\n\n/** Format version for encrypted record envelopes. */\nexport const NOYDB_FORMAT_VERSION = 1 as const\n\n/** Format version for keyring files. */\nexport const NOYDB_KEYRING_VERSION = 1 as const\n\n/** Format version for backup files. */\nexport const NOYDB_BACKUP_VERSION = 1 as const\n\n/** Format version for sync metadata. */\nexport const NOYDB_SYNC_VERSION = 1 as const\n\n// ─── Roles & Permissions ───────────────────────────────────────────────\n\n/**\n * Access role assigned to a user within a vault.\n *\n * Roles control both the operations a user can perform and which DEKs\n * they receive in their keyring:\n *\n * | Role       | Collections      | Can grant/revoke | Can export |\n * |------------|-----------------|:----------------:|:----------:|\n * | `owner`    | all (rw)        | Yes (all roles)  | Yes        |\n * | `admin`    | all (rw)        | Yes (≤ admin)    | Yes        |\n * | `operator` | explicit (rw)   | No               | ACL-scoped |\n * | `viewer`   | all (ro)        | No               | Yes        |\n * | `client`   | explicit (ro)   | No               | ACL-scoped |\n */\nexport type Role = 'owner' | 'admin' | 'operator' | 'viewer' | 'client'\n\n/**\n * Read-write or read-only access on a collection.\n * Stored per-collection in the user's keyring.\n */\nexport type Permission = 'rw' | 'ro'\n\n/**\n * Map of collection name → permission level for a user's keyring entry.\n * `'*'` is the wildcard collection matching all collections in the vault.\n */\nexport type Permissions = Record<string, Permission>\n\n// ─── Encrypted Envelope ────────────────────────────────────────────────\n\n/** The encrypted wrapper stored by adapters. Adapters only ever see this. */\nexport interface EncryptedEnvelope {\n  readonly _noydb: typeof NOYDB_FORMAT_VERSION\n  readonly _v: number\n  readonly _ts: string\n  readonly _iv: string\n  readonly _data: string\n  /** User who created this version (unencrypted metadata). */\n  readonly _by?: string\n  /**\n   * Hierarchical access tier. Omitted → tier 0.\n   *\n   * Unencrypted on purpose — the store reads it to route the envelope\n   * to the right DEK slot without having to try-decrypt against every\n   * tier. Only leaks the tier of each record, not any value\n   * equivalence.\n   */\n  readonly _tier?: number\n  /**\n   * User id who last elevated this record. Used by\n   * `demote()` to gate the reverse operation: only the original\n   * elevator or an owner can demote a record back down. Cleared on\n   * every successful demote so a later re-elevate requires the new\n   * actor to own the demotion right.\n   */\n  readonly _elevatedBy?: string\n  /**\n   * Deterministic-encryption index. Map of field name →\n   * base64 deterministic ciphertext. Present only when the collection\n   * declares `deterministicFields` and the feature is acknowledged. The\n   * field names are unencrypted (they're the index keys); the values\n   * are AES-GCM ciphertext with an HKDF-derived deterministic IV.\n   *\n   * Enables blind equality search (`collection.findByDet(field,\n   * value)`) without decrypting every record. Leaks equality as a known\n   * side channel.\n   */\n  readonly _det?: Record<string, string>\n}\n\n/**\n * Placeholder returned by `getAtTier()` in `'ghost'` mode when a\n * record is at a tier the caller cannot decrypt. Record existence is\n * advertised — the id and tier are visible — but contents are\n * withheld. `canElevateFrom` lists user ids authorized to elevate\n * access for this caller when known; absent when the workflow is\n * not configured.\n */\nexport interface GhostRecord {\n  readonly _ghost: true\n  readonly _tier: number\n  readonly canElevateFrom?: readonly string[]\n}\n\n/** Control what lower-tier reads see above their clearance. */\nexport type TierMode = 'invisibility' | 'ghost'\n\n/**\n * Event emitted when a record at a tier above the caller's inherent\n * clearance is read or written successfully (via elevation or\n * delegation). Always written to the ledger; subscribers get a\n * real-time feed.\n */\nexport interface CrossTierAccessEvent {\n  readonly actor: string\n  readonly collection: string\n  readonly id: string\n  readonly tier: number\n  /** How the caller gained tier access: they elevated it, or a delegation is active. */\n  readonly authorization: 'elevation' | 'delegation' | 'inherent'\n  readonly op: 'get' | 'put' | 'elevate' | 'demote'\n  readonly ts: string\n  /**\n   * When `authorization === 'elevation'`, the audit reason string the\n   * caller passed to `vault.elevate(...)`. Empty for inherent /\n   * delegation paths.\n   */\n  readonly reason?: string\n  /**\n   * When `authorization === 'elevation'`, the tier the caller's\n   * keyring effectively held BEFORE elevation. Useful for audit\n   * dashboards distinguishing \"operator elevating to 2\" from\n   * \"inherent tier-2 write.\"\n   */\n  readonly elevatedFrom?: number\n}\n\n/**\n * A single deterministic-ciphertext index slot on an envelope. Stored\n * as `iv:data` (both base64, colon-separated) so a single string per\n * field keeps the envelope compact.\n */\nexport type DeterministicCipher = string\n\n// ─── Vault Snapshot ──────────────────────────────────────────────\n\n/** All records across all collections for a compartment. */\nexport type VaultSnapshot = Record<string, Record<string, EncryptedEnvelope>>\n\n/**\n * Result of a single page fetch via the optional `listPage` adapter extension.\n *\n * `items` carries the actual encrypted envelopes (not just ids) so the\n * caller can decrypt and emit a single record without an extra `get()`\n * round-trip per id. `nextCursor` is `null` on the final page.\n */\nexport interface ListPageResult {\n  /** Encrypted envelopes for this page, in adapter-defined order. */\n  items: Array<{ id: string; envelope: EncryptedEnvelope }>\n  /** Opaque cursor for the next page, or `null` if this was the last page. */\n  nextCursor: string | null\n}\n\n// ─── Store Interface ───────────────────────────────────────────────────\n\nexport interface NoydbStore {\n  /**\n   * Optional human-readable adapter name (e.g. 'memory', 'file', 'dynamo').\n   * Used in diagnostic messages and the listPage fallback warning. Adapters\n   * are encouraged to set this so logs are clearer about which backend is\n   * involved when something goes wrong.\n   */\n  name?: string\n\n  /** Get a single record. Returns null if not found. */\n  get(vault: string, collection: string, id: string): Promise<EncryptedEnvelope | null>\n\n  /** Put a record. Throws ConflictError if expectedVersion doesn't match. */\n  put(\n    vault: string,\n    collection: string,\n    id: string,\n    envelope: EncryptedEnvelope,\n    expectedVersion?: number,\n  ): Promise<void>\n\n  /** Delete a record. */\n  delete(vault: string, collection: string, id: string): Promise<void>\n\n  /** List all record IDs in a collection. */\n  list(vault: string, collection: string): Promise<string[]>\n\n  /** Load all records for a vault (initial hydration). */\n  loadAll(vault: string): Promise<VaultSnapshot>\n\n  /** Save all records for a vault (bulk write / restore). */\n  saveAll(vault: string, data: VaultSnapshot): Promise<void>\n\n  /** Optional connectivity check for sync engine. */\n  ping?(): Promise<boolean>\n\n  /**\n   * Optional: list record IDs in a collection that have `_ts` after `since`.\n   * Used by partial sync (`pull({ modifiedSince })`). Adapters that omit this\n   * fall back to a full `loadAll` + client-side timestamp filter.\n   */\n  listSince?(vault: string, collection: string, since: string): Promise<string[]>\n\n  /**\n   * Optional pagination extension. Adapters that implement `listPage` get\n   * the streaming `Collection.scan()` fast path; adapters that don't are\n   * silently fallen back to a full `loadAll()` + slice (with a one-time\n   * console.warn).\n   *\n   * `cursor` is opaque to the core — each adapter encodes its own paging\n   * state (DynamoDB: base64 LastEvaluatedKey JSON; S3: ContinuationToken;\n   * memory/file/browser: numeric offset of a sorted id list). Pass\n   * `undefined` to start from the beginning.\n   *\n   * `limit` is a soft upper bound on `items.length`. Adapters MAY return\n   * fewer items even when more exist (e.g. if the underlying store has\n   * its own page size cap), and MUST signal \"no more pages\" by returning\n   * `nextCursor: null`.\n   *\n   * The 6-method core contract is unchanged — this is an additive\n   * extension discovered via `'listPage' in adapter`.\n   */\n  listPage?(\n    vault: string,\n    collection: string,\n    cursor?: string,\n    limit?: number,\n  ): Promise<ListPageResult>\n\n  /**\n   * Optional pub/sub for real-time presence.\n   * Publish an encrypted payload to a presence channel.\n   * Falls back to storage-based polling when absent.\n   */\n  presencePublish?(channel: string, payload: string): Promise<void>\n\n  /**\n   * Optional pub/sub for real-time presence.\n   * Subscribe to a presence channel. Returns an unsubscribe function.\n   * Falls back to storage-based polling when absent.\n   */\n  presenceSubscribe?(channel: string, callback: (payload: string) => void): () => void\n\n  /**\n   * Optional cross-vault enumeration extension.\n   *\n   * Returns the names of every top-level vault the store\n   * currently stores. Used by `Noydb.listAccessibleVaults()` to\n   * enumerate the universe of vaults before filtering down to\n   * the ones the calling principal can actually unwrap.\n   *\n   * **Why this is optional:** the storage shape of compartments\n   * differs across backends. Memory and file stores store\n   * vaults as top-level keys / directories and can enumerate\n   * them in O(1) calls. DynamoDB stores everything in a single table\n   * keyed by `(compartment#collection, id)` — enumerating compartments\n   * requires either a Scan (expensive, eventually consistent, leaks\n   * ciphertext metadata) or a dedicated GSI that the consumer\n   * provisioned. S3 needs a prefix list (cheap if enabled, ACL-sensitive\n   * otherwise). Browser localStorage can scan keys by prefix.\n   *\n   * Stores that cannot implement `listVaults` cheaply or\n   * cleanly should omit it. Core surfaces a `StoreCapabilityError`\n   * with a clear message when a caller invokes\n   * `listAccessibleVaults()` against a store that doesn't\n   * provide this method, so consumers know to either upgrade their\n   * store, provide a candidate list explicitly to `queryAcross()`,\n   * or fall back to maintaining the compartment index out of band.\n   *\n   * **Privacy note:** `listVaults` returns *every* compartment\n   * the store has, not just the ones the caller can access. The\n   * existence-leak filtering (returning only compartments whose\n   * keyring the caller can unwrap) happens in core, not in the\n   * store. The store is trusted to know its own contents — that\n   * is not a leak in the threat model. The leak the API guards\n   * against is the *return value* of `listAccessibleVaults()`\n   * exposing existence to a downstream observer who only sees that\n   * function's output.\n   *\n   * The 6-method core contract is unchanged — this is an additive\n   * extension discovered via `'listVaults' in store`.\n   */\n  listVaults?(): Promise<string[]>\n\n  /**\n   * Optional: generate a presigned URL for direct client download.\n   * Only meaningful for object stores (S3, GCS) that support URL signing.\n   * Returns a time-limited URL that fetches the encrypted envelope directly.\n   * The caller must decrypt client-side (the URL returns ciphertext).\n   */\n  presignUrl?(vault: string, collection: string, id: string, expiresInSeconds?: number): Promise<string>\n\n  /**\n   * Optional: estimate current storage usage.\n   * Returns `{ usedBytes, quotaBytes }` or null if the store cannot estimate.\n   * Used by quota-aware routing to detect overflow conditions.\n   */\n  estimateUsage?(): Promise<{ usedBytes: number; quotaBytes: number } | null>\n\n  /**\n   * Optional multi-record atomic write.\n   *\n   * When present, `db.transaction(async (tx) => { ... })` uses this to\n   * commit every staged op in one storage-layer transaction — either\n   * all ops land or none do, regardless of which records they touch.\n   * Every `TxOp.expectedVersion` (when set) must be honored atomically\n   * alongside the write; any violation throws `ConflictError` and the\n   * whole batch fails.\n   *\n   * Stores that omit this fall through to the hub's per-record OCC\n   * fallback: pre-flight CAS check, then sequential `put`/`delete`\n   * with best-effort unwind on mid-batch failure (see\n   * `runTransaction` for the exact semantics and crash window).\n   *\n   * Native implementations: `to-memory` (single Map mutation),\n   * `to-dynamo` (`TransactWriteItems`), `to-browser-idb` (one\n   * `readwrite` transaction). File / S3 cannot implement this\n   * atomically and should omit the method.\n   */\n  tx?(ops: readonly TxOp[]): Promise<void>\n}\n\n/**\n * A single staged operation inside a `db.transaction(fn)` commit. The\n * hub assembles `TxOp[]` from the user's `tx.collection().put/delete`\n * calls, encrypts any `record` values into `envelope`, and hands the\n * array to `NoydbStore.tx()` when the store supports atomic batch\n * writes. Stores that implement `tx()` MUST honor every\n * `expectedVersion` atomically against the stored envelope version.\n */\nexport interface TxOp {\n  readonly type: 'put' | 'delete'\n  readonly vault: string\n  readonly collection: string\n  readonly id: string\n  /** Populated for `type: 'put'` — the encrypted envelope to write. */\n  readonly envelope?: EncryptedEnvelope\n  /** Optional per-record CAS. Mismatch must throw `ConflictError`. */\n  readonly expectedVersion?: number\n}\n\n// ─── Store Factory Helper ──────────────────────────────────────────────\n\n/** Type-safe helper for creating store factories. */\nexport function createStore<TOptions>(\n  factory: (options: TOptions) => NoydbStore,\n): (options: TOptions) => NoydbStore {\n  return factory\n}\n\n// ─── Keyring ───────────────────────────────────────────────────────────\n\n/**\n * Interchange formats `@noy-db/as-*` packages can produce. `'*'` is a\n * wildcard granting every current + future plaintext format.\n */\nexport type ExportFormat =\n  | 'xlsx'\n  | 'csv'\n  | 'json'\n  | 'ndjson'\n  | 'xml'\n  | 'sql'\n  | 'pdf'\n  | 'blob'\n  | 'zip'\n  | '*'\n\n/**\n * Owner-granted export capability on a keyring.\n *\n * Two independent dimensions:\n *\n * - `plaintext` — per-format allowlist for record formatters + blob\n *   extractors that emit plaintext bytes (`as-xlsx`, `as-csv`,\n *   `as-blob`, `as-zip`, …). **Defaults to empty** for every role;\n *   the owner/admin must positively grant per-format (or `'*'`).\n * - `bundle` — boolean for `.noydb` encrypted container export\n *   (`as-noydb`). **Default policy: on for owner/admin, off for\n *   operator/viewer/client** — applied when the field is absent or\n *   undefined (see `hasExportCapability`).\n */\nexport interface ExportCapability {\n  readonly plaintext?: readonly ExportFormat[]\n  readonly bundle?: boolean\n}\n\n/**\n * Owner-granted import capability on a keyring (sibling of\n * `ExportCapability`, issue ).\n *\n * Two independent dimensions:\n *\n * - `plaintext` — per-format allowlist for `as-*` readers that ingest\n *   plaintext bytes (`as-csv`, `as-json`, `as-ndjson`, `as-zip`, …).\n *   Defaults to empty for every role; the owner/admin must positively\n *   grant per-format (or `'*'`).\n * - `bundle` — boolean gate for `.noydb` bundle import. **Defaults to\n *   `false` for every role**, including owner/admin. Import is more\n *   dangerous than export (corrupts vs leaks), so the policy is\n *   default-closed across the board — the owner explicitly opts a\n *   keyring in via `db.grant({ importCapability: { bundle: true } })`.\n */\nexport interface ImportCapability {\n  readonly plaintext?: readonly ExportFormat[]\n  readonly bundle?: boolean\n}\n\nexport interface KeyringFile {\n  readonly _noydb_keyring: typeof NOYDB_KEYRING_VERSION\n  readonly user_id: string\n  readonly display_name: string\n  readonly role: Role\n  readonly permissions: Permissions\n  readonly deks: Record<string, string>\n  readonly salt: string\n  readonly created_at: string\n  readonly granted_by: string\n  /**\n   * Optional — authorization spec capability bits. Absent on keyrings written\n   * before the RFC implementation. Loading falls back to role-based\n   * defaults (owner/admin get bundle-on, everyone else off).\n   */\n  readonly export_capability?: ExportCapability\n  /**\n   * Optional bundle-slot expiry. ISO-8601 timestamp; past\n   * the cutoff `loadKeyring` throws `KeyringExpiredError` before any\n   * DEK unwrap is attempted. Useful for time-boxed audit access:\n   * \"this slot works for 30 days then becomes opaque to its holder.\"\n   *\n   * Absent on live keyrings written via `db.grant()` — the field is\n   * meaningful for `BundleRecipient` slots produced by\n   * `writeNoydbBundle({ recipients: [...] })`. Setting it on a live\n   * keyring is allowed but unusual.\n   */\n  readonly expires_at?: string\n  /**\n   * Optional — issue  import-capability bits. Absent on keyrings\n   * written before  landed. Loading falls back to default-closed\n   * for every role and every format.\n   */\n  readonly import_capability?: ImportCapability\n  /**\n   * hierarchical access clearance. Absent → 0 (advisory;\n   * the real check is whether the DEK map carries a `collection#tier`\n   * entry for the requested tier). Owners and admins default to the\n   * highest tier they have DEKs for at grant time.\n   */\n  readonly clearance?: number\n}\n\n// ─── Backup ────────────────────────────────────────────────────────────\n\nexport interface VaultBackup {\n  readonly _noydb_backup: typeof NOYDB_BACKUP_VERSION\n  readonly _compartment: string\n  readonly _exported_at: string\n  readonly _exported_by: string\n  readonly keyrings: Record<string, KeyringFile>\n  readonly collections: VaultSnapshot\n  /**\n   * Internal collections (`_ledger`, `_ledger_deltas`, `_history`, `_sync`, …)\n   * captured alongside the data collections. Optional for backwards\n   * compat with backups, which only stored data collections —\n   * loading a backup leaves the ledger empty (and `verifyBackupIntegrity`\n   * skips the chain check, surfacing only a console warning).\n   */\n  readonly _internal?: VaultSnapshot\n  /**\n   * Verifiable-backup metadata. Embeds the ledger head at\n   * dump time so `load()` can cross-check that the loaded chain matches\n   * exactly what was exported. A backup whose chain has been tampered\n   * with — either by modifying ledger entries or by modifying data\n   * envelopes that the chain references — fails this check.\n   *\n   * Optional for backwards compat with backups; missing means\n   * \"legacy backup, load with a warning, no integrity check\".\n   */\n  readonly ledgerHead?: {\n    /** Hex sha256 of the canonical JSON of the last ledger entry. */\n    readonly hash: string\n    /** Sequential index of the last ledger entry. */\n    readonly index: number\n    /** ISO timestamp captured at dump time. */\n    readonly ts: string\n  }\n}\n\n// ─── Export ────────────────────────────────────────────────────────────\n\n/**\n * Options for `Vault.exportStream()` and `Vault.exportJSON()`.\n *\n * The defaults match the most common consumer pattern: one chunk per\n * collection, no ledger metadata. Per-record streaming and ledger-head\n * inclusion are opt-in because both add structure most consumers don't\n * need.\n */\nexport interface ExportStreamOptions {\n  /**\n   * `'collection'` (default) yields one chunk per collection with all\n   * records bundled in `chunk.records`. `'record'` yields one chunk per\n   * record, useful for arbitrarily large collections that should never\n   * be materialized as a single array.\n   */\n  readonly granularity?: 'collection' | 'record'\n\n  /**\n   * When `true`, every chunk includes the current compartment ledger\n   * head under `chunk.ledgerHead`. The value is identical across every\n   * chunk in a single export (one ledger per compartment). Forward-\n   * compatible with future partition work where the head would become\n   * per-partition. Default: `false`.\n   */\n  readonly withLedgerHead?: boolean\n  /**\n   * When set to a BCP 47 locale string (e.g. `'th'`), `exportJSON()`\n   * resolves all `dictKey` labels to that locale and omits the raw\n   * `dictionaries` snapshot from the output. Has no effect\n   * on `exportStream()` — format packages use the `chunk.dictionaries`\n   * snapshot directly and apply their own locale strategy.\n   *\n   * Default: `undefined` — embed the raw snapshot under `_dictionaries`.\n   */\n  readonly resolveLabels?: string\n}\n\n/**\n * One chunk yielded by `Vault.exportStream()`.\n *\n * `granularity: 'collection'` yields one chunk per collection with the\n * full record array in `records`. `granularity: 'record'` yields one\n * chunk per record with `records` containing exactly one element — the\n * `schema` and `refs` metadata is repeated on every chunk so consumers\n * doing per-record streaming don't have to thread state across yields.\n */\nexport interface ExportChunk<T = unknown> {\n  /** Collection name (no leading underscore — internal collections are filtered out). */\n  readonly collection: string\n\n  /**\n   * Standard Schema validator attached to the collection at `collection()`\n   * construction time, or `null` if no schema was provided. Surfaced so\n   * downstream serializers (`@noy-db/as-*` packages, custom\n   * exporters) can produce schema-aware output (typed CSV headers, XSD\n   * generation, etc.) without poking at collection internals.\n   */\n  readonly schema: StandardSchemaV1<unknown, T> | null\n\n  /**\n   * Foreign-key references declared on the collection via the `refs`\n   * option, as the `{ field → { target, mode } }` map produced by\n   * `RefRegistry.getOutbound`. Empty object when no refs were declared.\n   */\n  readonly refs: Record<string, { readonly target: string; readonly mode: 'strict' | 'warn' | 'cascade' }>\n\n  /**\n   * Decrypted, ACL-scoped, schema-validated records. Length 1 in\n   * `granularity: 'record'` mode, full collection in `granularity: 'collection'`\n   * mode. Records are returned by reference from the collection's eager\n   * cache where applicable — consumers must treat them as immutable.\n   */\n  readonly records: T[]\n\n  /**\n   * Dictionary snapshots for every `dictKey` field declared on this\n   * collection. Captured once at stream-start and held\n   * constant across all chunks within the same export — a rename\n   * mid-export does not change the snapshot. `undefined` when the\n   * collection has no `dictKeyFields`.\n   *\n   * Shape: `{ [fieldName]: { [stableKey]: { [locale]: label } } }`\n   *\n   * @example\n   * ```ts\n   * chunk.dictionaries?.status?.paid?.th  // → 'ชำระแล้ว'\n   * ```\n   */\n  readonly dictionaries?: Record<\n    string, // field name\n    Record<string, Record<string, string>> // stable key → locale → label\n  >\n\n  /**\n   * Vault ledger head at export time. Present only when\n   * `exportStream({ withLedgerHead: true })` was called. Identical\n   * across every chunk in the same export — included on every chunk\n   * for forward-compatibility with future per-partition ledgers, where\n   * the value will differ per chunk.\n   */\n  readonly ledgerHead?: {\n    readonly hash: string\n    readonly index: number\n    readonly ts: string\n  }\n}\n\n// ─── Sync ──────────────────────────────────────────────────────────────\n\nexport interface DirtyEntry {\n  readonly vault: string\n  readonly collection: string\n  readonly id: string\n  readonly action: 'put' | 'delete'\n  readonly version: number\n  readonly timestamp: string\n}\n\nexport interface SyncMetadata {\n  readonly _noydb_sync: typeof NOYDB_SYNC_VERSION\n  readonly last_push: string | null\n  readonly last_pull: string | null\n  readonly dirty: DirtyEntry[]\n}\n\nexport interface Conflict {\n  readonly vault: string\n  readonly collection: string\n  readonly id: string\n  readonly local: EncryptedEnvelope\n  readonly remote: EncryptedEnvelope\n  readonly localVersion: number\n  readonly remoteVersion: number\n  /**\n   * Present only when the collection uses `conflictPolicy: 'manual'`.\n   * Call `resolve(winner)` to commit the winning envelope, or\n   * `resolve(null)` to defer (conflict stays queued for the next sync).\n   * Called synchronously inside the `sync:conflict` event handler.\n   */\n  readonly resolve?: (winner: EncryptedEnvelope | null) => void\n}\n\nexport type ConflictStrategy =\n  | 'local-wins'\n  | 'remote-wins'\n  | 'version'\n  | ((conflict: Conflict) => 'local' | 'remote')\n\n/**\n * Collection-level conflict policy.\n * Overrides the db-level `conflict` option for the specific collection.\n *\n * - `'last-writer-wins'` — higher `_ts` wins (timestamp LWW).\n * - `'first-writer-wins'` — lower `_v` wins (earlier version is preserved).\n * - `'manual'` — emits `sync:conflict` with a `resolve` callback. Call\n *   `resolve(winner)` synchronously to commit or `resolve(null)` to defer.\n * - Custom fn — synchronous `(local: T, remote: T) => T`. Must be pure.\n */\nexport type ConflictPolicy<T> =\n  | 'last-writer-wins'\n  | 'first-writer-wins'\n  | 'manual'\n  | ((local: T, remote: T) => T)\n\n/**\n * Envelope-level resolver registered per collection with the SyncEngine.\n * Receives the `id` of the conflicting record and both envelopes.\n * Returns the winning envelope, or `null` to defer resolution.\n * @internal\n */\nexport type CollectionConflictResolver = (\n  id: string,\n  local: EncryptedEnvelope,\n  remote: EncryptedEnvelope,\n) => Promise<EncryptedEnvelope | null>\n\n/** Options for targeted push operations. */\nexport interface PushOptions {\n  /** Only push records belonging to these collections. Omit to push all dirty. */\n  collections?: string[]\n}\n\n/** Options for targeted pull operations. */\nexport interface PullOptions {\n  /** Only pull these collections. Omit to pull all. */\n  collections?: string[]\n  /**\n   * Only pull records with `_ts` strictly after this ISO timestamp.\n   * Adapters that implement `listSince` use it directly; others fall back\n   * to a full scan with client-side filtering.\n   */\n  modifiedSince?: string\n}\n\nexport interface PushResult {\n  readonly pushed: number\n  readonly conflicts: Conflict[]\n  readonly errors: Error[]\n}\n\nexport interface PullResult {\n  readonly pulled: number\n  readonly conflicts: Conflict[]\n  readonly errors: Error[]\n}\n\n/** Result of a sync transaction commit. */\nexport interface SyncTransactionResult {\n  readonly status: 'committed' | 'conflict'\n  readonly pushed: number\n  readonly conflicts: Conflict[]\n}\n\nexport interface SyncStatus {\n  readonly dirty: number\n  readonly lastPush: string | null\n  readonly lastPull: string | null\n  readonly online: boolean\n}\n\n// ─── Sync Target ─────────────────────────────────────────\n\nexport type SyncTargetRole = 'sync-peer' | 'backup' | 'archive'\n\n/**\n * A sync target with role and optional per-target policy.\n *\n * | Role        | Direction     | Conflict resolution | Typical use              |\n * |-------------|---------------|---------------------|--------------------------|\n * | `sync-peer` | Bidirectional | ConflictStrategy    | DynamoDB live sync       |\n * | `backup`    | Push-only     | N/A (receives merged)| S3 dump, Google Drive   |\n * | `archive`   | Push-only     | N/A                 | IPFS, Git tags, S3 Lock  |\n */\nexport interface SyncTarget {\n  /** The store to sync with. */\n  readonly store: NoydbStore\n  /** Role determines sync direction and conflict handling. */\n  readonly role: SyncTargetRole\n  /** Per-target sync policy. Inherits store-category default when absent. */\n  readonly policy?: SyncPolicy\n  /** Human-readable label for DevTools and audit logs. */\n  readonly label?: string\n}\n\n// ─── Events ────────────────────────────────────────────────────────────\n\nexport interface ChangeEvent {\n  readonly vault: string\n  readonly collection: string\n  readonly id: string\n  readonly action: 'put' | 'delete'\n}\n\nexport interface NoydbEventMap {\n  'change': ChangeEvent\n  'error': Error\n  'sync:push': PushResult\n  'sync:pull': PullResult\n  'sync:conflict': Conflict\n  'sync:online': void\n  'sync:offline': void\n  'sync:backup-error': { vault: string; target: string; error: Error }\n  'history:save': { vault: string; collection: string; id: string; version: number }\n  'history:prune': { vault: string; collection: string; id: string; pruned: number }\n  /**\n   * Emitted when a persisted-index side-car put/delete fails after the\n   * main record write already succeeded. The main record is durable; the\n   * index mirror may have drifted. Operators reconcile via\n   * `collection.reconcileIndex(field)`.\n   */\n  'index:write-partial': {\n    vault: string\n    collection: string\n    id: string\n    action: 'put' | 'delete'\n    error: Error\n  }\n  /**\n   * emitted by `Collection.ensurePersistedIndexesLoaded()`\n   * once per field on first lazy-mode query when\n   * `reconcileOnOpen: 'auto' | 'dry-run'` is configured. `applied` is\n   * `0` in `'dry-run'` mode. `skipped` is reserved for a future\n   * drift-stamp optimization that short-circuits the reconcile when\n   * the mirror version matches what's on disk — currently always\n   * `false` (the full reconcile runs every session).\n   */\n  'index:reconciled': {\n    vault: string\n    collection: string\n    field: string\n    missing: readonly string[]\n    stale: readonly string[]\n    applied: number\n    skipped: boolean\n  }\n}\n\n// ─── Grant / Revoke ────────────────────────────────────────────────────\n\nexport interface GrantOptions {\n  readonly userId: string\n  readonly displayName: string\n  readonly role: Role\n  readonly passphrase: string\n  readonly permissions?: Permissions\n  /**\n   * Optional `@noy-db/as-*` export capability. Omit or\n   * leave undefined to apply role-based defaults (see\n   * `hasExportCapability` and `ExportCapability`).\n   */\n  readonly exportCapability?: ExportCapability\n  /**\n   * Optional `@noy-db/as-*` import capability (issue ). Omit or\n   * leave undefined for default-closed semantics — no plaintext format\n   * is grantable until positively listed; bundle import is denied.\n   */\n  readonly importCapability?: ImportCapability\n}\n\nexport interface RevokeOptions {\n  readonly userId: string\n  readonly rotateKeys?: boolean\n\n  /**\n   * Cascade behavior when the revoked user is an admin who has granted\n   * other admins.\n   *\n   * - `'strict'` (default) — recursively revoke every admin that the\n   *   target (transitively) granted. The cascade walks the\n   *   `granted_by` field on each keyring file and stops at non-admin\n   *   leaves. All affected collections are accumulated and rotated in\n   *   a single pass at the end, so cascade cost is O(records in\n   *   affected collections), not O(records × cascade depth).\n   *\n   * - `'warn'` — leave the descendant admins in place but emit a\n   *   `console.warn` listing them. Useful for diagnostic dry runs and\n   *   for environments where the operator wants to clean up the\n   *   delegation tree manually.\n   *\n   * No effect when the target is not an admin (operators, viewers, and\n   * clients cannot grant other users, so they have no delegation\n   * subtree to cascade through). Defaults to `'strict'`.\n   */\n  readonly cascade?: 'strict' | 'warn'\n}\n\n// ─── Cross-vault queries ──────────────────────────────\n\n/**\n * One entry returned by `Noydb.listAccessibleVaults()`. Carries\n * the compartment id and the role the calling principal holds in it,\n * so the consumer can decide how to fan out without re-checking\n * permissions per vault.\n */\nexport interface AccessibleVault {\n  readonly id: string\n  readonly role: Role\n}\n\n/**\n * Options for `Noydb.listAccessibleVaults()`.\n */\nexport interface ListAccessibleVaultsOptions {\n  /**\n   * Minimum role the caller must hold to include a compartment in the\n   * result. Compartments where the caller's role is strictly *below*\n   * this threshold are silently excluded. Defaults to `'client'`,\n   * which means \"every vault I can unwrap is returned.\" Set to\n   * `'admin'` for \"vaults where I can grant/revoke,\" or\n   * `'owner'` for \"vaults I own.\"\n   *\n   * The privilege ordering used:\n   *   `client (1) < viewer (2) < operator (3) < admin (4) < owner (5)`\n   *\n   * Note: `viewer` and `client` are conceptually peers in the ACL\n   * (neither can grant), but `viewer` has read-all access while\n   * `client` has only explicit-collection read. The numeric order\n   * reflects \"how much can this principal see,\" not \"how much can\n   * this principal modify.\"\n   */\n  readonly minRole?: Role\n}\n\n/**\n * Options for `Noydb.queryAcross()`.\n */\nexport interface QueryAcrossOptions {\n  /**\n   * Maximum number of compartments to process in parallel. Defaults\n   * to `1` (sequential) — conservative because the per-compartment\n   * callback typically does its own I/O and an unbounded fan-out can\n   * exhaust adapter connections (DynamoDB throughput, S3 socket\n   * limits, browser fetch concurrency).\n   *\n   * Set to `4` or `8` for cloud-backed compartments where parallelism\n   * is the whole point of fanning out. Set to `1` (default) for local\n   * adapters where the disk I/O serializes anyway.\n   */\n  readonly concurrency?: number\n}\n\n/**\n * One entry in the array returned by `Noydb.queryAcross()`. Either\n * `result` is set (callback succeeded for this compartment) or\n * `error` is set (callback threw, or compartment failed to open).\n *\n * Per-compartment errors do **not** abort the overall fan-out — every\n * compartment is given a chance to run its callback, and the\n * partition between success and failure is exposed in the return\n * value. Consumers that want fail-fast semantics can check\n * `r.error !== undefined` and short-circuit themselves.\n */\nexport type QueryAcrossResult<T> =\n  | { readonly vault: string; readonly result: T; readonly error?: undefined }\n  | { readonly vault: string; readonly result?: undefined; readonly error: Error }\n\n// ─── User Info ─────────────────────────────────────────────────────────\n\nexport interface UserInfo {\n  readonly userId: string\n  readonly displayName: string\n  readonly role: Role\n  readonly permissions: Permissions\n  readonly createdAt: string\n  readonly grantedBy: string\n}\n\n// ─── Session ───────────────────────────────────────────────\n\n/**\n * Operations that a session policy can require re-authentication for.\n * Passed as the `requireReAuthFor` array in `SessionPolicy`.\n */\nexport type ReAuthOperation = 'export' | 'grant' | 'revoke' | 'rotate' | 'changeSecret'\n\n/**\n * Session policy controlling lifetime, re-auth requirements, and\n * background-lock behavior.\n *\n * All timeout values are in milliseconds. `undefined` means \"no limit.\"\n * The policy is evaluated lazily — it does not start timers itself;\n * enforcement happens at the Noydb call site.\n */\nexport interface SessionPolicy {\n  /**\n   * Idle timeout in ms. If no NOYDB operation is performed for this\n   * duration, the session is revoked on the next operation attempt\n   * (which will throw `SessionExpiredError`). The idle clock resets\n   * on every successful operation.\n   *\n   * Default: `undefined` (no idle timeout).\n   */\n  readonly idleTimeoutMs?: number\n\n  /**\n   * Absolute timeout in ms from session creation. After this duration\n   * the session is unconditionally revoked regardless of activity.\n   *\n   * Default: `undefined` (no absolute timeout).\n   */\n  readonly absoluteTimeoutMs?: number\n\n  /**\n   * Operations that require the user to re-authenticate (re-enter their\n   * passphrase or perform a fresh WebAuthn assertion) before proceeding,\n   * even if the session is still alive.\n   *\n   * Common pattern: `requireReAuthFor: ['export', 'grant']` — allow\n   * read/write operations in the background but demand a fresh credential\n   * for high-risk mutations.\n   *\n   * Default: `[]` (no extra re-auth requirements).\n   */\n  readonly requireReAuthFor?: readonly ReAuthOperation[]\n\n  /**\n   * If `true`, the session is revoked when the page goes to the background\n   * (visibilitychange event, `document.hidden === true`). Useful for\n   * high-sensitivity deployments where leaving the tab is treated as\n   * a session boundary.\n   *\n   * No-op in non-browser environments (Node.js, workers without document).\n   * Default: `false`.\n   */\n  readonly lockOnBackground?: boolean\n}\n\n// ─── i18n / Locale ─────────────────────────────────────\n\n/**\n * Locale-aware read options. Pass to `Collection.get()`, `list()`,\n * `query()`, and `scan()` to trigger per-record locale resolution for\n * `dictKey` and `i18nText` fields.\n *\n * - **`locale: 'raw'`** — skip resolution for `i18nText` fields and\n *   return the full `{ [locale]: string }` map. Dict key fields still\n *   return the stable key (no `<field>Label` added).\n * - **`fallback`** — single locale code or ordered list. Use `'any'` as\n *   the last element to fall back to any present translation.\n *\n * When neither the call-level locale nor the compartment's default locale\n * is set, reading a record with `i18nText` fields throws\n * `LocaleNotSpecifiedError`.\n */\nexport interface LocaleReadOptions {\n  /**\n   * The target locale code (e.g. `'th'`), or `'raw'` to return the full\n   * language map without resolution.\n   */\n  readonly locale?: string\n  /**\n   * Fallback locale or ordered fallback chain. Use `'any'` as the last\n   * element to fall back to any present translation.\n   */\n  readonly fallback?: string | readonly string[]\n}\n\n// ─── plaintextTranslator hook ──────────────────────────────\n\n/**\n * Context passed to the consumer-supplied `plaintextTranslator` function.\n * The hook receives the source text plus enough metadata to route it to the\n * right translation service and record what it did.\n */\nexport interface PlaintextTranslatorContext {\n  /** The plaintext string to translate. */\n  readonly text: string\n  /** BCP 47 source locale (the locale the text is written in). */\n  readonly from: string\n  /** BCP 47 target locale to translate into. */\n  readonly to: string\n  /** The schema field name that triggered the translation. */\n  readonly field: string\n  /** The collection the record is being put into. */\n  readonly collection: string\n}\n\n/**\n * A consumer-supplied async function that translates a single string\n * from one locale to another. noy-db ships no built-in translator.\n *\n * **Security:** this function receives plaintext. The consumer is\n * responsible for the data policy of whatever service it calls. See\n * `NOYDB_SPEC.md § Zero-Knowledge Storage` and the `plaintextTranslator`\n * JSDoc on `NoydbOptions` for the full invariant statement.\n */\nexport type PlaintextTranslatorFn = (\n  ctx: PlaintextTranslatorContext,\n) => Promise<string>\n\n/**\n * One entry in the in-process translator audit log. Cleared when\n * `db.close()` is called — same lifetime as the KEK and DEKs.\n *\n * Deliberately omits any content hash or translated-text fingerprint\n * to prevent correlation attacks on the audit trail.\n */\nexport interface TranslatorAuditEntry {\n  readonly type: 'translator-invocation'\n  /** Schema field name that was translated. */\n  readonly field: string\n  /** Collection the record belongs to. */\n  readonly collection: string\n  /** Source locale. */\n  readonly fromLocale: string\n  /** Target locale. */\n  readonly toLocale: string\n  /**\n   * Consumer-provided translator name from\n   * `NoydbOptions.plaintextTranslatorName`. Defaults to `'anonymous'`\n   * when not supplied.\n   */\n  readonly translatorName: string\n  /** ISO 8601 timestamp of the invocation. */\n  readonly timestamp: string\n  /**\n   * `true` when the result was served from the in-process cache rather\n   * than by calling the translator function. Present only on cache hits\n   * so the absence of the field also communicates a cache miss.\n   */\n  readonly cached?: true\n}\n\n// ─── Presence ─────────────────────────────────────────────\n\n/**\n * A presence peer entry. `lastSeen` is an ISO timestamp set by core on each\n * `update()` call. Stale entries (lastSeen older than `staleMs`) are filtered\n * before delivering to the subscriber callback.\n */\nexport interface PresencePeer<P> {\n  readonly userId: string\n  readonly payload: P\n  readonly lastSeen: string\n}\n\n// ─── CRDT ─────────────────────────────────────────────────\n\n// Re-exported from crdt.ts so consumers only need one import path.\nexport type { CrdtMode, CrdtState, LwwMapState, RgaState, YjsState } from './crdt/crdt.js'\n\n// ─── Blob / Attachment Store ────────────────────────\n\n/**\n * Second store shape for blob-store backends (Drive, WebDAV, Git, iCloud)\n * that operate on whole-vault bundles rather than per-record KV.\n *\n * Implement `readBundle` / `writeBundle` instead of the six-method KV\n * contract. Use `wrapBundleStore()` from `@noy-db/hub` to convert to a\n * `NoydbStore` that the rest of the API consumes transparently.\n *\n * Named `NoydbBundleStore` (not `NoydbBundleAdapter`) for consistency\n * with the hub / to-* / in-* rename. Concrete implementations ship\n * in `@noy-db/to-*` packages starting in.\n */\nexport interface NoydbBundleStore {\n  /** Discriminant for engine auto-detection of store shape. */\n  readonly kind: 'bundle'\n  /** Human-readable name for diagnostics (e.g. `'drive'`, `'webdav'`). */\n  readonly name?: string\n  /**\n   * Read the entire vault as raw bytes. Returns `null` if no bundle exists\n   * yet (first open of a brand-new vault).\n   */\n  readBundle(vaultId: string): Promise<{ bytes: Uint8Array; version: string } | null>\n  /**\n   * Write the entire vault as raw bytes. `expectedVersion` is the version\n   * token from the last `readBundle` (or `null` for a first write).\n   * Implementations MUST reject the write if the stored version has advanced\n   * past `expectedVersion` — throw `BundleVersionConflictError`.\n   * Returns the new version token on success.\n   */\n  writeBundle(\n    vaultId: string,\n    bytes: Uint8Array,\n    expectedVersion: string | null,\n  ): Promise<{ version: string }>\n  /** Delete a vault bundle. Idempotent — no-op if the bundle does not exist. */\n  deleteBundle(vaultId: string): Promise<void>\n  /** List all vault bundles managed by this store. */\n  listBundles(): Promise<Array<{ vaultId: string; version: string; size: number }>>\n}\n\n/**\n * Content-addressed blob object stored in the vault-level blob index.\n * Identified by HMAC-SHA-256(blobDEK, plaintext) — opaque to the store.\n *\n * Shared across all collections within a vault for deduplication: two\n * records that attach identical byte content reference the same `eTag`\n * and share a single set of encrypted chunks in `_blob_chunks`.\n */\nexport interface BlobObject {\n  /** HMAC-SHA-256 hex of the original plaintext bytes, keyed by `_blob` DEK. */\n  readonly eTag: string\n  /** Original uncompressed size in bytes. */\n  readonly size: number\n  /** Compressed size in bytes (the payload that is actually encrypted and chunked). */\n  readonly compressedSize: number\n  /** Compression algorithm applied before encryption. */\n  readonly compression: 'gzip' | 'none'\n  /** Raw chunk size in bytes used at write time. Readers MUST use this value. */\n  readonly chunkSize: number\n  /** Total number of chunks written. Reader expects exactly this many. */\n  readonly chunkCount: number\n  /** MIME type if provided or auto-detected at upload time. */\n  readonly mimeType?: string\n  /** ISO timestamp of first upload. */\n  readonly createdAt: string\n  /** Live reference count — slots + published versions pointing to this blob. */\n  readonly refCount: number\n  /**\n   * Hint indicating which store holds the chunk data.\n   * Used by `routeStore` size-tiered routing: `'default'` for small blobs\n   * stored inline (e.g. DynamoDB), `'blobs'` for large blobs in the overflow\n   * store (e.g. S3). Absent when no routing is configured.\n   */\n  readonly storeHint?: 'default' | 'blobs'\n}\n\n// ─── Attachment types ─────────────────────────────────────────\n\n/** Single attachment metadata entry stored inside a record's attachment envelope. */\nexport interface AttachmentEntry {\n  /** Content-addressed identifier (HMAC-SHA-256 of plaintext). */\n  readonly eTag: string\n  /** User-visible filename for the slot. */\n  readonly filename: string\n  /** Original uncompressed size in bytes. */\n  readonly size: number\n  /** MIME type, if provided or auto-detected at upload time. */\n  readonly mimeType?: string\n  /** ISO timestamp of the upload. */\n  readonly uploadedAt: string\n  /** User ID of the uploader, if available. */\n  readonly uploadedBy?: string\n}\n\n/** Attachment entry annotated with its slot name, as returned by `AttachmentHandle.list()`. */\nexport type AttachmentInfo = AttachmentEntry & { readonly name: string }\n\n/** Options for `AttachmentHandle.put()`. */\nexport interface AttachmentPutOptions {\n  /** Compress the attachment with gzip before encryption. Default: `true`. */\n  compress?: boolean\n  /** Chunk size in bytes. Default: `DEFAULT_CHUNK_SIZE` (256 KB). */\n  chunkSize?: number\n  /** MIME type to store with the attachment. Auto-detected from magic bytes if omitted. */\n  mimeType?: string\n  /** User ID to record as the uploader. Falls back to the active user's ID. */\n  uploadedBy?: string\n}\n\n/** Options for `AttachmentHandle.response()`. */\nexport interface AttachmentResponseOptions {\n  /**\n   * Set `Content-Disposition: inline` so the browser renders the file\n   * instead of downloading it. Default: `false` (attachment disposition).\n   */\n  inline?: boolean\n}\n\n/**\n * Slot record — mutable metadata linking a named slot on a record\n * to a `BlobObject` via its eTag.\n *\n * Multiple slots (even across different records) may reference the same\n * `eTag` — the underlying chunks are shared. Updating metadata creates\n * a new envelope version (`_v++`) while the blob data is unchanged.\n */\nexport interface SlotRecord {\n  /** Reference to the `BlobObject` in `_blob_index`. */\n  readonly eTag: string\n  /** User-visible filename for the slot. */\n  readonly filename: string\n  /** Original uncompressed size in bytes (denormalized from `BlobObject`). */\n  readonly size: number\n  /** MIME type. Takes precedence over the MIME type stored in `BlobObject`. */\n  readonly mimeType?: string\n  /** ISO timestamp of the upload that set this slot. */\n  readonly uploadedAt: string\n  /** User ID of the uploader, if available. */\n  readonly uploadedBy?: string\n}\n\n/** Result of `BlobSet.list()` — slot record plus its named slot key. */\nexport interface SlotInfo extends SlotRecord {\n  /** The slot name (key in the record's slot map). */\n  readonly name: string\n}\n\n/**\n * Explicitly published version snapshot — an independent reference to a\n * blob at a specific point in time.\n */\nexport interface VersionRecord {\n  /** User-defined label (e.g. `'issued-2025-01'`, `'amendment-2025-02'`). */\n  readonly label: string\n  /** eTag of the blob snapshot at publish time — independent of the current slot. */\n  readonly eTag: string\n  /** ISO timestamp when the version was published. */\n  readonly publishedAt: string\n  /** User ID of the publisher, if available. */\n  readonly publishedBy?: string\n}\n\n/** Options for `BlobSet.put()`. */\nexport interface BlobPutOptions {\n  /** MIME type hint. If omitted, auto-detected from magic bytes. */\n  mimeType?: string\n  /**\n   * Raw chunk size in bytes. Priority: this value > store.maxBlobBytes > 256 KB.\n   */\n  chunkSize?: number\n  /**\n   * Whether to gzip-compress bytes before encrypting. Default: `true`.\n   * Auto-set to `false` for pre-compressed MIME types (JPEG, PNG, ZIP, etc.).\n   */\n  compress?: boolean\n  /** User ID to record as `uploadedBy`. Defaults to the Noydb session user. */\n  uploadedBy?: string\n}\n\n/** Options for `BlobSet.response()` and `BlobSet.responseVersion()`. */\nexport interface BlobResponseOptions {\n  /**\n   * When `true`, sets `Content-Disposition: inline; filename=\"...\"` so\n   * the browser renders the file in the tab. Default (`false`) sets\n   * `attachment; filename=\"...\"` which triggers a download.\n   */\n  inline?: boolean\n  /** Override the filename in the Content-Disposition header. */\n  filename?: string\n}\n\n// ─── Store Capabilities ─────────────────────────────\n\nexport type StoreAuthKind =\n  | 'none'\n  | 'filesystem'\n  | 'api-key'\n  | 'iam'\n  | 'oauth'\n  | 'kerberos'\n  | 'browser-origin'\n\nexport interface StoreAuth {\n  kind: StoreAuthKind | StoreAuthKind[]\n  required: boolean\n  flow: 'static' | 'oauth' | 'kerberos' | 'implicit'\n}\n\nexport interface StoreCapabilities {\n  /**\n   * true — the store's expectedVersion check and write are atomic at the\n   * storage layer. Two concurrent puts with the same expectedVersion will\n   * produce exactly one success and one ConflictError.\n   * false — check and write are separate operations with a race window.\n   */\n  casAtomic: boolean\n  auth: StoreAuth\n  /**\n   * true — the store implements {@link NoydbStore.tx} and commits\n   * every op atomically at the storage layer. The hub's\n   * `db.transaction(fn)` will delegate to `tx(ops)` and surface a\n   * single pass/fail outcome. false (or absent) — no native\n   * multi-record atomicity; the hub falls back to per-record OCC\n   * with best-effort unwind on partial failure.\n   */\n  txAtomic?: boolean\n  /**\n   * Maximum raw bytes per blob chunk record.\n   * `undefined` — no limit (S3, file, IDB); blob stored as single chunk.\n   * `256 * 1024` — DynamoDB (400 KB item limit minus envelope overhead).\n   * `5 * 1024 * 1024` — localStorage quota safety.\n   */\n  maxBlobBytes?: number\n}\n\n// ─── Factory Options ───────────────────────────────────────────────────\n\nexport interface NoydbOptions {\n  /** Primary store (local storage). */\n  readonly store: NoydbStore\n  /**\n   * tree-shake seam — optional blob strategy. Pass `withBlobs()`\n   * from `@noy-db/hub/blobs` to enable `collection.blob(id)` storage.\n   * When omitted, hub's blob machinery stays out of the bundle (ESM\n   * tree-shaking) and `collection.blob(id)` throws with a pointer at\n   * the subpath. `BlobStrategy` is `@internal` — users only construct\n   * it via the subpath factory.\n   *\n   * @internal\n   */\n  readonly blobStrategy?: BlobStrategy\n  /**\n   * tree-shake seam — optional indexing strategy. Pass\n   * `withIndexing()` from `@noy-db/hub/indexing` to enable eager-mode\n   * `==/in` fast-paths, lazy-mode `.lazyQuery()`, rebuild/reconcile,\n   * and auto-reconcile. When omitted, indexing code never reaches the\n   * bundle; `.lazyQuery()` throws with a pointer at the subpath, and\n   * eager-mode collections fall back to linear scans regardless of\n   * `indexes: [...]` declarations. `IndexStrategy` is `@internal` —\n   * users only construct it via the subpath factory.\n   *\n   * @internal\n   */\n  readonly indexStrategy?: IndexStrategy\n  /**\n   * tree-shake seam — optional aggregate strategy. Pass\n   * `withAggregate()` from `@noy-db/hub/aggregate` to enable\n   * `.aggregate()` and `.groupBy()` on Query. When omitted, those\n   * methods throw with a pointer at the subpath; the ~886 LOC of\n   * Aggregation + GroupedQuery machinery never reaches the bundle.\n   * Streaming `scan().aggregate()` works independently of this\n   * strategy — it doesn't use the `Aggregation` class.\n   *\n   * @internal\n   */\n  readonly aggregateStrategy?: AggregateStrategy\n  /**\n   * tree-shake seam — optional CRDT strategy. Required when\n   * any collection is declared with `crdt: 'lww-map' | 'rga' | 'yjs'`;\n   * otherwise the first put/sync-merge hitting the CRDT path throws.\n   * When omitted, ~221 LOC of LWW-Map / RGA / merge helpers never\n   * reach the bundle.\n   *\n   * @internal\n   */\n  readonly crdtStrategy?: CrdtStrategy\n  /**\n   * tree-shake seam — optional consent-audit strategy. Pass\n   * `withConsent()` from `@noy-db/hub/consent` to enable per-op audit\n   * writes into `_consent_audit` when a consent scope is active.\n   * When omitted, `vault.consentAudit()` returns `[]` and writes are\n   * no-ops; the consent module's ~194 LOC never reaches the bundle.\n   *\n   * @internal\n   */\n  readonly consentStrategy?: ConsentStrategy\n  /**\n   * tree-shake seam — optional periods strategy. Pass\n   * `withPeriods()` from `@noy-db/hub/periods` to enable\n   * `vault.closePeriod()` / `.openPeriod()` / write-guard on closed\n   * periods. When omitted, `vault.listPeriods()` returns `[]` and\n   * the write-guard is a no-op; the ~363 LOC of period validation +\n   * ledger appending stay out of the bundle.\n   *\n   * @internal\n   */\n  readonly periodsStrategy?: PeriodsStrategy\n  /**\n   * tree-shake seam — optional VaultFrame strategy. Pass\n   * `withShadow()` from `@noy-db/hub/shadow` to enable\n   * `vault.frame()`. Without it, calling `vault.frame()` throws.\n   *\n   * @internal\n   */\n  readonly shadowStrategy?: ShadowStrategy\n  /**\n   * tree-shake seam — optional multi-record transactions. Pass\n   * `withTransactions()` from `@noy-db/hub/tx` to enable\n   * `db.transaction(fn)`. Without it, calling the method throws.\n   *\n   * @internal\n   */\n  readonly txStrategy?: TxStrategy\n  /**\n   * tree-shake seam — optional history + ledger + time-machine.\n   * Pass `withHistory()` from `@noy-db/hub/history` to enable\n   * per-record version snapshots, the hash-chained audit ledger, JSON\n   * Patch deltas, `vault.ledger()`, `vault.at()`, and the\n   * `collection.history()` / `getVersion()` / `revert()` / `diff()` /\n   * `clearHistory()` / `pruneRecordHistory()` read APIs. When omitted,\n   * snapshots/prune/clear are silent no-ops, the read APIs throw with\n   * a pointer at the subpath, and ~1,880 LOC stay out of the bundle.\n   *\n   * @internal\n   */\n  readonly historyStrategy?: HistoryStrategy\n  /**\n   * tree-shake seam — optional i18n strategy. Pass `withI18n()`\n   * from `@noy-db/hub/i18n` to enable `i18nText`/`dictKey` field\n   * resolution on reads, `i18nText` validation on writes, and\n   * `vault.dictionary(name)`. When omitted, locale resolution is the\n   * identity (raw values returned), the validators throw with a\n   * pointer to the subpath, and ~854 LOC of dictionary + locale\n   * machinery stay out of the bundle.\n   *\n   * @internal\n   */\n  readonly i18nStrategy?: I18nStrategy\n  /**\n   * tree-shake seam — optional session-policy strategy. Pass\n   * `withSession()` from `@noy-db/hub/session` to enable\n   * `sessionPolicy` validation, `PolicyEnforcer` lifecycle (idle /\n   * absolute timeouts, lockOnBackground), and global session-token\n   * revocation. When omitted, setting `sessionPolicy` throws at\n   * `createNoydb()` time, and ~495 LOC of policy + token machinery\n   * stay out of the bundle.\n   *\n   * @internal\n   */\n  readonly sessionStrategy?: SessionStrategy\n  /**\n   * tree-shake seam — optional sync engine + presence strategy.\n   * Pass `withSync()` from `@noy-db/hub/sync` to enable\n   * `db.push()` / `pull()` / replication, `db.transaction(vault)`\n   * for sync-aware transactions, and `collection.presence()`. When\n   * omitted, configuring `sync` / calling these surfaces throws with\n   * a pointer at the subpath, and ~856 LOC of replication + presence\n   * machinery stay out of the bundle. Keyring stays core; grant/\n   * revoke/magic-link/delegation tree-shake via direct imports.\n   *\n   * @internal\n   */\n  readonly syncStrategy?: SyncStrategy\n  /** Optional remote store(s) for sync. Accepts a single store, a SyncTarget, or an array. */\n  readonly sync?: NoydbStore | SyncTarget | SyncTarget[]\n  /** User identifier. */\n  readonly user: string\n  /** Passphrase for key derivation. Required unless encrypt is false. */\n  readonly secret?: string\n  /** Auth method. Default: 'passphrase'. */\n  readonly auth?: 'passphrase' | 'biometric'\n  /** Enable encryption. Default: true. */\n  readonly encrypt?: boolean\n  /** Conflict resolution strategy. Default: 'version'. */\n  readonly conflict?: ConflictStrategy\n  /**\n   * Sync scheduling policy. Controls when push/pull fire.\n   * Default inferred from store category: per-record → `on-change`,\n   * bundle → `debounce 30s`.\n   */\n  readonly syncPolicy?: SyncPolicy\n  /**\n   * @deprecated Use `syncPolicy` instead. Kept for backward compatibility.\n   * When both are supplied, `syncPolicy` takes precedence.\n   */\n  readonly autoSync?: boolean\n  /**\n   * @deprecated Use `syncPolicy` instead. Kept for backward compatibility.\n   */\n  readonly syncInterval?: number\n  /**\n   * Session timeout in ms. Clears keys after inactivity. Default: none.\n   * @deprecated Use `sessionPolicy.idleTimeoutMs` instead. This field is\n   * still honored for backwards compatibility but `sessionPolicy` takes\n   * precedence when both are supplied.\n   */\n  readonly sessionTimeout?: number\n  /**\n   * Session policy controlling lifetime, re-auth requirements, and\n   * background-lock behavior. When supplied, replaces the\n   * legacy `sessionTimeout` field.\n   */\n  readonly sessionPolicy?: SessionPolicy\n  /** Validate passphrase strength on creation. Default: true. */\n  readonly validatePassphrase?: boolean\n  /** Audit history configuration. */\n  readonly history?: HistoryConfig\n  /**\n   * Consumer-supplied translation function for `i18nText` fields with\n   * `autoTranslate: true`.\n   *\n   * ⚠ **`plaintextTranslator` receives unencrypted text.** Configuring\n   * this hook causes plaintext to leave noy-db's zero-knowledge boundary\n   * over whatever channel the consumer's implementation uses. noy-db ships\n   * no built-in translator and adds no translator SDKs as dependencies.\n   * The consumer chooses and owns the data policy of the external service.\n   *\n   * Per-field opt-in via `autoTranslate: true` on `i18nText()`. Calling\n   * `put()` on a collection with `autoTranslate: true` fields while this\n   * option is absent throws `TranslatorNotConfiguredError`.\n   *\n   * See `NOYDB_SPEC.md § Zero-Knowledge Storage` for the invariant text.\n   */\n  readonly plaintextTranslator?: PlaintextTranslatorFn\n  /**\n   * Human-readable name for the translator, recorded in the in-process\n   * audit log (e.g. `'deepl-pro-with-dpa'`, `'self-hosted-llama-7b'`).\n   * Defaults to `'anonymous'` when not supplied.\n   */\n  readonly plaintextTranslatorName?: string\n}\n\n// ─── History / Audit Trail ─────────────────────────────────────────────\n\n/** History configuration. */\nexport interface HistoryConfig {\n  /** Enable history tracking. Default: true. */\n  readonly enabled?: boolean\n  /** Maximum history entries per record. Oldest pruned on overflow. Default: unlimited. */\n  readonly maxVersions?: number\n}\n\n/** Options for querying history. */\nexport interface HistoryOptions {\n  /** Start date (inclusive), ISO 8601. */\n  readonly from?: string\n  /** End date (inclusive), ISO 8601. */\n  readonly to?: string\n  /** Maximum entries to return. */\n  readonly limit?: number\n}\n\n/** Options for pruning history. */\nexport interface PruneOptions {\n  /** Keep only the N most recent versions. */\n  readonly keepVersions?: number\n  /** Delete versions older than this date, ISO 8601. */\n  readonly beforeDate?: string\n}\n\n/** A decrypted history entry. */\nexport interface HistoryEntry<T> {\n  readonly version: number\n  readonly timestamp: string\n  readonly userId: string\n  readonly record: T\n}\n\n// ─── Bulk operations ──────────────────────────────────────\n\n/** Per-item options for `Collection.putMany()`. */\nexport interface PutManyItemOptions {\n  /**\n   * Optimistic-concurrency check: fail this item if the stored version\n   * is not `expectedVersion`. Honored only in `atomic: true` mode;\n   * ignored in the default best-effort loop.\n   */\n  readonly expectedVersion?: number\n}\n\n/**\n * Batch-level options for `Collection.putMany()` and `deleteMany()`.\n *\n * `atomic: true` switches the call from best-effort loop\n * to all-or-nothing: a pre-flight CAS check runs first, then every op\n * is executed; any mid-batch failure triggers a best-effort revert.\n * On failure in atomic mode the whole call throws — you won't get a\n * partial `PutManyResult`. On success the result mirrors the default\n * loop's shape.\n */\nexport interface PutManyOptions {\n  readonly atomic?: boolean\n}\n\n/** Result of `Collection.putMany()`. */\nexport interface PutManyResult {\n  /** `true` iff every entry succeeded. */\n  readonly ok: boolean\n  /** IDs that were successfully written. */\n  readonly success: readonly string[]\n  /** Entries that failed, with the error that prevented each write. */\n  readonly failures: ReadonlyArray<{ readonly id: string; readonly error: Error }>\n}\n\n/** Result of `Collection.deleteMany()`. Same shape as `PutManyResult`. */\nexport interface DeleteManyResult {\n  readonly ok: boolean\n  readonly success: readonly string[]\n  readonly failures: ReadonlyArray<{ readonly id: string; readonly error: Error }>\n}\n"],"mappings":";AAyCO,IAAM,uBAAuB;AAG7B,IAAM,wBAAwB;AAG9B,IAAM,uBAAuB;AAG7B,IAAM,qBAAqB;AA6U3B,SAAS,YACd,SACmC;AACnC,SAAO;AACT;","names":[]}

package/dist/consent/index.cjs

@@ -0,0 +1,204 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/consent/index.ts
+var consent_exports = {};
+__export(consent_exports, {
+  CONSENT_AUDIT_COLLECTION: () => CONSENT_AUDIT_COLLECTION,
+  loadConsentEntries: () => loadConsentEntries,
+  withConsent: () => withConsent,
+  writeConsentEntry: () => writeConsentEntry
+});
+module.exports = __toCommonJS(consent_exports);
+
+// src/errors.ts
+var NoydbError = class extends Error {
+  /** Machine-readable error code. Stable across library versions. */
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "NoydbError";
+    this.code = code;
+  }
+};
+var DecryptionError = class extends NoydbError {
+  constructor(message = "Decryption failed") {
+    super("DECRYPTION_FAILED", message);
+    this.name = "DecryptionError";
+  }
+};
+var TamperedError = class extends NoydbError {
+  constructor(message = "Data integrity check failed \u2014 record may have been tampered with") {
+    super("TAMPERED", message);
+    this.name = "TamperedError";
+  }
+};
+
+// src/crypto.ts
+var IV_BYTES = 12;
+var subtle = globalThis.crypto.subtle;
+async function encrypt(plaintext, dek) {
+  const iv = generateIV();
+  const encoded = new TextEncoder().encode(plaintext);
+  const ciphertext = await subtle.encrypt(
+    { name: "AES-GCM", iv },
+    dek,
+    encoded
+  );
+  return {
+    iv: bufferToBase64(iv),
+    data: bufferToBase64(ciphertext)
+  };
+}
+async function decrypt(ivBase64, dataBase64, dek) {
+  const iv = base64ToBuffer(ivBase64);
+  const ciphertext = base64ToBuffer(dataBase64);
+  try {
+    const plaintext = await subtle.decrypt(
+      { name: "AES-GCM", iv },
+      dek,
+      ciphertext
+    );
+    return new TextDecoder().decode(plaintext);
+  } catch (err) {
+    if (err instanceof Error && err.name === "OperationError") {
+      throw new TamperedError();
+    }
+    throw new DecryptionError(
+      err instanceof Error ? err.message : "Decryption failed"
+    );
+  }
+}
+function generateIV() {
+  return globalThis.crypto.getRandomValues(new Uint8Array(IV_BYTES));
+}
+function bufferToBase64(buffer) {
+  const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+function base64ToBuffer(base64) {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+// src/bundle/ulid.ts
+var CROCKFORD_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+function encodeBase32(value, length) {
+  let out = "";
+  let v = value;
+  for (let i = 0; i < length; i++) {
+    out = CROCKFORD_ALPHABET[v % 32] + out;
+    v = Math.floor(v / 32);
+  }
+  return out;
+}
+function generateULID() {
+  const now = Date.now();
+  const timestampHigh = Math.floor(now / 16777216);
+  const timestampLow = now & 16777215;
+  const tsPart = encodeBase32(timestampHigh, 5) + encodeBase32(timestampLow, 5);
+  const randBytes = new Uint8Array(10);
+  crypto.getRandomValues(randBytes);
+  const rand1 = randBytes[0] * 2 ** 32 + (randBytes[1] << 24 >>> 0) + (randBytes[2] << 16) + (randBytes[3] << 8) + randBytes[4];
+  const rand2 = randBytes[5] * 2 ** 32 + (randBytes[6] << 24 >>> 0) + (randBytes[7] << 16) + (randBytes[8] << 8) + randBytes[9];
+  const randPart = encodeBase32(rand1, 8) + encodeBase32(rand2, 8);
+  return tsPart + randPart;
+}
+
+// src/consent/consent.ts
+var CONSENT_AUDIT_COLLECTION = "_consent_audit";
+async function writeConsentEntry(adapter, vault, encrypted, entry, getDEK) {
+  const id = generateULID();
+  const full = {
+    id,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    ...entry
+  };
+  const envelope = await buildEnvelope(full, encrypted, getDEK);
+  await adapter.put(vault, CONSENT_AUDIT_COLLECTION, id, envelope);
+}
+async function loadConsentEntries(adapter, vault, encrypted, getDEK, filter = {}) {
+  const ids = await adapter.list(vault, CONSENT_AUDIT_COLLECTION);
+  const entries = [];
+  for (const id of ids.sort()) {
+    const envelope = await adapter.get(vault, CONSENT_AUDIT_COLLECTION, id);
+    if (!envelope) continue;
+    const entry = await decryptEntry(envelope, encrypted, getDEK);
+    if (!matchesFilter(entry, filter)) continue;
+    entries.push(entry);
+  }
+  return entries;
+}
+async function buildEnvelope(entry, encrypted, getDEK) {
+  const json = JSON.stringify(entry);
+  if (!encrypted) {
+    return {
+      _noydb: 1,
+      _v: 1,
+      _ts: entry.timestamp,
+      _iv: "",
+      _data: json
+    };
+  }
+  const dek = await getDEK(CONSENT_AUDIT_COLLECTION);
+  const { iv, data } = await encrypt(json, dek);
+  return {
+    _noydb: 1,
+    _v: 1,
+    _ts: entry.timestamp,
+    _iv: iv,
+    _data: data
+  };
+}
+async function decryptEntry(envelope, encrypted, getDEK) {
+  const json = encrypted ? await decrypt(envelope._iv, envelope._data, await getDEK(CONSENT_AUDIT_COLLECTION)) : envelope._data;
+  return JSON.parse(json);
+}
+function matchesFilter(entry, f) {
+  if (f.since && entry.timestamp < f.since) return false;
+  if (f.until && entry.timestamp > f.until) return false;
+  if (f.collection && entry.collection !== f.collection) return false;
+  if (f.actor && entry.actor !== f.actor) return false;
+  if (f.purpose && entry.purpose !== f.purpose) return false;
+  return true;
+}
+
+// src/consent/active.ts
+function withConsent() {
+  return {
+    write: writeConsentEntry,
+    read: loadConsentEntries
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CONSENT_AUDIT_COLLECTION,
+  loadConsentEntries,
+  withConsent,
+  writeConsentEntry
+});
+//# sourceMappingURL=index.cjs.map

package/dist/consent/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/consent/index.ts","../../src/errors.ts","../../src/crypto.ts","../../src/bundle/ulid.ts","../../src/consent/consent.ts","../../src/consent/active.ts"],"sourcesContent":["/**\n * @noy-db/hub/consent — opt-in consent-audit subsystem.\n *\n * @category capability\n *\n * Records per-operation consent entries into a reserved\n * `_consent_audit` collection when a consent scope is active.\n * Applications that don't need GDPR-style audit trails can omit this\n * subpath and skip the ~194 LOC.\n */\n\nexport { withConsent } from './active.js'\nexport type { ConsentStrategy } from './strategy.js'\n\nexport {\n  CONSENT_AUDIT_COLLECTION,\n  writeConsentEntry,\n  loadConsentEntries,\n} from './consent.js'\nexport type {\n  ConsentContext,\n  ConsentOp,\n  ConsentAuditEntry,\n  ConsentAuditFilter,\n} from './consent.js'\n","/**\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// ─── 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 (issue ).\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// ─── 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// ─── 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// ─── 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// ─── 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 * Cryptographic primitives — thin wrappers around the Web Crypto API.\n *\n * ## Design principle\n *\n * **Zero npm crypto dependencies.** Every operation uses `globalThis.crypto.subtle`,\n * which is available natively in Node.js ≥ 18, all modern browsers, and\n * Deno/Bun. This avoids supply-chain risk from third-party crypto packages and\n * ensures the library stays auditable.\n *\n * ## Algorithms\n *\n * | Use case | Algorithm | Parameters |\n * |----------|-----------|------------|\n * | Key derivation | PBKDF2-SHA256 | 600,000 iterations, 32-byte salt |\n * | Record encryption | AES-256-GCM | 12-byte random IV per operation |\n * | DEK wrapping | AES-KW (RFC 3394) | 256-bit KEK |\n * | Binary encrypt | AES-256-GCM | same as record encryption |\n * | Integrity | HMAC-SHA256 | for presence channels |\n * | Content hash | SHA-256 | for ledger and bundle integrity |\n *\n * ## Key lifecycle\n *\n * ```\n * passphrase + salt\n *   └─► deriveKey()       → KEK (CryptoKey, extractable: false)\n *         └─► wrapKey()   → wrapped DEK bytes  [stored in keyring]\n *         └─► unwrapKey() → DEK (CryptoKey)    [memory only during session]\n *               └─► encrypt() / decrypt()       → ciphertext / plaintext\n * ```\n *\n * IVs are generated fresh by {@link generateIV} on every encrypt call.\n * Reusing an IV with the same key would break GCM's authentication guarantee —\n * this function should be the only place IVs are produced.\n *\n * @module\n */\n\nimport { DecryptionError, InvalidKeyError, TamperedError } from './errors.js'\n\nconst PBKDF2_ITERATIONS = 600_000\nconst SALT_BYTES = 32\nconst IV_BYTES = 12\nconst KEY_BITS = 256\n\nconst subtle = globalThis.crypto.subtle\n\n// ─── Key Derivation ────────────────────────────────────────────────────\n\n/** Derive a KEK from a passphrase and salt using PBKDF2-SHA256. */\nexport async function deriveKey(\n  passphrase: string,\n  salt: Uint8Array,\n): Promise<CryptoKey> {\n  const keyMaterial = await subtle.importKey(\n    'raw',\n    new TextEncoder().encode(passphrase),\n    'PBKDF2',\n    false,\n    ['deriveKey'],\n  )\n\n  return subtle.deriveKey(\n    {\n      name: 'PBKDF2',\n      salt: salt as BufferSource,\n      iterations: PBKDF2_ITERATIONS,\n      hash: 'SHA-256',\n    },\n    keyMaterial,\n    { name: 'AES-KW', length: KEY_BITS },\n    false,\n    ['wrapKey', 'unwrapKey'],\n  )\n}\n\n// ─── DEK Generation ────────────────────────────────────────────────────\n\n/** Generate a random AES-256-GCM data encryption key. */\nexport async function generateDEK(): Promise<CryptoKey> {\n  return subtle.generateKey(\n    { name: 'AES-GCM', length: KEY_BITS },\n    true, // extractable — needed for AES-KW wrapping\n    ['encrypt', 'decrypt'],\n  )\n}\n\n// ─── Key Wrapping ──────────────────────────────────────────────────────\n\n/** Wrap (encrypt) a DEK with a KEK using AES-KW. Returns base64 string. */\nexport async function wrapKey(dek: CryptoKey, kek: CryptoKey): Promise<string> {\n  const wrapped = await subtle.wrapKey('raw', dek, kek, 'AES-KW')\n  return bufferToBase64(wrapped)\n}\n\n/** Unwrap (decrypt) a DEK from base64 string using a KEK. */\nexport async function unwrapKey(\n  wrappedBase64: string,\n  kek: CryptoKey,\n): Promise<CryptoKey> {\n  try {\n    return await subtle.unwrapKey(\n      'raw',\n      base64ToBuffer(wrappedBase64) as BufferSource,\n      kek,\n      'AES-KW',\n      { name: 'AES-GCM', length: KEY_BITS },\n      true,\n      ['encrypt', 'decrypt'],\n    )\n  } catch {\n    throw new InvalidKeyError()\n  }\n}\n\n// ─── Encrypt / Decrypt ─────────────────────────────────────────────────\n\nexport interface EncryptResult {\n  iv: string   // base64\n  data: string // base64\n}\n\n/** Encrypt plaintext JSON string with AES-256-GCM. Fresh IV per call. */\nexport async function encrypt(\n  plaintext: string,\n  dek: CryptoKey,\n): Promise<EncryptResult> {\n  const iv = generateIV()\n  const encoded = new TextEncoder().encode(plaintext)\n\n  const ciphertext = await subtle.encrypt(\n    { name: 'AES-GCM', iv: iv as BufferSource },\n    dek,\n    encoded,\n  )\n\n  return {\n    iv: bufferToBase64(iv),\n    data: bufferToBase64(ciphertext),\n  }\n}\n\n/** Decrypt AES-256-GCM ciphertext. Throws on wrong key or tampered data. */\nexport async function decrypt(\n  ivBase64: string,\n  dataBase64: string,\n  dek: CryptoKey,\n): Promise<string> {\n  const iv = base64ToBuffer(ivBase64)\n  const ciphertext = base64ToBuffer(dataBase64)\n\n  try {\n    const plaintext = await subtle.decrypt(\n      { name: 'AES-GCM', iv: iv as BufferSource },\n      dek,\n      ciphertext as BufferSource,\n    )\n    return new TextDecoder().decode(plaintext)\n  } catch (err) {\n    if (err instanceof Error && err.name === 'OperationError') {\n      throw new TamperedError()\n    }\n    throw new DecryptionError(\n      err instanceof Error ? err.message : 'Decryption failed',\n    )\n  }\n}\n\n// ─── Binary Encrypt / Decrypt ────────\n\n/**\n * Encrypt raw bytes with AES-256-GCM using a fresh random IV.\n * Used by the attachment store so binary blobs avoid double base64 encoding\n * (the existing `encrypt()` function calls `TextEncoder` on a string — here\n * we pass the `Uint8Array` directly to `subtle.encrypt`).\n */\nexport async function encryptBytes(\n  data: Uint8Array,\n  dek: CryptoKey,\n): Promise<EncryptResult> {\n  const iv = generateIV()\n  const ciphertext = await subtle.encrypt(\n    { name: 'AES-GCM', iv: iv as BufferSource },\n    dek,\n    data as unknown as BufferSource,\n  )\n  return {\n    iv: bufferToBase64(iv),\n    data: bufferToBase64(ciphertext),\n  }\n}\n\n/**\n * Decrypt AES-256-GCM ciphertext back to raw bytes.\n * Counterpart to `encryptBytes`. Throws `TamperedError` on auth-tag failure.\n */\nexport async function decryptBytes(\n  ivBase64: string,\n  dataBase64: string,\n  dek: CryptoKey,\n): Promise<Uint8Array> {\n  const iv = base64ToBuffer(ivBase64)\n  const ciphertext = base64ToBuffer(dataBase64)\n  try {\n    const plaintext = await subtle.decrypt(\n      { name: 'AES-GCM', iv: iv as BufferSource },\n      dek,\n      ciphertext as BufferSource,\n    )\n    return new Uint8Array(plaintext)\n  } catch (err) {\n    if (err instanceof Error && err.name === 'OperationError') {\n      throw new TamperedError()\n    }\n    throw new DecryptionError(\n      err instanceof Error ? err.message : 'Decryption failed',\n    )\n  }\n}\n\n/**\n * SHA-256 hex digest of raw bytes. Used to derive content-addressed\n * eTags for blob deduplication. Computed on plaintext bytes\n * before compression and encryption so the eTag identifies content, not\n * ciphertext, and survives re-encryption (key rotation, re-upload).\n */\nexport async function sha256Hex(data: Uint8Array): Promise<string> {\n  const hash = await subtle.digest('SHA-256', data as unknown as BufferSource)\n  return Array.from(new Uint8Array(hash))\n    .map((b) => b.toString(16).padStart(2, '0'))\n    .join('')\n}\n\n// ─── HMAC-SHA-256 ─────────────────────────────\n\n/**\n * Compute HMAC-SHA-256(key, data) and return hex string.\n *\n * Used to derive content-addressed eTags that are opaque to the store:\n * ```\n * eTag = hmacSha256Hex(blobDEK, plaintext)\n * ```\n *\n * Unlike a plain SHA-256, the HMAC is keyed by the vault-shared `_blob` DEK,\n * so an attacker with store access cannot pre-compute eTags for known files.\n * Deduplication still works within a vault (same key + same content = same eTag).\n */\nexport async function hmacSha256Hex(key: CryptoKey, data: Uint8Array): Promise<string> {\n  // Export AES-GCM DEK raw bytes → import as HMAC key\n  const rawKey = await subtle.exportKey('raw', key)\n  const hmacKey = await subtle.importKey(\n    'raw',\n    rawKey,\n    { name: 'HMAC', hash: 'SHA-256' },\n    false,\n    ['sign'],\n  )\n  const sig = await subtle.sign('HMAC', hmacKey, data as unknown as BufferSource)\n  return Array.from(new Uint8Array(sig))\n    .map((b) => b.toString(16).padStart(2, '0'))\n    .join('')\n}\n\n// ─── AAD-aware Binary Encrypt / Decrypt ──\n\n/**\n * Encrypt raw bytes with AES-256-GCM using Additional Authenticated Data.\n *\n * The AAD binds each chunk to its parent blob and position, preventing\n * chunk reorder, substitution, and truncation attacks:\n * ```\n * AAD = UTF-8(\"{eTag}:{chunkIndex}:{chunkCount}\")\n * ```\n *\n * The AAD is NOT stored — the reader reconstructs it from `BlobObject`\n * metadata and passes it to `decryptBytesWithAAD`.\n */\nexport async function encryptBytesWithAAD(\n  data: Uint8Array,\n  dek: CryptoKey,\n  aad: Uint8Array,\n): Promise<EncryptResult> {\n  const iv = generateIV()\n  const ciphertext = await subtle.encrypt(\n    {\n      name: 'AES-GCM',\n      iv: iv as BufferSource,\n      additionalData: aad as BufferSource,\n    },\n    dek,\n    data as unknown as BufferSource,\n  )\n  return {\n    iv: bufferToBase64(iv),\n    data: bufferToBase64(ciphertext),\n  }\n}\n\n/**\n * Decrypt AES-256-GCM ciphertext with AAD verification.\n *\n * If the AAD does not match the one used at encryption time (e.g. because\n * a chunk was reordered or substituted from another blob), the GCM auth\n * tag fails and this throws `TamperedError`.\n */\nexport async function decryptBytesWithAAD(\n  ivBase64: string,\n  dataBase64: string,\n  dek: CryptoKey,\n  aad: Uint8Array,\n): Promise<Uint8Array> {\n  const iv = base64ToBuffer(ivBase64)\n  const ciphertext = base64ToBuffer(dataBase64)\n  try {\n    const plaintext = await subtle.decrypt(\n      {\n        name: 'AES-GCM',\n        iv: iv as BufferSource,\n        additionalData: aad as BufferSource,\n      },\n      dek,\n      ciphertext as BufferSource,\n    )\n    return new Uint8Array(plaintext)\n  } catch (err) {\n    if (err instanceof Error && err.name === 'OperationError') {\n      throw new TamperedError()\n    }\n    throw new DecryptionError(\n      err instanceof Error ? err.message : 'Decryption failed',\n    )\n  }\n}\n\n// ─── Presence Key Derivation ──────────────────────────────\n\n/**\n * Derive an AES-256-GCM presence key from a collection DEK using HKDF-SHA256.\n *\n * The presence key is domain-separated from the data DEK by the fixed salt\n * `'noydb-presence'` and the `info` = collection name. This means:\n *  - The adapter never sees the presence key.\n *  - Presence payloads rotate automatically when the collection DEK is rotated.\n *  - Revoked users cannot derive the new presence key after a DEK rotation.\n *\n * @param dek            The collection's AES-256-GCM DEK (extractable).\n * @param collectionName Used as the HKDF `info` parameter for domain separation.\n * @returns A non-extractable AES-256-GCM key suitable for presence payload encryption.\n */\nexport async function derivePresenceKey(dek: CryptoKey, collectionName: string): Promise<CryptoKey> {\n  // Step 1: export DEK raw bytes\n  const rawDek = await subtle.exportKey('raw', dek)\n\n  // Step 2: import as HKDF key material\n  const hkdfKey = await subtle.importKey(\n    'raw',\n    rawDek,\n    'HKDF',\n    false,\n    ['deriveBits'],\n  )\n\n  // Step 3: derive 256 bits with salt='noydb-presence' and info=collectionName\n  const salt = new TextEncoder().encode('noydb-presence')\n  const info = new TextEncoder().encode(collectionName)\n  const bits = await subtle.deriveBits(\n    { name: 'HKDF', hash: 'SHA-256', salt, info },\n    hkdfKey,\n    KEY_BITS,\n  )\n\n  // Step 4: import derived bits as AES-GCM key\n  return subtle.importKey(\n    'raw',\n    bits,\n    { name: 'AES-GCM', length: KEY_BITS },\n    false,\n    ['encrypt', 'decrypt'],\n  )\n}\n\n// ─── Deterministic Encryption ────────────────────────────\n\n/**\n * Derive a deterministic 12-byte IV from `{ DEK, context, plaintext }`\n * via HKDF-SHA256. Given the same three inputs, the IV is identical, so\n * `encryptDeterministic` produces the same ciphertext on every call —\n * which is precisely what enables blind equality search on encrypted\n * fields.\n *\n * **The side channel this opens.** Two records whose field value is the\n * same produce the same ciphertext. An observer with store access can\n * therefore tell which records share a value — not *what* the value is,\n * but the equivalence class. This is the well-known trade-off of\n * deterministic encryption and is why the feature is strictly opt-in\n * per field, guarded by `acknowledgeDeterministicRisk: true` at\n * collection creation.\n *\n * The context string MUST include the collection name and field name,\n * so:\n *   - The same plaintext in two different fields encrypts differently\n *     (no cross-field equality leak).\n *   - The same plaintext in two different collections (different DEKs)\n *     encrypts differently by virtue of the key, even before HKDF\n *     domain separation kicks in.\n */\nasync function deriveDeterministicIV(\n  dek: CryptoKey,\n  context: string,\n  plaintext: string,\n): Promise<Uint8Array> {\n  const rawDek = await subtle.exportKey('raw', dek)\n  const hkdfKey = await subtle.importKey('raw', rawDek, 'HKDF', false, ['deriveBits'])\n  const salt = new TextEncoder().encode('noydb-deterministic-v1')\n  const info = new TextEncoder().encode(`${context}\\x00${plaintext}`)\n  const bits = await subtle.deriveBits(\n    { name: 'HKDF', hash: 'SHA-256', salt, info },\n    hkdfKey,\n    IV_BYTES * 8,\n  )\n  return new Uint8Array(bits)\n}\n\n/**\n * Encrypt a plaintext string with AES-256-GCM and a deterministic,\n * HKDF-derived IV.\n *\n * The same `{ dek, context, plaintext }` triple always produces the\n * same `{ iv, data }` — call this twice and you can string-compare the\n * ciphertexts to check equality of the inputs without decrypting them.\n *\n * @param context  Domain-separation string — by convention\n *                 `'<collection>/<field>'`. Different contexts encrypt\n *                 the same plaintext to different ciphertexts, so\n *                 `email` in collection `users` does not collide with\n *                 `email` in collection `customers`.\n */\nexport async function encryptDeterministic(\n  plaintext: string,\n  dek: CryptoKey,\n  context: string,\n): Promise<EncryptResult> {\n  const iv = await deriveDeterministicIV(dek, context, plaintext)\n  const encoded = new TextEncoder().encode(plaintext)\n  const ciphertext = await subtle.encrypt(\n    { name: 'AES-GCM', iv: iv as BufferSource },\n    dek,\n    encoded,\n  )\n  return {\n    iv: bufferToBase64(iv),\n    data: bufferToBase64(ciphertext),\n  }\n}\n\n/**\n * Counterpart to {@link encryptDeterministic}. The IV is stored\n * alongside the ciphertext (exactly like the randomized path), so\n * decrypt uses the stored IV and verifies the GCM auth tag — a tampered\n * ciphertext throws `TamperedError` just like randomized AES-GCM.\n */\nexport async function decryptDeterministic(\n  ivBase64: string,\n  dataBase64: string,\n  dek: CryptoKey,\n): Promise<string> {\n  return decrypt(ivBase64, dataBase64, dek)\n}\n\n// ─── Random Generation ─────────────────────────────────────────────────\n\n/** Generate a random 12-byte IV for AES-GCM. */\nexport function generateIV(): Uint8Array {\n  return globalThis.crypto.getRandomValues(new Uint8Array(IV_BYTES))\n}\n\n/** Generate a random 32-byte salt for PBKDF2. */\nexport function generateSalt(): Uint8Array {\n  return globalThis.crypto.getRandomValues(new Uint8Array(SALT_BYTES))\n}\n\n// ─── Base64 Helpers ────────────────────────────────────────────────────\n\nexport function bufferToBase64(buffer: ArrayBuffer | Uint8Array): string {\n  const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer)\n  let binary = ''\n  for (let i = 0; i < bytes.length; i++) {\n    binary += String.fromCharCode(bytes[i]!)\n  }\n  return btoa(binary)\n}\n\nexport function base64ToBuffer(base64: string): Uint8Array<ArrayBuffer> {\n  const binary = atob(base64)\n  const bytes = new Uint8Array(binary.length)\n  for (let i = 0; i < binary.length; i++) {\n    bytes[i] = binary.charCodeAt(i)\n  }\n  return bytes\n}\n","/**\n * Minimal ULID generator — zero dependencies, Web Crypto API only.\n *\n *. Used by the bundle writer to generate stable opaque\n * handles for `.noydb` containers.\n *\n * **What's a ULID?** A 128-bit identifier encoded as 26 Crockford\n * base32 characters. Layout:\n *\n * ```\n *   01HYABCDEFGHJKMNPQRSTVWXYZ\n *   |--------||---------------|\n *    48-bit     80-bit\n *    timestamp  randomness\n * ```\n *\n * The first 10 chars encode a millisecond Unix timestamp (so ULIDs\n * sort lexicographically by creation time), and the remaining 16\n * chars are random. Crockford base32 omits I/L/O/U to avoid\n * ambiguity in handwriting and URLs.\n *\n * **Why hand-roll instead of pulling in `ulid`?** The package adds\n * a dep, the implementation is ~30 lines, and the bundle module\n * is the only consumer. Adding `ulid` would also drag in its own\n * crypto polyfill that we don't need on Node 18+ or modern\n * browsers.\n *\n * **Privacy consideration:** the timestamp prefix is observable in\n * the bundle header. This is a deliberate trade-off:\n *   - Pro: lexicographic sortability lets bundle adapters list\n *     newest-first without an extra index.\n *   - Con: a casual observer can read the bundle's creation time\n *     from the handle. They cannot read it from any OTHER field\n *     (the header explicitly forbids `_exported_at`), and a\n *     creation timestamp is the same kind of metadata that\n *     filesystem mtime would already expose for a downloaded\n *     bundle. The leak is therefore equivalent to what's already\n *     visible from the file's mtime — not a new exposure.\n *\n * If a future use case needs timestamp-free handles, a v2 of the\n * format could specify \"use the random portion only\" without a\n * format break — `validateBundleHeader` only checks the regex\n * shape, not the encoded timestamp.\n */\n\n/**\n * Crockford base32 alphabet — omits I, L, O, U to avoid handwriting\n * and URL-encoding ambiguity. 32 characters covering 5 bits each.\n */\nconst CROCKFORD_ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'\n\n/**\n * Encode a non-negative integer as a fixed-width Crockford base32\n * string. The width is fixed (not the natural log32 length) so\n * leading zeros are preserved — that's required for the timestamp\n * prefix to remain lexicographically sortable.\n *\n * Used twice: once for the 48-bit timestamp portion (10 chars) and\n * once for each 40-bit half of the randomness (8 chars × 2).\n */\nfunction encodeBase32(value: number, length: number): string {\n  let out = ''\n  let v = value\n  for (let i = 0; i < length; i++) {\n    out = CROCKFORD_ALPHABET[v % 32]! + out\n    v = Math.floor(v / 32)\n  }\n  return out\n}\n\n/**\n * Generate a fresh ULID. Uses `crypto.getRandomValues` for the\n * randomness portion — same Web Crypto API the rest of the\n * codebase uses for IVs and salt.\n *\n * Returns a 26-character string. Calling twice in the same\n * millisecond produces two distinct ULIDs (the random portion\n * differs); ULIDs from the same millisecond are NOT guaranteed\n * to be monotonically ordered relative to each other, only\n * relative to ULIDs from a different millisecond. The bundle\n * format never relies on intra-millisecond ordering.\n */\nexport function generateULID(): string {\n  const now = Date.now()\n\n  // 48-bit timestamp → 10 Crockford base32 characters.\n  // JavaScript's max safe integer is 2^53 - 1; Date.now() is well\n  // within that range until the year ~285,000 AD. Splitting into\n  // high and low 24-bit halves keeps every intermediate value\n  // inside the safe-integer range and avoids any ambiguity in the\n  // base32 encoder above.\n  const timestampHigh = Math.floor(now / 0x1000000) // top 24 bits\n  const timestampLow = now & 0xffffff               // bottom 24 bits\n  const tsPart =\n    encodeBase32(timestampHigh, 5) + encodeBase32(timestampLow, 5)\n\n  // 80-bit randomness → 16 Crockford base32 characters. Split into\n  // two 40-bit halves so each fits in JavaScript's safe-integer\n  // range (53 bits) and the base32 encoder doesn't have to deal\n  // with bigints.\n  const randBytes = new Uint8Array(10)\n  crypto.getRandomValues(randBytes)\n\n  // First 5 bytes (40 bits) → 8 Crockford base32 characters.\n  // Reconstruct the 40-bit integer from bytes in big-endian order.\n  // Multiplication by 2^32 (instead of bit-shift) avoids JavaScript's\n  // 32-bit integer cast on the high byte.\n  const rand1 =\n    randBytes[0]! * 2 ** 32 +\n    (randBytes[1]! << 24 >>> 0) +\n    (randBytes[2]! << 16) +\n    (randBytes[3]! << 8) +\n    randBytes[4]!\n  // Same for the second 5 bytes.\n  const rand2 =\n    randBytes[5]! * 2 ** 32 +\n    (randBytes[6]! << 24 >>> 0) +\n    (randBytes[7]! << 16) +\n    (randBytes[8]! << 8) +\n    randBytes[9]!\n  const randPart = encodeBase32(rand1, 8) + encodeBase32(rand2, 8)\n\n  return tsPart + randPart\n}\n\n/**\n * Validate that a string is a syntactically well-formed ULID. Used\n * by the bundle header validator. Does NOT verify that the\n * timestamp portion decodes to a sensible date — the format only\n * cares about the encoding shape.\n */\nexport function isULID(value: string): boolean {\n  return /^[0-9A-HJKMNP-TV-Z]{26}$/.test(value)\n}\n","/**\n * Consent boundaries — per-access audit log.\n *\n * ```ts\n * const audit = await vault.withConsent(\n *   { purpose: 'quarterly-review', consentHash: '7f3a...' },\n *   async () => {\n *     const invoices = await vault.collection<Invoice>('invoices').list()\n *     return invoices\n *   },\n * )\n *\n * const log = await vault.consentAudit({ since: '2026-01-01T00:00:00Z' })\n * // → entries: { actor, purpose, consentHash, ts, op, collection, id }\n * ```\n *\n * ## Contract\n *\n * Every `get` / `put` / `delete` that happens inside a `withConsent`\n * callback writes one entry to the reserved `_consent_audit`\n * collection. Entries are encrypted with the vault's consent-audit\n * DEK (separate from per-user-collection DEKs so access-log queries\n * don't require unwrapping individual collection keys). Outside a\n * `withConsent` scope, no entries are written — consent is\n * opt-in by design (GDPR Art. 7: *demonstrable*, *specific*\n * consent).\n *\n * ## Why store the hash, not the consent text?\n *\n * The `consentHash` is the sha256 of whatever consent receipt the\n * actor presented (a signed GDPR banner click, a HIPAA authorisation\n * PDF, an API-level `X-Consent-Hash` header). Storing only the hash:\n *\n *   1. Keeps the audit log small and indexable.\n *   2. Preserves zero-knowledge at the adapter — adapters see\n *      ciphertext envelopes of `{ actor, purpose, consentHash, ts,\n *      op, collection, id }`, never the consent record itself.\n *   3. Lets the regulator verify a presented consent doc matches\n *      the logged hash at audit time without the system ever\n *      possessing the doc.\n *\n * ## Concurrency\n *\n * The consent context lives on the {@link Vault} instance. Two\n * concurrent `withConsent` calls on the same Vault would stomp each\n * other — documented limitation; adopters needing per-flight scope\n * should use separate Vault instances or an AsyncLocalStorage shim.\n *\n * @module\n */\nimport type { EncryptedEnvelope, NoydbStore } from '../types.js'\nimport { encrypt, decrypt } from '../crypto.js'\nimport { generateULID } from '../bundle/ulid.js'\n\n/** Reserved collection for consent-audit entries. */\nexport const CONSENT_AUDIT_COLLECTION = '_consent_audit'\n\n/**\n * The consent scope active for a block of work. Set via\n * `vault.withConsent()`; observed by the collection's access hooks.\n */\nexport interface ConsentContext {\n  /**\n   * What this access is for. Used by the audit query (`consentAudit\n   * ({ purpose })`) and carried in the stored entry. Free-form; the\n   * regulator or compliance tooling decides the vocabulary.\n   */\n  readonly purpose: string\n  /**\n   * Hex-encoded sha256 of whatever consent artefact the actor\n   * presented. Stored as-is in each entry.\n   */\n  readonly consentHash: string\n}\n\n/** Access operation recorded in an audit entry. */\nexport type ConsentOp = 'get' | 'put' | 'delete'\n\n/** One consent-audit record, as decrypted for the caller. */\nexport interface ConsentAuditEntry {\n  /** ULID — stable insertion-order key. */\n  readonly id: string\n  readonly timestamp: string\n  readonly actor: string\n  readonly purpose: string\n  readonly consentHash: string\n  readonly op: ConsentOp\n  readonly collection: string\n  readonly recordId: string\n}\n\n/** Filter passed to `vault.consentAudit()`. */\nexport interface ConsentAuditFilter {\n  /** Only entries at or after this ISO timestamp. */\n  readonly since?: string\n  /** Only entries at or before this ISO timestamp. */\n  readonly until?: string\n  /** Match entries targeting this collection. */\n  readonly collection?: string\n  /** Match entries written by this actor. */\n  readonly actor?: string\n  /** Match entries with this purpose. */\n  readonly purpose?: string\n}\n\n/**\n * Write one audit entry. Called by Vault's onAccess hook when a\n * consent context is active.\n */\nexport async function writeConsentEntry(\n  adapter: NoydbStore,\n  vault: string,\n  encrypted: boolean,\n  entry: Omit<ConsentAuditEntry, 'id' | 'timestamp'>,\n  getDEK: (collection: string) => Promise<CryptoKey>,\n): Promise<void> {\n  const id = generateULID()\n  const full: ConsentAuditEntry = {\n    id,\n    timestamp: new Date().toISOString(),\n    ...entry,\n  }\n  const envelope = await buildEnvelope(full, encrypted, getDEK)\n  await adapter.put(vault, CONSENT_AUDIT_COLLECTION, id, envelope)\n}\n\n/** Load + decrypt + filter all entries. */\nexport async function loadConsentEntries(\n  adapter: NoydbStore,\n  vault: string,\n  encrypted: boolean,\n  getDEK: (collection: string) => Promise<CryptoKey>,\n  filter: ConsentAuditFilter = {},\n): Promise<ConsentAuditEntry[]> {\n  const ids = await adapter.list(vault, CONSENT_AUDIT_COLLECTION)\n  const entries: ConsentAuditEntry[] = []\n\n  for (const id of ids.sort()) {\n    const envelope = await adapter.get(vault, CONSENT_AUDIT_COLLECTION, id)\n    if (!envelope) continue\n    const entry = await decryptEntry(envelope, encrypted, getDEK)\n    if (!matchesFilter(entry, filter)) continue\n    entries.push(entry)\n  }\n  return entries\n}\n\n// ── internals ──────────────────────────────────────────────────────\n\nasync function buildEnvelope(\n  entry: ConsentAuditEntry,\n  encrypted: boolean,\n  getDEK: (collection: string) => Promise<CryptoKey>,\n): Promise<EncryptedEnvelope> {\n  const json = JSON.stringify(entry)\n  if (!encrypted) {\n    return {\n      _noydb: 1,\n      _v: 1,\n      _ts: entry.timestamp,\n      _iv: '',\n      _data: json,\n    }\n  }\n  const dek = await getDEK(CONSENT_AUDIT_COLLECTION)\n  const { iv, data } = await encrypt(json, dek)\n  return {\n    _noydb: 1,\n    _v: 1,\n    _ts: entry.timestamp,\n    _iv: iv,\n    _data: data,\n  }\n}\n\nasync function decryptEntry(\n  envelope: EncryptedEnvelope,\n  encrypted: boolean,\n  getDEK: (collection: string) => Promise<CryptoKey>,\n): Promise<ConsentAuditEntry> {\n  const json = encrypted\n    ? await decrypt(envelope._iv, envelope._data, await getDEK(CONSENT_AUDIT_COLLECTION))\n    : envelope._data\n  return JSON.parse(json) as ConsentAuditEntry\n}\n\nfunction matchesFilter(entry: ConsentAuditEntry, f: ConsentAuditFilter): boolean {\n  if (f.since && entry.timestamp < f.since) return false\n  if (f.until && entry.timestamp > f.until) return false\n  if (f.collection && entry.collection !== f.collection) return false\n  if (f.actor && entry.actor !== f.actor) return false\n  if (f.purpose && entry.purpose !== f.purpose) return false\n  return true\n}\n","/**\n * Active consent strategy. Calling `withConsent()` returns a\n * `ConsentStrategy` that delegates to the real\n * `writeConsentEntry` / `loadConsentEntries` functions. Only\n * reachable through the `@noy-db/hub/consent` subpath.\n */\n\nimport { writeConsentEntry, loadConsentEntries } from './consent.js'\nimport type { ConsentStrategy } from './strategy.js'\n\n/**\n * Build the default consent strategy. Pass into\n * `createNoydb({ consentStrategy: withConsent() })` to enable\n * per-operation audit writes into the reserved `_consent_audit`\n * collection.\n */\nexport function withConsent(): ConsentStrategy {\n  return {\n    write: writeConsentEntry,\n    read: loadConsentEntries,\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;AC4EO,IAAM,aAAN,cAAyB,MAAM;AAAA;AAAA,EAE3B;AAAA,EAET,YAAY,MAAc,SAAiB;AACzC,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,OAAO;AAAA,EACd;AACF;AAYO,IAAM,kBAAN,cAA8B,WAAW;AAAA,EAC9C,YAAY,UAAU,qBAAqB;AACzC,UAAM,qBAAqB,OAAO;AAClC,SAAK,OAAO;AAAA,EACd;AACF;AAWO,IAAM,gBAAN,cAA4B,WAAW;AAAA,EAC5C,YAAY,UAAU,yEAAoE;AACxF,UAAM,YAAY,OAAO;AACzB,SAAK,OAAO;AAAA,EACd;AACF;;;AC5EA,IAAM,WAAW;AAGjB,IAAM,SAAS,WAAW,OAAO;AA8EjC,eAAsB,QACpB,WACA,KACwB;AACxB,QAAM,KAAK,WAAW;AACtB,QAAM,UAAU,IAAI,YAAY,EAAE,OAAO,SAAS;AAElD,QAAM,aAAa,MAAM,OAAO;AAAA,IAC9B,EAAE,MAAM,WAAW,GAAuB;AAAA,IAC1C;AAAA,IACA;AAAA,EACF;AAEA,SAAO;AAAA,IACL,IAAI,eAAe,EAAE;AAAA,IACrB,MAAM,eAAe,UAAU;AAAA,EACjC;AACF;AAGA,eAAsB,QACpB,UACA,YACA,KACiB;AACjB,QAAM,KAAK,eAAe,QAAQ;AAClC,QAAM,aAAa,eAAe,UAAU;AAE5C,MAAI;AACF,UAAM,YAAY,MAAM,OAAO;AAAA,MAC7B,EAAE,MAAM,WAAW,GAAuB;AAAA,MAC1C;AAAA,MACA;AAAA,IACF;AACA,WAAO,IAAI,YAAY,EAAE,OAAO,SAAS;AAAA,EAC3C,SAAS,KAAK;AACZ,QAAI,eAAe,SAAS,IAAI,SAAS,kBAAkB;AACzD,YAAM,IAAI,cAAc;AAAA,IAC1B;AACA,UAAM,IAAI;AAAA,MACR,eAAe,QAAQ,IAAI,UAAU;AAAA,IACvC;AAAA,EACF;AACF;AAkTO,SAAS,aAAyB;AACvC,SAAO,WAAW,OAAO,gBAAgB,IAAI,WAAW,QAAQ,CAAC;AACnE;AASO,SAAS,eAAe,QAA0C;AACvE,QAAM,QAAQ,kBAAkB,aAAa,SAAS,IAAI,WAAW,MAAM;AAC3E,MAAI,SAAS;AACb,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;AACrC,cAAU,OAAO,aAAa,MAAM,CAAC,CAAE;AAAA,EACzC;AACA,SAAO,KAAK,MAAM;AACpB;AAEO,SAAS,eAAe,QAAyC;AACtE,QAAM,SAAS,KAAK,MAAM;AAC1B,QAAM,QAAQ,IAAI,WAAW,OAAO,MAAM;AAC1C,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK;AACtC,UAAM,CAAC,IAAI,OAAO,WAAW,CAAC;AAAA,EAChC;AACA,SAAO;AACT;;;AClcA,IAAM,qBAAqB;AAW3B,SAAS,aAAa,OAAe,QAAwB;AAC3D,MAAI,MAAM;AACV,MAAI,IAAI;AACR,WAAS,IAAI,GAAG,IAAI,QAAQ,KAAK;AAC/B,UAAM,mBAAmB,IAAI,EAAE,IAAK;AACpC,QAAI,KAAK,MAAM,IAAI,EAAE;AAAA,EACvB;AACA,SAAO;AACT;AAcO,SAAS,eAAuB;AACrC,QAAM,MAAM,KAAK,IAAI;AAQrB,QAAM,gBAAgB,KAAK,MAAM,MAAM,QAAS;AAChD,QAAM,eAAe,MAAM;AAC3B,QAAM,SACJ,aAAa,eAAe,CAAC,IAAI,aAAa,cAAc,CAAC;AAM/D,QAAM,YAAY,IAAI,WAAW,EAAE;AACnC,SAAO,gBAAgB,SAAS;AAMhC,QAAM,QACJ,UAAU,CAAC,IAAK,KAAK,MACpB,UAAU,CAAC,KAAM,OAAO,MACxB,UAAU,CAAC,KAAM,OACjB,UAAU,CAAC,KAAM,KAClB,UAAU,CAAC;AAEb,QAAM,QACJ,UAAU,CAAC,IAAK,KAAK,MACpB,UAAU,CAAC,KAAM,OAAO,MACxB,UAAU,CAAC,KAAM,OACjB,UAAU,CAAC,KAAM,KAClB,UAAU,CAAC;AACb,QAAM,WAAW,aAAa,OAAO,CAAC,IAAI,aAAa,OAAO,CAAC;AAE/D,SAAO,SAAS;AAClB;;;ACpEO,IAAM,2BAA2B;AAsDxC,eAAsB,kBACpB,SACA,OACA,WACA,OACA,QACe;AACf,QAAM,KAAK,aAAa;AACxB,QAAM,OAA0B;AAAA,IAC9B;AAAA,IACA,YAAW,oBAAI,KAAK,GAAE,YAAY;AAAA,IAClC,GAAG;AAAA,EACL;AACA,QAAM,WAAW,MAAM,cAAc,MAAM,WAAW,MAAM;AAC5D,QAAM,QAAQ,IAAI,OAAO,0BAA0B,IAAI,QAAQ;AACjE;AAGA,eAAsB,mBACpB,SACA,OACA,WACA,QACA,SAA6B,CAAC,GACA;AAC9B,QAAM,MAAM,MAAM,QAAQ,KAAK,OAAO,wBAAwB;AAC9D,QAAM,UAA+B,CAAC;AAEtC,aAAW,MAAM,IAAI,KAAK,GAAG;AAC3B,UAAM,WAAW,MAAM,QAAQ,IAAI,OAAO,0BAA0B,EAAE;AACtE,QAAI,CAAC,SAAU;AACf,UAAM,QAAQ,MAAM,aAAa,UAAU,WAAW,MAAM;AAC5D,QAAI,CAAC,cAAc,OAAO,MAAM,EAAG;AACnC,YAAQ,KAAK,KAAK;AAAA,EACpB;AACA,SAAO;AACT;AAIA,eAAe,cACb,OACA,WACA,QAC4B;AAC5B,QAAM,OAAO,KAAK,UAAU,KAAK;AACjC,MAAI,CAAC,WAAW;AACd,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,IAAI;AAAA,MACJ,KAAK,MAAM;AAAA,MACX,KAAK;AAAA,MACL,OAAO;AAAA,IACT;AAAA,EACF;AACA,QAAM,MAAM,MAAM,OAAO,wBAAwB;AACjD,QAAM,EAAE,IAAI,KAAK,IAAI,MAAM,QAAQ,MAAM,GAAG;AAC5C,SAAO;AAAA,IACL,QAAQ;AAAA,IACR,IAAI;AAAA,IACJ,KAAK,MAAM;AAAA,IACX,KAAK;AAAA,IACL,OAAO;AAAA,EACT;AACF;AAEA,eAAe,aACb,UACA,WACA,QAC4B;AAC5B,QAAM,OAAO,YACT,MAAM,QAAQ,SAAS,KAAK,SAAS,OAAO,MAAM,OAAO,wBAAwB,CAAC,IAClF,SAAS;AACb,SAAO,KAAK,MAAM,IAAI;AACxB;AAEA,SAAS,cAAc,OAA0B,GAAgC;AAC/E,MAAI,EAAE,SAAS,MAAM,YAAY,EAAE,MAAO,QAAO;AACjD,MAAI,EAAE,SAAS,MAAM,YAAY,EAAE,MAAO,QAAO;AACjD,MAAI,EAAE,cAAc,MAAM,eAAe,EAAE,WAAY,QAAO;AAC9D,MAAI,EAAE,SAAS,MAAM,UAAU,EAAE,MAAO,QAAO;AAC/C,MAAI,EAAE,WAAW,MAAM,YAAY,EAAE,QAAS,QAAO;AACrD,SAAO;AACT;;;ACjLO,SAAS,cAA+B;AAC7C,SAAO;AAAA,IACL,OAAO;AAAA,IACP,MAAM;AAAA,EACR;AACF;","names":[]}

package/dist/consent/index.d.cts

@@ -0,0 +1,24 @@
+import { Z as ConsentStrategy } from '../types-Bfs0qr5F.cjs';
+export { _ as CONSENT_AUDIT_COLLECTION, $ as ConsentAuditEntry, a0 as ConsentAuditFilter, a1 as ConsentContext, a2 as ConsentOp, a3 as loadConsentEntries, a4 as writeConsentEntry } from '../types-Bfs0qr5F.cjs';
+import '../lazy-builder-CZVLKh0Z.cjs';
+import '../predicate-SBHmi6D0.cjs';
+import '../strategy-D-SrOLCl.cjs';
+import '../strategy-BSxFXGzb.cjs';
+import '../index-DN-J-5wT.cjs';
+
+/**
+ * Active consent strategy. Calling `withConsent()` returns a
+ * `ConsentStrategy` that delegates to the real
+ * `writeConsentEntry` / `loadConsentEntries` functions. Only
+ * reachable through the `@noy-db/hub/consent` subpath.
+ */
+
+/**
+ * Build the default consent strategy. Pass into
+ * `createNoydb({ consentStrategy: withConsent() })` to enable
+ * per-operation audit writes into the reserved `_consent_audit`
+ * collection.
+ */
+declare function withConsent(): ConsentStrategy;
+
+export { ConsentStrategy, withConsent };

package/dist/consent/index.d.ts

@@ -0,0 +1,24 @@
+import { Z as ConsentStrategy } from '../types-BZpCZB8N.js';
+export { _ as CONSENT_AUDIT_COLLECTION, $ as ConsentAuditEntry, a0 as ConsentAuditFilter, a1 as ConsentContext, a2 as ConsentOp, a3 as loadConsentEntries, a4 as writeConsentEntry } from '../types-BZpCZB8N.js';
+import '../lazy-builder-BwEoBQZ9.js';
+import '../predicate-SBHmi6D0.js';
+import '../strategy-D-SrOLCl.js';
+import '../strategy-BSxFXGzb.js';
+import '../index-BRHBCmLt.js';
+
+/**
+ * Active consent strategy. Calling `withConsent()` returns a
+ * `ConsentStrategy` that delegates to the real
+ * `writeConsentEntry` / `loadConsentEntries` functions. Only
+ * reachable through the `@noy-db/hub/consent` subpath.
+ */
+
+/**
+ * Build the default consent strategy. Pass into
+ * `createNoydb({ consentStrategy: withConsent() })` to enable
+ * per-operation audit writes into the reserved `_consent_audit`
+ * collection.
+ */
+declare function withConsent(): ConsentStrategy;
+
+export { ConsentStrategy, withConsent };