@noy-db/hub 0.1.0-pre.9 → 0.2.0-pre.2

package/dist/chunk-RKJ6OL7K.js.map

@@ -1 +0,0 @@
-{"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'\nimport type { UnlockedKeyring } from './team/keyring.js'\nimport type { VaultPolicy } from './policy/types.js'\nimport type { PublicEnvelopeSchema } from './meta/public-envelope/types.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\n/**\n * Forward-declared on-disk shape for `VaultPolicy` — the actual policy\n * model lives in `policy/types.ts` (#9). Declared here as `unknown`-typed\n * map so types.ts has no dependency on the policy module while the\n * `KeyringFile.policy` field can still round-trip foreign documents.\n *\n * @internal\n */\nexport type VaultPolicyOnDisk = Record<string, unknown>\n\n/**\n * Recovery profile enrolled at vault creation (issue #10).\n *\n * - `paper` — `on-recovery` codes (the only end-to-end profile in v0.1.0-pre.5).\n * - `shamir` / `multi-channel` / `admin-mediated` — API surface ships;\n *   per-profile dispatch lands in follow-up issues. Calling\n *   `db.recoverPassphrase` against these throws\n *   {@link RecoveryProfileNotImplementedError}.\n */\nexport type RecoveryEnrollment =\n  | {\n      readonly profile: 'paper'\n      /** Number of single-use codes to print at enrollment. */\n      readonly codes: number\n    }\n  | {\n      readonly profile: 'shamir'\n      readonly k: number\n      readonly n: number\n      readonly trustees: ReadonlyArray<string>\n    }\n  | {\n      readonly profile: 'multi-channel'\n      readonly email?: string\n      readonly pin?: boolean\n      readonly paperCodes?: number\n    }\n  | {\n      readonly profile: 'admin-mediated'\n      readonly grantorUserId: string\n    }\n\n/**\n * One tier-2 authenticator slot inside a keyring file. Each slot\n * independently wraps the SAME KEK under a method-specific derived key\n * (LUKS pattern). Adding or removing a slot is a constant-time keyring\n * write — no DEK re-keying required.\n *\n * @see docs/subsystems/session-tiers.md → Tier 2 — Authenticate (multi-slot)\n */\n/**\n * Shared fields across all authenticator slot variants. The variant\n * (`KeyringAuthenticatorWrappingKEK` vs `KeyringAuthenticatorWrappingDEKs`)\n * carries the actual wrapped material; everything below is identity +\n * metadata only.\n */\ninterface KeyringAuthenticatorBase {\n  /** Caller-chosen identifier — e.g. `'webauthn-yubikey-blue'`, `'oidc-google'`, `'password-daily'`. */\n  readonly id: string\n  /** Method family — selects which `@noy-db/on-*` package handles unlock. */\n  readonly method: 'webauthn' | 'oidc' | 'password'\n  /** ISO-8601 timestamp at which the slot was added. */\n  readonly enrolled_at: string\n  /**\n   * Which session tier ENROLLED this slot. Tier 1 enrolls a fresh slot;\n   * tier 2 may add a sibling slot when the active policy permits.\n   */\n  readonly enrolled_via_tier: 1 | 2\n  /**\n   * Method-specific metadata: WebAuthn cred id, OIDC issuer/sub, PBKDF2\n   * salt for `on-password`, etc. The schema is open by design — the\n   * `@noy-db/on-*` package owns the contents.\n   */\n  readonly meta: Record<string, unknown>\n}\n\n/**\n * Slot that wraps the KEK directly under a method-derived AES-KW key.\n * Used by ceremonies where the on-* package can produce/recover an\n * extractable KEK from its own credential — WebAuthn (PRF-derived\n * wrapping key) and split-key OIDC.\n *\n * `wrapKind` is optional/absent on slots written before pre.8 — those\n * legacy slots are treated as wrap-KEK by default at unlock time.\n */\nexport interface KeyringAuthenticatorWrappingKEK extends KeyringAuthenticatorBase {\n  readonly wrapKind?: 'kek'\n  /** Base64 wrapped-KEK ciphertext under the method-derived key. */\n  readonly wrapped_kek: string\n  /** XOR guard — wrap-KEK slots must NOT carry wrap-DEKs material. */\n  readonly wrapped_deks?: never\n  /** XOR guard — wrap-KEK slots must NOT carry wrap-DEKs material. */\n  readonly iv?: never\n}\n\n/**\n * Slot that wraps the DEK set (not the KEK) under a method-derived\n * AES-GCM key — sidesteps the non-extractable-KEK constraint by\n * encrypting the serialized `{ deks: { collection: rawDekBase64 } }`\n * directly. Mirrors the format used by `mintPaperRecoveryEntry`\n * (`PaperRecoveryEntry`) and `@noy-db/on-pin`'s `PinResumeState` —\n * the unified wrap-DEKs primitive across tier-0 / tier-2 / tier-3.\n *\n * Trade-off: a slot of this kind reconstructs `UnlockedKeyring` with\n * `kek: null` after unlock. That is semantically correct for tier-2\n * (sensitive ops like `enrollAuthenticator` / `rotatePassphrase`\n * require a tier-1 unlock anyway) and matches how `@noy-db/on-pin`\n * already behaves at tier 3.\n *\n * @see `mintPaperRecoveryEntry` in `team/recovery.ts` — same shape on\n *      a different on-disk path (`_meta/recovery-paper`).\n */\nexport interface KeyringAuthenticatorWrappingDEKs extends KeyringAuthenticatorBase {\n  readonly wrapKind: 'deks'\n  /** Base64 AES-GCM ciphertext of `{ deks: { collection: base64rawDek } }`. */\n  readonly wrapped_deks: string\n  /** Base64 AES-GCM IV used for the `wrapped_deks` ciphertext. */\n  readonly iv: string\n  /** XOR guard — wrap-DEKs slots must NOT carry wrap-KEK material. */\n  readonly wrapped_kek?: never\n}\n\n/**\n * Discriminated union over the two wrap-format variants. Reads from\n * disk should always go through this type so the variant is preserved.\n *\n * Discriminator: `wrapKind`. Absent → wrap-KEK (legacy / WebAuthn /\n * OIDC). Present and `'deks'` → wrap-DEKs (password / future on-* that\n * want to sidestep extractable-KEK).\n *\n * The type-level XOR enforces \"exactly one of `wrapped_kek` /\n * `wrapped_deks` is present\" — a structural guarantee that the runtime\n * dispatch is safe.\n */\nexport type KeyringAuthenticator =\n  | KeyringAuthenticatorWrappingKEK\n  | KeyringAuthenticatorWrappingDEKs\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   * Tier-2 authenticator slots (multi-slot keyring extension).\n   * Optional / append-only: keyring files written before the\n   * extension load with an empty list. Each slot independently wraps\n   * the same KEK; any one of them unlocks.\n   *\n   * @see KeyringAuthenticator\n   */\n  readonly authenticators?: readonly KeyringAuthenticator[]\n  /**\n   * Per-keyring policy override (reserved). The on-disk format\n   * accepts the field for forward compatibility with the Option C\n   * merge engine deferred to a later release; v1.0 reads only the\n   * vault-level `_meta/policy` document, so this field is parsed and\n   * round-tripped but never enforced.\n   */\n  readonly policy?: VaultPolicyOnDisk\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   * Skip phrase-format strength validation (issue #7). Defaults to\n   * false — `grant()` rejects phrases that don't meet the configured\n   * `PassphrasePolicy`. Test fixtures and CLI scripts pass `true`.\n   */\n  readonly allowWeakPassphrase?: boolean\n  /**\n   * Initial user-envelope payload for the new principal. Sealed under\n   * the same vault DEK (the reserved `_users` collection's DEK) and\n   * persisted alongside the keyring during grant.\n   *\n   * **Bootstrap-only.** Once the new user activates and writes their\n   * own envelope, the own-only write rule kicks in — admins cannot\n   * edit a teammate's envelope after activation. Use this field for\n   * pre-fill at invite time (e.g. \"displayName: Bob, locale: en-US\")\n   * and let the user take over from there.\n   *\n   * Hub does not introspect the payload; it is JSON-serialized and\n   * encrypted opaquely. Apps own the schema.\n   *\n   * @see docs/superpowers/specs/2026-05-05-user-envelope-design.md → Lifecycle\n   */\n  readonly initialProfile?: unknown\n}\n\n/**\n * Caller payload for `db.updateUser` (#54). Mutate one or more\n * identity fields on an existing keyring without rotating any keys.\n *\n * `role`, `displayName`, and `permissions` live in the plaintext header\n * of `_keyring/<userId>` (the sync engine reads them without keys).\n * Mutating them is a JSON header swap — no DEK rewrap, no KEK\n * required, no authenticator slots touched. Tier-2 slots and recovery\n * enrollments survive unchanged. Last-write-wins through the existing\n * keyring put (same concurrency story as `db.grant` / `db.revoke`).\n *\n * Top-level fields are partial-merge: absent fields are not modified.\n * `permissions`, however, is a **full replacement** at the map level —\n * passing `{ invoices: 'rw' }` REPLACES the entire permissions map,\n * silently dropping any other entries. To partially update, read the\n * current keyring and merge: `permissions: { ...current, invoices: 'rw' }`.\n * To clear all permissions, pass `permissions: {}` explicitly.\n *\n * Role-elevation guard: the same hierarchy as `db.grant`. Admins can\n * change `admin` / `operator` / `viewer` / `client` to and from each\n * other; admins cannot promote to or demote from `owner`. Owners can\n * do anything. Non-admin callers (operator/viewer/client) cannot call\n * `db.updateUser` at all — for self-displayName changes, use\n * `vault.user.updateMe` (the user-envelope API).\n *\n * @see #54\n */\nexport interface UpdateUserOptions {\n  readonly userId: string\n  readonly role?: Role\n  readonly displayName?: string\n  readonly permissions?: Permissions\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 or `getKeyring` is provided. */\n  readonly secret?: string\n  /**\n   * Optional callback that returns an unlocked keyring for a given vault.\n   * Use this to plug in WebAuthn / OIDC / Shamir / any unlock path that\n   * produces an `UnlockedKeyring` outside the passphrase model.\n   *\n   * When set, `secret` MUST NOT also be set — `createNoydb` throws if both\n   * are supplied. When neither is set (and `encrypt !== false`), `createNoydb`\n   * also throws.\n   *\n   * The callback is called lazily, on the first operation that needs the\n   * keyring for a given vault. Noydb caches the returned keyring per-vault\n   * for the lifetime of the instance, so the callback is invoked at most\n   * once per `(instance, vault)` pair (assuming the callback resolves\n   * successfully). If the callback rejects, the rejection surfaces from the\n   * first vault operation that triggered the unlock; subsequent operations\n   * will retry the callback.\n   *\n   * @example\n   * ```ts\n   * import { createNoydb } from '@noy-db/hub'\n   * import { unlockWebAuthn } from '@noy-db/on-webauthn'\n   *\n   * const enrollment = await loadEnrollment()\n   * const db = await createNoydb({\n   *   store,\n   *   user: 'alice',\n   *   getKeyring: (vault) => unlockWebAuthn(enrollment),\n   * })\n   * ```\n   *\n   * Note: this callback is responsible for both the \"open existing vault\"\n   * and the \"create new vault\" cases. Unlike the passphrase path, there is\n   * no automatic `NoAccessError` → `createOwnerKeyring` fallback, because\n   * the callback owner has the UI context to decide which path to run.\n   * For first-time bootstrap, use a passphrase or recovery code, enroll\n   * WebAuthn from the unlocked keyring, then swap to `getKeyring` on\n   * subsequent sessions.\n   */\n  readonly getKeyring?: (vault: string) => Promise<UnlockedKeyring>\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  /**\n   * Validate passphrase strength against the phrase format\n   * (`@noy-db/hub` issue #7) on first-time keyring creation. When\n   * `true`, weak phrases throw {@link WeakPassphraseError} from\n   * `createNoydb()` / `db.rotatePassphrase()`. Default: `false` for\n   * back-compat in v0.1.x; planned to flip to `true` at v1.0.\n   */\n  readonly validatePassphrase?: boolean\n  /**\n   * Vault-level policy gate document (issue #9). When present, the hub\n   * persists the merged policy at `_meta/policy` on first-time vault\n   * creation and gates sensitive operations (`db.rotatePassphrase`,\n   * `db.export*`, …) against it. Omitted ⇒ the engine uses\n   * {@link PERSONAL_POLICY}. Use {@link STRICT_POLICY} for regulated\n   * deployments.\n   *\n   * The on-disk document is the source of truth — the policy field\n   * is only honored at vault creation; subsequent runs read from\n   * `_meta/policy`. Use `db.updatePolicy()` to change it deliberately.\n   *\n   * Imported from `@noy-db/hub` as a type-only reference; the runtime\n   * import lives in `policy/index.ts`.\n   */\n  readonly policy?: VaultPolicy\n  /**\n   * Mandatory recovery profile enrollment (issue #10). Vaults with\n   * `recover-passphrase` enabled MUST register at least one profile\n   * before being production-ready, otherwise `createNoydb()` throws\n   * {@link RecoveryNotEnrolledError}. Set\n   * `policy.gates['recover-passphrase'].enabled = false` to\n   * deliberately opt out of recovery (passphrase loss = data loss).\n   *\n   * v0.1.0-pre.5 supports the `'paper'` profile end-to-end. Other\n   * profiles ship the API shape and throw\n   * {@link RecoveryProfileNotImplementedError} during use.\n   */\n  readonly recovery?: ReadonlyArray<RecoveryEnrollment>\n  /**\n   * When `true`, `createNoydb` rejects vaults with no recovery\n   * entries persisted (per the spec's mandatory-enrollment\n   * requirement). Default `false` for v0.1.x back-compat; planned to\n   * flip to `true` at v1.0. Apps in regulated environments should\n   * turn this on now.\n   */\n  readonly requireRecovery?: boolean\n  /**\n   * What to do when `openVault` finds an existing keyring in the store that\n   * cannot be decrypted with the supplied credentials (`InvalidKeyError`).\n   *\n   * - `'error'` (default) — propagate the error. The app must prompt the user\n   *   to supply the correct credentials or clear both the data and auth stores.\n   * - `'reset'` — delete the stale keyring and re-initialise the vault from\n   *   scratch using the current credentials. Use this when the data store can\n   *   become detached from the auth store (e.g. the user cleared the IndexedDB\n   *   data records but not the keyring row, or a WebAuthn credential was rotated).\n   *   **All previously encrypted data is unrecoverable after a reset.**\n   *\n   * Only applies to the passphrase (`secret`) path. When `getKeyring` is used,\n   * the callback is responsible for handling stale-keyring detection itself.\n   */\n  readonly onInvalidKey?: 'error' | 'reset'\n  /**\n   * Enable the public envelope subsystem (`docs/subsystems/public-envelope.md`).\n   * Pass `true` for the default schema (every standard field, 256 KB\n   * icon cap, 200-char text cap), or a `PublicEnvelopeSchema` to\n   * narrow what the owner can set. Off by default — vaults written\n   * by hubs without this option carry no envelope, full stop.\n   */\n  readonly publicEnvelope?: true | PublicEnvelopeSchema\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":";AA4CO,IAAM,uBAAuB;AAG7B,IAAM,wBAAwB;AAG9B,IAAM,uBAAuB;AAG7B,IAAM,qBAAqB;AA6U3B,SAAS,YACd,SACmC;AACnC,SAAO;AACT;","names":[]}

