@noy-db/hub 0.4.0-pre.1 → 0.4.0-pre.2

package/dist/tiers/index.js

@@ -11,19 +11,19 @@ import {
   putAtTier,
   syncDerivedOutputs,
   withTiers
-} from "../chunk-DDATL6PU.js";
-import "../chunk-UC2ETWF3.js";
-import "../chunk-DVUZMT2W.js";
-import "../chunk-WEYZTLXN.js";
-import "../chunk-IY23KFNZ.js";
-import "../chunk-N6WF5PKC.js";
-import "../chunk-6HY2X62D.js";
+} from "../chunk-IU22SQGU.js";
+import "../chunk-MSO2C3KG.js";
+import "../chunk-PEY6ZTCF.js";
+import "../chunk-QXPOEAKR.js";
+import "../chunk-LLVW4V7R.js";
+import "../chunk-M25ZIEB2.js";
+import "../chunk-5BB3N4KU.js";
 import "../chunk-LP7BEXCT.js";
-import "../chunk-HOONYZY2.js";
-import "../chunk-LSASLXGC.js";
+import "../chunk-5P5AAXYA.js";
+import "../chunk-5BHNQNBI.js";
 import {
   TiersNotEnabledError
-} from "../chunk-W2OG6JOL.js";
+} from "../chunk-IGM563N5.js";
 import "../chunk-PZ5AY32C.js";
 export {
   NO_TIERS,

package/dist/to/index.js

@@ -4,7 +4,7 @@ import {
   NetworkError,
   PodVersionConflictError,
   StoreCapabilityError
-} from "../chunk-W2OG6JOL.js";
+} from "../chunk-IGM563N5.js";
 import "../chunk-PZ5AY32C.js";
 export {
   BundleVersionConflictError,

package/dist/tx/index.js

@@ -3,9 +3,9 @@ import {
   TxContext,
   TxVault,
   runTransaction
-} from "../chunk-JRBNCUNT.js";
+} from "../chunk-FLHOTGOO.js";
 import "../chunk-ZJADGNYF.js";
-import "../chunk-W2OG6JOL.js";
+import "../chunk-IGM563N5.js";
 import "../chunk-PZ5AY32C.js";
 
 // src/with-commit/tx/dry-run.ts
@@ -44,7 +44,7 @@ async function runDryRun(db, fn) {
     const gctx = { existing: before, vault: facade, userId: v.userId, role: v.role };
     try {
       await registry.runChecks(op.collectionName, after, gctx);
-      const { GuardExecutor } = await import("../executor-KGNLJD6M.js");
+      const { GuardExecutor } = await import("../executor-WQQRU6DO.js");
       for (const g of guards) {
         await GuardExecutor.checkFrozenFields(g, op.id, before, after);
       }

package/dist/util/index.js

@@ -3,7 +3,7 @@ import {
 } from "../chunk-PY4KJPYU.js";
 import {
   FilenameSanitizationError
-} from "../chunk-W2OG6JOL.js";
+} from "../chunk-IGM563N5.js";
 import "../chunk-PZ5AY32C.js";
 
 // src/kernel/util/sanitize-filename.ts

package/dist/{verify-26Y5GNMK.js → verify-MXN66IIH.js}

@@ -2,10 +2,10 @@ import {
   blindedEqual,
   evaluateKofN,
   openVdigPayload
-} from "./chunk-IY23KFNZ.js";
+} from "./chunk-LLVW4V7R.js";
 import {
   dualReadSealedSlot
-} from "./chunk-N6WF5PKC.js";
+} from "./chunk-M25ZIEB2.js";
 import {
   VDIG_ITERATIONS,
   normalizeForVerify,
@@ -14,11 +14,11 @@ import {
 import {
   base64ToBuffer,
   generateSalt
-} from "./chunk-HOONYZY2.js";
+} from "./chunk-5P5AAXYA.js";
 import {
   ClassifiedConfigError,
   ClassifiedVerifyError
-} from "./chunk-W2OG6JOL.js";
+} from "./chunk-IGM563N5.js";
 import "./chunk-PZ5AY32C.js";
 
 // src/kernel/enclave/classify/verify.ts
