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

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

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;

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

@@ -2,6 +2,7 @@ import type { NoydbStore, BlobObject, SlotInfo, VersionRecord, BlobPutOptions, B
 import type { ObjectProjection } from './object-projection.js';
 import type { BlobFieldsConfig } from './blob-compaction.js';
 import { type EnclaveKey } from '../../kernel/enclave/index.js';
+import { type BlobPinCache } from './blob-pinning.js';
 import type { UnlockedKeyring } from '../../with-party/team/keyring.js';
 /**
  * DEK slot name for vault-shared blob data. Calling `getDEK('_blob')`
@@ -69,6 +70,12 @@ export declare class BlobSet {
     private readonly objectStore;
     private readonly blobFields;
     private readonly keyring;
+    /**
+     * Device-local pin registry + external side-cache + KPI counters (#808).
+     * Injected by `withBlobs()` (one shared instance per strategy — per
+     * "device"); absent on a direct construction that never threads one.
+     */
+    private readonly pinCache;
     /**
      * Set only on the cleared clone `atTier()` returns (#749) — never by
      * `openSlot`/`Collection.blob()`. Its presence is what makes a `BlobSet`
@@ -91,6 +98,7 @@ export declare class BlobSet {
         blobFields?: BlobFieldsConfig;
         keyring?: UnlockedKeyring;
         clearedTier?: number;
+        pinCache?: BlobPinCache;
     });
     /**
      * #724 I1 completion: a legacy (non-`perRecordKeys`) blob has no per-blob
@@ -101,7 +109,7 @@ export declare class BlobSet {
      * DECLARED; a collection with an undeclared field (or no `blobFields` at
      * all) constructs fine and reaches this write path unguarded. Refuse the
      * write itself instead of broadening the construction mandate, which
-     * would over-refuse blobless tiered collections (`blobStrategy` is
+     * would over-refuse blobless tiered collections (`blobsStrategy` is
      * vault-wide, not per-collection). Called from every content-write entry
      * (`put()`, `publish()`) — never from a read path, so a pre-existing
      * legacy blob stays readable (back-compat).
@@ -1136,7 +1144,11 @@ export declare class BlobSet {
     /**
      * Fetch all bytes for the named slot.
      * Returns `null` if the slot does not exist.
-     * Throws `NotFoundError` if the index entry exists but a chunk is missing.
+     * Throws `BlobOfflineError` if the content is not available locally (#808):
+     * an internal blob whose chunk envelopes are absent from the local store, or
+     * an external slot with no local cached copy while the object store is
+     * unreachable. External reads populate the device-local encrypted
+     * side-cache, so a repeat read is served locally (see `pin()`).
      */
     get(slotName: string): Promise<Uint8Array | null>;
     /**
@@ -1182,6 +1194,12 @@ export declare class BlobSet {
     /**
      * List all slot entries for this record.
      * Returns metadata only — no chunk data is loaded.
+     *
+     * #808: when a pin registry is present (`withBlobs()`), each entry is
+     * annotated with this DEVICE's view — `pinned` / `lastAccessAt` /
+     * `cachedBytes` (see their `SlotInfo` doc comments). The annotations come
+     * from the device-local registry, never the vault store, and are what
+     * `vault.compact()`'s pin exemption + cache-budget LRU pass key off.
      */
     list(): Promise<SlotInfo[]>;
     /**
@@ -1189,6 +1207,72 @@ export declare class BlobSet {
      * Decrements refCount on the blob. Chunks are GC'd by `vault.blobGC()`.
      */
     delete(slotName: string): Promise<void>;
+    /**
+     * Pin the named slot for offline availability ON THIS DEVICE.
+     *
+     * - Downloads eagerly (call while online): an internal blob's chunks are
+     *   fetched once to prove they are locally readable; an `external` slot's
+     *   bytes are fetched from the object store and kept in the device-local
+     *   side-cache, **encrypted** under the vault's `_blob` DEK via the same
+     *   enclave path as chunk encryption (the object-store copy sits outside
+     *   the ZK envelope by design; the local copy does not).
+     * - A pinned slot is EXEMPT from `vault.compact()` eviction — both the
+     *   `blobFields` policy pass and the `cacheBudget` LRU pass.
+     * - Pin state is device-local (never synced): it lives in the `withBlobs()`
+     *   pin registry, not in the vault store. Each device pins for itself.
+     *
+     * Throws `NotFoundError` for a missing slot and `BlobOfflineError` when the
+     * eager download cannot complete (offline).
+     */
+    pin(slotName: string): Promise<void>;
+    /**
+     * Unpin the named slot on this device — it returns to the normal lifecycle:
+     * `blobFields` policy eviction applies again, and any local cached copy
+     * (external slots) stays but becomes budget-managed (`cacheBudget` LRU).
+     * A no-op when the slot is not pinned here.
+     */
+    unpin(slotName: string): Promise<void>;
+    /** Whether the named slot is pinned for offline ON THIS DEVICE (#808). */
+    isPinned(slotName: string): Promise<boolean>;
+    /**
+     * Drop this slot's device-local cached copy (the encrypted external
+     * side-cache) WITHOUT touching the slot, the vault store, or the object
+     * store. Returns the plaintext bytes freed (0 when nothing was cached, the
+     * slot is pinned — pinned copies are exempt — or no registry is present).
+     * The cache-budget pass inside `vault.compact()` is the expected caller;
+     * the LRU access row itself is kept.
+     */
+    dropLocalCache(slotName: string): Promise<number>;
+    /** This slot's registry key — see {@link blobPinKey}. */
+    private pinKeyFor;
+    /** AAD binding for a cached external copy: the row's own registry key. */
+    private pinCopyAAD;
+    private requirePinCache;
+    /** KPI hit + LRU access stamp for a successful LOCAL read. No-op without a registry. */
+    private recordLocalHit;
+    /**
+     * Read an `external` slot (#808 taxonomy): local encrypted side-cache first
+     * (hit); else the object store (miss + `bytesDownloaded`), auto-caching the
+     * fetched bytes so the NEXT read — and any later offline read — is local.
+     * A network failure with no local copy is the typed `BlobOfflineError`;
+     * a genuinely absent object (fetch succeeded, nothing there) stays `null`.
+     */
+    private readExternal;
+    /**
+     * Decrypt a cached external copy. `null` (treated as a cache miss → network
+     * refresh) when the vault keys can no longer open it — e.g. the copy was
+     * cached before the owning record moved tiers, so it is sealed under a DEK
+     * this handle no longer resolves. Genuine non-crypto failures propagate.
+     */
+    private decryptCachedCopy;
+    /**
+     * Write an external slot's bytes into the device-local side-cache —
+     * ENCRYPTED under the vault's `_blob` DEK (owner tier) via the enclave's
+     * AAD-bound path, mirroring chunk encryption; base64 plaintext with
+     * `iv: ''` only on an unencrypted vault (the envelope convention). A
+     * pre-existing pin flag survives the rewrite.
+     */
+    private cacheExternalCopy;
     /**
      * Return a native `Response` whose body streams the decrypted,
      * decompressed blob bytes with full HTTP metadata headers.

package/dist/with-shape/introspection/index.d.ts

@@ -9,4 +9,10 @@
  */
 export type { VaultSchemaSnapshot, DumpSchemaOptions, CollectionDescriptor, CollectionConfig, CollectionStats, FieldDescriptor, FieldSource, MaterializedViewDescriptor, OverlayViewDescriptor, DerivationDescriptor, InternalCollectionStats, } from './types.js';
 export { dumpVaultSchema } from './walk.js';
+export type { VaultIntrospectState } from './walk.js';
 export { jsonSchemaToFields } from './fields.js';
+export type { SchemaIntrospection } from './types.js';
+export type { FieldMeta, SemanticType } from './field-meta.js';
+export type { CollectionDescription, DescribedField, DescribeOptions } from './describe.js';
+export { applyListProjection } from './projection.js';
+export type { ListProjectionOptions } from './projection.js';

package/dist/with-shape/schema-update/index.d.ts

@@ -4,3 +4,4 @@ export { evaluateStrategies } from './dispatch.js';
 export { blindUpdate, additiveOnly, lockSchema } from './strategies.js';
 export { coordinatedCutover } from './cutover.js';
 export { SchemaUpdateGate } from './gate.js';
+export type { FenceDoc } from './fence.js';

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

@@ -3,8 +3,9 @@
  *
  * Store routing (multiplex by collection/size/age) and composable store
  * middleware (retry, logging, metrics, circuit-breaker, cache, health-check).
- * Root-barrel-only: no dedicated `@noy-db/hub/with-store` subpath export —
- * consumers reach these through the main `@noy-db/hub` entry.
+ * Published as `@noy-db/hub/store` (#843 C3a). Also re-exported from the root
+ * barrel, matching how the Via features are dual-homed — the subpath exists so
+ * the surface is navigable and tree-shakeable, not to force a migration.
  *
  * Named re-exports (not `export *`) so tsup keeps the barrel populated
  * even with `sideEffects: false`.

package/dist/with-store/route-store.d.ts

@@ -204,7 +204,7 @@ export interface RoutedNoydbStore extends NoydbStore {
      * - `hydrate: ['invoices', 'clients']` — copies only named collections.
      *
      * Use cases:
-     * - Shared device: `await store.override('default', memory(), { hydrate: true })`
+     * - Shared device: `await store.override('default', toMemory(), { hydrate: true })`
      * - Restricted network: `store.override('blobs', localFile(...))`
      */
     override(route: OverrideTarget, store: NoydbStore, opts?: OverrideOptions): void | Promise<void>;

package/dist/{with-party/team/sync-active.d.ts → with-sync/active.d.ts}

@@ -29,5 +29,5 @@
  *
  * @public
  */
-import type { SyncStrategy } from './sync-strategy.js';
+import type { SyncStrategy } from './strategy.js';
 export declare function withSync(): SyncStrategy;

package/dist/{with-party/team/sync-credentials.d.ts → with-sync/credentials.d.ts}

@@ -36,15 +36,15 @@
  * Operators, viewers, and clients cannot call this API. The check is made
  * against the caller's keyring role at call time.
  */
-import type { NoydbStore } from '../../kernel/types.js';
-import type { UnlockedKeyring } from './keyring.js';
+import type { NoydbStore } from '../kernel/types.js';
+import type { UnlockedKeyring } from '../with-party/team/keyring.js';
 /**
  * The reserved collection name. Never collides with user collections.
  * Canonical definition lives in `reserved-secret-collections.ts` (shared with
  * the `vault.collection()` guard and grant DEK-propagation); re-exported here
  * for existing consumers.
  */
-export { SYNC_CREDENTIALS_COLLECTION } from './reserved-secret-collections.js';
+export { SYNC_CREDENTIALS_COLLECTION } from '../with-party/team/reserved-secret-collections.js';
 /**
  * An OAuth/auth token stored in `_sync_credentials`.
  *

package/dist/{with-party/team/sync.d.ts → with-sync/engine.d.ts}

@@ -1,8 +1,8 @@
-import type { NoydbStore, DirtyEntry, ConflictStrategy, CollectionConflictResolver, PushOptions, PullOptions, PushResult, PullResult, SyncStatus, SyncTargetRole } from '../../kernel/types.js';
-import { type PeriodPullSource } from './sync-period-scope.js';
-import type { NoydbEventEmitter } from '../../kernel/events.js';
-import type { SyncPolicy } from '../../kernel/sync-policy.js';
-import { SyncScheduler } from '../../kernel/sync-policy.js';
+import type { NoydbStore, DirtyEntry, ConflictStrategy, CollectionConflictResolver, PushOptions, PullOptions, PushResult, PullResult, SyncStatus, SyncTargetRole } from '../kernel/types.js';
+import { type PeriodPullSource } from './period-scope.js';
+import type { NoydbEventEmitter } from '../kernel/events.js';
+import type { SyncPolicy } from '../kernel/sync-policy.js';
+import { SyncScheduler } from '../kernel/sync-policy.js';
 /** #650 Task 4 (#647) — the declared reserved-lookup (`_dict_*`/`_lookup_*`) collection-name
  *  registry a `SyncEngine` enumerates on pull. Explicit, not a blanket underscore-glob — other
  *  `_`-prefixed namespaces keep their `loadAll`-skip semantics untouched. */

package/dist/{with-party/sync → with-sync}/index.d.ts

@@ -27,5 +27,7 @@
  * via `@noy-db/hub/team` for advanced consumers that construct them
  * directly. This subpath is the clean LTS factory entry point.
  */
-export { withSync } from '../team/sync-active.js';
-export type { SyncStrategy } from '../team/sync-strategy.js';
+export { withSync } from './active.js';
+export type { SyncStrategy } from './strategy.js';
+/** The un-opted-in stub for this service — exported so callers can compare against it (#844). */
+export { NO_SYNC } from './strategy.js';