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

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-IPLXE36W.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-CJ5KKU6X.js";
-import "./chunk-W4TCUGQR.js";
-import "./chunk-A4FXFAKF.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-VCTXU4AT.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-IPLXE36W.js.map
+//# sourceMappingURL=walk-H4YE52S2.js.map

package/dist/with/index.js

@@ -6,18 +6,18 @@ import {
   assertCanImport,
   canExport,
   canImport
-} from "../chunk-EWPOHMN2.js";
-import "../chunk-554KLAAN.js";
-import "../chunk-NCCBLYEB.js";
-import "../chunk-W4TCUGQR.js";
-import "../chunk-A4FXFAKF.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-VCTXU4AT.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/periods.d.ts

@@ -146,14 +146,7 @@
  */
 import type { NoydbStore, EncryptedEnvelope } from '../../kernel/types.js';
 import type { LedgerStore } from '../../with-commit/history/ledger/index.js';
-/** The reserved collection name holding closed-period metadata. */
-export declare const PERIODS_COLLECTION = "_periods";
-/** Sibling of {@link PERIODS_COLLECTION} holding freeze companions (#604). */
-export declare const PERIOD_FREEZES_COLLECTION = "_period_freezes";
-/** Sibling of {@link PERIODS_COLLECTION} holding archive companions (#613). */
-export declare const PERIOD_ARCHIVES_COLLECTION = "_period_archives";
-/** Sibling of {@link PERIODS_COLLECTION} holding target-purge companions (#615). */
-export declare const PERIOD_TARGET_PURGES_COLLECTION = "_period_target_purges";
+export { PERIODS_COLLECTION, PERIOD_FREEZES_COLLECTION, PERIOD_ARCHIVES_COLLECTION, PERIOD_TARGET_PURGES_COLLECTION, periodExclusiveUpperBound, } from './window.js';
 /**
  * Companion record recording that a closed period was frozen (its delete
  * markers physically purged). Stored in {@link PERIOD_FREEZES_COLLECTION},
@@ -196,14 +189,6 @@ export interface PeriodTargetPurgeRecord {
     readonly purgedBy: string;
     readonly targets: readonly TargetPurgeCount[];
 }
-/**
- * Exclusive upper bound for a period's delete-marker purge window (#604).
- * Markers carry no business date (empty body), only write-time `_ts`, so freeze
- * purges markers with `_ts < bound`, `bound` being the instant just after the
- * period's inclusive `endDate`: a date-only `endDate` seals through end-of-day
- * → next midnight; a full-timestamp `endDate` seals through that instant → +1ms.
- */
-export declare function periodExclusiveUpperBound(endDate: string): string;
 /**
  * Stored record for one closed or opened accounting period. One entry
  * per period, keyed by `name` in the reserved `_periods` collection.

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/with-audit/periods/window.d.ts

@@ -0,0 +1,16 @@
+/** The reserved collection name holding closed-period metadata. */
+export declare const PERIODS_COLLECTION = "_periods";
+/** Sibling of {@link PERIODS_COLLECTION} holding freeze companions (#604). */
+export declare const PERIOD_FREEZES_COLLECTION = "_period_freezes";
+/** Sibling of {@link PERIODS_COLLECTION} holding archive companions (#613). */
+export declare const PERIOD_ARCHIVES_COLLECTION = "_period_archives";
+/** Sibling of {@link PERIODS_COLLECTION} holding target-purge companions (#615). */
+export declare const PERIOD_TARGET_PURGES_COLLECTION = "_period_target_purges";
+/**
+ * Exclusive upper bound for a period's delete-marker purge window (#604).
+ * Markers carry no business date (empty body), only write-time `_ts`, so freeze
+ * purges markers with `_ts < bound`, `bound` being the instant just after the
+ * period's inclusive `endDate`: a date-only `endDate` seals through end-of-day
+ * → next midnight; a full-timestamp `endDate` seals through that instant → +1ms.
+ */
+export declare function periodExclusiveUpperBound(endDate: string): string;

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';
@@ -26,6 +26,17 @@ export { withCargo } from './active.js';
 export { NO_CARGO } from './strategy.js';
 export type { CargoStrategy } from './strategy.js';
 export { CargoNotEnabledError } from '../kernel/errors.js';
+export { extractPartition } from './extract-partition.js';
+export { walkClosure } from './walk-closure.js';
+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-party/team/sync-period-scope.d.ts

