@noy-db/hub 0.4.0-pre.0 → 0.4.0-pre.10

package/dist/kernel/types.d.ts

@@ -24,18 +24,18 @@
  */
 import type { StandardSchemaV1 } from './schema.js';
 import type { DeferredNumberingConfig } from '../with-commit/numbering/descriptor.js';
-import type { SyncPolicy } from './sync-policy.js';
-import type { BlobStrategy } from '../port/with/blob-strategy.js';
+import type { SyncPolicy, ReadinessState } from './sync-policy.js';
+import type { BlobsStrategy } from '../port/with/blob-strategy.js';
 import type { ArchiveStrategy } from '../with-fork/archive/index.js';
-import type { IndexStrategy } from '../with-lookup/indexing/strategy.js';
-import type { AggregateStrategy } from '../with-lookup/aggregate/strategy.js';
+import type { IndexingStrategy } from '../with-lookup/indexing/strategy.js';
+import type { ReduceStrategy } from '../with-lookup/reduce/strategy.js';
 import type { ConsentStrategy } from '../with-audit/consent/strategy.js';
 import type { PeriodsStrategy } from '../with-audit/periods/strategy.js';
 import type { ShadowStrategy } from '../with-fork/shadow/strategy.js';
-import type { TxStrategy } from '../with-commit/tx/strategy.js';
+import type { TransactionsStrategy } from '../with-commit/tx/strategy.js';
 import type { HistoryStrategy } from '../with-commit/history/strategy.js';
 import type { ForgetStrategy } from '../with-audit/forget/strategy.js';
-import type { SnapshotStrategy } from '../with-fork/snapshots/strategy.js';
+import type { SnapshotsStrategy } from '../with-fork/snapshots/strategy.js';
 import type { DerivationSkippedFrozen } from './via/dispatch.js';
 import type { AttestationStrategy } from '../with-audit/attestation/strategy.js';
 import type { ClassifiedStrategy } from '../port/with/classified-strategy.js';
@@ -51,15 +51,15 @@ import type { SearchStrategy } from '../with-lookup/search/strategy.js';
 import type { CargoStrategy } from '../with-cargo/strategy.js';
 import type { Layer, I18nStrategy } from '../port/with/i18n-strategy.js';
 import type { SessionStrategy } from '../with-party/session/strategy.js';
-import type { SyncStrategy } from '../with-party/team/sync-strategy.js';
-import type { GuardStrategyHandleAny } from '../with-audit/guards/types.js';
-import type { DerivationStrategyHandle } from '../with-formula/derivations/types.js';
+import type { SyncStrategy } from '../with-sync/strategy.js';
+import type { GuardStrategyAny } from '../with-audit/guards/types.js';
+import type { DerivationStrategy } from '../with-formula/derivations/types.js';
 import type { UnlockedKeyring } from '../with-party/team/keyring.js';
-import type { PassphrasePolicy } from './validation.js';
+import type { SecretPolicy } from './validation.js';
 import type { CoverSchema } from '../with-party/directory/cover/types.js';
-import type { MaterializedViewStrategyHandle } from '../with-formula/materialized-views/types.js';
-import type { OverlayedViewStrategyHandle } from '../with-formula/overlay-views/types.js';
-import type { SealingKeyProvider, RecipientHint } from '../with-party/team/managed-passphrase.js';
+import type { MaterializedViewStrategy } from '../with-formula/materialized-views/types.js';
+import type { OverlayedViewStrategy } from '../with-formula/overlay-views/types.js';
+import type { SealingKeyProvider, RecipientHint } from '../with-party/team/managed-secret.js';
 import type { ShamirRecoveryProvider } from '../with-party/team/shamir-recovery-provider.js';
 import type { ObjectProjection } from '../with-shape/blobs/object-projection.js';
 import type { CoordinationProvider } from '../port/by/types.js';
