mindoodb 0.0.19 → 0.0.21

package/dist/core/BaseMindooDB.js

@@ -11,19 +11,59 @@ const types_2 = require("./appendonlystores/types");
 const bloom_1 = require("./appendonlystores/bloom");
 const MaterializationPlanner_1 = require("./appendonlystores/MaterializationPlanner");
 const DocumentDagAnalysis_1 = require("./DocumentDagAnalysis");
+const DocumentConflictAnalysis_1 = require("./DocumentConflictAnalysis");
 const AttachmentReadPlanner_1 = require("./appendonlystores/AttachmentReadPlanner");
 const idGeneration_1 = require("./utils/idGeneration");
 const errors_1 = require("./errors");
 const logging_1 = require("./logging");
+const databaseIdValidation_1 = require("./databaseIdValidation");
 /**
  * Default chunk size for attachments: 256KB
  */
 const DEFAULT_CHUNK_SIZE_BYTES = 256 * 1024;
+const ATTACHMENT_WRITE_BATCH_BYTES = 16 * 1024 * 1024;
+const ATTACHMENT_WRITE_RETRY_DELAYS_MS = [50, 250, 1000];
 const DEFAULT_ATTACHMENT_STREAM_BATCH_SIZE = 4;
 const DEFAULT_SNAPSHOT_MIN_CHANGES = 100;
 const DEFAULT_SNAPSHOT_COOLDOWN_MS = 10 * 60 * 1000;
 const DEFAULT_MAX_CACHED_DOCS = 128;
 const DEFAULT_ITERATE_PREFETCH_WINDOW_DOCS = 0;
