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

package/dist/with-party/team/peer-recover.d.ts

@@ -22,7 +22,7 @@
  *      gate `peer-recover-user` carries the freshness requirement.
  *   5. **Tier-2 slots dropped.** The slots wrap the OLD KEK under
  *      method-derived keys; after recovery the KEK is re-derived
- *      from the new temp passphrase. Match `rotatePassphrase`'s
+ *      from the new temp secret. Match `rotateSecret`'s
  *      precedent — the recovered user re-enrols slots after picking
  *      their own phrase.
  *
@@ -34,47 +34,47 @@
  * @module
  */
 import type { NoydbStore, Role } from '../../kernel/types.js';
-import { type PassphrasePolicy } from '../../kernel/validation.js';
+import { type SecretPolicy } from '../../kernel/validation.js';
 import type { UnlockedKeyring } from './keyring.js';
 /** Input shape for {@link recoverUser}. */
 export 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
+     * Temporary secret under which the new keyring is wrapped.
+     * The recipient should call `db.rotateSecret` immediately on
      * acceptance to choose their own phrase — this temp acts as a
      * single-use bridge in invite / peer-recovery flows.
      */
-    readonly passphrase: string;
+    readonly secret: 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;
+    readonly validateSecret?: boolean;
     /**
-     * Skip phrase strength validation even when `validatePassphrase` is
+     * Skip phrase strength validation even when `validateSecret` 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;
+    readonly allowWeakSecret?: boolean;
     /**
      * Optional explicit phrase policy override (passed through to
-     * `assertStrongPassphrase`). Mirrors how `grant` accepts a custom
-     * `PassphrasePolicy` for app-specific tightening.
+     * `assertStrongSecret`). Mirrors how `grant` accepts a custom
+     * `SecretPolicy` for app-specific tightening.
      */
-    readonly passphrasePolicy?: PassphrasePolicy;
+    readonly secretPolicy?: SecretPolicy;
 }
 /**
  * Atomically rewrap the target user's keyring under a fresh temp
- * passphrase. Single store write; no revoke step; no key rotation.
+ * secret. 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
+ *   - Communicate the temp secret to the recipient via a secure
  *     channel (URL fragment, in-person, etc.) — the hub does not
  *     transport secrets.
  */

package/dist/with-party/team/recovery.d.ts

@@ -34,7 +34,7 @@ import type { ShamirRecoveryProvider } from './shamir-recovery-provider.js';
  * 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.
