mindoodb 0.0.3 → 0.0.5

package/dist/core/appendonlystores/types.d.ts

@@ -69,10 +69,10 @@ export interface AwaitIndexReadyOptions {
 }
 /**
  * Cursor used by cursor-based store scans.
- * Entries are ordered by (createdAt, id) ascending.
+ * Entries are ordered by (receiptOrder, id) ascending.
  */
 export interface StoreScanCursor {
-    createdAt: number;
+    receiptOrder: number;
     id: string;
 }
 /**
@@ -104,6 +104,126 @@ export interface StoreIdBloomSummary {
     salt: string;
     bitsetBase64: string;
 }
+/**
+ * Options for causal document materialization planning.
+ * The planner computes which snapshot (if any) should be used and which
+ * change entries still need to be applied to reconstruct the latest state.
+ */
+export interface MaterializationPlanOptions {
+    /**
+     * If true, include planner diagnostics to aid debugging and tuning.
+     */
+    includeDiagnostics?: boolean;
+}
+/**
+ * Debug and observability details for materialization planning.
+ */
+export interface MaterializationPlanDiagnostics {
+    /**
+     * Current tip entries for the document (entries with no descendants in the
+     * doc graph among change/create/delete entries).
+     */
+    headEntryIds: string[];
+    /**
+     * Number of latest-state entries causally covered by the selected snapshot.
+     */
+    coveredLatestEntryCount: number;
+    /**
+     * Number of latest-state entries not covered by the selected snapshot.
+     */
+    uncoveredLatestEntryCount: number;
+}
+/**
+ * Store-level causal replay plan for one document.
+ */
+export interface DocumentMaterializationPlan {
+    /**
+     * Document ID this plan is for.
+     */
+    docId: string;
+    /**
+     * Snapshot entry to load first (if present).
+     */
+    snapshotEntryId: string | null;
+    /**
+     * Change entry IDs to apply after the snapshot (or from empty doc if no snapshot).
+     * The order is dependency-first (oldest first).
+     */
+    entryIdsToApply: string[];
+    /**
+     * Optional debug details.
+     */
+    diagnostics?: MaterializationPlanDiagnostics;
+}
+/**
+ * Batched materialization planning result.
+ */
+export interface DocumentMaterializationBatchPlan {
+    /**
+     * Per-document plans.
+     */
+    plans: DocumentMaterializationPlan[];
+}
+/**
+ * Byte-range request for attachment reads.
+ */
+export interface AttachmentReadPlanOptions {
+    /**
+     * Inclusive start byte within the plaintext attachment.
+     */
+    startByte: number;
+    /**
+     * Exclusive end byte within the plaintext attachment.
+     * Defaults to the attachment size.
+     */
+    endByteExclusive?: number;
+}
+/**
+ * One planned attachment chunk covering a plaintext byte window.
+ */
+export interface AttachmentReadPlanChunk {
+    /**
+     * Store entry ID of the chunk.
+     */
+    id: string;
+    /**
+     * Inclusive plaintext start byte of this chunk within the full attachment.
+     */
+    startByte: number;
+    /**
+     * Exclusive plaintext end byte of this chunk within the full attachment.
+     */
+    endByteExclusive: number;
+    /**
+     * Plaintext size of this chunk as stored in metadata.
+     */
+    originalSize: number;
+}
+/**
+ * Store-level plan for reading a plaintext attachment byte range.
+ */
+export interface AttachmentReadPlan {
+    /**
+     * Declared plaintext attachment size.
+     */
+    attachmentSize: number;
+    /**
+     * Inclusive requested start byte.
+     */
+    startByte: number;
+    /**
+     * Exclusive requested end byte.
+     */
+    endByteExclusive: number;
+    /**
+     * Ordered chunk plans needed to satisfy the read.
+     */
+    chunkPlans: AttachmentReadPlanChunk[];
+    /**
+     * Number of bytes to skip from the first planned chunk.
+     */
+    offsetInFirstChunk: number;
+}
 /**
  * Result of creating stores for a database.
  * Contains the document store and an optional separate attachment store.
@@ -184,6 +304,34 @@ export interface ContentAddressedStore {
      * @return A list of entries (may be shorter than input if some don't exist)
      */
     getEntries(ids: string[]): Promise<StoreEntry[]>;