+const DEFAULT_WARMER_BATCH_SIZE = 50;
+/**
+ * Default number of cached documents fetched per `getMany` batch during
+ * the eager startup restore. 256 is a balance between IDB transaction
+ * overhead (favours larger batches) and transient memory pressure
+ * during decryption (favours smaller batches): at ~50 KB/doc this is
+ * roughly 25 MB of transient encrypted+decrypted bytes per batch.
+ * Tunable via {@link DocumentCacheConfig.restoreBatchSize}.
+ */
+const DEFAULT_RESTORE_BATCH_SIZE = 256;
+/**
+ * Default {@link WarmerScheduler}: a simple `setTimeout(0)` yield that
+ * works in Node, browsers, and React Native without pulling in any
+ * runtime-specific APIs.
+ */
+const DEFAULT_WARMER_SCHEDULER = {
+    yield() {
+        return new Promise((resolve) => setTimeout(resolve, 0));
+    },
+};
+/**
+ * On-disk format version for L2 (persisted) document cache records.
+ *
+ * v1 (implicit): legacy header with `id, createdAt, lastModified,
+ * decryptionKeyId, isDeleted` only. No version field.
+ *
+ * v2: explicit `version: 2` header, plus `changeSeq` and
+ * `automergeHeads` so the L2 read path can detect freshness without
+ * touching the document store, and apply only missing changes when
+ * stale (see Phase 1c of the L1/L2 cache plan).
+ *
+ * v1 records are silently ignored on restore - the next read of that
+ * doc falls through to the normal materialization path and re-flushes
+ * with a v2 header.
+ */
+const DOC_CACHE_HEADER_VERSION = 2;
 /**
  * Hard-coded initial Automerge change bytes that seed every document created
  * with a caller-provided id (`createDocument({ id })`).
@@ -88,7 +128,7 @@ function getCustomIdInitialChangeBytes() {
  * - Automerge.applyChanges(doc, changes) - verify method signature
  */
 class BaseMindooDB {
-    constructor(tenant, store, attachmentStore, attachmentConfig, documentCacheConfig, snapshotConfig, adminOnlyDb = false, logger, performanceCallback) {
+    constructor(tenant, store, attachmentStore, attachmentConfig, documentCacheConfig, snapshotConfig, adminOnlyDb = false, logger, performanceCallback, timeTravelDate = null) {
         // Internal changefeed index: sorted by (changeSeq, docId) for deterministic iteration.
         // lastModified remains available for UX metadata but is not the primary cursor key.
         this.index = [];
@@ -111,6 +151,46 @@ class BaseMindooDB {
         this.cachePrefix = null;
         this.dirtyDocIds = new Set();
         this.cacheMetaDirty = false;
+        /**
+         * 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.
+         */
+        this.lastReconciledKeyBagFingerprint = null;
+        /**
+         * 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.
+         */
+        this.warmerPromise = null;
+        /**
+         * AbortController for the in-flight warmer. `null` when no warmer is
+         * running. {@link stopBackgroundWarmer} aborts via this controller.
+         */
+        this.warmerAbort = null;
+        /**
+         * 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.
+         */
+        this.warmerProgress = null;
+        (0, databaseIdValidation_1.validateDatabaseId)(store.getId(), "dbId");
+        (0, databaseIdValidation_1.validateDatabaseId)(attachmentStore.getId(), "dbId");
+        if (store.getId() !== attachmentStore.getId()) {
+            throw new Error(`[BaseMindooDB] Expected document and attachment stores to share dbId but received ${store.getId()} and ${attachmentStore.getId()}`);
+        }
         if (store.getStoreKind() !== types_2.StoreKind.docs) {
             throw new Error(`[BaseMindooDB] Expected primary store kind ${types_2.StoreKind.docs} but received ${store.getStoreKind()}`);
         }
@@ -122,11 +202,17 @@ class BaseMindooDB {
         this.attachmentStore = attachmentStore;
         this.chunkSizeBytes = attachmentConfig?.chunkSizeBytes ?? DEFAULT_CHUNK_SIZE_BYTES;
         this._isAdminOnlyDb = adminOnlyDb;
+        this.timeTravelDate = timeTravelDate;
         this.maxCachedDocs = Math.max(1, Math.floor(documentCacheConfig?.maxEntries ?? DEFAULT_MAX_CACHED_DOCS));
         this.iteratePrefetchWindowDocs = Math.max(0, Math.floor(documentCacheConfig?.iteratePrefetchWindowDocs ??
             DEFAULT_ITERATE_PREFETCH_WINDOW_DOCS));
         this.cacheRestoreLimit = Math.max(1, Math.floor(documentCacheConfig?.restoreLimit ?? this.maxCachedDocs));
+        this.cacheRestoreBatchSize = Math.max(1, Math.floor(documentCacheConfig?.restoreBatchSize ?? DEFAULT_RESTORE_BATCH_SIZE));
         this.reconcileRestoredIndexOnInit = documentCacheConfig?.reconcileRestoredIndexOnInit ?? false;
+        this.restoreToL2 = documentCacheConfig?.restoreToL2 ?? false;
+        this.warmerBatchSize = Math.max(1, Math.floor(documentCacheConfig?.warmer?.batchSize ?? DEFAULT_WARMER_BATCH_SIZE));
+        this.warmerScheduler =
+            documentCacheConfig?.warmer?.scheduler ?? DEFAULT_WARMER_SCHEDULER;
         this.snapshotMinChanges = Math.max(1, Math.floor(snapshotConfig?.minChanges ?? DEFAULT_SNAPSHOT_MIN_CHANGES));
         this.snapshotCooldownMs = Math.max(0, Math.floor(snapshotConfig?.cooldownMs ?? DEFAULT_SNAPSHOT_COOLDOWN_MS));
         // Create logger if not provided (for backward compatibility)
@@ -145,6 +231,39 @@ class BaseMindooDB {
     isAdminOnlyDb() {
         return this._isAdminOnlyDb;
     }
+    isTimeTravelMode() {
+        return this.timeTravelDate !== null;
+    }
+    isReadOnly() {
+        return this.isTimeTravelMode();
+    }
+    getTimeTravelDate() {
+        return this.timeTravelDate;
+    }
+    assertWritable(operation) {
+        if (this.isReadOnly()) {
+            throw new Error(`${operation} is not allowed because database "${this.store.getId()}" is opened in time travel read-only mode.`);
+        }
+    }
+    metadataVisibleAtTimeTravelDate(metadata) {
+        return this.timeTravelDate == null || metadata.createdAt < this.timeTravelDate;
+    }
+    applyTimeTravelFilter(metadata) {
+        return this.timeTravelDate == null ? metadata : metadata.filter((entry) => this.metadataVisibleAtTimeTravelDate(entry));
+    }
+    mergeTimeTravelScanFilters(filters) {
+        if (this.timeTravelDate == null) {
+            return filters;
+        }
+        const existingUntil = filters?.creationDateUntil ?? null;
+        const creationDateUntil = existingUntil == null
+            ? this.timeTravelDate
+            : Math.min(existingUntil, this.timeTravelDate);
+        return {
+            ...filters,
+            creationDateUntil,
+        };
+    }
     // ---------------------------------------------------------------------------
     // Local cache support (ICacheable)
     // ---------------------------------------------------------------------------
@@ -166,7 +285,9 @@ class BaseMindooDB {
     clearDirty() {
         this.dirtyDocIds.clear();
         this.cacheMetaDirty = false;
-        this.evictCachedDocsIfNeeded();
+        // Safe to use the sync eviction here: a successful flush has just
+        // drained `dirtyDocIds`, so there is nothing left to flush-before-evict.
+        this.evictCleanCachedDocsIfNeeded();
     }
     markDocDirty(docId) {
         this.dirtyDocIds.add(docId);
@@ -185,11 +306,69 @@ class BaseMindooDB {
         this.docCache.delete(docId);
         this.docCache.set(docId, internalDoc);
     }
-    storeCachedDocument(internalDoc) {
+    async storeCachedDocument(internalDoc) {
         this.touchCachedDocument(internalDoc.id, internalDoc);
-        this.evictCachedDocsIfNeeded(new Set([internalDoc.id]));
+        await this.evictCachedDocsIfNeeded(new Set([internalDoc.id]));
+    }
+    /**
+     * 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.
+     */
+    async evictCachedDocsIfNeeded(protectedDocIds) {
+        if (this.docCache.size <= this.maxCachedDocs) {
+            return;
+        }
+        const store = this.cacheManager?.getStore() ?? null;
+        const prefix = store ? this.getCachePrefix() : null;
+        // Snapshot the iteration order to avoid surprises if a flush ever
+        // re-touches a doc mid-loop. Map iteration in insertion order is the
+        // LRU eviction order we want.
+        const candidates = [];
+        for (const docId of this.docCache.keys()) {
+            candidates.push(docId);
+        }
+        for (const docId of candidates) {
+            if (this.docCache.size <= this.maxCachedDocs) {
+                break;
+            }
+            if (protectedDocIds?.has(docId)) {
+                continue;
+            }
+            if (store && prefix && this.dirtyDocIds.has(docId)) {
+                const internal = this.docCache.get(docId);
+                if (internal) {
+                    try {
+                        await this.flushDirtyDocToCache(store, prefix, docId, internal);
+                    }
+                    catch (e) {
+                        this.logger.warn(`Flush-before-evict failed for doc ${docId}; dropping dirty marker without persisting: ${e}`);
+                    }
+                }
+            }
+            this.docCache.delete(docId);
+            this.dirtyDocIds.delete(docId);
+        }
     }
-    evictCachedDocsIfNeeded(protectedDocIds) {
+    /**
+     * 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.
+     */
+    evictCleanCachedDocsIfNeeded(protectedDocIds) {
         if (this.docCache.size <= this.maxCachedDocs) {
             return;
         }
@@ -214,22 +393,7 @@ class BaseMindooDB {
             const internal = this.docCache.get(docId);
             if (!internal)
                 continue;
-            const amBinary = automerge_adapter_1.Automerge.save(internal.doc);
-            const header = JSON.stringify({
-                id: internal.id,
-                createdAt: internal.createdAt,
-                lastModified: internal.lastModified,
-                decryptionKeyId: internal.decryptionKeyId,
-                isDeleted: internal.isDeleted,
-            });
-            const headerBytes = new TextEncoder().encode(header);
-            // Format: 4-byte header length (big-endian) + header JSON + Automerge binary
-            const value = new Uint8Array(4 + headerBytes.length + amBinary.length);
-            const view = new DataView(value.buffer);
-            view.setUint32(0, headerBytes.length, false);
-            value.set(headerBytes, 4);
-            value.set(amBinary, 4 + headerBytes.length);
-            await store.put("doc", `${prefix}/${docId}`, value);
+            await this.flushDirtyDocToCache(store, prefix, docId, internal);
             written++;
         }
         // Write metadata checkpoint
@@ -238,6 +402,50 @@ class BaseMindooDB {
         written++;
         return written;
     }
+    /**
+     * 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.
+     */
+    async flushDirtyDocToCache(store, prefix, docId, internal) {
+        const amBinary = automerge_adapter_1.Automerge.save(internal.doc);
+        const indexEntryIdx = this.indexLookup.get(docId);
+        const changeSeq = indexEntryIdx === undefined
+            ? 0
+            : this.index[indexEntryIdx].changeSeq;
+        const automergeHeads = automerge_adapter_1.Automerge.getHeads(internal.doc);
+        const header = JSON.stringify({
+            version: DOC_CACHE_HEADER_VERSION,
+            id: internal.id,
+            createdAt: internal.createdAt,
+            lastModified: internal.lastModified,
+            decryptionKeyId: internal.decryptionKeyId,
+            isDeleted: internal.isDeleted,
+            changeSeq,
+            automergeHeads,
+        });
+        const headerBytes = new TextEncoder().encode(header);
+        // Format: 4-byte header length (big-endian) + header JSON + Automerge binary
+        const value = new Uint8Array(4 + headerBytes.length + amBinary.length);
+        const view = new DataView(value.buffer);
+        view.setUint32(0, headerBytes.length, false);
+        value.set(headerBytes, 4);
+        value.set(amBinary, 4 + headerBytes.length);
+        await store.put("doc", `${prefix}/${docId}`, value);
+    }
     exportMetadataCheckpoint() {
         const checkpoint = {
             version: 2,
@@ -255,6 +463,13 @@ class BaseMindooDB {
         if (!this.supportsCursorScan(this.store)) {
             checkpoint.processedEntryIds = this.processedEntryIds;
         }
+        // Persist the KeyBag fingerprint observed at the last reconciliation
+        // so the next restore can decide whether to skip the visibility
+        // metadata scan. `null` is acceptable - older checkpoints simply
+        // force one reconcile on the next startup.
+        if (this.lastReconciledKeyBagFingerprint !== null) {
+            checkpoint.keyBagFingerprint = this.lastReconciledKeyBagFingerprint;
+        }
         return new TextEncoder().encode(JSON.stringify(checkpoint));
     }
     /**
@@ -281,12 +496,20 @@ class BaseMindooDB {
             if (checkpoint.processedEntryIds) {
                 this.processedEntryIds = checkpoint.processedEntryIds;
             }
+            this.lastReconciledKeyBagFingerprint =
+                typeof checkpoint.keyBagFingerprint === "string" ? checkpoint.keyBagFingerprint : null;
             // Rebuild indexLookup from index
             this.indexLookup.clear();
             for (let i = 0; i < this.index.length; i++) {
                 if (typeof this.index[i].changeSeq !== "number") {
                     this.index[i].changeSeq = i + 1;
                 }
+                if (!this.index[i].decryptionKeyId) {
+                    this.index[i].decryptionKeyId = "default";
+                }
+                if (!this.index[i].accessState) {
+                    this.index[i].accessState = "visible";
+                }
                 this.indexLookup.set(this.index[i].docId, i);
             }
             if (this.index.length > 0 && this.nextChangeSeq <= this.index.length) {
@@ -302,26 +525,71 @@ class BaseMindooDB {
             // 3. Load cached documents
             const docIds = await store.list("doc");
             const docPrefix = `${prefix}/`;
+            const allOwnedKeys = docIds.filter((id) => id.startsWith(docPrefix));
+            if (this.restoreToL2) {
+                // L2-only restore: leave L1 empty; let lazy reads via
+                // tryLoadFromL2 promote individual docs as they are needed. We
+                // still log how many records are sitting in L2 so operators can
+                // sanity-check cache size.
+                this.logger.info(`restoreToL2 enabled for ${prefix}: deferring L1 fill; ${allOwnedKeys.length} cached document records will load lazily on demand`);
+                return true;
+            }
+            // Eager restore mode (default): bulk-load doc records via the
+            // batched getMany API. This avoids N independent IndexedDB
+            // transactions for N docs while preserving exactly the legacy
+            // semantics (capped by `cacheRestoreLimit`, populates L1). The
+            // batch size is bounded by `cacheRestoreBatchSize` so that the
+            // transient encrypted+decrypted byte buffers held in memory at
+            // any one time stay predictable - see
+            // `DocumentCacheConfig.restoreBatchSize`.
+            const targetKeys = allOwnedKeys.slice(0, this.cacheRestoreLimit);
             let restoredDocs = 0;
-            for (const id of docIds) {
+            let skippedLegacyDocs = 0;
+            for (let offset = 0; offset < targetKeys.length; offset += this.cacheRestoreBatchSize) {
                 if (restoredDocs >= this.cacheRestoreLimit) {
                     break;
                 }
-                if (!id.startsWith(docPrefix))
-                    continue;
-                const docId = id.slice(docPrefix.length);
-                const docBytes = await store.get("doc", id);
-                if (!docBytes)
-                    continue;
-                try {
-                    const internal = this.deserializeDoc(docBytes);
-                    this.storeCachedDocument(internal);
-                    restoredDocs++;
-                }
-                catch (e) {
-                    this.logger.warn(`Failed to restore cached doc ${docId}, will reload from store: ${e}`);
+                const batch = targetKeys.slice(offset, offset + this.cacheRestoreBatchSize);
+                const batchValues = await store.getMany("doc", batch);
+                for (let i = 0; i < batch.length; i++) {
+                    if (restoredDocs >= this.cacheRestoreLimit) {
+                        break;
+                    }
+                    const docBytes = batchValues[i];
+                    if (!docBytes)
+                        continue;
+                    try {
+                        const deserialized = this.deserializeDoc(docBytes);
+                        if (deserialized === null) {
+                            skippedLegacyDocs++;
+                            continue;
+                        }
+                        // Defence-in-depth: an L2 record holds the decrypted Automerge
+                        // state. If the current KeyBag can no longer resolve the doc's
+                        // key (e.g. the user lost access between sessions) we evict
+                        // both the L2 record and any L1 entry instead of restoring
+                        // plaintext into memory. The post-restore call to
+                        // `reconcileKeyVisibility` will then flip the index entry to
+                        // `"inaccessible"` so future reads behave correctly.
+                        const canRead = await this.tenant.hasDecryptionKey(deserialized.internal.decryptionKeyId);
+                        if (!canRead) {
+                            const docId = batch[i].slice(docPrefix.length);
+                            await store.delete("doc", batch[i]);
+                            this.docCache.delete(docId);
+                            continue;
+                        }
+                        await this.storeCachedDocument(deserialized.internal);
+                        restoredDocs++;
+                    }
+                    catch (e) {
+                        const docId = batch[i].slice(docPrefix.length);
+                        this.logger.warn(`Failed to restore cached doc ${docId}, will reload from store: ${e}`);
+                    }
                 }
             }
+            if (skippedLegacyDocs > 0) {
+                this.logger.info(`Skipped ${skippedLegacyDocs} legacy (v1) cached documents during restore; they will be re-flushed in v2 format on next access.`);
+            }
             this.logger.info(`Restored ${restoredDocs} cached documents for ${this.store.getId()}`);
             this.logger.info(`Restored ${restoredDocs} documents from cache for ${prefix}`);
             return true;
@@ -331,14 +599,29 @@ class BaseMindooDB {
             return false;
         }
     }
+    /**
+     * 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).
+     */
     deserializeDoc(value) {
         const view = new DataView(value.buffer, value.byteOffset, value.byteLength);
         const headerLen = view.getUint32(0, false);
         const headerBytes = value.slice(4, 4 + headerLen);
         const amBinary = value.slice(4 + headerLen);
         const header = JSON.parse(new TextDecoder().decode(headerBytes));
+        if (header.version !== DOC_CACHE_HEADER_VERSION) {
+            // v1 records (no `version`) and unknown future versions: skip
+            // gracefully so they get re-flushed with the current header on
+            // the next dirty cycle.
+            return null;
+        }
         const doc = automerge_adapter_1.Automerge.load(amBinary);
-        return {
+        const internal = {
             id: header.id,
             doc,
             createdAt: header.createdAt,
@@ -346,6 +629,11 @@ class BaseMindooDB {
             decryptionKeyId: header.decryptionKeyId,
             isDeleted: header.isDeleted,
         };
+        return {
+            internal,
+            persistedChangeSeq: typeof header.changeSeq === "number" ? header.changeSeq : 0,
+            persistedHeads: Array.isArray(header.automergeHeads) ? header.automergeHeads : [],
+        };
     }
     /**
      * Get or import a CryptoKey for signature verification, with caching.
@@ -398,25 +686,45 @@ class BaseMindooDB {
     }
     /**
      * 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
      */
-    updateIndex(docId, lastModified, isDeleted) {
+    updateIndex(docId, lastModified, isDeleted, decryptionKeyId = "default", accessState = "visible") {
         const startedAt = Date.now();
         const assignedSeq = this.nextChangeSeq;
-        const newEntry = { docId, changeSeq: assignedSeq, lastModified, isDeleted };
+        const newEntry = {
+            docId,
+            changeSeq: assignedSeq,
+            lastModified,
+            isDeleted,
+            decryptionKeyId,
+            accessState,
+        };
         const existingIndex = this.indexLookup.get(docId);
         // Check if the entry already exists and hasn't changed position
         if (existingIndex !== undefined) {
             const existingEntry = this.index[existingIndex];
             // If only metadata flags stayed identical and caller replays same state, skip.
-            if (existingEntry.lastModified === lastModified && existingEntry.isDeleted === isDeleted) {
+            if (existingEntry.lastModified === lastModified
+                && existingEntry.isDeleted === isDeleted
+                && existingEntry.decryptionKeyId === decryptionKeyId
+                && existingEntry.accessState === accessState) {
                 return; // No change needed
             }
             // Remove from current position
@@ -592,6 +900,23 @@ class BaseMindooDB {
             if (restored) {
                 this.logger.info("Restored from cache, processing delta only");
                 await this.syncStoreChanges();
+                // Visibility reconciliation runs a full metadata scan over the
+                // store, which on a remote store is one or more REST round-trips.
+                // Skip it on warm starts when we can prove the KeyBag composition
+                // has not changed since the last flush by comparing fingerprints.
+                // Fall back to the unconditional reconcile when the tenant does
+                // not expose a fingerprint so we never silently miss a key
+                // transition.
+                const currentFingerprint = await this.computeCurrentKeyBagFingerprint();
+                const fingerprintMatches = currentFingerprint !== null && currentFingerprint === this.lastReconciledKeyBagFingerprint;
+                if (!fingerprintMatches) {
+                    await this.reconcileKeyVisibility();
+                }
+                this.markKeyBagFingerprintReconciled(currentFingerprint);
+                // If `reconcileRestoredIndexOnInit` triggers a full rebuild,
+                // that rebuild reruns `syncStoreChanges` from scratch, which
+                // applies per-doc visibility checks itself. We do not need to
+                // call `reconcileKeyVisibility` again afterwards.
                 if (this.reconcileRestoredIndexOnInit) {
                     await this.reconcileRestoredIndexWithStore();
                 }
@@ -599,6 +924,195 @@ class BaseMindooDB {
             }
         }
         await this.syncStoreChanges();
+        // First-time materialization: `syncStoreChanges` already filters out
+        // docs whose keys are unavailable, so the only thing left to do is
+        // record the current fingerprint for the next warm start.
+        this.markKeyBagFingerprintReconciled(await this.computeCurrentKeyBagFingerprint());
+    }
+    /**
+     * Compute the current tenant KeyBag fingerprint, or `null` when the
+     * tenant does not expose one (older `MindooTenant` implementations).
+     */
+    async computeCurrentKeyBagFingerprint() {
+        if (typeof this.tenant.getDocKeyFingerprint !== "function") {
+            return null;
+        }
+        return this.tenant.getDocKeyFingerprint();
+    }
+    /**
+     * 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.
+     */
+    markKeyBagFingerprintReconciled(fingerprint) {
+        if (this.lastReconciledKeyBagFingerprint === fingerprint) {
+            return;
+        }
+        this.lastReconciledKeyBagFingerprint = fingerprint;
+        this.cacheMetaDirty = true;
+        this.cacheManager?.markDirty();
+    }
+    /**
+     * 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.
+     */
+    deriveDocumentVisibilityMetadata(metadata) {
+        const lifecycleEntries = metadata.filter((entry) => entry.entryType === "doc_create"
+            || entry.entryType === "doc_change"
+            || entry.entryType === "doc_delete"
+            || entry.entryType === "doc_undelete"
+            || entry.entryType === "doc_snapshot");
+        if (lifecycleEntries.length === 0) {
+            return null;
+        }
+        lifecycleEntries.sort((left, right) => left.createdAt !== right.createdAt ? left.createdAt - right.createdAt : left.id.localeCompare(right.id));
+        const replayEntries = metadata.filter((entry) => this.isDocumentReplayEntry(entry));
+        const entriesForLastModified = replayEntries.length > 0 ? replayEntries : lifecycleEntries;
+        return {
+            decryptionKeyId: lifecycleEntries[0].decryptionKeyId,
+            lastModified: Math.max(...entriesForLastModified.map((entry) => entry.createdAt)),
+            isDeleted: this.computeIsDeletedFromMetadata(metadata),
+        };
+    }
+    /**
+     * 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.
+     */
+    async purgeMaterializedDocument(docId) {
+        this.docCache.delete(docId);
+        this.dirtyDocIds.delete(docId);
+        this.automergeHashToEntryId.delete(docId);
+        const store = this.cacheManager?.getStore();
+        if (store) {
+            try {
+                await store.delete("doc", `${this.getCachePrefix()}/${docId}`);
+            }
+            catch (error) {
+                // Best-effort: failure to evict the L2 record only means a stale
+                // cached doc may linger on disk; the index entry below still
+                // marks the doc inaccessible so read paths refuse to surface it.
+                this.logger.warn(`Failed to evict L2 cache record for inaccessible doc ${docId}: ${error}`);
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    async reconcileKeyVisibility() {
+        if (this.isTimeTravelMode()) {
+            return;
+        }
+        const lifecycleMetadata = await this.scanAllMetadata(this.store);
+        const metadataByDoc = new Map();
+        for (const entry of lifecycleMetadata) {
+            if (entry.entryType !== "doc_create"
+                && entry.entryType !== "doc_change"
+                && entry.entryType !== "doc_delete"
+                && entry.entryType !== "doc_undelete"
+                && entry.entryType !== "doc_snapshot") {
+                continue;
+            }
+            const entries = metadataByDoc.get(entry.docId) ?? [];
+            entries.push(entry);
+            metadataByDoc.set(entry.docId, entries);
+        }
+        let changed = false;
+        // Deterministic ordering by docId keeps the resulting changefeed
+        // stable between runs, which simplifies test expectations.
+        const docIds = Array.from(metadataByDoc.keys()).sort((left, right) => left.localeCompare(right));
+        for (const docId of docIds) {
+            const visibility = this.deriveDocumentVisibilityMetadata(metadataByDoc.get(docId));
+            if (!visibility) {
+                continue;
+            }
+            const existingIndex = this.indexLookup.get(docId);
+            const existing = existingIndex === undefined ? undefined : this.index[existingIndex];
+            const canRead = await this.tenant.hasDecryptionKey(visibility.decryptionKeyId);
+            if (canRead) {
+                // Reveal-on-add only triggers when the previous state was
+                // missing or inaccessible; visible->visible transitions stay
+                // idempotent via the existing `updateIndex` short-circuit.
+                if (!existing || existing.accessState === "inaccessible") {
+                    this.updateIndex(docId, visibility.lastModified, visibility.isDeleted, visibility.decryptionKeyId, "visible");
+                    changed = true;
+                }
+                continue;
+            }
+            if (existing?.accessState === "visible") {
+                // Key was revoked while we still had plaintext state in cache:
+                // wipe it and flip the index entry to an inaccessible tombstone
+                // with `isDeleted: true` so view feeds emit a clean removal.
+                await this.purgeMaterializedDocument(docId);
+                this.updateIndex(docId, visibility.lastModified, true, visibility.decryptionKeyId, "inaccessible");
+                changed = true;
+            }
+            else {
+                // Already inaccessible (or never seen). Scrub defensively in
+                // case a previous session left an L2 record behind.
+                await this.purgeMaterializedDocument(docId);
+            }
+        }
+        if (changed) {
+            this.cacheMetaDirty = true;
+            this.cacheManager?.markDirty();
+        }
+        // Whatever path triggered the reconcile (init, KeyBag listener,
+        // explicit caller), record the fingerprint observed during this
+        // pass so a subsequent warm start with identical bag composition
+        // can skip the scan.
+        this.markKeyBagFingerprintReconciled(await this.computeCurrentKeyBagFingerprint());
     }
     async reconcileRestoredIndexWithStore() {
         const lifecycleMetadata = await this.scanAllMetadata(this.store);
@@ -633,6 +1147,12 @@ class BaseMindooDB {
      * 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.
      */
     async syncStoreChanges() {
         const syncStartedAt = Date.now();
@@ -682,7 +1202,7 @@ class BaseMindooDB {
                         if (updatedDoc) {
                             this.logger.debug(`Successfully updated cached document ${docId} incrementally`);
                             // Only update index if document actually changed
-                            this.updateIndex(docId, updatedDoc.lastModified, updatedDoc.isDeleted);
+                            this.updateIndex(docId, updatedDoc.lastModified, updatedDoc.isDeleted, updatedDoc.decryptionKeyId, "visible");
                             this.logger.debug(`Updated index for document ${docId} (lastModified: ${updatedDoc.lastModified}, isDeleted: ${updatedDoc.isDeleted})`);
                         }
                         else {
@@ -695,7 +1215,7 @@ class BaseMindooDB {
                         this.docCache.delete(docId);
                         updatedDoc = await this.loadDocumentInternal(docId);
                         if (updatedDoc) {
-                            this.updateIndex(docId, updatedDoc.lastModified, updatedDoc.isDeleted);
+                            this.updateIndex(docId, updatedDoc.lastModified, updatedDoc.isDeleted, updatedDoc.decryptionKeyId, "visible");
                         }
                     }
                 }
@@ -728,19 +1248,58 @@ class BaseMindooDB {
                             const entriesForLastModified = mutationEntries.length > 0 ? mutationEntries : docLifecycleEntries;
                             const lastModified = Math.max(...entriesForLastModified.map((e) => e.createdAt));
                             const isDeleted = this.computeIsDeletedFromMetadata(allDocMetadata);
-                            this.updateIndex(docId, lastModified, isDeleted);
+                            this.updateIndex(docId, lastModified, isDeleted, representativeEntry.decryptionKeyId, "visible");
                             this.logger.debug(`Metadata-first update for uncached doc ${docId} (lastModified: ${lastModified}, isDeleted: ${isDeleted})`);
                         }
                     }
                 }
             }
             catch (error) {
-                // Handle missing symmetric key gracefully - skip documents we can't decrypt
+                // Missing symmetric key during live sync: the doc exists in the
+                // store but we cannot decrypt it. Treat this as a visibility
+                // transition rather than a hard failure:
+                //  - If the doc had previously been visible, purge any plaintext
+                //    we still hold and flip the index entry to `"inaccessible"`
+                //    with a deletion tombstone so view feeds remove it cleanly.
+                //  - If the doc was never visible (first time we see it without
+                //    a key), we simply skip; `reconcileKeyVisibility` will mark
+                //    it appropriately the next time it runs.
+                // Either way we advance the processed-entries marker so a
+                // subsequent sync doesn't endlessly retry the same untranslatable
+                // doc.
                 if (error instanceof errors_1.SymmetricKeyNotFoundError) {
                     this.logger.debug(`Skipping document ${docId} - missing key: ${error.keyId}`);
-                    // Mark entry IDs as processed so we don't retry them
+                    // Avoid a per-doc scanAllMetadata round-trip here: everything
+                    // we need is already in this batch's entryMetadataList plus the
+                    // existing index entry (if any). We do NOT need a second pass
+                    // over the underlying store - the key is missing, so we just
+                    // record an inaccessibility tombstone.
+                    const existingIndex = this.indexLookup.get(docId);
+                    const existing = existingIndex === undefined ? undefined : this.index[existingIndex];
+                    if (existing?.accessState === "visible") {
+                        const lifecycleEntriesInBatch = entryMetadataList.filter((entry) => entry.entryType === "doc_create"
+                            || entry.entryType === "doc_change"
+                            || entry.entryType === "doc_delete"
+                            || entry.entryType === "doc_undelete"
+                            || entry.entryType === "doc_snapshot");
+                        // Prefer a lifecycle entry from the failing batch for the
+                        // key id (they all share the same `decryptionKeyId` for a
+                        // doc), then fall back to any entry, then to the existing
+                        // index entry. One of these must be present whenever we
+                        // reach this branch.
+                        const representative = lifecycleEntriesInBatch[0] ?? entryMetadataList[0];
+                        const decryptionKeyId = representative?.decryptionKeyId ?? existing.decryptionKeyId;
+                        const batchLastModified = entryMetadataList.length > 0
+                            ? Math.max(...entryMetadataList.map((entry) => entry.createdAt))
+                            : 0;
+                        const lastModified = Math.max(existing.lastModified, batchLastModified);
+                        await this.purgeMaterializedDocument(docId);
+                        this.updateIndex(docId, lastModified, true, decryptionKeyId, "inaccessible");
+                        this.cacheMetaDirty = true;
+                        this.cacheManager?.markDirty();
+                    }
                     this.processedEntryIds.push(...entryMetadataList.map(em => em.id));
-                    return; // Skip this document
+                    return;
                 }
                 this.logger.error(`===== ERROR processing document ${docId} in syncStoreChanges =====`, error);
                 // Re-throw the error so we can see what's happening in the test
@@ -791,16 +1350,31 @@ class BaseMindooDB {
         return typeof store.scanEntriesSince === "function";
     }
     async scanAllMetadata(store, filters) {
+        const effectiveFilters = this.mergeTimeTravelScanFilters(filters);
         if (!this.supportsCursorScan(store)) {
+            let entries;
             if (filters?.docId) {
-                return store.findNewEntriesForDoc([], filters.docId);
+                entries = await store.findNewEntriesForDoc([], filters.docId);
             }
-            return store.findNewEntries([]);
+            else {
+                entries = await store.findNewEntries([]);
+            }
+            if (effectiveFilters?.entryTypes?.length) {
+                const allowedTypes = new Set(effectiveFilters.entryTypes);
+                entries = entries.filter((entry) => allowedTypes.has(entry.entryType));
+            }
+            if (effectiveFilters?.creationDateFrom != null) {
+                entries = entries.filter((entry) => entry.createdAt >= effectiveFilters.creationDateFrom);
+            }
+            if (effectiveFilters?.creationDateUntil != null) {
+                entries = entries.filter((entry) => entry.createdAt < effectiveFilters.creationDateUntil);
+            }
+            return this.applyTimeTravelFilter(entries);
         }
         const all = [];
         let cursor = null;
         while (true) {
-            const page = await store.scanEntriesSince(cursor, 1000, filters);
+            const page = await store.scanEntriesSince(cursor, 1000, effectiveFilters);
             all.push(...page.entries);
             cursor = page.nextCursor;
             if (!page.hasMore) {
@@ -812,7 +1386,7 @@ class BaseMindooDB {
     async getNewEntryMetadataForSync() {
         const startedAt = Date.now();
         if (!this.supportsCursorScan(this.store)) {
-            const result = await this.store.findNewEntries(this.processedEntryIds);
+            const result = this.applyTimeTravelFilter(await this.store.findNewEntries(this.processedEntryIds));
             this.performanceCallback?.onSyncOperation?.({
                 operation: "findNewEntries",
                 time: Date.now() - startedAt,
@@ -830,7 +1404,7 @@ class BaseMindooDB {
         const allNew = [];
         let cursor = this.processedEntryCursor;
         while (true) {
-            const page = await this.store.scanEntriesSince(cursor, 1000);
+            const page = await this.store.scanEntriesSince(cursor, 1000, this.mergeTimeTravelScanFilters());
             allNew.push(...page.entries);
             cursor = page.nextCursor;
             if (!page.hasMore) {
@@ -1238,6 +1812,50 @@ class BaseMindooDB {
     getAttachmentStore() {
         return this.attachmentStore;
     }
+    async reclaimIncompleteAttachmentUploads(options) {
+        const minAgeMs = options?.minAgeMs ?? 5 * 60 * 1000;
+        const cutoff = Date.now() - minAgeMs;
+        const ledgers = await this.store.findEntries("pending_attachment_upload", null, cutoff);
+        const result = {
+            scannedLedgers: ledgers.length,
+            reclaimedUploads: 0,
+            reclaimedChunks: 0,
+            keptCommittedUploads: 0,
+            keptRecentUploads: 0,
+        };
+        for (const ledger of ledgers) {
+            const attachmentId = ledger.attachmentId;
+            if (!attachmentId) {
+                continue;
+            }
+            if ((ledger.uploadStartedAt ?? ledger.createdAt) > cutoff) {
+                result.keptRecentUploads++;
+                continue;
+            }
+            const liveDoc = await this.getDocument(ledger.docId).catch(() => null);
+            if (liveDoc?.getAttachments().some((attachment) => attachment.attachmentId === attachmentId)) {
+                await this.clearPendingAttachmentUploadLedger(attachmentId);
+                result.keptCommittedUploads++;
+                continue;
+            }
+            const docEntries = await this.scanAllMetadata(this.store, { docId: ledger.docId });
+            const mentionedByHistory = docEntries.some((entry) => entry.attachmentIds?.includes(attachmentId));
+            if (mentionedByHistory) {
+                await this.clearPendingAttachmentUploadLedger(attachmentId);
+                result.keptCommittedUploads++;
+                continue;
+            }
+            const deletedChunks = await this.getEffectiveAttachmentStore()
+                .deleteEntriesForAttachment?.(ledger.docId, attachmentId) ?? 0;
+            await this.clearPendingAttachmentUploadLedger(attachmentId);
+            result.reclaimedUploads++;
+            result.reclaimedChunks += deletedChunks;
+        }
+        if (result.scannedLedgers > 0) {
+            this.logger.info(`[idb-orphan-sweep] reclaimed ${result.reclaimedUploads} incomplete uploads (${result.reclaimedChunks} chunks), kept ${result.keptCommittedUploads} committed, kept ${result.keptRecentUploads} recent`);
+        }
+        return result;
+    }
     getTenant() {
         return this.tenant;
     }
@@ -1270,6 +1888,7 @@ class BaseMindooDB {
      * custom ID converge when synced (see `getCustomIdInitialChangeBytes`).
      */
     async createDocumentInternal(options) {
+        this.assertWritable("createDocument");
         const { signingKeyPair, signingKeyPassword } = options;
         if ((signingKeyPair !== undefined) !== (signingKeyPassword !== undefined)) {
             throw new Error("createDocument: signingKeyPair and signingKeyPassword must be provided together");
@@ -1432,8 +2051,8 @@ class BaseMindooDB {
             isDeleted: false,
         };
         // Update cache and index
-        this.storeCachedDocument(internalDoc);
-        this.updateIndex(docId, internalDoc.lastModified, false);
+        await this.storeCachedDocument(internalDoc);
+        this.updateIndex(docId, internalDoc.lastModified, false, internalDoc.decryptionKeyId, "visible");
         this.markDocDirty(docId);
         this.logger.info(`Document ${docId} created successfully`);
         this.logger.debug(`Document ${docId} cached and indexed (lastModified: ${internalDoc.lastModified})`);
@@ -1912,77 +2531,1081 @@ class BaseMindooDB {
         return result;
     }
     /**
-     * Derives human-readable changed field paths for one DAG entry.
+     * Streams conflict-analysis events for one or more documents.
      *
-     * This compares the branch-local document state at the selected entry with each
-     * reachable parent state, then normalizes array indices so the UI can show stable
-     * paths such as `_attachments[].fileName` instead of raw Automerge op keys only.
+     * 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.
      */
-    async deriveReadableTouchedPaths(docId, entryMetadata, allEntryMetadata, touchedKeys) {
-        if (entryMetadata.entryType === "doc_snapshot") {
-            return [];
-        }
-        const currentDoc = await this.materializeBranchInternalDoc(docId, allEntryMetadata, entryMetadata.id);
-        const currentData = this.getReadableDiffValueForDoc(currentDoc);
-        const parentEntryIds = entryMetadata.dependencyIds.filter((dependencyId) => allEntryMetadata.some((entry) => entry.id === dependencyId));
-        const diffPaths = new Set();
-        if (parentEntryIds.length === 0) {
-            this.collectReadableDiffPaths(undefined, currentData, "", diffPaths);
-        }
-        else {
-            for (const parentEntryId of parentEntryIds) {
-                const parentDoc = await this.materializeBranchInternalDoc(docId, allEntryMetadata, parentEntryId);
-                const parentData = this.getReadableDiffValueForDoc(parentDoc);
-                this.collectReadableDiffPaths(parentData, currentData, "", diffPaths);
+    async *analyzeDocumentConflicts(docIds, options = {}) {
+        const scanCheckpoint = await this.getConflictScanCheckpoint();
+        const candidateDocIds = await this.resolveConflictAnalysisCandidateDocIds(docIds, options);
+        const totalDocs = candidateDocIds.length;
+        let scannedDocs = 0;
+        const mode = options.mode ?? "quick";
+        let lastYieldAt = Date.now();
+        for (const docId of candidateDocIds) {
+            this.throwIfConflictAnalysisAborted(options.signal);
+            const docStartedAt = Date.now();
+            yield { type: "docStart", docId };
+            try {
+                const allEntryMetadata = await this.scanAllMetadata(this.store, { docId });
+                yield {
+                    type: "progress",
+                    scannedDocs,
+                    totalDocs,
+                    docId,
+                    scannedEntries: allEntryMetadata.length,
+                    message: `Scanned conflict metadata for document ${docId}`,
+                };
+                const plan = (0, DocumentConflictAnalysis_1.computeDocumentConflictAnalysisPlan)(docId, allEntryMetadata);
+                let conflictsFound = 0;
+                let hadConflicts = false;
+                if (plan.hasConcurrencyCandidates) {
+                    const maxConflictsPerDoc = options.maxConflictsPerDoc ?? (mode === "quick" ? 1 : undefined);
+                    const detection = await this.detectDocumentConflictsFromPlan(docId, plan, {
+                        ...options,
+                        mode,
+                        maxConflictsPerDoc,
+                    });
+                    for (const conflict of detection.conflicts) {
+                        this.throwIfConflictAnalysisAborted(options.signal);
+                        hadConflicts = true;
+                        conflictsFound += conflict.paths.length;
+                        yield {
+                            type: "conflictDetected",
+                            conflict,
+                            quick: mode === "quick",
+                        };
+                        lastYieldAt = await this.maybeYieldForConflictAnalysis(options.yieldEveryMs, lastYieldAt);
+                    }
+                    if (mode === "full") {
+                        for (const resolution of detection.resolutions) {
+                            this.throwIfConflictAnalysisAborted(options.signal);
+                            yield resolution;
+                            lastYieldAt = await this.maybeYieldForConflictAnalysis(options.yieldEveryMs, lastYieldAt);
+                        }
+                    }
+                }
+                scannedDocs++;
+                yield {
+                    type: "docDone",
+                    docId,
+                    hadConflicts,
+                    conflictsFound,
+                    entriesScanned: allEntryMetadata.length,
+                };
+                this.performanceCallback?.onHistoryOperation?.({
+                    operation: "analyzeDocumentConflicts",
+                    docId,
+                    time: Date.now() - docStartedAt,
+                    scannedEntries: allEntryMetadata.length,
+                    returnedEntries: conflictsFound,
+                    bounded: true,
+                });
             }
-        }
-        const normalizedPaths = Array.from(diffPaths)
-            .map((path) => path.replace(/\[\d+\]/g, "[]"))
-            .filter((path, index, allPaths) => path.length > 0 && allPaths.indexOf(path) === index)
-            .sort();
-        if (normalizedPaths.length === 0) {
-            return [];
-        }
-        const touchedKeySet = new Set(touchedKeys);
-        if (touchedKeySet.size === 0) {
-            return normalizedPaths;
-        }
-        const filteredPaths = normalizedPaths.filter((path) => touchedKeySet.has(this.extractLeafPathSegment(path)));
-        return filteredPaths.length > 0 ? filteredPaths : normalizedPaths;
-    }
-    async getAllDocumentIds() {
-        // Return all non-deleted document IDs from index
-        const docIds = [];
-        for (const entry of this.index) {
-            if (!entry.isDeleted) {
-                docIds.push(entry.docId);
+            catch (error) {
+                if (options.signal?.aborted) {
+                    throw error;
+                }
+                yield { type: "error", docId, error };
+                scannedDocs++;
             }
+            yield {
+                type: "progress",
+                scannedDocs,
+                totalDocs,
+                docId,
+                message: `Completed conflict analysis for document ${docId}`,
+            };
+            lastYieldAt = await this.maybeYieldForConflictAnalysis(options.yieldEveryMs, lastYieldAt);
         }
-        return docIds;
+        yield {
+            type: "scanCheckpoint",
+            checkpoint: scanCheckpoint,
+        };
     }
-    async getDeletedDocumentIds() {
-        const docIds = [];
-        for (const entry of this.index) {
-            if (entry.isDeleted) {
-                docIds.push(entry.docId);
+    /**
+     * 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.
+     */
+    async getDocumentConflictReport(docId, options = {}) {
+        const startedAt = Date.now();
+        const report = {
+            docId,
+            hadConflicts: false,
+            conflictsFound: 0,
+            conflicts: [],
+            resolutions: [],
+            entriesScanned: 0,
+            errors: [],
+            scanCheckpoint: null,
+        };
+        for await (const event of this.analyzeDocumentConflicts([docId], {
+            ...options,
+            mode: "full",
+        })) {
+            if (event.type === "conflictDetected") {
+                report.hadConflicts = true;
+                report.conflicts.push(event.conflict);
+                report.conflictsFound += event.conflict.paths.length;
+            }
+            else if (event.type === "conflictResolved") {
+                report.resolutions.push(event);
+            }
+            else if (event.type === "docDone") {
+                report.entriesScanned = event.entriesScanned;
+            }
+            else if (event.type === "error") {
+                report.errors.push(event);
+            }
+            else if (event.type === "scanCheckpoint") {
+                report.scanCheckpoint = event.checkpoint;
             }
         }
-        return docIds;
+        this.performanceCallback?.onHistoryOperation?.({
+            operation: "getDocumentConflictReport",
+            docId,
+            time: Date.now() - startedAt,
+            scannedEntries: report.entriesScanned,
+            returnedEntries: report.conflictsFound,
+            bounded: true,
+        });
+        return report;
     }
-    async getAllDocumentIdsAtTimestamp(timestamp) {
-        // findEntries() uses an exclusive upper bound (createdAt < creationDateUntil).
-        // Query up to timestamp + 1 so entries created exactly at `timestamp` are included
-        // for the strict checks below (createTime < timestamp, deleteTime > timestamp).
-        const upperBoundExclusive = timestamp === Number.MAX_SAFE_INTEGER ? timestamp : timestamp + 1;
-        // We only need lifecycle metadata for this query. Changes and snapshots can
-        // affect document contents, but create/delete/undelete determine existence.
-        const [creates, deletes, undeletes] = await Promise.all([
-            this.store.findEntries("doc_create", null, upperBoundExclusive),
-            this.store.findEntries("doc_delete", null, upperBoundExclusive),
-            this.store.findEntries("doc_undelete", null, upperBoundExclusive),
-        ]);
-        const lifecycleEntriesByDocId = new Map();
-        const addLifecycleEntry = (entry) => {
+    /**
+     * 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`.
+     */
+    async getDocumentConflictBaseValues(docId, queries) {
+        const startedAt = Date.now();
+        if (queries.length === 0) {
+            this.performanceCallback?.onHistoryOperation?.({
+                operation: "getDocumentConflictBaseValues",
+                docId,
+                time: Date.now() - startedAt,
+                scannedEntries: 0,
+                returnedEntries: 0,
+                bounded: true,
+            });
+            return [];
+        }
+        const allEntryMetadata = await this.scanAllMetadata(this.store, { docId });
+        const metadataById = new Map(allEntryMetadata.map((entry) => [entry.id, entry]));
+        const groups = new Map();
+        for (let index = 0; index < queries.length; index += 1) {
+            const query = queries[index];
+            const parents = this.resolveConflictBaseParents(query.location, metadataById);
+            const key = parents.length === 0 ? "" : parents.slice().sort().join("|");
+            let group = groups.get(key);
+            if (!group) {
+                group = { parents, queries: [] };
+                groups.set(key, group);
+            }
+            group.queries.push({ originalIndex: index, query });
+        }
+        const results = new Array(queries.length);
+        for (const group of groups.values()) {
+            if (group.parents.length === 0) {
+                for (const grouped of group.queries) {
+                    results[grouped.originalIndex] = {
+                        pathString: grouped.query.pathString,
+                        baseEntryId: null,
+                        status: "missing-entry",
+                        preview: null,
+                    };
+                }
+                continue;
+            }
+            const baseEntryId = this.computeConflictMergeBaseEntryId(metadataById, group.parents);
+            if (baseEntryId === null) {
+                for (const grouped of group.queries) {
+                    results[grouped.originalIndex] = {
+                        pathString: grouped.query.pathString,
+                        baseEntryId: null,
+                        status: "no-base",
+                        preview: null,
+                    };
+                }
+                continue;
+            }
+            const internalDoc = await this.materializeBranchInternalDoc(docId, allEntryMetadata, baseEntryId);
+            if (!internalDoc || internalDoc.isDeleted) {
+                for (const grouped of group.queries) {
+                    results[grouped.originalIndex] = {
+                        pathString: grouped.query.pathString,
+                        baseEntryId,
+                        status: "no-prior-value",
+                        preview: null,
+                    };
+                }
+                continue;
+            }
+            for (const grouped of group.queries) {
+                const value = this.readValueAtDocumentPath(internalDoc.doc, grouped.query.path);
+                if (value === undefined) {
+                    results[grouped.originalIndex] = {
+                        pathString: grouped.query.pathString,
+                        baseEntryId,
+                        status: "no-prior-value",
+                        preview: null,
+                    };
+                }
+                else {
+                    results[grouped.originalIndex] = {
+                        pathString: grouped.query.pathString,
+                        baseEntryId,
+                        status: "available",
+                        preview: this.previewChangeValue(value),
+                        value: this.toJsonSafeConflictValue(value),
+                    };
+                }
+            }
+        }
+        this.performanceCallback?.onHistoryOperation?.({
+            operation: "getDocumentConflictBaseValues",
+            docId,
+            time: Date.now() - startedAt,
+            scannedEntries: allEntryMetadata.length,
+            returnedEntries: results.length,
+            bounded: true,
+        });
+        return results;
+    }
+    /**
+     * 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.
+     */
+    resolveConflictBaseParents(location, metadataById) {
+        if (location.kind === "active-heads") {
+            return location.headEntryIds.filter((id) => metadataById.has(id));
+        }
+        if (!location.entryId) {
+            return [];
+        }
+        const entry = metadataById.get(location.entryId);
+        if (!entry) {
+            return [];
+        }
+        return entry.dependencyIds.filter((id) => metadataById.has(id));
+    }
+    /**
+     * 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.
+     */
+    computeConflictMergeBaseEntryId(metadataById, parents) {
+        if (parents.length === 0) {
+            return null;
+        }
+        if (parents.length === 1) {
+            return parents[0];
+        }
+        const ancestorCache = new Map();
+        const collectAncestors = (startId) => {
+            const cached = ancestorCache.get(startId);
+            if (cached) {
+                return cached;
+            }
+            const visited = new Set();
+            const queue = [startId];
+            while (queue.length > 0) {
+                const id = queue.shift();
+                if (visited.has(id)) {
+                    continue;
+                }
+                visited.add(id);
+                const meta = metadataById.get(id);
+                if (!meta) {
+                    continue;
+                }
+                for (const dep of meta.dependencyIds) {
+                    if (!visited.has(dep)) {
+                        queue.push(dep);
+                    }
+                }
+            }
+            ancestorCache.set(startId, visited);
+            return visited;
+        };
+        let common = null;
+        for (const parent of parents) {
+            const ancestors = collectAncestors(parent);
+            if (common === null) {
+                common = new Set(ancestors);
+            }
+            else {
+                const next = new Set();
+                for (const id of common) {
+                    if (ancestors.has(id)) {
+                        next.add(id);
+                    }
+                }
+                common = next;
+            }
+            if (common.size === 0) {
+                return null;
+            }
+        }
+        if (!common || common.size === 0) {
+            return null;
+        }
+        const isProperAncestorOfAnother = new Set();
+        for (const id of common) {
+            const ancestors = collectAncestors(id);
+            for (const ancestorId of ancestors) {
+                if (ancestorId !== id && common.has(ancestorId)) {
+                    isProperAncestorOfAnother.add(ancestorId);
+                }
+            }
+        }
+        const deepest = [];
+        for (const id of common) {
+            if (!isProperAncestorOfAnother.has(id)) {
+                deepest.push(id);
+            }
+        }
+        if (deepest.length === 0) {
+            return null;
+        }
+        deepest.sort((a, b) => {
+            const tA = metadataById.get(a)?.createdAt ?? 0;
+            const tB = metadataById.get(b)?.createdAt ?? 0;
+            if (tA !== tB) {
+                return tB - tA;
+            }
+            return a.localeCompare(b);
+        });
+        return deepest[0];
+    }
+    /**
+     * Captures the current local receipt/index position for future incremental
+     * conflict scans.
+     */
+    async getConflictScanCheckpoint() {
+        const latestCursor = this.getLatestChangeCursor();
+        return {
+            changeSeqAsOf: latestCursor?.changeSeq ?? 0,
+            storeReceiptOrderAsOf: await this.getStoreMaxReceiptOrder(),
+            takenAt: Date.now(),
+        };
+    }
+    /**
+     * 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.
+     */
+    async resolveConflictAnalysisCandidateDocIds(docIds, options) {
+        if (!options.since || options.includeUnresolvedFromBefore) {
+            return docIds;
+        }
+        const requestedDocIds = new Set(docIds);
+        const movedDocIds = new Set();
+        const cursor = {
+            changeSeq: options.since.changeSeqAsOf,
+            lastModified: 0,
+            docId: "",
+        };
+        for await (const summary of this.iterateChangeMetadataSince(cursor)) {
+            if (requestedDocIds.has(summary.docId)) {
+                movedDocIds.add(summary.docId);
+            }
+        }
+        return docIds.filter((docId) => movedDocIds.has(docId));
+    }
+    /**
+     * 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.
+     */
+    async getStoreMaxReceiptOrder() {
+        let maxReceiptOrder;
+        const metadata = await this.scanAllMetadata(this.store);
+        for (const entry of metadata) {
+            if (typeof entry.receiptOrder !== "number") {
+                continue;
+            }
+            maxReceiptOrder = maxReceiptOrder === undefined
+                ? entry.receiptOrder
+                : Math.max(maxReceiptOrder, entry.receiptOrder);
+        }
+        return maxReceiptOrder;
+    }
+    /**
+     * 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.
+     */
+    async detectDocumentConflictsFromPlan(docId, plan, options) {
+        const verifiedChanges = await this.loadVerifiedReplayChanges(plan.replayEntries);
+        const hashToEntryId = this.buildAutomergeHashToEntryId(plan.replayEntries, verifiedChanges);
+        const activeConflictPaths = new Map();
+        const conflicts = [];
+        const resolutions = [];
+        const maxConflictsPerDoc = options.maxConflictsPerDoc;
+        let entriesApplied = 0;
+        let doc = automerge_adapter_1.Automerge.init();
+        for (const entryId of plan.orderedReplayEntryIds) {
+            this.throwIfConflictAnalysisAborted(options.signal);
+            const change = verifiedChanges.get(entryId);
+            if (!change) {
+                continue;
+            }
+            const beforeHeads = automerge_adapter_1.Automerge.getHeads(doc);
+            // A multi-head state can already contain conflicts before the next change
+            // is applied. This is especially important for resolution changes: the
+            // conflict exists in the dependency heads and disappears after the write.
+            if (beforeHeads.length > 1) {
+                const alreadyReported = new Set([
+                    ...conflicts.flatMap((conflict) => conflict.paths.map((path) => path.pathString)),
+                    ...activeConflictPaths.keys(),
+                ]);
+                const preApplyConflictPaths = this.collectDocumentConflictPaths(doc, options.detail === "values").filter((path) => !alreadyReported.has(path.pathString));
+                const conflictPathCount = conflicts.reduce((count, conflict) => count + conflict.paths.length, 0);
+                const remainingBudget = maxConflictsPerDoc === undefined
+                    ? preApplyConflictPaths.length
+                    : Math.max(0, maxConflictsPerDoc - conflictPathCount);
+                const boundedPreApplyConflictPaths = preApplyConflictPaths.slice(0, remainingBudget);
+                if (boundedPreApplyConflictPaths.length > 0) {
+                    for (const path of boundedPreApplyConflictPaths) {
+                        activeConflictPaths.set(path.pathString, path);
+                    }
+                    if (this.shouldEmitConflictObservation(change.entry, options)) {
+                        conflicts.push({
+                            docId,
+                            location: {
+                                kind: change.entry.dependencyIds.length > 1 ? "merge-deps" : "active-heads",
+                                entryId: change.entry.id,
+                                createdAt: change.entry.createdAt,
+                                receiptOrder: change.entry.receiptOrder,
+                                createdByPublicKey: change.entry.createdByPublicKey,
+                                headEntryIds: beforeHeads
+                                    .map((head) => hashToEntryId.get(head))
+                                    .filter((headEntryId) => typeof headEntryId === "string"),
+                                automergeHeads: [...beforeHeads],
+                            },
+                            paths: boundedPreApplyConflictPaths,
+                        });
+                    }
+                }
+            }
+            const afterDoc = automerge_adapter_1.Automerge.loadIncremental(doc, change.changeBytes);
+            const afterHeads = automerge_adapter_1.Automerge.getHeads(afterDoc);
+            const patches = this.diffAutomergeHeads(afterDoc, beforeHeads, afterHeads);
+            const detectedPaths = new Map();
+            // Patches tell us which paths changed, keeping analysis proportional to
+            // the change size. We then confirm conflict state with getConflicts() for
+            // those paths only, rather than walking arbitrary JSON after every change.
+            for (const patch of patches) {
+                const path = this.getConflictPatchPath(patch);
+                if (!path) {
+                    continue;
+                }
+                if (this.isInternalConflictPath(path)) {
+                    continue;
+                }
+                const pathString = (0, DocumentConflictAnalysis_1.formatDocumentConflictPath)(path);
+                const action = this.getConflictPatchAction(patch);
+                const isConflictPut = action === "put" && (this.isConflictPatch(patch) || this.hasDocumentConflictAtPath(afterDoc, path));
+                if (isConflictPut) {
+                    const conflictPath = this.buildDocumentConflictPath(afterDoc, path, options.detail === "values");
+                    detectedPaths.set(pathString, conflictPath);
+                    activeConflictPaths.set(pathString, conflictPath);
+                    continue;
+                }
+                if ((action === "put" || action === "del") && activeConflictPaths.has(pathString)) {
+                    if (this.shouldEmitConflictObservation(change.entry, options)) {
+                        resolutions.push({
+                            type: "conflictResolved",
+                            docId,
+                            entryId: change.entry.id,
+                            createdAt: change.entry.createdAt,
+                            receiptOrder: change.entry.receiptOrder,
+                            createdByPublicKey: change.entry.createdByPublicKey,
+                            path: activeConflictPaths.get(pathString),
+                            automergeHash: change.automergeHash,
+                        });
+                    }
+                    activeConflictPaths.delete(pathString);
+                }
+            }
+            if (detectedPaths.size > 0 && this.shouldEmitConflictObservation(change.entry, options)) {
+                conflicts.push({
+                    docId,
+                    location: {
+                        kind: "entry-after",
+                        entryId: change.entry.id,
+                        createdAt: change.entry.createdAt,
+                        receiptOrder: change.entry.receiptOrder,
+                        createdByPublicKey: change.entry.createdByPublicKey,
+                        headEntryIds: afterHeads
+                            .map((head) => hashToEntryId.get(head))
+                            .filter((headEntryId) => typeof headEntryId === "string"),
+                        automergeHeads: [...afterHeads],
+                    },
+                    paths: Array.from(detectedPaths.values()).sort((left, right) => left.pathString.localeCompare(right.pathString)),
+                });
+            }
+            doc = afterDoc;
+            entriesApplied++;
+            const conflictPathCount = conflicts.reduce((count, conflict) => count + conflict.paths.length, 0);
+            if (maxConflictsPerDoc !== undefined && conflictPathCount >= maxConflictsPerDoc) {
+                break;
+            }
+        }
+        // If the document still has multiple active heads after replay, there may
+        // be unresolved conflicts with no later patch to surface them. Do one final
+        // tree scan in that bounded case so active conflicts are visible.
+        if (plan.activeHeadEntryIds.length > 1
+            && (maxConflictsPerDoc === undefined
+                || conflicts.reduce((count, conflict) => count + conflict.paths.length, 0) < maxConflictsPerDoc)) {
+            const alreadyReported = new Set(conflicts.flatMap((conflict) => conflict.paths.map((path) => path.pathString)));
+            const activeConflictPaths = this.collectDocumentConflictPaths(doc, options.detail === "values").filter((path) => !alreadyReported.has(path.pathString));
+            const remainingBudget = maxConflictsPerDoc === undefined
+                ? activeConflictPaths.length
+                : Math.max(0, maxConflictsPerDoc - conflicts.reduce((count, conflict) => count + conflict.paths.length, 0));
+            const boundedActiveConflictPaths = activeConflictPaths.slice(0, remainingBudget);
+            if (boundedActiveConflictPaths.length > 0) {
+                const activeHeadEntries = plan.activeHeadEntryIds
+                    .map((entryId) => plan.replayById.get(entryId))
+                    .filter((entry) => entry !== undefined);
+                const latestActiveHeadEntry = activeHeadEntries
+                    .sort((left, right) => {
+                    const leftOrder = left.receiptOrder ?? left.createdAt;
+                    const rightOrder = right.receiptOrder ?? right.createdAt;
+                    return leftOrder !== rightOrder ? rightOrder - leftOrder : right.id.localeCompare(left.id);
+                })[0];
+                if (options.includeUnresolvedFromBefore || this.shouldEmitConflictObservation(latestActiveHeadEntry, options)) {
+                    conflicts.push({
+                        docId,
+                        location: {
+                            kind: "active-heads",
+                            entryId: latestActiveHeadEntry?.id,
+                            createdAt: latestActiveHeadEntry?.createdAt,
+                            receiptOrder: latestActiveHeadEntry?.receiptOrder,
+                            createdByPublicKey: latestActiveHeadEntry?.createdByPublicKey,
+                            headEntryIds: [...plan.activeHeadEntryIds],
+                            automergeHeads: automerge_adapter_1.Automerge.getHeads(doc),
+                        },
+                        paths: boundedActiveConflictPaths,
+                    });
+                }
+            }
+        }
+        return { conflicts, resolutions, entriesApplied };
+    }
+    /**
+     * 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.
+     */
+    shouldEmitConflictObservation(entry, options) {
+        if (!options.since) {
+            return true;
+        }
+        if (!entry) {
+            return options.includeUnresolvedFromBefore === true;
+        }
+        if (typeof entry.receiptOrder === "number"
+            && typeof options.since.storeReceiptOrderAsOf === "number") {
+            return entry.receiptOrder > options.since.storeReceiptOrderAsOf;
+        }
+        return entry.createdAt > options.since.takenAt;
+    }
+    /**
+     * 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.
+     */
+    async loadVerifiedReplayChanges(replayEntries) {
+        const loadedEntries = replayEntries.length > 0
+            ? await this.store.getEntries(replayEntries.map((entry) => entry.id))
+            : [];
+        const entryById = new Map(loadedEntries.map((entry) => [entry.id, entry]));
+        const result = new Map();
+        for (const metadata of replayEntries) {
+            const entry = entryById.get(metadata.id);
+            if (!entry) {
+                this.logger.warn(`Conflict analysis: entry ${metadata.id} not found in store, skipping`);
+                continue;
+            }
+            if (this._isAdminOnlyDb && entry.createdByPublicKey !== this.getAdminPublicKey()) {
+                this.logger.warn(`Admin-only DB: skipping conflict analysis entry ${entry.id} not signed by admin key`);
+                continue;
+            }
+            const isValid = await this.tenant.verifySignature(entry.encryptedData, entry.signature, entry.createdByPublicKey);
+            if (!isValid) {
+                this.logger.warn(`Invalid signature for conflict analysis entry ${entry.id}, skipping`);
+                continue;
+            }
+            const changeBytes = await this.tenant.decryptPayload(entry.encryptedData, entry.decryptionKeyId);
+            const decodedChange = automerge_adapter_1.Automerge.decodeChange(changeBytes);
+            result.set(metadata.id, {
+                entry: metadata,
+                changeBytes,
+                automergeHash: typeof decodedChange.hash === "string" ? decodedChange.hash : null,
+                dependencyHashes: Array.isArray(decodedChange.deps)
+                    ? decodedChange.deps.filter((dep) => typeof dep === "string")
+                    : [],
+            });
+        }
+        return result;
+    }
+    /**
+     * 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.
+     */
+    buildAutomergeHashToEntryId(replayEntries, verifiedChanges) {
+        const result = new Map();
+        for (const entry of replayEntries) {
+            const parsed = (0, idGeneration_1.parseDocEntryId)(entry.id);
+            if (parsed) {
+                result.set(parsed.automergeHash, entry.id);
+            }
+            const verified = verifiedChanges.get(entry.id);
+            if (verified?.automergeHash) {
+                result.set(verified.automergeHash, entry.id);
+            }
+        }
+        return result;
+    }
+    /**
+     * 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.
+     */
+    diffAutomergeHeads(doc, beforeHeads, afterHeads) {
+        const automergeApi = automerge_adapter_1.Automerge;
+        if (typeof automergeApi.diff !== "function") {
+            return [];
+        }
+        return automergeApi.diff(doc, beforeHeads, afterHeads);
+    }
+    /**
+     * 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.
+     */
+    getConflictPatchAction(patch) {
+        return typeof patch.action === "string" ? patch.action : null;
+    }
+    /**
+     * 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.
+     */
+    getConflictPatchPath(patch) {
+        const path = patch.path;
+        if (!Array.isArray(path) || path.length === 0) {
+            return null;
+        }
+        const normalized = path.filter((segment) => typeof segment === "string" || typeof segment === "number");
+        return normalized.length === path.length ? normalized : null;
+    }
+    /**
+     * 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.
+     */
+    isConflictPatch(patch) {
+        return patch.conflict === true;
+    }
+    /**
+     * 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.
+     */
+    isInternalConflictPath(path) {
+        return path[0] === "_lastModified";
+    }
+    /**
+     * 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.
+     */
+    hasDocumentConflictAtPath(doc, path) {
+        if (path.length === 0) {
+            return false;
+        }
+        const prop = path[path.length - 1];
+        const parent = this.readValueAtDocumentPath(doc, path.slice(0, -1));
+        if (parent === undefined || parent === null) {
+            return false;
+        }
+        const conflicts = automerge_adapter_1.Automerge.getConflicts(parent, prop);
+        return !!conflicts && Object.keys(conflicts).length > 1;
+    }
+    /**
+     * 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.
+     */
+    buildDocumentConflictPath(doc, path, includeValues) {
+        const pathString = (0, DocumentConflictAnalysis_1.formatDocumentConflictPath)(path);
+        const result = { path: [...path], pathString };
+        if (includeValues) {
+            result.values = this.getDocumentConflictValueSummaries(doc, path);
+        }
+        return result;
+    }
+    /**
+     * 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.
+     */
+    collectDocumentConflictPaths(doc, includeValues) {
+        const results = new Map();
+        const seen = new WeakSet();
+        this.collectDocumentConflictPathsFromParent(doc, doc, [], includeValues, results, seen);
+        return Array.from(results.values()).sort((left, right) => left.pathString.localeCompare(right.pathString));
+    }
+    /**
+     * 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.
+     */
+    collectDocumentConflictPathsFromParent(root, parent, basePath, includeValues, results, seen) {
+        if (parent === null || parent === undefined || typeof parent !== "object") {
+            return;
+        }
+        if (seen.has(parent)) {
+            return;
+        }
+        seen.add(parent);
+        const keys = Array.isArray(parent)
+            ? parent.map((_value, index) => index)
+            : Object.keys(parent);
+        for (const key of keys) {
+            const path = [...basePath, key];
+            if (this.isInternalConflictPath(path)) {
+                continue;
+            }
+            if (this.hasDocumentConflictAtPath(parent, [key])) {
+                const conflictPath = this.buildDocumentConflictPath(root, path, includeValues);
+                results.set(conflictPath.pathString, conflictPath);
+            }
+            this.collectDocumentConflictPathsFromParent(root, parent[key], path, includeValues, results, seen);
+        }
+    }
+    /**
+     * 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.
+     */
+    getDocumentConflictValueSummaries(doc, path) {
+        if (path.length === 0) {
+            return [];
+        }
+        const prop = path[path.length - 1];
+        const parent = this.readValueAtDocumentPath(doc, path.slice(0, -1));
+        if (parent === undefined || parent === null) {
+            return [];
+        }
+        const conflicts = automerge_adapter_1.Automerge.getConflicts(parent, prop);
+        if (!conflicts) {
+            return [];
+        }
+        const winner = this.readValueAtDocumentPath(doc, path);
+        const winnerFingerprint = this.fingerprintConflictValue(winner);
+        return Object.entries(conflicts)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([conflictId, value]) => ({
+            conflictId,
+            preview: this.previewChangeValue(value),
+            value: this.toJsonSafeConflictValue(value),
+            isWinner: this.fingerprintConflictValue(value) === winnerFingerprint,
+        }));
+    }
+    /**
+     * 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.
+     */
+    readValueAtDocumentPath(root, path) {
+        let current = root;
+        for (const segment of path) {
+            if (current === null || current === undefined) {
+                return undefined;
+            }
+            current = current[segment];
+        }
+        return current;
+    }
+    /**
+     * Produces a stable comparison key for conflict winner detection.
+     *
+     * @param value Value to fingerprint.
+     * @returns String key derived from the JSON-safe representation.
+     */
+    fingerprintConflictValue(value) {
+        try {
+            return JSON.stringify(this.toJsonSafeConflictValue(value));
+        }
+        catch {
+            return String(value);
+        }
+    }
+    /**
+     * 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.
+     */
+    toJsonSafeConflictValue(value, depth = 0, seen = new WeakSet()) {
+        if (value === null
+            || typeof value === "string"
+            || typeof value === "number"
+            || typeof value === "boolean") {
+            return value;
+        }
+        if (value === undefined || typeof value === "function" || typeof value === "symbol") {
+            return undefined;
+        }
+        if (value instanceof Uint8Array) {
+            return { type: "Uint8Array", byteLength: value.byteLength };
+        }
+        if (typeof value !== "object") {
+            return String(value);
+        }
+        if (seen.has(value)) {
+            return "[Circular]";
+        }
+        if (depth >= 4) {
+            return this.previewChangeValue(value);
+        }
+        seen.add(value);
+        if (Array.isArray(value)) {
+            return value.slice(0, 50).map((item) => this.toJsonSafeConflictValue(item, depth + 1, seen));
+        }
+        const result = {};
+        for (const [key, child] of Object.entries(value).slice(0, 50)) {
+            result[key] = this.toJsonSafeConflictValue(child, depth + 1, seen);
+        }
+        return result;
+    }
+    /**
+     * Throws when the caller cancels conflict analysis.
+     *
+     * @param signal Optional `AbortSignal` supplied through analysis options.
+     */
+    throwIfConflictAnalysisAborted(signal) {
+        if (signal?.aborted) {
+            throw new Error("Conflict analysis aborted");
+        }
+    }
+    /**
+     * 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.
+     */
+    async maybeYieldForConflictAnalysis(yieldEveryMs, lastYieldAt) {
+        if (yieldEveryMs === undefined || yieldEveryMs < 0) {
+            return lastYieldAt;
+        }
+        const now = Date.now();
+        if (now - lastYieldAt < yieldEveryMs) {
+            return lastYieldAt;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        return Date.now();
+    }
+    /**
+     * Derives human-readable changed field paths for one DAG entry.
+     *
+     * This compares the branch-local document state at the selected entry with each
+     * reachable parent state, then normalizes array indices so the UI can show stable
+     * paths such as `_attachments[].fileName` instead of raw Automerge op keys only.
+     */
+    async deriveReadableTouchedPaths(docId, entryMetadata, allEntryMetadata, touchedKeys) {
+        if (entryMetadata.entryType === "doc_snapshot") {
+            return [];
+        }
+        const currentDoc = await this.materializeBranchInternalDoc(docId, allEntryMetadata, entryMetadata.id);
+        const currentData = this.getReadableDiffValueForDoc(currentDoc);
+        const parentEntryIds = entryMetadata.dependencyIds.filter((dependencyId) => allEntryMetadata.some((entry) => entry.id === dependencyId));
+        const diffPaths = new Set();
+        if (parentEntryIds.length === 0) {
+            this.collectReadableDiffPaths(undefined, currentData, "", diffPaths);
+        }
+        else {
+            for (const parentEntryId of parentEntryIds) {
+                const parentDoc = await this.materializeBranchInternalDoc(docId, allEntryMetadata, parentEntryId);
+                const parentData = this.getReadableDiffValueForDoc(parentDoc);
+                this.collectReadableDiffPaths(parentData, currentData, "", diffPaths);
+            }
+        }
+        const normalizedPaths = Array.from(diffPaths)
+            .map((path) => path.replace(/\[\d+\]/g, "[]"))
+            .filter((path, index, allPaths) => path.length > 0 && allPaths.indexOf(path) === index)
+            .sort();
+        if (normalizedPaths.length === 0) {
+            return [];
+        }
+        const touchedKeySet = new Set(touchedKeys);
+        if (touchedKeySet.size === 0) {
+            return normalizedPaths;
+        }
+        const filteredPaths = normalizedPaths.filter((path) => touchedKeySet.has(this.extractLeafPathSegment(path)));
+        return filteredPaths.length > 0 ? filteredPaths : normalizedPaths;
+    }
+    async getAllDocumentIds() {
+        // Return all non-deleted document IDs from index
+        const docIds = [];
+        for (const entry of this.index) {
+            if (entry.accessState === "visible" && !entry.isDeleted) {
+                docIds.push(entry.docId);
+            }
+        }
+        return docIds;
+    }
+    async getDeletedDocumentIds() {
+        const docIds = [];
+        for (const entry of this.index) {
+            if (entry.accessState === "visible" && entry.isDeleted) {
+                docIds.push(entry.docId);
+            }
+        }
+        return docIds;
+    }
+    async getAllDocumentIdsAtTimestamp(timestamp) {
+        // findEntries() uses an exclusive upper bound (createdAt < creationDateUntil).
+        // Query up to timestamp + 1 so entries created exactly at `timestamp` are included
+        // for the strict checks below (createTime < timestamp, deleteTime > timestamp).
+        let upperBoundExclusive = timestamp === Number.MAX_SAFE_INTEGER ? timestamp : timestamp + 1;
+        if (this.timeTravelDate != null) {
+            upperBoundExclusive = Math.min(upperBoundExclusive, this.timeTravelDate);
+        }
+        // We only need lifecycle metadata for this query. Changes and snapshots can
+        // affect document contents, but create/delete/undelete determine existence.
+        const [creates, deletes, undeletes] = await Promise.all([
+            this.store.findEntries("doc_create", null, upperBoundExclusive),
+            this.store.findEntries("doc_delete", null, upperBoundExclusive),
+            this.store.findEntries("doc_undelete", null, upperBoundExclusive),
+        ]);
+        const lifecycleEntriesByDocId = new Map();
+        const addLifecycleEntry = (entry) => {
             // Group entries by document so each document's lifecycle can be evaluated
             // independently without materializing its Automerge state.
             const entries = lifecycleEntriesByDocId.get(entry.docId) ?? [];
@@ -2008,6 +3631,10 @@ class BaseMindooDB {
             if (!ordered.some((entry) => entry.entryType === "doc_create" && entry.createdAt <= timestamp)) {
                 continue;
             }
+            const createEntry = ordered.find((entry) => entry.entryType === "doc_create");
+            if (createEntry && !(await this.tenant.hasDecryptionKey(createEntry.decryptionKeyId))) {
+                continue;
+            }
             // Delete and undelete are terminal lifecycle markers. The latest one at
             // the timestamp decides whether the document existed then.
             const latestTerminal = ordered
@@ -2029,6 +3656,7 @@ class BaseMindooDB {
         return this.undeleteDocInternal(docId, options.signingKeyPair, options.signingKeyPassword);
     }
     async assertLifecycleMutationAllowed(signingKeyPair, signingKeyPassword) {
+        this.assertWritable("document lifecycle mutation");
         const useCustomSigningKey = signingKeyPair !== undefined && signingKeyPassword !== undefined;
         if ((signingKeyPair !== undefined) !== (signingKeyPassword !== undefined)) {
             throw new Error("Lifecycle mutation requires both signingKeyPair and signingKeyPassword");
@@ -2115,8 +3743,8 @@ class BaseMindooDB {
         internalDoc.doc = newDoc;
         internalDoc.isDeleted = entryType === "doc_delete";
         internalDoc.lastModified = now;
-        this.storeCachedDocument(internalDoc);
-        this.updateIndex(docId, internalDoc.lastModified, internalDoc.isDeleted);
+        await this.storeCachedDocument(internalDoc);
+        this.updateIndex(docId, internalDoc.lastModified, internalDoc.isDeleted, internalDoc.decryptionKeyId, "visible");
         this.markDocDirty(docId);
     }
     /**
@@ -2157,9 +3785,73 @@ class BaseMindooDB {
     async changeDocWithSigningKey(doc, changeFunc, signingKeyPair, signingKeyPassword) {
         return this.changeDoc(doc, changeFunc, { signingKeyPair, signingKeyPassword });
     }
-    async applyTextPatch(doc, patch) {
+    async applyTextPatch(doc, patch) {
+        this.assertWritable("applyTextPatch");
+        const docId = doc.getId();
+        this.logger.debug(`===== applyTextPatch called for document ${docId} =====`);
+        if (this._isAdminOnlyDb) {
+            const adminPublicKey = this.getAdminPublicKey();
+            const currentUser = await this.tenant.getCurrentUserId();
+            if (currentUser.userSigningPublicKey !== adminPublicKey) {
+                throw new Error("Admin-only database: only the admin key can modify data");
+            }
+        }
+        let internalDoc = this.getCachedDocument(docId);
+        if (!internalDoc) {
+            const loadedDoc = await this.loadDocumentInternal(docId);
+            if (!loadedDoc) {
+                throw new Error(`Document ${docId} not found`);
+            }
+            internalDoc = loadedDoc;
+        }
+        if (internalDoc.isDeleted) {
+            throw new Error(`Document ${docId} has been deleted`);
+        }
+        this.validateTextPatch(patch);
+        const now = Date.now();
+        const headsBeforeChange = automerge_adapter_1.Automerge.getHeads(internalDoc.doc);
+        const baseHeads = patch.baseHeads;
+        const applyEdits = (automergeDoc) => {
+            this.ensureTextPath(automergeDoc, patch.path);
+            for (const edit of patch.edits) {
+                automerge_adapter_1.Automerge.splice(automergeDoc, patch.path, edit.index, edit.deleteCount, edit.insert ?? "");
+            }
+            automergeDoc._lastModified = now;
+        };
+        let newDoc;
+        try {
+            if (baseHeads && baseHeads.length > 0) {
+                const result = automerge_adapter_1.Automerge.changeAt(internalDoc.doc, baseHeads, applyEdits);
+                newDoc = result.newDoc;
+            }
+            else {
+                newDoc = automerge_adapter_1.Automerge.change(internalDoc.doc, applyEdits);
+            }
+            this.logger.debug(`Successfully applied text patch, new document heads: ${JSON.stringify(automerge_adapter_1.Automerge.getHeads(newDoc))}`);
+        }
+        catch (error) {
+            this.logger.error(`Error applying text patch for document ${docId}:`, error);
+            throw error;
+        }
+        await this.persistDocumentChange({
+            internalDoc,
+            newDoc,
+            now,
+            headsBeforeChange,
+            useCustomKey: false,
+            successMessage: "text patched",
+        });
+        const wrapped = this.wrapDocument(internalDoc);
+        return {
+            doc: wrapped,
+            heads: wrapped.getHeads(),
+            data: wrapped.getData(),
+        };
+    }
+    async applyJsonPatch(doc, patch) {
+        this.assertWritable("applyJsonPatch");
         const docId = doc.getId();
-        this.logger.debug(`===== applyTextPatch called for document ${docId} =====`);
+        this.logger.debug(`===== applyJsonPatch called for document ${docId} =====`);
         if (this._isAdminOnlyDb) {
             const adminPublicKey = this.getAdminPublicKey();
             const currentUser = await this.tenant.getCurrentUserId();
@@ -2178,30 +3870,26 @@ class BaseMindooDB {
         if (internalDoc.isDeleted) {
             throw new Error(`Document ${docId} has been deleted`);
         }
-        this.validateTextPatch(patch);
+        this.validateJsonPatch(patch);
         const now = Date.now();
         const headsBeforeChange = automerge_adapter_1.Automerge.getHeads(internalDoc.doc);
-        const baseHeads = patch.baseHeads;
-        const applyEdits = (automergeDoc) => {
-            this.ensureTextPath(automergeDoc, patch.path);
-            for (const edit of patch.edits) {
-                automerge_adapter_1.Automerge.splice(automergeDoc, patch.path, edit.index, edit.deleteCount, edit.insert ?? "");
-            }
+        const applyPatch = (automergeDoc) => {
+            this.applyJsonPatchOperations(automergeDoc, patch);
             automergeDoc._lastModified = now;
         };
         let newDoc;
         try {
-            if (baseHeads && baseHeads.length > 0) {
-                const result = automerge_adapter_1.Automerge.changeAt(internalDoc.doc, baseHeads, applyEdits);
+            if (patch.baseHeads && patch.baseHeads.length > 0) {
+                const result = automerge_adapter_1.Automerge.changeAt(internalDoc.doc, patch.baseHeads, applyPatch);
                 newDoc = result.newDoc;
             }
             else {
-                newDoc = automerge_adapter_1.Automerge.change(internalDoc.doc, applyEdits);
+                newDoc = automerge_adapter_1.Automerge.change(internalDoc.doc, applyPatch);
             }
-            this.logger.debug(`Successfully applied text patch, new document heads: ${JSON.stringify(automerge_adapter_1.Automerge.getHeads(newDoc))}`);
+            this.logger.debug(`Successfully applied JSON patch, new document heads: ${JSON.stringify(automerge_adapter_1.Automerge.getHeads(newDoc))}`);
         }
         catch (error) {
-            this.logger.error(`Error applying text patch for document ${docId}:`, error);
+            this.logger.error(`Error applying JSON patch for document ${docId}:`, error);
             throw error;
         }
         await this.persistDocumentChange({
@@ -2210,7 +3898,7 @@ class BaseMindooDB {
             now,
             headsBeforeChange,
             useCustomKey: false,
-            successMessage: "text patched",
+            successMessage: "JSON patched",
         });
         const wrapped = this.wrapDocument(internalDoc);
         return {
@@ -2220,6 +3908,7 @@ class BaseMindooDB {
         };
     }
     async changeDocInternal(doc, changeFunc, signingKeyPair, signingKeyPassword) {
+        this.assertWritable("changeDoc");
         const docId = doc.getId();
         if ((signingKeyPair !== undefined) !== (signingKeyPassword !== undefined)) {
             throw new Error("changeDoc: signingKeyPair and signingKeyPassword must be provided together");
@@ -2370,7 +4059,8 @@ class BaseMindooDB {
                 // If it was added in this same changeDoc call, just remove from pending
                 const pendingIndex = pendingAttachmentAdditions.findIndex(a => a.attachmentId === attachmentId);
                 if (pendingIndex >= 0) {
-                    pendingAttachmentAdditions.splice(pendingIndex, 1);
+                    const [pendingRef] = pendingAttachmentAdditions.splice(pendingIndex, 1);
+                    await db.cleanupIncompleteAttachmentUpload(docId, pendingRef.attachmentId);
                 }
                 else {
                     // Mark for removal from existing attachments
@@ -2427,7 +4117,13 @@ class BaseMindooDB {
             },
         };
         // Execute the async callback (this may do async operations like signing)
-        await changeFunc(collectingDoc);
+        try {
+            await changeFunc(collectingDoc);
+        }
+        catch (error) {
+            await Promise.all(pendingAttachmentAdditions.map((ref) => this.cleanupIncompleteAttachmentUpload(docId, ref.attachmentId)));
+            throw error;
+        }
         // Deactivate the callback guard - no more changes can be made via collectingDoc
         isCallbackActive = false;
         // Now apply the collected changes synchronously in Automerge.change()
@@ -2477,18 +4173,27 @@ class BaseMindooDB {
         }
         catch (error) {
             this.logger.error(`Error in Automerge.change for document ${docId}:`, error);
+            await Promise.all(pendingAttachmentAdditions.map((ref) => this.cleanupIncompleteAttachmentUpload(docId, ref.attachmentId)));
             throw error;
         }
-        await this.persistDocumentChange({
-            internalDoc,
-            newDoc,
-            now,
-            headsBeforeChange,
-            useCustomKey: Boolean(useCustomKey),
-            signingKeyPair,
-            signingKeyPassword,
-            successMessage: useCustomKey ? "changed with custom signing key" : "changed",
-        });
+        try {
+            await this.persistDocumentChange({
+                internalDoc,
+                newDoc,
+                now,
+                headsBeforeChange,
+                useCustomKey: Boolean(useCustomKey),
+                signingKeyPair,
+                signingKeyPassword,
+                successMessage: useCustomKey ? "changed with custom signing key" : "changed",
+                attachmentIds: pendingAttachmentAdditions.map((ref) => ref.attachmentId),
+            });
+        }
+        catch (error) {
+            await Promise.all(pendingAttachmentAdditions.map((ref) => this.cleanupIncompleteAttachmentUpload(docId, ref.attachmentId)));
+            throw error;
+        }
+        await Promise.all(pendingAttachmentAdditions.map((ref) => this.clearPendingAttachmentUploadLedger(ref.attachmentId)));
     }
     validateTextPatch(patch) {
         if (!Array.isArray(patch.path) || patch.path.length === 0) {
@@ -2514,6 +4219,108 @@ class BaseMindooDB {
             }
         }
     }
+    validateJsonPatch(patch) {
+        const operationCount = (patch.set?.length ?? 0)
+            + (patch.unset?.length ?? 0)
+            + (patch.listDelete?.length ?? 0)
+            + (patch.listInsert?.length ?? 0);
+        if (operationCount === 0) {
+            throw new Error("JSON patch must include at least one operation");
+        }
+        for (const operation of patch.set ?? []) {
+            this.validateJsonPath(operation.path, "JSON set");
+        }
+        for (const operation of patch.unset ?? []) {
+            this.validateJsonPath(operation.path, "JSON unset");
+        }
+        for (const operation of patch.listDelete ?? []) {
+            this.validateJsonPath(operation.path, "JSON listDelete");
+            if (!Number.isInteger(operation.index) || operation.index < 0) {
+                throw new Error("JSON listDelete index must be a non-negative integer");
+            }
+            if (!Number.isInteger(operation.deleteCount) || operation.deleteCount < 0) {
+                throw new Error("JSON listDelete deleteCount must be a non-negative integer");
+            }
+        }
+        for (const operation of patch.listInsert ?? []) {
+            this.validateJsonPath(operation.path, "JSON listInsert");
+            if (!Number.isInteger(operation.index) || operation.index < 0) {
+                throw new Error("JSON listInsert index must be a non-negative integer");
+            }
+            if (!Array.isArray(operation.values)) {
+                throw new Error("JSON listInsert values must be an array");
+            }
+        }
+    }
+    validateJsonPath(path, label) {
+        if (!Array.isArray(path) || path.length === 0) {
+            throw new Error(`${label} path must contain at least one segment`);
+        }
+        for (const segment of path) {
+            if (typeof segment !== "string" && typeof segment !== "number") {
+                throw new Error(`${label} path segments must be strings or numbers`);
+            }
+        }
+    }
+    applyJsonPatchOperations(automergeDoc, patch) {
+        for (const operation of patch.set ?? []) {
+            this.setJsonValueAtPath(automergeDoc, operation.path, structuredClone(operation.value));
+        }
+        for (const operation of patch.unset ?? []) {
+            this.unsetJsonValueAtPath(automergeDoc, operation.path);
+        }
+        for (const operation of patch.listDelete ?? []) {
+            const list = this.readJsonListAtPath(automergeDoc, operation.path);
+            list.splice(operation.index, operation.deleteCount);
+        }
+        for (const operation of patch.listInsert ?? []) {
+            const list = this.readJsonListAtPath(automergeDoc, operation.path);
+            list.splice(operation.index, 0, ...structuredClone(operation.values));
+        }
+    }
+    setJsonValueAtPath(target, path, value) {
+        const parent = this.ensureJsonParentAtPath(target, path);
+        parent[path[path.length - 1]] = value;
+    }
+    unsetJsonValueAtPath(target, path) {
+        const parent = this.readJsonParentAtPath(target, path);
+        delete parent[path[path.length - 1]];
+    }
+    readJsonListAtPath(target, path) {
+        let value = target;
+        for (const segment of path) {
+            value = value?.[segment];
+        }
+        if (!Array.isArray(value)) {
+            throw new Error(`Cannot apply JSON list operation to non-array value at '${path.map(String).join(".")}'`);
+        }
+        return value;
+    }
+    ensureJsonParentAtPath(target, path) {
+        let parent = target;
+        for (let index = 0; index < path.length - 1; index += 1) {
+            const segment = path[index];
+            const nextSegment = path[index + 1];
+            if (parent[segment] === undefined || parent[segment] === null) {
+                parent[segment] = typeof nextSegment === "number" ? [] : {};
+            }
+            parent = parent[segment];
+            if (parent === null || typeof parent !== "object") {
+                throw new Error(`Cannot apply JSON patch through non-object path segment '${String(segment)}'`);
+            }
+        }
+        return parent;
+    }
+    readJsonParentAtPath(target, path) {
+        let parent = target;
+        for (let index = 0; index < path.length - 1; index += 1) {
+            parent = parent?.[path[index]];
+            if (parent === null || typeof parent !== "object") {
+                throw new Error(`Cannot resolve JSON patch path '${path.map(String).join(".")}'`);
+            }
+        }
+        return parent;
+    }
     ensureTextPath(automergeDoc, path) {
         let target = automergeDoc;
         for (let i = 0; i < path.length - 1; i++) {
@@ -2538,7 +4345,7 @@ class BaseMindooDB {
         }
     }
     async persistDocumentChange(options) {
-        const { internalDoc, newDoc, now, headsBeforeChange, useCustomKey, signingKeyPair, signingKeyPassword, successMessage } = options;
+        const { internalDoc, newDoc, now, headsBeforeChange, useCustomKey, signingKeyPair, signingKeyPassword, successMessage, attachmentIds } = options;
         const docId = internalDoc.id;
         this.logger.debug(`Getting change bytes from document ${docId}`);
         const changesSincePreviousHeads = headsBeforeChange
@@ -2586,6 +4393,7 @@ class BaseMindooDB {
             signature,
             originalSize: changeBytes.length,
             encryptedSize: encryptedPayload.length,
+            attachmentIds: attachmentIds && attachmentIds.length > 0 ? attachmentIds : undefined,
         };
         const fullEntry = {
             ...entryMetadata,
@@ -2595,8 +4403,8 @@ class BaseMindooDB {
         this.registerAutomergeHashMapping(docId, automergeHash, entryId);
         internalDoc.doc = newDoc;
         internalDoc.lastModified = now;
-        this.storeCachedDocument(internalDoc);
-        this.updateIndex(docId, internalDoc.lastModified, internalDoc.isDeleted);
+        await this.storeCachedDocument(internalDoc);
+        this.updateIndex(docId, internalDoc.lastModified, internalDoc.isDeleted, internalDoc.decryptionKeyId, "visible");
         this.markDocDirty(docId);
         this.logger.info(`Document ${docId} ${successMessage} successfully`);
         await this.maybeWriteSnapshotForDocument(internalDoc, useCustomKey
@@ -2672,7 +4480,11 @@ class BaseMindooDB {
         // Only look ahead a bounded number of uncached docs so iteration does not
         // materialize the entire remaining changefeed tail up front.
         for (let i = startIndex; i < indexSnapshot.length && docIds.length < this.iteratePrefetchWindowDocs; i++) {
-            const docId = indexSnapshot[i].docId;
+            const entry = indexSnapshot[i];
+            if (entry.accessState === "inaccessible") {
+                continue;
+            }
+            const docId = entry.docId;
             if (seen.has(docId) || this.docCache.has(docId)) {
                 continue;
             }
@@ -3046,6 +4858,9 @@ class BaseMindooDB {
             // Iterate through the stable snapshot and yield documents one at a time.
             for (let i = startIndex; i < indexSnapshot.length; i++) {
                 const entry = indexSnapshot[i];
+                if (entry.accessState !== "visible") {
+                    continue;
+                }
                 try {
                     this.logger.debug(`Yielding document ${entry.docId} from index (lastModified: ${entry.lastModified}, isDeleted: ${entry.isDeleted})`);
                     let internalDoc = this.getCachedDocument(entry.docId);
@@ -3220,20 +5035,381 @@ class BaseMindooDB {
             isDeleted,
         };
         // Update cache
-        this.storeCachedDocument(updatedInternalDoc);
+        await this.storeCachedDocument(updatedInternalDoc);
         this.markDocDirty(docId);
         return updatedInternalDoc;
     }
+    /**
+     * 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.
+     */
+    async tryLoadFromL2(docId) {
+        const store = this.cacheManager?.getStore() ?? null;
+        if (!store)
+            return null;
+        const prefix = this.getCachePrefix();
+        const key = `${prefix}/${docId}`;
+        let bytes;
+        try {
+            bytes = await store.get("doc", key);
+        }
+        catch (e) {
+            this.logger.warn(`L2 read failed for ${docId}; falling back to full materialization: ${e}`);
+            return null;
+        }
+        if (!bytes)
+            return null;
+        let deserialized;
+        try {
+            deserialized = this.deserializeDoc(bytes);
+        }
+        catch (e) {
+            this.logger.warn(`L2 deserialize failed for ${docId}, evicting stale record: ${e}`);
+            try {
+                await store.delete("doc", key);
+            }
+            catch (deleteError) {
+                this.logger.warn(`Failed to evict corrupt L2 record for ${docId}: ${deleteError}`);
+            }
+            return null;
+        }
+        if (deserialized === null) {
+            // Legacy v1 record - fall through; the full path will rewrite a v2 record.
+            return null;
+        }
+        const { internal, persistedChangeSeq } = deserialized;
+        // L2 records persist the decrypted Automerge state. If the current
+        // KeyBag cannot resolve the doc's key, scrub the cached copy and
+        // refuse to surface it instead of returning plaintext for which the
+        // caller no longer has authorization.
+        if (!(await this.tenant.hasDecryptionKey(internal.decryptionKeyId))) {
+            await this.purgeMaterializedDocument(docId);
+            return null;
+        }
+        const indexEntryIdx = this.indexLookup.get(docId);
+        if (indexEntryIdx === undefined) {
+            // Doc isn't in the in-memory changefeed index. Either the cache is
+            // ahead of the index (very rare race during initial restore) or the
+            // L2 record is orphaned. Drop and fall through.
+            try {
+                await store.delete("doc", key);
+            }
+            catch (deleteError) {
+                this.logger.warn(`Failed to evict orphaned L2 record for ${docId}: ${deleteError}`);
+            }
+            return null;
+        }
+        const currentChangeSeq = this.index[indexEntryIdx].changeSeq;
+        // Fresh hit: index agrees with the persisted state.
+        if (persistedChangeSeq === currentChangeSeq) {
+            await this.storeCachedDocument(internal);
+            return internal;
+        }
+        // L2 newer than index: should not happen in a well-behaved system,
+        // but trust the persisted record and re-mark dirty so the next flush
+        // re-anchors the changeSeq pointer.
+        if (persistedChangeSeq > currentChangeSeq) {
+            this.logger.warn(`L2 record for ${docId} reports changeSeq ${persistedChangeSeq} > index changeSeq ${currentChangeSeq}; trusting L2`);
+            await this.storeCachedDocument(internal);
+            this.markDocDirty(docId);
+            return internal;
+        }
+        // Stale L2. Identify the entries the persisted doc is missing and
+        // apply only those via the standard incremental path.
+        let allMetadata;
+        try {
+            allMetadata = await this.scanAllMetadata(this.store, { docId });
+        }
+        catch (e) {
+            this.logger.warn(`L2 stale-doc metadata scan failed for ${docId}: ${e}`);
+            return null;
+        }
+        // Enumerate Automerge change hashes already in the persisted doc.
+        const persistedHashes = new Set();
+        try {
+            for (const ch of automerge_adapter_1.Automerge.getAllChanges(internal.doc)) {
+                const decoded = automerge_adapter_1.Automerge.decodeChange(ch);
+                persistedHashes.add(decoded.hash);
+            }
+        }
+        catch (e) {
+            this.logger.warn(`Failed to enumerate persisted changes for ${docId}: ${e}`);
+            return null;
+        }
+        const missingMetadata = allMetadata.filter((em) => {
+            const parsed = (0, idGeneration_1.parseDocEntryId)(em.id);
+            if (!parsed)
+                return true;
+            return !persistedHashes.has(parsed.automergeHash);
+        });
+        if (missingMetadata.length === 0) {
+            // No real deltas (changeSeq pointer drift only). Promote and return.
+            await this.storeCachedDocument(internal);
+            return internal;
+        }
+        let updated;
+        try {
+            updated = await this.applyNewEntriesToCachedDocument(internal, missingMetadata);
+        }
+        catch (e) {
+            this.logger.warn(`L2 incremental apply failed for ${docId}: ${e}`);
+            return null;
+        }
+        if (updated === null) {
+            // applyNewEntriesToCachedDocument returns null when no signed entries
+            // produced a head change. Treat the persisted doc as authoritative
+            // and put it in L1 ourselves (the helper only caches when it
+            // actually applied work).
+            await this.storeCachedDocument(internal);
+            return internal;
+        }
+        return updated;
+    }
+    // ---------------------------------------------------------------------------
+    // Background L2 warmer (Phase 4)
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns whether a background warmer pass is currently running.
+     *
+     * @see startBackgroundWarmer
+     * @see stopBackgroundWarmer
+     */
+    isWarmerRunning() {
+        return this.warmerPromise !== null;
+    }
+    /**
+     * 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) {
+        if (this.warmerPromise) {
+            // Single-flight: return the in-flight promise. We deliberately do
+            // not honor a new external signal in this case - the caller can
+            // either stopBackgroundWarmer() to kill the existing run and
+            // re-start, or wait for the in-flight pass to finish.
+            return this.warmerPromise;
+        }
+        const internalAbort = new AbortController();
+        this.warmerAbort = internalAbort;
+        // If the caller passed an external signal, propagate aborts.
+        const externalSignal = options?.signal;
+        let externalListener = null;
+        if (externalSignal) {
+            if (externalSignal.aborted) {
+                internalAbort.abort();
+            }
+            else {
+                externalListener = () => internalAbort.abort();
+                externalSignal.addEventListener("abort", externalListener);
+            }
+        }
+        const run = this.runBackgroundWarmer(internalAbort.signal, options?.onProgress).finally(() => {
+            this.warmerPromise = null;
+            this.warmerAbort = null;
+            if (externalSignal && externalListener) {
+                externalSignal.removeEventListener("abort", externalListener);
+            }
+        });
+        this.warmerPromise = run;
+        return run;
+    }
+    /**
+     * 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() {
+        return this.warmerProgress;
+    }
+    /**
+     * 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.
+     */
+    async stopBackgroundWarmer() {
+        const inFlight = this.warmerPromise;
+        if (!inFlight)
+            return;
+        this.warmerAbort?.abort();
+        try {
+            await inFlight;
+        }
+        catch {
+            // Errors are already logged inside the warmer body. Swallow here
+            // so callers waiting only for "warmer is no longer running" do
+            // not have to wrap stopBackgroundWarmer in try/catch.
+        }
+    }
+    /**
+     * 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.
+     */
+    async runBackgroundWarmer(signal, onProgress) {
+        if (!this.cacheManager) {
+            this.logger.debug("Warmer skipped: no cacheManager attached, no L2 to warm.");
+            return;
+        }
+        // Snapshot the docId list so concurrent index updates don't shift
+        // our iteration mid-pass. Iterating the index directly would also
+        // work but a snapshot makes the loop's behavior easier to reason
+        // about under sync activity.
+        const docIds = this.index.map((entry) => entry.docId);
+        const total = docIds.length;
+        // Progress snapshot is replaced (not mutated in place) so polled
+        // readers see consistent values. We initialize even when total=0
+        // so the UI can display a "done" terminal state.
+        this.warmerProgress = { processed: 0, total, phase: "warming" };
+        const emitProgress = (progress) => {
+            this.warmerProgress = progress;
+            if (!onProgress)
+                return;
+            try {
+                onProgress(progress);
+            }
+            catch (e) {
+                // A buggy progress consumer must not break the warmer.
+                this.logger.warn(`Warmer onProgress callback threw: ${e}`);
+            }
+        };
+        if (total === 0) {
+            this.logger.debug("Warmer: nothing to warm, index is empty.");
+            emitProgress({ processed: 0, total: 0, phase: "done" });
+            return;
+        }
+        const startedAt = Date.now();
+        let processed = 0;
+        let warmed = 0;
+        let skippedAlreadyHot = 0;
+        let errored = 0;
+        try {
+            for (const docId of docIds) {
+                if (signal.aborted) {
+                    this.logger.info(`Warmer: aborted after ${processed}/${total} docs (warmed=${warmed}, skipped=${skippedAlreadyHot})`);
+                    emitProgress({ processed, total, phase: "cancelled" });
+                    return;
+                }
+                processed++;
+                if (this.docCache.has(docId)) {
+                    skippedAlreadyHot++;
+                }
+                else {
+                    try {
+                        const fromL2 = await this.tryLoadFromL2(docId);
+                        if (fromL2 === null) {
+                            // L2 miss -> full materialization. flush-before-evict on
+                            // the next L1 churn will turn this into an L2 record so
+                            // future reads are fast.
+                            await this.loadDocumentInternal(docId);
+                        }
+                        warmed++;
+                    }
+                    catch (e) {
+                        errored++;
+                        this.logger.warn(`Warmer: failed to warm doc ${docId}: ${e}`);
+                    }
+                }
+                if (processed % this.warmerBatchSize === 0) {
+                    // Emit progress BEFORE yielding so the UI updates while we
+                    // are off the critical path. Use the still-warming phase
+                    // since the loop may still have docs left.
+                    emitProgress({ processed, total, phase: "warming" });
+                    await this.warmerScheduler.yield();
+                }
+            }
+            this.logger.info(`Warmer finished in ${Date.now() - startedAt}ms: processed=${processed}, ` +
+                `warmed=${warmed}, alreadyHot=${skippedAlreadyHot}, errored=${errored}`);
+            emitProgress({ processed, total, phase: "done" });
+        }
+        catch (e) {
+            // Defensive: any unexpected error is logged and swallowed - the
+            // warmer is purely an optimization. Surface the partial progress
+            // as `cancelled` since the pass did not complete normally.
+            this.logger.warn(`Warmer crashed: ${e}`);
+            emitProgress({ processed, total, phase: "cancelled" });
+        }
+    }
     /**
      * Internal method to load a document from the content-addressed store
      */
     async loadDocumentInternal(docId) {
         const startedAt = Date.now();
         const cacheCheckStartedAt = Date.now();
-        // Check cache first
+        // Short-circuit on the visibility layer: a doc marked
+        // `"inaccessible"` is logically absent for this database, regardless
+        // of whether L1/L2 still hold a cached copy. This keeps the public
+        // contract of `loadDocumentInternal` aligned with `getDocument` /
+        // `getAllDocumentIds`.
+        const indexEntryIdx = this.indexLookup.get(docId);
+        if (indexEntryIdx !== undefined && this.index[indexEntryIdx].accessState === "inaccessible") {
+            return null;
+        }
         if (this.docCache.has(docId)) {
             this.logger.debug(`Document ${docId} found in cache, returning cached version`);
             const cached = this.getCachedDocument(docId);
+            // Belt-and-braces: even if the index says visible, recheck the
+            // KeyBag before returning plaintext. Catches races where a key
+            // was just removed but the index has not been reconciled yet.
+            if (!(await this.tenant.hasDecryptionKey(cached.decryptionKeyId))) {
+                await this.purgeMaterializedDocument(docId);
+                return null;
+            }
             this.performanceCallback?.onDocumentLoad?.({
                 docId,
                 cacheHit: true,
@@ -3250,6 +5426,28 @@ class BaseMindooDB {
             });
             return cached;
         }
+        // L1 missed. Try the persistent L2 cache before falling through to
+        // the full signature-verify + decrypt + Automerge-replay pipeline.
+        // The L2 path either returns a ready-to-use InternalDoc (already
+        // promoted into L1) or null - in which case we proceed below.
+        const l2Doc = await this.tryLoadFromL2(docId);
+        if (l2Doc !== null) {
+            this.performanceCallback?.onDocumentLoad?.({
+                docId,
+                cacheHit: true,
+                metadataEntriesScanned: 0,
+                replayEntriesLoaded: 0,
+                snapshotUsed: false,
+                cacheCheckTime: Date.now() - cacheCheckStartedAt,
+                storeQueryTime: 0,
+                entryLoadTime: 0,
+                signatureVerificationTime: 0,
+                decryptionTime: 0,
+                automergeTime: 0,
+                totalTime: Date.now() - startedAt,
+            });
+            return l2Doc;
+        }
         this.logger.debug(`===== Starting to load document ${docId} from store =====`);
         const cacheCheckTime = Date.now() - cacheCheckStartedAt;
         let storeQueryTime = 0;
@@ -3509,7 +5707,7 @@ class BaseMindooDB {
             isDeleted,
         };
         // Update cache
-        this.storeCachedDocument(internalDoc);
+        await this.storeCachedDocument(internalDoc);
         this.markDocDirty(docId);
         this.logger.debug(`===== Successfully loaded document ${docId} and cached it =====`);
         this.performanceCallback?.onDocumentLoad?.({
@@ -3845,6 +6043,7 @@ class BaseMindooDB {
                 docId,
                 dependencyIds: prevChunkId ? [prevChunkId] : [],
                 createdAt,
+                attachmentId,
                 createdByPublicKey: currentUser.userSigningPublicKey,
                 decryptionKeyId,
                 signature,
@@ -3871,6 +6070,66 @@ class BaseMindooDB {
         };
         return ref;
     }
+    pendingAttachmentUploadLedgerId(attachmentId) {
+        return `pending_upload_${attachmentId}`;
+    }
+    async putEntriesWithRetry(store, entries, description) {
+        let lastError;
+        for (let attempt = 0; attempt <= ATTACHMENT_WRITE_RETRY_DELAYS_MS.length; attempt++) {
+            try {
+                await store.putEntries(entries);
+                return;
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt >= ATTACHMENT_WRITE_RETRY_DELAYS_MS.length) {
+                    break;
+                }
+                this.logger.warn(`Attachment write ${description} failed; retrying batch (attempt ${attempt + 1})`, error);
+                await new Promise((resolve) => setTimeout(resolve, ATTACHMENT_WRITE_RETRY_DELAYS_MS[attempt]));
+            }
+        }
+        throw lastError;
+    }
+    async createPendingAttachmentUploadLedger(docId, attachmentId, decryptionKeyId, createdAt, createdByPublicKey) {
+        const encryptedData = new Uint8Array(0);
+        const contentHash = await (0, idGeneration_1.computeContentHash)(encryptedData, this.getSubtle());
+        const signature = await this.tenant.signPayload(encryptedData);
+        await this.putEntriesWithRetry(this.store, [{
+                entryType: "pending_attachment_upload",
+                id: this.pendingAttachmentUploadLedgerId(attachmentId),
+                contentHash,
+                docId,
+                dependencyIds: [],
+                createdAt,
+                attachmentId,
+                uploadStartedAt: Date.now(),
+                createdByPublicKey,
+                decryptionKeyId,
+                signature,
+                originalSize: 0,
+                encryptedSize: 0,
+                encryptedData,
+            }], `pending ledger ${attachmentId}`);
+    }
+    async clearPendingAttachmentUploadLedger(attachmentId) {
+        const deleteEntriesById = this.store.deleteEntriesById;
+        if (!deleteEntriesById) {
+            return;
+        }
+        await deleteEntriesById.call(this.store, [this.pendingAttachmentUploadLedgerId(attachmentId)]);
+    }
+    async cleanupIncompleteAttachmentUpload(docId, attachmentId) {
+        const store = this.getEffectiveAttachmentStore();
+        try {
+            await store.deleteEntriesForAttachment?.(docId, attachmentId);
+            await this.clearPendingAttachmentUploadLedger(attachmentId);
+            this.logger.info(`Cleaned up incomplete attachment upload ${attachmentId}`);
+        }
+        catch (cleanupError) {
+            this.logger.warn(`Failed to clean up incomplete attachment upload ${attachmentId}; boot recovery can retry`, cleanupError);
+        }
+    }
     /**
      * Internal method to add an attachment from a streaming data source.
      * Memory efficient - processes data chunk by chunk without loading entire file into memory.
@@ -3880,21 +6139,26 @@ class BaseMindooDB {
         const store = this.getEffectiveAttachmentStore();
         const currentUser = await this.tenant.getCurrentUserId();
         const attachmentId = (0, idGeneration_1.generateFileUuid7)();
-        // Buffer to accumulate incoming data until we have a full chunk
-        let buffer = new Uint8Array(0);
         let totalSize = 0;
         let prevChunkId = null;
         let lastChunkId = "";
         let chunkCount = 0;
-        // Helper to concatenate Uint8Arrays
-        const concatArrays = (a, b) => {
-            const result = new Uint8Array(a.length + b.length);
-            result.set(a, 0);
-            result.set(b, a.length);
-            return result;
+        const pendingEntries = [];
+        let pendingEncryptedBytes = 0;
+        let ledgerCreated = false;
+        const flushPendingEntries = async (force = false) => {
+            if (pendingEntries.length === 0) {
+                return;
+            }
+            if (!force && pendingEncryptedBytes < ATTACHMENT_WRITE_BATCH_BYTES) {
+                return;
+            }
+            const batch = pendingEntries.splice(0, pendingEntries.length);
+            pendingEncryptedBytes = 0;
+            await this.putEntriesWithRetry(store, batch, `attachment ${attachmentId} (${batch.length} chunks)`);
         };
         // Helper to store a chunk
-        const storeChunk = async (chunkData) => {
+        const queueChunk = async (chunkData) => {
             // Encrypt chunk
             const encryptedData = await this.tenant.encryptAttachmentPayload(chunkData, decryptionKeyId);
             // Compute content hash
@@ -3911,6 +6175,7 @@ class BaseMindooDB {
                 docId,
                 dependencyIds: prevChunkId ? [prevChunkId] : [],
                 createdAt,
+                attachmentId,
                 createdByPublicKey: currentUser.userSigningPublicKey,
                 decryptionKeyId,
                 signature,
@@ -3918,42 +6183,61 @@ class BaseMindooDB {
                 encryptedSize: encryptedData.length,
                 encryptedData,
             };
-            // Store immediately (streaming - don't buffer chunks in memory)
-            await store.putEntries([chunkEntry]);
+            pendingEntries.push(chunkEntry);
+            pendingEncryptedBytes += encryptedData.length;
             chunkCount++;
+            await flushPendingEntries();
             return chunkId;
         };
-        // Process incoming data stream
-        for await (const chunk of dataStream) {
-            // Add incoming data to buffer
-            buffer = concatArrays(buffer, chunk);
-            // Process complete chunks
-            while (buffer.length >= this.chunkSizeBytes) {
-                const chunkData = buffer.slice(0, this.chunkSizeBytes);
-                buffer = buffer.slice(this.chunkSizeBytes);
-                lastChunkId = await storeChunk(chunkData);
+        try {
+            await this.createPendingAttachmentUploadLedger(docId, attachmentId, decryptionKeyId, createdAt, currentUser.userSigningPublicKey);
+            ledgerCreated = true;
+            const accumulator = new Uint8Array(this.chunkSizeBytes);
+            let cursor = 0;
+            const writeFilledChunk = async (chunkData) => {
+                lastChunkId = await queueChunk(chunkData);
                 prevChunkId = lastChunkId;
                 totalSize += chunkData.length;
+            };
+            // Process incoming data stream without reallocating the pending buffer.
+            for await (const chunk of dataStream) {
+                let offset = 0;
+                while (offset < chunk.byteLength) {
+                    const writableBytes = Math.min(this.chunkSizeBytes - cursor, chunk.byteLength - offset);
+                    accumulator.set(chunk.subarray(offset, offset + writableBytes), cursor);
+                    cursor += writableBytes;
+                    offset += writableBytes;
+                    if (cursor === this.chunkSizeBytes) {
+                        await writeFilledChunk(accumulator.slice());
+                        cursor = 0;
+                    }
+                }
             }
+            // Store remaining data as final chunk (if any)
+            if (cursor > 0) {
+                await writeFilledChunk(accumulator.slice(0, cursor));
+            }
+            await flushPendingEntries(true);
+            this.logger.debug(`Stored ${chunkCount} chunks for streaming attachment ${attachmentId} (${totalSize} bytes)`);
+            // Create attachment reference
+            const ref = {
+                attachmentId,
+                fileName,
+                mimeType,
+                size: totalSize,
+                lastChunkId,
+                decryptionKeyId,
+                createdAt,
+                createdBy: currentUser.userSigningPublicKey,
+            };
+            return ref;
         }
-        // Store remaining data as final chunk (if any)
-        if (buffer.length > 0) {
-            lastChunkId = await storeChunk(buffer);
-            totalSize += buffer.length;
+        catch (error) {
+            if (ledgerCreated || chunkCount > 0) {
+                await this.cleanupIncompleteAttachmentUpload(docId, attachmentId);
+            }
+            throw error;
         }
-        this.logger.debug(`Stored ${chunkCount} chunks for streaming attachment ${attachmentId} (${totalSize} bytes)`);
-        // Create attachment reference
-        const ref = {
-            attachmentId,
-            fileName,
-            mimeType,
-            size: totalSize,
-            lastChunkId,
-            decryptionKeyId,
-            createdAt,
-            createdBy: currentUser.userSigningPublicKey,
-        };
-        return ref;
     }
     /**
      * Internal method to append data to an existing attachment.
@@ -3985,6 +6269,7 @@ class BaseMindooDB {
                 docId,
                 dependencyIds: [prevChunkId],
                 createdAt,
+                attachmentId,
                 createdByPublicKey: currentUser.userSigningPublicKey,
                 decryptionKeyId,
                 signature,
@@ -4082,6 +6367,7 @@ class BaseMindooDB {
      * @return A promise that resolves with the sync result
      */
     async pullChangesFrom(remote, options) {
+        this.assertWritable("pullChangesFrom");
         const storeKind = options?.storeKind ?? types_2.StoreKind.docs;
         const localStore = this.getStoreForKind(storeKind);
         const remoteStore = this.resolveStore(remote, storeKind);
@@ -4165,6 +6451,7 @@ class BaseMindooDB {
      * @return A promise that resolves with the sync result
      */
     async pushChangesTo(remote, options) {
+        this.assertWritable("pushChangesTo");
         const storeKind = options?.storeKind ?? types_2.StoreKind.docs;
         const localStore = this.getStoreForKind(storeKind);
         const remoteStore = this.resolveStore(remote, storeKind);