@@ -0,0 +1,78 @@
+/**
+ * #807 — period-scoped pull support for the `SyncEngine` (thin-client
+ * bootstrap: first sync pulls the current period + the period summaries;
+ * historical periods backfill on demand via `pull({ periods: ['<name>'] })`).
+ *
+ * ## Membership law
+ *
+ * The engine only ever sees ciphertext envelopes, so period membership at
+ * the sync tier is by write-time `_ts` against the closed periods' windows
+ * (`periodExclusiveUpperBound`) — the SAME store-tier law freeze (#604) and
+ * archive (#613) use, NOT the business-date (`dateField`) seal the write
+ * guard applies inside the trust boundary. A late-booked record (in-period
+ * business date, current write-time) therefore syncs with the current
+ * period — mirroring how it archives at the NEXT period's archive.
+ *
+ * Closed periods partition the timeline by their exclusive upper bounds:
+ * the earliest closed period's window is unbounded below (a close seals
+ * everything at-or-before its `endDate`), each later one starts at its
+ * predecessor's bound, and the CURRENT window is everything at-or-after
+ * the latest closed bound (everything, when no period was ever closed).
+ *
+ * ## What a period filter can never drop
+ *
+ * - **Period summaries** (`_periods` + freeze/archive/target-purge
+ *   companions) — the navigation index; always pulled in full, exempt from
+ *   every filter (`collections`, `periods`, `modifiedSince`).
+ * - **Delete markers and tombstones** — an erasure or delete must never be
+ *   skipped by partial sync (the #589/#590 law, mirroring the
+ *   `modifiedSince` exemption). This is what makes a device that never
+ *   pulled period P converge instead of resurrecting P's deleted records
+ *   when it later backfills.
+ * - **Reserved lookups** (`_dict_*`/`_lookup_*`) — vocabulary/config rows
+ *   are not period-partitioned data; their explicit pull loop is exempt.
+ *
+ * Push is NEVER period-filtered — `PushOptions` has no `periods` member at
+ * all; a thin client's writes always flow up in full.
+ */
+import type { EncryptedEnvelope } from '../../kernel/types.js';
+import { PERIODS_COLLECTION } from '../../with-audit/periods/window.js';
+export { PERIODS_COLLECTION };
+/**
+ * The reserved period-metadata collections a period-scoped pull always
+ * fetches first (phase 1, "summaries"): the hash-chained `_periods` index
+ * plus its freeze/archive/target-purge companions.
+ */
+export declare const PERIOD_SUMMARY_COLLECTIONS: readonly string[];
+/** The subset of a decrypted `PeriodRecord` the window computation needs. */
+export interface PeriodSyncRecord {
+    readonly name: string;
+    readonly kind: 'closed' | 'opened';
+    readonly endDate: string;
+}
+/**
+ * Vault-injected source of decrypted period records, wired via
+ * `SyncEngine.setPeriodPullSource` (same injection pattern as
+ * `setReservedLookupSource`). MUST re-read from the local store on every
+ * call — the engine invokes it right after the summaries phase applied
+ * freshly pulled `_periods` envelopes.
+ */
+export interface PeriodPullSource {
+    periods(): Promise<readonly PeriodSyncRecord[]>;
+}
+/** Validate the raw `PullOptions.periods` value (runtime shape only). */
+export declare function validatePeriodsOption(periods: unknown): asserts periods is readonly string[] | {
+    readonly current: true;
+};
+/**
+ * Resolve the selected `_ts` windows and return the pull-scope predicate:
+ * `true` = the envelope is in scope for this pull. Tombstones and delete
+ * markers are unconditionally in scope (see module doc).
+ *
+ * Throws `ValidationError` for a name that is not a closed period in the
+ * (freshly synced) `_periods` index — a typo'd backfill must fail loudly,
+ * never silently pull nothing.
+ */
+export declare function buildPeriodScope(option: readonly string[] | {
+    readonly current: true;
+}, records: readonly PeriodSyncRecord[]): (envelope: EncryptedEnvelope) => boolean;

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

@@ -1,4 +1,5 @@
 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';
@@ -66,6 +67,18 @@ export declare class SyncEngine {
     private reservedDictExpander?;
     /** Wire the reserved-dict expansion function (#653). Same injection pattern as `setPairExpander`. */
     setReservedDictExpander(expander: (names: readonly string[]) => readonly string[]): void;
+    /** #807: vault-injected source of decrypted period records — resolves the `_ts` windows a
+     *  `pull({ periods })` scopes to. Re-read AFTER the summaries phase, so a fresh device's
+     *  freshly pulled `_periods` index is what the windows are computed from. `undefined` on a
+     *  standalone engine that was never vault-attached (period-scoped pull then throws). */
+    private periodPullSource?;
+    /** Wire the period-window source (#807). Same injection pattern as `setReservedLookupSource`. */
+    setPeriodPullSource(source: PeriodPullSource): void;
+    /** #807: KPI accumulator `applyRemote` feeds during a period-scoped `pull()` — pointed at the
+     *  active phase's counters (summaries → records) and cleared before pull returns. Approximate
+     *  by design: a push interleaved mid-pull on the same engine would attribute its converge
+     *  applies to the open phase; the counters are a download-budget KPI, not an audit source. */
+    private pullByteSink;
     constructor(opts: {
         local: NoydbStore;
         remote: NoydbStore;

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