+ * secret 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
@@ -67,8 +67,8 @@ export declare function hasRecoveryEnrolled(store: NoydbStore, vault: string): P
 /**
  * Whether at least one **strong** recovery profile is enrolled.
  *
- * "Strong" excludes paper-alone — under managed-passphrase mode the
- * user has no memorized passphrase, so a stolen/lost paper sheet
+ * "Strong" excludes paper-alone — under managed-secret mode the
+ * user has no memorized secret, so a stolen/lost paper sheet
  * would be a single point of total loss. Strong profiles today:
  *
  *   - `shamir` (k-of-n threshold; survives loss of up to n-k shares)
@@ -167,7 +167,7 @@ export declare function unwrapDeksFromShamirEntry(provider: ShamirRecoveryProvid
  *
  * 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.
+ * DEK set, then mints a fresh KEK from the user's new secret.
  *
  * Thin wrapper over {@link mintWrappedDeksBlob} — the crypto
  * lives in the shared primitive; this function just adds paper-
@@ -182,7 +182,7 @@ export declare function unwrapDeksFromShamirEntry(provider: ShamirRecoveryProvid
 export declare function mintPaperRecoveryEntry(deks: Map<string, EnclaveKey>, 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.
+ * `recoverSecret` flow after the user's code has been parsed.
  *
  * Thin wrapper over {@link unwrapDeksFromBlob}.
  *

package/dist/with-party/team/rotate-recover.d.ts

@@ -1,12 +1,12 @@
 /**
- * Tier-1 change flows — `rotatePassphrase` (user remembers old) and
- * `recoverPassphrase` (user supplies a recovery proof).
+ * Tier-1 change flows — `rotateSecret` (user remembers old) and
+ * `recoverSecret` (user supplies a recovery proof).
  *
  * The two flows share the post-verification half — fresh salt, fresh
  * KEK, rewrap every DEK — and differ only in how they re-derive the
  * old KEK:
  *
- * - **Rotate**: derive from the supplied `oldPassphrase`.
+ * - **Rotate**: derive from the supplied `oldSecret`.
  * - **Recover (paper)**: unwrap from a `RecoveryCodeEntry` using a
  *   user-supplied recovery code. The entry is burned on success.
  *
@@ -20,12 +20,12 @@ import type { NoydbStore } from '../../kernel/types.js';
 import { type EnclaveKey } from '../../kernel/enclave/index.js';
 import { type PaperRecoveryEntry } from './recovery.js';
 import type { ShamirRecoveryProvider } from './shamir-recovery-provider.js';
-import { type PassphrasePolicy } from '../../kernel/validation.js';
+import { type SecretPolicy } from '../../kernel/validation.js';
 import type { UnlockedKeyring } from './keyring.js';
 import type { KeyringAuthenticator } from '../../kernel/types.js';
 import type { EnrollAuthenticatorOptions } from './authenticators.js';
 /**
- * Context handed to a {@link SlotRewrapCeremony} when `rotatePassphrase`
+ * Context handed to a {@link SlotRewrapCeremony} when `rotateSecret`
  * preserves a tier-2 slot. The ceremony's job is to re-derive its
  * method-specific wrapping material (PRF assertion, PBKDF2 of the
  * password, etc.) and wrap the freshly rewrapped DEK set under
@@ -57,25 +57,25 @@ export interface SlotRewrapContext {
     readonly oldSlot: KeyringAuthenticator;
 }
 /**
- * Callback that re-enrolls one tier-2 slot during `rotatePassphrase`.
+ * Callback that re-enrolls one tier-2 slot during `rotateSecret`.
  * Returns the new slot's `EnrollAuthenticatorOptions` — same shape
  * the consumer would pass to `db.enrollAuthenticator` for a fresh
  * enrollment. Hub persists the result atomically with the rotation.
  */
 export type SlotRewrapCeremony = (ctx: SlotRewrapContext) => Promise<EnrollAuthenticatorOptions>;
