@noy-db/hub 0.1.0-pre.14 → 0.1.0-pre.16

package/dist/{types-DIOLYPUq.d.ts → types-DImsOlJe.d.ts}

@@ -1,8 +1,9 @@
 import { I as IndexStrategy, d as LazyQuery } from './lazy-builder-Rpd-V3jP.js';
-import { A as AggregateStrategy } from './strategy-D-SrOLCl.js';
+import { b as AggregateSpec, A as AggregateStrategy } from './strategy-DSTrsZ8t.js';
 import { C as CrdtStrategy, a as CrdtMode, b as CrdtState } from './strategy-BSxFXGzb.js';
-import { N as NoydbError, Q as Query, ae as RefDescriptor, X as JoinableSource, aj as RefViolation, ak as ScanBuilder } from './index-7nd15fgy.js';
+import { N as NoydbError, Q as Query, ak as RefRegistry, ah as RefDescriptor, _ as JoinableSource, am as RefViolation, an as ScanBuilder } from './index-CNwA-B6-.js';
 import { F as FieldClause, I as IndexDef, C as CollectionIndexes } from './predicate-Dnu81tsS.js';
+import { RawShare } from '@noy-db/on-shamir';
 
 /**
  * Standard Schema v1 integration.
@@ -819,6 +820,17 @@ interface LedgerEntry {
      * the file docstring.
      */
     readonly payloadHash: string;
+    /**
+     * Optional human-readable tag describing why this mutation happened
+     * (#1). Threaded through `collection.put(_, _, { reason })`. Common
+     * values include `'import:csv'`, `'import:json'`, `'import:xlsx'` from
+     * `as-*` ImportPlan.apply(), but consumers can use any string for
+     * domain-specific audit filtering. Auto-strip via `canonicalJson` —
+     * absent on the wire, never serialized as `null`.
+     *
+     * Audit consumers filter: `entries.filter(e => e.reason?.startsWith('import:'))`.
+     */
+    readonly reason?: string;
     /**
      * Optional hex-encoded sha256 of the encrypted JSON Patch delta
      * blob stored alongside this entry in `_ledger_deltas/`. Present
@@ -1086,6 +1098,13 @@ interface AppendInput {
      * resulting ledger entry.
      */
     amendment?: LedgerEntry['amendment'];