+    /**
+     * Get metadata for a single entry without loading its encrypted payload.
+     *
+     * This is useful for dependency planning and attachment range access where
+     * callers only need dependency links, sizes, or timestamps before deciding
+     * which payload entries to fetch.
+     *
+     * @param id The entry ID to look up
+     * @return The entry metadata, or null if the entry does not exist
+     */
+    getEntryMetadata(id: string): Promise<StoreEntryMetadata | null>;
+    /**
+     * Optionally plan a plaintext attachment read range.
+     *
+     * Implementations may optimize metadata traversal (for example via batching,
+     * dependency pre-resolution, or caching) while callers still receive a
+     * backend-agnostic chunk plan.
+     *
+     * Custom stores do not need to implement this from scratch: core helper
+     * planners can compose existing methods like `getEntryMetadata()` and
+     * `resolveDependencies()`.
+     *
+     * @param lastChunkId The newest attachment chunk entry ID
+     * @param attachmentSize Declared plaintext attachment size
+     * @param options Requested plaintext byte window
+     * @return A read plan for the requested attachment bytes
+     */
+    planAttachmentReadByWalkingMetadata?(lastChunkId: string, attachmentSize: number, options: AttachmentReadPlanOptions): Promise<AttachmentReadPlan>;
     /**
      * Check which IDs from the provided list exist in this store.
      *
@@ -231,7 +379,7 @@ export interface ContentAddressedStore {
      * Cursor-based metadata scan.
      * Preferred for large stores to avoid known-id set exchange.
      *
-     * Ordering is deterministic: (createdAt ASC, id ASC).
+     * Ordering is deterministic: (receiptOrder ASC, id ASC).
      * Returned entries are strictly after `cursor`.
      */
     scanEntriesSince?(cursor: StoreScanCursor | null, limit?: number, filters?: StoreScanFilters): Promise<StoreScanResult>;