@@ -137,4 +137,4 @@ export {
   verifyDigestField,
   verifyTextField
 };
-//# sourceMappingURL=verify-26Y5GNMK.js.map
+//# sourceMappingURL=verify-MXN66IIH.js.map

package/dist/via/blob/active.d.ts

@@ -10,6 +10,29 @@
  * this (ESM tree-shaking + hub's `"sideEffects": false`).
  */
 import type { BlobStrategy } from '../../port/with/blob-strategy.js';
+import type { BlobPinStore, BlobCacheStats } from '../../with-shape/blobs/blob-pinning.js';
+/** Options for {@link withBlobs} (#808). */
+export interface WithBlobsOptions {
+    /**
+     * Device-local backend for the offline-pin registry + external side-cache
+     * (`collection.blob(id).pin()`, the `cacheBudget` LRU stamps). Default:
+     * in-memory — pins then last one app session. Supply a durable,
+     * DEVICE-LOCAL store (IndexedDB-backed on the web; it must never sync) to
+     * keep pins across restarts. See `BlobPinStore`'s doc for the posture.
+     */
+    readonly pinStore?: BlobPinStore;
+}
+/**
+ * The strategy `withBlobs()` returns — a `BlobStrategy` plus the device-local
+ * blob-cache KPI surface (#808).
+ */
+export interface BlobsService extends BlobStrategy {
+    /**
+     * Snapshot of this device's blob-cache KPI counters: local-read hits,
+     * network misses, and total bytes downloaded from the object store.
+     */
+    cacheStats(): BlobCacheStats;
+}
 /**
  * Build a default `BlobStrategy` ready to pass into `createNoydb`.
  *
@@ -17,6 +40,9 @@ import type { BlobStrategy } from '../../port/with/blob-strategy.js';
  * avoid shadowing the very common local idiom
  * `const blobs = invoices.blob(id)` in user code.
  *
+ * One `withBlobs()` instance owns one device-local pin registry + KPI
+ * counter set (#808) — treat it as "this device's" blob service.
+ *
  * @example
  * ```ts
  * import { createNoydb } from '@noy-db/hub'
@@ -31,4 +57,4 @@ import type { BlobStrategy } from '../../port/with/blob-strategy.js';
  * await db.vault('acme').collection('invoices').blob('inv-1').put('receipt.pdf', bytes)
  * ```
  */
-export declare function withBlobs(): BlobStrategy;
+export declare function withBlobs(options?: WithBlobsOptions): BlobsService;

package/dist/via/blob/index.d.ts

@@ -19,7 +19,11 @@
  * code should prefer this subpath so the import boundary is explicit.
  */
 export { withBlobs } from './active.js';
+export type { WithBlobsOptions, BlobsService } from './active.js';
 export type { BlobStrategy, BlobStrategyOpenArgs } from '../../port/with/blob-strategy.js';
+export { memoryBlobPinStore, blobPinKey } from '../../with-shape/blobs/blob-pinning.js';
+export type { BlobPinStore, BlobPinEntry, BlobCacheStats } from '../../with-shape/blobs/blob-pinning.js';
+export { BlobOfflineError } from '../../kernel/errors.js';
 export { memoryObjectProjection } from '../../with-shape/blobs/object-projection.js';
 export type { ObjectProjection, ObjectMeta, ObjectListEntry, PutObjectOptions, ObjectUrlOptions, PutUrlOptions, } from '../../with-shape/blobs/object-projection.js';
 export { importExternalObjects } from '../../with-shape/blobs/import-external.js';

package/dist/{walk-XS3PKM6I.js → walk-H4YE52S2.js}

@@ -3,19 +3,19 @@ import {
 } from "./chunk-VYYM3MEN.js";
 import {
   derivePersistedSchema
-} from "./chunk-BOKIKJJB.js";
+} from "./chunk-EDC6MLXV.js";
 import {
   loadPersistedSchema
-} from "./chunk-F6T6L2UK.js";
-import "./chunk-DVUZMT2W.js";
-import "./chunk-WEYZTLXN.js";
-import "./chunk-IY23KFNZ.js";
-import "./chunk-N6WF5PKC.js";
-import "./chunk-6HY2X62D.js";
+} from "./chunk-IGAIOGCN.js";
+import "./chunk-PEY6ZTCF.js";
+import "./chunk-QXPOEAKR.js";
+import "./chunk-LLVW4V7R.js";
+import "./chunk-M25ZIEB2.js";
+import "./chunk-5BB3N4KU.js";
 import "./chunk-LP7BEXCT.js";
