mindoodb 0.0.3 → 0.0.4

package/dist/core/appendonlystores/MaterializationPlanner.js

@@ -0,0 +1,325 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeDocumentMaterializationPlan = computeDocumentMaterializationPlan;
+exports.computeBatchMaterializationPlan = computeBatchMaterializationPlan;
+/**
+ * Shared, metadata-only planner for causal document materialization.
+ *
+ * Why this exists:
+ * - local and remote stores need the same causal replay behavior
+ * - planner must work without decrypting payloads
+ * - replay order must be deterministic across runs
+ *
+ * Core invariant:
+ * - `entryIdsToApply` contains exactly the replay entries needed to reconstruct
+ *   latest state that are not already covered by the selected snapshot.
+ */
+const DOC_REPLAY_TYPES = new Set(["doc_create", "doc_change", "doc_delete"]);
+/**
+ * Returns true for entry types that can influence Automerge latest state replay.
+ */
+function isReplayEntry(meta) {
+    return DOC_REPLAY_TYPES.has(meta.entryType);
+}
+/**
+ * Computes latest-state heads and all replay entries causally reachable from them.
+ *
+ * `latestReachable` intentionally excludes unrelated historical branches that are
+ * not ancestors of current heads, so coverage/replay decisions only operate on
+ * data needed for latest state materialization.
+ */
+function buildLatestStateReachability(replayEntries) {
+    const byId = new Map();
+    const referenced = new Set();
+    for (const entry of replayEntries) {
+        byId.set(entry.id, entry);
+    }
+    for (const entry of replayEntries) {
+        for (const depId of entry.dependencyIds) {
+            if (byId.has(depId)) {
+                referenced.add(depId);
+            }
+        }
+    }
+    // Heads are entries that are not referenced as dependencies by any other replay entry.
+    const latestHeads = replayEntries
+        .filter((e) => !referenced.has(e.id))
+        .map((e) => e.id);
+    const latestReachable = new Set();
+    const stack = [...latestHeads];
+    while (stack.length > 0) {
+        const id = stack.pop();
+        if (latestReachable.has(id)) {
+            continue;
+        }
+        latestReachable.add(id);
+        const entry = byId.get(id);
+        if (!entry) {
+            continue;
+        }
+        for (const depId of entry.dependencyIds) {
+            if (byId.has(depId) && !latestReachable.has(depId)) {
+                stack.push(depId);
+            }
+        }
+    }
+    return { latestHeads, latestReachable };
+}
+/**
+ * Computes replay entries covered by the given snapshot.
+ *
+ * Coverage roots are chosen in this order:
+ * 1) explicit `snapshotHeadEntryIds` (preferred; most accurate)
+ * 2) snapshot `dependencyIds` (compatibility fallback)
+ */
+function coveredBySnapshot(snapshot, replayById) {
+    if (!snapshot) {
+        return new Set();
+    }
+    const roots = snapshot.snapshotHeadEntryIds && snapshot.snapshotHeadEntryIds.length > 0
+        ? snapshot.snapshotHeadEntryIds
+        : snapshot.dependencyIds;
+    const covered = new Set();
+    const stack = [...roots];
+    while (stack.length > 0) {
+        const id = stack.pop();
+        if (covered.has(id)) {
+            continue;
+        }
+        const entry = replayById.get(id);
+        if (!entry) {
+            continue;
+        }
+        covered.add(id);
+        for (const depId of entry.dependencyIds) {
+            if (!covered.has(depId)) {
+                stack.push(depId);
+            }
+        }
+    }
+    return covered;
+}
+/**
+ * Produces a stable, dependency-first ordering of replay entries using
+ * Kahn's algorithm for topological sorting.
+ *
+ * The caller passes a set of entry IDs that need to be replayed (the
+ * "uncovered" set from {@link computeDocumentMaterializationPlan}) and the
+ * full metadata map so the function can inspect each entry's
+ * `dependencyIds`.  The result is an array where every entry appears
+ * *after* all of its causal predecessors, which is the order
+ * `Automerge.applyChanges` requires to apply changes correctly.
+ *
+ * **Why Kahn's algorithm?**  It processes nodes in BFS order starting from
+ * roots (entries with no in-set dependencies), decrementing the in-degree
+ * of each dependent as its predecessors are emitted.  This naturally
+ * produces a valid topological order for any DAG.
+ *
+ * **Determinism:** When multiple entries become ready at the same time
+ * (in-degree drops to zero simultaneously), the queue is sorted
+ * lexicographically before the next dequeue.  This guarantees the same
+ * output regardless of `Set` or `Map` iteration order, which can vary
+ * across JavaScript engines and process runs.
+ *
+ * **Cycle safety:** In a well-formed Automerge DAG, cycles are impossible.
+ * However, if corrupted metadata somehow introduces a cycle, the algorithm
+ * detects it (ordered.length < ids.size) and falls back to a simple
+ * lexicographic sort so the caller still receives a complete list rather
+ * than a partial one.
+ *
+ * @param ids        The entry IDs to sort (typically the uncovered set).
+ * @param replayById Lookup map from entry ID to its metadata, used to
+ *                   read `dependencyIds` for graph edges.
+ * @returns Entry IDs in dependency-first order suitable for sequential
+ *          application to an Automerge document.
+ */
+function topologicalByDependencies(ids, replayById) {
+    // ── Build the in-degree and reverse-adjacency structures ──────────
+    // `indegree`   — for each id, how many of its dependencies are also in `ids`
+    // `dependents` — for each id, which other ids in the set depend on it
+    const indegree = new Map();
+    const dependents = new Map();
+    for (const id of ids) {
+        indegree.set(id, 0);
+        dependents.set(id, []);
+    }
+    for (const id of ids) {
+        const entry = replayById.get(id);
+        if (!entry) {
+            continue;
+        }
+        for (const depId of entry.dependencyIds) {
+            if (!ids.has(depId)) {
+                // Dependency is outside the uncovered set (already covered by
+                // the snapshot or not part of the latest-state DAG) — skip it.
+                continue;
+            }
+            indegree.set(id, (indegree.get(id) || 0) + 1);
+            dependents.get(depId).push(id);
+        }
+    }
+    // ── Kahn's BFS ────────────────────────────────────────────────────
+    // Seed the queue with root entries (in-degree 0 within the set).
+    const queue = Array.from(ids).filter((id) => (indegree.get(id) || 0) === 0);
+    queue.sort();
+    const ordered = [];
+    while (queue.length > 0) {
+        const id = queue.shift();
+        ordered.push(id);
+        for (const dep of dependents.get(id) || []) {
+            const next = (indegree.get(dep) || 0) - 1;
+            indegree.set(dep, next);
+            if (next === 0) {
+                queue.push(dep);
+            }
+        }
+        // Re-sort after adding newly ready entries to maintain determinism.
+        queue.sort();
+    }
+    // ── Cycle fallback ────────────────────────────────────────────────
+    if (ordered.length !== ids.size) {
+        return Array.from(ids).sort();
+    }
+    return ordered;
+}
+/**
+ * Computes a causal materialization plan for one document.
+ *
+ * Given all store entries for a document, this function answers two questions:
+ *
+ * 1. **Which snapshot should we load first?**
+ *    The planner evaluates every `doc_snapshot` entry and selects the one whose
+ *    causal coverage overlaps the most with the entries needed for the latest
+ *    document state.  A snapshot that covers 90% of the DAG means only 10%
+ *    of entries need to be replayed — a large win for documents with long
+ *    histories.  When two snapshots cover the same number of latest-state
+ *    entries, the newer one (by `createdAt`) wins as a deterministic
+ *    tie-breaker.  Correctness never depends on timestamps.
+ *
+ * 2. **Which change entries must be replayed on top of that snapshot?**
+ *    Every entry in the latest-state DAG that is *not* causally covered by
+ *    the selected snapshot is collected and sorted in dependency-first
+ *    (topological) order.  This is the minimal set of Automerge changes
+ *    the caller must decrypt and apply to reach the current document state.
+ *
+ * Snapshot selection strategy:
+ * - Choose the snapshot with maximal overlap against `latestReachable`.
+ * - Break equal-coverage ties by newer `createdAt` (optimization only).
+ * - If no snapshots exist, all replay entries are returned (full rebuild).
+ *
+ * Attachment entries (`attachment_chunk`) are never included — the planner
+ * operates exclusively on `doc_create`, `doc_change`, and `doc_delete`
+ * entries (the types tracked by `DOC_REPLAY_TYPES`).
+ *
+ * @param docId            The document to plan for.
+ * @param allEntriesForDoc Every entry metadata record for this document,
+ *                         including snapshots and attachments (attachments
+ *                         are filtered out internally).
+ * @param options          Pass `{ includeDiagnostics: true }` to populate the
+ *                         `diagnostics` field with head IDs and coverage counts.
+ * @returns A plan containing the snapshot to load (if any) and the ordered
+ *          list of entry IDs to apply afterwards.
+ */
+function computeDocumentMaterializationPlan(docId, allEntriesForDoc, options) {
+    // ── Step 1: Partition entries ──────────────────────────────────────
+    // Replay entries are the doc-lifecycle entries (create/change/delete) that
+    // form the Automerge DAG.  Snapshots are evaluated separately as candidate
+    // starting points.
+    const replayEntries = allEntriesForDoc.filter(isReplayEntry);
+    const replayById = new Map(replayEntries.map((e) => [e.id, e]));
+    const snapshots = allEntriesForDoc.filter((e) => e.entryType === "doc_snapshot");
+    // ── Step 2: Handle empty replay set ─────────────────────────────────
+    // After a dense sync the local store may contain only a snapshot with no
+    // individual change entries.  In that case select the newest snapshot so
+    // the caller can still load the document state.
+    if (replayEntries.length === 0) {
+        if (snapshots.length > 0) {
+            const best = snapshots.reduce((a, b) => (b.createdAt > a.createdAt ? b : a));
+            return {
+                docId,
+                snapshotEntryId: best.id,
+                entryIdsToApply: [],
+                diagnostics: options?.includeDiagnostics
+                    ? { headEntryIds: [], coveredLatestEntryCount: 0, uncoveredLatestEntryCount: 0 }
+                    : undefined,
+            };
+        }
+        return {
+            docId,
+            snapshotEntryId: null,
+            entryIdsToApply: [],
+            diagnostics: options?.includeDiagnostics
+                ? { headEntryIds: [], coveredLatestEntryCount: 0, uncoveredLatestEntryCount: 0 }
+                : undefined,
+        };
+    }
+    // ── Step 3: Build latest-state reachability ───────────────────────
+    // Identify the DAG heads (entries with no dependents) and walk backward
+    // to collect every entry causally needed for the current document state.
+    const { latestHeads, latestReachable } = buildLatestStateReachability(replayEntries);
+    // ── Step 4: Score each snapshot by how many latest-state entries it covers
+    let bestSnapshot = null;
+    let bestCoveredCount = -1;
+    for (const snapshot of snapshots) {
+        const covered = coveredBySnapshot(snapshot, replayById);
+        let coveredLatest = 0;
+        for (const id of latestReachable) {
+            if (covered.has(id)) {
+                coveredLatest++;
+            }
+        }
+        if (coveredLatest > bestCoveredCount ||
+            (coveredLatest === bestCoveredCount && bestSnapshot && snapshot.createdAt > bestSnapshot.createdAt)) {
+            bestSnapshot = snapshot;
+            bestCoveredCount = coveredLatest;
+        }
+        if (!bestSnapshot) {
+            bestSnapshot = snapshot;
+            bestCoveredCount = coveredLatest;
+        }
+    }
+    // ── Step 5: Compute the uncovered set ─────────────────────────────
+    // These are the entries that the selected snapshot does NOT already include.
+    // If no snapshot was selected, the entire latestReachable set is uncovered.
+    const covered = coveredBySnapshot(bestSnapshot, replayById);
+    const uncovered = new Set();
+    for (const id of latestReachable) {
+        if (!covered.has(id)) {
+            uncovered.add(id);
+        }
+    }
+    // ── Step 6: Sort uncovered entries in dependency-first order ──────
+    // This guarantees that Automerge.applyChanges sees each change only after
+    // all of its causal predecessors have already been applied.
+    const entryIdsToApply = topologicalByDependencies(uncovered, replayById);
+    return {
+        docId,
+        snapshotEntryId: bestSnapshot ? bestSnapshot.id : null,
+        entryIdsToApply,
+        diagnostics: options?.includeDiagnostics
+            ? {
+                headEntryIds: latestHeads,
+                coveredLatestEntryCount: bestCoveredCount < 0 ? 0 : bestCoveredCount,
+                uncoveredLatestEntryCount: uncovered.size,
+            }
+            : undefined,
+    };
+}
+/**
+ * Computes plans for many documents in one metadata pass.
+ *
+ * Batch planning is important for networked stores to reduce request/response
+ * chattiness during startup and dense sync operations.
+ */
+function computeBatchMaterializationPlan(allEntries, docIds, options) {
+    const byDoc = new Map();
+    for (const entry of allEntries) {
+        if (!byDoc.has(entry.docId)) {
+            byDoc.set(entry.docId, []);
+        }
+        byDoc.get(entry.docId).push(entry);
+    }
+    const plans = docIds.map((docId) => computeDocumentMaterializationPlan(docId, byDoc.get(docId) || [], options));
+    return { plans };
+}
+//# sourceMappingURL=MaterializationPlanner.js.map