package/dist/chunk-SCZXXXU4.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/team/tiers.ts","../src/team/delegation.ts"],"sourcesContent":["/**\n * Hierarchical access — tier-aware keyring helpers.\n *\n * The keyring's existing `deks: Map<string, CryptoKey>` is keyed by\n * collection name. extends the key space:\n *\n *   `'invoices'`      — tier-0 DEK (unchanged from v0.x)\n *   `'invoices#1'`    — tier-1 DEK\n *   `'invoices#2'`    — tier-2 DEK\n *\n * Tier 0 keeps the bare collection name so any keyring written\n * before tiers existed loads without migration. Tiers ≥ 1 use `#N`\n * suffixes that\n * would be invalid as user-supplied collection names (see\n * `ReservedCollectionNameError` — `#` is reserved).\n *\n * @module\n */\n\nimport type { UnlockedKeyring } from './keyring.js'\nimport { TierNotGrantedError } from '../errors.js'\n\n/** Canonical DEK key for a given collection + tier. Tier 0 → bare name. */\nexport function dekKey(collection: string, tier: number): string {\n  if (tier <= 0) return collection\n  return `${collection}#${tier}`\n}\n\n/**\n * Returns the user's effective clearance for a given collection: the\n * maximum tier for which their keyring holds a DEK. Falls back to 0\n * when the user has only the tier-0 DEK (or none — the getDEK caller\n * will raise separately).\n */\nexport function effectiveClearance(keyring: UnlockedKeyring, collection: string): number {\n  let max = 0\n  const prefix = `${collection}#`\n  for (const key of keyring.deks.keys()) {\n    if (!key.startsWith(prefix)) continue\n    const suffix = key.slice(prefix.length)\n    const n = Number.parseInt(suffix, 10)\n    if (Number.isFinite(n) && n > max) max = n\n  }\n  return max\n}\n\n/**\n * Assert the caller is cleared for the requested tier. Owners and\n * admins always pass (they can mint any new tier DEK on demand);\n * other roles must already hold the tier DEK — via a prior grant or\n * an active delegation — otherwise this throws `TierNotGrantedError`.\n *\n * This gate runs BEFORE `getDEK()` on the mutation path so a\n * non-cleared operator never has the opportunity to silently\n * auto-create a tier DEK they shouldn't have.\n */\nexport function assertTierAccess(\n  keyring: UnlockedKeyring,\n  collection: string,\n  tier: number,\n): void {\n  if (tier <= 0) return\n  if (keyring.role === 'owner' || keyring.role === 'admin') return\n  if (!keyring.deks.has(dekKey(collection, tier))) {\n    throw new TierNotGrantedError(collection, tier)\n  }\n}\n","/**\n * Time-boxed cross-tier delegation tokens.\n *\n * A higher-tier user can issue a delegation that grants another user\n * temporary access to records at a specified tier. The delegation is\n * persisted as an encrypted envelope in the reserved `_delegations`\n * collection. The target user's runtime scans this collection on every\n * open and, while `until` is still in the future, merges the\n * unwrapped tier DEKs into their in-memory DEK map.\n *\n * ## Token shape\n *\n * ```\n * {\n *   id,             // ULID, also the _delegations record id\n *   toUser,         // grantee user id\n *   fromUser,       // grantor user id (owner/admin/higher-tier principal)\n *   tier,           // tier being delegated\n *   collection,     // collection name OR null for \"every collection\"\n *   record,         // optional specific record id\n *   until,          // ISO timestamp — token expires at this instant\n *   wrappedDek,     // base64 AES-KW-wrapped tier DEK, wrapped under target KEK\n *   createdAt,      // ISO timestamp\n * }\n * ```\n *\n * The ciphertext is stored as a normal noy-db envelope — the\n * `_delegations` collection has its own DEK shared across all vault\n * users, so an operator can enumerate active delegations for audit\n * without being able to *use* them (the `wrappedDek` inside is still\n * keyed to the target user's KEK).\n *\n * ## Revocation\n *\n * Delete the `_delegations/<id>` envelope. The target user's runtime\n * reloads the delegation list at each open and at periodic intervals\n * (tracked by the caller — this module is pure logic).\n *\n * @module\n */\n\nimport type { NoydbStore, EncryptedEnvelope } from '../types.js'\nimport type { UnlockedKeyring } from './keyring.js'\nimport { encrypt, decrypt, wrapKey, unwrapKey } from '../crypto.js'\nimport { dekKey } from './tiers.js'\nimport { DelegationTargetMissingError } from '../errors.js'\nimport { generateULID } from '../bundle/ulid.js'\n\nexport const DELEGATIONS_COLLECTION = '_delegations'\n\n/**\n * Durable payload of a delegation token. Encrypted under the vault's\n * `_delegations` DEK; the `wrappedDek` inside is additionally wrapped\n * under the target user's KEK.\n */\nexport interface DelegationToken {\n  readonly id: string\n  readonly toUser: string\n  readonly fromUser: string\n  readonly tier: number\n  /** Collection name or `null` for all collections. */\n  readonly collection: string | null\n  /** Optional specific record id scope. */\n  readonly record?: string\n  readonly until: string\n  readonly wrappedDek: string\n  readonly createdAt: string\n}\n\nexport interface IssueDelegationOptions {\n  readonly toUser: string\n  readonly tier: number\n  readonly collection?: string\n  readonly record?: string\n  readonly until: Date | string\n}\n\n/**\n * Build and persist a delegation token. The caller must hold a tier-N\n * DEK and must have already located the target user's keyring file\n * (so the `wrappedDek` can be re-wrapped against their KEK).\n */\nexport async function issueDelegation(\n  store: NoydbStore,\n  vault: string,\n  grantor: UnlockedKeyring,\n  targetKek: CryptoKey | null,\n  delegationsDek: CryptoKey,\n  opts: IssueDelegationOptions,\n): Promise<DelegationToken> {\n  if (!targetKek) {\n    throw new DelegationTargetMissingError(opts.toUser)\n  }\n  const tier = opts.tier\n  const collectionName = opts.collection ?? null\n  const dekLookupCollection = collectionName ?? ''\n  // Tier DEK to delegate — fetched from the grantor's own keyring.\n  const sourceDek = collectionName\n    ? grantor.deks.get(dekKey(collectionName, tier))\n    : undefined\n  if (!sourceDek) {\n    throw new DelegationTargetMissingError(\n      `grantor cannot find tier ${tier} DEK for ${dekLookupCollection || '(any)'}`,\n    )\n  }\n  const wrappedDek = await wrapKey(sourceDek, targetKek)\n\n  const until = typeof opts.until === 'string' ? opts.until : opts.until.toISOString()\n  const token: DelegationToken = {\n    id: generateULID(),\n    toUser: opts.toUser,\n    fromUser: grantor.userId,\n    tier,\n    collection: collectionName,\n    ...(opts.record && { record: opts.record }),\n    until,\n    wrappedDek,\n    createdAt: new Date().toISOString(),\n  }\n\n  const plaintext = JSON.stringify(token)\n  const { iv, data } = await encrypt(plaintext, delegationsDek)\n  const envelope: EncryptedEnvelope = {\n    _noydb: 1,\n    _v: 1,\n    _ts: token.createdAt,\n    _iv: iv,\n    _data: data,\n    _by: grantor.userId,\n  }\n  await store.put(vault, DELEGATIONS_COLLECTION, token.id, envelope)\n  return token\n}\n\n/**\n * Enumerate every live (non-expired) delegation addressed to `toUser`\n * and merge the unwrapped tier DEKs into their keyring. Returns the\n * list of merged delegations so the caller can register per-access\n * audit context.\n */\nexport async function loadActiveDelegations(\n  store: NoydbStore,\n  vault: string,\n  user: UnlockedKeyring,\n  delegationsDek: CryptoKey,\n  now: Date = new Date(),\n): Promise<DelegationToken[]> {\n  const ids = await store.list(vault, DELEGATIONS_COLLECTION)\n  const merged: DelegationToken[] = []\n  const nowIso = now.toISOString()\n  for (const id of ids) {\n    const env = await store.get(vault, DELEGATIONS_COLLECTION, id)\n    if (!env) continue\n    let token: DelegationToken\n    try {\n      const plaintext = await decrypt(env._iv, env._data, delegationsDek)\n      token = JSON.parse(plaintext) as DelegationToken\n    } catch {\n      continue\n    }\n    if (token.toUser !== user.userId) continue\n    if (token.until <= nowIso) continue\n\n    // A user without a KEK in memory (tier-3 PIN resume, wrap-DEKs\n    // tier-2 unlock, session restore) cannot unwrap delegation tokens\n    // — those were wrapped under the user's KEK at issue time. Skip\n    // this token; the consumer reaches it again at tier-1 unlock.\n    if (!user.kek) continue\n    let dek: CryptoKey\n    try {\n      dek = await unwrapKey(token.wrappedDek, user.kek)\n    } catch {\n      continue\n    }\n    const k = token.collection\n      ? dekKey(token.collection, token.tier)\n      : `__any#${token.tier}`\n    user.deks.set(k, dek)\n    merged.push(token)\n  }\n  return merged\n}\n\n/**\n * Revoke a delegation by id — the caller resolves the envelope and\n * issues a `delete`. Provided as a stable helper so the naming is\n * symmetric to `issueDelegation`.\n */\nexport async function revokeDelegation(\n  store: NoydbStore,\n  vault: string,\n  id: string,\n): Promise<void> {\n  await store.delete(vault, DELEGATIONS_COLLECTION, id)\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-TDR6T5CJ.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/aggregate/reducers.ts","../src/aggregate/aggregation.ts","../src/aggregate/groupby.ts"],"sourcesContent":["/**\n * Aggregation reducers for the query DSL.\n *\n * the reducer protocol plus five built-in factories\n * (`count`, `sum`, `avg`, `min`, `max`) consumed by `Query.aggregate()`\n * and, in the future, `Scan.aggregate()`. Every factory accepts\n * an optional `{ seed }` parameter that is plumbed through the\n * protocol but unused by the executor — that's the load-bearing\n * half of  constraint #2. When partition-aware aggregation\n * lands, the seed carries the previous partition's running total into\n * the next partition without requiring a protocol change.\n *\n * Reducers are intentionally generic over their internal state type\n * `S` so compound reducers (avg keeps `{sum, count}`, min/max keep a\n * value bag) can model internal bookkeeping without leaking the\n * implementation through the accumulator's public shape. `finalize`\n * collapses `S` back into the user-visible `R`.\n *\n * Reducers are pure data — `init` / `step` / `finalize` / optional\n * `remove` are stateless functions that receive and return `S`. This\n * is the shape that admits O(1) incremental maintenance in a future\n * optimization (delta-aware `LiveAggregation` applies `step` or\n * `remove` per delta), without blocking the simpler \"full re-run on\n * source change\" that ships.\n */\n\nimport { readPath } from '../query/predicate.js'\n\n/**\n * A single reducer: factory-produced, ready to plug into an\n * `.aggregate()` spec.\n *\n * Type parameters:\n *   - `R` — user-visible result type (what the aggregation returns\n *     for this slot, e.g. `number` for `sum()`)\n *   - `S` — internal state type, defaults to `R` for simple reducers\n *     that don't need compound bookkeeping\n *\n * A reducer is stateless: every method is pure over `S`. `init()` is\n * called once per aggregation run to build the initial state; `step()`\n * folds a record into the state; `remove()` (optional) un-folds a\n * record, enabling incremental live maintenance; `finalize()` reads\n * the final answer out of the state at the end of the run.\n */\nexport interface Reducer<R, S = R> {\n  /** Build the initial state for a fresh aggregation run. */\n  init(): S\n  /** Fold a record into the state. Returns the new state. */\n  step(state: S, record: unknown): S\n  /**\n   * Un-fold a record from the state. Returns the new state.\n   *\n   * Optional — reducers without `remove` cannot be maintained\n   * incrementally and must be re-run from scratch when the underlying\n   * record set changes. `sum`, `count`, `avg` implement `remove` in\n   * O(1); `min` and `max` implement it in O(N) worst case (when the\n   * extremum itself is removed and the next extremum must be\n   * recomputed from the remaining contributing values).\n   */\n  remove?(state: S, record: unknown): S\n  /** Collapse the internal state into the user-visible result. */\n  finalize(state: S): R\n}\n\n/**\n * Common options accepted by every reducer factory.\n *\n * `seed` — optional initial value for the internal state. **Unused by\n * the executor**, plumbed through the protocol for  constraint\n * #2 (partition-aware aggregation seam). In, partitioned\n * aggregations will pass the previous partition's carry as `seed` so\n * a long time series can be rolled forward one partition at a time\n * without re-aggregating closed partitions.\n *\n * always uses `init()` with the factory's zero value, regardless\n * of whether `seed` was passed. Do not remove the parameter — that's\n * the whole point of having it exist now.\n */\nexport interface ReducerOptions<TSeed = unknown> {\n  /**  constraint #2 — seed is plumbed through but unused in. */\n  readonly seed?: TSeed\n}\n\n// ---------------------------------------------------------------------------\n// Factories\n// ---------------------------------------------------------------------------\n\n/**\n * Count the number of records that match the query. Ignores field\n * values entirely — the count is over the number of records, not over\n * the number of non-null field values in any column.\n */\nexport function count(opts?: ReducerOptions<number>): Reducer<number> {\n  // Seed captured on the closure but unused at execution time in\n  //. The reference in _seed keeps lint happy.\n  const _seed = opts?.seed\n  void _seed\n  return {\n    init: () => 0,\n    step: (state) => state + 1,\n    remove: (state) => state - 1,\n    finalize: (state) => state,\n  }\n}\n\n/**\n * Sum a numeric field across all matching records. Non-number values\n * at the field path are coerced to 0 — consumers who want a different\n * behavior (throw, skip, treat as NaN) should filter upstream via\n * `.where()` or write a custom reducer.\n */\nexport function sum(\n  field: string,\n  opts?: ReducerOptions<number>,\n): Reducer<number> {\n  const _seed = opts?.seed\n  void _seed\n  return {\n    init: () => 0,\n    step: (state, record) => state + readNumber(record, field),\n    remove: (state, record) => state - readNumber(record, field),\n    finalize: (state) => state,\n  }\n}\n\n/**\n * Arithmetic mean of a numeric field across all matching records.\n *\n * Returns `null` for an empty result set (zero records is not a\n * well-defined denominator — returning NaN would poison downstream\n * arithmetic, and throwing would force every consumer to wrap in\n * try/catch just to handle \"no matches\"). Consumers who want an\n * explicit zero should coalesce with `?? 0`.\n *\n * Internal state is `{sum, count}` so the running average can be\n * maintained incrementally — on each delta, both fields update in\n * O(1) and `finalize` divides. Directly storing `avg` as state would\n * not admit incremental removal without also tracking count.\n */\nexport function avg(\n  field: string,\n  opts?: ReducerOptions<{ sum: number; count: number }>,\n): Reducer<number | null, { sum: number; count: number }> {\n  const _seed = opts?.seed\n  void _seed\n  return {\n    init: () => ({ sum: 0, count: 0 }),\n    step: (state, record) => ({\n      sum: state.sum + readNumber(record, field),\n      count: state.count + 1,\n    }),\n    remove: (state, record) => ({\n      sum: state.sum - readNumber(record, field),\n      count: state.count - 1,\n    }),\n    finalize: (state) => (state.count === 0 ? null : state.sum / state.count),\n  }\n}\n\ninterface MinMaxState {\n  /**\n   * Multiset of contributing field values. Stored as a plain array\n   * because we need to support `remove` and a plain array gives us\n   * O(1) push + O(N) worst-case removal — which matches the\n   * documented min/max removal complexity. A sorted structure would\n   * let us drop the O(N) rescan but adds complexity that doesn't\n   * need; consumers hitting the O(N) ceiling should file an issue.\n   */\n  readonly values: number[]\n}\n\nfunction pushValue(state: MinMaxState, value: number): MinMaxState {\n  return { values: [...state.values, value] }\n}\n\nfunction removeValue(state: MinMaxState, value: number): MinMaxState {\n  // Remove the first matching value — duplicates are fine, we only\n  // need to drop one instance per `remove()` call so the multiset\n  // count stays consistent with the record count.\n  const idx = state.values.indexOf(value)\n  if (idx < 0) return state\n  const next = state.values.slice()\n  next.splice(idx, 1)\n  return { values: next }\n}\n\n/**\n * Smallest numeric value of a field across all matching records.\n * Returns `null` for an empty result set. See `avg()` for the\n * reasoning on `null` vs NaN vs throwing.\n *\n * Incremental complexity: O(1) for `step`, O(N) worst case for\n * `remove` when the current minimum is removed (the state holds the\n * full multiset of contributing values and `finalize` scans for the\n * new minimum). Consumers with very large result sets and frequent\n * removals of the current extremum should either accept the cost or\n * wait for a future optimization.\n */\nexport function min(\n  field: string,\n  opts?: ReducerOptions<number>,\n): Reducer<number | null, MinMaxState> {\n  const _seed = opts?.seed\n  void _seed\n  return {\n    init: () => ({ values: [] }),\n    step: (state, record) => pushValue(state, readNumber(record, field)),\n    remove: (state, record) => removeValue(state, readNumber(record, field)),\n    finalize: (state) => {\n      if (state.values.length === 0) return null\n      let out = state.values[0]!\n      for (let i = 1; i < state.values.length; i++) {\n        const v = state.values[i]!\n        if (v < out) out = v\n      }\n      return out\n    },\n  }\n}\n\n/**\n * Largest numeric value of a field across all matching records.\n * Mirror of `min()` — see that doc for semantics, null-on-empty\n * behavior, and the O(N) removal caveat.\n */\nexport function max(\n  field: string,\n  opts?: ReducerOptions<number>,\n): Reducer<number | null, MinMaxState> {\n  const _seed = opts?.seed\n  void _seed\n  return {\n    init: () => ({ values: [] }),\n    step: (state, record) => pushValue(state, readNumber(record, field)),\n    remove: (state, record) => removeValue(state, readNumber(record, field)),\n    finalize: (state) => {\n      if (state.values.length === 0) return null\n      let out = state.values[0]!\n      for (let i = 1; i < state.values.length; i++) {\n        const v = state.values[i]!\n        if (v > out) out = v\n      }\n      return out\n    },\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Read a numeric field from a record. Non-number values (null,\n * undefined, strings, objects) coerce to 0 so sum/avg/min/max don't\n * produce NaN on one bad row. Consumers who want strict typing should\n * validate upstream with Standard Schema, which NOYDB already runs on\n * every `put()`.\n */\nfunction readNumber(record: unknown, field: string): number {\n  const value = readPath(record, field)\n  return typeof value === 'number' && Number.isFinite(value) ? value : 0\n}\n","/**\n * Aggregate execution — the runtime behind `Query.aggregate()`.\n *\n * takes an `AggregateSpec` (a record of named reducers\n * built from `reducers.ts`) and runs every reducer over the records\n * produced by the underlying query. Two terminal surfaces:\n *\n *   - `.run(): R` — synchronous one-shot reduction. Matches the\n *     existing `Query.toArray()` / `.first()` / `.count()` style.\n *   - `.live(): LiveAggregation<R>` — reactive primitive that\n *     re-runs the reduction whenever the query's source notifies of\n *     a change. uses naive full re-run; incremental delta\n *     maintenance is admitted by the reducer protocol (`remove()`)\n *     but not wired to the executor yet — a follow-up optimization\n *     can switch from full re-run to delta-based without breaking\n *     the public API. Consumers get correct, reactive values today.\n *\n * The `Aggregation<R>` wrapper is deliberately tiny — it exists so\n * `.aggregate(spec)` can be chained with either `.run()` or `.live()`\n * without the builder needing two separate terminal methods. It\n * holds the closure over the query execution (produces the current\n * matching record set) and the spec, and stitches them together in\n * either mode.\n *\n * This file depends ONLY on `reducers.ts` — it has no knowledge of\n * the `Query` class. Tests can therefore exercise the reduction\n * surface with plain record arrays, without spinning up a Collection.\n */\n\nimport type { Reducer } from './reducers.js'\n\n/**\n * A named set of reducers, keyed by output field name. Each key\n * becomes a field on the aggregated result.\n *\n * ```ts\n * const spec = {\n *   total: sum('amount'),\n *   n:     count(),\n *   avgAmount: avg('amount'),\n * }\n * ```\n */\nexport type AggregateSpec = Readonly<Record<string, Reducer<unknown, unknown>>>\n\n/**\n * Map an `AggregateSpec` to its reduced result shape — each key\n * carries the finalized result type from its reducer. A spec built\n * from `{ total: sum('amount'), n: count() }` yields a result of\n * `{ total: number, n: number }`.\n *\n * This uses a mapped type with a conditional to extract `R` from\n * each `Reducer<R, _>`. The `infer` captures the user-visible result\n * type, discarding the internal state type `S`.\n */\nexport type AggregateResult<Spec extends AggregateSpec> = {\n  [K in keyof Spec]: Spec[K] extends Reducer<infer R, unknown> ? R : never\n}\n\n/**\n * Pure reduction over a record array. Runs every reducer's\n * `init → step* → finalize` pipeline exactly once over the records.\n *\n * Called by `Aggregation.run()` and by the live-mode refresh path.\n * Exported for tests and for future `scan().aggregate()` reuse\n * — the streaming path will call the same reducer protocol with a\n * per-page loop instead of a single array.\n */\nexport function reduceRecords<Spec extends AggregateSpec>(\n  records: readonly unknown[],\n  spec: Spec,\n): AggregateResult<Spec> {\n  // Per-slot state, keyed by the spec's output field name.\n  const state: Record<string, unknown> = {}\n  for (const key of Object.keys(spec)) {\n    state[key] = spec[key]!.init()\n  }\n  for (const record of records) {\n    for (const key of Object.keys(spec)) {\n      state[key] = spec[key]!.step(state[key], record)\n    }\n  }\n  const result: Record<string, unknown> = {}\n  for (const key of Object.keys(spec)) {\n    result[key] = spec[key]!.finalize(state[key])\n  }\n  return result as AggregateResult<Spec>\n}\n\n/**\n * A minimal reactive primitive for aggregation results.\n *\n * Same spirit as the `LiveQuery` in : frame-agnostic, a plain\n * object with `value` / `error` fields and a `subscribe(cb)`\n * notification channel that Vue / React / Solid adapters wrap in\n * their own primitive. Intentionally NOT a Promise — aggregations\n * have a well-defined \"current value\" at every instant, and the\n * reactive consumer wants to read that value synchronously.\n *\n * Error semantics mirror `LiveQuery`: if a re-run throws, the\n * previous successful `value` is preserved and the error is stored\n * in `error` so consumers can render an error state without losing\n * the last-known-good result. The throw does NOT propagate out of\n * the source's change handler (which would tear down the upstream\n * emitter).\n *\n * `stop()` tears down the upstream subscription. It is idempotent —\n * calling it multiple times is safe — and subscribe calls after\n * stop are no-ops (they immediately return a no-op unsubscribe).\n * Always call `stop()` when done; Vue's `onUnmounted` is the\n * canonical place. Raw consumers must do it themselves.\n */\nexport interface LiveAggregation<R> {\n  /** Current reduced value. Undefined only if the first compute threw. */\n  readonly value: R | undefined\n  /** Last execution error, if any. Cleared on the next successful run. */\n  readonly error: unknown\n  /** Notify on every recomputation (success or error). Returns unsubscribe. */\n  subscribe(cb: () => void): () => void\n  /** Tear down the upstream subscription. Idempotent. */\n  stop(): void\n}\n\n/**\n * Upstream change-notification hook for live aggregation.\n *\n * Matches the shape that `QuerySource.subscribe` already uses — a\n * single method that accepts a callback and returns an unsubscribe\n * function. The `Aggregation` wrapper collects upstreams from the\n * query's source and wires them into a single re-run trigger.\n */\nexport interface AggregationUpstream {\n  subscribe(cb: () => void): () => void\n}\n\n/**\n * Internal implementation of `LiveAggregation`. Not exported —\n * consumers get the interface only. The class wraps a `recompute`\n * closure (which runs the full reduction and returns the new value)\n * and a list of upstreams (sources whose changes should trigger a\n * re-run).\n *\n * Error isolation: if an individual listener callback throws, the\n * other listeners still fire and the error is logged to the warn\n * channel. This matches `LiveQuery` from  and keeps one misbehaving\n * consumer from tearing down the whole live aggregation.\n */\nclass LiveAggregationImpl<R> implements LiveAggregation<R> {\n  public value: R | undefined\n  public error: unknown\n  private readonly listeners = new Set<() => void>()\n  private readonly unsubscribes: Array<() => void> = []\n  private stopped = false\n\n  constructor(\n    private readonly recompute: () => R,\n    upstreams: readonly AggregationUpstream[],\n  ) {\n    // Initial computation — surface any error through the `error`\n    // field rather than letting the constructor throw, so consumers\n    // can always construct a LiveAggregation and check its state\n    // afterwards. Throwing from a constructor would force every\n    // caller to wrap in try/catch, which is the opposite of the\n    // \"reactive value with error state\" ergonomics we want.\n    try {\n      this.value = recompute()\n      this.error = undefined\n    } catch (err) {\n      this.value = undefined\n      this.error = err\n    }\n\n    // Wire up upstream subscriptions. Each one triggers a full\n    // recomputation; we don't attempt incremental updates in.\n    for (const upstream of upstreams) {\n      const unsub = upstream.subscribe(() => this.refresh())\n      this.unsubscribes.push(unsub)\n    }\n  }\n\n  private refresh(): void {\n    if (this.stopped) return\n    try {\n      this.value = this.recompute()\n      this.error = undefined\n    } catch (err) {\n      // Preserve the previous successful value — consumers render an\n      // error state using `error` without losing the last-known-good\n      // number. This matches LiveQuery's error-preservation contract.\n      this.error = err\n    }\n    for (const listener of this.listeners) {\n      try {\n        listener()\n      } catch (err) {\n        // Isolate listener errors so one bad consumer can't tear\n        // down every other subscriber on the same aggregation.\n        console.warn('[noy-db] LiveAggregation listener threw:', err)\n      }\n    }\n  }\n\n  subscribe(cb: () => void): () => void {\n    if (this.stopped) {\n      // No-op after stop. Returning a harmless unsubscribe lets\n      // consumers use the same teardown pattern unconditionally.\n      return () => {}\n    }\n    this.listeners.add(cb)\n    return () => {\n      this.listeners.delete(cb)\n    }\n  }\n\n  stop(): void {\n    if (this.stopped) return\n    this.stopped = true\n    for (const unsub of this.unsubscribes) {\n      try {\n        unsub()\n      } catch (err) {\n        console.warn('[noy-db] LiveAggregation upstream unsubscribe threw:', err)\n      }\n    }\n    this.unsubscribes.length = 0\n    this.listeners.clear()\n  }\n}\n\n/**\n * Chainable wrapper returned by `Query.aggregate(spec)`. Holds the\n * execute-records closure and the spec; terminal methods (`run`,\n * `live`) stitch them together in either mode.\n *\n * Why a wrapper instead of two terminal methods on `Query` directly?\n *\n * The `.aggregate(spec)` call is where the spec is bound — both\n * `.run()` and `.live()` need the same spec, and the consumer's\n * fluent style is `query.where(...).aggregate(spec).run()` or\n * `.aggregate(spec).live()`. Wrapping lets the spec be named once\n * and reused for either terminal, and keeps the `Query` class\n * from growing a pair of near-duplicate method overloads\n * (`aggregateRun` / `aggregateLive`) that would be harder to\n * discover.\n */\nexport class Aggregation<R> {\n  constructor(\n    private readonly executeRecords: () => readonly unknown[],\n    private readonly spec: AggregateSpec,\n    private readonly upstreams: readonly AggregationUpstream[],\n  ) {}\n\n  /**\n   * Execute the query and reduce the results synchronously.\n   * Returns the reduced shape matching the spec — e.g. a spec of\n   * `{ total: sum('amount'), n: count() }` returns\n   * `{ total: number, n: number }`.\n   */\n  run(): R {\n    return reduceRecords(this.executeRecords(), this.spec) as unknown as R\n  }\n\n  /**\n   * Build a reactive `LiveAggregation<R>` that re-runs the reduction\n   * whenever any upstream source notifies of a change. The initial\n   * value is computed eagerly in the constructor, so consumers can\n   * read `live.value` immediately after calling `.live()`.\n   *\n   * Always call `live.stop()` when finished — it tears down the\n   * upstream subscriptions. Vue's `onUnmounted` is the canonical\n   * place.\n   *\n   * **Implementation note:** every upstream change triggers a full\n   * re-reduction. Incremental maintenance (O(1) per delta for\n   * sum/count/avg via the reducer protocol's `remove()` method) is a\n   * planned follow-up optimization — the protocol already supports\n   * it, but the executor doesn't drive it yet. Consumers get\n   * correct, reactive values today; future PRs can switch to\n   * delta-based maintenance without changing this API.\n   */\n  live(): LiveAggregation<R> {\n    const recompute = (): R =>\n      reduceRecords(this.executeRecords(), this.spec) as unknown as R\n    return new LiveAggregationImpl<R>(recompute, this.upstreams)\n  }\n}\n\n/**\n * Build a `LiveAggregation<V>` from a recompute closure and a list\n * of upstreams. Exposed so sibling files in the query DSL\n * (currently `groupby.ts`) can reuse the reactive primitive\n * without reaching into `LiveAggregationImpl` directly. This keeps\n * the implementation class private while still allowing planned\n * composition with `.groupBy().aggregate().live()`.\n */\nexport function buildLiveAggregation<V>(\n  recompute: () => V,\n  upstreams: readonly AggregationUpstream[],\n): LiveAggregation<V> {\n  return new LiveAggregationImpl<V>(recompute, upstreams)\n}\n","/**\n * Query DSL `.groupBy()` —.\n *\n * Chains after `.where()` / `.filter()` / `.or()` / `.and()` on a\n * Query and before a reducer spec, so consumers can compute\n * per-bucket aggregates without folding in userland:\n *\n * ```ts\n * const byClient = invoices.query()\n *   .where('status', '==', 'open')\n *   .groupBy('clientId')\n *   .aggregate({ total: sum('amount'), n: count() })\n *   .run()\n * // → [ { clientId: 'c1', total: 5250, n: 3 }, … ]\n * ```\n *\n * Execution pipeline:\n *\n *   1. Run the query's where/filter clauses (same candidate /\n *      filter pipeline as `.aggregate()` directly on Query).\n *   2. Partition the matching records into buckets keyed by\n *      `readPath(record, field)`. JS `Map` preserves insertion\n *      order, so the first-seen key for a bucket determines its\n *      position in the result array — consumers who want a\n *      specific ordering should `.sort()` downstream.\n *   3. Enforce cardinality: warn once per field at 10% of the cap\n *      (10_000 buckets), throw `GroupCardinalityError` at 100% of\n *      the cap (100_000 buckets).\n *   4. For each bucket, build a per-group reducer state and\n *      step every record in the bucket through it.\n *   5. Emit one result row per bucket, shaped as\n *      `{ [field]: key, ...reduced }`.\n *\n * **Null / undefined keys:** `Map` distinguishes `null` from\n * `undefined`, so records with a missing group field get their own\n * bucket, and records with an explicit `null` value get a separate\n * bucket from that. Consumers who want them merged can coalesce\n * upstream with `.filter()`.\n *\n * **Live mode:** `.groupBy().aggregate().live()` re-runs the full\n * grouping pipeline on every source change. Per-bucket incremental\n * delta maintenance is a future optimization — the reducer\n * protocol's `remove()` hook admits it, but ships naive\n * re-grouping for simplicity.\n *\n * **Type-level stable-key narrowing:** when\n * `dictKey` lands, `groupBy<DictField>()` will narrow the group key\n * type to the stable dictionary key rather than the resolved locale\n * label. That prevents grouping by the locale-resolved label,\n * which would produce different buckets per reader. types the\n * key as `unknown` at the result shape; the dictKey narrowing\n * layers on top without an API break.\n *\n * Partition-awareness seam: when partitioned collections land,\n * per-partition grouping will need to merge sub-results across\n * partitions. The reducer protocol's `{ seed }` parameter\n * (already plumbed through in `reducers.ts`) is the mechanism —\n * groupBy doesn't need its own seam for the moment, because it\n * delegates to the reducer protocol for all per-bucket state.\n */\n\nimport { readPath } from '../query/predicate.js'\nimport type {\n  AggregateSpec,\n  AggregateResult,\n  AggregationUpstream,\n  LiveAggregation,\n} from './aggregation.js'\nimport { buildLiveAggregation } from './aggregation.js'\nimport { GroupCardinalityError } from '../errors.js'\n\n/**\n * Cardinality thresholds for `.groupBy()`. The warn threshold gives\n * consumers a heads-up before the hard error; the cap is a fixed\n * constant in (not overridable). A `{ maxGroups }` override\n * can be added later without a break if a real consumer asks.\n */\nexport const GROUPBY_WARN_CARDINALITY = 10_000\nexport const GROUPBY_MAX_CARDINALITY = 100_000\n\n/**\n * One-shot warning dedup per-field — reactive dashboards\n * re-executing the same grouped query should produce the warning\n * once, not once per re-fire. Keyed on the grouping field name\n * because \"this field has high cardinality on your current data\"\n * is a field-level property, not a per-query one.\n */\nconst warnedCardinalityFields = new Set<string>()\nfunction warnCardinalityApproaching(field: string, observed: number): void {\n  if (warnedCardinalityFields.has(field)) return\n  warnedCardinalityFields.add(field)\n  console.warn(\n    `[noy-db] .groupBy(\"${field}\") produced ${observed} distinct groups, ` +\n      `${Math.round((observed / GROUPBY_MAX_CARDINALITY) * 100)}% of the ` +\n      `${GROUPBY_MAX_CARDINALITY}-group ceiling. Narrow the query with ` +\n      `.where() before grouping, or switch to a lower-cardinality field.`,\n  )\n}\n\n/**\n * Test-only: clear the per-field cardinality warning dedup between\n * tests. Production code never calls this — matching the\n * `resetJoinWarnings` pattern in `join.ts`.\n */\nexport function resetGroupByWarnings(): void {\n  warnedCardinalityFields.clear()\n}\n\n/**\n * Result row shape for a grouped aggregation. Each row carries the\n * group key value under the grouping field name plus every reducer\n * output from the spec.\n *\n * types the group key as `unknown` at the result shape — the\n * runtime read via `readPath` can return any value, and narrowing\n * to a specific type would require the caller to assert at the\n * call site. `dictKey` narrowing layers on top of this by\n * adding an overload that constrains `F` when the grouping field\n * is a `dictKey`.\n */\nexport type GroupedRow<F extends string, R> = { [K in F]: unknown } & R\n\n/**\n * Chainable wrapper returned by `Query.groupBy(field)`. Terminates\n * with `.aggregate(spec)` which returns a `GroupedAggregation`.\n *\n * Kept minimal — the only operation on a grouped query is\n * aggregation. Ordering, limiting, and further filtering belong on\n * the underlying `Query` before `.groupBy()` is called; applying\n * them post-group would be a different operation (`having` /\n * `groupOrderBy`), out of scope for.\n */\nexport class GroupedQuery<T, F extends string> {\n  constructor(\n    private readonly executeRecords: () => readonly unknown[],\n    private readonly field: F,\n    private readonly upstreams: readonly AggregationUpstream[],\n    /**\n     * Optional dict label resolver attached by the query builder when\n     * the grouping field is a dictKey.\n     */\n    private readonly dictLabelResolver?: (\n      key: string,\n      locale: string,\n      fallback?: string | readonly string[],\n    ) => Promise<string | undefined>,\n  ) {\n    // T is phantom on the wrapper so consumers can still see the\n    // source row type on hover. Reference it to keep lint quiet.\n    void undefined as T | undefined\n  }\n\n  /**\n   * Build a grouped aggregation. Returns a `GroupedAggregation`\n   * with `.run()`, `.runAsync()`, and `.live()` terminals — same shape\n   * as the non-grouped `.aggregate()` wrapper, just with an array\n   * result (one row per bucket) instead of a single reduced object.\n   */\n  aggregate<Spec extends AggregateSpec>(\n    spec: Spec,\n  ): GroupedAggregation<GroupedRow<F, AggregateResult<Spec>>> {\n    return new GroupedAggregation<GroupedRow<F, AggregateResult<Spec>>>(\n      this.executeRecords,\n      this.field,\n      spec,\n      this.upstreams,\n      this.dictLabelResolver,\n    )\n  }\n}\n\n/**\n * Execute the group-and-reduce pipeline. Pure function over a\n * record array and a spec — shared by `GroupedAggregation.run()`\n * and the live-mode refresh path. Exported for tests and for any\n * future `scan().groupBy().aggregate()` reuse.\n *\n * Enforces the cardinality cap incrementally during the partition\n * loop, so a runaway grouping throws at the moment the 100_001st\n * bucket would be created — the consumer doesn't have to wait for\n * the full partition to materialize before the error fires.\n */\nexport function groupAndReduce<R>(\n  records: readonly unknown[],\n  field: string,\n  spec: AggregateSpec,\n): R[] {\n  // Map preserves insertion order natively (ES2015), so first-seen\n  // keys determine output ordering without a parallel order array.\n  const buckets = new Map<unknown, unknown[]>()\n  for (const record of records) {\n    const key = readPath(record, field)\n    let bucket = buckets.get(key)\n    if (bucket === undefined) {\n      if (buckets.size >= GROUPBY_MAX_CARDINALITY) {\n        throw new GroupCardinalityError(\n          field,\n          buckets.size + 1,\n          GROUPBY_MAX_CARDINALITY,\n        )\n      }\n      bucket = []\n      buckets.set(key, bucket)\n    }\n    bucket.push(record)\n  }\n\n  if (buckets.size >= GROUPBY_WARN_CARDINALITY) {\n    warnCardinalityApproaching(field, buckets.size)\n  }\n\n  // Reduce each bucket through the spec. Same init/step/finalize\n  // pipeline as `reduceRecords` in aggregate.ts, but one state per\n  // bucket. Inlining the loop here keeps the per-bucket path tight\n  // — calling `reduceRecords` per bucket would recompute\n  // `Object.keys(spec)` once per bucket unnecessarily.\n  const keys = Object.keys(spec)\n  const out: R[] = []\n  for (const [groupKey, bucketRecords] of buckets) {\n    const state: Record<string, unknown> = {}\n    for (const key of keys) {\n      state[key] = spec[key]!.init()\n    }\n    for (const record of bucketRecords) {\n      for (const key of keys) {\n        state[key] = spec[key]!.step(state[key], record)\n      }\n    }\n    const row: Record<string, unknown> = { [field]: groupKey }\n    for (const key of keys) {\n      row[key] = spec[key]!.finalize(state[key])\n    }\n    out.push(row as unknown as R)\n  }\n  return out\n}\n\n/**\n * Grouped aggregation wrapper — the `.groupBy(field).aggregate(spec)`\n * terminal. Shape mirrors `Aggregation<R>` from aggregate.ts: two\n * terminals (`.run()` and `.live()`), spec bound at construction\n * time, upstreams collected for live mode.\n *\n * The generic `R` is the per-row result shape (i.e. a single\n * grouped row), and the terminals return `R[]` — one row per\n * bucket.\n */\nexport class GroupedAggregation<R> {\n  constructor(\n    private readonly executeRecords: () => readonly unknown[],\n    private readonly field: string,\n    private readonly spec: AggregateSpec,\n    private readonly upstreams: readonly AggregationUpstream[],\n    /**\n     * Optional dict label resolver for `<field>Label` projection\n     *. Present when the grouping field is a dictKey.\n     */\n    private readonly dictLabelResolver?: (\n      key: string,\n      locale: string,\n      fallback?: string | readonly string[],\n    ) => Promise<string | undefined>,\n  ) {}\n\n  /** Execute the query, group, reduce, and return an array of rows. */\n  run(): R[] {\n    return groupAndReduce<R>(this.executeRecords(), this.field, this.spec)\n  }\n\n  /**\n   * Execute the query, group, reduce, and resolve `<field>Label` for\n   * each result row when the grouping field is a `dictKey` and a\n   * `locale` is provided. Returns `R[]` synchronously when\n   * no locale is specified (identical to `.run()`).\n   *\n   * The `<field>Label` field is appended to each row. Rows whose group\n   * key has no dictionary entry get `<field>Label: undefined`.\n   */\n  async runAsync(opts?: {\n    locale?: string\n    fallback?: string | readonly string[]\n  }): Promise<R[]> {\n    const rows = groupAndReduce<R>(this.executeRecords(), this.field, this.spec)\n    if (!opts?.locale || !this.dictLabelResolver) return rows\n\n    const resolve = this.dictLabelResolver\n    const locale = opts.locale\n    const fallback = opts.fallback\n    const labelKey = `${this.field}Label`\n\n    return Promise.all(\n      rows.map(async (row) => {\n        const key = (row as Record<string, unknown>)[this.field]\n        if (typeof key !== 'string') return row\n        const label = await resolve(key, locale, fallback)\n        return { ...(row as Record<string, unknown>), [labelKey]: label } as unknown as R\n      }),\n    )\n  }\n\n  /**\n   * Build a reactive `LiveAggregation<R[]>` that re-runs the full\n   * group-and-reduce pipeline whenever any upstream source notifies\n   * of a change. Same error-isolation and idempotent-stop contract\n   * as `Aggregation.live()` — the implementation delegates to the\n   * same `LiveAggregationImpl` class by threading a fresh\n   * recompute closure through the existing constructor.\n   *\n   * uses naive full re-run on every change. Incremental\n   * per-bucket maintenance (apply `step` on inserted records,\n   * `remove` on deleted records, route by bucket key) is a future\n   * optimization — the reducer protocol admits it, but wiring\n   * delta-aware source subscriptions is a separate PR.\n   *\n   * Always call `live.stop()` when finished.\n   */\n  live(): LiveAggregation<R[]> {\n    const recompute = (): R[] =>\n      groupAndReduce<R>(this.executeRecords(), this.field, this.spec)\n    return buildLiveAggregation<R[]>(recompute, this.upstreams)\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-WDM5XGGS.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/validation.ts","../src/meta/user-envelope/types.ts","../src/meta/user-envelope/storage.ts","../src/team/keyring.ts"],"sourcesContent":["/**\n * Passphrase validation — phrase format (per the three-tier session-tiers\n * design, locked 2026-05-04).\n *\n * Passphrases are **phrases**: multiple simple words, easy to remember,\n * structurally constrained so a weak choice cannot silently collapse the\n * security floor. The format is intentionally narrow: lowercase letters\n * and single spaces only, no punctuation, no symbols, no digits.\n *\n * - Default minimum: 6 words (~77 bits with the 7,776-word EFF list).\n * - Strict minimum: 8 words (~103 bits).\n * - Per-word minimum: 3 characters (excludes \"a\", \"is\", \"of\").\n * - Adjacent repeats rejected (\"the the\").\n *\n * The hub runs validation default-on at every passphrase ingress\n * (`createOwnerKeyring`, `grant`, `rotatePassphrase`); test fixtures and\n * CLI scripts override via `{ allowWeakPassphrase: true }`.\n *\n * @module\n */\nimport { NoydbError, ValidationError } from './errors.js'\n\n/** All reasons a phrase can be rejected. */\nexport type WeakPassphraseReason =\n  | 'empty'\n  | 'invalid-chars'\n  | 'leading-or-trailing-space'\n  | 'double-space'\n  | 'too-few-words'\n  | 'word-too-short'\n  | 'repeated-adjacent'\n\n/** Per-vault knobs. Aligns with `VaultPolicy.passphrase`. */\nexport interface PassphrasePolicy {\n  /** Minimum number of words. Default 6. Strict policy uses 8. */\n  readonly minWords?: number\n  /** Minimum characters per word. Default 3. */\n  readonly minWordLength?: number\n  /** Reject adjacent identical words (\"the the\"). Default true. */\n  readonly rejectRepeatedAdjacent?: boolean\n  /**\n   * Override the default character-class rule (`/^[a-z]+( [a-z]+)*$/`).\n   *\n   * The hub's strict default is lowercase-letters-and-single-spaces\n   * because that's what the EFF wordlist generator emits and what\n   * most attacker password lists are keyed on. Use this knob to allow\n   * digits, uppercase, hyphens, or non-Latin scripts when the\n   * consumer's audience needs them — e.g.:\n   *\n   * ```ts\n   * // Thai + English mix with digits permitted\n   * pattern: /^[\\p{L}0-9 ]+( [\\p{L}0-9 ]+)*$/u\n   *\n   * // Allow uppercase + hyphens (passphrase-with-hyphens style)\n   * pattern: /^[A-Za-z]+([- ][A-Za-z]+)*$/\n   * ```\n   *\n   * The OTHER structural rules still apply (min-words split by space,\n   * min-word-length, repeated-adjacent, leading/trailing whitespace,\n   * double-space). For non-space-delimited word semantics, use\n   * {@link customValidator} instead.\n   *\n   * Added in pre.8 (#31).\n   */\n  readonly pattern?: RegExp\n  /**\n   * Replace ALL validation entirely with a custom function. When set,\n   * none of the other PassphrasePolicy fields apply — the consumer\n   * owns every rule (word splitting, character classes, entropy\n   * thresholds, allowlist/denylist). Use sparingly; this is the\n   * escape hatch for domain-specific phrase formats:\n   *\n   *   - Localized wordlists with non-space word boundaries\n   *   - BIP-39 seed phrases (24 words, fixed wordlist, etc.)\n   *   - Organization-specific HR password policies\n   *\n   * The returned `PassphraseValidationResult` is what\n   * {@link assertStrongPassphrase} dispatches on — `ok: true` accepts;\n   * `ok: false` throws `WeakPassphraseError` with the supplied reason.\n   *\n   * Added in pre.8 (#31).\n   */\n  readonly customValidator?: (phrase: string) => PassphraseValidationResult\n}\n\n/** Result of a check. Discriminated union — compile-time exhaustive. */\nexport type PassphraseValidationResult =\n  | { readonly ok: true; readonly words: number }\n  | {\n      readonly ok: false\n      readonly reason: WeakPassphraseReason\n      readonly minimum?: number\n      readonly got?: number\n    }\n\n/**\n * Thrown by `assertStrongPassphrase()` and by every hub ingress\n * point (`createOwnerKeyring`, `grant`, `rotatePassphrase`) when a\n * supplied phrase fails the structural rules above.\n */\nexport class WeakPassphraseError extends NoydbError {\n  readonly reason: WeakPassphraseReason\n  readonly suggestion: string\n  constructor(reason: WeakPassphraseReason, suggestion: string) {\n    super('WEAK_PASSPHRASE', `Weak passphrase (${reason}). ${suggestion}`)\n    this.name = 'WeakPassphraseError'\n    this.reason = reason\n    this.suggestion = suggestion\n  }\n}\n\nconst DEFAULT_MIN_WORDS = 6\nconst DEFAULT_MIN_WORD_LENGTH = 3\n\nconst SUGGESTIONS: Record<WeakPassphraseReason, string> = {\n  empty: 'Provide a phrase of at least 6 lowercase words separated by single spaces.',\n  'invalid-chars':\n    'Use only lowercase letters [a-z] and single spaces. No punctuation, symbols, digits, or uppercase.',\n  'leading-or-trailing-space': 'Trim leading and trailing spaces.',\n  'double-space': 'Use exactly one space between words.',\n  'too-few-words':\n    'Use at least 6 words by default (8 under strict policy). Example: \"correct horse battery staple printer toaster\".',\n  'word-too-short': 'Each word must be at least 3 characters. Drop short fillers like \"a\", \"is\", \"of\".',\n  'repeated-adjacent': 'Avoid repeating the same word twice in a row.',\n}\n\n/**\n * Inspect a phrase against the format rules and return a structured\n * verdict. Never throws — callers either branch on `ok` or pass the\n * result to {@link assertStrongPassphrase} for the throwing flavour.\n */\nexport function validatePassphrase(\n  s: string,\n  opts?: PassphrasePolicy,\n): PassphraseValidationResult {\n  // Escape hatch: customValidator owns the entire decision. None of\n  // the structural rules below run when this is set — the consumer is\n  // responsible for the full validation contract.\n  if (opts?.customValidator) {\n    return opts.customValidator(s)\n  }\n\n  const minWords = opts?.minWords ?? DEFAULT_MIN_WORDS\n  const minWordLength = opts?.minWordLength ?? DEFAULT_MIN_WORD_LENGTH\n  const rejectRepeated = opts?.rejectRepeatedAdjacent ?? true\n\n  if (s.length === 0) {\n    return { ok: false, reason: 'empty' }\n  }\n\n  if (s !== s.trim()) {\n    return { ok: false, reason: 'leading-or-trailing-space' }\n  }\n\n  if (s.includes('  ')) {\n    return { ok: false, reason: 'double-space' }\n  }\n\n  // The default character class is lowercase-letters-and-spaces;\n  // consumers can override via PassphrasePolicy.pattern (e.g. to\n  // allow digits, uppercase, or non-Latin scripts). Word splitting\n  // below remains space-based — for non-space word semantics the\n  // consumer should use customValidator instead.\n  const charPattern = opts?.pattern ?? /^[a-z]+( [a-z]+)*$/\n  if (!charPattern.test(s)) {\n    return { ok: false, reason: 'invalid-chars' }\n  }\n\n  const words = s.split(' ')\n\n  if (words.length < minWords) {\n    return { ok: false, reason: 'too-few-words', minimum: minWords, got: words.length }\n  }\n\n  for (const w of words) {\n    if (w.length < minWordLength) {\n      return { ok: false, reason: 'word-too-short', minimum: minWordLength, got: w.length }\n    }\n  }\n\n  if (rejectRepeated) {\n    for (let i = 1; i < words.length; i++) {\n      if (words[i] === words[i - 1]) {\n        return { ok: false, reason: 'repeated-adjacent' }\n      }\n    }\n  }\n\n  return { ok: true, words: words.length }\n}\n\n/**\n * Throw {@link WeakPassphraseError} when the phrase fails. Used by\n * `createOwnerKeyring`, `grant`, and `rotatePassphrase` at ingress.\n *\n * Pass `{ allowWeakPassphrase: true }` to bypass — intended for test\n * fixtures, CLI scripts, and dev environments. The override never\n * loosens the cryptographic key derivation; it only relaxes the\n * structural-strength gate.\n */\nexport function assertStrongPassphrase(\n  s: string,\n  opts?: PassphrasePolicy & { allowWeakPassphrase?: boolean },\n): void {\n  if (opts?.allowWeakPassphrase) return\n  const result = validatePassphrase(s, opts)\n  if (result.ok) return\n  throw new WeakPassphraseError(result.reason, SUGGESTIONS[result.reason])\n}\n\n/**\n * Estimate the entropy of a phrase, given the EFF 7,776-word list as\n * the assumed wordlist. ~12.9 bits per word.\n *\n * Returns 0 for any input that fails the phrase format — character-class\n * estimates aren't comparable to phrase entropy, and surfacing 0 makes\n * weak inputs visible in any UI that displays an entropy meter.\n */\nexport function estimateEntropy(passphrase: string): number {\n  const result = validatePassphrase(passphrase)\n  if (!result.ok) return 0\n  return Math.round(result.words * Math.log2(7776))\n}\n\n/**\n * Internal compatibility shim. Older code paths used the throwing\n * `validatePassphrase(s)` directly; some still do via re-exports. Routes\n * to the new `assertStrongPassphrase` so the contract holds for both\n * shapes during the transition. New code should call\n * {@link assertStrongPassphrase} directly.\n *\n * @internal\n */\nexport function legacyAssertPassphrase(s: string): void {\n  try {\n    assertStrongPassphrase(s)\n  } catch (err) {\n    if (err instanceof WeakPassphraseError) {\n      throw new ValidationError(err.message)\n    }\n    throw err\n  }\n}\n","/**\n * Type surface for the per-principal user envelope subsystem.\n *\n * @see docs/superpowers/specs/2026-05-05-user-envelope-design.md\n *\n * @module\n */\nimport { NoydbError } from '../../errors.js'\n\n/**\n * Thin reader view of a user envelope. The on-disk shape is the standard\n * {@link import('../../types.js').EncryptedEnvelope}; this is what callers\n * see after the storage layer has decrypted the payload.\n *\n * Hub commits to the `keyringId` ⇔ `userId` identity and the `_v` / `_ts`\n * envelope metadata. The `data` payload is fully app-defined — hub does\n * not introspect, validate, or reserve any keys inside it.\n */\nexport interface UserEnvelope<T> {\n  /** The principal id this envelope belongs to. Equals the keyring `user_id`. */\n  readonly keyringId: string\n  /** App-owned payload. Opaque to hub. */\n  readonly data: T\n  /** Optimistic-concurrency version. Increments on every write. */\n  readonly _v: number\n  /** ISO timestamp of the last write. */\n  readonly _ts: string\n}\n\n/**\n * Soft cap on the JSON-serialized payload size. Generous (a typical\n * profile + preferences + small app annex is ~1 KiB); rejects accidental\n * \"stuff app state in here\" anti-patterns.\n */\nexport const USER_ENVELOPE_MAX_BYTES = 64 * 1024\n\n/**\n * Reserved store collection name for user envelopes. Starts with `_` so the\n * keyring grant machinery propagates the DEK to every granted user via the\n * existing system-collection DEK propagation path in `team/keyring.ts`.\n */\nexport const USER_ENVELOPE_COLLECTION = '_users'\n\n/**\n * Thrown when a user-envelope payload exceeds {@link USER_ENVELOPE_MAX_BYTES}\n * after JSON-serialization. The error carries the actual size so callers\n * can decide whether to trim or split.\n */\nexport class UserEnvelopeOversizedError extends NoydbError {\n  readonly bytes: number\n  readonly limit: number\n  constructor(bytes: number, limit: number = USER_ENVELOPE_MAX_BYTES) {\n    super(\n      'USER_ENVELOPE_OVERSIZED',\n      `User envelope payload is ${bytes} bytes; soft cap is ${limit} bytes. ` +\n        `Move large data into the vault's regular collections.`,\n    )\n    this.name = 'UserEnvelopeOversizedError'\n    this.bytes = bytes\n    this.limit = limit\n  }\n}\n","/**\n * Persistence helpers for per-principal user envelopes stored at\n * `_users/<keyringId>` (logically: `_meta/user/<keyringId>`).\n *\n * Unlike `_meta/policy` and `_meta/handle` which are plaintext, user\n * envelopes carry user data and are encrypted with a dedicated\n * {@link USER_ENVELOPE_COLLECTION} DEK (provisioned at vault open and\n * propagated to every keyring via the system-collection DEK path in\n * `team/keyring.ts`).\n *\n * This module is the **storage primitive** layer. The public API\n * (`vault.user.*`) sits on top of this; permission gates, own-only\n * write enforcement, and presence-channel propagation live there.\n *\n * @see docs/superpowers/specs/2026-05-05-user-envelope-design.md\n *\n * @module\n */\nimport type { NoydbStore, EncryptedEnvelope } from '../../types.js'\nimport { NOYDB_FORMAT_VERSION } from '../../types.js'\nimport { encrypt, decrypt } from '../../crypto.js'\nimport { ConflictError } from '../../errors.js'\nimport {\n  USER_ENVELOPE_COLLECTION,\n  USER_ENVELOPE_MAX_BYTES,\n  UserEnvelopeOversizedError,\n  type UserEnvelope,\n} from './types.js'\n\n/**\n * Read and decrypt the user envelope for `keyringId`. Returns `null`\n * when no envelope has been persisted (either the principal has never\n * called `updateMe`, or the keyring predates this feature).\n *\n * Decryption errors propagate — a tampered or wrong-keyed envelope\n * surfaces as the underlying crypto error rather than masquerading as\n * \"not found\".\n */\nexport async function loadUserEnvelope<T = unknown>(\n  store: NoydbStore,\n  vault: string,\n  keyringId: string,\n  dek: CryptoKey,\n): Promise<UserEnvelope<T> | null> {\n  const envelope = await store.get(vault, USER_ENVELOPE_COLLECTION, keyringId)\n  if (!envelope) return null\n  const plaintext = await decrypt(envelope._iv, envelope._data, dek)\n  const data = JSON.parse(plaintext) as T\n  return {\n    keyringId,\n    data,\n    _v: envelope._v,\n    _ts: envelope._ts,\n  }\n}\n\n/**\n * Encrypt and persist the user envelope for `keyringId`. The new\n * version is `(prior._v ?? 0) + 1`. Pass `expectedVersion` to enable\n * optimistic-concurrency checks: a mismatch with the stored version\n * throws {@link ConflictError} with the actual stored version.\n *\n * `expectedVersion: 0` means \"expect no prior envelope\"; the write\n * succeeds only if no envelope exists yet.\n *\n * Soft-caps the JSON-serialized payload at {@link USER_ENVELOPE_MAX_BYTES};\n * larger payloads throw {@link UserEnvelopeOversizedError}.\n */\nexport async function saveUserEnvelope<T>(\n  store: NoydbStore,\n  vault: string,\n  keyringId: string,\n  payload: T,\n  dek: CryptoKey,\n  expectedVersion?: number,\n): Promise<UserEnvelope<T>> {\n  const json = JSON.stringify(payload)\n  // TextEncoder counts bytes correctly for multi-byte UTF-8 (Thai text,\n  // emoji, etc.) — JSON.stringify().length would undercount.\n  const bytes = new TextEncoder().encode(json).byteLength\n  if (bytes > USER_ENVELOPE_MAX_BYTES) {\n    throw new UserEnvelopeOversizedError(bytes)\n  }\n\n  const prior = await store.get(vault, USER_ENVELOPE_COLLECTION, keyringId)\n  if (expectedVersion !== undefined) {\n    const priorVersion = prior?._v ?? 0\n    if (priorVersion !== expectedVersion) {\n      throw new ConflictError(\n        priorVersion,\n        `User envelope for \"${keyringId}\" expected version ${expectedVersion}, ` +\n          `actual ${priorVersion}`,\n      )\n    }\n  }\n\n  const nextVersion = (prior?._v ?? 0) + 1\n  const ts = new Date().toISOString()\n  const { iv, data } = await encrypt(json, dek)\n\n  const envelope: EncryptedEnvelope = {\n    _noydb: NOYDB_FORMAT_VERSION,\n    _v: nextVersion,\n    _ts: ts,\n    _iv: iv,\n    _data: data,\n  }\n  await store.put(vault, USER_ENVELOPE_COLLECTION, keyringId, envelope)\n\n  return {\n    keyringId,\n    data: payload,\n    _v: nextVersion,\n    _ts: ts,\n  }\n}\n\n/**\n * Delete the user envelope for `keyringId`. Idempotent — no error if\n * the envelope is already absent. Called from the keyring revoke path\n * (cascade-delete) and is a no-op for keyrings that never wrote.\n */\nexport async function deleteUserEnvelope(\n  store: NoydbStore,\n  vault: string,\n  keyringId: string,\n): Promise<void> {\n  await store.delete(vault, USER_ENVELOPE_COLLECTION, keyringId)\n}\n\n/**\n * List the keyring ids that have a user envelope persisted in `vault`.\n * Order is store-defined — callers that need a stable order should sort.\n */\nexport async function listUserEnvelopeIds(\n  store: NoydbStore,\n  vault: string,\n): Promise<string[]> {\n  return store.list(vault, USER_ENVELOPE_COLLECTION)\n}\n","import type { NoydbStore, KeyringFile, KeyringAuthenticator, Role, Permissions, GrantOptions, RevokeOptions, UpdateUserOptions, UserInfo, EncryptedEnvelope, ExportCapability, ExportFormat, ImportCapability, VaultPolicyOnDisk } from '../types.js'\nimport { NOYDB_KEYRING_VERSION, NOYDB_FORMAT_VERSION } from '../types.js'\nimport {\n  deriveKey,\n  generateDEK,\n  generateSalt,\n  wrapKey,\n  unwrapKey,\n  encrypt,\n  decrypt,\n  bufferToBase64,\n  base64ToBuffer,\n} from '../crypto.js'\nimport { NoAccessError, PermissionDeniedError, PrivilegeEscalationError, KeyringExpiredError, ValidationError } from '../errors.js'\nimport { assertStrongPassphrase, type PassphrasePolicy } from '../validation.js'\nimport {\n  saveUserEnvelope,\n  loadUserEnvelope as loadUserEnvelopeFn,\n  deleteUserEnvelope,\n  USER_ENVELOPE_COLLECTION,\n  type UserEnvelope as UserEnvelopeReader,\n} from '../meta/user-envelope/index.js'\n\n// ─── Roles that can grant/revoke ───────────────────────────────────────\n\n/**\n * Roles that an `admin` is allowed to grant and revoke.\n *\n * Includes `'admin'` itself: the model bottlenecked all admin\n * onboarding through the single `owner` principal, which made lateral\n * delegation impossible and left a single-owner bus-factor risk\n * unresolved even when multiple trusted humans existed. opens up\n * admin↔admin lateral delegation, with two guardrails:\n *\n *   1. **No privilege escalation.** Enforced in `grant()`: every DEK\n *      wrapped into the new admin's keyring must be present in the\n *      grantor's own DEK set. Today this is structurally trivially\n *      true (admin grants always inherit the full caller DEK set),\n *      but the check is wired in so future per-collection admin scoping\n *      cannot accidentally bypass it. See `PrivilegeEscalationError`.\n *\n *   2. **Cascade on revoke.** Enforced in `revoke()`: when an admin is\n *      revoked, every admin they (transitively) granted is either\n *      revoked too (`cascade: 'strict'`, default) or left in place with\n *      a console warning (`cascade: 'warn'`). The walk uses the\n *      `granted_by` field on each keyring file as the parent pointer.\n */\nconst ADMIN_GRANTABLE_TARGETS: readonly Role[] = ['operator', 'viewer', 'client', 'admin']\n\nfunction canGrant(callerRole: Role, targetRole: Role): boolean {\n  if (callerRole === 'owner') return true\n  if (callerRole === 'admin') return ADMIN_GRANTABLE_TARGETS.includes(targetRole)\n  return false\n}\n\nfunction canRevoke(callerRole: Role, targetRole: Role): boolean {\n  if (targetRole === 'owner') return false // owner cannot be revoked\n  if (callerRole === 'owner') return true\n  if (callerRole === 'admin') return ADMIN_GRANTABLE_TARGETS.includes(targetRole)\n  return false\n}\n\n/**\n * Whether `callerRole` can mutate a keyring whose role is (or becomes)\n * `targetRole`. Used by `updateKeyringIdentity` (#54).\n *\n * Mirrors `canGrant`'s hierarchy: admins manage admin/operator/viewer/\n * client laterally; admins cannot create or destroy `owner`-shaped\n * keyrings. Owner can do anything.\n *\n * Both the OLD role and the NEW role must satisfy this check —\n * otherwise admin could elevate themselves (`admin → owner`) or demote\n * an owner (`owner → admin`) under cover of \"update.\"\n */\nfunction canUpdateRole(callerRole: Role, targetRole: Role): boolean {\n  if (callerRole === 'owner') return true\n  if (callerRole === 'admin') return ADMIN_GRANTABLE_TARGETS.includes(targetRole)\n  return false\n}\n\n// ─── Unlocked Keyring ──────────────────────────────────────────────────\n\n/** In-memory representation of an unlocked keyring. */\nexport interface UnlockedKeyring {\n  readonly userId: string\n  readonly displayName: string\n  readonly role: Role\n  readonly permissions: Permissions\n  readonly deks: Map<string, CryptoKey>\n  /**\n   * The KEK, when this keyring was unlocked via tier 1 (passphrase) or\n   * a wrap-KEK tier-2 method (WebAuthn / OIDC). `null` when the\n   * keyring was opened via:\n   *\n   *   - Unencrypted mode (no KEK exists)\n   *   - Tier-3 PIN quick-resume (`@noy-db/on-pin`)\n   *   - Wrap-DEKs tier-2 unlock (`@noy-db/on-password`'s\n   *     `verifyPasswordSlot` after #26 Path C)\n   *   - Session-state restore (`session/session.ts`)\n   *   - Dev-unlock fixture (`session/dev-unlock.ts`)\n   *\n   * Consumers performing tier-1 operations that need the KEK\n   * (DEK rewrap, keyring persist, delegation issue/unwrap) must\n   * null-check and throw a clear error if absent — re-authenticate\n   * at tier 1 first to recover the KEK.\n   *\n   * Tightened from `CryptoKey` to `CryptoKey | null` in pre.8 (#41).\n   * The runtime contract has always allowed null; the type now\n   * matches reality.\n   */\n  readonly kek: CryptoKey | null\n  readonly salt: Uint8Array\n  /**\n   * `@noy-db/as-*` export capability. Absent when the\n   * keyring was written before this RFC landed — role-based defaults\n   * apply via `hasExportCapability`.\n   */\n  readonly exportCapability?: ExportCapability\n  /**\n   * `@noy-db/as-*` import capability (issue ). Absent when the\n   * keyring was written before  landed — default-closed semantics\n   * apply via `hasImportCapability` (no plaintext format granted, no\n   * bundle import granted, regardless of role).\n   */\n  readonly importCapability?: ImportCapability\n  /**\n   * Tier-2 authenticator slots — readonly snapshot loaded from the\n   * keyring file. Mutations go through `enrollAuthenticator` /\n   * `removeAuthenticator` (issue #11), which write back via\n   * `persistKeyring`. Always defined; loads with an empty array for\n   * keyrings written before the multi-slot extension landed.\n   */\n  readonly authenticators: readonly KeyringAuthenticator[]\n  /**\n   * Reserved per-keyring policy override (forward-compat for Option C\n   * — see {@link VaultPolicyOnDisk}). v1.0 round-trips this field but\n   * never enforces it; the gate engine uses `_meta/policy` only.\n   */\n  readonly policy?: VaultPolicyOnDisk\n}\n\n// ─── Load / Create ─────────────────────────────────────────────────────\n\n/** Load and unlock a user's keyring for a vault. */\nexport async function loadKeyring(\n  adapter: NoydbStore,\n  vault: string,\n  userId: string,\n  passphrase: string,\n): Promise<UnlockedKeyring> {\n  const envelope = await adapter.get(vault, '_keyring', userId)\n\n  if (!envelope) {\n    throw new NoAccessError(`No keyring found for user \"${userId}\" in vault \"${vault}\"`)\n  }\n\n  const keyringFile = JSON.parse(envelope._data) as KeyringFile\n\n  //  — refuse to unwrap an expired slot. Check happens before any\n  // KEK derivation so an expired slot doesn't leak timing on the\n  // passphrase. Comparison uses Date.parse → ms-since-epoch; an\n  // unparseable expires_at is treated as \"no expiry\" so a malformed\n  // value can't silently lock users out (it'll surface in tests).\n  if (keyringFile.expires_at !== undefined) {\n    const cutoff = Date.parse(keyringFile.expires_at)\n    if (Number.isFinite(cutoff) && Date.now() >= cutoff) {\n      throw new KeyringExpiredError({ userId: keyringFile.user_id, expiresAt: keyringFile.expires_at })\n    }\n  }\n\n  const salt = base64ToBuffer(keyringFile.salt)\n  const kek = await deriveKey(passphrase, salt)\n\n  const deks = new Map<string, CryptoKey>()\n  for (const [collName, wrappedDek] of Object.entries(keyringFile.deks)) {\n    const dek = await unwrapKey(wrappedDek, kek)\n    deks.set(collName, dek)\n  }\n\n  return {\n    userId: keyringFile.user_id,\n    displayName: keyringFile.display_name,\n    role: keyringFile.role,\n    permissions: keyringFile.permissions,\n    deks,\n    kek,\n    salt,\n    authenticators: keyringFile.authenticators ?? [],\n    ...(keyringFile.export_capability !== undefined && { exportCapability: keyringFile.export_capability }),\n    ...(keyringFile.import_capability !== undefined && { importCapability: keyringFile.import_capability }),\n    ...(keyringFile.policy !== undefined && { policy: keyringFile.policy }),\n  }\n}\n\n/**\n * Create the initial owner keyring for a new vault.\n *\n * Pass `{ validate: true }` (or a `PassphrasePolicy`) to gate creation\n * on the phrase-format strength rules — `Noydb` threads this from\n * `NoydbOptions.validatePassphrase`. Direct callers (CLI, scripts,\n * test fixtures) opt in explicitly.\n */\nexport async function createOwnerKeyring(\n  adapter: NoydbStore,\n  vault: string,\n  userId: string,\n  passphrase: string,\n  passphraseOpts?: PassphrasePolicy & { validate?: boolean; allowWeakPassphrase?: boolean },\n): Promise<UnlockedKeyring> {\n  if (passphraseOpts?.validate && !passphraseOpts.allowWeakPassphrase) {\n    assertStrongPassphrase(passphrase, passphraseOpts)\n  }\n  const salt = generateSalt()\n  const kek = await deriveKey(passphrase, salt)\n\n  // Eager-provision the _users DEK at owner creation. This guarantees\n  // every subsequent grant inherits it via the existing\n  // collName.startsWith('_') propagation in grant() — so multi-principal\n  // user-envelope reads (alice reading bob's profile) work for new\n  // vaults without any per-keyring DEK rotation. Pre-existing vaults\n  // get the DEK lazily on first vault.user.* access (which only\n  // materializes a single-principal DEK that won't propagate\n  // retroactively — that's the documented \"lazy creation for\n  // pre-existing keyrings\" rollout note in the spec).\n  const userEnvelopeDek = await generateDEK()\n  const wrappedUserEnvelopeDek = await wrapKey(userEnvelopeDek, kek)\n\n  const keyringFile: KeyringFile = {\n    _noydb_keyring: NOYDB_KEYRING_VERSION,\n    user_id: userId,\n    display_name: userId,\n    role: 'owner',\n    permissions: {},\n    deks: { [USER_ENVELOPE_COLLECTION]: wrappedUserEnvelopeDek },\n    salt: bufferToBase64(salt),\n    created_at: new Date().toISOString(),\n    granted_by: userId,\n  }\n\n  await writeKeyringFile(adapter, vault, userId, keyringFile)\n\n  return {\n    userId,\n    displayName: userId,\n    role: 'owner',\n    permissions: {},\n    deks: new Map([[USER_ENVELOPE_COLLECTION, userEnvelopeDek]]),\n    kek,\n    salt,\n    authenticators: [],\n  }\n}\n\n// ─── Grant ─────────────────────────────────────────────────────────────\n\n/** Grant access to a new user. Caller must have grant privilege. */\nexport async function grant(\n  adapter: NoydbStore,\n  vault: string,\n  callerKeyring: UnlockedKeyring,\n  options: GrantOptions,\n): Promise<void> {\n  if (!canGrant(callerKeyring.role, options.role)) {\n    throw new PermissionDeniedError(\n      `Role \"${callerKeyring.role}\" cannot grant role \"${options.role}\"`,\n    )\n  }\n\n  // Optional strength validation — opt-in via grant({ validatePassphrase: true })\n  // or via the calling Noydb's NoydbOptions.validatePassphrase flag.\n  // The override `allowWeakPassphrase: true` skips even when validate is on.\n  if (\n    (options as { validatePassphrase?: boolean }).validatePassphrase &&\n    !options.allowWeakPassphrase\n  ) {\n    assertStrongPassphrase(options.passphrase)\n  }\n\n  // Determine which collections the new user gets access to\n  const permissions = resolvePermissions(options.role, options.permissions)\n\n  // Derive the new user's KEK from their passphrase\n  const newSalt = generateSalt()\n  const newKek = await deriveKey(options.passphrase, newSalt)\n\n  // Wrap the appropriate DEKs with the new user's KEK\n  const wrappedDeks: Record<string, string> = {}\n  for (const collName of Object.keys(permissions)) {\n    const dek = callerKeyring.deks.get(collName)\n    if (dek) {\n      wrappedDeks[collName] = await wrapKey(dek, newKek)\n    }\n  }\n\n  // For owner/admin/viewer roles, wrap ALL known DEKs\n  if (options.role === 'owner' || options.role === 'admin' || options.role === 'viewer') {\n    for (const [collName, dek] of callerKeyring.deks) {\n      if (!(collName in wrappedDeks)) {\n        wrappedDeks[collName] = await wrapKey(dek, newKek)\n      }\n    }\n  }\n\n  // For ALL roles, propagate system-prefixed collection DEKs\n  // (`_ledger`, `_history`, `_sync`, …). These are internal collections\n  // that any user with access to the vault must be able to\n  // read and write — for example, the hash-chained ledger writes\n  // an entry on every put/delete, so operators and clients with write\n  // access to a single data collection still need the `_ledger` DEK.\n  //\n  // Trade-off: a granted user can decrypt every system-collection\n  // entry, including ones they would not otherwise have access to\n  // (e.g., an operator on `invoices` can read ledger entries for\n  // mutations in `salaries`). This is a metadata leak, not a\n  // plaintext leak — the ledger entries record collection names,\n  // record ids, and ciphertext hashes, but never plaintext records.\n  // Per-collection ledger DEKs are tracked as a follow-up.\n  for (const [collName, dek] of callerKeyring.deks) {\n    if (collName.startsWith('_') && !(collName in wrappedDeks)) {\n      wrappedDeks[collName] = await wrapKey(dek, newKek)\n    }\n  }\n\n  // Anti-privilege-escalation check. Every DEK we just\n  // wrapped into the new keyring must come from the caller's own DEK\n  // set — the grantor cannot give the grantee access to a collection\n  // they themselves can't read. Today this is structurally trivially\n  // satisfied because every wrapped DEK was looked up in\n  // `callerKeyring.deks` above, but the explicit check is wired in\n  // so a future change (per-collection admin scoping, escrow-based\n  // re-wrapping, etc.) cannot accidentally let a widening grant\n  // through. See `PrivilegeEscalationError` for the rationale.\n  for (const collName of Object.keys(wrappedDeks)) {\n    if (!callerKeyring.deks.has(collName)) {\n      throw new PrivilegeEscalationError(collName)\n    }\n  }\n\n  const keyringFile: KeyringFile = {\n    _noydb_keyring: NOYDB_KEYRING_VERSION,\n    user_id: options.userId,\n    display_name: options.displayName,\n    role: options.role,\n    permissions,\n    deks: wrappedDeks,\n    salt: bufferToBase64(newSalt),\n    created_at: new Date().toISOString(),\n    granted_by: callerKeyring.userId,\n    ...(options.exportCapability !== undefined && { export_capability: options.exportCapability }),\n    ...(options.importCapability !== undefined && { import_capability: options.importCapability }),\n  }\n\n  await writeKeyringFile(adapter, vault, options.userId, keyringFile)\n\n  // User envelope bootstrap. Seeded with `options.initialProfile` if\n  // provided, otherwise an empty `{}`. Encrypted with the caller's\n  // _users DEK — which is the same DEK that was wrapped into the new\n  // keyring's `wrappedDeks[USER_ENVELOPE_COLLECTION]` above (system-\n  // collection propagation), so the new user can decrypt it on first\n  // open. Skipped silently if the caller has no _users DEK (pre-feature\n  // vault upgrade path — documented \"lazy creation for pre-existing\n  // keyrings\" in the spec).\n  const userEnvelopeDek = callerKeyring.deks.get(USER_ENVELOPE_COLLECTION)\n  if (userEnvelopeDek) {\n    const initialPayload = options.initialProfile ?? {}\n    await saveUserEnvelope(\n      adapter,\n      vault,\n      options.userId,\n      initialPayload,\n      userEnvelopeDek,\n    )\n  }\n}\n\n// ─── Revoke ────────────────────────────────────────────────────────────\n\n/**\n * Walk every keyring in the vault to find admins that the given\n * `rootUserId` (transitively) granted, via the `granted_by` parent\n * pointer recorded on each keyring file.\n *\n * Returns the set of descendant admin user-ids in DFS order, NOT\n * including the root itself. Non-admin descendants are excluded\n * because operators/viewers/clients cannot grant other users — they\n * are leaves in the delegation tree and cleaning them up is the\n * caller's job (or the next rotate, since they'd lose key access\n * anyway when the cascading admin's collections rotate).\n *\n * The walk uses a visited set keyed by user-id so cycles introduced\n * by re-grants (admin-A revoked, then re-granted later by admin-B who\n * was originally granted by A) terminate cleanly.\n */\nasync function findAdminDescendants(\n  adapter: NoydbStore,\n  vault: string,\n  rootUserId: string,\n): Promise<string[]> {\n  const allUserIds = await adapter.list(vault, '_keyring')\n\n  // Build a map: parentUserId → child KeyringFiles. We only ever\n  // descend into admins, so non-admin children are skipped at the\n  // edge level rather than after a recursive call.\n  const childrenByParent = new Map<string, string[]>()\n  for (const userId of allUserIds) {\n    const env = await adapter.get(vault, '_keyring', userId)\n    if (!env) continue\n    const kf = JSON.parse(env._data) as KeyringFile\n    if (kf.role !== 'admin') continue // only admins can grant — leaves are uninteresting\n    if (kf.user_id === rootUserId) continue // self-edges are noise\n    const list = childrenByParent.get(kf.granted_by) ?? []\n    list.push(kf.user_id)\n    childrenByParent.set(kf.granted_by, list)\n  }\n\n  const visited = new Set<string>()\n  const order: string[] = []\n  const stack: string[] = [...(childrenByParent.get(rootUserId) ?? [])]\n  while (stack.length > 0) {\n    const next = stack.pop()!\n    if (visited.has(next)) continue\n    visited.add(next)\n    order.push(next)\n    for (const grandchild of childrenByParent.get(next) ?? []) {\n      if (!visited.has(grandchild)) stack.push(grandchild)\n    }\n  }\n  return order\n}\n\n/** Revoke a user's access. Optionally rotate keys for affected collections. */\nexport async function revoke(\n  adapter: NoydbStore,\n  vault: string,\n  callerKeyring: UnlockedKeyring,\n  options: RevokeOptions,\n): Promise<void> {\n  // Load the target's keyring to check their role\n  const targetEnvelope = await adapter.get(vault, '_keyring', options.userId)\n  if (!targetEnvelope) {\n    throw new NoAccessError(`User \"${options.userId}\" has no keyring in vault \"${vault}\"`)\n  }\n\n  const targetKeyring = JSON.parse(targetEnvelope._data) as KeyringFile\n\n  if (!canRevoke(callerKeyring.role, targetKeyring.role)) {\n    throw new PermissionDeniedError(\n      `Role \"${callerKeyring.role}\" cannot revoke role \"${targetKeyring.role}\"`,\n    )\n  }\n\n  // Cascade-on-revoke. Only meaningful when the target is\n  // an admin — operators/viewers/clients cannot grant other users so\n  // they have no delegation subtree to walk.\n  const cascadeMode = options.cascade ?? 'strict'\n  const usersToRevoke: string[] = [options.userId]\n  const affectedCollections = new Set(Object.keys(targetKeyring.deks))\n\n  if (targetKeyring.role === 'admin') {\n    const descendants = await findAdminDescendants(adapter, vault, options.userId)\n    if (descendants.length > 0) {\n      if (cascadeMode === 'warn') {\n        // Diagnostic mode: leave the descendants in place but make\n        // them visible. The owner / a different admin can clean up\n        // manually. The single console.warn is intentionally noisy\n        // (a list, not a count) so the operator sees exactly which\n        // keyrings will become orphans.\n        console.warn(\n          `[noy-db] revoke(${options.userId}): cascade='warn' — leaving ` +\n            `${descendants.length} descendant admin(s) in place: ` +\n            `${descendants.join(', ')}. These admins were granted by the revoked user ` +\n            `(transitively) and will become orphans in the delegation tree.`,\n        )\n      } else {\n        // Strict mode (default): pull every descendant into the\n        // revoke set. We collect their affected collections too so\n        // the single rotation pass at the end covers everything.\n        for (const userId of descendants) {\n          const descEnv = await adapter.get(vault, '_keyring', userId)\n          if (!descEnv) continue\n          const descKf = JSON.parse(descEnv._data) as KeyringFile\n          usersToRevoke.push(userId)\n          for (const c of Object.keys(descKf.deks)) affectedCollections.add(c)\n        }\n      }\n    }\n  }\n\n  // Delete every keyring in the revoke set. Order doesn't matter\n  // because each keyring file is independent on disk; we don't have\n  // referential integrity to maintain across deletes.\n  for (const userId of usersToRevoke) {\n    await adapter.delete(vault, '_keyring', userId)\n    // Cascade-delete the principal's user envelope. Idempotent — no\n    // error when the envelope was never written (e.g. the user was\n    // granted but never authenticated to write their own profile).\n    await deleteUserEnvelope(adapter, vault, userId)\n  }\n\n  // Single rotation pass at the end. The cost is O(records in\n  // affected collections), NOT O(records × cascade depth) — every\n  // descendant's collections were unioned into `affectedCollections`\n  // before we got here, so the rotation re-encrypts each affected\n  // record exactly once regardless of how deep the cascade went.\n  if (options.rotateKeys !== false && affectedCollections.size > 0) {\n    await rotateKeys(adapter, vault, callerKeyring, [...affectedCollections])\n  }\n}\n\n// ─── Update User (#54) ─────────────────────────────────────────────────\n\n/**\n * Mutate `role`, `displayName`, and/or `permissions` on an existing\n * keyring. Pure plaintext-header rewrite — no DEK rewrap, no KEK\n * required, no authenticator slots touched. Tier-2 enrollments and\n * recovery codes survive the operation.\n *\n * Role-elevation guard: BOTH the old role AND the new role must\n * satisfy `canUpdateRole(callerRole, _)`. This blocks the two\n * privilege-escalation shapes:\n *   - admin elevates someone (or themselves) to owner\n *   - admin demotes an owner to a role they then control\n *\n * Owner is always allowed. Admin manages admin / operator / viewer /\n * client laterally.\n *\n * Identity preserved: same userId, same DEK wrappings. Last-write-wins\n * through the standard keyring put (same concurrency story as `grant`\n * and `revoke`).\n *\n * @throws `NoAccessError` when no keyring exists for the target.\n * @throws `PermissionDeniedError` when the role hierarchy rejects.\n * @throws `ValidationError` when the diff is empty (nothing to update).\n *\n * @see #54\n */\nexport async function updateKeyringIdentity(\n  adapter: NoydbStore,\n  vault: string,\n  callerKeyring: UnlockedKeyring,\n  options: UpdateUserOptions,\n): Promise<void> {\n  if (\n    options.role === undefined &&\n    options.displayName === undefined &&\n    options.permissions === undefined\n  ) {\n    throw new ValidationError(\n      `updateUser: at least one of role / displayName / permissions must be provided ` +\n        `(userId: \"${options.userId}\").`,\n    )\n  }\n\n  const env = await adapter.get(vault, '_keyring', options.userId)\n  if (!env) {\n    throw new NoAccessError(\n      `updateUser: user \"${options.userId}\" has no keyring in vault \"${vault}\".`,\n    )\n  }\n  const target = JSON.parse(env._data) as KeyringFile\n\n  // Role-elevation guard. The OLD role must be one this caller is\n  // allowed to manage, AND the NEW role (if changing) must be too.\n  // Two-sided check: blocks admin→owner promotion (new side) and\n  // demoting an owner (old side).\n  if (!canUpdateRole(callerKeyring.role, target.role)) {\n    throw new PermissionDeniedError(\n      `Role \"${callerKeyring.role}\" cannot update a keyring with role \"${target.role}\"`,\n    )\n  }\n  if (\n    options.role !== undefined &&\n    options.role !== target.role &&\n    !canUpdateRole(callerKeyring.role, options.role)\n  ) {\n    throw new PermissionDeniedError(\n      `Role \"${callerKeyring.role}\" cannot promote target to role \"${options.role}\"`,\n    )\n  }\n\n  const next: KeyringFile = {\n    ...target,\n    ...(options.role !== undefined && { role: options.role }),\n    ...(options.displayName !== undefined && { display_name: options.displayName }),\n    ...(options.permissions !== undefined && { permissions: options.permissions }),\n  }\n\n  await writeKeyringFile(adapter, vault, options.userId, next)\n}\n\n// ─── Key Rotation ──────────────────────────────────────────────────────\n\n/**\n * Rotate DEKs for specified collections:\n * 1. Generate new DEKs\n * 2. Re-encrypt all records in affected collections\n * 3. Re-wrap new DEKs for all remaining users\n */\nexport async function rotateKeys(\n  adapter: NoydbStore,\n  vault: string,\n  callerKeyring: UnlockedKeyring,\n  collections: string[],\n): Promise<void> {\n  // Generate new DEKs for each affected collection\n  const newDeks = new Map<string, CryptoKey>()\n  for (const collName of collections) {\n    newDeks.set(collName, await generateDEK())\n  }\n\n  // Re-encrypt all records in affected collections\n  for (const collName of collections) {\n    const oldDek = callerKeyring.deks.get(collName)\n    const newDek = newDeks.get(collName)!\n    if (!oldDek) continue\n\n    const ids = await adapter.list(vault, collName)\n    for (const id of ids) {\n      const envelope = await adapter.get(vault, collName, id)\n      if (!envelope || !envelope._iv) continue\n\n      // Decrypt with old DEK\n      const plaintext = await decrypt(envelope._iv, envelope._data, oldDek)\n\n      // Re-encrypt with new DEK\n      const { iv, data } = await encrypt(plaintext, newDek)\n      const newEnvelope: EncryptedEnvelope = {\n        _noydb: NOYDB_FORMAT_VERSION,\n        _v: envelope._v,\n        _ts: new Date().toISOString(),\n        _iv: iv,\n        _data: data,\n      }\n      await adapter.put(vault, collName, id, newEnvelope)\n    }\n  }\n\n  // Update caller's keyring with new DEKs\n  for (const [collName, newDek] of newDeks) {\n    callerKeyring.deks.set(collName, newDek)\n  }\n  await persistKeyring(adapter, vault, callerKeyring)\n\n  // Update all remaining users' keyrings with re-wrapped new DEKs\n  const userIds = await adapter.list(vault, '_keyring')\n  for (const userId of userIds) {\n    if (userId === callerKeyring.userId) continue\n\n    const userEnvelope = await adapter.get(vault, '_keyring', userId)\n    if (!userEnvelope) continue\n\n    const userKeyringFile = JSON.parse(userEnvelope._data) as KeyringFile\n    // Note: we can't derive other users' KEKs to re-wrap DEKs for them.\n    // Rotation requires users to re-unlock and be re-granted after the caller\n    // re-wraps with the raw DEKs held in memory. See rotation flow below.\n    // The trick: import the user's KEK from their salt? No — we need their passphrase.\n    //\n    // Per the spec: the caller (owner/admin) wraps the new DEKs with each remaining\n    // user's KEK. But we can't derive their KEK without their passphrase.\n    //\n    // Real solution from the spec: the caller wraps the DEK using the approach of\n    // reading each user's existing wrapping. Since we can't derive their KEK,\n    // we use a RE-KEYING approach: the new DEK is wrapped with a key-wrapping-key\n    // that we CAN derive — we use the existing wrapped DEK as proof that the user\n    // had access, and we replace it with the new wrapped DEK.\n    //\n    // Practical approach: Since the owner/admin has all raw DEKs in memory,\n    // and each user's keyring contains their salt, we need the users to\n    // re-authenticate to get the new wrapped keys. This is the standard approach.\n    //\n    // For NOYDB Phase 2: we'll update the keyring file to include a \"pending_rekey\"\n    // flag. Users will get new DEKs on next login when the owner provides them.\n    //\n    // SIMPLER approach used here: Since the owner performed the rotation,\n    // the owner has both old and new DEKs. We store a \"rekey token\" that the\n    // user can use to unwrap: we wrap the new DEK with the OLD DEK (which the\n    // user can still unwrap from their keyring, since their keyring has the old\n    // wrapped DEK and their KEK can unwrap it).\n\n    // Actually even simpler: we just need the user's KEK. We don't have it.\n    // The spec says the owner wraps new DEKs for each remaining user.\n    // This requires knowing each user's KEK (or having a shared secret).\n    //\n    // The CORRECT implementation from the spec: the owner/admin has all DEKs.\n    // Each user's keyring stores DEKs wrapped with THAT USER's KEK.\n    // To re-wrap, we need each user's KEK — which we can't get.\n    //\n    // Real-world solution: use a KEY ESCROW approach where the owner stores\n    // each user's wrapping key (not their passphrase, but a key derived from\n    // the grant process). During grant, the owner stores a copy of the new user's\n    // KEK (wrapped with the owner's KEK) so they can re-wrap later.\n    //\n    // For now: mark the user's keyring as needing rekey. The user will need to\n    // re-authenticate (owner provides new passphrase or re-grants).\n\n    // Update: simplest correct approach — during grant, we store the user's KEK\n    // wrapped with the owner's KEK in a separate escrow field. Then during rotation,\n    // the owner unwraps the user's KEK from escrow and wraps the new DEKs.\n    //\n    // BUT: that means we need to change the KeyringFile format.\n    // For Phase 2 MVP: just delete the user's old DEK entries and require re-grant.\n    // This is secure (revoked keys are gone) but inconvenient (remaining users\n    // need re-grant for rotated collections).\n\n    // PHASE 2 APPROACH: Remove the affected collection DEKs from remaining users'\n    // keyrings. The owner must re-grant access to those collections.\n    // This is correct and secure — just requires the owner to re-run grant().\n\n    const updatedDeks = { ...userKeyringFile.deks }\n    for (const collName of collections) {\n      delete updatedDeks[collName]\n    }\n\n    const updatedPermissions = { ...userKeyringFile.permissions }\n    for (const collName of collections) {\n      delete updatedPermissions[collName]\n    }\n\n    const updatedKeyring: KeyringFile = {\n      ...userKeyringFile,\n      deks: updatedDeks,\n      permissions: updatedPermissions,\n    }\n\n    await writeKeyringFile(adapter, vault, userId, updatedKeyring)\n  }\n}\n\n// ─── Change Secret ─────────────────────────────────────────────────────\n\n/**\n * Change the user's passphrase. Re-wraps every DEK under the new KEK.\n *\n * Pass `{ validate: true }` (or a `PassphrasePolicy`) to gate the new\n * phrase on the strength rules. `db.rotatePassphrase()` adds a\n * `checkGate('rotate-passphrase')` step on top of this primitive and\n * always validates.\n */\nexport async function changeSecret(\n  adapter: NoydbStore,\n  vault: string,\n  keyring: UnlockedKeyring,\n  newPassphrase: string,\n  passphraseOpts?: PassphrasePolicy & { validate?: boolean; allowWeakPassphrase?: boolean },\n): Promise<UnlockedKeyring> {\n  if (passphraseOpts?.validate && !passphraseOpts.allowWeakPassphrase) {\n    assertStrongPassphrase(newPassphrase, passphraseOpts)\n  }\n  const newSalt = generateSalt()\n  const newKek = await deriveKey(newPassphrase, newSalt)\n\n  // Re-wrap all DEKs with the new KEK\n  const wrappedDeks: Record<string, string> = {}\n  for (const [collName, dek] of keyring.deks) {\n    wrappedDeks[collName] = await wrapKey(dek, newKek)\n  }\n\n  const keyringFile: KeyringFile = {\n    _noydb_keyring: NOYDB_KEYRING_VERSION,\n    user_id: keyring.userId,\n    display_name: keyring.displayName,\n    role: keyring.role,\n    permissions: keyring.permissions,\n    deks: wrappedDeks,\n    salt: bufferToBase64(newSalt),\n    created_at: new Date().toISOString(),\n    granted_by: keyring.userId,\n  }\n\n  await writeKeyringFile(adapter, vault, keyring.userId, keyringFile)\n\n  return {\n    userId: keyring.userId,\n    displayName: keyring.displayName,\n    role: keyring.role,\n    permissions: keyring.permissions,\n    deks: keyring.deks, // Same DEKs, different wrapping\n    kek: newKek,\n    salt: newSalt,\n    // Tier-2 slots are NOT preserved through `changeSecret` —\n    // each slot wraps the OLD KEK, so the new keyring has no\n    // authenticator slots until the user re-enrolls. The higher-level\n    // `db.rotatePassphrase()` (#10) preserves slots by rewrapping the\n    // KEK reference, not the KEK itself.\n    authenticators: [],\n    ...(keyring.policy !== undefined && { policy: keyring.policy }),\n  }\n}\n\n// ─── Bundle recipients ──────────────────────────────────────────\n\n/**\n * Recipient slot in a re-keyed `.noydb` bundle. Each slot becomes its\n * own keyring file inside the bundle, sealed with its own passphrase.\n * Same role/permission semantics as `db.grant()` but no adapter side\n * effect — the slot only exists inside the bundle bytes.\n *\n * @public\n */\nexport interface BundleRecipient {\n  /** User id stamped onto the keyring file in the bundle. */\n  readonly id: string\n  /** Optional display name. Defaults to `id`. */\n  readonly displayName?: string\n  /** Passphrase the recipient will type to unlock. */\n  readonly passphrase: string\n  /** Role on the destination vault. Defaults to `'viewer'`. */\n  readonly role?: Role\n  /**\n   * Per-collection permissions. When omitted, role defaults apply.\n   * Restricting permissions here ALSO restricts which DEKs are wrapped\n   * into the slot — a slot with `{ invoices: 'ro' }` cannot decrypt\n   * other collections even though their ciphertext sits in the bundle.\n   */\n  readonly permissions?: Permissions\n  /**\n   * Optional `as-*` export grants on the destination vault.\n   * Mirrors the `exportCapability` field on a live keyring.\n   */\n  readonly exportCapability?: ExportCapability\n  /**\n   * Optional `as-*` import grants on the destination vault.\n   * Mirrors the `importCapability` field on a live keyring.\n   * Default-closed: no plaintext format granted, no bundle import.\n   */\n  readonly importCapability?: ImportCapability\n  /**\n   * Optional bundle-slot expiry. ISO-8601 timestamp; past the\n   * cutoff this slot's keyring refuses to load with\n   * `KeyringExpiredError`. Time-boxed audit access pattern: \"this\n   * slot works for 30 days then becomes opaque to its holder.\"\n   */\n  readonly expiresAt?: string\n}\n\n/**\n * Build a `KeyringFile` for one bundle recipient, given the source\n * vault's unwrapped DEKs. Mirrors `grant()` minus the adapter write —\n * the produced file is meant to be embedded in the bundle's\n * `keyrings` map, never persisted to the source vault.\n *\n * Privilege-escalation check still runs: every DEK wrapped into the\n * recipient's keyring must come from the source's own DEK set.\n *\n * @internal\n */\nexport async function buildRecipientKeyringFile(\n  callerKeyring: UnlockedKeyring,\n  recipient: BundleRecipient,\n): Promise<KeyringFile> {\n  const role: Role = recipient.role ?? 'viewer'\n  const permissions = resolvePermissions(role, recipient.permissions)\n\n  const newSalt = generateSalt()\n  const newKek = await deriveKey(recipient.passphrase, newSalt)\n\n  const wrappedDeks: Record<string, string> = {}\n\n  // Collections the recipient was explicitly granted permission to.\n  for (const collName of Object.keys(permissions)) {\n    const dek = callerKeyring.deks.get(collName)\n    if (dek) {\n      wrappedDeks[collName] = await wrapKey(dek, newKek)\n    }\n  }\n\n  // owner / admin / viewer: wrap every known DEK (matches grant).\n  if (role === 'owner' || role === 'admin' || role === 'viewer') {\n    for (const [collName, dek] of callerKeyring.deks) {\n      if (!(collName in wrappedDeks)) {\n        wrappedDeks[collName] = await wrapKey(dek, newKek)\n      }\n    }\n  }\n\n  // Always propagate system-prefixed collection DEKs (`_ledger`, etc.) —\n  // the recipient needs them to verify the bundle on import.\n  for (const [collName, dek] of callerKeyring.deks) {\n    if (collName.startsWith('_') && !(collName in wrappedDeks)) {\n      wrappedDeks[collName] = await wrapKey(dek, newKek)\n    }\n  }\n\n  // Anti-privilege-escalation: every wrapped DEK must come from the\n  // caller's own DEK set. Belt-and-braces with the lookups above.\n  for (const collName of Object.keys(wrappedDeks)) {\n    if (!callerKeyring.deks.has(collName)) {\n      throw new PrivilegeEscalationError(collName)\n    }\n  }\n\n  return {\n    _noydb_keyring: NOYDB_KEYRING_VERSION,\n    user_id: recipient.id,\n    display_name: recipient.displayName ?? recipient.id,\n    role,\n    permissions,\n    deks: wrappedDeks,\n    salt: bufferToBase64(newSalt),\n    created_at: new Date().toISOString(),\n    granted_by: callerKeyring.userId,\n    ...(recipient.exportCapability !== undefined\n      ? { export_capability: recipient.exportCapability }\n      : {}),\n    ...(recipient.importCapability !== undefined\n      ? { import_capability: recipient.importCapability }\n      : {}),\n    ...(recipient.expiresAt !== undefined\n      ? { expires_at: recipient.expiresAt }\n      : {}),\n  }\n}\n\n// ─── List Users ────────────────────────────────────────────────────────\n\n/** List all users with access to a vault. */\nexport async function listUsers(\n  adapter: NoydbStore,\n  vault: string,\n): Promise<UserInfo[]> {\n  const userIds = await adapter.list(vault, '_keyring')\n  const users: UserInfo[] = []\n\n  for (const userId of userIds) {\n    const envelope = await adapter.get(vault, '_keyring', userId)\n    if (!envelope) continue\n    const kf = JSON.parse(envelope._data) as KeyringFile\n    users.push({\n      userId: kf.user_id,\n      displayName: kf.display_name,\n      role: kf.role,\n      permissions: kf.permissions,\n      createdAt: kf.created_at,\n      grantedBy: kf.granted_by,\n    })\n  }\n\n  return users\n}\n\n/**\n * Joined enumeration: every keyring + its `_users/<keyringId>`\n * envelope side by side. Convenience for admin UIs that want to\n * render team-member lists with profile data (\"Bob — operator —\n * 'Bob the Auditor' avatar X locale fr-FR\") in a single pass.\n *\n * `userEnvelopeDek` is the vault's `_users` collection DEK\n * (`vault.getDEK('_users')`); used to decrypt every envelope.\n *\n * Principals without a persisted envelope (legacy keyrings predating\n * the user-envelope feature) come back with `envelope: null`. The\n * caller chooses how to render — usually \"fall back to keyring's\n * `displayName`\".\n *\n * Order matches `listUsers()` (store-defined; sort if you need a\n * stable display order).\n */\nexport async function listUsersWithEnvelopes<T = unknown>(\n  adapter: NoydbStore,\n  vault: string,\n  userEnvelopeDek: CryptoKey,\n): Promise<Array<{ user: UserInfo; envelope: UserEnvelopeReader<T> | null }>> {\n  const users = await listUsers(adapter, vault)\n  const out: Array<{ user: UserInfo; envelope: UserEnvelopeReader<T> | null }> = []\n  for (const user of users) {\n    const envelope = await loadUserEnvelopeFn<T>(\n      adapter,\n      vault,\n      user.userId,\n      userEnvelopeDek,\n    )\n    out.push({ user, envelope })\n  }\n  return out\n}\n\n\n// ─── DEK Management ────────────────────────────────────────────────────\n\n/** Ensure a DEK exists for a collection. Generates one if new. */\nexport async function ensureCollectionDEK(\n  adapter: NoydbStore,\n  vault: string,\n  keyring: UnlockedKeyring,\n): Promise<(collectionName: string) => Promise<CryptoKey>> {\n  // Dedupe concurrent first-time DEK creates per collection. Without\n  // this, two concurrent `getDEK('foo')` calls both pass the `existing`\n  // check (the Map is empty), both generate fresh DEKs, and the second\n  // `set` overwrites the first — making any envelope encrypted with\n  // the discarded DEK fail to decrypt later (TamperedError on read).\n  // Pre-existing race exposed by the multi-writer ledger work in #296.\n  const inFlight = new Map<string, Promise<CryptoKey>>()\n  return async (collectionName: string): Promise<CryptoKey> => {\n    const existing = keyring.deks.get(collectionName)\n    if (existing) return existing\n    const pending = inFlight.get(collectionName)\n    if (pending) return pending\n\n    const promise = (async () => {\n      const dek = await generateDEK()\n      keyring.deks.set(collectionName, dek)\n      await persistKeyring(adapter, vault, keyring)\n      return dek\n    })()\n    inFlight.set(collectionName, promise)\n    try {\n      return await promise\n    } finally {\n      inFlight.delete(collectionName)\n    }\n  }\n}\n\n// ─── Permission Checks ─────────────────────────────────────────────────\n\n/** Check if a user has write permission for a collection. */\nexport function hasWritePermission(keyring: UnlockedKeyring, collectionName: string): boolean {\n  if (keyring.role === 'owner' || keyring.role === 'admin') return true\n  if (keyring.role === 'viewer' || keyring.role === 'client') return false\n  return keyring.permissions[collectionName] === 'rw'\n}\n\n/** Check if a user has any access to a collection. */\nexport function hasAccess(keyring: UnlockedKeyring, collectionName: string): boolean {\n  if (keyring.role === 'owner' || keyring.role === 'admin' || keyring.role === 'viewer') return true\n  return collectionName in keyring.permissions\n}\n\n// ─── Helpers ───────────────────────────────────────────────────────────\n\n/** Persist a keyring file to the adapter. */\nexport async function persistKeyring(\n  adapter: NoydbStore,\n  vault: string,\n  keyring: UnlockedKeyring,\n): Promise<void> {\n  if (!keyring.kek) {\n    throw new ValidationError(\n      'persistKeyring: keyring.kek is null — cannot wrap DEKs without the KEK. ' +\n        'This typically means the keyring was opened via tier-3 PIN resume, ' +\n        'session restore, or a wrap-DEKs tier-2 unlock. Re-authenticate at ' +\n        'tier 1 (passphrase) before persisting.',\n    )\n  }\n  const wrappedDeks: Record<string, string> = {}\n  for (const [collName, dek] of keyring.deks) {\n    wrappedDeks[collName] = await wrapKey(dek, keyring.kek)\n  }\n\n  const keyringFile: KeyringFile = {\n    _noydb_keyring: NOYDB_KEYRING_VERSION,\n    user_id: keyring.userId,\n    display_name: keyring.displayName,\n    role: keyring.role,\n    permissions: keyring.permissions,\n    deks: wrappedDeks,\n    salt: bufferToBase64(keyring.salt),\n    created_at: new Date().toISOString(),\n    granted_by: keyring.userId,\n    ...(keyring.exportCapability !== undefined && { export_capability: keyring.exportCapability }),\n    ...(keyring.importCapability !== undefined && { import_capability: keyring.importCapability }),\n    ...(keyring.authenticators.length > 0 && { authenticators: keyring.authenticators }),\n    ...(keyring.policy !== undefined && { policy: keyring.policy }),\n  }\n\n  await writeKeyringFile(adapter, vault, keyring.userId, keyringFile)\n}\n\n// ─── Export capability ──────────────────────────────────────\n\n/**\n * Role-based default policy for the encrypted-bundle capability.\n *\n * Applied when `keyring.exportCapability` is absent or\n * `exportCapability.bundle` is undefined:\n *\n * - `owner` / `admin` → `true` (happy-path backup without friction)\n * - `operator` / `viewer` / `client` → `false` (explicit grant required)\n *\n * Rationale: a bundle is inert without the KEK, so an owner backing up\n * their own vault doesn't need friction; a non-admin role producing a\n * bundle for an external party does, because the bundle outlives\n * keyring revocation.\n */\nfunction defaultBundleCapability(role: Role): boolean {\n  return role === 'owner' || role === 'admin'\n}\n\n/**\n * Check whether a keyring is authorised for a given `@noy-db/as-*`\n * export tier.\n *\n * - `tier: 'plaintext'` — returns true iff `exportCapability.plaintext`\n *   contains the requested `format` or the `'*'` wildcard. Default for\n *   every role is empty — no grant, no plaintext export.\n * - `tier: 'bundle'` — returns `exportCapability.bundle` if present, or\n *   the role-based default otherwise (owner/admin → true, else false).\n *\n * `@noy-db/as-*` packages MUST call this before invoking the underlying\n * export primitive. Rogue forks that skip the check are caught by code\n * review — the single-entry-point contract is a convention, not a\n * runtime invariant. Vault-level gated wrappers\n * (`vault.exportRecords` / `exportBlobs` / `writeBundle`) will land in a\n * follow-up PR to enforce at the primitive level.\n */\nexport function hasExportCapability(\n  keyring: UnlockedKeyring,\n  tier: 'plaintext',\n  format: ExportFormat,\n): boolean\nexport function hasExportCapability(\n  keyring: UnlockedKeyring,\n  tier: 'bundle',\n): boolean\nexport function hasExportCapability(\n  keyring: UnlockedKeyring,\n  tier: 'plaintext' | 'bundle',\n  format?: ExportFormat,\n): boolean {\n  const cap = keyring.exportCapability\n  if (tier === 'plaintext') {\n    const allowed = cap?.plaintext ?? []\n    return allowed.includes('*') || (format !== undefined && allowed.includes(format))\n  }\n  // tier === 'bundle'\n  return cap?.bundle ?? defaultBundleCapability(keyring.role)\n}\n\n/**\n * Same-shape inspector for an `ExportCapability` value that isn't yet\n * attached to a keyring (e.g. for previewing a grant before applying).\n * Role must be supplied separately so bundle defaults can be computed.\n */\nexport function evaluateExportCapability(\n  capability: ExportCapability | undefined,\n  role: Role,\n  tier: 'plaintext',\n  format: ExportFormat,\n): boolean\nexport function evaluateExportCapability(\n  capability: ExportCapability | undefined,\n  role: Role,\n  tier: 'bundle',\n): boolean\nexport function evaluateExportCapability(\n  capability: ExportCapability | undefined,\n  role: Role,\n  tier: 'plaintext' | 'bundle',\n  format?: ExportFormat,\n): boolean {\n  if (tier === 'plaintext') {\n    const allowed = capability?.plaintext ?? []\n    return allowed.includes('*') || (format !== undefined && allowed.includes(format))\n  }\n  return capability?.bundle ?? defaultBundleCapability(role)\n}\n\n// ─── Import capability (issue ) ────────────────────────────────────\n\n/**\n * Check whether a keyring is authorised for a given `@noy-db/as-*`\n * import tier (issue ).\n *\n * - `tier: 'plaintext'` — true iff `importCapability.plaintext`\n *   contains the requested `format` or the `'*'` wildcard.\n * - `tier: 'bundle'` — true iff `importCapability.bundle === true`.\n *\n * **Default-closed for every role on every dimension** — including\n * owner. Import is more dangerous than export (corrupts vs leaks), so\n * the policy refuses to assume intent. Owners must positively grant\n * the capability via `vault.grant({ importCapability: ... })`.\n */\nexport function hasImportCapability(\n  keyring: UnlockedKeyring,\n  tier: 'plaintext',\n  format: ExportFormat,\n): boolean\nexport function hasImportCapability(\n  keyring: UnlockedKeyring,\n  tier: 'bundle',\n): boolean\nexport function hasImportCapability(\n  keyring: UnlockedKeyring,\n  tier: 'plaintext' | 'bundle',\n  format?: ExportFormat,\n): boolean {\n  const cap = keyring.importCapability\n  if (tier === 'plaintext') {\n    const allowed = cap?.plaintext ?? []\n    return allowed.includes('*') || (format !== undefined && allowed.includes(format))\n  }\n  // tier === 'bundle' — closed default for every role\n  return cap?.bundle === true\n}\n\n/**\n * Same-shape inspector for an `ImportCapability` value that isn't yet\n * attached to a keyring (e.g. previewing a grant before applying).\n * `role` is accepted for symmetry with `evaluateExportCapability` even\n * though the import policy ignores it — bundle defaults are\n * role-agnostic and closed.\n */\nexport function evaluateImportCapability(\n  capability: ImportCapability | undefined,\n  role: Role,\n  tier: 'plaintext',\n  format: ExportFormat,\n): boolean\nexport function evaluateImportCapability(\n  capability: ImportCapability | undefined,\n  role: Role,\n  tier: 'bundle',\n): boolean\nexport function evaluateImportCapability(\n  capability: ImportCapability | undefined,\n  _role: Role,\n  tier: 'plaintext' | 'bundle',\n  format?: ExportFormat,\n): boolean {\n  if (tier === 'plaintext') {\n    const allowed = capability?.plaintext ?? []\n    return allowed.includes('*') || (format !== undefined && allowed.includes(format))\n  }\n  return capability?.bundle === true\n}\n\nfunction resolvePermissions(role: Role, explicit?: Permissions): Permissions {\n  if (role === 'owner' || role === 'admin' || role === 'viewer') return {}\n  return explicit ?? {}\n}\n\nasync function writeKeyringFile(\n  adapter: NoydbStore,\n  vault: string,\n  userId: string,\n  keyringFile: KeyringFile,\n): Promise<void> {\n  const envelope = {\n    _noydb: 1 as const,\n    _v: 1,\n    _ts: new Date().toISOString(),\n    _iv: '',\n    _data: JSON.stringify(keyringFile),\n  }\n  await adapter.put(vault, '_keyring', userId, envelope)\n}\n"],"mappings":"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","names":[]}