@@ -755,7 +755,7 @@ export type VaultPolicyOnDisk = Record<string, unknown>;
  * - `paper` — `on-recovery` codes (the standard end-to-end profile).
  * - `shamir` / `multi-channel` / `admin-mediated` — API surface ships;
  *   per-profile dispatch lands in follow-up issues. Calling
- *   `db.recoverPassphrase` against these throws
+ *   `db.recoverSecret` against these throws
  *   {@link RecoveryProfileNotImplementedError}.
  */
 export type RecoveryEnrollment = {
@@ -837,7 +837,7 @@ export interface KeyringAuthenticatorWrappingKEK extends KeyringAuthenticatorBas
  *
  * Trade-off: a slot of this kind reconstructs `UnlockedKeyring` with
  * `kek: null` after unlock. That is semantically correct for tier-2
- * (sensitive ops like `enrollAuthenticator` / `rotatePassphrase`
+ * (sensitive ops like `enrollAuthenticator` / `rotateSecret`
  * require a tier-1 unlock anyway) and matches how `@noy-db/on-pin`
  * already behaves at tier 3.
  *
@@ -877,12 +877,12 @@ export interface KeyringFile {
     readonly created_at: string;
     readonly granted_by: string;
     /**
-     * Passphrase canary — base64 AES-KW-wrapped form of a known constant
+     * Secret canary — base64 AES-KW-wrapped form of a known constant
      * 256-bit value, wrapped under the keyring's KEK.
      *
      * Optional: older keyrings load with no canary and fall back to
      * the multi-DEK corruption heuristic. Newer keyrings
-     * carry one and let `loadKeyring` distinguish wrong-passphrase
+     * carry one and let `loadKeyring` distinguish wrong-secret
      * from corruption even when ALL DEKs (including a single-DEK keyring's
      * sole DEK) are corrupted.
      *
@@ -1184,6 +1184,24 @@ export interface PullOptions {
      * to a full scan with client-side filtering.
      */
     modifiedSince?: string;
+    /**
+     * #807 — period-scoped pull (thin-client bootstrap). `{ current: true }`
+     * pulls only records at-or-after the latest closed period's boundary;
+     * an array of closed-period names backfills exactly those periods'
+     * windows. Membership is by envelope write-time `_ts` (the freeze/
+     * archive store-tier law — the engine never sees business dates).
+     *
+     * Never filtered regardless of this option: the `_periods` summaries +
+     * companions (always pulled first — the navigation index), delete
+     * markers/tombstones (the #589/#590 convergence law), and reserved
+     * lookup collections. Composes with `collections` as an intersection.
+     * Requires the periods service (`periodsStrategy: withPeriods()`) to
+     * resolve windows once the vault holds `_periods` records. Push is
+     * never period-filtered.
+     */
+    periods?: string[] | {
+        current: true;
+    };
 }
 export interface PushResult {
     readonly pushed: number;
@@ -1198,6 +1216,23 @@ export interface PullResult {
     readonly errors: Error[];
     /** #590: tombstone enforcements applied during this run (never resolver-visible). */
     readonly erasures?: ErasureEnforcement[];
+    /**
+     * #807: present on period-scoped pulls only — per-phase KPI counters
+     * (`summaries` = the `_periods` navigation index + companions; `records`
+     * = everything after it). `records`/`bytes` count envelopes applied to
+     * the local store; `bytes` approximates ciphertext payload size
+     * (`_data` + `_iv` length), for bounding a first sync's download budget.
+     */
+    readonly phases?: {
+        readonly summaries: {
+            readonly records: number;
+            readonly bytes: number;
+        };
+        readonly records: {
+            readonly records: number;
+            readonly bytes: number;
+        };
+    };
 }
 /** Result of a sync transaction commit. */
 export interface SyncTransactionResult {
@@ -1212,6 +1247,18 @@ export interface SyncStatus {
     readonly lastPush: string | null;
     readonly lastPull: string | null;
     readonly online: boolean;
+    /**
+     * Per-collection readiness under a `'phased'` pull policy (#809). **Absent**
+     * for every other policy, and a collection the sequence never names is absent
+     * from the map — `undefined` means *"no claim made"*, never a reason to gate
+     * a UI. Only `'live'` asserts that a miss from `get()` is a real absence.
+     */
+    readonly readiness?: ReadonlyMap<string, ReadinessState>;
+    /** 1-based position in the phased sequence; `null` once it has drained. */
+    readonly phase?: {
+        readonly index: number;
+        readonly total: number;
+    } | null;
 }
 export type SyncTargetRole = 'sync-peer' | 'backup' | 'archive';
 /**
@@ -1228,7 +1275,11 @@ export interface SyncTarget {
     readonly store: NoydbStore;
     /** Role determines sync direction and conflict handling. */
     readonly role: SyncTargetRole;
-    /** Per-target sync policy. Inherits store-category default when absent. */
+    /**
+     * Per-target sync policy. Inherits the store-category default when absent —
+     * but only a *declared* policy starts automation (#897), so a target with no
+     * `policy` and no instance-level `syncPolicy` syncs on explicit calls only.
+     */
     readonly policy?: SyncPolicy;
     /** Human-readable label for DevTools and audit logs. */
     readonly label?: string;
@@ -1360,7 +1411,7 @@ export interface GrantOptions {
     readonly userId: string;
     readonly displayName: string;
     readonly role: Role;
-    readonly passphrase: string;
+    readonly secret: string;
     readonly permissions?: Permissions;
     /**
      * Optional `@noy-db/as-*` export capability. Omit or
@@ -1377,9 +1428,9 @@ export interface GrantOptions {
     /**
      * Skip phrase-format strength validation (issue #7). Defaults to
      * false — `grant()` rejects phrases that don't meet the configured
-     * `PassphrasePolicy`. Test fixtures and CLI scripts pass `true`.
+     * `SecretPolicy`. Test fixtures and CLI scripts pass `true`.
      */
-    readonly allowWeakPassphrase?: boolean;
+    readonly allowWeakSecret?: boolean;
     /**
      * Initial user-envelope payload for the new principal. Sealed under
      * the same vault DEK (the reserved `_users` collection's DEK) and
@@ -1577,7 +1628,7 @@ export interface SessionPolicy {
     readonly absoluteTimeoutMs?: number;
     /**
      * Operations that require the user to re-authenticate (re-enter their
-     * passphrase or perform a fresh WebAuthn assertion) before proceeding,
+     * secret or perform a fresh WebAuthn assertion) before proceeding,
      * even if the session is still alive.
      *
      * Common pattern: `requireReAuthFor: ['export', 'grant']` — allow
@@ -1977,6 +2028,26 @@ export interface SlotRecord {
 export interface SlotInfo extends SlotRecord {
     /** The slot name (key in the record's slot map). */
     readonly name: string;
+    /**
+     * DEVICE-LOCAL (#808): slot is pinned for offline on THIS device. Read from
+     * the `withBlobs()` pin registry at list time — never stored in (or synced
+     * through) the vault store; present only when `true`. Pinned slots are
+     * exempt from `vault.compact()` eviction and the cache-budget pass.
+     */
+    readonly pinned?: boolean;
+    /**
+     * DEVICE-LOCAL (#808): ISO timestamp of the last local read of this slot on
+     * this device — the LRU input for `vault.compact({ cacheBudget })`. Absent
+     * when the slot was never read here (the budget pass falls back to
+     * `uploadedAt`).
+     */
+    readonly lastAccessAt?: string;
+    /**
+     * DEVICE-LOCAL (#808): byte size of the local encrypted side-cache copy of
+     * an `external` slot on this device (see `BlobPinEntry.cipher`). Absent for
+     * internal slots and for external slots with no local copy.
+     */
+    readonly cachedBytes?: number;
 }
 /**
  * Explicitly published version snapshot — an independent reference to a
@@ -2044,6 +2115,12 @@ export type StoreCredentials = {
     readonly kind: 'token';
     readonly token: string;
     readonly expiresAt?: string;
+} | {
+    readonly kind: 'password';
+    readonly username: string;
+    readonly password: string;
+    readonly domain?: string;
+    readonly expiresAt?: string;
 };
 /** Refresh hook a store calls when it has no credentials or they are near expiry. */
 export type StoreCredentialSource = () => Promise<StoreCredentials>;
@@ -2112,12 +2189,12 @@ export interface NoydbOptions {
      * from `@noy-db/hub/blobs` to enable `collection.blob(id)` storage.
      * When omitted, hub's blob machinery stays out of the bundle (ESM
      * tree-shaking) and `collection.blob(id)` throws with a pointer at
-     * the subpath. `BlobStrategy` is `@internal` — users only construct
+     * the subpath. `BlobsStrategy` is `@internal` — users only construct
      * it via the subpath factory.
      *
      * @internal
      */
-    readonly blobStrategy?: BlobStrategy;
+    readonly blobsStrategy?: BlobsStrategy;
     /**
      * Cold-storage archival target. `withArchive({ store })` designates a
      * second store that holds archived record envelopes. Enables
@@ -2131,24 +2208,24 @@ export interface NoydbOptions {
      * and auto-reconcile. When omitted, indexing code never reaches the
      * bundle; `.lazyQuery()` throws with a pointer at the subpath, and
      * eager-mode collections fall back to linear scans regardless of
-     * `indexes: [...]` declarations. `IndexStrategy` is `@internal` —
+     * `indexes: [...]` declarations. `IndexingStrategy` is `@internal` —
      * users only construct it via the subpath factory.
      *
      * @internal
      */
-    readonly indexStrategy?: IndexStrategy;
+    readonly indexingStrategy?: IndexingStrategy;
     /**
      * tree-shake seam — optional aggregate strategy. Pass
-     * `withAggregate()` from `@noy-db/hub/aggregate` to enable
+     * `withReduce()` from `@noy-db/hub/reduce` to enable
      * `.aggregate()` and `.groupBy()` on Query. When omitted, those
      * methods throw with a pointer at the subpath; the ~886 LOC of
-     * Aggregation + GroupedQuery machinery never reaches the bundle.
+     * Reduction + GroupedQuery machinery never reaches the bundle.
      * Streaming `scan().aggregate()` works independently of this
-     * strategy — it doesn't use the `Aggregation` class.
+     * strategy — it doesn't use the `Reduction` class.
      *
      * @internal
      */
-    readonly aggregateStrategy?: AggregateStrategy;
+    readonly reduceStrategy?: ReduceStrategy;
     /**
      * tree-shake seam — optional CRDT strategy. Required when
      * any collection is declared with `crdt: 'lww-map' | 'rga' | 'yjs'`;
@@ -2201,12 +2278,12 @@ export interface NoydbOptions {
     readonly shadowStrategy?: ShadowStrategy;
     /**
      * tree-shake seam — optional multi-record transactions. Pass
-     * `withTransactions()` from `@noy-db/hub/tx` to enable
+     * `withTransactions()` from `@noy-db/hub/transactions` to enable
      * `db.transaction(fn)`. Without it, calling the method throws.
      *
      * @internal
      */
-    readonly txStrategy?: TxStrategy;
+    readonly transactionsStrategy?: TransactionsStrategy;
     /**
      * tree-shake seam — optional history + ledger + time-machine.
      * Pass `withHistory()` from `@noy-db/hub/history` to enable
@@ -2221,7 +2298,7 @@ export interface NoydbOptions {
      */
     readonly historyStrategy?: HistoryStrategy;
     /**
-     * GDPR right-to-erasure. Pass `withForgetCascade({ subjects })`
+     * GDPR right-to-erasure. Pass `withForget({ subjects })`
      * from `@noy-db/hub/forget` to declare which collections carry erasable
      * subject data and the record field naming the data subject. Enables
      * `vault.forget(subjectId)` crypto-shred (rewrite-to-tombstone of the live
@@ -2276,7 +2353,7 @@ export interface NoydbOptions {
      * `db.snapshot()`, `db.listSnapshots()`, and `db.restoreSnapshot()`.
      * When omitted, all three methods throw with a pointer at the subpath.
      */
-    readonly snapshotStrategy?: SnapshotStrategy;
+    readonly snapshotsStrategy?: SnapshotsStrategy;
     /**
      * Tree-shake seam — optional attestation capability. Pass
      * `withAttestation()` from `@noy-db/hub/attestation` to enable
@@ -2339,7 +2416,7 @@ export interface NoydbOptions {
      * throw `TeamNotEnabledError` and the keyring grant/revoke/rotate engines
      * are reached only via opt-in — the always-on floor is single-user.
      * Single-user primitives (owner keyring, unlock, `listUsers`,
-     * `updateUser`, passphrase rotate/recover) stay ungated, as does the
+     * `updateUser`, secret rotate/recover) stay ungated, as does the
      * `createDeedOwner` free function (no createNoydb instance to gate
      * against).
      */
@@ -2388,7 +2465,7 @@ export interface NoydbOptions {
      * Multiple guards per collection are allowed; they are dispatched
      * in registration order on `collection.put()`.
      */
-    readonly guardStrategies?: ReadonlyArray<GuardStrategyHandleAny>;
+    readonly guardStrategies?: ReadonlyArray<GuardStrategyAny>;
     /**
      * Deferred-numbering series declared via `withDeferredNumbering(...)`.
      * `vault.sequence(series).next({ for })` then assigns gap-free serials at a
@@ -2402,7 +2479,7 @@ export interface NoydbOptions {
      * validates the derivation graph for cycles on `openVault`; a cyclic
      * graph throws `DerivationCycleError`.
      */
-    readonly derivationStrategies?: ReadonlyArray<DerivationStrategyHandle>;
+    readonly derivationStrategies?: ReadonlyArray<DerivationStrategy>;
     /**
      * Optional materialized-view strategies.
      * Each handle returned by `withMaterializedView()` from
@@ -2410,7 +2487,7 @@ export interface NoydbOptions {
      * detection across the MV + derivation graphs at `openVault`; a
      * cyclic graph throws `MaterializedViewCycleError`.
      */
-    readonly materializedViewStrategies?: ReadonlyArray<MaterializedViewStrategyHandle>;
+    readonly materializedViewStrategies?: ReadonlyArray<MaterializedViewStrategy>;
     /**
      * Optional overlay strategies. Each handle returned by
      * `withOverlayedView()` from `@noy-db/hub/overlay-views`. The vault
@@ -2418,17 +2495,17 @@ export interface NoydbOptions {
      * availability at `openVault`; a clash throws one of the
      * `Overlay*Error` family.
      */
-    readonly overlayedViewStrategies?: ReadonlyArray<OverlayedViewStrategyHandle>;
+    readonly overlayedViewStrategies?: ReadonlyArray<OverlayedViewStrategy>;
     /** Optional remote store(s) for sync. Accepts a single store, a SyncTarget, or an array. */
     readonly sync?: NoydbStore | SyncTarget | SyncTarget[];
     /** User identifier. */
     readonly user: string;
-    /** Passphrase for key derivation. Required unless encrypt is false or `getKeyring` is provided. */
+    /** Secret for key derivation. Required unless encrypt is false or `getKeyring` is provided. */
     readonly secret?: string;
     /**
      * Optional callback that returns an unlocked keyring for a given vault.
      * Use this to plug in WebAuthn / OIDC / Shamir / any unlock path that
-     * produces an `UnlockedKeyring` outside the passphrase model.
+     * produces an `UnlockedKeyring` outside the secret model.
      *
      * When set, `secret` MUST NOT also be set — `createNoydb` throws if both
      * are supplied. When neither is set (and `encrypt !== false`), `createNoydb`
@@ -2456,32 +2533,32 @@ export interface NoydbOptions {
      * ```
      *
      * Note: this callback is responsible for both the "open existing vault"
-     * and the "create new vault" cases. Unlike the passphrase path, there is
+     * and the "create new vault" cases. Unlike the secret path, there is
      * no automatic `NoAccessError` → `createOwnerKeyring` fallback, because
      * the callback owner has the UI context to decide which path to run.
-     * For first-time bootstrap, use a passphrase or recovery code, enroll
+     * For first-time bootstrap, use a secret or recovery code, enroll
      * WebAuthn from the unlocked keyring, then swap to `getKeyring` on
      * subsequent sessions.
      */
     readonly getKeyring?: (vault: string) => Promise<UnlockedKeyring>;
     /**
-     * Passphrase mode. Default `'standard'`.
+     * Secret mode. Default `'standard'`.
      *
      *   - `'standard'` — the legacy flow. `secret` supplies the
-     *     plaintext passphrase, the user knows it, and the policy gate
-     *     `rotate-passphrase` is enabled.
+     *     plaintext secret, the user knows it, and the policy gate
+     *     `rotate-secret` is enabled.
      *   - `'managed'` — rubber-hose-resistant mode. Hub generates a
-     *     256-bit random passphrase at first open and seals it under
+     *     256-bit random secret at first open and seals it under
      *     the provided `sealingKey`. The user never sees or types the
-     *     passphrase, defeating the $5-wrench attack. Mutually
+     *     secret, defeating the $5-wrench attack. Mutually
      *     exclusive with `secret` and `getKeyring`.
      *
-     * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/session-tiers.md → Managed-passphrase mode
+     * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/session-tiers.md → Managed-secret mode
      */
-    readonly passphraseMode?: 'standard' | 'managed';
+    readonly secretMode?: 'standard' | 'managed';
     /**
      * Provider that seals/unseals the auto-generated managed-mode
-     * passphrase. Required when `passphraseMode === 'managed'`; ignored
+     * secret. Required when `secretMode === '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`, …).
@@ -2490,8 +2567,6 @@ export interface NoydbOptions {
     /** Required to use `profile: 'shamir'` recovery. Pass
      *  `shamirRecoveryProvider()` from `@noy-db/on-shamir`. */
     readonly shamirRecovery?: ShamirRecoveryProvider;
-    /** Auth method. Default: 'passphrase'. */
-    readonly auth?: 'passphrase' | 'biometric';
     /** Enable encryption. Default: true. */
     readonly encrypt?: boolean;
     /**
@@ -2518,15 +2593,6 @@ export interface NoydbOptions {
      * bundle → `debounce 30s`.
      */
     readonly syncPolicy?: SyncPolicy;
-    /**
-     * @deprecated Use `syncPolicy` instead. Kept for backward compatibility.
-     * When both are supplied, `syncPolicy` takes precedence.
-     */
-    readonly autoSync?: boolean;
-    /**
-     * @deprecated Use `syncPolicy` instead. Kept for backward compatibility.
-     */
-    readonly syncInterval?: number;
     /**
      * Session timeout in ms. Clears keys after inactivity. Default: none.
      * @deprecated Use `sessionPolicy.idleTimeoutMs` instead. This field is
@@ -2541,17 +2607,17 @@ export interface NoydbOptions {
      */
     readonly sessionPolicy?: SessionPolicy;
     /**
-     * Validate passphrase strength against the phrase format
+     * Validate secret strength against the phrase format
      * on first-time keyring creation. When
-     * `true`, weak phrases throw {@link WeakPassphraseError} from
-     * `createNoydb()` / `db.rotatePassphrase()`. Default: `false` for
+     * `true`, weak phrases throw {@link WeakSecretError} from
+     * `createNoydb()` / `db.team.rotateSecret()`. Default: `false` for
      * back-compat; planned to flip to `true` in a future major release.
      */
-    readonly validatePassphrase?: boolean;
+    readonly validateSecret?: boolean;
     /**
      * Vault-level policy gate document. When present, the hub
      * persists the merged policy at `_meta/policy` on first-time vault
-     * creation and gates sensitive operations (`db.rotatePassphrase`,
+     * creation and gates sensitive operations (`db.rotateSecret`,
      * `db.export*`, …) against it. Omitted ⇒ the engine uses
      * {@link PERSONAL_POLICY}. Use {@link STRICT_POLICY} for regulated
      * deployments.
@@ -2566,11 +2632,11 @@ export interface NoydbOptions {
     readonly policy?: VaultPolicy;
     /**
      * Mandatory recovery profile enrollment. Vaults with
-     * `recover-passphrase` enabled MUST register at least one profile
+     * `recover-secret` enabled MUST register at least one profile
      * before being production-ready, otherwise `createNoydb()` throws
      * {@link RecoveryNotEnrolledError}. Set
-     * `policy.gates['recover-passphrase'].enabled = false` to
-     * deliberately opt out of recovery (passphrase loss = data loss).
+     * `policy.gates['recover-secret'].enabled = false` to
+     * deliberately opt out of recovery (secret loss = data loss).
      *
      * The `'paper'` profile is supported end-to-end. Other
      * profiles ship the API shape and throw
@@ -2597,7 +2663,7 @@ export interface NoydbOptions {
      *   data records but not the keyring row, or a WebAuthn credential was rotated).
      *   **All previously encrypted data is unrecoverable after a reset.**
      *
-     * Only applies to the passphrase (`secret`) path. When `getKeyring` is used,
+     * Only applies to the secret (`secret`) path. When `getKeyring` is used,
      * the callback is responsible for handling stale-keyring detection itself.
      */
     readonly onInvalidKey?: 'error' | 'reset';
@@ -2609,12 +2675,6 @@ export interface NoydbOptions {
      * without this option carry no cover, full stop.
      */
     readonly cover?: true | CoverSchema;
-    /**
-     * @deprecated Use {@link NoydbOptions.cover} (#799 rename). Still
-     * accepted for one pre-release window; when both keys are set,
-     * `cover` wins.
-     */
-    readonly publicEnvelope?: true | CoverSchema;
     /** Audit history configuration. */
     readonly history?: HistoryConfig;
     /**
@@ -2993,7 +3053,7 @@ export interface WarningRules {
 }
 /**
  * Policy applied to one named gate. `enabled: false` disables the
- * action entirely (useful in managed-passphrase mode where rotation is
+ * action entirely (useful in managed-secret mode where rotation is
  * impossible by construction).
  */
 export interface GatePolicy {
@@ -3009,11 +3069,11 @@ export interface GatePolicy {
  * and use the same engine; the engine treats unknown names with no
  * configured policy as "no gate" (no-op).
  */
-export type BuiltInGateName = 'rotate-passphrase' | 'recover-passphrase' | 'enroll-authenticator' | 'remove-authenticator'
+export type BuiltInGateName = 'rotate-secret' | 'recover-secret' | 'enroll-authenticator' | 'remove-authenticator'
 /**
  * Authorize a deliberate paper-recovery-code regeneration —
- * `db.rotateRecovery`. Symmetric to `rotate-passphrase` for
- * the case where the user remembers their passphrase but wants a
+ * `db.rotateRecovery`. Symmetric to `rotate-secret` for
+ * the case where the user remembers their secret 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
@@ -3036,7 +3096,7 @@ export type BuiltInGateName = 'rotate-passphrase' | 'recover-passphrase' | 'enro
 /**
  * Authorize an atomic peer-recovery — `db.recoverUser`.
  * Distinct from `revoke-user` because peer-recovery is intentional
- * re-issuance of someone's keyring under a temp passphrase, NOT
+ * re-issuance of someone's keyring under a temp secret, NOT
  * removal. Allows owner→owner natively (matches the threat model:
  * a co-owner explicitly recovering another co-owner). Ships with a
  * factor-proof default in `STRICT_POLICY` so the issuer must
@@ -3095,12 +3155,12 @@ export type BuiltInGateName = 'rotate-passphrase' | 'recover-passphrase' | 'enro
 export type GateName = BuiltInGateName | `app:${string}`;
 /**
  * Top-level policy object. Persisted at `_meta/policy` once at vault
- * creation. The `passphrase` block configures the strength rules
- * applied at every passphrase ingress; `gates` configures
+ * creation. The `secret` block configures the strength rules
+ * applied at every secret ingress; `gates` configures
  * the action-level requirements.
  */
 export interface VaultPolicy {
-    readonly passphrase?: PassphrasePolicy;
+    readonly secret?: SecretPolicy;
     readonly gates: Partial<Record<GateName, GatePolicy>>;
 }
 /** Concrete proof an actor presents to {@link checkGate}. */
@@ -3116,7 +3176,7 @@ export interface FactorProof {
  * Noydb method. Used as the optional last parameter of every method
  * that runs through `checkGate`: `db.grant`, `db.revoke`, `db.updateUser`,
  * `db.enrollAuthenticator`, `db.removeAuthenticator`, `db.updateAuthenticator`,
- * `db.enrollWebAuthn`, `db.rotatePassphrase`, `db.recoverPassphrase`,
+ * `db.enrollWebAuthn`, `db.rotateSecret`, `db.recoverSecret`,
  * `db.recoverUser`, `db.enrollUnlock`, `db.describeUserAuth`,
  * `db.describeAllUsersAuth`.
  *
@@ -3242,4 +3302,45 @@ export interface NoydbPolicyDeps {
  * synchronously — mirrors {@link UserApiFactory}.
  */
 export type NoydbPolicyFactory = (deps: NoydbPolicyDeps) => NoydbPolicyApi;
+/**
+ * Named field-set declarations for a collection's type-level shape (#839).
+ *
+ * Replaces the positional `Collection<T, S, Q, M>` tail at every surface a
+ * consumer touches. The positional form was unreadable and unsafe: `Q` and `M`
+ * are both `keyof T & string`, so swapping them type-checked silently, and
+ * reaching `M` meant writing placeholders —
+ * `collection<Sale, never, never, 'amount' | 'tax'>`.
+ *
+ * ```ts
+ * vault.collection<Sale, { money: 'amount' | 'tax' }>('sales')
+ * vault.collection<Invoice, { sensitive: 'ssn'; indexed: 'clientId' }>('invoices')
+ * ```
+ *
+ * Every member is optional; omitting one keeps that axis permissive, which is
+ * what the `[X] extends [never]` guards in {@link QueryField} /
+ * {@link IndexFieldName} encode. Those guards are NOT removable — they are the
+ * difference between "no indexes declared, so `where()` accepts any field" and
+ * "indexes declared, so `where()` is restricted to them" — so they are
+ * re-expressed against this shape rather than dropped.
+ */
+export interface CollectionShape<T> {
+    /** Fields sealed at rest; reads return {@link Sealed} handles. */
+    readonly sensitive?: keyof T & string;
+    /** Fields carrying a declared secondary index; narrows `where()` / `orderBy()`. */
+    readonly indexed?: keyof T & string;
+    /** Fields carrying a money descriptor. */
+    readonly money?: keyof T & string;
+}
+/** The `sensitive` field set of a {@link CollectionShape}, or `never` if unset. */
+export type SensitiveOf<T, O> = O extends {
+    sensitive: infer S;
+} ? (S & keyof T & string) : never;
+/** The `indexed` field set of a {@link CollectionShape}, or `never` if unset. */
+export type IndexedOf<T, O> = O extends {
+    indexed: infer Q;
+} ? (Q & keyof T & string) : never;
+/** The `money` field set of a {@link CollectionShape}, or `never` if unset. */
+export type MoneyOf<T, O> = O extends {
+    money: infer M;
+} ? (M & keyof T & string) : never;
 export {};