+    /**
+     * Optional human-readable tag describing why this mutation happened
+     * (#1). Threaded from `collection.put(_, _, { reason })`.
+     * Carried verbatim onto the resulting ledger entry's `reason` field;
+     * omitted from canonical JSON when undefined.
+     */
+    reason?: string;
 }
 /**
  * Result of `LedgerStore.verify()`. On success, `head` is the hash of
@@ -3072,6 +3091,266 @@ declare class SyncEngine {
     private persistMeta;
 }
 
+/**
+ * **Wrap-DEKs primitive (#44)** — a single canonical shape for the
+ * pattern of "serialize a DEK set, encrypt it under a credential-derived
+ * AES-GCM key." Used by:
+ *
+ *   - **tier-0** — paper recovery entries (`_meta/recovery-paper`),
+ *     credential = the printed code.
+ *   - **tier-2** — password authenticator slots (`KeyringFile.authenticators`,
+ *     `wrapKind: 'deks'`), credential = the user's password.
+ *
+ * **Not** used by `@noy-db/on-pin` — tier-3 wraps the DEK set under
+ * the same conceptual pattern but at **100,000 PBKDF2 iterations**
+ * (vs the 600,000 here), because the protection window for a PIN
+ * slot is short (idle-timeout-bounded, typically 15 min) and 600k
+ * iterations would make every PIN-resume noticeably slow. The wire
+ * formats are deliberately incompatible. See `@noy-db/on-pin`'s
+ * `PIN_PBKDF2_ITERATIONS` and the threat-model rationale in its
+ * module docstring.
+ *
+ * Before #44, the same crypto lived in two places: `mintPaperRecoveryEntry`
+ * (in `team/recovery.ts`) and `enrollPasswordAuthenticator` (in
+ * `@noy-db/on-password`). Both functions did identical work — PBKDF2
+ * the credential, AES-GCM-encrypt the JSON-serialized DEK set — but
+ * their implementations had drifted apart enough that fixing a bug
+ * in one wouldn't fix the other.
+ *
+ * This module owns the canonical implementation. Consumers compose:
+ *
+ *   - `mintPaperRecoveryEntry` is now a thin wrapper that calls
+ *     `mintWrappedDeksBlob` and adds `{ codeId, enrolledAt }`.
+ *   - `enrollPasswordAuthenticator` calls `mintWrappedDeksBlob` and
+ *     wraps the result in the slot envelope.
+ *
+ * @module
+ */
+/**
+ * The wrap-DEKs primitive — a serialized + AES-GCM-encrypted DEK set
+ * keyed under a credential-derived key.
+ *
+ * All three fields are base64-encoded so the blob is JSON-safe and
+ * round-trips through `_meta/*` envelopes (which carry plaintext
+ * JSON in `_data`).
+ *
+ * Composition: `PaperRecoveryEntry extends WrappedDeksBlob` plus
+ * `{ codeId, enrolledAt }`. `KeyringAuthenticatorWrappingDEKs`
+ * carries the same three fields with `salt` stored in `meta` for
+ * slot-format back-compat (#44 defers moving it to top-level).
+ */
+interface WrappedDeksBlob {
+    /** Base64 PBKDF2 salt for the credential-derived wrapping key. */
+    readonly salt: string;
+    /** Base64 AES-GCM IV used for the `wrappedDeks` ciphertext. */
+    readonly iv: string;
+    /** Base64 AES-GCM ciphertext of `{ deks: { collection: base64rawDek } }`. */
+    readonly wrappedDeks: string;
+}
+/**
+ * Mint a fresh `WrappedDeksBlob` from a DEK set + a string credential.
+ *
+ * Generates a random salt + IV, derives a 256-bit AES-GCM key via
+ * PBKDF2-SHA256(credential, salt, 600K), serializes the DEK set as
+ * `{ deks: { coll: rawBase64 } }`, and AES-GCM-encrypts.
+ *
+ * The `credential` is the user-typed string (recovery code, password,
+ * PIN). Caller normalization rules apply (e.g. paper
+ * recovery uppercase-strips the code before reaching this function).
+ *
+ * @param deks - DEK set to wrap. Each DEK must be exportable via
+ *               `subtle.exportKey('raw', dek)` (the hub mints DEKs
+ *               this way; consumers feeding non-extractable keys
+ *               will get `InvalidAccessError` from WebCrypto).
+ * @param credential - String input the consumer minted (paper code,
+ *               password, PIN). Treated as opaque bytes by PBKDF2.
+ */
+declare function mintWrappedDeksBlob(deks: Map<string, CryptoKey>, credential: string): Promise<WrappedDeksBlob>;
+/**
+ * Reverse of {@link mintWrappedDeksBlob}. Re-derives the wrapping key
+ * from the credential + stored salt, AES-GCM-decrypts the wrapped DEK
+ * set, and re-imports each DEK as an extractable AES-GCM CryptoKey.
+ *
+ * Throws (AES-GCM auth tag failure) when the credential doesn't
+ * match the blob. Callers iterating over multiple blobs (e.g. paper
+ * recovery's "try every entry until one matches") should catch.
+ */
+declare function unwrapDeksFromBlob(blob: WrappedDeksBlob, credential: string): Promise<Map<string, CryptoKey>>;
+
+/**
+ * Recovery profile persistence + dispatch — issue #10.
+ *
+ * v0.1.0-pre.5 wires the **paper** profile end-to-end through
+ * `@noy-db/on-recovery`. The other three profiles (Shamir,
+ * multi-channel, admin-mediated) ship the API surface and throw
+ * {@link RecoveryProfileNotImplementedError} during use; per-profile
+ * dispatch lands in follow-up issues.
+ *
+ * Storage layout:
+ *
+ * ```
+ * _meta/recovery-paper       — JSON { entries: RecoveryCodeEntry[] } produced by `on-recovery`.
+ * _meta/recovery-shamir      — reserved
+ * _meta/recovery-multi       — reserved
+ * _meta/recovery-admin       — reserved
+ * ```
+ *
+ * Like `_meta/policy` and `_meta/handle`, the documents are plain JSON
+ * with empty `_iv` — the recovery-code wrapping is what protects the
+ * KEK; the entries themselves are inert without the user's code.
+ *
+ * @module
+ */
+
+/**
+ * One paper recovery code as persisted in `_meta/recovery-paper`.
+ *
+ * The hub's KEK is intentionally non-extractable (see `crypto.ts`),
+ * so the recovery entry can't AES-KW-wrap the KEK directly. Instead
+ * we wrap a serialized DEK set: the entry holds the AES-GCM
+ * ciphertext of `{ deks: { collection: rawDekBase64 } }`. Recovery
+ * deserializes the DEK set, then mints a fresh KEK from the new
+ * passphrase and rewraps the DEKs under it.
+ *
+ * This is the same pattern `@noy-db/on-pin` uses for tier-3 quick
+ * resume — the cryptographic guarantee is identical (AES-GCM with a
+ * PBKDF2-derived key), and it sidesteps the non-extractable-KEK
+ * constraint cleanly.
+ *
+ * Type-level composition (#44): `PaperRecoveryEntry extends
+ * WrappedDeksBlob` — the three crypto fields (`salt`, `iv`,
+ * `wrappedDeks`) come from the shared primitive; `codeId` and
+ * `enrolledAt` are paper-recovery's own metadata. Wire format
+ * unchanged.
+ */
+interface PaperRecoveryEntry extends WrappedDeksBlob {
+    readonly codeId: string;
+    readonly enrolledAt: string;
+}
+interface PaperRecoveryDoc {
+    readonly _noydb_recovery: 1;
+    readonly profile: 'paper';
+    readonly entries: ReadonlyArray<PaperRecoveryEntry>;
+}
+/** Read the paper-recovery entries. Returns empty array when absent. */
+declare function loadPaperRecoveryEntries(store: NoydbStore, vault: string): Promise<ReadonlyArray<PaperRecoveryEntry>>;
+/** Replace the paper-recovery entries (used after burn-on-recovery). */
+declare function savePaperRecoveryEntries(store: NoydbStore, vault: string, entries: ReadonlyArray<PaperRecoveryEntry>): Promise<void>;
+/** Drop a single paper-recovery entry (burn-on-use). */
+declare function burnPaperRecoveryEntry(store: NoydbStore, vault: string, codeId: string): Promise<void>;
+/** Whether at least one recovery profile has any enrolled entries. */
+declare function hasRecoveryEnrolled(store: NoydbStore, vault: string): Promise<boolean>;
+/**
+ * One Shamir-recovery entry as persisted in `_meta/recovery-shamir`.
+ *
+ * Like {@link PaperRecoveryEntry}, the entry composes
+ * {@link WrappedDeksBlob} (DEKs wrapped under a fresh ephemeral
+ * recovery secret) with profile-specific metadata. Unlike paper, the
+ * "credential" was never visible to the user — it was 32 random
+ * bytes split into N Shamir shares at enrollment. The shares ARE
+ * the credential; the user holds them, the hub never sees them
+ * again after `enrollRecovery` returns.
+ *
+ * Per the spec §5: the recovery secret is base64-encoded and
+ * passed as the `credential` arg to
+ * {@link mintWrappedDeksBlob} / {@link unwrapDeksFromBlob}. The
+ * PBKDF2 round over high-entropy input is harmless overhead — it
+ * keeps the shared primitive unchanged while letting Shamir reuse
+ * the same wrapping pipeline as paper.
+ */
+interface ShamirRecoveryEntry extends WrappedDeksBlob {
+    /** Stable id for this entry. Allows multiple Shamir splits to coexist. */
+    readonly entryId: string;
+    /** Threshold — minimum shares to reconstruct. */
+    readonly k: number;
+    /** Total shares minted at enrollment. */
+    readonly n: number;
+    /** x-coordinates of the n minted shares (audit metadata; not used at unlock). */
+    readonly xCoords: ReadonlyArray<number>;
+    /** ISO timestamp. */
+    readonly enrolledAt: string;
+    /** Optional caller-supplied label (e.g., "2-of-3 board escrow"). */
+    readonly label?: string;
+}
+interface ShamirRecoveryDoc {
+    readonly _noydb_recovery: 1;
+    readonly profile: 'shamir';
+    readonly entries: ReadonlyArray<ShamirRecoveryEntry>;
+}
+/** Read the Shamir-recovery entries. Returns empty array when absent. */
+declare function loadShamirRecoveryEntries(store: NoydbStore, vault: string): Promise<ReadonlyArray<ShamirRecoveryEntry>>;
+/** Replace the Shamir-recovery entries (used by enrollment and rotation). */
+declare function saveShamirRecoveryEntries(store: NoydbStore, vault: string, entries: ReadonlyArray<ShamirRecoveryEntry>): Promise<void>;
+/**
+ * Mint a fresh Shamir recovery entry from a DEK set.
+ *
+ * 1. Generates a 32-byte recovery secret.
+ * 2. Wraps the DEK set under that secret via
+ *    {@link mintWrappedDeksBlob} (the recovery secret is base64-
+ *    encoded as the credential string — PBKDF2 over high-entropy
+ *    input is harmless overhead).
+ * 3. Splits the recovery secret via Shamir into `n` shares with
+ *    threshold `k`.
+ * 4. Zeros the in-memory recovery secret after wrapping + splitting.
+ *
+ * Returns:
+ *   - `entry` — the {@link ShamirRecoveryEntry} to persist.
+ *   - `shareStrings` — the `n` Base32-encoded share strings to
+ *     return to the caller. The HUB MUST NOT PERSIST THESE; once
+ *     returned they are the user's responsibility.
+ *
+ * @param deks - DEK set to wrap.
+ * @param entryId - Stable id for this entry (caller-supplied or
+ *                  hub-generated).
+ * @param k - Threshold (>= 2).
+ * @param n - Total shares (k <= n <= 255).
+ * @param label - Optional caller label.
+ */
+declare function mintShamirRecoveryEntry(deks: Map<string, CryptoKey>, entryId: string, k: number, n: number, label?: string): Promise<{
+    entry: ShamirRecoveryEntry;
+    shareStrings: string[];
+}>;
+/**
+ * Decrypt a Shamir recovery entry to recover the raw DEK set.
+ *
+ * Combines K or more `shares`, reconstructs the recovery secret,
+ * unwraps the DEKs via {@link unwrapDeksFromBlob}.
+ *
+ * Throws (AES-GCM auth-tag mismatch) when the shares don't combine
+ * to the secret originally used to mint the entry — typically
+ * because they came from a different enrollment or were tampered
+ * with. Callers iterating multiple entries should catch.
+ */
+declare function unwrapDeksFromShamirEntry(entry: ShamirRecoveryEntry, shares: readonly RawShare[]): Promise<Map<string, CryptoKey>>;
+
+/**
+ * Generate one paper-recovery entry from an unlocked DEK set.
+ *
+ * Returns the serializable entry (persisted via
+ * {@link savePaperRecoveryEntries}). The recovery flow unwraps the
+ * DEK set, then mints a fresh KEK from the user's new passphrase.
+ *
+ * Thin wrapper over {@link mintWrappedDeksBlob} (#44) — the crypto
+ * lives in the shared primitive; this function just adds paper-
+ * recovery's own metadata (`codeId`, `enrolledAt`).
+ *
+ * @param deks      Map of collection-name → DEK (extractable).
+ * @param code      The plaintext recovery code (caller-supplied;
+ *                  pair this with `@noy-db/on-recovery`'s code
+ *                  generator/parser if available).
+ * @param codeId    Stable id used by `burnPaperRecoveryEntry`.
+ */
+declare function mintPaperRecoveryEntry(deks: Map<string, CryptoKey>, code: string, codeId: string): Promise<PaperRecoveryEntry>;
+/**
+ * Decrypt a recovery entry to recover the raw DEK set. Used by the
+ * `recoverPassphrase` flow after the user's code has been parsed.
+ *
+ * Thin wrapper over {@link unwrapDeksFromBlob} (#44).
+ *
+ * @throws when the code does not match the entry (AES-GCM auth tag fail).
+ */
+declare function unwrapDeksFromPaperEntry(entry: PaperRecoveryEntry, code: string): Promise<Map<string, CryptoKey>>;
+
 /**
  * Tier-2 authenticator slot management — issue #11.
  *
@@ -3272,20 +3551,26 @@ declare function rotatePassphrase(store: NoydbStore, vault: string, userId: stri
 /**
  * Caller payload for {@link recoverPassphrase}.
  *
- * **Narrowed to `'paper'` only (#86).** The other three profiles
- * (`shamir`, `multi-channel`, `admin-mediated`) are documented in the
- * spec but not yet wired end-to-end. Matching the discipline of
- * {@link db.enrollRecovery}, the type rejects them at compile time
- * rather than accepting them and throwing at runtime. The runtime
- * guard ({@link RecoveryProfileNotImplementedError}) remains so
- * consumers who bypass TS via `as unknown as RecoveryProof` still
- * receive a clear error.
+ * As of #196 slice 1, `paper` and `shamir` are wired end-to-end.
+ * The remaining two profiles (`multi-channel`, `admin-mediated`)
+ * stay outside the union and throw
+ * {@link RecoveryProfileNotImplementedError} at the runtime guard
+ * when bypassed via `as unknown as RecoveryProof`.
  */
 type RecoveryProof = {
     readonly profile: 'paper';
     readonly payload: {
         readonly code: string;
     };
+} | {
+    readonly profile: 'shamir';
+    readonly payload: {
+        /** Optional disambiguator when multiple Shamir entries are enrolled.
+         *  When omitted, hub tries each entry until one combines. */
+        readonly entryId?: string;
+        /** K or more share strings (Base32-encoded per @noy-db/on-shamir). */
+        readonly shares: ReadonlyArray<string>;
+    };
 };
 interface RecoverPassphraseInput {
     readonly newPassphrase: string;
@@ -3345,6 +3630,83 @@ interface RecoverPassphraseInput {
 interface RecoverPassphraseResult {
     readonly newCodes: readonly string[];
 }
+/**
+ * Input for {@link Noydb.rotateRecovery} (#121) — deliberate
+ * recovery-credential regeneration when the user knows their
+ * passphrase but wants a fresh sheet (paper) or fresh shares
+ * (shamir). Symmetric to {@link RotatePassphraseInput}.
+ */
+type RotateRecoveryOptions = {
+    readonly profile: 'paper';
+    /** How many fresh codes to mint. Default: existing sheet size. */
+    readonly count?: number;
+    /** Optional code generator — see {@link RecoverPassphraseInput.codeGenerator}. */
+    readonly codeGenerator?: () => string;
+} | {
+    readonly profile: 'shamir';
+    /** New threshold. */
+    readonly k: number;
+    /** New total share count. */
+    readonly n: number;
+    /** Disambiguator when multiple Shamir entries exist; required if there are 2+. */
+    readonly entryId?: string;
+    /** Optional updated label. */
+    readonly label?: string;
+};
+/**
+ * Result of {@link Noydb.rotateRecovery}. Shape varies by profile:
+ *
+ * - `paper` → `{ newCodes: string[] }` (and `entryId === 'paper-batch'`)
+ * - `shamir` → `{ newShares: string[], entryId }`
+ *
+ * `newCodes` is populated for paper rotations; `newShares` for
+ * Shamir rotations. Both are show-once — the hub does not
+ * retain them.
+ */
+interface RotateRecoveryResult {
+    readonly newCodes?: readonly string[];
+    readonly newShares?: readonly string[];
+    readonly entryId?: string;
+}
+/**
+ * Result of {@link Noydb.enrollRecovery}. Shape varies by profile:
+ *
+ * - `paper` → `{ entryId: 'paper-batch' }` (caller minted the
+ *   entries; this is a sentinel since paper enrollments are batch-shaped).
+ * - `shamir` → `{ entryId, shares: string[] }` — shares are
+ *   show-once; the hub does not retain them.
+ */
+interface EnrollRecoveryResult {
+    readonly entryId: string;
+    readonly shares?: readonly string[];
+}
+/**
+ * Input shape for {@link Noydb.enrollRecovery} and
+ * {@link Noydb.openVaultAndEnrollRecovery} (#195). Discriminated
+ * union over recovery profiles.
+ *
+ * - `paper`: caller pre-mints entries (typically via
+ *   `mintPaperRecoveryEntry` or `@noy-db/on-recovery`'s
+ *   `generateRecoveryCodeSet`) and passes them in. The hub stores
+ *   them and surfaces an opaque batch id.
+ * - `shamir`: hub mints the recovery secret + the shares at
+ *   enrollment time. The shares are returned in
+ *   {@link EnrollRecoveryResult.shares} (show-once); the hub never
+ *   retains them.
+ *
+ * Multi-channel and admin-mediated will be added when the respective
+ * dispatch slices ship.
+ */
+type RecoveryEnrollmentInput = {
+    readonly profile: 'paper';
+    readonly entries: ReadonlyArray<PaperRecoveryEntry>;
+} | {
+    readonly profile: 'shamir';
+    readonly k: number;
+    readonly n: number;
+    readonly label?: string;
+    readonly entryId?: string;
+};
 /**
  * Reset the user's passphrase using a recovery proof. v0.1.0-pre.5
  * supports the `'paper'` profile via `@noy-db/on-recovery` entries
@@ -3385,233 +3747,56 @@ declare function recoverPassphrase(store: NoydbStore, vault: string, userId: str
  *      their own phrase.
  *
  * Caller must be at least as privileged as the target. The hub
- * `db.recoverUser` method gates this with the `peer-recover-user`
- * policy gate (#33's factor-proof requirement); the function below
- * enforces only the role + anti-privilege-escalation invariants.
- *
- * @module
- */
-
-/** Input shape for {@link recoverUser}. */
-interface RecoverUserOptions {
-    /** Target user id whose keyring is being recovered. */
-    readonly userId: string;
-    /**
-     * Temporary passphrase under which the new keyring is wrapped.
-     * The recipient should call `db.rotatePassphrase` immediately on
-     * acceptance to choose their own phrase — this temp acts as a
-     * single-use bridge in invite / peer-recovery flows.
-     */
-    readonly passphrase: string;
-    /** Override the target's role. Defaults to the existing target's role. */
-    readonly role?: Role;
-    /** Override the target's display name. Defaults to existing. */
-    readonly displayName?: string;
-    /** Validate phrase strength against the configured policy. */
-    readonly validatePassphrase?: boolean;
-    /**
-     * Skip phrase strength validation even when `validatePassphrase` is
-     * set. The escape hatch matches `grant`'s shape — used when the
-     * temp phrase is a high-entropy one-shot string that doesn't need
-     * to satisfy the human-typeable rules.
-     */
-    readonly allowWeakPassphrase?: boolean;
-    /**
-     * Optional explicit phrase policy override (passed through to
-     * `assertStrongPassphrase`). Mirrors how `grant` accepts a custom
-     * `PassphrasePolicy` for app-specific tightening.
-     */
-    readonly passphrasePolicy?: PassphrasePolicy;
-}
-/**
- * Atomically rewrap the target user's keyring under a fresh temp
- * passphrase. Single store write; no revoke step; no key rotation.
- *
- * Caller's responsibilities (NOT enforced here):
- *   - Run the `peer-recover-user` policy gate first via
- *     `Noydb.checkGate` to enforce the freshness factor proof.
- *   - Communicate the temp passphrase to the recipient via a secure
- *     channel (URL fragment, in-person, etc.) — the hub does not
- *     transport secrets.
- */
-declare function recoverUser(store: NoydbStore, vault: string, callerKeyring: UnlockedKeyring, options: RecoverUserOptions): Promise<void>;
-
-/**
- * **Wrap-DEKs primitive (#44)** — a single canonical shape for the
- * pattern of "serialize a DEK set, encrypt it under a credential-derived
- * AES-GCM key." Used by:
- *
- *   - **tier-0** — paper recovery entries (`_meta/recovery-paper`),
- *     credential = the printed code.
- *   - **tier-2** — password authenticator slots (`KeyringFile.authenticators`,
- *     `wrapKind: 'deks'`), credential = the user's password.
- *
- * **Not** used by `@noy-db/on-pin` — tier-3 wraps the DEK set under
- * the same conceptual pattern but at **100,000 PBKDF2 iterations**
- * (vs the 600,000 here), because the protection window for a PIN
- * slot is short (idle-timeout-bounded, typically 15 min) and 600k
- * iterations would make every PIN-resume noticeably slow. The wire
- * formats are deliberately incompatible. See `@noy-db/on-pin`'s
- * `PIN_PBKDF2_ITERATIONS` and the threat-model rationale in its
- * module docstring.
- *
- * Before #44, the same crypto lived in two places: `mintPaperRecoveryEntry`
- * (in `team/recovery.ts`) and `enrollPasswordAuthenticator` (in
- * `@noy-db/on-password`). Both functions did identical work — PBKDF2
- * the credential, AES-GCM-encrypt the JSON-serialized DEK set — but
- * their implementations had drifted apart enough that fixing a bug
- * in one wouldn't fix the other.
- *
- * This module owns the canonical implementation. Consumers compose:
- *
- *   - `mintPaperRecoveryEntry` is now a thin wrapper that calls
- *     `mintWrappedDeksBlob` and adds `{ codeId, enrolledAt }`.
- *   - `enrollPasswordAuthenticator` calls `mintWrappedDeksBlob` and
- *     wraps the result in the slot envelope.
- *
- * @module
- */
-/**
- * The wrap-DEKs primitive — a serialized + AES-GCM-encrypted DEK set
- * keyed under a credential-derived key.
- *
- * All three fields are base64-encoded so the blob is JSON-safe and
- * round-trips through `_meta/*` envelopes (which carry plaintext
- * JSON in `_data`).
- *
- * Composition: `PaperRecoveryEntry extends WrappedDeksBlob` plus
- * `{ codeId, enrolledAt }`. `KeyringAuthenticatorWrappingDEKs`
- * carries the same three fields with `salt` stored in `meta` for
- * slot-format back-compat (#44 defers moving it to top-level).
- */
-interface WrappedDeksBlob {
-    /** Base64 PBKDF2 salt for the credential-derived wrapping key. */
-    readonly salt: string;
-    /** Base64 AES-GCM IV used for the `wrappedDeks` ciphertext. */
-    readonly iv: string;
-    /** Base64 AES-GCM ciphertext of `{ deks: { collection: base64rawDek } }`. */
-    readonly wrappedDeks: string;
-}
-/**
- * Mint a fresh `WrappedDeksBlob` from a DEK set + a string credential.
- *
- * Generates a random salt + IV, derives a 256-bit AES-GCM key via
- * PBKDF2-SHA256(credential, salt, 600K), serializes the DEK set as
- * `{ deks: { coll: rawBase64 } }`, and AES-GCM-encrypts.
- *
- * The `credential` is the user-typed string (recovery code, password,
- * PIN). Caller normalization rules apply (e.g. paper
- * recovery uppercase-strips the code before reaching this function).
- *
- * @param deks - DEK set to wrap. Each DEK must be exportable via
- *               `subtle.exportKey('raw', dek)` (the hub mints DEKs
- *               this way; consumers feeding non-extractable keys
- *               will get `InvalidAccessError` from WebCrypto).
- * @param credential - String input the consumer minted (paper code,
- *               password, PIN). Treated as opaque bytes by PBKDF2.
- */
-declare function mintWrappedDeksBlob(deks: Map<string, CryptoKey>, credential: string): Promise<WrappedDeksBlob>;
-/**
- * Reverse of {@link mintWrappedDeksBlob}. Re-derives the wrapping key
- * from the credential + stored salt, AES-GCM-decrypts the wrapped DEK
- * set, and re-imports each DEK as an extractable AES-GCM CryptoKey.
- *
- * Throws (AES-GCM auth tag failure) when the credential doesn't
- * match the blob. Callers iterating over multiple blobs (e.g. paper
- * recovery's "try every entry until one matches") should catch.
- */
-declare function unwrapDeksFromBlob(blob: WrappedDeksBlob, credential: string): Promise<Map<string, CryptoKey>>;
-
-/**
- * Recovery profile persistence + dispatch — issue #10.
- *
- * v0.1.0-pre.5 wires the **paper** profile end-to-end through
- * `@noy-db/on-recovery`. The other three profiles (Shamir,
- * multi-channel, admin-mediated) ship the API surface and throw
- * {@link RecoveryProfileNotImplementedError} during use; per-profile
- * dispatch lands in follow-up issues.
- *
- * Storage layout:
- *
- * ```
- * _meta/recovery-paper       — JSON { entries: RecoveryCodeEntry[] } produced by `on-recovery`.
- * _meta/recovery-shamir      — reserved
- * _meta/recovery-multi       — reserved
- * _meta/recovery-admin       — reserved
- * ```
- *
- * Like `_meta/policy` and `_meta/handle`, the documents are plain JSON
- * with empty `_iv` — the recovery-code wrapping is what protects the
- * KEK; the entries themselves are inert without the user's code.
- *
- * @module
- */
-
-/**
- * One paper recovery code as persisted in `_meta/recovery-paper`.
- *
- * The hub's KEK is intentionally non-extractable (see `crypto.ts`),
- * so the recovery entry can't AES-KW-wrap the KEK directly. Instead
- * we wrap a serialized DEK set: the entry holds the AES-GCM
- * ciphertext of `{ deks: { collection: rawDekBase64 } }`. Recovery
- * deserializes the DEK set, then mints a fresh KEK from the new
- * passphrase and rewraps the DEKs under it.
- *
- * This is the same pattern `@noy-db/on-pin` uses for tier-3 quick
- * resume — the cryptographic guarantee is identical (AES-GCM with a
- * PBKDF2-derived key), and it sidesteps the non-extractable-KEK
- * constraint cleanly.
- *
- * Type-level composition (#44): `PaperRecoveryEntry extends
- * WrappedDeksBlob` — the three crypto fields (`salt`, `iv`,
- * `wrappedDeks`) come from the shared primitive; `codeId` and
- * `enrolledAt` are paper-recovery's own metadata. Wire format
- * unchanged.
- */
-interface PaperRecoveryEntry extends WrappedDeksBlob {
-    readonly codeId: string;
-    readonly enrolledAt: string;
-}
-interface PaperRecoveryDoc {
-    readonly _noydb_recovery: 1;
-    readonly profile: 'paper';
-    readonly entries: ReadonlyArray<PaperRecoveryEntry>;
-}
-/** Read the paper-recovery entries. Returns empty array when absent. */
-declare function loadPaperRecoveryEntries(store: NoydbStore, vault: string): Promise<ReadonlyArray<PaperRecoveryEntry>>;
-/** Replace the paper-recovery entries (used after burn-on-recovery). */
-declare function savePaperRecoveryEntries(store: NoydbStore, vault: string, entries: ReadonlyArray<PaperRecoveryEntry>): Promise<void>;
-/** Drop a single paper-recovery entry (burn-on-use). */
-declare function burnPaperRecoveryEntry(store: NoydbStore, vault: string, codeId: string): Promise<void>;
-/** Whether at least one recovery profile has any enrolled entries. */
-declare function hasRecoveryEnrolled(store: NoydbStore, vault: string): Promise<boolean>;
-/**
- * Generate one paper-recovery entry from an unlocked DEK set.
- *
- * Returns the serializable entry (persisted via
- * {@link savePaperRecoveryEntries}). The recovery flow unwraps the
- * DEK set, then mints a fresh KEK from the user's new passphrase.
- *
- * Thin wrapper over {@link mintWrappedDeksBlob} (#44) — the crypto
- * lives in the shared primitive; this function just adds paper-
- * recovery's own metadata (`codeId`, `enrolledAt`).
+ * `db.recoverUser` method gates this with the `peer-recover-user`
+ * policy gate (#33's factor-proof requirement); the function below
+ * enforces only the role + anti-privilege-escalation invariants.
  *
- * @param deks      Map of collection-name → DEK (extractable).
- * @param code      The plaintext recovery code (caller-supplied;
- *                  pair this with `@noy-db/on-recovery`'s code
- *                  generator/parser if available).
- * @param codeId    Stable id used by `burnPaperRecoveryEntry`.
+ * @module
  */
-declare function mintPaperRecoveryEntry(deks: Map<string, CryptoKey>, code: string, codeId: string): Promise<PaperRecoveryEntry>;
+
+/** Input shape for {@link recoverUser}. */
+interface RecoverUserOptions {
+    /** Target user id whose keyring is being recovered. */
+    readonly userId: string;
+    /**
+     * Temporary passphrase under which the new keyring is wrapped.
+     * The recipient should call `db.rotatePassphrase` immediately on
+     * acceptance to choose their own phrase — this temp acts as a
+     * single-use bridge in invite / peer-recovery flows.
+     */
+    readonly passphrase: string;
+    /** Override the target's role. Defaults to the existing target's role. */
+    readonly role?: Role;
+    /** Override the target's display name. Defaults to existing. */
+    readonly displayName?: string;
+    /** Validate phrase strength against the configured policy. */
+    readonly validatePassphrase?: boolean;
+    /**
+     * Skip phrase strength validation even when `validatePassphrase` is
+     * set. The escape hatch matches `grant`'s shape — used when the
+     * temp phrase is a high-entropy one-shot string that doesn't need
+     * to satisfy the human-typeable rules.
+     */
+    readonly allowWeakPassphrase?: boolean;
+    /**
+     * Optional explicit phrase policy override (passed through to
+     * `assertStrongPassphrase`). Mirrors how `grant` accepts a custom
+     * `PassphrasePolicy` for app-specific tightening.
+     */
+    readonly passphrasePolicy?: PassphrasePolicy;
+}
 /**
- * Decrypt a recovery entry to recover the raw DEK set. Used by the
- * `recoverPassphrase` flow after the user's code has been parsed.
- *
- * Thin wrapper over {@link unwrapDeksFromBlob} (#44).
+ * Atomically rewrap the target user's keyring under a fresh temp
+ * passphrase. Single store write; no revoke step; no key rotation.
  *
- * @throws when the code does not match the entry (AES-GCM auth tag fail).
+ * Caller's responsibilities (NOT enforced here):
+ *   - Run the `peer-recover-user` policy gate first via
+ *     `Noydb.checkGate` to enforce the freshness factor proof.
+ *   - Communicate the temp passphrase to the recipient via a secure
+ *     channel (URL fragment, in-person, etc.) — the hub does not
+ *     transport secrets.
  */
-declare function unwrapDeksFromPaperEntry(entry: PaperRecoveryEntry, code: string): Promise<Map<string, CryptoKey>>;
+declare function recoverUser(store: NoydbStore, vault: string, callerKeyring: UnlockedKeyring, options: RecoverUserOptions): Promise<void>;
 
 /**
  * Public envelope — owner-curated plaintext metadata, readable
@@ -3833,6 +4018,12 @@ interface StagedOp {
     id: string;
     record?: unknown;
     expectedVersion?: number;
+    /**
+     * Optional human-readable tag forwarded to the resulting ledger
+     * entry's `reason` field (#1). Set by callers via
+     * `tx.vault(v).collection(c).put(id, record, { reason })`.
+     */
+    reason?: string;
 }
 /**
  * One executed op (main staged op or recursive side-effect like a
@@ -3922,6 +4113,7 @@ declare class TxCollection<T> {
      */
     put(id: string, record: T, options?: {
         expectedVersion?: number;
+        reason?: string;
     }): void;
     /**
      * Stage a delete. Does not write until the transaction body returns.
@@ -4026,6 +4218,16 @@ interface GatePolicy {
  * configured policy as "no gate" (no-op).
  */
 type BuiltInGateName = 'rotate-passphrase' | 'recover-passphrase' | 'enroll-authenticator' | 'remove-authenticator'
+/**
+ * Authorize a deliberate paper-recovery-code regeneration —
+ * `db.rotateRecovery` (#121). Symmetric to `rotate-passphrase` for
+ * the case where the user remembers their passphrase but wants a
+ * fresh sheet (lost the printout, suspect compromise of the off-site
+ * copy). PERSONAL allows tier-1; STRICT requires an off-device
+ * factor so a stolen unlocked laptop cannot silently mint a new
+ * sheet for an attacker.
+ */
+ | 'rotate-recovery'
 /**
  * Authorize a meta-only mutation on an existing authenticator slot —
  * `db.updateAuthenticator` (#55). The slot's wrap material, id, and
@@ -4118,6 +4320,14 @@ declare class Noydb {
      * `_meta/policy` load; replaced by `db.updatePolicy()`.
      */
     private readonly policyCache;
+    /**
+     * One-shot bypass for the managed-mode strong-recovery check (#195).
+     * Set true by {@link openVaultAndEnrollRecovery} for the duration of
+     * the bootstrap window so the keyring can be created before the
+     * strong recovery is enrolled. Always cleared (try/finally).
+     * @internal
+     */
+    private _skipNextManagedRecoveryCheck;
     /** Per-vault tier-3 (PIN / quick-resume) state — issue #11. */
     private readonly quickUnlock;
     /**
@@ -4581,15 +4791,29 @@ declare class Noydb {
     /** Read or persist the vault policy at `_meta/policy` on first open. */
     private bootstrapPolicy;
     /**
-     * Throw {@link RecoveryNotEnrolledError} when the developer
-     * explicitly opts into strict mandatory-recovery enforcement
-     * (`createNoydb({ requireRecovery: true })`) and no recovery
-     * entries are persisted.
+     * Throw {@link RecoveryNotEnrolledError} or
+     * {@link ManagedRecoveryNotEnrolledError} when recovery enrollment
+     * is missing.
      *
-     * The default behavior is lenient — `recover-passphrase` is enabled
-     * in `PERSONAL_POLICY` but the hub does not block vault open on
-     * missing enrollment. v1.0 will flip the default to strict; for now,
-     * apps that want the spec-mandated check turn it on per-vault.
+     * Two enforcement modes:
+     *
+     * 1. **Managed-mode mandatory strong-recovery (#195).** When
+     *    `passphraseMode === 'managed'`, the vault MUST have at least
+     *    one **strong** recovery profile (Shamir today). Paper alone is
+     *    rejected because under managed mode the user has no memorized
+     *    passphrase, so losing the paper sheet = losing every record.
+     *    This check is unconditional — independent of `requireRecovery`
+     *    and the `recover-passphrase` gate.
+     *
+     * 2. **Opt-in strict mandatory-recovery.** When
+     *    `requireRecovery: true` is set on createNoydb (and the gate is
+     *    not explicitly disabled), require ANY recovery profile (paper
+     *    or shamir). This is the v0.x default-off behavior; v1.0 may
+     *    flip it default-on.
+     *
+     * The managed-mode check fires from {@link bootstrapPolicy} unless
+     * the `skipManagedCheck` flag is set (used by
+     * {@link openVaultAndEnrollRecovery} to allow atomic create-and-enroll).
      */
     private assertRecoveryEnrolled;
     /**
@@ -4785,6 +5009,123 @@ declare class Noydb {
      * Burns the used recovery entry on success.
      */
     recoverPassphrase(vault: string, input: RecoverPassphraseInput, factors?: FactorProofBundle): Promise<RecoverPassphraseResult>;
+    /**
+     * Deliberate paper-recovery-code regeneration (#121). User knows their
+     * passphrase but wants a fresh sheet — they lost the printout or
+     * suspect compromise of the off-site copy.
+     *
+     * Symmetric to {@link rotatePassphrase} for the recovery profile:
+     * gated, audit-trackable, ergonomic. Replaces (not appends) the
+     * paper sheet under `_meta/recovery-paper` in a single envelope `put`.
+     *
+     * Gated by the `rotate-recovery` policy gate:
+     *   - PERSONAL_POLICY: `{ minTier: 1 }` — knowing the passphrase
+     *     suffices, matching the pre-#121 low-level flow's bar.
+     *   - STRICT_POLICY: `{ minTier: 1, factors: [{ anyOf: ['totp',
+     *     'email-otp', 'webauthn-roaming'] }] }` — rotation is an
+     *     off-site-trust event; require an off-device factor so a
+     *     stolen unlocked laptop cannot silently mint a sheet for the
+     *     attacker.
+     *
+     * Defaults `count` to the existing sheet size so consumers aren't
+     * surprised by a different code count. Explicit `count` overrides.
+     *
+     * @throws {@link RecoveryProfileNotImplementedError} when `profile`
+     *         is anything other than `'paper'` (v1 dispatch limit).
+     * @throws {@link PolicyDeniedError} when the gate denies (missing
+     *         factor, tier mismatch, ...).
+     * @throws on missing paper sheet — "nothing to rotate" surfaces as
+     *         an error rather than silently minting an entire new sheet.
+     *
+     * @example Default count + show-once UI
+     * ```ts
+     * const { newCodes } = await db.rotateRecovery('acme', { profile: 'paper' })
+     * showCodesToUser(newCodes)
+     * ```
+     *
+     * @example STRICT-policy site with TOTP factor proof
+     * ```ts
+     * await db.rotateRecovery(
+     *   'acme',
+     *   { profile: 'paper', count: 10 },
+     *   { factors: [{ kind: 'totp', proof: '123456' }] },
+     * )
+     * ```
+     */
+    rotateRecovery(vault: string, options: RotateRecoveryOptions, factors?: FactorProofBundle): Promise<RotateRecoveryResult>;
+    private rotateRecoveryPaper;
+    private rotateRecoveryShamir;
+    /**
+     * **Atomic create-and-enroll for managed-mode vaults (#195).**
+     *
+     * Bootstraps a managed-mode vault and enrolls strong recovery in
+     * a single ceremony. Under `passphraseMode: 'managed'`, every
+     * `openVault` call requires a strong recovery profile (Shamir
+     * today) to be enrolled — otherwise it throws
+     * {@link ManagedRecoveryNotEnrolledError}. This method bypasses
+     * the check temporarily so the keyring can be created, enrolls
+     * the supplied recovery profile(s), then returns the vault.
+     *
+     * For Shamir enrollments, the show-once share strings come back
+     * in `recoveryEnrollments[i].shares`. The hub never retains them
+     * — the caller MUST display them to the user (once) before any
+     * subsequent operation.
+     *
+     * Paper alone is NOT a strong profile under managed mode; passing
+     * `{ profile: 'paper', ... }` without an accompanying shamir entry
+     * is rejected at validation time.
+     *
+     * ```ts
+     * const db = await createNoydb({
+     *   store, user: 'alice',
+     *   passphraseMode: 'managed',
+     *   sealingKey: macosKeychainSealingProvider({ ... }),
+     * })
+     *
+     * const { vault, recoveryEnrollments } = await db.openVaultAndEnrollRecovery('acme', {
+     *   recovery: [{ profile: 'shamir', k: 2, n: 3 }],
+     * })
+     * for (const r of recoveryEnrollments) {
+     *   if (r.shares) showSharesToUser(r.shares)  // ONCE
+     * }
+     * ```
+     *
+     * @throws ValidationError if recovery is empty, or contains no
+     *   strong profile under managed mode.
+     */
+    openVaultAndEnrollRecovery(vault: string, opts: {
+        readonly recovery: ReadonlyArray<RecoveryEnrollmentInput>;
+        readonly locale?: string;
+    }): Promise<{
+        readonly vault: Vault;
+        readonly recoveryEnrollments: ReadonlyArray<EnrollRecoveryResult>;
+    }>;
+    /**
+     * **Recovery flow under managed-passphrase mode (#195).**
+     *
+     * Replaces the sealed passphrase of a managed-mode vault with a
+     * fresh 256-bit random, sealed under the configured
+     * `SealingKeyProvider`. The user never sees the new passphrase.
+     *
+     * Internally:
+     *   1. Verify the recovery proof (Shamir today) and unwrap the
+     *      DEK set.
+     *   2. Mint a fresh 256-bit random as the new effective passphrase.
+     *   3. Rewrap the DEK set under a fresh KEK derived from the new
+     *      passphrase (via the existing `recoverPassphrase` path).
+     *   4. Seal the random bytes under the provider and overwrite
+     *      `_meta/sealed-passphrase`.
+     *   5. Drop the keyring cache so the next operation re-derives.
+     *
+     * The vault's strong-recovery enrollment is preserved across
+     * recovery (Shamir entries are not burned on use — see #196).
+     *
+     * @throws ValidationError if the Noydb instance is not in managed mode.
+     */
+    recoverManagedPassphrase(vault: string, options: {
+        readonly recoveryProof: RecoveryProof;
+        readonly passphrasePolicy?: PassphrasePolicy;
+    }): Promise<void>;
     /**
      * Atomic peer-recovery — re-wraps an EXISTING user's keyring under
      * a fresh temp passphrase in a single store write. Closes #34's
@@ -4860,13 +5201,11 @@ declare class Noydb {
      * await db.enrollRecovery('acme', { profile: 'paper', entries })
      * ```
      */
-    enrollRecovery(vault: string, enrollment: {
-        profile: 'paper';
-        entries: ReadonlyArray<PaperRecoveryEntry>;
-    }): Promise<void>;
-    /** Read the persisted paper-recovery entries. Used by `describeAuthConfig` (#13). */
+    enrollRecovery(vault: string, enrollment: RecoveryEnrollmentInput): Promise<EnrollRecoveryResult>;
+    /** Read the persisted recovery entries (paper + Shamir). Used by `describeAuthConfig` (#13). */
     listRecoveryEntries(vault: string): Promise<{
         paper: ReadonlyArray<PaperRecoveryEntry>;
+        shamir: ReadonlyArray<ShamirRecoveryEntry>;
     }>;
     /**
      * Register a tier-3 quick-unlock state for the vault. The state is
@@ -5062,6 +5401,39 @@ interface GuardStrategyHandle<T extends Record<string, unknown>> {
     readonly __noydb_strategy: 'guard';
     readonly spec: GuardStrategy<T>;
 }
+/**
+ * Existential erasure of `GuardStrategyHandle<T>` — used as the
+ * element type of `ReadonlyArray<>` fields where the per-handle T
+ * differs (e.g. `guardStrategies: [invoiceGuard, disbursementGuard]`).
+ *
+ * Background: `GuardStrategyHandle<T>` is INVARIANT in T because T
+ * appears in callback positions on the spec (`check(incoming: T, ctx)`,
+ * `invariant(changes: ReadonlyArray<GuardChange<T>>, ctx)`). So
+ * `Handle<Invoice>` is not assignable to `Handle<Record<string, unknown>>`.
+ * A bounded existential ("there exists some T satisfying the constraint
+ * such that this is a Handle<T>") is the right shape; TypeScript has
+ * no first-class existentials, so we fake it with a structurally narrow
+ * interface that ERASES T from both the discriminant and the spec.
+ *
+ * Consumers continue to construct typed handles via `withGuard<T>(...)`
+ * which returns `GuardStrategyHandle<T>`. Both `Handle<Invoice>` and
+ * `Handle<Disbursement>` structurally assign to `GuardStrategyHandleAny`,
+ * so an array of them is `GuardStrategyHandleAny[]`.
+ *
+ * Internal code that needs T re-narrows via the runtime discriminant
+ * (`__noydb_strategy === 'guard'`) plus per-handle type information
+ * carried by the registry.
+ *
+ * NOT exported from the public barrel — keeping this internal
+ * discourages consumers from constructing it directly. Used only as
+ * the array-element type on `Vault` / `NoydbOptions.guardStrategies`.
+ *
+ * @internal
+ */
+interface GuardStrategyHandleAny {
+    readonly __noydb_strategy: 'guard';
+    readonly spec: GuardStrategy<any>;
+}
 /** Public registration shape. See `withGuard()`. */
 interface GuardStrategy<T extends Record<string, unknown>> {
     collection: string;
@@ -5154,8 +5526,8 @@ interface DerivedFromMeta {
      */
     readonly strategyHash: string;
 }
-/** Per-output declaration. v1: only `'record'` shape. */
-interface OutputSpec {
+/** Record-shape output — one source row produces (optionally) one output row at the source's id. */
+interface RecordOutputSpec {
     shape: 'record';
     collection: string;
     /**
@@ -5169,6 +5541,50 @@ interface OutputSpec {
      */
     optional?: boolean;
 }
+/**
+ * Array-shape output (#200) — one source row produces a variable-length
+ * list of output rows, each with its own id (from the `key` extractor).
+ *
+ * On every source-row change, the dispatcher diffs the previously
+ * emitted key set against the new one: removed keys are deleted via
+ * `_internalDelete`, new and unchanged keys are upserted via
+ * `Collection.put`. Strict-mode rollback is preserved via the existing
+ * `_executed` tracking.
+ *
+ * Storage of the per-source-row key set lives at
+ * `_meta/derivations-fanout/<source>/<sourceId>/<outputKey>` as a
+ * plain JSON sidecar — keeps dispatch cost O(1) per source row.
+ *
+ * **Slice 1 limitation**: only `lifecycle: 'eager'` is supported.
+ * Registering an array-shape output with `lifecycle: 'lazy'` throws
+ * at `withDerivation` construction time.
+ */
+interface ArrayOutputSpec {
+    shape: 'array';
+    collection: string;
+    /**
+     * Stable identity extractor for each derived row. Called on every
+     * row returned by `derive`. The string MUST be unique within a
+     * single invocation — duplicate keys throw
+     * `DerivationOutputShapeError`.
+     *
+     * Type is intentionally `(out: Record<string, unknown>) => string`
+     * (not generic) because OutputSpec is type-erased at the registry
+     * level. Strategy-level inference still produces typed `out`
+     * through the strategy's `outputs` map.
+     */
+    key: (output: Record<string, unknown>) => string;
+    /**
+     * Cap on derived rows per source-row invocation. Defaults to 64.
+     * Raise for carry-forward cases (e.g. monthly expansion of
+     * multi-year contracts). Exceeding the cap throws
+     * `DerivationCapExceededError` BEFORE any writes — partial fanout
+     * is never persisted.
+     */
+    maxFanout?: number;
+}
+/** Discriminated union — record + array. */
+type OutputSpec = RecordOutputSpec | ArrayOutputSpec;
 /**
  * Registration shape passed to `withDerivation()`.
  *
@@ -5298,6 +5714,28 @@ interface MaterializedViewOutput {
         value: unknown;
     };
 }
+/**
+ * One arm of a UNION materialized view. Reads rows from `collection`,
+ * then maps each into the MV's row shape via `map`.
+ *
+ * The per-source `map` is the schema-unification boundary — sibling
+ * collections can have different schemas, and `map` is where they
+ * meet the MV's row type. The hub does NOT compare schemas across
+ * arms; consumer responsibility is that every arm's `map` returns
+ * the same shape (the strategy's `TRow` type parameter enforces this
+ * at compile time).
+ */
+interface UnionSource<TRow extends Record<string, unknown>> {
+    /** Source collection name. Must exist in the vault. */
+    readonly collection: string;
+    /**
+     * Pure function from a source row to the unified MV row shape.
+     * Called once per source row at materialization time. Each arm's
+     * mapped output is concatenated into a single stream before
+     * `groupBy` + `aggregate` run.
+     */
+    readonly map: (sourceRow: Record<string, unknown>) => TRow;
+}
 /**
  * Registration shape passed to `withMaterializedView()`.
  *
@@ -5310,16 +5748,59 @@ interface MaterializedViewStrategy<TRow extends Record<string, unknown>> {
      */
     name: string;
     /**
-     * Declared query. Called at registration time with a vault-shaped
-     * accessor so the closure can compose collections without
-     * pre-existing in-scope references; called again at each refresh.
+     * Declared query (single-source mode). Called at registration time
+     * with a vault-shaped accessor so the closure can compose collections
+     * without pre-existing in-scope references; called again at each
+     * refresh.
      *
      * Built via the same `Query<T>` chainable builder used elsewhere —
      * `.where()`, `.join()`, `.groupBy()`, `.aggregate()`. The
      * dependency analyzer walks the returned plan to determine source
      * collections.
+     *
+     * Mutually exclusive with {@link unionSources}: a strategy must
+     * declare exactly one of `query` (single-source) or `unionSources`
+     * (multi-source UNION). Registration throws
+     * `MaterializedViewConfigError` if both are set or neither is set.
+     */
+    query?: (db: MVQueryContext) => Query<TRow>;
+    /**
+     * UNION-form sources (#165): an explicit list of sibling collections
+     * that contribute rows to a single MV. Each arm's `map` projects a
+     * source row into the MV's unified row shape; the mapped streams are
+     * concatenated, then {@link groupBy} + {@link aggregate} run on the
+     * combined output.
+     *
+     * Mutually exclusive with {@link query}. Registration throws
+     * `MaterializedViewConfigError` if both are set, if `unionSources`
+     * has fewer than 2 arms, or if two arms name the same `collection`.
+     *
+     * UNION mode replaces the dependency-analyzer path: the source
+     * collections come directly from `unionSources[].collection`, and
+     * {@link sources} is ignored.
+     */
+    unionSources?: ReadonlyArray<UnionSource<TRow>>;
+    /**
+     * Group-key field(s) for UNION mode (#165). Applied to the
+     * concatenated mapped-row stream from {@link unionSources} before
+     * {@link aggregate} runs. Accepts a single field name or a tuple of
+     * field names for multi-key grouping (same shape as
+     * `Query.groupBy(...fields)`).
+     *
+     * UNION-mode only. Ignored if {@link query} is set — single-source
+     * grouping is expressed inside the `Query<T>` returned from `query()`
+     * via `.groupBy(...).aggregate(...)`.
+     */
+    groupBy?: string | ReadonlyArray<string>;
+    /**
+     * Aggregation spec for UNION mode (#165). Applied per-group after
+     * {@link groupBy} buckets the concatenated mapped-row stream from
+     * {@link unionSources}. Same shape as the `AggregateSpec` passed to
+     * `Query.aggregate()`.
+     *
+     * UNION-mode only. Ignored if {@link query} is set.
      */
-    query: (db: MVQueryContext) => Query<TRow>;
+    aggregate?: AggregateSpec;
     /**
      * Pure function from a materialized row → stable id used in the
      * output collection. Required — explicit always beats default-with-pitfalls
@@ -6268,6 +6749,159 @@ declare class UserApi {
     private fireChange;
 }
 
+/**
+ * Persisted-schema envelope shape.
+ *
+ * Stored encrypted under `_schemas/<collection>` with the same DEK as the
+ * collection's records. Auditors who can unlock the collection's data can
+ * also read its schema; nothing more.
+ *
+ * @see docs/superpowers/specs/2026-05-22-schema-dump-design.md
+ *
+ * @module
+ */
+/** Family of Standard Schema v1 validator the persisted snapshot was derived from. */
+type PersistedSchemaKind = 'Zod' | 'Valibot' | 'ArkType' | 'Effect' | 'Unknown';
+/**
+ * Plaintext payload encrypted into the `_data` field of the
+ * `_schemas/<collection>` envelope. The wrapper `EncryptedEnvelope` adds
+ * `_noydb`, `_v`, `_ts`, `_iv`, `_data` per the standard noy-db record
+ * format.
+ */
+interface PersistedSchemaEnvelope {
+    readonly _noydb_schema: 1;
+    /** Detected validator family. */
+    readonly kind: PersistedSchemaKind;
+    /**
+     * JSON Schema (Draft 2020-12) derived from the validator. Null when
+     * derivation isn't yet supported for `kind`; in that case `reason` is
+     * populated.
+     */
+    readonly jsonSchema: object | null;
+    /** SHA-256 (hex) of the canonicalised JSON Schema, or null when unavailable. */
+    readonly hash: string | null;
+    /** Human-readable reason when `jsonSchema` is null. */
+    readonly reason?: string;
+    /** ISO-8601 timestamp of the most recent derivation write. */
+    readonly derivedAt: string;
+}
+
+/**
+ * Types for {@link VaultSchemaSnapshot} — the structured object returned
+ * by `vault.dumpSchema()`. Consumed by the upcoming `noydb describe`
+ * CLI to emit human-readable YAML/JSON audit output.
+ *
+ * @see docs/superpowers/specs/2026-05-22-schema-dump-design.md
+ *
+ * @module
+ */
+
+/** Where the field-level info in the snapshot came from. */
+type FieldSource = 'persisted' | 'live-validator' | 'sampled' | 'unknown';
+interface FieldDescriptor {
+    /** Inferred type tag: 'string' | 'number' | 'boolean' | 'enum' | 'object' | 'array' | 'null' | 'opaque'. */
+    readonly type: string;
+    /** Where this field info was sourced from. */
+    readonly source: FieldSource;
+    /** Optional constraints — minLength, maxLength, enum values, gt, etc. */
+    readonly constraints?: Record<string, unknown>;
+    /** True when the schema marks this field optional. */
+    readonly optional?: boolean;
+    /** Foreign-key target as `<collection>.<field>` when declared. */
+    readonly references?: string;
+}
+interface CollectionStats {
+    readonly records: number;
+    readonly bytes: number;
+    readonly bytesAvg: number;
+    readonly bytesMin: number;
+    readonly bytesMax: number;
+    /** ISO-8601 from min(_ts) across envelopes. Empty string when no records. */
+    readonly oldest: string;
+    /** ISO-8601 from max(_ts) across envelopes. Empty string when no records. */
+    readonly newest: string;
+}
+interface CollectionDescriptor {
+    readonly fields: Record<string, FieldDescriptor>;
+    readonly indexes: ReadonlyArray<{
+        readonly fields: ReadonlyArray<string>;
+        readonly unique?: boolean;
+    }>;
+    readonly refs: Record<string, {
+        readonly target: string;
+        readonly mode: 'strict' | 'warn' | 'cascade';
+    }>;
+    readonly validator?: {
+        readonly kind: PersistedSchemaKind;
+        readonly source: 'persisted' | 'live-validator';
+    };
+    readonly stats?: CollectionStats;
+}
+interface MaterializedViewDescriptor {
+    readonly sources: ReadonlyArray<string>;
+    readonly groupBy?: ReadonlyArray<string>;
+    readonly aggregate?: Record<string, string>;
+    readonly refresh: string;
+    readonly stats?: CollectionStats;
+}
+interface OverlayViewDescriptor {
+    readonly base: string;
+    readonly overlay: string;
+}
+interface DerivationDescriptor {
+    readonly source: string;
+    readonly outputs: ReadonlyArray<string>;
+}
+interface InternalCollectionStats {
+    readonly records: number;
+    readonly bytes: number;
+}
+interface VaultSchemaSnapshot {
+    readonly _noydb_snapshot: 1;
+    readonly vault: string;
+    readonly emittedAt: string;
+    readonly subsystems: Record<string, boolean>;
+    readonly aclRoles?: ReadonlyArray<string>;
+    readonly collections: Record<string, CollectionDescriptor>;
+    readonly materializedViews: Record<string, MaterializedViewDescriptor>;
+    readonly overlayViews: Record<string, OverlayViewDescriptor>;
+    readonly derivations: Record<string, DerivationDescriptor>;
+    /** Only present when `dumpSchema({ withStats: true })` was called. */
+    readonly internal?: Record<string, InternalCollectionStats>;
+}
+interface DumpSchemaOptions {
+    /** When true, walk every collection's envelopes to compute counters. Default `false`. */
+    readonly withStats?: boolean;
+    /** Sample N records per collection lacking a persisted/live schema. Default 50. `0` disables sampling. */
+    readonly sampleSize?: number;
+}
+
+/**
+ * Orchestrate the structural walk of a Vault, producing a
+ * {@link VaultSchemaSnapshot}. Called from `Vault.dumpSchema()`.
+ *
+ * @module
+ */
+
+/**
+ * The minimal slice of Vault internal state the walker needs.
+ * Exposed via `vault._introspectState()` to keep the public Vault
+ * surface narrow.
+ *
+ * @internal
+ */
+interface VaultIntrospectState {
+    readonly name: string;
+    readonly adapter: NoydbStore;
+    readonly collectionCache: Map<string, Collection<unknown>>;
+    readonly refRegistry: RefRegistry;
+    readonly getDEK: (collectionName: string) => Promise<CryptoKey>;
+    readonly subsystems: Record<string, boolean>;
+    readonly mvRegistry: unknown;
+    readonly overlayRegistry: unknown;
+    readonly derivationRegistry: unknown;
+}
+
 /** A vault (tenant namespace) containing collections. */
 declare class Vault {
     private readonly adapter;
@@ -6391,6 +7025,16 @@ declare class Vault {
      * docstring.
      */
     private ledgerStore;
+    /**
+     * Background writes for persisted-schema envelopes (#schema-dump v0
+     * slice 1). One promise per `collection({ persistJsonSchema: true })`
+     * registration that actually fired a derive call. Fire-and-forget
+     * from the collection factory; tests await
+     * {@link _drainPendingSchemaWrites} before asserting on storage.
+     * Production code does not need to drain — the writes are
+     * idempotent fingerprints, not correctness invariants.
+     */
+    private _pendingSchemaWrites;
     /**
      * Per-vault foreign-key reference registry. Collections
      * register their `refs` option here on construction; the
@@ -6502,7 +7146,7 @@ declare class Vault {
         historyStrategy?: HistoryStrategy | undefined;
         i18nStrategy?: I18nStrategy | undefined;
         syncStrategy?: SyncStrategy | undefined;
-        guardStrategies?: ReadonlyArray<GuardStrategyHandle<any>> | undefined;
+        guardStrategies?: ReadonlyArray<GuardStrategyHandleAny> | undefined;
     });
     /**
      * Construct (or reconstruct) the lazy DEK resolver. Captures the
@@ -6575,7 +7219,26 @@ declare class Vault {
         tiers?: readonly number[];
         /**  — how lower-tier reads see above-tier records. */
         tierMode?: TierMode;
+        /**
+         * Opt-in persisted JSON Schema. When `true` AND a Zod `schema` is
+         * provided, hub derives a JSON Schema via `zod-to-json-schema`
+         * (optional peer-dep) and writes an encrypted snapshot to
+         * `_schemas/<collectionName>`. Re-runs on every open; hash-skip
+         * avoids write churn when the schema is unchanged.
+         *
+         * Default: `false`. Non-Zod Standard Schema validators receive a
+         * stub envelope flagging the kind without a JSON Schema body.
+         *
+         * @see docs/superpowers/specs/2026-05-22-schema-dump-design.md
+         */
+        persistJsonSchema?: boolean;
     }): Collection<T>;
+    /**
+     * Await all background persisted-schema writes triggered by
+     * `collection({ persistJsonSchema: true })` calls on this vault.
+     * Used in tests; production code does not need to call this.
+     */
+    _drainPendingSchemaWrites(): Promise<void>;
     /**
      * Validate i18nText fields on a `put()`. Called by Collection just
      * before the adapter write, after schema validation. Throws
@@ -6876,7 +7539,7 @@ declare class Vault {
      * accessor `_getReadOnlyFacade()` (called from the tx amendment
      * runner) stays synchronous.
      */
-    _initGuards(handles: ReadonlyArray<GuardStrategyHandle<any>>): Promise<void>;
+    _initGuards(handles: ReadonlyArray<GuardStrategyHandleAny>): Promise<void>;
     /**
      * @internal — Collection.put calls into this. Returns `null` for
      * vaults that never registered any guard strategy. Callers MUST
@@ -7186,6 +7849,34 @@ declare class Vault {
     private _decryptPeriodRecord;
     /** List all collection names in this vault. */
     collections(): Promise<string[]>;
+    /**
+     * Emit a structured introspection snapshot of this vault — vault name,
+     * subsystem opt-in matrix, collections + their fields, materialized
+     * views, overlay views, derivations. With `withStats: true`, walks
+     * every collection's envelopes to compute record counts, byte totals,
+     * and oldest/newest timestamps.
+     *
+     * Consumed by the `noydb describe` CLI to produce human-readable
+     * audit YAML/JSON from a `.noydb` bundle.
+     *
+     * Field provenance:
+     *   - `persisted`: read from `_schemas/<col>` envelope (Route B opt-in)
+     *   - `live-validator`: derived in-process from a Zod schema attached
+     *     to the live `Collection`
+     *   - `sampled`: inferred from decrypted records (deferred to a follow-up)
+     *   - `unknown`: no schema info available
+     *
+     * @see docs/superpowers/specs/2026-05-22-schema-dump-design.md
+     */
+    dumpSchema(opts?: DumpSchemaOptions): Promise<VaultSchemaSnapshot>;
+    /**
+     * Internal accessor for {@link dumpVaultSchema}. Exposes the structural
+     * state the walker needs (collection cache, registries, ref registry,
+     * adapter) without widening the public Vault surface.
+     *
+     * @internal
+     */
+    _introspectState(): VaultIntrospectState;
     /**
      * Return the stable opaque bundle handle for this vault,
      * generating and persisting a fresh ULID on first call.
@@ -8241,8 +8932,20 @@ declare class Collection<T> {
         staleMs?: number;
         pollIntervalMs?: number;
     }): PresenceHandle<P>;
-    /** Create or update a record. */
-    put(id: string, record: T): Promise<void>;
+    /**
+     * Create or update a record.
+     *
+     * @param id      Record identifier.
+     * @param record  The record body (validated by the collection's schema
+     *                if one was attached at `vault.collection(...)` time).
+     * @param options Optional metadata for audit + import workflows.
+     *                `reason` is stamped onto the resulting ledger entry
+     *                (see #1) so audit consumers can filter via
+     *                `entries.filter(e => e.reason?.startsWith('import:'))`.
+     */
+    put(id: string, record: T, options?: {
+        readonly reason?: string;
+    }): Promise<void>;
     /**
      * Fire registered MV strategies whose dependency set includes this
      * collection. Eager-mode MVs re-materialize inline via
@@ -8310,6 +9013,28 @@ declare class Collection<T> {
      */
     _internalDelete(id: string, txCtx?: TxContext | null): Promise<void>;
     private _doDelete;
+    /**
+     * Cascade deletes of array-shape derived rows when a source row is
+     * deleted (#200). Reads each registered strategy's fanout sidecar
+     * for this source id, deletes every listed derived row, then
+     * deletes the sidecar itself.
+     *
+     * Record-shape derivations are skipped — see _doDelete's comment
+     * for why the asymmetry is correct.
+     *
+     * @internal
+     */
+    private dispatchArrayDerivationsOnDelete;
+    /**
+     * Mirror of {@link dispatchMaterializedViews} for the delete path
+     * (#181). No record content is available (it's gone), so the
+     * `_materializedFrom` skip used by the put-side dispatch doesn't
+     * apply here — instead, the recursion guard is the `internal` gate
+     * at the `_doDelete` call site above.
+     *
+     * @internal
+     */
+    private dispatchMaterializedViewsOnDelete;
     /**
      * List all records in the collection.
      *
@@ -9138,6 +9863,160 @@ interface SessionStrategy {
     revokeAllSessions(): void;
 }
 
+/**
+ * Managed-passphrase mode — issue #14, rubber-hose-resistant vaults.
+ *
+ * A vault mode where the passphrase is machine-generated and never
+ * exposed to the user, sealed under a developer-provided
+ * {@link SealingKeyProvider} (macOS Keychain, Windows Credential
+ * Manager, libsecret, AWS KMS, …). The user has no secret to give
+ * up to coercion — they can't reveal what they don't know.
+ *
+ * ## Components in this file
+ *
+ *   - {@link SealingKeyProvider} — the interface concrete providers
+ *     implement. Provider implementations live OUTSIDE hub (per-
+ *     platform packages).
+ *   - {@link MemorySealingKeyProvider} — in-memory test provider; uses
+ *     a deterministic per-instance "key" so two providers with
+ *     different ids cannot unseal each other's outputs.
+ *   - {@link loadSealedPassphrase} / {@link saveSealedPassphrase} —
+ *     plaintext envelope storage at `_meta/sealed-passphrase`.
+ *     Mirrors the `_meta/handle` and `_meta/public-envelope` AES-
+ *     GCM-bypassed patterns. The sealing layer (provider's job)
+ *     is the security boundary; hub doesn't have a key to encrypt
+ *     with at this layer — that's the whole point of the design.
+ *   - {@link resolveManagedSecret} — orchestrates the "generate +
+ *     seal + persist on first open; unseal on reopen" flow.
+ *     Returns the plaintext passphrase string that the rest of the
+ *     `createNoydb` keyring path consumes.
+ *
+ * Slice 1 of #14. Deferred to follow-ups:
+ *   - Block `rotate-passphrase` policy gate under managed mode.
+ *   - Mandatory strong-recovery enforcement (depends on #10).
+ *   - Recovery flow under managed mode (generates fresh sealed phrase).
+ *
+ * @see docs/subsystems/session-tiers.md → Managed-passphrase mode
+ *
+ * @module
+ */
+
+/**
+ * The contract concrete providers (per-platform key stores) implement
+ * to seal and unseal a hub-generated random passphrase. The plaintext
+ * passphrase NEVER leaves hub-controlled memory in unsealed form —
+ * the provider receives the bytes, returns opaque sealed bytes, and
+ * later reverses the operation. Hub treats the sealed bytes as
+ * fully opaque.
+ *
+ * Implementations live OUTSIDE `@noy-db/hub` (separate packages
+ * per the issue's "Concrete providers (live outside hub)" note):
+ *
+ * | Platform | Package (TBD) | Backing |
+ * |---|---|---|
+ * | macOS | `@noy-db/seal-macos-keychain` | Security.framework |
+ * | Windows | `@noy-db/seal-wincred` | Credential Manager |
+ * | Linux | `@noy-db/seal-libsecret` | libsecret / secret-service |
+ * | Cloud / server | `@noy-db/seal-aws-kms` | AWS KMS Decrypt |
+ */
+interface SealingKeyProvider {
+    /**
+     * Non-sensitive identifier disclosed in the persisted envelope.
+     * Surfaced to consumers via `loadSealedPassphrase().providerId` so
+     * a vault opened with the wrong provider class can detect the
+     * mismatch and surface a clear error. NOT secret — fine to log.
+     *
+     * Suggested format: `<family>:<scope>` — e.g. `macos-keychain:com.acme.app`,
+     * `aws-kms:arn:aws:kms:us-east-1:123:key/abc`. The hub never
+     * parses this; it's purely audit metadata.
+     */
+    readonly id: string;
+    /** Seal raw passphrase bytes. Output bytes are opaque to hub. */
+    seal(passphrase: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Reverse {@link seal}. MUST throw on tamper, wrong-provider, or
+     * any other failure — hub treats a thrown error as "this provider
+     * cannot unlock this vault" and surfaces it to the caller.
+     */
+    unseal(sealed: Uint8Array): Promise<Uint8Array>;
+}
+/**
+ * In-memory test provider. NOT secure — uses a deterministic
+ * per-instance "key" (16-byte SHA-256 of `id`) XOR'd over the
+ * passphrase plus a 4-byte provider-id fingerprint prefix. The XOR is
+ * sufficient to make different `id` values produce mutually-unsealable
+ * outputs (the contract tests for that), but offers ZERO real
+ * confidentiality — never use outside tests.
+ *
+ * Replace with a real platform provider in production.
+ */
+declare class MemorySealingKeyProvider implements SealingKeyProvider {
+    readonly id: string;
+    private readonly fingerprint;
+    private readonly keyBytes;
+    constructor(opts: {
+        id: string;
+    });
+    seal(passphrase: Uint8Array): Promise<Uint8Array>;
+    unseal(sealed: Uint8Array): Promise<Uint8Array>;
+}
+/** Reserved id for the managed-passphrase envelope under `_meta`. */
+declare const SEALED_PASSPHRASE_RECORD_ID: "sealed-passphrase";
+/** Plaintext payload stored inside the `_meta/sealed-passphrase` envelope. */
+interface SealedPassphrase {
+    readonly _noydb_sealed: 1;
+    readonly providerId: string;
+    /** Sealed bytes. Base64-encoded on the wire; decoded on load. */
+    readonly sealed: Uint8Array;
+}
+/**
+ * Wire-format envelope persisted at `_meta/sealed-passphrase` for
+ * managed-mode vaults. The provider produces raw sealed bytes via
+ * {@link SealingKeyProvider.seal}; this wrapper carries the dispatch
+ * metadata hub needs to pick the right provider on the unseal path.
+ *
+ * Stability boundary: once shipped, the wire format only grows by
+ * adding optional fields. See the at-* sealing dimension foundation
+ * doc, §11.9.1.
+ *
+ * v1 shape (this release): `{ v: 1, _noydb_sealed: 1, pid, payload }`.
+ *
+ * Legacy shape (pre.14, pre.15): `{ _noydb_sealed: 1, providerId, sealed }`
+ * — accepted on read for backwards compatibility; never produced on
+ * write going forward.
+ */
+interface SealedEnvelope {
+    /** Envelope schema version. v1 is the shape shipped in pre.16. */
+    readonly v: 1;
+    /** Magic marker for forensics + legacy-shape detection. */
+    readonly _noydb_sealed: 1;
+    /** Matches the producing provider's `.id`. Dispatch key on unseal. */
+    readonly pid: string;
+    /** Sealed bytes from the provider, base64-encoded on the wire. */
+    readonly payload: string;
+}
+/**
+ * Parse a `_meta/sealed-passphrase` `_data` JSON string into the
+ * in-memory {@link SealedPassphrase} representation. Accepts both:
+ *
+ *   1. v1 wire format `{ v: 1, _noydb_sealed: 1, pid, payload }` —
+ *      the shape produced from pre.16 onward.
+ *   2. Legacy wire format `{ _noydb_sealed: 1, providerId, sealed }` —
+ *      the shape produced in pre.14/pre.15. Read-only; never written
+ *      going forward.
+ *
+ * Returns `undefined` for any input that doesn't match either shape,
+ * so callers can fall back to "no managed-mode envelope present."
+ *
+ * @internal — exported only for the migration safety-net test suite.
+ */
+declare function parseSealedEnvelope(raw: unknown): SealedPassphrase | undefined;
+declare function saveSealedPassphrase(store: NoydbStore, vault: string, payload: {
+    readonly providerId: string;
+    readonly sealed: Uint8Array;
+}): Promise<void>;
+declare function loadSealedPassphrase(store: NoydbStore, vault: string): Promise<SealedPassphrase | undefined>;
+
 /**
  * Core types — the {@link NoydbStore} interface, envelope format, roles, and
  * all configuration shapes consumed by {@link createNoydb}.
@@ -10656,7 +11535,7 @@ interface NoydbOptions {
      * Multiple guards per collection are allowed; they are dispatched
      * in registration order on `collection.put()`.
      */
-    readonly guardStrategies?: ReadonlyArray<GuardStrategyHandle<any>>;
+    readonly guardStrategies?: ReadonlyArray<GuardStrategyHandleAny>;
     /**
      * Optional derivation strategies — source-to-output projections that
      * fire on `collection.put()`. Each handle is the output of
@@ -10726,6 +11605,29 @@ interface NoydbOptions {
      * subsequent sessions.
      */
     readonly getKeyring?: (vault: string) => Promise<UnlockedKeyring>;
+    /**
+     * Passphrase mode (#14). Default `'standard'`.
+     *
+     *   - `'standard'` — the legacy flow. `secret` supplies the
+     *     plaintext passphrase, the user knows it, and the policy gate
+     *     `rotate-passphrase` is enabled.
+     *   - `'managed'` — rubber-hose-resistant mode. Hub generates a
+     *     256-bit random passphrase at first open and seals it under
+     *     the provided `sealingKey`. The user never sees or types the
+     *     passphrase, defeating the $5-wrench attack. Mutually
+     *     exclusive with `secret` and `getKeyring`.
+     *
+     * @see docs/subsystems/session-tiers.md → Managed-passphrase mode
+     */
+    readonly passphraseMode?: 'standard' | 'managed';
+    /**
+     * Provider that seals/unseals the auto-generated managed-mode
+     * passphrase. Required when `passphraseMode === 'managed'`; ignored
+     * otherwise. Implementations live in per-platform packages
+     * (`@noy-db/seal-macos-keychain`, `@noy-db/seal-wincred`,
+     * `@noy-db/seal-libsecret`, `@noy-db/seal-aws-kms`, …).
+     */
+    readonly sealingKey?: SealingKeyProvider;
     /** Auth method. Default: 'passphrase'. */
     readonly auth?: 'passphrase' | 'biometric';
     /** Enable encryption. Default: true. */
@@ -10929,4 +11831,4 @@ interface DeleteManyResult {
     }>;
 }
 
-export { type ConsentAuditEntry as $, type BlobObject as A, type BlobStrategy as B, type BlobPutOptions as C, DICT_COLLECTION_PREFIX as D, type BlobResponseOptions as E, BlobSet as F, type BlobStrategyOpenArgs as G, type CompactRunOptions as H, type I18nStrategy as I, type CompactionContext as J, type CompactionResult as K, DEFAULT_CHUNK_SIZE as L, EXPORT_AUDIT_COLLECTION as M, ExportBlobsAbortedError as N, type ExportBlobsAuditEntry as O, PolicyEnforcer as P, type ExportBlobsHandle as Q, type ExportBlobsOptions as R, type SessionStrategy as S, type ExportedBlob as T, type SlotInfo as U, type SlotRecord as V, type VersionRecord as W, createExportBlobsHandle as X, runCompaction as Y, type ConsentStrategy as Z, CONSENT_AUDIT_COLLECTION as _, type DictEntry as a, applyPatch as a$, type ConsentAuditFilter as a0, type ConsentContext as a1, type ConsentOp as a2, loadConsentEntries as a3, writeConsentEntry as a4, type PeriodsStrategy as a5, type CarryForwardContext as a6, type ClosePeriodOptions as a7, type OpenPeriodOptions as a8, PERIODS_COLLECTION as a9, type DerivedFromMeta as aA, type OutputSpec as aB, type MaterializedViewStrategy as aC, type MaterializedViewStrategyHandle as aD, type OverlayedViewStrategy as aE, Collection as aF, OverlayedViewRegistry as aG, type OverlayedViewStrategyHandle as aH, type SyncStrategy as aI, type Role as aJ, type UnlockedKeyring as aK, type HistoryStrategy as aL, type NoydbStore as aM, type HistoryOptions as aN, type EncryptedEnvelope as aO, type PruneOptions as aP, type AppendInput as aQ, type ChangeType as aR, CollectionInstant as aS, type DiffEntry as aT, type JsonPatch as aU, type JsonPatchOp as aV, type LedgerEntry as aW, LedgerStore as aX, type VaultEngine as aY, VaultInstant as aZ, type VerifyResult as a_, type PeriodRecord as aa, type ReadOnlyCollection as ab, appendPeriodLedgerEntry as ac, assertTsWritable as ad, chainAnchor as ae, loadPeriods as af, validatePeriodName as ag, type GuardStrategy as ah, type GuardChange as ai, type GuardContext as aj, GuardRegistry as ak, type GuardStrategyHandle as al, ReadOnlyVaultFacade as am, type ShadowStrategy as an, CollectionFrame as ao, VaultFrame as ap, type TxStrategy as aq, type AmendmentTxOptions as ar, TxCollection as as, TxContext as at, TxVault as au, runTransaction as av, type DerivationStrategy as aw, type DerivationContext as ax, DerivationRegistry as ay, type DerivationStrategyHandle as az, type DictKeyDescriptor as b, type IssueMagicLinkGrantOptions as b$, canonicalJson as b0, computePatch as b1, diff as b2, formatDiff as b3, hashEntry as b4, paddedIndex as b5, parseIndex as b6, sha256Hex as b7, type MVQueryContext as b8, type RegisteredMV as b9, DEFAULT_PUBLIC_ENVELOPE_SCHEMA as bA, DELEGATIONS_COLLECTION as bB, type DeepPartial as bC, type DeepPartialOrNull as bD, type DelegationToken as bE, type DeleteManyResult as bF, type DirtyEntry as bG, ELEVATION_AUDIT_COLLECTION as bH, ElevatedHandle as bI, type EnrollAuthenticatorOptions as bJ, type EnrollAuthenticatorWrappingDEKsOptions as bK, type EnrollAuthenticatorWrappingKEKOptions as bL, type ExportCapability as bM, type ExportChunk as bN, type ExportFormat as bO, type ExportStreamOptions as bP, type FactorKind as bQ, type FactorProofBundle as bR, type FactorRequirement as bS, type GhostRecord as bT, type GrantOptions as bU, type HistoryConfig as bV, type HistoryEntry as bW, INDEXED_STORE_POLICY as bX, type ImportCapability as bY, type InferOutput as bZ, type IssueDelegationOptions as b_, MaterializedViewRegistry as ba, type MaterializedFromMeta as bb, type MaterializedViewOutput as bc, type UserEnvelope as bd, type PublicEnvelope as be, type GateName as bf, type GatePolicy as bg, type VaultPolicy as bh, type ActiveTier as bi, type FactorProof as bj, type DirectoryConfig as bk, type UserVisibility as bl, Vault as bm, type AccessibleVault as bn, BUNDLE_STORE_POLICY as bo, type BuiltInGateName as bp, type BundleRecipient as bq, type CacheOptions as br, type CacheStats as bs, type ChangeEvent as bt, type CollectionChangeEvent as bu, type CollectionConflictResolver as bv, type Conflict as bw, type ConflictPolicy as bx, type ConflictStrategy as by, type CrossTierAccessEvent as bz, DictionaryHandle as c, type SetPublicEnvelopeInput as c$, type KeyringAuthenticator as c0, type KeyringAuthenticatorWrappingDEKs as c1, type KeyringAuthenticatorWrappingKEK as c2, type KeyringFile as c3, type ListAccessibleVaultsOptions as c4, type ListPageResult as c5, type ListUsersOptions as c6, type LiveUserEnvelope as c7, type LocaleReadOptions as c8, Lru as c9, type PublicEnvelopeField as cA, type PublicEnvelopeSchema as cB, type PublicEnvelopeText as cC, type PullMode as cD, type PullOptions as cE, type PullPolicy as cF, type PullResult as cG, type PushMode as cH, type PushOptions as cI, type PushPolicy as cJ, type PushResult as cK, type PutManyItemOptions as cL, type PutManyOptions as cM, type PutManyResult as cN, type QueryAcrossOptions as cO, type QueryAcrossResult as cP, type QuickUnlockState as cQ, QuickUnlockStore as cR, type ReAuthOperation as cS, type RecoverPassphraseInput as cT, type RecoverPassphraseResult as cU, type RecoverUserOptions as cV, type RecoveryProof as cW, type ResolvedPublicEnvelopeSchema as cX, type RevokeOptions as cY, type RotatePassphraseInput as cZ, type SessionPolicy as c_, type LruOptions as ca, type LruStats as cb, MAGIC_LINK_CONTENT_INFO_PREFIX as cc, MAGIC_LINK_GRANTS_COLLECTION as cd, MAGIC_LINK_KEK_INFO_PREFIX as ce, type MagicLinkGrantPayload as cf, type MagicLinkGrantRecord as cg, NOYDB_BACKUP_VERSION as ch, NOYDB_FORMAT_VERSION as ci, NOYDB_KEYRING_VERSION as cj, NOYDB_SYNC_VERSION as ck, Noydb as cl, type NoydbBundleStore as cm, type NoydbEventMap as cn, type NoydbOptions as co, PUBLIC_ENVELOPE_FIELDS as cp, type PaperRecoveryDoc as cq, type PaperRecoveryEntry as cr, type PassphrasePolicy as cs, type PassphraseValidationResult as ct, type Permission as cu, type Permissions as cv, type PlaintextTranslatorContext as cw, type PlaintextTranslatorFn as cx, PresenceHandle as cy, type PresencePeer as cz, type DictionaryOptions as d, magicLinkGrantRecordId as d$, type SlotRewrapCeremony as d0, type SlotRewrapContext as d1, type StandardSchemaV1 as d2, type StandardSchemaV1Issue as d3, type StandardSchemaV1SyncResult as d4, type StoreAuth as d5, type StoreAuthKind as d6, type StoreCapabilities as d7, SyncEngine as d8, type SyncMetadata as d9, WeakPassphraseError as dA, type WeakPassphraseReason as dB, type WrappedDeksBlob as dC, assertStrongPassphrase as dD, buildRecipientKeyringFile as dE, burnPaperRecoveryEntry as dF, createNoydb as dG, createStore as dH, deriveMagicLinkContentKey as dI, enrollAuthenticator as dJ, estimateEntropy as dK, evaluateExportCapability as dL, evaluateImportCapability as dM, findAuthenticator as dN, hasExportCapability as dO, hasImportCapability as dP, hasRecoveryEnrolled as dQ, isMagicLinkGrantExpired as dR, isPublicEnvelope as dS, issueDelegation as dT, recoverPassphrase as dU, rotatePassphrase as dV, listMagicLinkGrants as dW, listUsers as dX, listUsersWithEnvelopes as dY, loadActiveDelegations as dZ, loadPaperRecoveryEntries as d_, type SyncPolicy as da, SyncScheduler as db, type SyncSchedulerStatus as dc, type SyncStatus as dd, type SyncTarget as de, type SyncTargetRole as df, SyncTransaction as dg, type SyncTransactionResult as dh, type TierMode as di, type TranslatorAuditEntry as dj, type TxOp as dk, USER_ENVELOPE_COLLECTION as dl, USER_ENVELOPE_MAX_BYTES as dm, type Unsubscribe as dn, type UpdateAuthenticatorOptions as dp, type UpdateUserOptions as dq, UserApi as dr, type UserEnvelopeCheckGate as ds, UserEnvelopeOversizedError as dt, type UserEnvelopePresented as du, type UserInfo as dv, type VaultBackup as dw, type VaultPolicyOnDisk as dx, type VaultSnapshot as dy, type WarningRules as dz, type I18nTextDescriptor as e, mintPaperRecoveryEntry as e0, mintWrappedDeksBlob as e1, readMagicLinkGrantRecord as e2, recoverUser as e3, removeAuthenticator as e4, resolveSchema as e5, revokeDelegation as e6, revokeMagicLinkGrant as e7, savePaperRecoveryEntries as e8, unwrapDeksFromBlob as e9, unwrapDeksFromPaperEntry as ea, unwrapMagicLinkGrant as eb, validatePassphrase as ec, validatePublicEnvelopeInput as ed, validateSchemaInput as ee, validateSchemaOutput as ef, writeMagicLinkGrant as eg, changeSecret as eh, createOwnerKeyring as ei, ensureCollectionDEK as ej, grant as ek, loadKeyring as el, persistKeyring as em, revoke as en, updateAuthenticator as eo, updateKeyringIdentity as ep, type I18nTextOptions as f, applyI18nLocale as g, dictCollectionName as h, dictKey as i, i18nText as j, isDictCollectionName as k, isDictKeyDescriptor as l, isI18nTextDescriptor as m, createEnforcer as n, validateSessionPolicy as o, BLOB_CHUNKS_COLLECTION as p, BLOB_COLLECTION as q, resolveI18nText as r, BLOB_EVICTION_AUDIT_COLLECTION as s, BLOB_INDEX_COLLECTION as t, BLOB_SLOTS_PREFIX as u, validateI18nTextValue as v, BLOB_VERSIONS_PREFIX as w, type BlobEvictionEntry as x, type BlobFieldPolicy as y, type BlobFieldsConfig as z };
+export { type ConsentAuditEntry as $, type BlobObject as A, type BlobStrategy as B, type BlobPutOptions as C, DICT_COLLECTION_PREFIX as D, type BlobResponseOptions as E, BlobSet as F, type BlobStrategyOpenArgs as G, type CompactRunOptions as H, type I18nStrategy as I, type CompactionContext as J, type CompactionResult as K, DEFAULT_CHUNK_SIZE as L, EXPORT_AUDIT_COLLECTION as M, ExportBlobsAbortedError as N, type ExportBlobsAuditEntry as O, PolicyEnforcer as P, type ExportBlobsHandle as Q, type ExportBlobsOptions as R, type SessionStrategy as S, type ExportedBlob as T, type SlotInfo as U, type SlotRecord as V, type VersionRecord as W, createExportBlobsHandle as X, runCompaction as Y, type ConsentStrategy as Z, CONSENT_AUDIT_COLLECTION as _, type DictEntry as a, VaultInstant as a$, type ConsentAuditFilter as a0, type ConsentContext as a1, type ConsentOp as a2, loadConsentEntries as a3, writeConsentEntry as a4, type PeriodsStrategy as a5, type CarryForwardContext as a6, type ClosePeriodOptions as a7, type OpenPeriodOptions as a8, PERIODS_COLLECTION as a9, type DerivationStrategyHandle as aA, type DerivedFromMeta as aB, type OutputSpec as aC, type RecordOutputSpec as aD, type MaterializedViewStrategy as aE, type MaterializedViewStrategyHandle as aF, type OverlayedViewStrategy as aG, Collection as aH, OverlayedViewRegistry as aI, type OverlayedViewStrategyHandle as aJ, type SyncStrategy as aK, type Role as aL, type UnlockedKeyring as aM, type HistoryStrategy as aN, type NoydbStore as aO, type HistoryOptions as aP, type EncryptedEnvelope as aQ, type PruneOptions as aR, type AppendInput as aS, type ChangeType as aT, CollectionInstant as aU, type DiffEntry as aV, type JsonPatch as aW, type JsonPatchOp as aX, type LedgerEntry as aY, LedgerStore as aZ, type VaultEngine as a_, type PeriodRecord as aa, type ReadOnlyCollection as ab, appendPeriodLedgerEntry as ac, assertTsWritable as ad, chainAnchor as ae, loadPeriods as af, validatePeriodName as ag, type GuardStrategy as ah, type GuardChange as ai, type GuardContext as aj, GuardRegistry as ak, type GuardStrategyHandle as al, ReadOnlyVaultFacade as am, type ShadowStrategy as an, CollectionFrame as ao, VaultFrame as ap, type TxStrategy as aq, type AmendmentTxOptions as ar, TxCollection as as, TxContext as at, TxVault as au, runTransaction as av, type DerivationStrategy as aw, type DerivationContext as ax, type ArrayOutputSpec as ay, DerivationRegistry as az, type DictKeyDescriptor as b, type FactorRequirement as b$, type VerifyResult as b0, applyPatch as b1, canonicalJson as b2, computePatch as b3, diff as b4, formatDiff as b5, hashEntry as b6, paddedIndex as b7, parseIndex as b8, sha256Hex as b9, type CollectionDescriptor as bA, type CollectionStats as bB, type Conflict as bC, type ConflictPolicy as bD, type ConflictStrategy as bE, type CrossTierAccessEvent as bF, DEFAULT_PUBLIC_ENVELOPE_SCHEMA as bG, DELEGATIONS_COLLECTION as bH, type DeepPartial as bI, type DeepPartialOrNull as bJ, type DelegationToken as bK, type DeleteManyResult as bL, type DerivationDescriptor as bM, type DirtyEntry as bN, type DumpSchemaOptions as bO, ELEVATION_AUDIT_COLLECTION as bP, ElevatedHandle as bQ, type EnrollAuthenticatorOptions as bR, type EnrollAuthenticatorWrappingDEKsOptions as bS, type EnrollAuthenticatorWrappingKEKOptions as bT, type EnrollRecoveryResult as bU, type ExportCapability as bV, type ExportChunk as bW, type ExportFormat as bX, type ExportStreamOptions as bY, type FactorKind as bZ, type FactorProofBundle as b_, type MVQueryContext as ba, type RegisteredMV as bb, MaterializedViewRegistry as bc, type MaterializedFromMeta as bd, type MaterializedViewOutput as be, type UnionSource as bf, type UserEnvelope as bg, type PublicEnvelope as bh, type GateName as bi, type GatePolicy as bj, type VaultPolicy as bk, type ActiveTier as bl, type FactorProof as bm, type PersistedSchemaEnvelope as bn, type DirectoryConfig as bo, type UserVisibility as bp, Vault as bq, type AccessibleVault as br, BUNDLE_STORE_POLICY as bs, type BuiltInGateName as bt, type BundleRecipient as bu, type CacheOptions as bv, type CacheStats as bw, type ChangeEvent as bx, type CollectionChangeEvent as by, type CollectionConflictResolver as bz, DictionaryHandle as c, type PutManyItemOptions as c$, type FieldDescriptor as c0, type FieldSource as c1, type GhostRecord as c2, type GrantOptions as c3, type HistoryConfig as c4, type HistoryEntry as c5, INDEXED_STORE_POLICY as c6, type ImportCapability as c7, type InferOutput as c8, type InternalCollectionStats as c9, type NoydbBundleStore as cA, type NoydbEventMap as cB, type NoydbOptions as cC, type OverlayViewDescriptor as cD, PUBLIC_ENVELOPE_FIELDS as cE, type PaperRecoveryDoc as cF, type PaperRecoveryEntry as cG, type PassphrasePolicy as cH, type PassphraseValidationResult as cI, type Permission as cJ, type Permissions as cK, type PersistedSchemaKind as cL, type PlaintextTranslatorContext as cM, type PlaintextTranslatorFn as cN, PresenceHandle as cO, type PresencePeer as cP, type PublicEnvelopeField as cQ, type PublicEnvelopeSchema as cR, type PublicEnvelopeText as cS, type PullMode as cT, type PullOptions as cU, type PullPolicy as cV, type PullResult as cW, type PushMode as cX, type PushOptions as cY, type PushPolicy as cZ, type PushResult as c_, type IssueDelegationOptions as ca, type IssueMagicLinkGrantOptions as cb, type KeyringAuthenticator as cc, type KeyringAuthenticatorWrappingDEKs as cd, type KeyringAuthenticatorWrappingKEK as ce, type KeyringFile as cf, type ListAccessibleVaultsOptions as cg, type ListPageResult as ch, type ListUsersOptions as ci, type LiveUserEnvelope as cj, type LocaleReadOptions as ck, Lru as cl, type LruOptions as cm, type LruStats as cn, MAGIC_LINK_CONTENT_INFO_PREFIX as co, MAGIC_LINK_GRANTS_COLLECTION as cp, MAGIC_LINK_KEK_INFO_PREFIX as cq, type MagicLinkGrantPayload as cr, type MagicLinkGrantRecord as cs, type MaterializedViewDescriptor as ct, MemorySealingKeyProvider as cu, NOYDB_BACKUP_VERSION as cv, NOYDB_FORMAT_VERSION as cw, NOYDB_KEYRING_VERSION as cx, NOYDB_SYNC_VERSION as cy, Noydb as cz, type DictionaryOptions as d, type WrappedDeksBlob as d$, type PutManyOptions as d0, type PutManyResult as d1, type QueryAcrossOptions as d2, type QueryAcrossResult as d3, type QuickUnlockState as d4, QuickUnlockStore as d5, type ReAuthOperation as d6, type RecoverPassphraseInput as d7, type RecoverPassphraseResult as d8, type RecoverUserOptions as d9, SyncScheduler as dA, type SyncSchedulerStatus as dB, type SyncStatus as dC, type SyncTarget as dD, type SyncTargetRole as dE, SyncTransaction as dF, type SyncTransactionResult as dG, type TierMode as dH, type TranslatorAuditEntry as dI, type TxOp as dJ, USER_ENVELOPE_COLLECTION as dK, USER_ENVELOPE_MAX_BYTES as dL, type Unsubscribe as dM, type UpdateAuthenticatorOptions as dN, type UpdateUserOptions as dO, UserApi as dP, type UserEnvelopeCheckGate as dQ, UserEnvelopeOversizedError as dR, type UserEnvelopePresented as dS, type UserInfo as dT, type VaultBackup as dU, type VaultPolicyOnDisk as dV, type VaultSchemaSnapshot as dW, type VaultSnapshot as dX, type WarningRules as dY, WeakPassphraseError as dZ, type WeakPassphraseReason as d_, type RecoveryProof as da, type ResolvedPublicEnvelopeSchema as db, type RevokeOptions as dc, type RotatePassphraseInput as dd, type RotateRecoveryOptions as de, type RotateRecoveryResult as df, SEALED_PASSPHRASE_RECORD_ID as dg, type SealedEnvelope as dh, type SealedPassphrase as di, type SealingKeyProvider as dj, type SessionPolicy as dk, type SetPublicEnvelopeInput as dl, type ShamirRecoveryDoc as dm, type ShamirRecoveryEntry as dn, type SlotRewrapCeremony as dp, type SlotRewrapContext as dq, type StandardSchemaV1 as dr, type StandardSchemaV1Issue as ds, type StandardSchemaV1SyncResult as dt, type StoreAuth as du, type StoreAuthKind as dv, type StoreCapabilities as dw, SyncEngine as dx, type SyncMetadata as dy, type SyncPolicy as dz, type I18nTextDescriptor as e, assertStrongPassphrase as e0, buildRecipientKeyringFile as e1, burnPaperRecoveryEntry as e2, createNoydb as e3, createStore as e4, deriveMagicLinkContentKey as e5, enrollAuthenticator as e6, estimateEntropy as e7, evaluateExportCapability as e8, evaluateImportCapability as e9, revokeMagicLinkGrant as eA, savePaperRecoveryEntries as eB, saveSealedPassphrase as eC, saveShamirRecoveryEntries as eD, unwrapDeksFromBlob as eE, unwrapDeksFromPaperEntry as eF, unwrapDeksFromShamirEntry as eG, unwrapMagicLinkGrant as eH, validatePassphrase as eI, validatePublicEnvelopeInput as eJ, validateSchemaInput as eK, validateSchemaOutput as eL, writeMagicLinkGrant as eM, changeSecret as eN, createOwnerKeyring as eO, ensureCollectionDEK as eP, grant as eQ, loadKeyring as eR, persistKeyring as eS, revoke as eT, updateAuthenticator as eU, updateKeyringIdentity as eV, findAuthenticator as ea, hasExportCapability as eb, hasImportCapability as ec, hasRecoveryEnrolled as ed, isMagicLinkGrantExpired as ee, isPublicEnvelope as ef, issueDelegation as eg, recoverPassphrase as eh, rotatePassphrase as ei, listMagicLinkGrants as ej, listUsers as ek, listUsersWithEnvelopes as el, loadActiveDelegations as em, loadPaperRecoveryEntries as en, loadSealedPassphrase as eo, loadShamirRecoveryEntries as ep, magicLinkGrantRecordId as eq, mintPaperRecoveryEntry as er, mintShamirRecoveryEntry as es, mintWrappedDeksBlob as et, parseSealedEnvelope as eu, readMagicLinkGrantRecord as ev, recoverUser as ew, removeAuthenticator as ex, resolveSchema as ey, revokeDelegation as ez, type I18nTextOptions as f, applyI18nLocale as g, dictCollectionName as h, dictKey as i, i18nText as j, isDictCollectionName as k, isDictKeyDescriptor as l, isI18nTextDescriptor as m, createEnforcer as n, validateSessionPolicy as o, BLOB_CHUNKS_COLLECTION as p, BLOB_COLLECTION as q, resolveI18nText as r, BLOB_EVICTION_AUDIT_COLLECTION as s, BLOB_INDEX_COLLECTION as t, BLOB_SLOTS_PREFIX as u, validateI18nTextValue as v, BLOB_VERSIONS_PREFIX as w, type BlobEvictionEntry as x, type BlobFieldPolicy as y, type BlobFieldsConfig as z };