package/dist/core/appendonlystores/MaterializationPlanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MaterializationPlanner.js","sourceRoot":"","sources":["../../../src/core/appendonlystores/MaterializationPlanner.ts"],"names":[],"mappings":";;AAsPA,gFAkGC;AAQD,0EAkBC;AA3WD;;;;;;;;;;;GAWG;AACH,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,CAAC,YAAY,EAAE,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC;AAE7E;;GAEG;AACH,SAAS,aAAa,CAAC,IAAwB;IAC7C,OAAO,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;GAMG;AACH,SAAS,4BAA4B,CACnC,aAAmC;IAEnC,MAAM,IAAI,GAAG,IAAI,GAAG,EAA8B,CAAC;IACnD,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,KAAK,MAAM,KAAK,IAAI,aAAa,EAAE,CAAC;QAClC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAC5B,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,aAAa,EAAE,CAAC;QAClC,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;YACxC,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBACpB,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;IACH,CAAC;IAED,uFAAuF;IACvF,MAAM,WAAW,GAAG,aAAa;SAC9B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;SACpC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAEpB,MAAM,eAAe,GAAG,IAAI,GAAG,EAAU,CAAC;IAC1C,MAAM,KAAK,GAAG,CAAC,GAAG,WAAW,CAAC,CAAC;IAC/B,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,EAAE,GAAG,KAAK,CAAC,GAAG,EAAG,CAAC;QACxB,IAAI,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YAC5B,SAAS;QACX,CAAC;QACD,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,SAAS;QACX,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;YACxC,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBACnD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACpB,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,CAAC;AAC1C,CAAC;AAED;;;;;;GAMG;AACH,SAAS,iBAAiB,CACxB,QAAmC,EACnC,UAA2C;IAE3C,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,IAAI,GAAG,EAAU,CAAC;IAC3B,CAAC;IAED,MAAM,KAAK,GAAG,QAAQ,CAAC,oBAAoB,IAAI,QAAQ,CAAC,oBAAoB,CAAC,MAAM,GAAG,CAAC;QACrF,CAAC,CAAC,QAAQ,CAAC,oBAAoB;QAC/B,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC;IAE3B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,MAAM,KAAK,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;IACzB,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,EAAE,GAAG,KAAK,CAAC,GAAG,EAAG,CAAC;QACxB,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YACpB,SAAS;QACX,CAAC;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACjC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,SAAS;QACX,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;YACxC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBACxB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACpB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,SAAS,yBAAyB,CAChC,GAAgB,EAChB,UAA2C;IAE3C,qEAAqE;IACrE,6EAA6E;IAC7E,sEAAsE;IACtE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,MAAM,UAAU,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC/C,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;QACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QACpB,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IACzB,CAAC;IAED,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;QACrB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACjC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,SAAS;QACX,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;YACxC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBACpB,8DAA8D;gBAC9D,+DAA+D;gBAC/D,SAAS;YACX,CAAC;YACD,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC9C,UAAU,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,qEAAqE;IACrE,iEAAiE;IACjE,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IAC5E,KAAK,CAAC,IAAI,EAAE,CAAC;IACb,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,EAAE,GAAG,KAAK,CAAC,KAAK,EAAG,CAAC;QAC1B,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,KAAK,MAAM,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC;YAC3C,MAAM,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YAC1C,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YACxB,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;gBACf,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAClB,CAAC;QACH,CAAC;QACD,oEAAoE;QACpE,KAAK,CAAC,IAAI,EAAE,CAAC;IACf,CAAC;IAED,qEAAqE;IACrE,IAAI,OAAO,CAAC,MAAM,KAAK,GAAG,CAAC,IAAI,EAAE,CAAC;QAChC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAChC,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,SAAgB,kCAAkC,CAChD,KAAa,EACb,gBAAsC,EACtC,OAAoC;IAGpC,sEAAsE;IACtE,2EAA2E;IAC3E,2EAA2E;IAC3E,mBAAmB;IACnB,MAAM,aAAa,GAAG,gBAAgB,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IAC7D,MAAM,UAAU,GAAG,IAAI,GAAG,CAA6B,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5F,MAAM,SAAS,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,cAAc,CAAC,CAAC;IAEjF,uEAAuE;IACvE,yEAAyE;IACzE,yEAAyE;IACzE,gDAAgD;IAChD,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC7E,OAAO;gBACL,KAAK;gBACL,eAAe,EAAE,IAAI,CAAC,EAAE;gBACxB,eAAe,EAAE,EAAE;gBACnB,WAAW,EAAE,OAAO,EAAE,kBAAkB;oBACtC,CAAC,CAAC,EAAE,YAAY,EAAE,EAAE,EAAE,uBAAuB,EAAE,CAAC,EAAE,yBAAyB,EAAE,CAAC,EAAE;oBAChF,CAAC,CAAC,SAAS;aACd,CAAC;QACJ,CAAC;QACD,OAAO;YACL,KAAK;YACL,eAAe,EAAE,IAAI;YACrB,eAAe,EAAE,EAAE;YACnB,WAAW,EAAE,OAAO,EAAE,kBAAkB;gBACtC,CAAC,CAAC,EAAE,YAAY,EAAE,EAAE,EAAE,uBAAuB,EAAE,CAAC,EAAE,yBAAyB,EAAE,CAAC,EAAE;gBAChF,CAAC,CAAC,SAAS;SACd,CAAC;IACJ,CAAC;IAED,qEAAqE;IACrE,wEAAwE;IACxE,yEAAyE;IACzE,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,GAAG,4BAA4B,CAAC,aAAa,CAAC,CAAC;IAErF,4EAA4E;IAC5E,IAAI,YAAY,GAA8B,IAAI,CAAC;IACnD,IAAI,gBAAgB,GAAG,CAAC,CAAC,CAAC;IAE1B,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,OAAO,GAAG,iBAAiB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACxD,IAAI,aAAa,GAAG,CAAC,CAAC;QACtB,KAAK,MAAM,EAAE,IAAI,eAAe,EAAE,CAAC;YACjC,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;gBACpB,aAAa,EAAE,CAAC;YAClB,CAAC;QACH,CAAC;QACD,IACE,aAAa,GAAG,gBAAgB;YAChC,CAAC,aAAa,KAAK,gBAAgB,IAAI,YAAY,IAAI,QAAQ,CAAC,SAAS,GAAG,YAAY,CAAC,SAAS,CAAC,EACnG,CAAC;YACD,YAAY,GAAG,QAAQ,CAAC;YACxB,gBAAgB,GAAG,aAAa,CAAC;QACnC,CAAC;QACD,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,YAAY,GAAG,QAAQ,CAAC;YACxB,gBAAgB,GAAG,aAAa,CAAC;QACnC,CAAC;IACH,CAAC;IAED,qEAAqE;IACrE,6EAA6E;IAC7E,4EAA4E;IAC5E,MAAM,OAAO,GAAG,iBAAiB,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;IAC5D,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;IACpC,KAAK,MAAM,EAAE,IAAI,eAAe,EAAE,CAAC;QACjC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YACrB,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED,qEAAqE;IACrE,0EAA0E;IAC1E,4DAA4D;IAC5D,MAAM,eAAe,GAAG,yBAAyB,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IAEzE,OAAO;QACL,KAAK;QACL,eAAe,EAAE,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI;QACtD,eAAe;QACf,WAAW,EAAE,OAAO,EAAE,kBAAkB;YACtC,CAAC,CAAC;gBACE,YAAY,EAAE,WAAW;gBACzB,uBAAuB,EAAE,gBAAgB,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,gBAAgB;gBACpE,yBAAyB,EAAE,SAAS,CAAC,IAAI;aAC1C;YACH,CAAC,CAAC,SAAS;KACd,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAgB,+BAA+B,CAC7C,UAAgC,EAChC,MAAgB,EAChB,OAAoC;IAEpC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAgC,CAAC;IACtD,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE,CAAC;QAC/B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC7B,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CACjC,kCAAkC,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,OAAO,CAAC,CAC3E,CAAC;IAEF,OAAO,EAAE,KAAK,EAAE,CAAC;AACnB,CAAC"}

