mindoodb 0.0.19 → 0.0.21

package/dist/core/BaseMindooDB.d.ts

@@ -1,4 +1,4 @@
-import { MindooDB, CreateOptions, DeleteOptions, UndeleteOptions, ChangeOptions, DocumentDagAnalysisTimestamp, DocumentDagAnalysisResult, DocumentDagBranchMaterializationResult, DocumentDagEntryDetails, MindooDoc, MindooTenant, ProcessChangesCursor, ProcessChangesResult, DocumentHistoryResult, AttachmentConfig, DocumentCacheConfig, SnapshotConfig, SigningKeyPair, PerformanceCallback, ProcessChangeSummaryResult, SyncOptions, SyncResult, DocumentHistoryPageOptions, DocumentHistoryPageResult, MindooTextPatch, MindooTextPatchResult } from "./types";
+import { MindooDB, CreateOptions, DeleteOptions, UndeleteOptions, ChangeOptions, DocumentDagAnalysisTimestamp, DocumentDagAnalysisResult, DocumentDagBranchMaterializationResult, DocumentDagEntryDetails, DocumentConflictAnalysisEvent, DocumentConflictAnalysisOptions, DocumentConflictBaseValue, DocumentConflictBaseValueQuery, DocumentConflictReport, DocumentConflictReportOptions, ConflictScanCheckpoint, MindooDoc, MindooTenant, ProcessChangesCursor, ProcessChangesResult, DocumentHistoryResult, AttachmentConfig, DocumentCacheConfig, SnapshotConfig, SigningKeyPair, PerformanceCallback, ProcessChangeSummaryResult, IncompleteAttachmentUploadReclaimResult, SyncOptions, SyncResult, DocumentHistoryPageOptions, DocumentHistoryPageResult, MindooJsonPatch, MindooJsonPatchResult, MindooTextPatch, MindooTextPatchResult, StartBackgroundWarmerOptions, BackgroundWarmerProgress } from "./types";
 import { BaseMindooTenant } from "./BaseMindooTenant";
 import type { ContentAddressedStore } from "./appendonlystores/types";
 import { Logger } from "./logging";
