mindoodb 0.0.23 → 0.0.24

package/dist/core/BaseMindooDB.js

@@ -779,6 +779,22 @@ class BaseMindooDB {
         }
         this.automergeHashToEntryId.get(docId).set(automergeHash, entryId);
     }
+    registerAutomergeHashMappingIfAbsent(docId, automergeHash, entryId) {
+        if (this.getEntryIdForAutomergeHash(docId, automergeHash)) {
+            return;
+        }
+        this.registerAutomergeHashMapping(docId, automergeHash, entryId);
+    }
+    registerSnapshotHeadHashMappings(metadata) {
+        if (metadata.entryType !== "doc_snapshot") {
+            return;
+        }
+        for (const headHash of metadata.snapshotHeadHashes ?? []) {
+            // A dense sync may keep only a snapshot for covered heads. In that case
+            // the snapshot entry is the local causal parent for future changes.
+            this.registerAutomergeHashMappingIfAbsent(metadata.docId, headHash, metadata.id);
+        }
+    }
     /**
      * Get the entry ID for an automerge hash within a document.
      * Returns null if not found.
@@ -823,6 +839,9 @@ class BaseMindooDB {
             }
             this.registerAutomergeHashMapping(docId, parsed.automergeHash, metadata.id);
         }
+        for (const metadata of allMetadata) {
+            this.registerSnapshotHeadHashMappings(metadata);
+        }
     }
     /**
      * Resolve Automerge dependency hashes to entry IDs without silently dropping parents.
@@ -2128,6 +2147,7 @@ class BaseMindooDB {
                     if (parsed) {
                         this.registerAutomergeHashMapping(docId, parsed.automergeHash, snapshotData.id);
                     }
+                    this.registerSnapshotHeadHashMappings(snapshotData);
                 }
             }
         }
@@ -3688,12 +3708,12 @@ class BaseMindooDB {
         // Lifecycle changes are intentionally non-destructive: they only bump
         // `_lastModified` and repair missing legacy attachment arrays. The document
         // body remains available for history and future undeletion.
-        const newDoc = automerge_adapter_1.Automerge.change(internalDoc.doc, { time: now }, (doc) => {
-            if (!Array.isArray(doc._attachments)) {
-                doc._attachments = [];
+        const newDoc = this.runChangeWithOutdatedDocRecovery(internalDoc, (doc) => automerge_adapter_1.Automerge.change(doc, { time: now }, (mutableDoc) => {
+            if (!Array.isArray(mutableDoc._attachments)) {
+                mutableDoc._attachments = [];
             }
-            doc._lastModified = now;
-        });
+            mutableDoc._lastModified = now;
+        }));
         const changeBytes = automerge_adapter_1.Automerge.getLastLocalChange(newDoc);
         if (!changeBytes) {
             throw new Error("Failed to get change bytes from Automerge document");
@@ -3821,13 +3841,13 @@ class BaseMindooDB {
         };
         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);
-            }
+            newDoc = this.runChangeWithOutdatedDocRecovery(internalDoc, (doc) => {
+                if (baseHeads && baseHeads.length > 0) {
+                    const result = automerge_adapter_1.Automerge.changeAt(doc, baseHeads, applyEdits);
+                    return result.newDoc;
+                }
+                return automerge_adapter_1.Automerge.change(doc, applyEdits);
+            });
             this.logger.debug(`Successfully applied text patch, new document heads: ${JSON.stringify(automerge_adapter_1.Automerge.getHeads(newDoc))}`);
         }
         catch (error) {
@@ -3874,20 +3894,34 @@ class BaseMindooDB {
         this.validateRichTextPatch(patch);
         const now = Date.now();
         const headsBeforeChange = automerge_adapter_1.Automerge.getHeads(internalDoc.doc);
+        const spansSequence = patch.spansSequence ?? (patch.spans ? [patch.spans] : []);
         const applySpans = (automergeDoc) => {
             this.ensureRichTextPath(automergeDoc, patch.path);
-            automerge_adapter_1.Automerge.updateSpans(automergeDoc, patch.path, this.reviveRichTextSpans(patch.spans), patch.updateSpansConfig);
+            for (const spans of spansSequence) {
+                const revivedSpans = this.reviveRichTextSpans(spans);
+                try {
+                    automerge_adapter_1.Automerge.updateSpans(automergeDoc, patch.path, revivedSpans, patch.updateSpansConfig);
+                }
+                catch (error) {
+                    if (!this.isRichTextUpdateSpansBoundsError(error)) {
+                        throw error;
+                    }
+                    this.logger.warn(`updateSpans failed for document ${docId} at '${patch.path.map(String).join(".")}', resetting rich-text field and applying snapshot from scratch`, error);
+                    this.setJsonValueAtPath(automergeDoc, patch.path, "");
+                    automerge_adapter_1.Automerge.updateSpans(automergeDoc, patch.path, revivedSpans, patch.updateSpansConfig);
+                }
+            }
             automergeDoc._lastModified = now;
         };
         let newDoc;
         try {
-            if (patch.baseHeads && patch.baseHeads.length > 0) {
-                const result = automerge_adapter_1.Automerge.changeAt(internalDoc.doc, patch.baseHeads, applySpans);
-                newDoc = result.newDoc;
-            }
-            else {
-                newDoc = automerge_adapter_1.Automerge.change(internalDoc.doc, applySpans);
-            }
+            newDoc = this.runChangeWithOutdatedDocRecovery(internalDoc, (doc) => {
+                if (patch.baseHeads && patch.baseHeads.length > 0) {
+                    const result = automerge_adapter_1.Automerge.changeAt(doc, patch.baseHeads, applySpans);
+                    return result.newDoc;
+                }
+                return automerge_adapter_1.Automerge.change(doc, applySpans);
+            });
             this.logger.debug(`Successfully applied rich-text patch, new document heads: ${JSON.stringify(automerge_adapter_1.Automerge.getHeads(newDoc))}`);
         }
         catch (error) {
@@ -3909,6 +3943,92 @@ class BaseMindooDB {
             data: wrapped.getData(),
         };
     }
+    async applyRichTextStepsPatch(doc, patch) {
+        this.assertWritable("applyRichTextStepsPatch");
+        const docId = doc.getId();
+        this.logger.debug(`===== applyRichTextStepsPatch 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.validateRichTextStepPatch(patch);
+        const now = Date.now();
+        const headsBeforeChange = automerge_adapter_1.Automerge.getHeads(internalDoc.doc);
+        const applySteps = (automergeDoc) => {
+            this.ensureRichTextPath(automergeDoc, patch.path);
+            const beforeValue = this.readValueAtPath(automergeDoc, patch.path);
+            const beforeLength = typeof beforeValue === "string" ? beforeValue.length : null;
+            this.logger.info("[RichTextSteps] Applying positional steps", {
+                docId,
+                path: patch.path,
+                baseHeads: patch.baseHeads,
+                stepCount: patch.steps.length,
+                firstStep: patch.steps[0],
+                beforeLength,
+            });
+            for (const step of patch.steps) {
+                automerge_adapter_1.Automerge.splice(automergeDoc, patch.path, step.index, step.deleteCount, step.insert ?? "");
+                for (const markRange of step.marks ?? []) {
+                    for (const [name, value] of Object.entries(markRange.marks)) {
+                        automerge_adapter_1.Automerge.mark(automergeDoc, patch.path, {
+                            start: markRange.index,
+                            end: markRange.index + markRange.length,
+                            expand: "none",
+                        }, name, this.reviveRichTextValue(value));
+                    }
+                }
+            }
+            const afterValue = this.readValueAtPath(automergeDoc, patch.path);
+            this.logger.info("[RichTextSteps] Applied positional steps", {
+                docId,
+                afterLength: typeof afterValue === "string" ? afterValue.length : null,
+            });
+            automergeDoc._lastModified = now;
+        };
+        let newDoc;
+        try {
+            newDoc = this.runChangeWithOutdatedDocRecovery(internalDoc, (doc) => {
+                if (patch.baseHeads && patch.baseHeads.length > 0) {
+                    const result = automerge_adapter_1.Automerge.changeAt(doc, patch.baseHeads, applySteps);
+                    return result.newDoc;
+                }
+                return automerge_adapter_1.Automerge.change(doc, applySteps);
+            });
+            this.logger.debug(`Successfully applied rich-text steps, new document heads: ${JSON.stringify(automerge_adapter_1.Automerge.getHeads(newDoc))}`);
+        }
+        catch (error) {
+            this.logger.error(`Error applying rich-text steps for document ${docId}:`, error);
+            throw error;
+        }
+        await this.persistDocumentChange({
+            internalDoc,
+            newDoc,
+            now,
+            headsBeforeChange,
+            useCustomKey: false,
+            successMessage: "rich text steps patched",
+        });
+        const wrapped = this.wrapDocument(internalDoc);
+        return {
+            doc: wrapped,
+            heads: wrapped.getHeads(),
+            data: wrapped.getData(),
+        };
+    }
     async getRichTextSnapshot(doc, path) {
         const docId = doc.getId();
         this.validateJsonPath(path, "Rich-text snapshot");
@@ -3933,6 +4053,122 @@ class BaseMindooDB {
             spans: this.dehydrateRichTextSpans(spans),
         };
     }
+    async exportAutomergeSnapshot(doc) {
+        const internalDoc = await this.resolveReadableInternalDoc(doc);
+        const binary = automerge_adapter_1.Automerge.save(internalDoc.doc);
+        return {
+            binary: new Uint8Array(binary),
+            heads: automerge_adapter_1.Automerge.getHeads(internalDoc.doc),
+        };
+    }
+    async applyAutomergeChanges(doc, patch) {
+        this.assertWritable("applyAutomergeChanges");
+        const docId = doc.getId();
+        this.logger.debug(`===== applyAutomergeChanges 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");
+            }
+        }
+        if (!Array.isArray(patch.changes) || patch.changes.length === 0) {
+            throw new Error("Automerge changes patch must include at least one change byte sequence");
+        }
+        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`);
+        }
+        await this.hydrateAutomergeHashMappingsFromStore(docId);
+        const now = Date.now();
+        const headsBeforeChange = automerge_adapter_1.Automerge.getHeads(internalDoc.doc);
+        if (patch.baseHeads?.length) {
+            const baseHeadsKey = [...patch.baseHeads].sort().join("|");
+            const currentHeadsKey = [...headsBeforeChange].sort().join("|");
+            if (baseHeadsKey !== currentHeadsKey) {
+                this.logger.debug(`Applying Automerge changes for document ${docId} with stale baseHeads; merging into current heads`);
+            }
+        }
+        let newDoc;
+        try {
+            newDoc = this.runChangeWithOutdatedDocRecovery(internalDoc, (currentDoc) => {
+                const [mergedDoc] = automerge_adapter_1.Automerge.applyChanges(currentDoc, patch.changes.map((change) => new Uint8Array(change)));
+                return mergedDoc;
+            });
+            this.logger.debug(`Successfully applied Automerge changes, new document heads: ${JSON.stringify(automerge_adapter_1.Automerge.getHeads(newDoc))}`);
+        }
+        catch (error) {
+            this.logger.error(`Error applying Automerge changes for document ${docId}:`, error);
+            throw error;
+        }
+        const incomingChanges = patch.changes.map((change) => new Uint8Array(change));
+        const changesToPersist = incomingChanges.filter((changeBytes) => {
+            const hash = automerge_adapter_1.Automerge.decodeChange(changeBytes).hash;
+            return this.getEntryIdForAutomergeHash(docId, hash) === null;
+        });
+        if (changesToPersist.length === 0) {
+            internalDoc.doc = newDoc;
+            internalDoc.lastModified = now;
+            await this.storeCachedDocument(internalDoc);
+            this.markDocDirty(docId);
+        }
+        else {
+            await this.persistAutomergeDocumentChanges({
+                internalDoc,
+                newDoc,
+                now,
+                changeBytesList: changesToPersist,
+                useCustomKey: false,
+                successMessage: "Automerge changes applied",
+            });
+        }
+        const wrapped = this.wrapDocument(internalDoc);
+        const mergedHeads = wrapped.getHeads();
+        let changesSince;
+        if (patch.replicaHeads?.length) {
+            try {
+                const missingChanges = automerge_adapter_1.Automerge.getChangesSince(newDoc, patch.replicaHeads);
+                changesSince = {
+                    sinceHeads: [...patch.replicaHeads],
+                    changes: missingChanges.map((change) => new Uint8Array(change)),
+                };
+            }
+            catch (error) {
+                this.logger.debug(`Could not compute Automerge changesSince for document ${docId}:`, error);
+            }
+        }
+        return {
+            doc: wrapped,
+            heads: mergedHeads,
+            data: wrapped.getData(),
+            changesSince,
+        };
+    }
+    async resolveReadableInternalDoc(doc) {
+        const docId = doc.getId();
+        let internalDoc = this.wrappedInternalDocs.get(doc) ?? null;
+        if (!internalDoc) {
+            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`);
+        }
+        return internalDoc;
+    }
     async applyJsonPatch(doc, patch) {
         this.assertWritable("applyJsonPatch");
         const docId = doc.getId();
@@ -3964,13 +4200,13 @@ class BaseMindooDB {
         };
         let newDoc;
         try {
-            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, applyPatch);
-            }
+            newDoc = this.runChangeWithOutdatedDocRecovery(internalDoc, (doc) => {
+                if (patch.baseHeads && patch.baseHeads.length > 0) {
+                    const result = automerge_adapter_1.Automerge.changeAt(doc, patch.baseHeads, applyPatch);
+                    return result.newDoc;
+                }
+                return automerge_adapter_1.Automerge.change(doc, applyPatch);
+            });
             this.logger.debug(`Successfully applied JSON patch, new document heads: ${JSON.stringify(automerge_adapter_1.Automerge.getHeads(newDoc))}`);
         }
         catch (error) {
@@ -4215,7 +4451,7 @@ class BaseMindooDB {
         const headsBeforeChange = automerge_adapter_1.Automerge.getHeads(internalDoc.doc);
         let newDoc;
         try {
-            newDoc = automerge_adapter_1.Automerge.change(internalDoc.doc, (automergeDoc) => {
+            newDoc = this.runChangeWithOutdatedDocRecovery(internalDoc, (doc) => automerge_adapter_1.Automerge.change(doc, (automergeDoc) => {
                 // Apply all pending changes (sets/updates)
                 for (const [key, value] of pendingChanges) {
                     automergeDoc[key] = value;
@@ -4253,7 +4489,7 @@ class BaseMindooDB {
                 }
                 // Update lastModified timestamp
                 automergeDoc._lastModified = now;
-            });
+            }));
             this.logger.debug(`Successfully applied change function, new document heads: ${JSON.stringify(automerge_adapter_1.Automerge.getHeads(newDoc))}`);
         }
         catch (error) {
@@ -4308,7 +4544,10 @@ class BaseMindooDB {
         const operationCount = (patch.set?.length ?? 0)
             + (patch.unset?.length ?? 0)
             + (patch.listDelete?.length ?? 0)
-            + (patch.listInsert?.length ?? 0);
+            + (patch.listInsert?.length ?? 0)
+            + (patch.textSplice?.length ?? 0)
+            + (patch.textMark?.length ?? 0)
+            + (patch.textUnmark?.length ?? 0);
         if (operationCount === 0) {
             throw new Error("JSON patch must include at least one operation");
         }
@@ -4336,13 +4575,69 @@ class BaseMindooDB {
                 throw new Error("JSON listInsert values must be an array");
             }
         }
+        for (const operation of patch.textSplice ?? []) {
+            this.validateJsonPath(operation.path, "JSON textSplice");
+            if (!Number.isInteger(operation.index) || operation.index < 0) {
+                throw new Error("JSON textSplice index must be a non-negative integer");
+            }
+            if (!Number.isInteger(operation.deleteCount) || operation.deleteCount < 0) {
+                throw new Error("JSON textSplice deleteCount must be a non-negative integer");
+            }
+            if (operation.insert !== undefined && typeof operation.insert !== "string") {
+                throw new Error("JSON textSplice insert must be a string");
+            }
+        }
+        for (const operation of patch.textMark ?? []) {
+            this.validateJsonPath(operation.path, "JSON textMark");
+            if (!Number.isInteger(operation.index) || operation.index < 0) {
+                throw new Error("JSON textMark index must be a non-negative integer");
+            }
+            if (!Number.isInteger(operation.length) || operation.length <= 0) {
+                throw new Error("JSON textMark length must be a positive integer");
+            }
+            if (!operation.marks || typeof operation.marks !== "object" || Array.isArray(operation.marks)) {
+                throw new Error("JSON textMark marks must be an object");
+            }
+        }
+        for (const operation of patch.textUnmark ?? []) {
+            this.validateJsonPath(operation.path, "JSON textUnmark");
+            if (!Number.isInteger(operation.index) || operation.index < 0) {
+                throw new Error("JSON textUnmark index must be a non-negative integer");
+            }
+            if (!Number.isInteger(operation.length) || operation.length <= 0) {
+                throw new Error("JSON textUnmark length must be a positive integer");
+            }
+            if (!Array.isArray(operation.names) || operation.names.some((name) => typeof name !== "string" || !name)) {
+                throw new Error("JSON textUnmark names must be non-empty strings");
+            }
+        }
     }
     validateRichTextPatch(patch) {
         this.validateJsonPath(patch.path, "Rich-text patch");
-        if (!Array.isArray(patch.spans)) {
-            throw new Error("Rich-text patch spans must be an array");
+        const hasSpans = patch.spans !== undefined;
+        const hasSpansSequence = patch.spansSequence !== undefined;
+        if (hasSpans === hasSpansSequence) {
+            throw new Error("Rich-text patch must include exactly one of spans or spansSequence");
+        }
+        if (hasSpans) {
+            if (!Array.isArray(patch.spans)) {
+                throw new Error("Rich-text patch spans must be an array");
+            }
+            this.validateRichTextSpans(patch.spans);
+            return;
         }
-        for (const span of patch.spans) {
+        if (!Array.isArray(patch.spansSequence) || patch.spansSequence.length === 0) {
+            throw new Error("Rich-text patch spansSequence must be a non-empty array");
+        }
+        for (const spans of patch.spansSequence) {
+            if (!Array.isArray(spans)) {
+                throw new Error("Rich-text patch spansSequence entries must be arrays");
+            }
+            this.validateRichTextSpans(spans);
+        }
+    }
+    validateRichTextSpans(spans) {
+        for (const span of spans) {
             if (!span || typeof span !== "object") {
                 throw new Error("Rich-text span must be an object");
             }
@@ -4361,6 +4656,40 @@ class BaseMindooDB {
             throw new Error("Rich-text span type must be 'text' or 'block'");
         }
     }
+    validateRichTextStepPatch(patch) {
+        this.validateJsonPath(patch.path, "Rich-text steps patch");
+        if (!Array.isArray(patch.steps) || patch.steps.length === 0) {
+            throw new Error("Rich-text steps patch steps must be a non-empty array");
+        }
+        for (const step of patch.steps) {
+            if (!step || typeof step !== "object") {
+                throw new Error("Rich-text step must be an object");
+            }
+            if (step.type !== "splice") {
+                throw new Error("Rich-text step type must be 'splice'");
+            }
+            if (!Number.isInteger(step.index) || step.index < 0) {
+                throw new Error("Rich-text splice step index must be a non-negative integer");
+            }
+            if (!Number.isInteger(step.deleteCount) || step.deleteCount < 0) {
+                throw new Error("Rich-text splice step deleteCount must be a non-negative integer");
+            }
+            if (step.insert !== undefined && typeof step.insert !== "string") {
+                throw new Error("Rich-text splice step insert must be a string");
+            }
+            for (const markRange of step.marks ?? []) {
+                if (!Number.isInteger(markRange.index) || markRange.index < 0) {
+                    throw new Error("Rich-text mark range index must be a non-negative integer");
+                }
+                if (!Number.isInteger(markRange.length) || markRange.length <= 0) {
+                    throw new Error("Rich-text mark range length must be a positive integer");
+                }
+                if (!markRange.marks || typeof markRange.marks !== "object" || Array.isArray(markRange.marks)) {
+                    throw new Error("Rich-text mark range marks must be an object");
+                }
+            }
+        }
+    }
     validateJsonPath(path, label) {
         if (!Array.isArray(path) || path.length === 0) {
             throw new Error(`${label} path must contain at least one segment`);
@@ -4454,6 +4783,53 @@ class BaseMindooDB {
             const list = this.ensureJsonListAtPath(automergeDoc, operation.path);
             list.splice(operation.index, 0, ...structuredClone(operation.values));
         }
+        for (const operation of patch.textSplice ?? []) {
+            this.spliceJsonTextAtPath(automergeDoc, operation.path, operation.index, operation.deleteCount, operation.insert ?? "");
+        }
+        for (const operation of patch.textMark ?? []) {
+            for (const [name, value] of Object.entries(operation.marks)) {
+                automerge_adapter_1.Automerge.mark(automergeDoc, operation.path, {
+                    start: operation.index,
+                    end: operation.index + operation.length,
+                    expand: "none",
+                }, name, this.reviveRichTextValue(value));
+            }
+        }
+        for (const operation of patch.textUnmark ?? []) {
+            for (const name of operation.names) {
+                this.unmarkJsonTextAtPath(automergeDoc, operation.path, operation.index, operation.length, name);
+            }
+        }
+    }
+    spliceJsonTextAtPath(automergeDoc, path, index, deleteCount, insert) {
+        const value = this.readValueAtPath(automergeDoc, path);
+        if (value === undefined || value === null) {
+            this.setJsonValueAtPath(automergeDoc, path, "");
+        }
+        else if (typeof value !== "string") {
+            throw new Error(`Cannot apply JSON textSplice to non-string value at '${path.map(String).join(".")}'`);
+        }
+        const text = this.readValueAtPath(automergeDoc, path);
+        const length = typeof text === "string" ? text.length : 0;
+        automerge_adapter_1.Automerge.splice(automergeDoc, path, this.clampIndex(index, length), Math.max(0, Math.min(deleteCount, length - this.clampIndex(index, length))), insert);
+    }
+    unmarkJsonTextAtPath(automergeDoc, path, index, length, name) {
+        const range = {
+            start: index,
+            end: index + length,
+            expand: "none",
+        };
+        if (typeof automerge_adapter_1.Automerge.unmark === "function") {
+            automerge_adapter_1.Automerge.unmark(automergeDoc, path, range, name);
+            return;
+        }
+        automerge_adapter_1.Automerge.mark(automergeDoc, path, range, name, null);
+    }
+    clampIndex(index, length) {
+        if (!Number.isFinite(index)) {
+            return length;
+        }
+        return Math.max(0, Math.min(Math.trunc(index), length));
     }
     setJsonValueAtPath(target, path, value) {
         const parent = this.ensureJsonParentAtPath(target, path);
@@ -4463,6 +4839,13 @@ class BaseMindooDB {
         const parent = this.readJsonParentAtPath(target, path);
         delete parent[path[path.length - 1]];
     }
+    readValueAtPath(target, path) {
+        let value = target;
+        for (const segment of path) {
+            value = value?.[segment];
+        }
+        return value;
+    }
     readJsonListAtPath(target, path) {
         let value = target;
         for (const segment of path) {
@@ -4555,6 +4938,46 @@ class BaseMindooDB {
             throw new Error(`Cannot apply text patch to non-string value at '${path.map(String).join(".")}'`);
         }
     }
+    /**
+     * Run an Automerge change operation against `internalDoc.doc`, recovering
+     * from the "outdated document" error by cloning the cached doc and
+     * retrying once.
+     *
+     * Automerge marks a document as outdated whenever the JS reference has
+     * already been passed to `Automerge.change` / `Automerge.applyChanges` /
+     * `Automerge.changeAt` (the WASM handle's `state.heads` is set to a
+     * non-null value, putting the doc into "view" mode). The mindoodb cache
+     * normally avoids this by reassigning `internalDoc.doc = newDoc` after
+     * every change, but a stale reference (left over from an aborted or
+     * out-of-band Automerge operation) can still leak in. When that happens
+     * the doc is still semantically up to date - it just can't be mutated -
+     * and `Automerge.clone(...)` produces a fresh, writable copy at the same
+     * heads. The same workaround already lives in
+     * {@link applyNewEntriesToCachedDocument} (line ~6606) for the sync
+     * pipeline; this helper centralizes it for the patch / changeDoc paths.
+     */
+    runChangeWithOutdatedDocRecovery(internalDoc, apply) {
+        try {
+            return apply(internalDoc.doc);
+        }
+        catch (error) {
+            if (!this.isOutdatedDocumentError(error)) {
+                throw error;
+            }
+            this.logger.warn(`Cached document ${internalDoc.id} was outdated for Automerge; cloning to recover and retrying change`);
+            internalDoc.doc = automerge_adapter_1.Automerge.clone(internalDoc.doc);
+            return apply(internalDoc.doc);
+        }
+    }
+    isOutdatedDocumentError(error) {
+        if (!(error instanceof Error))
+            return false;
+        return /outdated document/i.test(error.message);
+    }
+    isRichTextUpdateSpansBoundsError(error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return /Cannot updateSpans|out of bounds/i.test(message);
+    }
     ensureRichTextPath(automergeDoc, path) {
         let target = automergeDoc;
         for (let i = 0; i < path.length - 1; i++) {
@@ -4592,6 +5015,60 @@ class BaseMindooDB {
         if (!changeBytes) {
             throw new Error("Failed to get change bytes from Automerge document");
         }
+        await this.persistAutomergeDocumentChanges({
+            internalDoc,
+            newDoc,
+            now,
+            changeBytesList: [changeBytes],
+            useCustomKey,
+            signingKeyPair,
+            signingKeyPassword,
+            successMessage,
+            attachmentIds,
+        });
+    }
+    async persistAutomergeDocumentChanges(options) {
+        const { internalDoc, newDoc, now, changeBytesList, headsBeforeChange, useCustomKey, signingKeyPair, signingKeyPassword, successMessage, attachmentIds, } = options;
+        const docId = internalDoc.id;
+        const resolvedChangeBytesList = changeBytesList ?? (headsBeforeChange
+            ? automerge_adapter_1.Automerge.getChangesSince(newDoc, headsBeforeChange)
+            : []);
+        if (resolvedChangeBytesList.length === 0) {
+            throw new Error("No Automerge changes to persist");
+        }
+        const entries = [];
+        for (let index = 0; index < resolvedChangeBytesList.length; index += 1) {
+            const changeBytes = resolvedChangeBytesList[index];
+            const entry = await this.buildDocChangeStoreEntry({
+                internalDoc,
+                changeBytes,
+                now,
+                useCustomKey,
+                signingKeyPair,
+                signingKeyPassword,
+                attachmentIds: index === 0 ? attachmentIds : undefined,
+            });
+            entries.push(entry);
+            const decodedChange = automerge_adapter_1.Automerge.decodeChange(changeBytes);
+            this.registerAutomergeHashMapping(docId, decodedChange.hash, entry.id);
+        }
+        await this.store.putEntries(entries);
+        internalDoc.doc = newDoc;
+        internalDoc.lastModified = now;
+        await this.storeCachedDocument(internalDoc);
+        this.updateIndex(docId, internalDoc.lastModified, internalDoc.isDeleted, internalDoc.decryptionKeyId, "visible");
+        this.markDocDirty(docId);
+        this.logger.info(`Document ${docId} ${successMessage} successfully`);
+        const createdByPublicKey = useCustomKey
+            ? signingKeyPair?.publicKey
+            : (await this.tenant.getCurrentUserId()).userSigningPublicKey;
+        await this.maybeWriteSnapshotForDocument(internalDoc, useCustomKey
+            ? { signingKeyPair, signingKeyPassword, createdByPublicKey: createdByPublicKey ?? "" }
+            : { createdByPublicKey: createdByPublicKey ?? "" });
+    }
+    async buildDocChangeStoreEntry(options) {
+        const { internalDoc, changeBytes, now, useCustomKey, signingKeyPair, signingKeyPassword, attachmentIds } = options;
+        const docId = internalDoc.id;
         this.logger.debug(`Got change bytes: ${changeBytes.length} bytes`);
         const decodedChange = automerge_adapter_1.Automerge.decodeChange(changeBytes);
         const automergeHash = decodedChange.hash;
@@ -4629,21 +5106,10 @@ class BaseMindooDB {
             encryptedSize: encryptedPayload.length,
             attachmentIds: attachmentIds && attachmentIds.length > 0 ? attachmentIds : undefined,
         };
-        const fullEntry = {
+        return {
             ...entryMetadata,
             encryptedData: encryptedPayload,
         };
-        await this.store.putEntries([fullEntry]);
-        this.registerAutomergeHashMapping(docId, automergeHash, entryId);
-        internalDoc.doc = newDoc;
-        internalDoc.lastModified = now;
-        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
-            ? { signingKeyPair, signingKeyPassword, createdByPublicKey }
-            : { createdByPublicKey });
     }
     /**
      * Best-effort snapshot scheduling and writing.
@@ -4977,6 +5443,7 @@ class BaseMindooDB {
                     if (parsed) {
                         this.registerAutomergeHashMapping(docId, parsed.automergeHash, snapshotData.id);
                     }
+                    this.registerSnapshotHeadHashMappings(snapshotData);
                 }
             }
         }
@@ -5799,6 +6266,7 @@ class BaseMindooDB {
                     if (parsed) {
                         this.registerAutomergeHashMapping(docId, parsed.automergeHash, snapshotData.id);
                     }
+                    this.registerSnapshotHeadHashMappings(snapshotData);
                 }
             }
         }