package/dist/core/appendonlystores/network/NetworkTransport.d.ts

@@ -1,4 +1,5 @@
 import type { StoreEntry, StoreEntryMetadata, StoreEntryType, StoreScanCursor, StoreScanFilters, StoreScanResult, StoreIdBloomSummary, StoreCompactionStatus } from "../../types";
+import type { DocumentMaterializationBatchPlan, DocumentMaterializationPlan, MaterializationPlanOptions } from "../types";
 import type { NetworkEncryptedEntry, AuthResult, NetworkSyncCapabilities } from "./types";
 /**
  * Abstract interface for network communication in MindooDB sync.
@@ -19,6 +20,12 @@ import type { NetworkEncryptedEntry, AuthResult, NetworkSyncCapabilities } from
  * - Entry payloads are RSA-encrypted with recipient's public key
  */
 export interface NetworkTransport {
+    /**
+     * Optional stable identifier for this transport (e.g. the server URL).
+     * Used for local cache scoping so the same DB opened against different
+     * servers produces different cache entries.
+     */
+    getIdentity?(): string;
     /**
      * Request a challenge string for authentication.
      *
@@ -105,6 +112,14 @@ export interface NetworkTransport {
      * Optional compaction observability for remote store monitoring.
      */
     getCompactionStatus?(token: string): Promise<StoreCompactionStatus>;
+    /**
+     * Compute a causal materialization plan for one document on the remote store.
+     */
+    planDocumentMaterialization?(token: string, docId: string, options?: MaterializationPlanOptions): Promise<DocumentMaterializationPlan>;
+    /**
+     * Compute causal materialization plans for multiple documents on the remote store.
+     */
+    planDocumentMaterializationBatch?(token: string, docIds: string[], options?: MaterializationPlanOptions): Promise<DocumentMaterializationBatchPlan>;
     /**
      * Get entries from the remote store.
      *

package/dist/core/appendonlystores/network/NetworkTransport.d.ts.map

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

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

@@ -115,6 +115,8 @@ export interface NetworkSyncCapabilities {
     supportsCursorScan: boolean;
     supportsIdBloomSummary: boolean;
     supportsCompactionStatus: boolean;
+    supportsMaterializationPlanning: boolean;
+    supportsBatchMaterializationPlanning: boolean;
 }
 /**
  * Network transport error types for error handling.

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/core/appendonlystores/network/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB;IAC/D;;;;;;;;;;OAUG;IACH,mBAAmB,EAAE,UAAU,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,sBAAsB,EAAE,OAAO,CAAC;IAChC,wBAAwB,EAAE,OAAO,CAAC;CACnC;AAED;;GAEG;AACH,oBAAY,gBAAgB;IAC1B,kCAAkC;IAClC,aAAa,kBAAkB;IAC/B,4BAA4B;IAC5B,YAAY,iBAAiB;IAC7B,oCAAoC;IACpC,iBAAiB,sBAAsB;IACvC,wCAAwC;IACxC,iBAAiB,sBAAsB;IACvC,kCAAkC;IAClC,aAAa,kBAAkB;IAC/B,wBAAwB;IACxB,YAAY,iBAAiB;IAC7B,kCAAkC;IAClC,cAAc,mBAAmB;CAClC;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;aAEnB,IAAI,EAAE,gBAAgB;gBAAtB,IAAI,EAAE,gBAAgB,EACtC,OAAO,EAAE,MAAM;CAKlB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/core/appendonlystores/network/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB;IAC/D;;;;;;;;;;OAUG;IACH,mBAAmB,EAAE,UAAU,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,sBAAsB,EAAE,OAAO,CAAC;IAChC,wBAAwB,EAAE,OAAO,CAAC;IAClC,+BAA+B,EAAE,OAAO,CAAC;IACzC,oCAAoC,EAAE,OAAO,CAAC;CAC/C;AAED;;GAEG;AACH,oBAAY,gBAAgB;IAC1B,kCAAkC;IAClC,aAAa,kBAAkB;IAC/B,4BAA4B;IAC5B,YAAY,iBAAiB;IAC7B,oCAAoC;IACpC,iBAAiB,sBAAsB;IACvC,wCAAwC;IACxC,iBAAiB,sBAAsB;IACvC,kCAAkC;IAClC,aAAa,kBAAkB;IAC/B,wBAAwB;IACxB,YAAY,iBAAiB;IAC7B,kCAAkC;IAClC,cAAc,mBAAmB;CAClC;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;aAEnB,IAAI,EAAE,gBAAgB;gBAAtB,IAAI,EAAE,gBAAgB,EACtC,OAAO,EAAE,MAAM;CAKlB"}

package/dist/core/appendonlystores/network/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/core/appendonlystores/network/types.ts"],"names":[],"mappings":";;;AAwIA;;GAEG;AACH,IAAY,gBAeX;AAfD,WAAY,gBAAgB;IAC1B,kCAAkC;IAClC,mDAA+B,CAAA;IAC/B,4BAA4B;IAC5B,iDAA6B,CAAA;IAC7B,oCAAoC;IACpC,2DAAuC,CAAA;IACvC,wCAAwC;IACxC,2DAAuC,CAAA;IACvC,kCAAkC;IAClC,mDAA+B,CAAA;IAC/B,wBAAwB;IACxB,iDAA6B,CAAA;IAC7B,kCAAkC;IAClC,qDAAiC,CAAA;AACnC,CAAC,EAfW,gBAAgB,gCAAhB,gBAAgB,QAe3B;AAED;;GAEG;AACH,MAAa,YAAa,SAAQ,KAAK;IACrC,YACkB,IAAsB,EACtC,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAkB;QAItC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AARD,oCAQC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/core/appendonlystores/network/types.ts"],"names":[],"mappings":";;;AA0IA;;GAEG;AACH,IAAY,gBAeX;AAfD,WAAY,gBAAgB;IAC1B,kCAAkC;IAClC,mDAA+B,CAAA;IAC/B,4BAA4B;IAC5B,iDAA6B,CAAA;IAC7B,oCAAoC;IACpC,2DAAuC,CAAA;IACvC,wCAAwC;IACxC,2DAAuC,CAAA;IACvC,kCAAkC;IAClC,mDAA+B,CAAA;IAC/B,wBAAwB;IACxB,iDAA6B,CAAA;IAC7B,kCAAkC;IAClC,qDAAiC,CAAA;AACnC,CAAC,EAfW,gBAAgB,gCAAhB,gBAAgB,QAe3B;AAED;;GAEG;AACH,MAAa,YAAa,SAAQ,KAAK;IACrC,YACkB,IAAsB,EACtC,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAkB;QAItC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AARD,oCAQC"}

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

@@ -104,6 +104,66 @@ 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[];
+}
 /**
  * Result of creating stores for a database.
  * Contains the document store and an optional separate attachment store.
@@ -240,6 +300,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 +360,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"}