-/** Caller payload for {@link rotatePassphrase}. */
-export interface RotatePassphraseInput {
-    readonly oldPassphrase: string;
-    readonly newPassphrase: string;
-    readonly passphrasePolicy?: PassphrasePolicy;
-    readonly allowWeakPassphrase?: boolean;
+/** Caller payload for {@link rotateSecret}. */
+export interface RotateSecretInput {
+    readonly oldSecret: string;
+    readonly newSecret: string;
+    readonly secretPolicy?: SecretPolicy;
+    readonly allowWeakSecret?: boolean;
     /**
      * Map of slot id → re-enrolment ceremony. Slots whose id appears
      * here are PRESERVED across rotation (the ceremony re-derives the
      * method-specific wrapping under the new keyring); slots whose id
      * is absent are DROPPED (the pre-slot-ceremony behavior).
      *
-     * Without this map, `rotatePassphrase` wipes every tier-2 slot. Consumers building a
+     * Without this map, `rotateSecret` wipes every tier-2 slot. Consumers building a
      * "rotate without losing my biometric" flow supply ceremonies for
      * each slot they want to keep.
      *
@@ -90,8 +90,8 @@ export interface RotatePassphraseInput {
     };
 }
 /**
- * Re-derive the user's KEK from `oldPassphrase`, rewrap every DEK
- * under a freshly-derived KEK from `newPassphrase`, and persist.
+ * Re-derive the user's KEK from `oldSecret`, rewrap every DEK
+ * under a freshly-derived KEK from `newSecret`, and persist.
  *
  * Tier-2 authenticator slots are dropped UNLESS the caller supplies
  * a `slotCeremonies` map — each ceremony re-derives its
@@ -99,14 +99,14 @@ export interface RotatePassphraseInput {
  * the rewrapped slots atomically with the rotation. Slots whose id
  * isn't in the map are still dropped.
  *
- * @throws `InvalidKeyError` if `oldPassphrase` does not unwrap the keyring.
- * @throws `WeakPassphraseError` if `newPassphrase` fails the strength rule.
+ * @throws `InvalidKeyError` if `oldSecret` does not unwrap the keyring.
+ * @throws `WeakSecretError` if `newSecret` fails the strength rule.
  * @throws `ValidationError` if a ceremony's result mismatches the
  *         slot's id or method (anti-slot-swap guard).
  */
-export declare function rotatePassphrase(store: NoydbStore, vault: string, userId: string, input: RotatePassphraseInput): Promise<UnlockedKeyring>;
+export declare function rotateSecret(store: NoydbStore, vault: string, userId: string, input: RotateSecretInput): Promise<UnlockedKeyring>;
 /**
- * Caller payload for {@link recoverPassphrase}.
+ * Caller payload for {@link recoverSecret}.
  *
  * `paper` and `shamir` are wired end-to-end.
  * The remaining two profiles (`multi-channel`, `admin-mediated`)
@@ -129,11 +129,11 @@ export type RecoveryProof = {
         readonly shares: ReadonlyArray<string>;
     };
 };
-export interface RecoverPassphraseInput {
-    readonly newPassphrase: string;
+export interface RecoverSecretInput {
+    readonly newSecret: string;
     readonly recoveryProof: RecoveryProof;
-    readonly passphrasePolicy?: PassphrasePolicy;
-    readonly allowWeakPassphrase?: boolean;
+    readonly secretPolicy?: SecretPolicy;
+    readonly allowWeakSecret?: boolean;
     /**
      * After a successful paper-recovery, replace ALL remaining recovery
      * entries with freshly-minted ones. Defaults to `true` (defensive).
@@ -177,27 +177,27 @@ export interface RecoverPassphraseInput {
     readonly codeGenerator?: () => string;
 }
 /**
- * Return shape of `db.recoverPassphrase`. `newCodes` is populated when
+ * Return shape of `db.recoverSecret`. `newCodes` is populated when
  * `rotateRemainingCodes` was enabled and at least one entry was
  * rotated; an empty array means no rotation happened (rotation
  * disabled, or no remaining codes after burn). Show the codes to the
  * user once — they are the canonical credential for future recovery
  * and CANNOT be retrieved again.
  */
-export interface RecoverPassphraseResult {
+export interface RecoverSecretResult {
     readonly newCodes: readonly string[];
 }
 /**
  * Input for {@link Noydb.rotateRecovery} — deliberate
  * recovery-credential regeneration when the user knows their
- * passphrase but wants a fresh sheet (paper) or fresh shares
- * (shamir). Symmetric to {@link RotatePassphraseInput}.
+ * secret but wants a fresh sheet (paper) or fresh shares
+ * (shamir). Symmetric to {@link RotateSecretInput}.
  */
 export 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}. */
+    /** Optional code generator — see {@link RecoverSecretInput.codeGenerator}. */
     readonly codeGenerator?: () => string;
 } | {
     readonly profile: 'shamir';
@@ -265,11 +265,11 @@ export type RecoveryEnrollmentInput = {
     readonly entryId?: string;
 };
 /**
- * Reset the user's passphrase using a recovery proof.
+ * Reset the user's secret using a recovery proof.
  * Supports `'paper'` and `'shamir'` profiles. The other profiles throw
  * {@link RecoveryProfileNotImplementedError}.
  *
  * On success, the used recovery entry is burned (deleted from the
  * stored set).
  */
-export declare function recoverPassphrase(provider: ShamirRecoveryProvider | undefined, store: NoydbStore, vault: string, userId: string, input: RecoverPassphraseInput): Promise<UnlockedKeyring>;
+export declare function recoverSecret(provider: ShamirRecoveryProvider | undefined, store: NoydbStore, vault: string, userId: string, input: RecoverSecretInput): Promise<UnlockedKeyring>;

package/dist/with-pod/bundle.d.ts

@@ -26,8 +26,8 @@
  * **Why split read/load?** `readPod` returns the
  * *unwrapped JSON string*, not a Vault object. The caller
  * is responsible for piping that JSON into
- * `vault.load(json, passphrase)`. Splitting the layers
- * keeps the bundle module free of any crypto/passphrase
+ * `vault.load(json, secret)`. Splitting the layers
+ * keeps the bundle module free of any crypto/secret
  * concerns — it's purely a format layer. The same `readPod`
  * call can also feed verification tools, format inspectors, or
  * archive utilities that don't care about decryption.
@@ -36,18 +36,18 @@ import { type NoydbPodHeader } from './format.js';
 import type { Vault } from '../kernel/vault.js';
 import type { BundleRecipient } from '../with-party/team/keyring.js';
 import type { Cover } from '../with-party/directory/cover/types.js';
-import type { SealingKeyProvider, RecipientSealer, RecipientHint } from '../with-party/team/managed-passphrase.js';
+import type { SealingKeyProvider, RecipientSealer, RecipientHint } from '../with-party/team/managed-secret.js';
 /**
  * The credential kinds that can be bundled for auto-unlock.
  * WebAuthn is intentionally excluded — it is hardware-bound and
  * cannot be embedded as a portable credential.
  */
-export type AutoCredentialKind = 'passphrase' | 'password' | 'pin';
+export type AutoCredentialKind = 'secret' | 'password' | 'pin';
 /**
  * A typed credential for auto-unlock. Carries the credential `kind`
  * alongside the plaintext `value`, so consumers can dispatch the
  * correct login/prefill path rather than treating all credentials
- * as passphrases.
+ * as secrets.
  *
  * `bundle.ts` is a pure format layer — it carries the credential
  * without interpreting it. The consumer is responsible for
@@ -112,17 +112,17 @@ export interface WritePodOptions {
     /**
      * Single-recipient re-keying shorthand. When set, the
      * bundle's keyring is replaced with one freshly-derived entry sealed
-     * with this passphrase. The recipient inherits the source keyring's
+     * with this secret. The recipient inherits the source keyring's
      * userId, role, and permissions. Mutually exclusive with `recipients`.
      */
-    readonly exportPassphrase?: string;
+    readonly exportSecret?: string;
     /**
      * Multi-recipient re-keying. Replaces the bundle's keyring
      * map with one slot per recipient, each sealed with its own
-     * passphrase. DEKs are unwrapped from the source keyring once and
+     * secret. DEKs are unwrapped from the source keyring once and
      * re-wrapped per recipient — record ciphertext is unchanged.
      *
-     * Mutually exclusive with `exportPassphrase`. When neither is set,
+     * Mutually exclusive with `exportSecret`. When neither is set,
      * the bundle inherits the source keyring as-is (today's behaviour,
      * suited to personal backup-and-restore).
      */
@@ -130,8 +130,8 @@ export interface WritePodOptions {
     /**
      * Auto-unlock — unsealed per-user credentials.
      *
-     * Generalises `autoPassphrases` to support any bundleable credential
-     * kind (`passphrase` | `password` | `pin`).
+     * Generalises `autoSecrets` to support any bundleable credential
+     * kind (`secret` | `password` | `pin`).
      *
      * Public-by-design: anyone holding the bundle bytes can read these
      * plaintext credentials. Use for demo data, sample vaults,
@@ -141,8 +141,8 @@ export interface WritePodOptions {
      * bare `{ perUser }` without it is rejected at write time — the
      * safety net against a careless call against a production vault.
      *
-     * Mutually exclusive with `sealedCredentials`, `autoPassphrases`,
-     * and `sealedPassphrases`.
+     * Mutually exclusive with `sealedCredentials`, `autoSecrets`,
+     * and `sealedSecrets`.
      */
     readonly autoCredentials?: {
         readonly policy: 'public-by-design';
@@ -152,8 +152,8 @@ export interface WritePodOptions {
      * Auto-unlock — per-user credentials sealed under a
      * {@link SealingKeyProvider}.
      *
-     * Generalises `sealedPassphrases` to support any bundleable
-     * credential kind (`passphrase` | `password` | `pin`).
+     * Generalises `sealedSecrets` to support any bundleable
+     * credential kind (`secret` | `password` | `pin`).
      *
      * The hub seals each user's plaintext credential under `provider`
      * and embeds the resulting sealed envelopes in the bundle. The
@@ -170,8 +170,8 @@ export interface WritePodOptions {
      * The bundle can only be unsealed by the holder of the matching
      * private key.
      *
-     * Mutually exclusive with `autoCredentials`, `autoPassphrases`,
-     * and `sealedPassphrases`.
+     * Mutually exclusive with `autoCredentials`, `autoSecrets`,
+     * and `sealedSecrets`.
      */
     readonly sealedCredentials?: {
         readonly mode: 'self-target';
@@ -188,7 +188,7 @@ export interface WritePodOptions {
     /**
      * @deprecated Use `autoCredentials` instead.
      *
-     * Auto-unlock — unsealed per-user passphrases.
+     * Auto-unlock — unsealed per-user secrets.
      *
      * Public-by-design: anyone holding the bundle bytes can read these
      * plaintext credentials. Use for demo data, sample vaults,
@@ -199,33 +199,33 @@ export interface WritePodOptions {
      * safety net against a careless call against a production vault.
      *
      * Mutually exclusive with `autoCredentials`, `sealedCredentials`,
-     * and `sealedPassphrases`.
+     * and `sealedSecrets`.
      */
-    readonly autoPassphrases?: {
+    readonly autoSecrets?: {
         readonly policy: 'public-by-design';
         readonly perUser: Record<string, string>;
     };
     /**
      * @deprecated Use `sealedCredentials` instead.
      *
-     * Auto-unlock — per-user passphrases sealed under a
+     * Auto-unlock — per-user secrets sealed under a
      * {@link SealingKeyProvider} (self-target only).
      *
-     * The hub seals each user's plaintext passphrase under `provider`
+     * The hub seals each user's plaintext secret under `provider`
      * and embeds the resulting sealed envelopes in the bundle. The
      * recipient must hold a provider with a matching `pid` (i.e.,
      * `provider.id`) to auto-unseal on import.
      *
-     * `mode: 'self-target'` is the only mode for `sealedPassphrases` — sender
+     * `mode: 'self-target'` is the only mode for `sealedSecrets` — sender
      * and recipient share the same provider identity (same iCloud Keychain
      * entry, same MDM-provisioned bundle id, same KMS account, etc.).
      * For recipient-target sealing via the `RecipientSealer` interface,
      * use `sealedCredentials` with `mode: 'recipient-target'` (§11.4).
      *
      * Mutually exclusive with `autoCredentials`, `sealedCredentials`,
-     * and `autoPassphrases`.
+     * and `autoSecrets`.
      */
-    readonly sealedPassphrases?: {
+    readonly sealedSecrets?: {
         readonly mode: 'self-target';
         readonly provider: SealingKeyProvider;
         readonly perUser: Record<string, string>;
@@ -235,7 +235,7 @@ export interface WritePodOptions {
 export type WriteNoydbBundleOptions = WritePodOptions;
 /**
  * Result returned by `readPod`. The caller is expected to
- * pass `dumpJson` into `vault.load(json, passphrase)` to
+ * pass `dumpJson` into `vault.load(json, secret)` to
  * actually restore a vault. Splitting the layers keeps the
  * bundle module free of crypto concerns — see file-level docs.
  */
@@ -251,7 +251,7 @@ export interface NoydbBundleReadResult {
      *
      * Consumers dispatch on `cred.kind` to choose the correct login /
      * prefill path. Pre-0.2 bundles (bare string entries) are coerced
-     * to `{ kind: 'passphrase', value }` on read for back-compat.
+     * to `{ kind: 'secret', value }` on read for back-compat.
      *
      * For `kind: 'sealed'` bundles read without `sealingProviders`, the
      * `value` field is the raw base64 sealed bytes — opaque to the
@@ -270,7 +270,7 @@ export interface NoydbBundleReadResult {
 export interface ReadNoydbBundleOptions {
     /**
      * Recipient-side sealing providers used to unseal entries from
-     * `sealedPassphrases`. The reader picks the one whose `.id`
+     * `sealedSecrets`. The reader picks the one whose `.id`
      * matches each entry's `pid`. Multiple providers may be supplied
      * (different users may seal under different identities).
      *
@@ -391,8 +391,6 @@ export declare const readNoydbBundleHeader: typeof readPodHeader;
 export declare function readPodCover(bytes: Uint8Array, opts?: {
     readonly locale?: string;
 }): Cover | undefined;
-/** @deprecated Use `readPodCover` (#799 rename). */
-export declare const readNoydbBundlePublicEnvelope: typeof readPodCover;
 /**
  * Read a full `.noydb` bundle: validate magic + header, verify
  * integrity hash over the body bytes, decompress, and return the
@@ -404,9 +402,9 @@ export declare const readNoydbBundlePublicEnvelope: typeof readPodCover;
  * format error so consumers can pattern-match in catch blocks
  * (corrupted-in-transit vs malformed-by-producer).
  *
- * Note: this function does NOT take a passphrase. The dump JSON
+ * Note: this function does NOT take a secret. The dump JSON
  * inside the body still contains encrypted records — restoring
- * the vault requires `vault.load(dumpJson, passphrase)`
+ * the vault requires `vault.load(dumpJson, secret)`
  * after this call. Splitting the layers keeps the bundle module
  * free of crypto concerns and lets the same code feed format
  * inspectors that never decrypt anything.

package/dist/with-pod/format.d.ts

@@ -34,7 +34,7 @@
  * The dump JSON inside the body still contains the original
  * metadata, but that's only readable by someone who already has the
  * file bytes — the same person who could read the encrypted records
- * with the right passphrase.
+ * with the right secret.
  *
  * **Why minimum disclosure** in the header? Because consumers will
  * inevitably store these in services where the filename, file size,
@@ -128,7 +128,7 @@ export interface NoydbPodHeader {
     /**
      * Auto-unlock material indicator. When present, the bundle
      * body wraps the dump JSON in a structure carrying per-user
-     * passphrases — either plaintext (`'unsealed'`, public-by-design)
+     * secrets — either plaintext (`'unsealed'`, public-by-design)
      * or sealed under a `SealingKeyProvider` (`'sealed'`, requires
      * matching provider on the recipient side).
      *

package/dist/with-pod/index.d.ts

@@ -14,8 +14,9 @@
 export { writePod, readPod, readPodHeader, readPodCover, writeNoydbBundle, readNoydbBundle, readNoydbBundleHeader, resetBrotliSupportCache, } from './bundle.js';
 export type { Cover } from '../with-party/directory/cover/types.js';
 export type { WritePodOptions, WriteNoydbBundleOptions, ReadNoydbBundleOptions, NoydbBundleReadResult, } from './bundle.js';
-export { NOYDB_BUNDLE_MAGIC, NOYDB_BUNDLE_PREFIX_BYTES, NOYDB_BUNDLE_FORMAT_VERSION, FLAG_COMPRESSED, FLAG_HAS_INTEGRITY_HASH, COMPRESSION_NONE, COMPRESSION_GZIP, COMPRESSION_BROTLI, validateBundleHeader, encodeBundleHeader, } from './format.js';
+export { NOYDB_BUNDLE_MAGIC, NOYDB_BUNDLE_PREFIX_BYTES, NOYDB_BUNDLE_FORMAT_VERSION, FLAG_COMPRESSED, FLAG_HAS_INTEGRITY_HASH, COMPRESSION_NONE, COMPRESSION_GZIP, COMPRESSION_BROTLI, validateBundleHeader, encodeBundleHeader, hasNoydbBundleMagic, } from './format.js';
 export type { CompressionAlgo, NoydbPodHeader, NoydbBundleHeader, } from './format.js';
 export { generateULID, isULID } from './ulid.js';
 export { wrapPodStore, createPodStore, wrapBundleStore, createBundleStore } from './pod-store.js';
 export type { WrappedPodNoydbStore, WrapPodStoreOptions, WrappedBundleNoydbStore, WrapBundleStoreOptions, } from './pod-store.js';
+export { BundleIntegrityError, BundleSealMismatchError, PodVersionConflictError, BundleVersionConflictError, BackupLedgerError, BackupCorruptedError, } from '../kernel/errors.js';

package/dist/with-shape/blobs/blob-compaction.d.ts

@@ -105,24 +105,41 @@ export interface BlobEvictionEntry {
     readonly recordId: string;
     readonly slotName: string;
     readonly blobHash: string;
-    readonly reason: 'ttl' | 'predicate' | 'both';
+    /** `'budget'` — evicted by the #808 cache-budget LRU pass, not a policy. */
+    readonly reason: 'ttl' | 'predicate' | 'both' | 'budget';
     readonly evictedAt: string;
     readonly actor: string;
 }
 export interface CompactionResult {
-    /** Number of blob slots evicted across all collections. */
+    /** Number of blob slots evicted by the policy pass across all collections. */
     readonly evicted: number;
     /** Number of records touched (iterated + policy checked). */
     readonly records: number;
     /** Number of collections with `blobFields` configured. */
     readonly collections: number;
-    /** Number of audit entries written. Equal to `evicted`. */
+    /**
+     * Number of audit entries written — one per policy eviction plus one per
+     * budget SLOT eviction (dropping a device-local cache copy writes none).
+     */
     readonly auditEntries: number;
     /**
      * Number of slots that would have evicted (TTL/predicate triggered)
      * but were retained by a `legalHold` or `retainUntil` floor.
      */
     readonly held: number;
+    /**
+     * #808: number of slots whose due policy eviction was skipped because they
+     * are pinned for offline on THIS device (pin state is device-local).
+     */
+    readonly pinned: number;
+    /**
+     * #808: number of evictions performed by the `cacheBudget` LRU pass —
+     * internal slots evicted through the standard eviction writer plus
+     * device-local external cache copies dropped. 0 when no budget was given.
+     */
+    readonly budgetEvicted: number;
+    /** #808: plaintext bytes freed by the `cacheBudget` LRU pass. */
+    readonly budgetBytesFreed: number;
     /** Per-collection breakdown for diagnostics. */
     readonly byCollection: Record<string, {
         records: number;
@@ -143,6 +160,22 @@ export interface CompactRunOptions {
      * what would happen.
      */
     readonly dryRun?: boolean;
+    /**
+     * #808 mobile cache budget: cap the locally-cached UNPINNED blob bytes.
+     * After the policy pass, a dedicated LRU pass walks every collection's
+     * slots (pinned slots and `legalHold`/`retainUntil`-held slots are exempt
+     * and uncounted) and evicts oldest-access-first — internal slots through
+     * the standard eviction writer (`deleteSlot` + a `'budget'` audit entry),
+     * external slots by dropping their device-local encrypted cache copy only
+     * (the object-store copy is authoritative and untouched) — until the
+     * remaining unpinned bytes fit `maxBytes`. Internal slots count their
+     * uncompressed `size`; external slots count `cachedBytes` (0 = nothing
+     * local, nothing to evict). LRU order comes from the device-local
+     * `lastAccessAt` stamp, falling back to `uploadedAt`.
+     */
+    readonly cacheBudget?: {
+        readonly maxBytes: number;
+    };
 }
 export interface CompactionContext {
     readonly adapter: NoydbStore;
@@ -166,5 +199,12 @@ export interface CompactionContext {
     readonly listSlots: (collection: string, id: string) => Promise<SlotInfo[]>;
     /** Delete a slot and decrement its blob's refCount. */
     readonly deleteSlot: (collection: string, id: string, slotName: string) => Promise<void>;
+    /**
+     * #808: drop a slot's DEVICE-LOCAL cached copy (the encrypted external
+     * side-cache) without touching the slot or the object store. Returns the
+     * plaintext bytes freed. Optional — absent (or a 0 return) means external
+     * cache entries simply cannot be budget-evicted through this context.
+     */
+    readonly dropLocalCache?: (collection: string, id: string, slotName: string) => Promise<number>;
 }
 export declare function runCompaction(ctx: CompactionContext, options?: CompactRunOptions): Promise<CompactionResult>;