-import "./chunk-HOONYZY2.js";
-import "./chunk-LSASLXGC.js";
-import "./chunk-W2OG6JOL.js";
+import "./chunk-5P5AAXYA.js";
+import "./chunk-5BHNQNBI.js";
+import "./chunk-IGM563N5.js";
 import "./chunk-PZ5AY32C.js";
 
 // src/with-shape/introspection/walk.ts
@@ -238,4 +238,4 @@ function summariseAggregateOp(value) {
 export {
   dumpVaultSchema
 };
-//# sourceMappingURL=walk-XS3PKM6I.js.map
+//# sourceMappingURL=walk-H4YE52S2.js.map

package/dist/with/index.js

@@ -6,18 +6,18 @@ import {
   assertCanImport,
   canExport,
   canImport
-} from "../chunk-PT37L5DV.js";
-import "../chunk-3SV2EPMN.js";
-import "../chunk-PK6QCH2C.js";
-import "../chunk-DVUZMT2W.js";
-import "../chunk-WEYZTLXN.js";
-import "../chunk-IY23KFNZ.js";
-import "../chunk-N6WF5PKC.js";
-import "../chunk-6HY2X62D.js";
+} from "../chunk-RGL53NXZ.js";
+import "../chunk-HVZT5T22.js";
+import "../chunk-7B4GPCX7.js";
+import "../chunk-PEY6ZTCF.js";
+import "../chunk-QXPOEAKR.js";
+import "../chunk-LLVW4V7R.js";
+import "../chunk-M25ZIEB2.js";
+import "../chunk-5BB3N4KU.js";
 import "../chunk-LP7BEXCT.js";