@@ -240,6 +388,17 @@ export interface ContentAddressedStore {
      * Callers must still perform exact reconciliation for correctness.
      */
     getIdBloomSummary?(): Promise<StoreIdBloomSummary>;
+    /**
+     * Plan causal materialization for a single document.
+     * This allows callers to fetch only required entries instead of scanning/applying
+     * full history every time.
+     */
+    planDocumentMaterialization(docId: string, options?: MaterializationPlanOptions): Promise<DocumentMaterializationPlan>;
+    /**
+     * Plan causal materialization for multiple documents in one call.
+     * Batch planning is important for high-latency network stores to reduce round trips.
+     */
+    planDocumentMaterializationBatch(docIds: string[], options?: MaterializationPlanOptions): Promise<DocumentMaterializationBatchPlan>;
     /**
      * Resolve the dependency chain starting from an entry ID.
      * Returns IDs in dependency order, traversing backward through dependencyIds.
@@ -289,5 +448,17 @@ export interface ContentAddressedStore {
      * Optional status API for metadata-segment compaction observability.
      */
     getCompactionStatus?(): Promise<StoreCompactionStatus>;
+    /**
+     * Optional unique fingerprint for local cache scoping.
+     * Must be stable across restarts and unique per store backend/location.
+     *
+     * Examples:
+     * - On-disk store: "disk:/data/myapp/contacts"
+     * - IndexedDB store: "idb:default/contacts"
+     * - Network store: "net:https://sync.example.com/contacts"
+     *
+     * If not implemented, BaseMindooDB falls back to getId().
+     */
+    getCacheIdentity?(): string;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/core/appendonlystores/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/appendonlystores/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/appendonlystores/types.ts"],"names":[],"mappings":"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"}

package/dist/core/cache/CacheManager.d.ts

@@ -0,0 +1,75 @@
+import { LocalCacheStore } from "./LocalCacheStore";
+import { Logger } from "../logging";
+/**
+ * Interface that cacheable consumers (BaseMindooDB, VirtualView) implement
+ * so the CacheManager can flush their dirty state.
+ */
+export interface ICacheable {
+    /**
+     * A unique key identifying this cacheable in the cache store.
+     * For BaseMindooDB: tenantId + "/" + store.getCacheIdentity()
+     * For VirtualView: viewId + "/" + version
+     */
+    getCachePrefix(): string;
+    /**
+     * Export the current dirty state to the cache store.
+     * Called by CacheManager during flush.
+     *
+     * @param store  The cache store to write to
+     * @returns The number of entries written
+     */
+    flushToCache(store: LocalCacheStore): Promise<number>;
+    /**
+     * Clear the dirty tracking state after a successful flush.
+     */
+    clearDirty(): void;
+    /**
+     * Whether this cacheable has any dirty state to flush.
+     */
+    hasDirtyState(): boolean;
+}
+export interface CacheManagerOptions {
+    /** Flush interval in milliseconds. Default: 5000 (5s) */
+    flushIntervalMs?: number;
+}
+/**
+ * Coordinates periodic cache persistence for all registered cacheables
+ * (databases, virtual views) within a tenant.
+ *
+ * Tracks dirty state and flushes periodically or on demand.
+ */
+export declare class CacheManager {
+    private store;
+    private cacheables;
+    private flushIntervalMs;
+    private timer;
+    private flushInProgress;
+    private disposed;
+    private logger;
+    constructor(store: LocalCacheStore, options?: CacheManagerOptions, logger?: Logger);
+    getStore(): LocalCacheStore;
+    /**
+     * Register a cacheable consumer. It will be included in periodic flushes.
+     */
+    register(cacheable: ICacheable): void;
+    /**
+     * Deregister a cacheable consumer (e.g. on db.close()).
+     * Triggers an immediate flush for this cacheable before removal.
+     */
+    deregister(cacheable: ICacheable): Promise<void>;
+    /**
+     * Notify the CacheManager that something changed.
+     * Schedules a flush if one is not already pending.
+     */
+    markDirty(): void;
+    private scheduleFlush;
+    /**
+     * Immediately flush all dirty cacheables.
+     */
+    flush(): Promise<void>;
+    /**
+     * Flush all pending state and stop the periodic timer.
+     */
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=CacheManager.d.ts.map

package/dist/core/cache/CacheManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheManager.d.ts","sourceRoot":"","sources":["../../../src/core/cache/CacheManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAoC,MAAM,YAAY,CAAC;AAEtE;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,cAAc,IAAI,MAAM,CAAC;IAEzB;;;;;;OAMG;IACH,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEtD;;OAEG;IACH,UAAU,IAAI,IAAI,CAAC;IAEnB;;OAEG;IACH,aAAa,IAAI,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAkB;IAC/B,OAAO,CAAC,UAAU,CAA8B;IAChD,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,MAAM,CAAS;gBAEX,KAAK,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,mBAAmB,EAAE,MAAM,CAAC,EAAE,MAAM;IAMlF,QAAQ,IAAI,eAAe;IAI3B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,UAAU,GAAG,IAAI;IAIrC;;;OAGG;IACG,UAAU,CAAC,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAYtD;;;OAGG;IACH,SAAS,IAAI,IAAI;IAKjB,OAAO,CAAC,aAAa;IAQrB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB5B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ/B"}

package/dist/core/cache/CacheManager.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheManager = void 0;
+const logging_1 = require("../logging");
+/**
+ * Coordinates periodic cache persistence for all registered cacheables
+ * (databases, virtual views) within a tenant.
+ *
+ * Tracks dirty state and flushes periodically or on demand.
+ */
+class CacheManager {
+    constructor(store, options, logger) {
+        this.cacheables = new Set();
+        this.timer = null;
+        this.flushInProgress = false;
+        this.disposed = false;
+        this.store = store;
+        this.flushIntervalMs = options?.flushIntervalMs ?? 5000;
+        this.logger = logger || new logging_1.MindooLogger((0, logging_1.getDefaultLogLevel)(), "CacheManager", true);
+    }
+    getStore() {
+        return this.store;
+    }
+    /**
+     * Register a cacheable consumer. It will be included in periodic flushes.
+     */
+    register(cacheable) {
+        this.cacheables.add(cacheable);
+    }
+    /**
+     * Deregister a cacheable consumer (e.g. on db.close()).
+     * Triggers an immediate flush for this cacheable before removal.
+     */
+    async deregister(cacheable) {
+        if (cacheable.hasDirtyState()) {
+            try {
+                await cacheable.flushToCache(this.store);
+                cacheable.clearDirty();
+            }
+            catch (e) {
+                this.logger.warn(`Failed to flush cache for ${cacheable.getCachePrefix()} on deregister: ${e}`);
+            }
+        }
+        this.cacheables.delete(cacheable);
+    }
+    /**
+     * Notify the CacheManager that something changed.
+     * Schedules a flush if one is not already pending.
+     */
+    markDirty() {
+        if (this.disposed)
+            return;
+        this.scheduleFlush();
+    }
+    scheduleFlush() {
+        if (this.timer !== null)
+            return;
+        this.timer = setTimeout(async () => {
+            this.timer = null;
+            await this.flush();
+        }, this.flushIntervalMs);
+    }
+    /**
+     * Immediately flush all dirty cacheables.
+     */
+    async flush() {
+        if (this.flushInProgress)
+            return;
+        this.flushInProgress = true;
+        try {
+            for (const cacheable of this.cacheables) {
+                if (!cacheable.hasDirtyState())
+                    continue;
+                try {
+                    const count = await cacheable.flushToCache(this.store);
+                    cacheable.clearDirty();
+                    this.logger.debug(`Flushed ${count} entries for ${cacheable.getCachePrefix()}`);
+                }
+                catch (e) {
+                    this.logger.warn(`Cache flush failed for ${cacheable.getCachePrefix()}: ${e}`);
+                }
+            }
+        }
+        finally {
+            this.flushInProgress = false;
+        }
+    }
+    /**
+     * Flush all pending state and stop the periodic timer.
+     */
+    async dispose() {
+        this.disposed = true;
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        await this.flush();
+    }
+}
+exports.CacheManager = CacheManager;
+//# sourceMappingURL=CacheManager.js.map

package/dist/core/cache/CacheManager.js.map

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

package/dist/core/cache/EncryptedLocalCacheStore.d.ts

@@ -0,0 +1,41 @@
+import { LocalCacheStore } from "./LocalCacheStore";
+import { CryptoAdapter } from "../crypto/CryptoAdapter";
+import { Logger } from "../logging";
+/**
+ * Transparent encryption wrapper around any {@link LocalCacheStore}.
+ *
+ * - Encrypts values on `put()`, decrypts on `get()`
+ * - Keys (type + id) are passed through unmodified
+ * - Uses AES-256-GCM with a key derived from the user's password via PBKDF2
+ * - If decryption fails (password changed, corruption) returns `null`
+ */
+export declare class EncryptedLocalCacheStore implements LocalCacheStore {
+    private inner;
+    private cryptoAdapter;
+    private derivedKey;
+    private keyPromise;
+    private logger;
+    /**
+     * @param inner        The underlying (plaintext) cache store
+     * @param userPassword The user's password used to derive the encryption key
+     * @param cryptoAdapter Platform-agnostic crypto interface
+     * @param logger       Optional logger
+     */
+    constructor(inner: LocalCacheStore, userPassword: string, cryptoAdapter: CryptoAdapter, logger?: Logger);
+    private deriveKey;
+    private getKey;
+    /**
+     * Ensure the Uint8Array owns its entire backing ArrayBuffer (byteOffset=0,
+     * byteLength=buffer.byteLength).  Some React Native crypto polyfills
+     * access `.buffer` directly, which would read wrong data for sub-views.
+     */
+    private static ensureOwnedBuffer;
+    private encrypt;
+    private decrypt;
+    get(type: string, id: string): Promise<Uint8Array | null>;
+    put(type: string, id: string, value: Uint8Array): Promise<void>;
+    delete(type: string, id: string): Promise<void>;
+    list(type: string): Promise<string[]>;
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=EncryptedLocalCacheStore.d.ts.map

package/dist/core/cache/EncryptedLocalCacheStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EncryptedLocalCacheStore.d.ts","sourceRoot":"","sources":["../../../src/core/cache/EncryptedLocalCacheStore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAExD,OAAO,EAAE,MAAM,EAAoC,MAAM,YAAY,CAAC;AAEtE;;;;;;;GAOG;AACH,qBAAa,wBAAyB,YAAW,eAAe;IAC9D,OAAO,CAAC,KAAK,CAAkB;IAC/B,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,UAAU,CAAmC;IACrD,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;;OAKG;gBAED,KAAK,EAAE,eAAe,EACtB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,aAAa,EAC5B,MAAM,CAAC,EAAE,MAAM;YAQH,SAAS;YAqCT,MAAM;IAKpB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;YASlB,OAAO;YAqBP,OAAO;IA6Bf,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAMzD,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/D,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAIrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/core/cache/EncryptedLocalCacheStore.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EncryptedLocalCacheStore = void 0;
+const pbkdf2Iterations_1 = require("../crypto/pbkdf2Iterations");
+const logging_1 = require("../logging");
+/**
+ * Transparent encryption wrapper around any {@link LocalCacheStore}.
+ *
+ * - Encrypts values on `put()`, decrypts on `get()`
+ * - Keys (type + id) are passed through unmodified
+ * - Uses AES-256-GCM with a key derived from the user's password via PBKDF2
+ * - If decryption fails (password changed, corruption) returns `null`
+ */
+class EncryptedLocalCacheStore {
+    /**
+     * @param inner        The underlying (plaintext) cache store
+     * @param userPassword The user's password used to derive the encryption key
+     * @param cryptoAdapter Platform-agnostic crypto interface
+     * @param logger       Optional logger
+     */
+    constructor(inner, userPassword, cryptoAdapter, logger) {
+        this.derivedKey = null;
+        this.keyPromise = null;
+        this.inner = inner;
+        this.cryptoAdapter = cryptoAdapter;
+        this.logger = logger || new logging_1.MindooLogger((0, logging_1.getDefaultLogLevel)(), "EncryptedLocalCacheStore", true);
+        this.keyPromise = this.deriveKey(userPassword);
+    }
+    async deriveKey(password) {
+        const subtle = this.cryptoAdapter.getSubtle();
+        const saltString = "mindoodb-cache-encryption:v1";
+        const salt = new TextEncoder().encode(saltString);
+        const passwordInput = new TextEncoder().encode(password);
+        const baseKey = await subtle.importKey("raw", passwordInput.buffer, "PBKDF2", false, ["deriveKey"]);
+        const iterations = (0, pbkdf2Iterations_1.resolvePbkdf2Iterations)(pbkdf2Iterations_1.DEFAULT_PBKDF2_ITERATIONS);
+        if (iterations !== pbkdf2Iterations_1.DEFAULT_PBKDF2_ITERATIONS) {
+            this.logger.warn(`Using overridden PBKDF2 iterations for cache key derivation: ${iterations}`);
+        }
+        const key = await subtle.deriveKey({
+            name: "PBKDF2",
+            salt: salt.buffer,
+            iterations,
+            hash: "SHA-256",
+        }, baseKey, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
+        this.derivedKey = key;
+        return key;
+    }
+    async getKey() {
+        if (this.derivedKey)
+            return this.derivedKey;
+        return this.keyPromise;
+    }
+    /**
+     * Ensure the Uint8Array owns its entire backing ArrayBuffer (byteOffset=0,
+     * byteLength=buffer.byteLength).  Some React Native crypto polyfills
+     * access `.buffer` directly, which would read wrong data for sub-views.
+     */
+    static ensureOwnedBuffer(arr) {
+        if (arr.byteOffset !== 0 || arr.byteLength !== arr.buffer.byteLength) {
+            const copy = new Uint8Array(arr.byteLength);
+            copy.set(arr);
+            return copy;
+        }
+        return arr;
+    }
+    async encrypt(plaintext) {
+        const subtle = this.cryptoAdapter.getSubtle();
+        const key = await this.getKey();
+        const iv = new Uint8Array(12);
+        this.cryptoAdapter.getRandomValues(iv);
+        const safeData = EncryptedLocalCacheStore.ensureOwnedBuffer(plaintext);
+        const ciphertext = await subtle.encrypt({ name: "AES-GCM", iv: iv.buffer, tagLength: 128 }, key, safeData.buffer);
+        // Format: IV (12 bytes) + ciphertext+tag (variable)
+        const result = new Uint8Array(12 + ciphertext.byteLength);
+        result.set(iv, 0);
+        result.set(new Uint8Array(ciphertext), 12);
+        return result;
+    }
+    async decrypt(data) {
+        if (data.length < 12 + 16) {
+            this.logger.warn("Encrypted cache entry too short, treating as corrupt");
+            return null;
+        }
+        try {
+            const subtle = this.cryptoAdapter.getSubtle();
+            const key = await this.getKey();
+            // .slice() creates copies with their own backing ArrayBuffer
+            const iv = data.slice(0, 12);
+            const ciphertext = data.slice(12);
+            const plaintext = await subtle.decrypt({ name: "AES-GCM", iv: iv.buffer, tagLength: 128 }, key, ciphertext.buffer);
+            return new Uint8Array(plaintext);
+        }
+        catch (e) {
+            this.logger.warn(`Cache decryption failed (password changed or data corrupt): ${e}`);
+            return null;
+        }
+    }
+    // --- LocalCacheStore interface ---
+    async get(type, id) {
+        const encrypted = await this.inner.get(type, id);
+        if (!encrypted)
+            return null;
+        return this.decrypt(encrypted);
+    }
+    async put(type, id, value) {
+        const encrypted = await this.encrypt(value);
+        return this.inner.put(type, id, encrypted);
+    }
+    async delete(type, id) {
+        return this.inner.delete(type, id);
+    }
+    async list(type) {
+        return this.inner.list(type);
+    }
+    async clear() {
+        return this.inner.clear();
+    }
+}
+exports.EncryptedLocalCacheStore = EncryptedLocalCacheStore;
+//# sourceMappingURL=EncryptedLocalCacheStore.js.map

package/dist/core/cache/EncryptedLocalCacheStore.js.map

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

package/dist/core/cache/LocalCacheStore.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A simple mutable key-value store for local cache data.
+ *
+ * Keys are structured as (type, id) pairs where:
+ * - `type` groups related entries (e.g. "db-meta", "doc", "vv")
+ * - `id` is caller-defined and may include tenant/store/doc scoping
+ *
+ * All values are opaque `Uint8Array`. Encryption is handled externally
+ * (e.g. by wrapping with {@link EncryptedLocalCacheStore}).
+ *
+ * One implementation per platform (Node.js filesystem, IndexedDB, MMKV),
+ * but the interface is open for custom implementations.
+ */
+export interface LocalCacheStore {
+    /**
+     * Retrieve a cached value.
+     * @returns The value, or `null` if not found.
+     */
+    get(type: string, id: string): Promise<Uint8Array | null>;
+    /**
+     * Store (or overwrite) a cached value.
+     */
+    put(type: string, id: string, value: Uint8Array): Promise<void>;
+    /**
+     * Delete a single cached value.
+     */
+    delete(type: string, id: string): Promise<void>;
+    /**
+     * List all ids stored under the given type.
+     */
+    list(type: string): Promise<string[]>;
+    /**
+     * Wipe all data from the cache store.
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Trivial in-memory implementation of {@link LocalCacheStore}.
+ * Useful for tests and as a reference implementation.
+ */
+export declare class InMemoryLocalCacheStore implements LocalCacheStore {
+    private data;
+    private toKey;
+    get(type: string, id: string): Promise<Uint8Array | null>;
+    put(type: string, id: string, value: Uint8Array): Promise<void>;
+    delete(type: string, id: string): Promise<void>;
+    list(type: string): Promise<string[]>;
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=LocalCacheStore.d.ts.map

package/dist/core/cache/LocalCacheStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalCacheStore.d.ts","sourceRoot":"","sources":["../../../src/core/cache/LocalCacheStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAE1D;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhE;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhD;;OAEG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEtC;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;GAGG;AACH,qBAAa,uBAAwB,YAAW,eAAe;IAC7D,OAAO,CAAC,IAAI,CAAsC;IAElD,OAAO,CAAC,KAAK;IAIP,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAIzD,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/D,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAWrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}