@interop/was-react 0.1.0

package/dist/storage/localStore.d.ts

@@ -0,0 +1,144 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * LocalStore: the always-on local encrypted replica. A GENERIC per-entity
+ * envelope store over an app's registered collections. Owns one RxDB
+ * (Dexie/IndexedDB) database holding one collection per entity on the shared
+ * `syncedDocSchema()`; every at-rest row is `{ id, updatedAt, version, data }`
+ * where `data` is the EDV envelope `{ id, sequence, jwe }` -- the server never
+ * sees plaintext.
+ *
+ * Two id planes: the logical entity `uuid` lives INSIDE the encrypted payload;
+ * the RxDB primary key is the opaque random EDV envelope id. An in-memory
+ * `uuid -> envelopeId` index (built during hydration) routes updates/deletes.
+ * Two timestamp planes: the row-level `updatedAt` is only the sync checkpoint;
+ * the payload's own `createdAt` / `updatedAt` (inside the ciphertext) drive
+ * domain sorting and LWW.
+ *
+ * Writes: create mints a fresh random envelope; update re-encrypts under the
+ * SAME envelope id with `sequence`+1 (the mutable-head model); delete is an RxDB
+ * soft-delete tombstone.
+ */
+import { type RxCollection, type RxStorage } from 'rxdb/plugins/core';
+import { type WasCollectionConfig } from '../config.js';
+import { type Json, type SyncedDoc } from '../sync/index.js';
+type EntityPayload = {
+    id: string;
+};
+/**
+ * The local encrypted store. Construct via {@link LocalStore.init}, which
+ * derives the per-collection ciphers from the master seed and opens RxDB.
+ */
+export declare class LocalStore {
+    private _db;
+    private _collections;
+    private _ciphers;
+    private _index;
+    private constructor();
+    /**
+     * Opens (or creates) the encrypted store: derives a per-collection KAK + cipher
+     * from the master seed and opens one RxDB collection per entity.
+     *
+     * @param options {object}
+     * @param options.seed {Uint8Array}   the 32-byte master seed
+     * @param options.collections {WasCollectionConfig[]}   the collection registry
+     *   (logical key to WAS collection id)
+     * @param [options.storage] {RxStorage<unknown, unknown>}   defaults to
+     *   Dexie/IndexedDB; injectable for tests
+     * @param [options.dbName] {string}   defaults to {@link DEFAULT_DB_NAME}
+     * @returns {Promise<LocalStore>}
+     */
+    static init({ seed, collections, storage, dbName }: {
+        seed: Uint8Array;
+        collections: WasCollectionConfig[];
+        storage?: RxStorage<unknown, unknown>;
+        dbName?: string;
+    }): Promise<LocalStore>;
+    private _collection;
+    private _cipher;
+    /**
+     * Builds (or rebuilds) the `uuid -> envelopeId` index for one collection by
+     * decrypting every live row. Returns the index map.
+     */
+    private _ensureIndex;
+    /**
+     * Encrypts `payload` into a fresh EDV envelope and inserts it as a new row.
+     *
+     * @param key {string}            the collection logical key
+     * @param payload {EntityPayload} the plaintext entity (carries its own uuid)
+     * @returns {Promise<void>}
+     */
+    insertEntity(key: string, payload: EntityPayload): Promise<void>;
+    /**
+     * Re-encrypts `payload` in place under its existing envelope id, advancing the
+     * envelope `sequence` (the mutable-head update). The row keeps its primary key;
+     * only `data` and the checkpoint `updatedAt` change.
+     *
+     * @param key {string}
+     * @param payload {EntityPayload}
+     * @returns {Promise<void>}
+     */
+    updateEntity(key: string, payload: EntityPayload): Promise<void>;
+    /**
+     * Tombstones the entity's row (RxDB soft delete) so the deletion replicates.
+     *
+     * @param key {string}
+     * @param uuid {string}   the logical entity uuid
+     * @returns {Promise<void>}
+     */
+    deleteEntity(key: string, uuid: string): Promise<void>;
+    /**
+     * Decrypts every live row of a collection into its plaintext payload, and
+     * (re)builds the `uuid -> envelopeId` index as a side effect of hydration.
+     *
+     * @param key {string}
+     * @returns {Promise<T[]>}
+     */
+    listEntities<T extends EntityPayload>(key: string): Promise<T[]>;
+    /**
+     * Decrypts a single EDV envelope into its plaintext payload, for per-doc
+     * reactive patching of a pulled remote change (without a whole-collection
+     * re-hydrate).
+     *
+     * @param key {string}
+     * @param envelope {Json}   the `data` field of the at-rest row
+     * @returns {Promise<T>}
+     */
+    decryptEnvelope<T extends EntityPayload>(key: string, envelope: Json): Promise<T>;
+    /**
+     * Records a `uuid -> envelopeId` mapping for a remotely-pulled row so a
+     * subsequent LOCAL edit of that entity can find its envelope. A no-op until
+     * the collection has been hydrated once (hydration builds the full index).
+     *
+     * @param key {string}
+     * @param uuid {string}
+     * @param envelopeId {string}
+     * @returns {void}
+     */
+    rememberEnvelope(key: string, uuid: string, envelopeId: string): void;
+    /**
+     * Forgets a `uuid -> envelopeId` mapping (a remotely-pulled tombstone).
+     *
+     * @param key {string}
+     * @param uuid {string}
+     * @returns {void}
+     */
+    forgetEnvelope(key: string, uuid: string): void;
+    /**
+     * The live RxDB collection handle, for reactive subscriptions and the sync
+     * controller.
+     *
+     * @param key {string}
+     * @returns {RxCollection<SyncedDoc>}
+     */
+    rxCollection(key: string): RxCollection<SyncedDoc>;
+    /**
+     * Closes the database (without removing data).
+     *
+     * @returns {Promise<void>}
+     */
+    close(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=localStore.d.ts.map

package/dist/storage/localStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localStore.d.ts","sourceRoot":"","sources":["../../src/storage/localStore.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAEL,KAAK,YAAY,EAEjB,KAAK,SAAS,EACf,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAA;AACxE,OAAO,EAIL,KAAK,IAAI,EACT,KAAK,SAAS,EAEf,MAAM,kBAAkB,CAAA;AAMzB,KAAK,aAAa,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAA;AAEnC;;;GAGG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,YAAY,CAAyC;IAC7D,OAAO,CAAC,QAAQ,CAA2B;IAE3C,OAAO,CAAC,MAAM,CAAqC;IAEnD,OAAO;IAeP;;;;;;;;;;;;OAYG;WACU,IAAI,CAAC,EAChB,IAAI,EACJ,WAAW,EACX,OAAO,EACP,MAAwB,EACzB,EAAE;QACD,IAAI,EAAE,UAAU,CAAA;QAChB,WAAW,EAAE,mBAAmB,EAAE,CAAA;QAClC,OAAO,CAAC,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACrC,MAAM,CAAC,EAAE,MAAM,CAAA;KAChB,GAAG,OAAO,CAAC,UAAU,CAAC;IAkDvB,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,OAAO;IAQf;;;OAGG;YACW,YAAY;IAsB1B;;;;;;OAMG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAetE;;;;;;;;OAQG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BtE;;;;;;OAMG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa5D;;;;;;OAMG;IACG,YAAY,CAAC,CAAC,SAAS,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAkBtE;;;;;;;;OAQG;IACG,eAAe,CAAC,CAAC,SAAS,aAAa,EAC3C,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,IAAI,GACb,OAAO,CAAC,CAAC,CAAC;IAIb;;;;;;;;;OASG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAIrE;;;;;;OAMG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAI/C;;;;;;OAMG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC;IAIlD;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/storage/localStore.js

@@ -0,0 +1,289 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * LocalStore: the always-on local encrypted replica. A GENERIC per-entity
+ * envelope store over an app's registered collections. Owns one RxDB
+ * (Dexie/IndexedDB) database holding one collection per entity on the shared
+ * `syncedDocSchema()`; every at-rest row is `{ id, updatedAt, version, data }`
+ * where `data` is the EDV envelope `{ id, sequence, jwe }` -- the server never
+ * sees plaintext.
+ *
+ * Two id planes: the logical entity `uuid` lives INSIDE the encrypted payload;
+ * the RxDB primary key is the opaque random EDV envelope id. An in-memory
+ * `uuid -> envelopeId` index (built during hydration) routes updates/deletes.
+ * Two timestamp planes: the row-level `updatedAt` is only the sync checkpoint;
+ * the payload's own `createdAt` / `updatedAt` (inside the ciphertext) drive
+ * domain sorting and LWW.
+ *
+ * Writes: create mints a fresh random envelope; update re-encrypts under the
+ * SAME envelope id with `sequence`+1 (the mutable-head model); delete is an RxDB
+ * soft-delete tombstone.
+ */
+import { createRxDatabase } from 'rxdb/plugins/core';
+import { getRxStorageDexie } from 'rxdb/plugins/storage-dexie';
+import { DEFAULT_DB_NAME } from '../config.js';
+import { syncedDocSchema, createDocCipher, makeLwwConflictHandler } from '../sync/index.js';
+import { deriveCollectionKeys } from '../identity/agents.js';
+/**
+ * The local encrypted store. Construct via {@link LocalStore.init}, which
+ * derives the per-collection ciphers from the master seed and opens RxDB.
+ */
+export class LocalStore {
+    _db;
+    _collections;
+    _ciphers;
+    // Per-collection logical-uuid -> envelope (RxDB primary key) index.
+    _index;
+    constructor({ db, collections, ciphers }) {
+        this._db = db;
+        this._collections = collections;
+        this._ciphers = ciphers;
+        this._index = {};
+    }
+    /**
+     * Opens (or creates) the encrypted store: derives a per-collection KAK + cipher
+     * from the master seed and opens one RxDB collection per entity.
+     *
+     * @param options {object}
+     * @param options.seed {Uint8Array}   the 32-byte master seed
+     * @param options.collections {WasCollectionConfig[]}   the collection registry
+     *   (logical key to WAS collection id)
+     * @param [options.storage] {RxStorage<unknown, unknown>}   defaults to
+     *   Dexie/IndexedDB; injectable for tests
+     * @param [options.dbName] {string}   defaults to {@link DEFAULT_DB_NAME}
+     * @returns {Promise<LocalStore>}
+     */
+    static async init({ seed, collections, storage, dbName = DEFAULT_DB_NAME }) {
+        const ciphers = {};
+        for (const { key, id } of collections) {
+            const { keyAgreementKey, keyResolver } = await deriveCollectionKeys({
+                seed,
+                collectionId: id
+            });
+            ciphers[key] = await createDocCipher({
+                keyAgreementKey,
+                keyResolver,
+                collectionId: id
+            });
+        }
+        const db = await createRxDatabase({
+            name: dbName,
+            storage: storage ?? getRxStorageDexie(),
+            closeDuplicates: true,
+            // Single-tab: RxDB gates replication on leadership under multiInstance;
+            // multi-tab is deferred, so replicate directly in this tab.
+            multiInstance: false
+        });
+        // Each collection gets an LWW conflict handler bound to its own cipher, so
+        // a 412 push conflict (concurrent multi-device edit of the same mutable
+        // head) is settled by decrypting both sides and comparing payload
+        // `updatedAt` (deviceId tiebreak) rather than RxDB's default master-wins.
+        const collectionsConfig = Object.fromEntries(collections.map(({ key }) => {
+            const cipher = ciphers[key];
+            if (!cipher) {
+                throw new Error(`No cipher for collection "${key}".`);
+            }
+            return [
+                key,
+                {
+                    schema: syncedDocSchema(),
+                    conflictHandler: makeLwwConflictHandler(envelope => cipher.decrypt({ envelope }))
+                }
+            ];
+        }));
+        const collectionsMap = (await db.addCollections(collectionsConfig));
+        return new LocalStore({ db, collections: collectionsMap, ciphers });
+    }
+    _collection(key) {
+        const collection = this._collections[key];
+        if (!collection) {
+            throw new Error(`Unknown collection "${key}".`);
+        }
+        return collection;
+    }
+    _cipher(key) {
+        const cipher = this._ciphers[key];
+        if (!cipher) {
+            throw new Error(`No cipher for collection "${key}".`);
+        }
+        return cipher;
+    }
+    /**
+     * Builds (or rebuilds) the `uuid -> envelopeId` index for one collection by
+     * decrypting every live row. Returns the index map.
+     */
+    async _ensureIndex(key) {
+        const existing = this._index[key];
+        if (existing) {
+            return existing;
+        }
+        const index = new Map();
+        const cipher = this._cipher(key);
+        const docs = await this._collection(key).find().exec();
+        for (const doc of docs) {
+            const { id: envelopeId, data } = doc.toMutableJSON();
+            if (data === undefined) {
+                continue;
+            }
+            const payload = (await cipher.decrypt({
+                envelope: data
+            }));
+            index.set(payload.id, envelopeId);
+        }
+        this._index[key] = index;
+        return index;
+    }
+    /**
+     * Encrypts `payload` into a fresh EDV envelope and inserts it as a new row.
+     *
+     * @param key {string}            the collection logical key
+     * @param payload {EntityPayload} the plaintext entity (carries its own uuid)
+     * @returns {Promise<void>}
+     */
+    async insertEntity(key, payload) {
+        const cipher = this._cipher(key);
+        const { id: envelopeId, envelope } = await cipher.encrypt({
+            data: payload
+        });
+        await this._collection(key).insert({
+            id: envelopeId,
+            updatedAt: new Date().toISOString(),
+            version: 0,
+            data: envelope
+        });
+        const index = await this._ensureIndex(key);
+        index.set(payload.id, envelopeId);
+    }
+    /**
+     * Re-encrypts `payload` in place under its existing envelope id, advancing the
+     * envelope `sequence` (the mutable-head update). The row keeps its primary key;
+     * only `data` and the checkpoint `updatedAt` change.
+     *
+     * @param key {string}
+     * @param payload {EntityPayload}
+     * @returns {Promise<void>}
+     */
+    async updateEntity(key, payload) {
+        const index = await this._ensureIndex(key);
+        const envelopeId = index.get(payload.id);
+        if (!envelopeId) {
+            throw new Error(`Cannot update: no envelope for entity "${payload.id}" in "${key}".`);
+        }
+        const doc = await this._collection(key).findOne(envelopeId).exec();
+        if (!doc) {
+            throw new Error(`Cannot update: row "${envelopeId}" is gone in "${key}".`);
+        }
+        const current = doc.toMutableJSON().data;
+        if (current === undefined) {
+            throw new Error(`Cannot update: row "${envelopeId}" has no envelope.`);
+        }
+        const cipher = this._cipher(key);
+        const { envelope } = await cipher.encryptUpdate({
+            id: envelopeId,
+            data: payload,
+            current
+        });
+        await doc.incrementalPatch({
+            data: envelope,
+            updatedAt: new Date().toISOString()
+        });
+    }
+    /**
+     * Tombstones the entity's row (RxDB soft delete) so the deletion replicates.
+     *
+     * @param key {string}
+     * @param uuid {string}   the logical entity uuid
+     * @returns {Promise<void>}
+     */
+    async deleteEntity(key, uuid) {
+        const index = await this._ensureIndex(key);
+        const envelopeId = index.get(uuid);
+        if (!envelopeId) {
+            return;
+        }
+        const doc = await this._collection(key).findOne(envelopeId).exec();
+        if (doc) {
+            await doc.remove();
+        }
+        index.delete(uuid);
+    }
+    /**
+     * Decrypts every live row of a collection into its plaintext payload, and
+     * (re)builds the `uuid -> envelopeId` index as a side effect of hydration.
+     *
+     * @param key {string}
+     * @returns {Promise<T[]>}
+     */
+    async listEntities(key) {
+        const cipher = this._cipher(key);
+        const index = new Map();
+        const docs = await this._collection(key).find().exec();
+        const payloads = [];
+        for (const doc of docs) {
+            const { id: envelopeId, data } = doc.toMutableJSON();
+            if (data === undefined) {
+                continue;
+            }
+            const payload = (await cipher.decrypt({ envelope: data }));
+            index.set(payload.id, envelopeId);
+            payloads.push(payload);
+        }
+        this._index[key] = index;
+        return payloads;
+    }
+    /**
+     * Decrypts a single EDV envelope into its plaintext payload, for per-doc
+     * reactive patching of a pulled remote change (without a whole-collection
+     * re-hydrate).
+     *
+     * @param key {string}
+     * @param envelope {Json}   the `data` field of the at-rest row
+     * @returns {Promise<T>}
+     */
+    async decryptEnvelope(key, envelope) {
+        return (await this._cipher(key).decrypt({ envelope }));
+    }
+    /**
+     * Records a `uuid -> envelopeId` mapping for a remotely-pulled row so a
+     * subsequent LOCAL edit of that entity can find its envelope. A no-op until
+     * the collection has been hydrated once (hydration builds the full index).
+     *
+     * @param key {string}
+     * @param uuid {string}
+     * @param envelopeId {string}
+     * @returns {void}
+     */
+    rememberEnvelope(key, uuid, envelopeId) {
+        this._index[key]?.set(uuid, envelopeId);
+    }
+    /**
+     * Forgets a `uuid -> envelopeId` mapping (a remotely-pulled tombstone).
+     *
+     * @param key {string}
+     * @param uuid {string}
+     * @returns {void}
+     */
+    forgetEnvelope(key, uuid) {
+        this._index[key]?.delete(uuid);
+    }
+    /**
+     * The live RxDB collection handle, for reactive subscriptions and the sync
+     * controller.
+     *
+     * @param key {string}
+     * @returns {RxCollection<SyncedDoc>}
+     */
+    rxCollection(key) {
+        return this._collection(key);
+    }
+    /**
+     * Closes the database (without removing data).
+     *
+     * @returns {Promise<void>}
+     */
+    async close() {
+        await this._db.close();
+    }
+}
+//# sourceMappingURL=localStore.js.map

package/dist/storage/localStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"localStore.js","sourceRoot":"","sources":["../../src/storage/localStore.ts"],"names":[],"mappings":"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"}

package/dist/storage/rehydrate.d.ts

@@ -0,0 +1,56 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The hydration MECHANISM: the per-collection re-hydrate hooks (decrypt the
+ * localStore rows into the app's stores) plus the debounced remote-change
+ * scheduler used by every sync entry point. Generic over an injected
+ * {@link StoreRegistry} -- the app supplies the concrete per-collection
+ * handlers; nothing here knows the domain entities.
+ */
+import type { Json } from '../sync/index.js';
+import type { StoreRegistry } from '../config.js';
+/**
+ * Hydrates every registered store from the (already opened) localStore.
+ *
+ * @param registry {StoreRegistry}
+ * @returns {Promise<void>}
+ */
+export declare function hydrateAll(registry: StoreRegistry): Promise<void>;
+/**
+ * Empties every registered store (logout).
+ *
+ * @param registry {StoreRegistry}
+ * @returns {void}
+ */
+export declare function clearAllEntityStores(registry: StoreRegistry): void;
+/**
+ * Patches ONE store from a single RxDB change event (per-doc, no whole-collection
+ * re-hydrate): decrypt the changed envelope, then upsert the payload (INSERT /
+ * UPDATE, including conflict-resolved rows) or drop it (DELETE / tombstone). The
+ * `uuid -> envelopeId` index is kept in step so a later local edit of a
+ * remotely-created doc still finds its envelope. Falls back to a debounced
+ * whole-collection re-hydrate if the envelope is missing or fails to decrypt.
+ *
+ * @param registry {StoreRegistry}
+ * @param collectionKey {string}
+ * @param event {object}   an RxDB change event (operation + documentData)
+ * @returns {Promise<void>}
+ */
+export declare function patchFromChange(registry: StoreRegistry, collectionKey: string, event: {
+    operation: string;
+    documentData?: {
+        id: string;
+        data?: Json;
+        _deleted?: boolean;
+    };
+}): Promise<void>;
+/**
+ * Schedules a debounced re-hydrate of one collection's store after a pull.
+ *
+ * @param registry {StoreRegistry}
+ * @param collectionKey {string}
+ * @returns {void}
+ */
+export declare function scheduleRehydrate(registry: StoreRegistry, collectionKey: string): void;
+//# sourceMappingURL=rehydrate.d.ts.map

package/dist/storage/rehydrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rehydrate.d.ts","sourceRoot":"","sources":["../../src/storage/rehydrate.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAGjD;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAIlE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,aAAa,EACvB,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE;IACL,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,IAAI,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;CAC/D,GACA,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAKD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,aAAa,EACvB,aAAa,EAAE,MAAM,GACpB,IAAI,CAgBN"}

package/dist/storage/rehydrate.js

@@ -0,0 +1,87 @@
+import { requireStore } from './storageManager.js';
+/**
+ * Hydrates every registered store from the (already opened) localStore.
+ *
+ * @param registry {StoreRegistry}
+ * @returns {Promise<void>}
+ */
+export async function hydrateAll(registry) {
+    await Promise.all(Object.values(registry).map(entry => entry.hydrate()));
+}
+/**
+ * Empties every registered store (logout).
+ *
+ * @param registry {StoreRegistry}
+ * @returns {void}
+ */
+export function clearAllEntityStores(registry) {
+    for (const entry of Object.values(registry)) {
+        entry.clear();
+    }
+}
+/**
+ * Patches ONE store from a single RxDB change event (per-doc, no whole-collection
+ * re-hydrate): decrypt the changed envelope, then upsert the payload (INSERT /
+ * UPDATE, including conflict-resolved rows) or drop it (DELETE / tombstone). The
+ * `uuid -> envelopeId` index is kept in step so a later local edit of a
+ * remotely-created doc still finds its envelope. Falls back to a debounced
+ * whole-collection re-hydrate if the envelope is missing or fails to decrypt.
+ *
+ * @param registry {StoreRegistry}
+ * @param collectionKey {string}
+ * @param event {object}   an RxDB change event (operation + documentData)
+ * @returns {Promise<void>}
+ */
+export async function patchFromChange(registry, collectionKey, event) {
+    const entry = registry[collectionKey];
+    if (!entry) {
+        return;
+    }
+    const row = event.documentData;
+    const envelope = row?.data;
+    const deleted = event.operation === 'DELETE' || row?._deleted === true;
+    if (!row || envelope === undefined) {
+        scheduleRehydrate(registry, collectionKey);
+        return;
+    }
+    let payload;
+    try {
+        payload = await requireStore().decryptEnvelope(collectionKey, envelope);
+    }
+    catch {
+        scheduleRehydrate(registry, collectionKey);
+        return;
+    }
+    if (deleted) {
+        requireStore().forgetEnvelope(collectionKey, payload.id);
+        entry.drop(payload.id);
+    }
+    else {
+        requireStore().rememberEnvelope(collectionKey, payload.id, row.id);
+        entry.upsert(payload);
+    }
+}
+/** Per-collection debounce timers coalescing a pull burst into one hydrate. */
+const rehydrateTimers = new Map();
+/**
+ * Schedules a debounced re-hydrate of one collection's store after a pull.
+ *
+ * @param registry {StoreRegistry}
+ * @param collectionKey {string}
+ * @returns {void}
+ */
+export function scheduleRehydrate(registry, collectionKey) {
+    const entry = registry[collectionKey];
+    if (!entry) {
+        return;
+    }
+    const existing = rehydrateTimers.get(collectionKey);
+    if (existing) {
+        clearTimeout(existing);
+    }
+    rehydrateTimers.set(collectionKey, setTimeout(() => {
+        rehydrateTimers.delete(collectionKey);
+        void entry.hydrate();
+    }, 50));
+}
+//# sourceMappingURL=rehydrate.js.map

package/dist/storage/rehydrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rehydrate.js","sourceRoot":"","sources":["../../src/storage/rehydrate.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAElD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAAuB;IACtD,MAAM,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;AAC1E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAuB;IAC1D,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5C,KAAK,CAAC,KAAK,EAAE,CAAA;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,QAAuB,EACvB,aAAqB,EACrB,KAGC;IAED,MAAM,KAAK,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAA;IACrC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAM;IACR,CAAC;IACD,MAAM,GAAG,GAAG,KAAK,CAAC,YAAY,CAAA;IAC9B,MAAM,QAAQ,GAAG,GAAG,EAAE,IAAI,CAAA;IAC1B,MAAM,OAAO,GAAG,KAAK,CAAC,SAAS,KAAK,QAAQ,IAAI,GAAG,EAAE,QAAQ,KAAK,IAAI,CAAA;IACtE,IAAI,CAAC,GAAG,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QACnC,iBAAiB,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAA;QAC1C,OAAM;IACR,CAAC;IACD,IAAI,OAAuB,CAAA;IAC3B,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,YAAY,EAAE,CAAC,eAAe,CAC5C,aAAa,EACb,QAAQ,CACT,CAAA;IACH,CAAC;IAAC,MAAM,CAAC;QACP,iBAAiB,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAA;QAC1C,OAAM;IACR,CAAC;IACD,IAAI,OAAO,EAAE,CAAC;QACZ,YAAY,EAAE,CAAC,cAAc,CAAC,aAAa,EAAE,OAAO,CAAC,EAAE,CAAC,CAAA;QACxD,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;IACxB,CAAC;SAAM,CAAC;QACN,YAAY,EAAE,CAAC,gBAAgB,CAAC,aAAa,EAAE,OAAO,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,CAAA;QAClE,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IACvB,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,MAAM,eAAe,GAAG,IAAI,GAAG,EAAyC,CAAA;AAExE;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAuB,EACvB,aAAqB;IAErB,MAAM,KAAK,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAA;IACrC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAM;IACR,CAAC;IACD,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,aAAa,CAAC,CAAA;IACnD,IAAI,QAAQ,EAAE,CAAC;QACb,YAAY,CAAC,QAAQ,CAAC,CAAA;IACxB,CAAC;IACD,eAAe,CAAC,GAAG,CACjB,aAAa,EACb,UAAU,CAAC,GAAG,EAAE;QACd,eAAe,CAAC,MAAM,CAAC,aAAa,CAAC,CAAA;QACrC,KAAK,KAAK,CAAC,OAAO,EAAE,CAAA;IACtB,CAAC,EAAE,EAAE,CAAC,CACP,CAAA;AACH,CAAC"}

package/dist/storage/rehydrate.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=rehydrate.test.d.ts.map

package/dist/storage/rehydrate.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rehydrate.test.d.ts","sourceRoot":"","sources":["../../src/storage/rehydrate.test.ts"],"names":[],"mappings":""}