-import "../chunk-HOONYZY2.js";
-import "../chunk-LSASLXGC.js";
-import "../chunk-W2OG6JOL.js";
+import "../chunk-5P5AAXYA.js";
+import "../chunk-5BHNQNBI.js";
+import "../chunk-IGM563N5.js";
 import "../chunk-PZ5AY32C.js";
 export {
   ServiceBus,

package/dist/with-audit/periods/vault-facade.d.ts

@@ -28,6 +28,12 @@ export interface VaultPeriodsDeps {
     archiveRecords(before: string): Promise<number>;
     /** #615: sweep delete markers off the vault's push-only sync targets. Bound to `vault._purgePeriodTargets`. */
     purgeTargets(before: string): Promise<readonly TargetPurgeCount[]>;
+    /**
+     * #822: mark a reserved-collection write dirty so the sync engine pushes
+     * it. Bound to the vault's `onDirty` when sync is configured, `undefined`
+     * otherwise. Only `_periods` uses it — see `writeReserved`.
+     */
+    onDirty?: ((collection: string, id: string, action: 'put', version: number) => Promise<void>) | undefined;
 }
 export declare class VaultPeriods {
     private readonly deps;

package/dist/{legacy/kernel.d.ts → with-cargo/floor.d.ts}

@@ -2,7 +2,7 @@
  * The `@noy-db/hub/kernel` published subpath has been retired (coordinated
  * removal; consumers migrated to `@noy-db/hub/cargo`). This file survives
  * unpublished as `/cargo`'s internal re-export floor — `with-cargo/index.ts`
- * does `export * from '../legacy/kernel.js'` to consolidate this runtime-helper
+ * does `export * from './floor.js'` to consolidate this runtime-helper
  * / error-class / type surface into the cargo seam, and
  * `cargo-surface-golden.test.ts` reads this file directly as part of that
  * union. Do not reintroduce it as a tsup entry or package.json export.

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

@@ -12,7 +12,7 @@
  *
  * @packageDocumentation
  */
-export * from '../legacy/kernel.js';
+export * from './floor.js';
 export { CustodyApi } from '../with-party/custody/index.js';
 export type { GrantCustodianOptions } from '../with-party/custody/index.js';
 export { liberateVault } from '../with-party/custody/liberate.js';
@@ -32,6 +32,11 @@ export { describeExtraction } from './describe-extraction.js';
 export { decryptExtractedPartition } from './decrypt-partition.js';
 export type { ExtractionPreview } from './describe-extraction.js';
 export type { DecryptedRecord } from './decrypt-partition.js';
+export type { WalkClosureOptions, ClosureResult, DanglingRefNotice } from './walk-closure.js';
+export type { ExtractPartitionResult } from './extract-partition.js';
+export { adoptPartition, unsealDeks, createOwnerOnAdoptedPartition } from './adopt-partition.js';
+export type { AdoptPartitionOptions, AdoptPartitionResult, CreateOwnerResult, CreateOwnerOptions, CreateOwnerStandardOptions, CreateOwnerManagedOptions, } from './adopt-partition.js';
+export { TransferSealError, AdoptionStateError, PartitionExtractionError } from '../kernel/errors.js';
 export type { WriteHook } from '../port/with/write-hooks.js';
 export type { WriteQueue } from '../kernel/write-queue.js';
 export type { WriteConflict } from '../kernel/types.js';

package/dist/with-party/directory/cover/index.d.ts

@@ -12,8 +12,3 @@ export type { SetCoverInput } from './schema.js';
 export { validateCoverInput, isCover } from './schema.js';
 export { mergeCustom, validateCoverSize } from './custom.js';
 export { loadCover, saveCover, readCover, resolveLocale, pickLocale, COVER_RECORD_ID, } from './storage.js';
-export type { PublicEnvelope, PublicEnvelopeText, PublicEnvelopeSchema, PublicEnvelopeField, ResolvedPublicEnvelopeSchema, } from './types.js';
-export { PUBLIC_ENVELOPE_FIELDS, DEFAULT_PUBLIC_ENVELOPE_SCHEMA, } from './types.js';
-export type { SetPublicEnvelopeInput } from './schema.js';
-export { validatePublicEnvelopeInput, isPublicEnvelope } from './schema.js';
-export { loadPublicEnvelope, savePublicEnvelope, readPublicEnvelope, PUBLIC_ENVELOPE_RECORD_ID, } from './storage.js';

package/dist/with-party/directory/cover/schema.d.ts

@@ -31,9 +31,3 @@ export declare function validateCoverInput(input: SetCoverInput, schema: Resolve
  * discriminator keeps its frozen name: `_noydb_public: 1`.)
  */
 export declare function isCover(x: unknown): x is Cover;
-/** @deprecated Use {@link SetCoverInput}. */
-export type SetPublicEnvelopeInput = SetCoverInput;
-/** @deprecated Use {@link validateCoverInput}. */
-export declare const validatePublicEnvelopeInput: typeof validateCoverInput;
-/** @deprecated Use {@link isCover}. */
-export declare const isPublicEnvelope: typeof isCover;

package/dist/with-party/directory/cover/storage.d.ts

@@ -61,11 +61,3 @@ export declare function resolveLocale(cover: Cover, locale: string): Cover;
  * This deviation is documented in `https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/public-envelope.md`.
  */
 export declare function pickLocale(value: string | Record<string, string>, locale: string, defaultLocale: string | undefined): string;
-/** @deprecated Use {@link COVER_RECORD_ID}. */
-export declare const PUBLIC_ENVELOPE_RECORD_ID = "public-envelope";
-/** @deprecated Use {@link loadCover}. */
-export declare const loadPublicEnvelope: typeof loadCover;
-/** @deprecated Use {@link saveCover}. */
-export declare const savePublicEnvelope: typeof saveCover;
-/** @deprecated Use {@link readCover}. */
-export declare const readPublicEnvelope: typeof readCover;

package/dist/with-party/directory/cover/types.d.ts

@@ -126,24 +126,3 @@ export interface ResolvedCoverSchema {
  * overrides the keys it provides.
  */
 export declare function resolveSchema(schema: true | CoverSchema | undefined): ResolvedCoverSchema | undefined;
-/** @deprecated Use {@link Cover}. */
-export type PublicEnvelope = Cover;
-/** @deprecated Use {@link CoverText}. */
-export type PublicEnvelopeText = CoverText;
-/** @deprecated Use {@link CoverField}. */
-export type PublicEnvelopeField = CoverField;
-/** @deprecated Use {@link CoverSchema}. */
-export type PublicEnvelopeSchema = CoverSchema;
-/** @deprecated Use {@link ResolvedCoverSchema}. */
-export type ResolvedPublicEnvelopeSchema = ResolvedCoverSchema;
-/** @deprecated Use {@link COVER_FIELDS}. */
-export declare const PUBLIC_ENVELOPE_FIELDS: readonly ["name", "description", "icon", "createdAt", "updatedAt", "defaultLocale", "custom"];
-/** @deprecated Use {@link DEFAULT_COVER_SCHEMA}. */
-export declare const DEFAULT_PUBLIC_ENVELOPE_SCHEMA: {
-    readonly fields: readonly ["name", "description", "icon", "createdAt", "updatedAt", "defaultLocale"];
-    readonly maxIconBytes: number;
-    readonly iconMimeTypes: readonly ["image/png", "image/svg+xml"];
-    readonly maxStringChars: 200;
-    readonly maxCustomBytes: number;
-    readonly maxCoverBytes: number;
-};

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

@@ -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

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>;

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

@@ -0,0 +1,112 @@
+/**
+ * #808 — device-local blob pin registry + external side-cache + KPI counters.
+ *
+ * Pinning marks a blob slot "keep this available offline" **for this device
+ * only**. Pin state is intentionally NEVER written to the vault's
+ * `NoydbStore` — the vault store is the synced/shared substrate, and each
+ * device pins for itself. Instead, `withBlobs()` owns one {@link BlobPinCache}
+ * per strategy instance and threads it into every `BlobSet` it opens; the
+ * registry rows live in a pluggable {@link BlobPinStore}.
+ *
+ * The default backend is in-memory ({@link memoryBlobPinStore}) — the hub has
+ * NO device-persistence idiom of its own (it never touches IndexedDB or any
+ * Node fs API; persistence backends are the `to-*` package family), so a
+ * durable registry is supplied by the consumer:
+ * `withBlobs({ pinStore: myIdbBackedStore })`. The interface is four async
+ * methods, deliberately trivial to implement over IndexedDB / SQLite / a file.
+ *
+ * ## What a registry row holds
+ *
+ * One row per `{vault, collection, record, slot}` ({@link blobPinKey}):
+ *  - the pin flag + timestamps (LRU input for the cache-budget pass), and
+ *  - for `external: true` slots, the **local encrypted copy** of the object's
+ *    bytes ({@link BlobPinEntry.cipher}). The object-store copy of an external
+ *    blob lives OUTSIDE the zero-knowledge envelope by design; the local copy
+ *    does NOT — it is AES-256-GCM-encrypted under the vault's `_blob` DEK
+ *    through the same enclave path that encrypts blob chunks
+ *    (`encryptBytesWithAAD`, AAD-bound to the row's pin key), so a stolen
+ *    device store leaks nothing the vault store wouldn't.
+ *
+ * Internal (chunked) blobs never store bytes here — their ciphertext already
+ * lives in `_blob_chunks`; the registry only carries their pin flag and
+ * access times.
+ *
+ * @module
+ */
+/** One device-local registry row — see the module doc for the field posture. */
+export interface BlobPinEntry {
+    /** Slot is pinned for offline on THIS device. */
+    readonly pinned: boolean;
+    /** ISO timestamp of the pin (absent when not pinned). */
+    readonly pinnedAt?: string;
+    /** ISO timestamp of the last local read — LRU input for the budget pass. */
+    readonly lastAccessAt?: string;
+    /** Plaintext byte length of the cached external copy (external slots only). */
+    readonly cachedBytes?: number;
+    /**
+     * Encrypted local copy of an external slot's bytes: base64 IV + base64
+     * AES-256-GCM ciphertext under the vault's `_blob` DEK, AAD-bound to the
+     * row's {@link blobPinKey}. On an UNENCRYPTED vault (`encrypt: false`) the
+     * fallback mirrors the envelope convention: `iv === ''`, `data` = base64
+     * plaintext.
+     */
+    readonly cipher?: {
+        readonly iv: string;
+        readonly data: string;
+    };
+}
+/**
+ * Pluggable device-local backend for the pin registry (#808). Implementations
+ * MUST be device-local (never synced) — an IndexedDB- or file-backed store is
+ * the expected production shape; {@link memoryBlobPinStore} is the default.
+ */
+export interface BlobPinStore {
+    get(key: string): Promise<BlobPinEntry | null>;
+    set(key: string, entry: BlobPinEntry): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** All rows whose key starts with `prefix` (`''` = every row). */
+    entries(prefix: string): Promise<Array<{
+        key: string;
+        entry: BlobPinEntry;
+    }>>;
+}
+/**
+ * In-memory {@link BlobPinStore} — the default. Pin state then lasts for the
+ * strategy instance's lifetime (one app session); pass a durable store to
+ * `withBlobs({ pinStore })` to keep pins across restarts.
+ */
+export declare function memoryBlobPinStore(): BlobPinStore;
+/**
+ * Device-local blob-cache KPI counters (#808) — read via
+ * `withBlobs().cacheStats()`. "Local" reads (internal chunks, cached external
+ * copies) count as hits; network fetches from the object store count as
+ * misses and add to `bytesDownloaded` (the 4G-budget number).
+ */
+export interface BlobCacheStats {
+    readonly hits: number;
+    readonly misses: number;
+    readonly bytesDownloaded: number;
+}
+/**
+ * The per-strategy bundle `withBlobs()` threads into every `BlobSet`: the
+ * registry backend plus the shared mutable KPI counters.
+ *
+ * @internal
+ */
+export interface BlobPinCache {
+    readonly store: BlobPinStore;
+    readonly stats: {
+        hits: number;
+        misses: number;
+        bytesDownloaded: number;
+    };
+}
+/** @internal */
+export declare function createBlobPinCache(store?: BlobPinStore): BlobPinCache;
+/**
+ * Registry key for one slot's row: `{vault}::{collection}::{record}::{slot}`
+ * (the blobs' established `::` separator — record ids and slot names are
+ * already `::`-refused at the write surface, see `assertKeyPartSafe`).
+ * Omitting `slotName` yields the record's row PREFIX (for per-record scans).
+ */
+export declare function blobPinKey(vault: string, collection: string, recordId: string, slotName?: string): string;