@@ -59,6 +59,7 @@ export declare class BaseMindooDB implements MindooDB {
     private attachmentStore;
     private chunkSizeBytes;
     private _isAdminOnlyDb;
+    private readonly timeTravelDate;
     private index;
     private indexLookup;
     private nextChangeSeq;
@@ -66,7 +67,14 @@ export declare class BaseMindooDB implements MindooDB {
     private readonly maxCachedDocs;
     private readonly iteratePrefetchWindowDocs;
     private readonly cacheRestoreLimit;
+    private readonly cacheRestoreBatchSize;
     private readonly reconcileRestoredIndexOnInit;
+    /**
+     * When `true`, startup leaves the in-memory L1 cache empty and lets
+     * subsequent reads pull documents lazily from L2 via
+     * {@link tryLoadFromL2}. See `DocumentCacheConfig.restoreToL2`.
+     */
+    private readonly restoreToL2;
     private readonly snapshotMinChanges;
     private readonly snapshotCooldownMs;
     private processedEntryIds;
@@ -79,13 +87,57 @@ export declare class BaseMindooDB implements MindooDB {
     private cachePrefix;
     private dirtyDocIds;
     private cacheMetaDirty;
-    constructor(tenant: BaseMindooTenant, store: ContentAddressedStore, attachmentStore: ContentAddressedStore, attachmentConfig?: AttachmentConfig, documentCacheConfig?: DocumentCacheConfig, snapshotConfig?: SnapshotConfig, adminOnlyDb?: boolean, logger?: Logger, performanceCallback?: PerformanceCallback);
+    /**
+     * Tenant KeyBag fingerprint observed at the time the in-memory index
+     * was last reconciled with the underlying store.
+     *
+     * Persisted alongside the cache checkpoint so warm starts can compare
+     * the current fingerprint against the stored one and skip a full
+     * metadata scan (and the associated REST round-trips against remote
+     * stores) when the bag composition has not changed since the last
+     * flush.
+     *
+     * Set to `null` when no reconciliation has been performed yet, or
+     * when the tenant does not expose a fingerprint method.
+     */
+    private lastReconciledKeyBagFingerprint;
+    private readonly warmerBatchSize;
+    private readonly warmerScheduler;
+    /**
+     * Resolves when the currently-running warmer pass finishes. `null`
+     * when no warmer is running. Re-used to enforce single-flight: a
+     * second `startBackgroundWarmer()` call returns the same promise.
+     */
+    private warmerPromise;
+    /**
+     * AbortController for the in-flight warmer. `null` when no warmer is
+     * running. {@link stopBackgroundWarmer} aborts via this controller.
+     */
+    private warmerAbort;
+    /**
+     * Snapshot of the most recent warmer pass's progress. Updated
+     * in-place by {@link runBackgroundWarmer} so {@link getBackgroundWarmerProgress}
+     * can return the current state without additional bookkeeping. Set
+     * back to a fresh `{ processed: 0, total, phase: "warming" }` at the
+     * start of each new pass; the final value (`"done"` or
+     * `"cancelled"`) lingers between passes so a UI that mounts after
+     * the warmer settled can still display its outcome.
+     */
+    private warmerProgress;
+    constructor(tenant: BaseMindooTenant, store: ContentAddressedStore, attachmentStore: ContentAddressedStore, attachmentConfig?: AttachmentConfig, documentCacheConfig?: DocumentCacheConfig, snapshotConfig?: SnapshotConfig, adminOnlyDb?: boolean, logger?: Logger, performanceCallback?: PerformanceCallback, timeTravelDate?: number | null);
     /**
      * Get the admin public key from the tenant.
      * Only used when adminOnlyDb is true.
      */
     private getAdminPublicKey;
     isAdminOnlyDb(): boolean;
+    isTimeTravelMode(): boolean;
+    isReadOnly(): boolean;
+    getTimeTravelDate(): number | null;
+    private assertWritable;
+    private metadataVisibleAtTimeTravelDate;
+    private applyTimeTravelFilter;
+    private mergeTimeTravelScanFilters;
     /**
      * Attach a CacheManager so this DB participates in periodic cache flushing.
      */
@@ -97,16 +149,68 @@ export declare class BaseMindooDB implements MindooDB {
     private getCachedDocument;
     private touchCachedDocument;
     private storeCachedDocument;
+    /**
+     * Bring the in-memory L1 cache back under `maxCachedDocs` after a new
+     * insert, performing flush-before-evict for any dirty entry that would
+     * otherwise be dropped.
+     *
+     * Without flush-before-evict, an evicted dirty doc loses its in-memory
+     * state before the periodic `CacheManager` flush has a chance to
+     * persist it, forcing the next read to fall through to the expensive
+     * full-materialization path. By writing the doc to L2 inline first, we
+     * guarantee the next read can recover it via the cheap L2 read path
+     * (Phase 1c) - either as a fresh hit (changeSeq matches) or as a
+     * stale hit that only needs the missing deltas re-applied.
+     *
+     * If no `cacheManager` is attached (i.e. there is no L2 store
+     * available), we fall back to the legacy behavior and just drop the
+     * dirty marker - matching pre-Phase-1 semantics so embedders who
+     * never opted into L2 see no behavior change.
+     */
     private evictCachedDocsIfNeeded;
+    /**
+     * Synchronous eviction variant used after the periodic flush has
+     * already drained `dirtyDocIds`. No L2 work is required because there
+     * are no dirty docs left to persist.
+     */
+    private evictCleanCachedDocsIfNeeded;
     /**
      * Flush dirty documents and metadata to the cache store.
      */
     flushToCache(store: LocalCacheStore): Promise<number>;
+    /**
+     * Serialize and persist a single document into the L2 cache store.
+     *
+     * Header format (v2):
+     *   `{ version: 2, id, createdAt, lastModified, decryptionKeyId,
+     *      isDeleted, changeSeq, automergeHeads }`
+     *
+     * `changeSeq` is read from the in-memory changefeed index so that on
+     * the next open we can compare it against the live index entry and
+     * decide whether the persisted Automerge state is up to date or needs
+     * incremental delta application. `automergeHeads` snapshots
+     * `Automerge.getHeads(doc)` so a future read can identify which entries
+     * (if any) still need to be applied to bring the persisted doc current.
+     *
+     * Both fields are derived inline (no extra index lookups beyond the
+     * O(1) `indexLookup`) so this stays cheap to call from the periodic
+     * flush as well as from the upcoming flush-before-evict path.
+     */
+    private flushDirtyDocToCache;
     private exportMetadataCheckpoint;
     /**
      * Attempt to restore state from cache. Returns true on success.
      */
     restoreFromCache(store: LocalCacheStore): Promise<boolean>;
+    /**
+     * Decode a persisted L2 document cache record.
+     *
+     * Returns `null` for legacy (v1) records - they predate the
+     * `changeSeq + automergeHeads` freshness sentinels and so cannot
+     * participate in the L2 read-path freshness check; callers should
+     * fall back to the normal materialization path when they encounter
+     * one. Throws on truly malformed records (caught by callers).
+     */
     private deserializeDoc;
     /**
      * Get or import a CryptoKey for signature verification, with caching.
@@ -126,14 +230,24 @@ export declare class BaseMindooDB implements MindooDB {
     private compareIndexEntries;
     /**
      * Update the index entry for a document.
-     * When a document changes, it gets a new monotonic sequence and is moved to
-     * maintain order by (changeSeq, docId).
      *
-     * Optimized to only update lookup map for entries that actually moved.
+     * When a document changes, it gets a new monotonic sequence and is
+     * moved within the sorted index to maintain `(changeSeq, docId)` order.
+     * The lookup map is only patched for the range of entries that actually
+     * shifted.
+     *
+     * Idempotent: if every tracked field (`lastModified`, `isDeleted`,
+     * `decryptionKeyId`, `accessState`) matches the existing entry the
+     * call is a no-op and no new `changeSeq` is consumed. This is what
+     * keeps repeated visibility reconciliations from inflating the
+     * changefeed.
      *
      * @param docId The document ID
      * @param lastModified The new last modified timestamp
-     * @param isDeleted Whether the document is deleted
+     * @param isDeleted Whether the document is a deletion/inaccessibility tombstone
+     * @param decryptionKeyId Encryption key id derived from the doc's store metadata
+     * @param accessState `"visible"` for readable docs, `"inaccessible"` for
+     *   tombstones produced by the key visibility layer
      */
     private updateIndex;
     /**
@@ -179,11 +293,94 @@ export declare class BaseMindooDB implements MindooDB {
      * then processes only the delta. Falls back to full rebuild on cache miss.
      */
     initialize(): Promise<void>;
+    /**
+     * Compute the current tenant KeyBag fingerprint, or `null` when the
+     * tenant does not expose one (older `MindooTenant` implementations).
+     */
+    private computeCurrentKeyBagFingerprint;
+    /**
+     * Record that the in-memory index now reflects the given KeyBag
+     * fingerprint. Marks the cache metadata dirty whenever the recorded
+     * value changes so the new fingerprint reaches the persisted
+     * checkpoint at the next flush.
+     */
+    private markKeyBagFingerprintReconciled;
+    /**
+     * Derive the per-doc visibility summary needed to reconcile the index
+     * against the current KeyBag state.
+     *
+     * - `decryptionKeyId` is taken from the chronologically first lifecycle
+     *   entry, mirroring how {@link syncStoreChanges} materializes a doc.
+     *   Replay entries inside a doc cannot retroactively re-key it.
+     * - `lastModified` is the latest `createdAt` among the entries that
+     *   would be replayed for this doc (or, if none exist, the lifecycle
+     *   entries themselves). This matches the user-visible timestamp the
+     *   existing read path produces.
+     * - `isDeleted` is the lifecycle state derived from the same metadata
+     *   {@link syncStoreChanges} would have observed.
+     *
+     * Returns `null` when there are no lifecycle entries for the doc,
+     * meaning there is nothing to reconcile.
+     */
+    private deriveDocumentVisibilityMetadata;
+    /**
+     * Evict every locally cached form of a document.
+     *
+     * Used by the visibility layer whenever a document transitions to
+     * `"inaccessible"` (the user lost the decryption key) or when a stale
+     * L2 record for an inaccessible doc is discovered. The point is to
+     * make sure no decrypted plaintext or in-memory Automerge state for
+     * the doc survives beyond the key revocation.
+     *
+     *  - L1 (`docCache`) is cleared and the dirty marker dropped so we do
+     *    not later persist a stale entry.
+     *  - The automerge-hash lookup is cleared so any future re-add starts
+     *    with a clean re-materialization.
+     *  - The L2 record is deleted via the {@link LocalCacheStore} (if a
+     *    cache manager is attached). Failures are logged but never thrown:
+     *    a leftover encrypted record is preferable to crashing the read
+     *    path that triggered the purge.
+     */
+    private purgeMaterializedDocument;
+    /**
+     * Reconcile the in-memory index with the current tenant KeyBag.
+     *
+     * This is the core entry point for "the user's keys changed; refresh
+     * what this database thinks is visible". It is safe to call repeatedly,
+     * including from concurrent live updates: the underlying `updateIndex`
+     * call only consumes a new `changeSeq` when state actually transitions.
+     *
+     * Behaviour for each doc that exists in the underlying store:
+     *
+     *  - **Key now available, no entry / inaccessible entry** -> mark
+     *    `"visible"` and emit a new index revision so view providers can
+     *    re-add the doc. The doc body will be materialized lazily on the
+     *    next read.
+     *  - **Key now available, already visible** -> no-op.
+     *  - **Key now missing, currently visible** -> purge any materialized
+     *    state and mark `"inaccessible"` with `isDeleted: true` so
+     *    metadata-only feeds emit a single tombstone and views remove
+     *    the entry.
+     *  - **Key now missing, already inaccessible (or not yet in index)** ->
+     *    no index change, but we still call {@link purgeMaterializedDocument}
+     *    defensively to scrub any leftover plaintext cache that might exist.
+     *
+     * Time-travel views are immutable; the function returns early for them.
+     * After running, if any transition occurred we mark the cache metadata
+     * dirty so the new visibility state survives a process restart.
+     */
+    reconcileKeyVisibility(): Promise<void>;
     private reconcileRestoredIndexWithStore;
     /**
      * Sync changes from the content-addressed store by finding new entries and processing them.
      * This method can be called multiple times to incrementally sync new entries.
      * On first call (when processedEntryIds is empty), it will process all entries.
+     *
+     * Sync intentionally does not trigger the L2 background warmer.
+     * Callers that want to warm the L2 cache after a sync (e.g. the Haven
+     * sync page) must call {@link startBackgroundWarmer} explicitly so
+     * casual sync calls stay cheap and the warmer cost is paid only when
+     * the workload is about to benefit from it.
      */
     syncStoreChanges(): Promise<void>;
     private supportsCursorScan;
@@ -252,6 +449,9 @@ export declare class BaseMindooDB implements MindooDB {
     private syncEntriesFromStoreDense;
     getStore(): ContentAddressedStore;
     getAttachmentStore(): ContentAddressedStore;
+    reclaimIncompleteAttachmentUploads(options?: {
+        minAgeMs?: number;
+    }): Promise<IncompleteAttachmentUploadReclaimResult>;
     getTenant(): MindooTenant;
     createDocument(options?: CreateOptions): Promise<MindooDoc>;
     /**
@@ -289,6 +489,289 @@ export declare class BaseMindooDB implements MindooDB {
     materializeDocumentBranchAtEntry(docId: string, headEntryId: string): Promise<DocumentDagBranchMaterializationResult | null>;
     materializeDocumentBranchAtTimestamp(docId: string, timestamp: DocumentDagAnalysisTimestamp, headEntryId: string): Promise<DocumentDagBranchMaterializationResult | null>;
     describeDocumentDagEntry(docId: string, entryId: string): Promise<DocumentDagEntryDetails | null>;
+    /**
+     * Streams conflict-analysis events for one or more documents.
+     *
+     * This is the UI/server friendly entry point for conflict analysis. It first
+     * does a metadata-only preflight for each document, then only decrypts and
+     * replays document changes when the DAG contains concurrency candidates. The
+     * yielded DTOs intentionally expose MindooDB concepts only; callers never get
+     * direct access to Automerge documents, patches, operation IDs, or objects.
+     *
+     * @param docIds Document IDs to analyze. Documents are processed sequentially
+     *   so browser callers can render progress and stop early without a large
+     *   burst of synchronous work.
+     * @param options Controls quick/full mode, value detail level, cancellation,
+     *   per-document conflict limits, and cooperative event-loop yielding.
+     * @returns An async generator yielding progress, conflict, resolution, done,
+     *   and error events.
+     */
+    analyzeDocumentConflicts(docIds: string[], options?: DocumentConflictAnalysisOptions): AsyncGenerator<DocumentConflictAnalysisEvent, void, unknown>;
+    /**
+     * Builds a complete conflict report for a single document.
+     *
+     * This is a convenience wrapper around `analyzeDocumentConflicts()`. It forces
+     * full analysis mode, consumes the event stream internally, and returns a
+     * stable report object suitable for server-side jobs or UI detail panels.
+     *
+     * @param docId Document ID to analyze.
+     * @param options Report options. The wrapper ignores quick-mode limits because
+     *   reports are intended to describe the full known conflict history.
+     * @returns Aggregated conflict and resolution information for the document.
+     */
+    getDocumentConflictReport(docId: string, options?: DocumentConflictReportOptions): Promise<DocumentConflictReport>;
+    /**
+     * Resolves the value each conflicted path had at its merge base.
+     *
+     * For every query, the database identifies the heads that contributed to
+     * the conflict (the merging entry's parents for `entry-after` /
+     * `merge-deps` conflicts, or the active heads for `active-heads`
+     * conflicts), computes the most recent common ancestor of those heads,
+     * materializes the document at that ancestor, and reads the path.
+     *
+     * Queries that share a merge base are coalesced: the document is
+     * materialized at most once per unique base entry.
+     *
+     * @param docId Document identifier the queries refer to.
+     * @param queries One entry per (location, path) lookup the caller wants.
+     * @returns A `DocumentConflictBaseValue` aligned 1:1 with `queries`.
+     */
+    getDocumentConflictBaseValues(docId: string, queries: DocumentConflictBaseValueQuery[]): Promise<DocumentConflictBaseValue[]>;
+    /**
+     * Returns the head entry IDs whose merge base should be resolved for one
+     * conflict location. Filters out IDs that aren't present in the local
+     * metadata so callers don't try to materialize against missing entries.
+     */
+    private resolveConflictBaseParents;
+    /**
+     * Computes the most recent common ancestor of `parents` in the document's
+     * dependency DAG.
+     *
+     * Returns the deepest common ancestor (an ancestor that is not itself a
+     * proper ancestor of another common ancestor). If multiple deepest
+     * candidates exist, the one with the highest `createdAt` wins so the UI
+     * shows a base value as close to the conflict as possible.
+     */
+    private computeConflictMergeBaseEntryId;
+    /**
+     * Captures the current local receipt/index position for future incremental
+     * conflict scans.
+     */
+    getConflictScanCheckpoint(): Promise<ConflictScanCheckpoint>;
+    /**
+     * Narrows scan work to documents whose indexed latest state changed after the
+     * caller's checkpoint. When the caller asks for pre-existing unresolved
+     * conflicts, every requested document remains a candidate because an old active
+     * conflict may still need to be returned.
+     */
+    private resolveConflictAnalysisCandidateDocIds;
+    /**
+     * Finds the latest local store receipt order. This is intentionally metadata
+     * only and works with stores that do not expose a direct max-receipt query.
+     */
+    private getStoreMaxReceiptOrder;
+    /**
+     * Replays verified document changes and detects conflict/resolution events.
+     *
+     * The input `plan` is metadata-only and has already determined that analyzing
+     * this document is worth the cost. This method performs the private Automerge
+     * work: decrypting changes, replaying them in dependency order, inspecting
+     * changed paths, and optionally resolving conflicting value summaries. All
+     * Automerge-specific objects are converted to MindooDB DTOs before returning.
+     *
+     * Conflict detection has three phases:
+     * 1. Before applying a change, inspect existing multi-head states. This catches
+     *    conflicts that exist between active heads and conflicts that are about to
+     *    be resolved by a merge/resolution change.
+     * 2. After applying a change, inspect Automerge patches for changed paths and
+     *    confirm conflicts with `getConflicts()` on those changed paths only.
+     * 3. After replay completes, inspect remaining active heads so unresolved
+     *    conflicts are still reported for documents that never wrote a merge change.
+     *
+     * @param docId Document being analyzed.
+     * @param plan Metadata-only replay/concurrency plan for the document.
+     * @param options Analysis options propagated from the public API.
+     * @returns Conflict findings, resolution events, and the number of entries
+     *   successfully replayed.
+     */
+    private detectDocumentConflictsFromPlan;
+    /**
+     * Applies incremental-scan visibility rules to conflict and resolution events.
+     *
+     * Receipt order is preferred because it represents local arrival. Created-at is
+     * only a fallback for legacy metadata that predates receipt-order assignment.
+     */
+    private shouldEmitConflictObservation;
+    /**
+     * Loads, verifies, decrypts, and decodes replay changes for conflict analysis.
+     *
+     * This mirrors the security checks used by normal materialization paths:
+     * admin-only databases ignore non-admin entries, signatures are verified
+     * before decryption, and malformed/missing entries are skipped with warnings.
+     *
+     * @param replayEntries Metadata entries selected by the conflict planner.
+     * @returns Map keyed by store entry ID containing decrypted change bytes and
+     *   decoded Automerge hash/dependency metadata for private replay.
+     */
+    private loadVerifiedReplayChanges;
+    /**
+     * Builds a private lookup from Automerge change hashes to MindooDB entry IDs.
+     *
+     * Public conflict DTOs use MindooDB entry IDs, while Automerge heads are
+     * hashes. This lookup lets us translate internal head sets back to stable
+     * store-entry references for UI and report consumers.
+     *
+     * @param replayEntries Store metadata for replay entries.
+     * @param verifiedChanges Decrypted/decoded changes keyed by entry ID.
+     * @returns Map from Automerge hash to MindooDB store entry ID.
+     */
+    private buildAutomergeHashToEntryId;
+    /**
+     * Calls Automerge's diff API through a defensive private adapter.
+     *
+     * The public API must not depend on Automerge patch types. This wrapper keeps
+     * the cast and optional-method handling localized so a future Automerge API
+     * change affects only this internal method.
+     *
+     * @param doc Materialized internal Automerge document containing both head sets.
+     * @param beforeHeads Heads before applying the current change.
+     * @param afterHeads Heads after applying the current change.
+     * @returns Raw patch-like records for internal inspection only.
+     */
+    private diffAutomergeHeads;
+    /**
+     * Reads a patch action without leaking Automerge patch types into the codebase.
+     *
+     * @param patch Raw patch-like record returned by the private diff adapter.
+     * @returns Patch action string, or null when unavailable.
+     */
+    private getConflictPatchAction;
+    /**
+     * Normalizes a raw patch path into a JSON-safe MindooDB path array.
+     *
+     * @param patch Raw patch-like record returned by the private diff adapter.
+     * @returns A path made of string/number segments, or null for unsupported
+     *   patch shapes.
+     */
+    private getConflictPatchPath;
+    /**
+     * Checks Automerge's optional conflict marker on a raw patch.
+     *
+     * Some conflict states are not surfaced solely by this flag, so callers also
+     * verify changed paths with `hasDocumentConflictAtPath()`.
+     *
+     * @param patch Raw patch-like record returned by the private diff adapter.
+     * @returns True when the patch explicitly says it wrote a conflicted value.
+     */
+    private isConflictPatch;
+    /**
+     * Filters MindooDB bookkeeping fields out of app-facing conflict results.
+     *
+     * `_lastModified` can conflict naturally because independent replicas update
+     * it during every change. Reporting it would be noisy and not useful to app
+     * developers analyzing their own JSON payload.
+     *
+     * @param path Candidate conflict path.
+     * @returns True when the path belongs to MindooDB internals.
+     */
+    private isInternalConflictPath;
+    /**
+     * Confirms whether a specific document path currently has multiple values.
+     *
+     * This is the narrow, path-level use of Automerge conflict inspection. It is
+     * called only for paths surfaced by patches or by the bounded active-head scan.
+     *
+     * @param doc Internal document or nested object containing the candidate path.
+     * @param path Path relative to `doc`.
+     * @returns True when Automerge reports more than one conflicting value.
+     */
+    private hasDocumentConflictAtPath;
+    /**
+     * Converts a conflict path into the public DTO representation.
+     *
+     * @param doc Internal document used to optionally resolve value summaries.
+     * @param path JSON-style path segments for the conflicted field.
+     * @param includeValues Whether to include winner/loser value summaries.
+     * @returns Public path DTO with optional conflict values.
+     */
+    private buildDocumentConflictPath;
+    /**
+     * Scans a materialized document for current conflicts.
+     *
+     * This is intentionally used only for bounded multi-head states: before a
+     * resolving change is applied and after replay if unresolved active heads
+     * remain. Regular per-change analysis stays patch-driven for performance.
+     *
+     * @param doc Internal materialized document to inspect.
+     * @param includeValues Whether to include value summaries in returned paths.
+     * @returns Sorted conflict path DTOs.
+     */
+    private collectDocumentConflictPaths;
+    /**
+     * Recursive worker for `collectDocumentConflictPaths()`.
+     *
+     * @param root Root internal document used when value summaries need absolute
+     *   paths.
+     * @param parent Current object/array being inspected.
+     * @param basePath Path from `root` to `parent`.
+     * @param includeValues Whether to include value summaries.
+     * @param results Mutable result map keyed by path string.
+     * @param seen Object identity set used to avoid cycles/proxy revisits.
+     */
+    private collectDocumentConflictPathsFromParent;
+    /**
+     * Reads winner/loser summaries for one conflicted path.
+     *
+     * Values are converted into JSON-safe summaries so callers can inspect them
+     * without seeing Automerge-specific wrappers or mutable document objects.
+     *
+     * @param doc Internal document containing the conflict.
+     * @param path Absolute path to the conflicted field.
+     * @returns Stable list of conflict value summaries.
+     */
+    private getDocumentConflictValueSummaries;
+    /**
+     * Reads a nested value using the public path representation.
+     *
+     * @param root Root object/document to read from.
+     * @param path String/number path segments.
+     * @returns The value at the path, or undefined when any segment is missing.
+     */
+    private readValueAtDocumentPath;
+    /**
+     * Produces a stable comparison key for conflict winner detection.
+     *
+     * @param value Value to fingerprint.
+     * @returns String key derived from the JSON-safe representation.
+     */
+    private fingerprintConflictValue;
+    /**
+     * Converts arbitrary conflict values to bounded, JSON-safe data.
+     *
+     * This avoids exposing live Automerge objects and prevents very deep or cyclic
+     * structures from overwhelming reports.
+     *
+     * @param value Value to convert.
+     * @param depth Current recursion depth.
+     * @param seen Objects already visited during this conversion.
+     * @returns JSON-safe scalar, array/object subset, or compact placeholder.
+     */
+    private toJsonSafeConflictValue;
+    /**
+     * Throws when the caller cancels conflict analysis.
+     *
+     * @param signal Optional `AbortSignal` supplied through analysis options.
+     */
+    private throwIfConflictAnalysisAborted;
+    /**
+     * Cooperatively yields to the event loop during long browser/server scans.
+     *
+     * @param yieldEveryMs Minimum elapsed time before yielding. Undefined disables
+     *   cooperative yielding; `0` yields at every call site.
+     * @param lastYieldAt Timestamp of the previous yield.
+     * @returns Updated timestamp to carry into the next call.
+     */
+    private maybeYieldForConflictAnalysis;
     /**
      * Derives human-readable changed field paths for one DAG entry.
      *
@@ -322,8 +805,17 @@ export declare class BaseMindooDB implements MindooDB {
     changeDoc(doc: MindooDoc, changeFunc: (doc: MindooDoc) => void | Promise<void>, options?: ChangeOptions): Promise<void>;
     changeDocWithSigningKey(doc: MindooDoc, changeFunc: (doc: MindooDoc) => void | Promise<void>, signingKeyPair: SigningKeyPair, signingKeyPassword: string): Promise<void>;
     applyTextPatch(doc: MindooDoc, patch: MindooTextPatch): Promise<MindooTextPatchResult>;
+    applyJsonPatch(doc: MindooDoc, patch: MindooJsonPatch): Promise<MindooJsonPatchResult>;
     private changeDocInternal;
     private validateTextPatch;
+    private validateJsonPatch;
+    private validateJsonPath;
+    private applyJsonPatchOperations;
+    private setJsonValueAtPath;
+    private unsetJsonValueAtPath;
+    private readJsonListAtPath;
+    private ensureJsonParentAtPath;
+    private readJsonParentAtPath;
     private ensureTextPath;
     private persistDocumentChange;
     /**
@@ -388,6 +880,97 @@ export declare class BaseMindooDB implements MindooDB {
      * Returns the updated document, or null if document wasn't actually changed.
      */
     private applyNewEntriesToCachedDocument;
+    /**
+     * Try to satisfy a document load from the persisted L2 cache without
+     * going through the full signature-verify + decrypt + Automerge replay
+     * pipeline.
+     *
+     * Three outcomes:
+     *
+     * 1. **L2 miss / unusable** (no record, legacy v1 record, deserialize
+     *    failure, no `cacheManager`, etc.): returns `null`. The caller
+     *    falls through to the existing full-materialization path.
+     *
+     * 2. **L2 fresh hit** (`persistedChangeSeq === currentChangeSeq`):
+     *    promote the deserialized doc to L1 and return it. No store
+     *    traffic, no crypto, no Automerge replay. This is the common case
+     *    for warm databases and is what makes view rebuilds fast.
+     *
+     * 3. **L2 stale hit** (`persistedChangeSeq < currentChangeSeq`): scan
+     *    the doc's store metadata, identify entries whose `automergeHash`
+     *    is *not* already in the persisted doc's history, and re-use the
+     *    existing {@link applyNewEntriesToCachedDocument} pipeline to
+     *    verify+decrypt+apply only those deltas. Pre-filtering by hash
+     *    means we never pay signature/decrypt cost for changes already
+     *    captured in the persisted Automerge state.
+     *
+     * Any unexpected error degrades gracefully to the full path - the L2
+     * read path is purely an optimization and must never lose data.
+     */
+    private tryLoadFromL2;
+    /**
+     * Returns whether a background warmer pass is currently running.
+     *
+     * @see startBackgroundWarmer
+     * @see stopBackgroundWarmer
+     */
+    isWarmerRunning(): boolean;
+    /**
+     * Start the L2 background warmer.
+     *
+     * Walks a snapshot of the in-memory document index and, for every
+     * doc not already in L1, calls {@link tryLoadFromL2}. That path
+     * either:
+     *
+     *  - hits L2 fresh and just promotes the doc to L1, or
+     *  - hits L2 stale and applies missing deltas (re-flushed via the
+     *    next CacheManager flush), or
+     *  - falls through to full materialization for L2 misses, which then
+     *    flushes a fresh L2 record via flush-before-evict.
+     *
+     * In all cases, after the warmer has visited every doc, every L2
+     * record has the current `changeSeq + automergeHeads`. Subsequent
+     * read-heavy workloads (most importantly virtual view rebuilds) can
+     * then satisfy every doc lookup via the cheap L2 read path.
+     *
+     * Single-flight: if a warmer is already running, the existing promise
+     * is returned. Yields to {@link warmerScheduler} between batches of
+     * `warmerBatchSize` docs so the foreground stays responsive.
+     *
+     * Cancellable via {@link stopBackgroundWarmer} or by passing an
+     * external {@link AbortSignal}. Cancellation is observed at batch
+     * boundaries; the in-flight doc is allowed to complete.
+     */
+    startBackgroundWarmer(options?: StartBackgroundWarmerOptions): Promise<void>;
+    /**
+     * Returns a snapshot of the most recent background warmer pass's
+     * progress, or `null` if no warmer has ever run on this instance.
+     *
+     * The returned object is the live snapshot used internally by
+     * {@link runBackgroundWarmer}; callers MUST NOT mutate it. The snapshot
+     * is replaced (not mutated in place) on the next
+     * {@link startBackgroundWarmer} call, so consumers polling this
+     * method see consistent integer readings.
+     *
+     * @see startBackgroundWarmer
+     */
+    getBackgroundWarmerProgress(): BackgroundWarmerProgress | null;
+    /**
+     * Cancel the in-flight warmer (if any) and wait for it to settle.
+     * Safe to call when no warmer is running - returns a resolved
+     * promise immediately.
+     */
+    stopBackgroundWarmer(): Promise<void>;
+    /**
+     * Body of one warmer pass. Pulled out so {@link startBackgroundWarmer}
+     * can wrap it in single-flight + abort plumbing without nesting.
+     *
+     * Maintains `this.warmerProgress` as a fresh snapshot for
+     * {@link getBackgroundWarmerProgress} consumers and invokes
+     * `onProgress` once per scheduler yield (per `warmerBatchSize` docs)
+     * plus once at the end of the pass with the terminal phase.
+     */
+    private runBackgroundWarmer;
     /**
      * Internal method to load a document from the content-addressed store
      */
@@ -434,6 +1017,11 @@ export declare class BaseMindooDB implements MindooDB {
      * Internal method to add an attachment by chunking the file and storing chunks.
      */
     private addAttachmentInternal;
+    private pendingAttachmentUploadLedgerId;
+    private putEntriesWithRetry;
+    private createPendingAttachmentUploadLedger;
+    private clearPendingAttachmentUploadLedger;
+    private cleanupIncompleteAttachmentUpload;
     /**
      * Internal method to add an attachment from a streaming data source.
      * Memory efficient - processes data chunk by chunk without loading entire file into memory.