mindoodb 0.0.16 → 0.0.18

package/dist/core/BaseMindooDB.js

@@ -1,12 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BaseMindooDB = void 0;
+exports.BaseMindooDB = exports.CUSTOM_DOC_ID_INITIAL_CHANGE_BYTES = void 0;
 // Import platform-appropriate Automerge implementation
 // React Native: native Rust (react-native-automerge-generated)
 // Browser/Node.js: WASM (@automerge/automerge/slim)
 const automerge_adapter_1 = require("./automerge-adapter");
 const uuid_1 = require("uuid");
-const types_1 = require("./appendonlystores/types");
+const types_1 = require("./types");
+const types_2 = require("./appendonlystores/types");
 const bloom_1 = require("./appendonlystores/bloom");
 const MaterializationPlanner_1 = require("./appendonlystores/MaterializationPlanner");
 const DocumentDagAnalysis_1 = require("./DocumentDagAnalysis");
@@ -23,6 +24,50 @@ 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;
+/**
+ * Hard-coded initial Automerge change bytes that seed every document created
+ * with a caller-provided id (`createDocument({ id })`).
+ *
+ * Two replicas independently invoking `createDocument({ id: ... })` must
+ * produce the same initial Automerge change bytes/hash so the resulting
+ * `doc_create` entries converge. We hard-code the bytes (rather than
+ * regenerating them at runtime) for two reasons recommended by the Automerge
+ * cookbook:
+ *
+ *  1. Future Automerge releases may change change-byte encoding. Hard-coding
+ *     pins the wire format we shipped, so old custom-id docs stay mergeable.
+ *  2. It prevents accidental schema drift in this file from silently shifting
+ *     the doc_create entry id of every newly-created custom-id document.
+ *
+ * To intentionally regenerate these bytes (a breaking change for existing
+ * custom-id documents in the field), run
+ *   `node scripts/regen-custom-id-initial-change.js`
+ * paste the new array below, then update the expected hash in
+ * `__tests__/CustomIdInitialChange.test.ts`.
+ *
+ * The encoded change is:
+ *   actor: 00000000000000c0  (well-known, 8 bytes; only used for this seed)
+ *   time:  0
+ *   deps:  []
+ *   ops:   set `_attachments` = []
+ *   hash:  b55efb45769e62bff921fd6f4fbb325a446d788ded077ec2a625c32e7631a190
+ */
+/** @internal Exported for tests only; do not import from app code. */
+exports.CUSTOM_DOC_ID_INITIAL_CHANGE_BYTES = new Uint8Array([
+    133, 111, 74, 131, 181, 94, 251, 69, 1, 47, 0, 8, 0, 0, 0, 0,
+    0, 0, 0, 192, 1, 1, 0, 0, 0, 5, 21, 14, 52, 1, 66, 2,
+    86, 2, 112, 2, 127, 12, 95, 97, 116, 116, 97, 99, 104, 109, 101, 110,
+    116, 115, 1, 127, 2, 127, 0, 127, 0,
+]);
+/**
+ * Returns the hard-coded initial Automerge change bytes used to seed every
+ * custom-id document. Callers must apply these bytes into a fresh
+ * `Automerge.init()` so that subsequent edits use the replica's own actor id
+ * while still sharing Automerge ancestry with peers.
+ */
+function getCustomIdInitialChangeBytes() {
+    return exports.CUSTOM_DOC_ID_INITIAL_CHANGE_BYTES;
+}
 /**
  * BaseMindooDB is a platform-agnostic implementation of MindooDB
  * that works in both browser and server environments.
@@ -66,11 +111,11 @@ class BaseMindooDB {
         this.cachePrefix = null;
         this.dirtyDocIds = new Set();
         this.cacheMetaDirty = false;
-        if (store.getStoreKind() !== types_1.StoreKind.docs) {
-            throw new Error(`[BaseMindooDB] Expected primary store kind ${types_1.StoreKind.docs} but received ${store.getStoreKind()}`);
+        if (store.getStoreKind() !== types_2.StoreKind.docs) {
+            throw new Error(`[BaseMindooDB] Expected primary store kind ${types_2.StoreKind.docs} but received ${store.getStoreKind()}`);
         }
-        if (attachmentStore.getStoreKind() !== types_1.StoreKind.attachments) {
-            throw new Error(`[BaseMindooDB] Expected attachment store kind ${types_1.StoreKind.attachments} but received ${attachmentStore.getStoreKind()}`);
+        if (attachmentStore.getStoreKind() !== types_2.StoreKind.attachments) {
+            throw new Error(`[BaseMindooDB] Expected attachment store kind ${types_2.StoreKind.attachments} but received ${attachmentStore.getStoreKind()}`);
         }
         this.tenant = tenant;
         this.store = store;
@@ -499,6 +544,41 @@ class BaseMindooDB {
     getSubtle() {
         return this.tenant.getCryptoAdapter().getSubtle();
     }
+    isDocumentReplayEntry(entry) {
+        // Only these entry types participate in Automerge replay and document
+        // lifecycle state. Snapshots and attachment entries are derived side data.
+        return (entry.entryType === "doc_create" ||
+            entry.entryType === "doc_change" ||
+            entry.entryType === "doc_delete" ||
+            entry.entryType === "doc_undelete");
+    }
+    findActiveReplayHeadEntryIds(replayEntries) {
+        const replayIds = new Set(replayEntries.map((entry) => entry.id));
+        const referencedIds = new Set();
+        // A replay entry is no longer an active head once another replay entry
+        // depends on it. Remaining entries are the branch heads visible in metadata.
+        for (const entry of replayEntries) {
+            for (const depId of entry.dependencyIds) {
+                if (replayIds.has(depId)) {
+                    referencedIds.add(depId);
+                }
+            }
+        }
+        return replayEntries
+            .filter((entry) => !referencedIds.has(entry.id))
+            .sort((left, right) => left.createdAt !== right.createdAt
+            ? left.createdAt - right.createdAt
+            : left.id.localeCompare(right.id))
+            .map((entry) => entry.id);
+    }
+    computeIsDeletedFromMetadata(metadata, headEntryIds) {
+        // Deletion is intentionally metadata-derived: the latest reachable
+        // doc_delete/doc_undelete lifecycle entry wins without materializing the doc.
+        const replayEntries = metadata.filter((entry) => this.isDocumentReplayEntry(entry));
+        const replayById = new Map(replayEntries.map((entry) => [entry.id, entry]));
+        const heads = headEntryIds ?? this.findActiveReplayHeadEntryIds(replayEntries);
+        return (0, DocumentDagAnalysis_1.isDeletedFromHeads)(heads, replayById);
+    }
     /**
      * Initialize the database instance.
      * If a cache store is available, attempts to restore from cache first,
@@ -526,6 +606,7 @@ class BaseMindooDB {
             .filter((entry) => entry.entryType === "doc_create"
             || entry.entryType === "doc_change"
             || entry.entryType === "doc_delete"
+            || entry.entryType === "doc_undelete"
             || entry.entryType === "doc_snapshot")
             .map((entry) => entry.docId))).sort((left, right) => left.localeCompare(right));
         const missingDocIds = lifecycleDocIds.filter((docId) => !this.indexLookup.has(docId));
@@ -620,12 +701,13 @@ class BaseMindooDB {
                 }
                 else {
                     // Metadata-first startup: avoid full materialization for uncached docs.
-                    // Index based on doc-lifecycle entries (create/change/delete) plus
+                    // Index based on doc-lifecycle entries (create/change/delete/undelete) plus
                     // doc_snapshot which may be the sole entry after a dense sync.
                     // Attachment-only batches should not trigger document index updates.
                     const docLifecycleEntries = entryMetadataList.filter((e) => e.entryType === "doc_create" ||
                         e.entryType === "doc_change" ||
                         e.entryType === "doc_delete" ||
+                        e.entryType === "doc_undelete" ||
                         e.entryType === "doc_snapshot");
                     if (docLifecycleEntries.length === 0) {
                         this.logger.debug(`Skipping metadata-first index for doc ${docId} — no document lifecycle entries (${entryMetadataList.length} attachment/other entries only)`);
@@ -639,14 +721,13 @@ class BaseMindooDB {
                             this.logger.debug(`Skipping metadata-first index for doc ${docId} — decryption key "${representativeEntry.decryptionKeyId}" not available`);
                         }
                         else {
-                            const mutationEntries = docLifecycleEntries.filter((e) => e.entryType === "doc_create" ||
-                                e.entryType === "doc_change" ||
-                                e.entryType === "doc_delete");
+                            const allDocMetadata = await this.scanAllMetadata(this.store, { docId });
+                            const mutationEntries = allDocMetadata.filter((e) => this.isDocumentReplayEntry(e));
                             // Snapshots compact replay history but should not change the user-visible
-                            // modification time when the original create/change/delete entries still exist.
+                            // modification time when the original create/change/delete/undelete entries still exist.
                             const entriesForLastModified = mutationEntries.length > 0 ? mutationEntries : docLifecycleEntries;
                             const lastModified = Math.max(...entriesForLastModified.map((e) => e.createdAt));
-                            const isDeleted = mutationEntries.some((e) => e.entryType === "doc_delete");
+                            const isDeleted = this.computeIsDeletedFromMetadata(allDocMetadata);
                             this.updateIndex(docId, lastModified, isDeleted);
                             this.logger.debug(`Metadata-first update for uncached doc ${docId} (lastModified: ${lastModified}, isDeleted: ${isDeleted})`);
                         }
@@ -833,7 +914,7 @@ class BaseMindooDB {
         if (options?.transferBatchSize && options.transferBatchSize > 0) {
             return options.transferBatchSize;
         }
-        if (options?.storeKind === types_1.StoreKind.attachments) {
+        if (options?.storeKind === types_2.StoreKind.attachments) {
             return 100;
         }
         return options?.pageSize ?? 1000;
@@ -1053,9 +1134,9 @@ class BaseMindooDB {
      *
      * Algorithm:
      * 1. Discover all documents on the source via `doc_create` metadata.
-     * 2. Also fetch `doc_delete` metadata so deletion markers are transferred.
+     * 2. Also fetch `doc_delete` and `doc_undelete` metadata so lifecycle markers are transferred.
      * 3. Ask the source's batch planner for the optimal replay set per document.
-     * 4. Merge all entry IDs: doc_create + doc_delete + snapshot + uncovered changes.
+     * 4. Merge all entry IDs: doc_create + doc_delete + doc_undelete + snapshot + uncovered changes.
      * 5. Filter out IDs the target already has (bloom + exact check).
      * 6. Transfer only the missing entries.
      *
@@ -1076,6 +1157,7 @@ class BaseMindooDB {
         // ── Phase 1: discover documents ──────────────────────────────────
         const docCreateEntries = await sourceStore.findEntries("doc_create", null, null);
         const docDeleteEntries = await sourceStore.findEntries("doc_delete", null, null);
+        const docUndeleteEntries = await sourceStore.findEntries("doc_undelete", null, null);
         const docIds = [...new Set(docCreateEntries.map((e) => e.docId))];
         this.logger.info(`Dense sync: found ${docIds.length} documents on source`);
         if (docIds.length === 0) {
@@ -1100,6 +1182,9 @@ class BaseMindooDB {
         for (const entry of docDeleteEntries) {
             neededIds.add(entry.id);
         }
+        for (const entry of docUndeleteEntries) {
+            neededIds.add(entry.id);
+        }
         for (const plan of batchPlan.plans) {
             if (plan.snapshotEntryId) {
                 neededIds.add(plan.snapshotEntryId);
@@ -1156,23 +1241,48 @@ class BaseMindooDB {
     getTenant() {
         return this.tenant;
     }
-    async createDocument() {
-        return this.createEncryptedDocument("default");
+    async createDocument(options) {
+        return this.createDocumentInternal(options ?? {});
     }
+    /**
+     * @deprecated Use `createDocument({ decryptionKeyId })` instead.
+     */
     async createEncryptedDocument(decryptionKeyId) {
-        return this.createDocumentInternal(decryptionKeyId || "default");
+        return this.createDocumentInternal({ decryptionKeyId });
     }
+    /**
+     * @deprecated Use `createDocument({ signingKeyPair, signingKeyPassword, decryptionKeyId })` instead.
+     */
     async createDocumentWithSigningKey(signingKeyPair, signingKeyPassword, decryptionKeyId) {
-        return this.createDocumentInternal(decryptionKeyId || "default", signingKeyPair, signingKeyPassword);
+        return this.createDocumentInternal({ signingKeyPair, signingKeyPassword, decryptionKeyId });
     }
     /**
      * Internal method to create a new document.
-     * Handles both regular document creation (signed by current user) and
-     * document creation with a custom signing key (e.g., for directory operations).
+     *
+     * Handles all four creation flavors expressible through `CreateOptions`:
+     * - generated UUID7 ID, current user signs, default tenant key
+     * - generated UUID7 ID, custom signing key (e.g. directory admin operations)
+     * - caller-provided ID, current user signs (idempotent on existing IDs)
+     * - caller-provided ID with custom signing key
+     *
+     * For caller-provided IDs the initial Automerge change is seeded from a
+     * deterministic, hard-coded change so that two replicas creating the same
+     * custom ID converge when synced (see `getCustomIdInitialChangeBytes`).
      */
-    async createDocumentInternal(decryptionKeyId, signingKeyPair, signingKeyPassword) {
-        const keyId = decryptionKeyId;
+    async createDocumentInternal(options) {
+        const { signingKeyPair, signingKeyPassword } = options;
+        if ((signingKeyPair !== undefined) !== (signingKeyPassword !== undefined)) {
+            throw new Error("createDocument: signingKeyPair and signingKeyPassword must be provided together");
+        }
         const useCustomSigningKey = signingKeyPair !== undefined && signingKeyPassword !== undefined;
+        const keyId = options.decryptionKeyId ?? "default";
+        const useCustomDocId = options.id !== undefined;
+        if (useCustomDocId) {
+            if (!types_1.CUSTOM_DOC_ID_REGEX.test(options.id)) {
+                throw new Error(`createDocument: invalid document id "${options.id}". ` +
+                    `Custom document IDs must match ${types_1.CUSTOM_DOC_ID_REGEX.source}.`);
+            }
+        }
         // Admin-only validation: only admin key can modify data in admin-only databases
         if (this._isAdminOnlyDb) {
             const adminPublicKey = this.getAdminPublicKey();
@@ -1183,32 +1293,70 @@ class BaseMindooDB {
                 throw new Error("Admin-only database: only the admin key can modify data");
             }
         }
-        // Generate UUID7 for document ID
-        const docId = (0, uuid_1.v7)();
-        this.logger.debug(`Creating document ${docId} with key ${keyId}${useCustomSigningKey ? ' using custom signing key' : ''}`);
-        // Create initial Automerge document
-        const initialDoc = automerge_adapter_1.Automerge.init();
-        // Create the first change
+        const docId = useCustomDocId ? options.id : (0, uuid_1.v7)();
+        // Idempotent create: when a caller-provided id already exists locally,
+        // return the existing document instead of producing a duplicate doc_create.
+        if (useCustomDocId) {
+            const existing = await this.loadDocumentInternal(docId);
+            if (existing) {
+                if (existing.isDeleted) {
+                    this.logger.debug(`Document ${docId} exists as a tombstone; undeleting existing custom-id document`);
+                    await this.undeleteDocInternal(docId, signingKeyPair, signingKeyPassword);
+                    const undeleted = await this.loadDocumentInternal(docId);
+                    if (!undeleted || undeleted.isDeleted) {
+                        throw new Error(`Document ${docId} could not be undeleted`);
+                    }
+                    return this.wrapDocument(undeleted);
+                }
+                this.logger.debug(`Document ${docId} already exists locally; returning existing document`);
+                return this.wrapDocument(existing);
+            }
+        }
+        this.logger.debug(`Creating document ${docId} with key ${keyId}${useCustomSigningKey ? ' using custom signing key' : ''}${useCustomDocId ? ' with caller-provided id' : ''}`);
+        // Build the initial Automerge document and its first change bytes.
+        //
+        // For UUID7 documents we use the historical path (Automerge.init + change).
+        // For custom-ID documents we apply a hard-coded initial change so that
+        // independent replicas using the same id produce the same Automerge hash
+        // and `doc_create` entry id, allowing later changes to merge.
         const now = Date.now();
-        this.logger.debug(`Creating initial Automerge change for document ${docId}`);
         let newDoc;
-        try {
-            newDoc = automerge_adapter_1.Automerge.change(initialDoc, (doc) => {
-                // Store metadata in the document payload
-                // We need to modify the document to ensure a change is created
-                doc._attachments = [];
-            });
-            this.logger.debug(`Successfully created Automerge change, document heads: ${JSON.stringify(automerge_adapter_1.Automerge.getHeads(newDoc))}`);
-        }
-        catch (error) {
-            this.logger.error(`Error in Automerge.change for document ${docId}:`, error);
-            throw error;
+        let changeBytes;
+        if (useCustomDocId) {
+            this.logger.debug(`Seeding custom-id document ${docId} with hard-coded initial Automerge change`);
+            changeBytes = getCustomIdInitialChangeBytes();
+            try {
+                const fresh = automerge_adapter_1.Automerge.init();
+                const [appliedDoc] = automerge_adapter_1.Automerge.applyChanges(fresh, [changeBytes]);
+                newDoc = appliedDoc;
+                this.logger.debug(`Applied hard-coded initial change, heads: ${JSON.stringify(automerge_adapter_1.Automerge.getHeads(newDoc))}`);
+            }
+            catch (error) {
+                this.logger.error(`Error applying hard-coded initial change for document ${docId}:`, error);
+                throw error;
+            }
         }
-        // Get the change bytes from the document
-        this.logger.debug(`Getting change bytes from document ${docId}`);
-        const changeBytes = automerge_adapter_1.Automerge.getLastLocalChange(newDoc);
-        if (!changeBytes) {
-            throw new Error("Failed to get change bytes from Automerge document");
+        else {
+            this.logger.debug(`Creating initial Automerge change for document ${docId}`);
+            const initialDoc = automerge_adapter_1.Automerge.init();
+            try {
+                newDoc = automerge_adapter_1.Automerge.change(initialDoc, (doc) => {
+                    // Store metadata in the document payload
+                    // We need to modify the document to ensure a change is created
+                    doc._attachments = [];
+                });
+                this.logger.debug(`Successfully created Automerge change, document heads: ${JSON.stringify(automerge_adapter_1.Automerge.getHeads(newDoc))}`);
+            }
+            catch (error) {
+                this.logger.error(`Error in Automerge.change for document ${docId}:`, error);
+                throw error;
+            }
+            this.logger.debug(`Getting change bytes from document ${docId}`);
+            const localChange = automerge_adapter_1.Automerge.getLastLocalChange(newDoc);
+            if (!localChange) {
+                throw new Error("Failed to get change bytes from Automerge document");
+            }
+            changeBytes = localChange;
         }
         this.logger.debug(`Got change bytes: ${changeBytes.length} bytes`);
         // Decode the change to get hash and dependencies
@@ -1314,6 +1462,7 @@ class BaseMindooDB {
             && (em.entryType === "doc_create"
                 || em.entryType === "doc_change"
                 || em.entryType === "doc_delete"
+                || em.entryType === "doc_undelete"
                 || em.entryType === "doc_snapshot"))
             .sort((a, b) => a.createdAt - b.createdAt);
         if (relevantEntries.length === 0) {
@@ -1394,16 +1543,14 @@ class BaseMindooDB {
                 this.registerAutomergeHashMapping(docId, parsed.automergeHash, entryData.id);
             }
         }
-        const replayEntries = relevantEntries.filter((entry) => entry.entryType === "doc_create"
-            || entry.entryType === "doc_change"
-            || entry.entryType === "doc_delete");
+        const replayEntries = relevantEntries.filter((entry) => this.isDocumentReplayEntry(entry));
         const firstReplayEntry = replayEntries.length > 0 ? replayEntries[0] : null;
         const lastReplayEntry = replayEntries.length > 0 ? replayEntries[replayEntries.length - 1] : null;
         const createdAt = firstReplayEntry?.createdAt ?? snapshotMeta?.createdAt ?? timestamp;
         const decryptionKeyId = firstReplayEntry?.decryptionKeyId
             ?? snapshotMeta?.decryptionKeyId
             ?? "default";
-        const isDeleted = lastReplayEntry?.entryType === "doc_delete";
+        const isDeleted = this.computeIsDeletedFromMetadata(relevantEntries);
         const lastModified = lastReplayEntry?.createdAt ?? snapshotMeta?.createdAt ?? timestamp;
         const internalDoc = {
             id: docId,
@@ -1427,9 +1574,9 @@ class BaseMindooDB {
         this.logger.debug(`Iterating document history for ${docId}`);
         // Get all entry metadata for this document
         const allEntryMetadata = await this.scanAllMetadata(this.store, { docId });
-        // Filter to only doc_create, doc_change, and doc_delete entries (exclude snapshots)
+        // Filter to document replay entries (exclude snapshots)
         const relevantEntries = allEntryMetadata
-            .filter(em => em.entryType === "doc_create" || em.entryType === "doc_change" || em.entryType === "doc_delete")
+            .filter((em) => this.isDocumentReplayEntry(em))
             .sort((a, b) => a.createdAt - b.createdAt);
         if (relevantEntries.length === 0) {
             return; // Document has no history
@@ -1481,10 +1628,10 @@ class BaseMindooDB {
             currentDoc = automerge_adapter_1.Automerge.loadIncremental(currentDoc, decryptedPayload);
             // Check if document actually changed by comparing heads
             // For first entry (doc_create), always yield since it's the initial creation
-            // For delete entries, always yield
+            // For lifecycle terminal entries, always yield
             // For other entries, only yield if heads changed
             let shouldYield = false;
-            if (isFirstEntry || entryMetadata.entryType === "doc_delete") {
+            if (isFirstEntry || entryMetadata.entryType === "doc_delete" || entryMetadata.entryType === "doc_undelete") {
                 shouldYield = true;
             }
             else {
@@ -1508,20 +1655,18 @@ class BaseMindooDB {
                     createdAt: createdAt,
                     lastModified: entryMetadata.createdAt,
                     decryptionKeyId,
-                    isDeleted: entryMetadata.entryType === "doc_delete",
+                    isDeleted: this.computeIsDeletedFromMetadata(relevantEntries.filter((entry) => entry.createdAt < entryMetadata.createdAt ||
+                        (entry.createdAt === entryMetadata.createdAt && entry.id <= entryMetadata.id))),
                 };
-                // Wrap and yield (including delete entries)
+                // Wrap and yield (including lifecycle terminal entries)
                 const wrappedDoc = this.wrapDocument(internalDoc);
                 yield {
+                    changeEntryId: entryMetadata.id,
                     doc: wrappedDoc,
                     changeCreatedAt: entryMetadata.createdAt,
                     changeCreatedByPublicKey: entryMetadata.createdByPublicKey,
                 };
             }
-            // Stop after delete entry (document is deleted, no more changes)
-            if (entryMetadata.entryType === "doc_delete") {
-                break;
-            }
         }
     }
     async getDocumentHistoryPage(docId, options) {
@@ -1534,7 +1679,8 @@ class BaseMindooDB {
         const relevantEntries = allEntryMetadata
             .filter((em) => em.entryType === "doc_create" ||
             em.entryType === "doc_change" ||
-            em.entryType === "doc_delete")
+            em.entryType === "doc_delete" ||
+            em.entryType === "doc_undelete")
             .sort((a, b) => a.createdAt - b.createdAt);
         // Cursor paging is offset-based because the result is a bounded timeline view
         // over the doc's sorted change metadata, not a resumable store scan cursor.
@@ -1545,7 +1691,8 @@ class BaseMindooDB {
             changeCreatedAt: entry.createdAt,
             changeCreatedByPublicKey: entry.createdByPublicKey,
             dependencyIds: [...entry.dependencyIds],
-            isDeleted: entry.entryType === "doc_delete",
+            isDeleted: this.computeIsDeletedFromMetadata(relevantEntries.filter((candidate) => candidate.createdAt < entry.createdAt ||
+                (candidate.createdAt === entry.createdAt && candidate.id <= entry.id))),
         }));
         const nextOffset = offset + entries.length;
         const hasMore = nextOffset < relevantEntries.length;
@@ -1827,63 +1974,65 @@ class BaseMindooDB {
         // 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;
-        // Efficiently query for doc_create and doc_delete entries before the timestamp
-        const [creates, deletes] = await Promise.all([
+        // 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_delete", null, upperBoundExclusive),
+            this.store.findEntries("doc_undelete", null, upperBoundExclusive),
         ]);
-        // Build sets of docIds for efficient lookup
-        const createdDocIds = new Set();
-        const deletedDocIds = new Set();
-        // Track earliest create time for each doc
-        const createTimes = new Map();
+        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) ?? [];
+            entries.push(entry);
+            lifecycleEntriesByDocId.set(entry.docId, entries);
+        };
         for (const entry of creates) {
-            const existingTime = createTimes.get(entry.docId);
-            if (!existingTime || entry.createdAt < existingTime) {
-                createTimes.set(entry.docId, entry.createdAt);
-                createdDocIds.add(entry.docId);
-            }
+            addLifecycleEntry(entry);
         }
-        // Track earliest delete time for each doc
-        const deleteTimes = new Map();
         for (const entry of deletes) {
-            const existingTime = deleteTimes.get(entry.docId);
-            if (!existingTime || entry.createdAt < existingTime) {
-                deleteTimes.set(entry.docId, entry.createdAt);
-                deletedDocIds.add(entry.docId);
-            }
+            addLifecycleEntry(entry);
+        }
+        for (const entry of undeletes) {
+            addLifecycleEntry(entry);
         }
-        // Find documents that existed at the timestamp
         const docIds = [];
-        for (const docId of createdDocIds) {
-            const createTime = createTimes.get(docId);
-            const deleteTime = deleteTimes.get(docId);
-            // Document exists at timestamp if:
-            // 1. It was created at or before the timestamp
-            // 2. Either it was never deleted, or it was deleted after the timestamp
-            if (createTime <= timestamp) {
-                if (!deleteTime || deleteTime > timestamp) {
-                    docIds.push(docId);
-                }
+        for (const [docId, lifecycleEntries] of lifecycleEntriesByDocId.entries()) {
+            // Sort deterministically so same-timestamp lifecycle entries resolve the
+            // same way on every replica.
+            const ordered = lifecycleEntries.sort((a, b) => a.createdAt !== b.createdAt ? a.createdAt - b.createdAt : a.id.localeCompare(b.id));
+            // A document cannot exist before its create entry, even if malformed or
+            // partial metadata somehow contains later lifecycle entries.
+            if (!ordered.some((entry) => entry.entryType === "doc_create" && entry.createdAt <= timestamp)) {
+                continue;
+            }
+            // Delete and undelete are terminal lifecycle markers. The latest one at
+            // the timestamp decides whether the document existed then.
+            const latestTerminal = ordered
+                .filter((entry) => entry.entryType === "doc_delete" || entry.entryType === "doc_undelete")
+                .at(-1);
+            if (!latestTerminal || latestTerminal.entryType === "doc_undelete") {
+                docIds.push(docId);
             }
         }
         return docIds;
     }
-    async deleteDocument(docId) {
-        return this.deleteDocInternal(docId);
+    async deleteDocument(docId, options = {}) {
+        return this.deleteDocInternal(docId, options.signingKeyPair, options.signingKeyPassword);
     }
     async deleteDocumentWithSigningKey(docId, signingKeyPair, signingKeyPassword) {
-        return this.deleteDocInternal(docId, signingKeyPair, signingKeyPassword);
+        return this.deleteDocument(docId, { signingKeyPair, signingKeyPassword });
     }
-    /**
-     * Internal method to delete a document.
-     * Handles both regular deletion (signed by current user) and
-     * deletion with a custom signing key (e.g., for directory operations).
-     */
-    async deleteDocInternal(docId, signingKeyPair, signingKeyPassword) {
+    async undeleteDocument(docId, options = {}) {
+        return this.undeleteDocInternal(docId, options.signingKeyPair, options.signingKeyPassword);
+    }
+    async assertLifecycleMutationAllowed(signingKeyPair, signingKeyPassword) {
         const useCustomSigningKey = signingKeyPair !== undefined && signingKeyPassword !== undefined;
-        this.logger.debug(`Deleting document ${docId}${useCustomSigningKey ? ' using custom signing key' : ''}`);
-        // Admin-only validation: only admin key can modify data in admin-only databases
+        if ((signingKeyPair !== undefined) !== (signingKeyPassword !== undefined)) {
+            throw new Error("Lifecycle mutation requires both signingKeyPair and signingKeyPassword");
+        }
         if (this._isAdminOnlyDb) {
             const adminPublicKey = this.getAdminPublicKey();
             const signerPublicKey = useCustomSigningKey
@@ -1893,58 +2042,57 @@ class BaseMindooDB {
                 throw new Error("Admin-only database: only the admin key can modify data");
             }
         }
-        // Get current document
-        const internalDoc = await this.loadDocumentInternal(docId);
-        if (!internalDoc || internalDoc.isDeleted) {
-            throw new Error(`Document ${docId} not found or already deleted`);
-        }
+    }
+    /**
+     * Write a delete or undelete lifecycle entry for an existing document.
+     *
+     * The document body is preserved; this method only writes a small Automerge
+     * change that advances `_lastModified`, wraps it in the requested lifecycle
+     * StoreEntry type, signs/encrypts it, and updates local caches/indexes.
+     */
+    async writeLifecycleEntry(internalDoc, entryType, signingKeyPair, signingKeyPassword) {
+        // Delete and undelete are encoded as normal Automerge changes so the DAG
+        // keeps causal ancestry, while the StoreEntry type carries lifecycle intent.
+        const useCustomSigningKey = signingKeyPair !== undefined && signingKeyPassword !== undefined;
         const now = Date.now();
-        // Create deletion change by clearing all fields from the document
-        // This ensures Automerge produces actual change bytes
-        // The deletion is also tracked via the "doc_delete" type entry in the append-only store
-        const newDoc = automerge_adapter_1.Automerge.change(internalDoc.doc, (doc) => {
-            // Remove all fields from the document
-            for (const key of Object.keys(doc)) {
-                delete doc[key];
-            }
-            // Mark as deleted for clarity
-            doc._deleted = true;
+        const docId = internalDoc.id;
+        // 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 = [];
+            }
             doc._lastModified = now;
         });
-        // Get the change bytes from the document
         const changeBytes = automerge_adapter_1.Automerge.getLastLocalChange(newDoc);
         if (!changeBytes) {
             throw new Error("Failed to get change bytes from Automerge document");
         }
-        // Decode the change to get hash and dependencies
         const decodedChange = automerge_adapter_1.Automerge.decodeChange(changeBytes);
         const automergeHash = decodedChange.hash;
-        const automergeDepHashes = decodedChange.deps || []; // Dependencies from the decoded change
-        // Encrypt the change payload first
+        const automergeDepHashes = decodedChange.deps || [];
         const encryptedPayload = await this.tenant.encryptPayload(changeBytes, internalDoc.decryptionKeyId);
-        // Compute content hash from encrypted data
         const contentHash = await (0, idGeneration_1.computeContentHash)(encryptedPayload, this.getSubtle());
-        // Generate entry ID with blockchain-like chaining
         const entryId = await (0, idGeneration_1.generateDocEntryId)(docId, automergeHash, automergeDepHashes, this.getSubtle());
-        // Resolve Automerge dependency hashes to entry IDs
+        // Convert Automerge dependency hashes back into store entry IDs so metadata
+        // consumers can traverse the lifecycle DAG without decrypting payloads.
         const dependencyIds = await this.ensureAutomergeDepsResolved(docId, automergeDepHashes);
-        // Sign the encrypted payload - either with custom key or current user's key
         let signature;
         let createdByPublicKey;
         if (useCustomSigningKey) {
-            this.logger.debug(`Signing deletion for document ${docId} with provided key`);
             signature = await this.tenant.signPayloadWithKey(encryptedPayload, signingKeyPair, signingKeyPassword);
             createdByPublicKey = signingKeyPair.publicKey;
         }
         else {
-            this.logger.debug(`Signing deletion for document ${docId} with current user's key`);
             const currentUser = await this.tenant.getCurrentUserId();
             signature = await this.tenant.signPayload(encryptedPayload);
             createdByPublicKey = currentUser.userSigningPublicKey;
         }
-        // Create entry metadata with type "doc_delete" to mark this as a deletion entry in the store
+        // The encrypted Automerge change is the payload; the metadata classifies it
+        // as a delete or undelete lifecycle entry for fast history/view queries.
         const entryMetadata = {
-            entryType: "doc_delete",
+            entryType,
             id: entryId,
             contentHash,
             docId,
@@ -1956,32 +2104,127 @@ class BaseMindooDB {
             originalSize: changeBytes.length,
             encryptedSize: encryptedPayload.length,
         };
-        // Create full entry object
         const fullEntry = {
             ...entryMetadata,
             encryptedData: encryptedPayload,
         };
-        // Store entry
         await this.store.putEntries([fullEntry]);
-        // Register automerge hash -> entry ID mapping
         this.registerAutomergeHashMapping(docId, automergeHash, entryId);
-        // Update cache and index
-        internalDoc.isDeleted = true;
+        // Keep the loaded document, cache, index, and sync dirty tracking in step
+        // with the append-only store entry we just wrote.
+        internalDoc.doc = newDoc;
+        internalDoc.isDeleted = entryType === "doc_delete";
         internalDoc.lastModified = now;
         this.storeCachedDocument(internalDoc);
-        this.updateIndex(docId, internalDoc.lastModified, true);
+        this.updateIndex(docId, internalDoc.lastModified, internalDoc.isDeleted);
         this.markDocDirty(docId);
+    }
+    /**
+     * Internal method to delete a document.
+     * Handles both regular deletion (signed by current user) and
+     * deletion with a custom signing key (e.g., for directory operations).
+     */
+    async deleteDocInternal(docId, signingKeyPair, signingKeyPassword) {
+        const useCustomSigningKey = signingKeyPair !== undefined && signingKeyPassword !== undefined;
+        this.logger.debug(`Deleting document ${docId}${useCustomSigningKey ? ' using custom signing key' : ''}`);
+        await this.assertLifecycleMutationAllowed(signingKeyPair, signingKeyPassword);
+        // Get current document
+        const internalDoc = await this.loadDocumentInternal(docId);
+        if (!internalDoc || internalDoc.isDeleted) {
+            throw new Error(`Document ${docId} not found or already deleted`);
+        }
+        await this.writeLifecycleEntry(internalDoc, "doc_delete", signingKeyPair, signingKeyPassword);
         this.logger.info(`Document ${docId} deleted successfully`);
     }
-    async changeDoc(doc, changeFunc) {
-        return this.changeDocInternal(doc, changeFunc);
+    async undeleteDocInternal(docId, signingKeyPair, signingKeyPassword) {
+        const useCustomSigningKey = signingKeyPair !== undefined && signingKeyPassword !== undefined;
+        this.logger.debug(`Undeleting document ${docId}${useCustomSigningKey ? ' using custom signing key' : ''}`);
+        await this.assertLifecycleMutationAllowed(signingKeyPair, signingKeyPassword);
+        const internalDoc = await this.loadDocumentInternal(docId);
+        if (!internalDoc) {
+            throw new Error(`Document ${docId} not found`);
+        }
+        if (!internalDoc.isDeleted) {
+            this.logger.debug(`Document ${docId} is already alive; undelete is a no-op`);
+            return;
+        }
+        await this.writeLifecycleEntry(internalDoc, "doc_undelete", signingKeyPair, signingKeyPassword);
+        this.logger.info(`Document ${docId} undeleted successfully`);
+    }
+    async changeDoc(doc, changeFunc, options = {}) {
+        return this.changeDocInternal(doc, changeFunc, options.signingKeyPair, options.signingKeyPassword);
     }
     async changeDocWithSigningKey(doc, changeFunc, signingKeyPair, signingKeyPassword) {
-        return this.changeDocInternal(doc, changeFunc, signingKeyPair, signingKeyPassword);
+        return this.changeDoc(doc, changeFunc, { signingKeyPair, signingKeyPassword });
+    }
+    async applyTextPatch(doc, patch) {
+        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 changeDocInternal(doc, changeFunc, signingKeyPair, signingKeyPassword) {
         const docId = doc.getId();
-        const useCustomKey = signingKeyPair && signingKeyPassword;
+        if ((signingKeyPair !== undefined) !== (signingKeyPassword !== undefined)) {
+            throw new Error("changeDoc: signingKeyPair and signingKeyPassword must be provided together");
+        }
+        const useCustomKey = signingKeyPair !== undefined && signingKeyPassword !== undefined;
         this.logger.debug(`===== ${useCustomKey ? 'changeDocWithSigningKey' : 'changeDoc'} called for document ${docId} =====`);
         // Admin-only validation: only admin key can modify data in admin-only databases
         if (this._isAdminOnlyDb) {
@@ -2046,6 +2289,7 @@ class BaseMindooDB {
             getLastModified: () => internalDoc.lastModified,
             getDecryptionKeyId: () => internalDoc.decryptionKeyId,
             isDeleted: () => false,
+            getHeads: () => automerge_adapter_1.Automerge.getHeads(internalDoc.doc),
             getData: () => {
                 // Return a proxy that collects property assignments and deletions
                 const currentData = internalDoc.doc;
@@ -2187,6 +2431,7 @@ class BaseMindooDB {
         // Deactivate the callback guard - no more changes can be made via collectingDoc
         isCallbackActive = false;
         // Now apply the collected changes synchronously in Automerge.change()
+        const headsBeforeChange = automerge_adapter_1.Automerge.getHeads(internalDoc.doc);
         let newDoc;
         try {
             newDoc = automerge_adapter_1.Automerge.change(internalDoc.doc, (automergeDoc) => {
@@ -2234,31 +2479,93 @@ class BaseMindooDB {
             this.logger.error(`Error in Automerge.change for document ${docId}:`, error);
             throw error;
         }
-        // Get the change bytes from the document
+        await this.persistDocumentChange({
+            internalDoc,
+            newDoc,
+            now,
+            headsBeforeChange,
+            useCustomKey: Boolean(useCustomKey),
+            signingKeyPair,
+            signingKeyPassword,
+            successMessage: useCustomKey ? "changed with custom signing key" : "changed",
+        });
+    }
+    validateTextPatch(patch) {
+        if (!Array.isArray(patch.path) || patch.path.length === 0) {
+            throw new Error("Text patch path must contain at least one segment");
+        }
+        for (const segment of patch.path) {
+            if (typeof segment !== "string" && typeof segment !== "number") {
+                throw new Error("Text patch path segments must be strings or numbers");
+            }
+        }
+        if (!Array.isArray(patch.edits) || patch.edits.length === 0) {
+            throw new Error("Text patch must include at least one edit");
+        }
+        for (const edit of patch.edits) {
+            if (!Number.isInteger(edit.index) || edit.index < 0) {
+                throw new Error("Text edit index must be a non-negative integer");
+            }
+            if (!Number.isInteger(edit.deleteCount) || edit.deleteCount < 0) {
+                throw new Error("Text edit deleteCount must be a non-negative integer");
+            }
+            if (edit.insert !== undefined && typeof edit.insert !== "string") {
+                throw new Error("Text edit insert value must be a string when provided");
+            }
+        }
+    }
+    ensureTextPath(automergeDoc, path) {
+        let target = automergeDoc;
+        for (let i = 0; i < path.length - 1; i++) {
+            const segment = path[i];
+            const nextSegment = path[i + 1];
+            if (target[segment] === undefined || target[segment] === null) {
+                target[segment] = typeof nextSegment === "number" ? [] : {};
+            }
+            target = target[segment];
+            if (target === null || typeof target !== "object") {
+                throw new Error(`Cannot apply text patch through non-object path segment '${String(segment)}'`);
+            }
+        }
+        const leaf = path[path.length - 1];
+        const currentValue = target[leaf];
+        if (currentValue === undefined || currentValue === null) {
+            target[leaf] = "";
+            return;
+        }
+        if (typeof currentValue !== "string") {
+            throw new Error(`Cannot apply text patch to non-string value at '${path.map(String).join(".")}'`);
+        }
+    }
+    async persistDocumentChange(options) {
+        const { internalDoc, newDoc, now, headsBeforeChange, useCustomKey, signingKeyPair, signingKeyPassword, successMessage } = options;
+        const docId = internalDoc.id;
         this.logger.debug(`Getting change bytes from document ${docId}`);
-        const changeBytes = automerge_adapter_1.Automerge.getLastLocalChange(newDoc);
+        const changesSincePreviousHeads = headsBeforeChange
+            ? automerge_adapter_1.Automerge.getChangesSince(newDoc, headsBeforeChange)
+            : [];
+        if (changesSincePreviousHeads.length > 1) {
+            throw new Error(`Expected one Automerge change, got ${changesSincePreviousHeads.length}`);
+        }
+        const changeBytes = changesSincePreviousHeads[0] ?? automerge_adapter_1.Automerge.getLastLocalChange(newDoc);
         if (!changeBytes) {
-            //TODO decide if we just exit here or throw an error
             throw new Error("Failed to get change bytes from Automerge document");
         }
         this.logger.debug(`Got change bytes: ${changeBytes.length} bytes`);
-        // Decode the change to get hash and dependencies
         const decodedChange = automerge_adapter_1.Automerge.decodeChange(changeBytes);
         const automergeHash = decodedChange.hash;
-        const automergeDepHashes = decodedChange.deps || []; // Dependencies from the decoded change
-        // Encrypt the change payload first
+        const automergeDepHashes = decodedChange.deps || [];
         const encryptedPayload = await this.tenant.encryptPayload(changeBytes, internalDoc.decryptionKeyId);
-        // Compute content hash from encrypted data
         const contentHash = await (0, idGeneration_1.computeContentHash)(encryptedPayload, this.getSubtle());
-        // Generate entry ID with blockchain-like chaining
         const entryId = await (0, idGeneration_1.generateDocEntryId)(docId, automergeHash, automergeDepHashes, this.getSubtle());
         this.logger.debug(`Generated entry ID for change: ${entryId}`);
-        // Resolve Automerge dependency hashes to entry IDs
         const dependencyIds = await this.ensureAutomergeDepsResolved(docId, automergeDepHashes);
-        // Sign the encrypted payload - use custom key if provided, otherwise current user's key
         let signature;
         let createdByPublicKey;
         if (useCustomKey) {
+            if (!signingKeyPair || !signingKeyPassword) {
+                throw new Error("Custom signing requires both signingKeyPair and signingKeyPassword");
+            }
             signature = await this.tenant.signPayloadWithKey(encryptedPayload, signingKeyPair, signingKeyPassword);
             createdByPublicKey = signingKeyPair.publicKey;
         }
@@ -2267,7 +2574,6 @@ class BaseMindooDB {
             signature = await this.tenant.signPayload(encryptedPayload);
             createdByPublicKey = currentUser.userSigningPublicKey;
         }
-        // Create entry metadata
         const entryMetadata = {
             entryType: "doc_change",
             id: entryId,
@@ -2281,23 +2587,18 @@ class BaseMindooDB {
             originalSize: changeBytes.length,
             encryptedSize: encryptedPayload.length,
         };
-        // Create full entry object
         const fullEntry = {
             ...entryMetadata,
             encryptedData: encryptedPayload,
         };
-        // Store entry
         await this.store.putEntries([fullEntry]);
-        // Register automerge hash -> entry ID mapping
         this.registerAutomergeHashMapping(docId, automergeHash, entryId);
-        // Update cache and index
         internalDoc.doc = newDoc;
         internalDoc.lastModified = now;
         this.storeCachedDocument(internalDoc);
         this.updateIndex(docId, internalDoc.lastModified, internalDoc.isDeleted);
         this.markDocDirty(docId);
-        this.logger.info(`Document ${docId} ${useCustomKey ? 'changed with custom signing key' : 'changed'} successfully`);
-        // Snapshot creation runs as a best-effort background optimization.
+        this.logger.info(`Document ${docId} ${successMessage} successfully`);
         await this.maybeWriteSnapshotForDocument(internalDoc, useCustomKey
             ? { signingKeyPair, signingKeyPassword, createdByPublicKey }
             : { createdByPublicKey });
@@ -2311,7 +2612,7 @@ class BaseMindooDB {
         const docId = internalDoc.id;
         try {
             const allMetadata = await this.scanAllMetadata(this.store, { docId });
-            const replayEntries = allMetadata.filter((em) => em.entryType === "doc_create" || em.entryType === "doc_change" || em.entryType === "doc_delete");
+            const replayEntries = allMetadata.filter((em) => this.isDocumentReplayEntry(em));
             const snapshots = allMetadata
                 .filter((em) => em.entryType === "doc_snapshot")
                 .sort((a, b) => b.createdAt - a.createdAt);
@@ -2674,7 +2975,7 @@ class BaseMindooDB {
             createdAt: firstReplayEntry?.createdAt ?? snapshotMeta?.createdAt ?? fallbackTimestamp,
             lastModified: lastReplayEntry?.createdAt ?? snapshotMeta?.createdAt ?? fallbackTimestamp,
             decryptionKeyId: firstReplayEntry?.decryptionKeyId ?? snapshotMeta?.decryptionKeyId ?? "default",
-            isDeleted: lastReplayEntry?.entryType === "doc_delete",
+            isDeleted: this.computeIsDeletedFromMetadata(replayEntriesForState),
         };
     }
     async *iterateChangeMetadataSince(cursor) {
@@ -2809,7 +3110,7 @@ class BaseMindooDB {
         // Get current document heads to check if it changes
         const headsBefore = automerge_adapter_1.Automerge.getHeads(cachedDoc.doc);
         // Filter entries to only include change entries (exclude snapshots)
-        const entriesToApply = newEntryMetadata.filter(em => em.entryType === "doc_create" || em.entryType === "doc_change" || em.entryType === "doc_delete");
+        const entriesToApply = newEntryMetadata.filter((em) => this.isDocumentReplayEntry(em));
         if (entriesToApply.length === 0) {
             this.logger.debug(`No change entries to apply for document ${docId}`);
             return null; // No changes
@@ -2908,9 +3209,8 @@ class BaseMindooDB {
         const lastEntryCreatedAt = entries.reduce((maxCreatedAt, entry) => Math.max(maxCreatedAt, entry.createdAt), cachedDoc.lastModified);
         const lastModified = payload._lastModified ||
             lastEntryCreatedAt;
-        // Check if document was deleted
-        const hasDeleteEntry = newEntryMetadata.some(em => em.entryType === "doc_delete");
-        const isDeleted = hasDeleteEntry || cachedDoc.isDeleted;
+        const allDocMetadata = await this.scanAllMetadata(this.store, { docId });
+        const isDeleted = this.computeIsDeletedFromMetadata(allDocMetadata);
         const updatedInternalDoc = {
             id: docId,
             doc: updatedDoc,
@@ -3186,9 +3486,7 @@ class BaseMindooDB {
         this.logger.debug(`All entries applied successfully for document ${docId}`);
         this.logger.debug(`Final document heads: ${JSON.stringify(automerge_adapter_1.Automerge.getHeads(doc))}`);
         const payload = doc;
-        // Check if document was deleted by looking for a "doc_delete" type entry
-        const hasDeleteEntry = allEntryMetadata.some(em => em.entryType === "doc_delete");
-        const isDeleted = hasDeleteEntry;
+        const isDeleted = this.computeIsDeletedFromMetadata(allEntryMetadata);
         this.logger.debug(`Document ${docId} isDeleted: ${isDeleted}`);
         // The authoritative decryptionKeyId comes from the doc_create entry's metadata,
         // not from the Automerge payload (which does not store encryption metadata).
@@ -3307,6 +3605,7 @@ class BaseMindooDB {
             getLastModified: () => internalDoc.lastModified,
             getDecryptionKeyId: () => internalDoc.decryptionKeyId,
             isDeleted: () => internalDoc.isDeleted,
+            getHeads: () => automerge_adapter_1.Automerge.getHeads(internalDoc.doc),
             getData: () => {
                 // Convert Automerge document to plain JS object, converting Text objects to strings
                 const jsDoc = this.convertAutomergeToJS(internalDoc.doc);
@@ -3333,13 +3632,13 @@ class BaseMindooDB {
                 return payload._attachments || [];
             },
             getAttachment: async (attachmentId) => {
-                return db.getAttachmentInternal(docId, attachmentId);
+                return db.getAttachmentForRefInternal(db.getAttachmentRefFromDoc(internalDoc, attachmentId));
             },
             getAttachmentRange: async (attachmentId, startByte, endByte) => {
-                return db.getAttachmentRangeInternal(docId, attachmentId, startByte, endByte);
+                return db.getAttachmentRangeForRefInternal(db.getAttachmentRefFromDoc(internalDoc, attachmentId), startByte, endByte);
             },
             streamAttachment: (attachmentId, startOffset = 0) => {
-                return db.streamAttachmentInternal(docId, attachmentId, startOffset);
+                return db.streamAttachmentForRefInternal(db.getAttachmentRefFromDoc(internalDoc, attachmentId), startOffset);
             },
         };
     }
@@ -3351,11 +3650,14 @@ class BaseMindooDB {
         if (!internalDoc) {
             throw new Error(`Document ${docId} not found while reading attachment ${attachmentId}`);
         }
+        return this.getAttachmentRefFromDoc(internalDoc, attachmentId);
+    }
+    getAttachmentRefFromDoc(internalDoc, attachmentId) {
         const payload = internalDoc.doc;
         const attachments = payload._attachments || [];
         const ref = attachments.find(a => a.attachmentId === attachmentId);
         if (!ref) {
-            throw new Error(`Attachment ${attachmentId} not found in document ${docId}`);
+            throw new Error(`Attachment ${attachmentId} not found in document ${internalDoc.id}`);
         }
         return ref;
     }
@@ -3398,10 +3700,13 @@ class BaseMindooDB {
     async getAttachmentInternal(docId, attachmentId) {
         this.logger.debug(`Getting attachment ${attachmentId} from document ${docId}`);
         const ref = await this.getAttachmentRefInternal(docId, attachmentId);
+        return await this.getAttachmentForRefInternal(ref);
+    }
+    async getAttachmentForRefInternal(ref) {
         const store = this.getEffectiveAttachmentStore();
         // Resolve dependency chain to get all chunk IDs in order (oldest first)
         const chunkIds = await store.resolveDependencies(ref.lastChunkId, { includeStart: true });
-        this.logger.debug(`Resolved ${chunkIds.length} chunks for attachment ${attachmentId}`);
+        this.logger.debug(`Resolved ${chunkIds.length} chunks for attachment ${ref.attachmentId}`);
         // Fetch all chunks
         const chunks = await store.getEntries(chunkIds);
         // Verify signatures, decrypt, and collect plaintext chunks
@@ -3419,7 +3724,7 @@ class BaseMindooDB {
             result.set(chunk, offset);
             offset += chunk.length;
         }
-        this.logger.debug(`Retrieved attachment ${attachmentId}: ${result.length} bytes`);
+        this.logger.debug(`Retrieved attachment ${ref.attachmentId}: ${result.length} bytes`);
         return result;
     }
     /**
@@ -3431,6 +3736,12 @@ class BaseMindooDB {
             throw new Error(`Invalid byte range: [${startByte}, ${endByte})`);
         }
         const ref = await this.getAttachmentRefInternal(docId, attachmentId);
+        return await this.getAttachmentRangeForRefInternal(ref, startByte, endByte);
+    }
+    async getAttachmentRangeForRefInternal(ref, startByte, endByte) {
+        if (startByte < 0 || endByte <= startByte) {
+            throw new Error(`Invalid byte range: [${startByte}, ${endByte})`);
+        }
         const store = this.getEffectiveAttachmentStore();
         const readPlan = await this.planAttachmentRead(store, ref, startByte, endByte);
         const neededChunkIds = readPlan.chunkPlans.map((chunkPlan) => chunkPlan.id);
@@ -3454,7 +3765,7 @@ class BaseMindooDB {
             resultOffset += bytesToCopy;
             bytesRemaining -= bytesToCopy;
         }
-        this.logger.debug(`Retrieved attachment ${attachmentId} range: ${result.length} bytes`);
+        this.logger.debug(`Retrieved attachment ${ref.attachmentId} range: ${result.length} bytes`);
         return result;
     }
     /**
@@ -3463,6 +3774,9 @@ class BaseMindooDB {
     async *streamAttachmentInternal(docId, attachmentId, startOffset) {
         this.logger.debug(`Streaming attachment ${attachmentId} from offset ${startOffset}`);
         const ref = await this.getAttachmentRefInternal(docId, attachmentId);
+        yield* this.streamAttachmentForRefInternal(ref, startOffset);
+    }
+    async *streamAttachmentForRefInternal(ref, startOffset) {
         if (startOffset < 0 || startOffset > ref.size) {
             throw new Error(`Invalid stream offset ${startOffset} for attachment size ${ref.size}`);
         }
@@ -3492,7 +3806,7 @@ class BaseMindooDB {
                 }
             }
         }
-        this.logger.debug(`Finished streaming attachment ${attachmentId}`);
+        this.logger.debug(`Finished streaming attachment ${ref.attachmentId}`);
     }
     /**
      * Get the attachment store for this database.
@@ -3693,12 +4007,12 @@ class BaseMindooDB {
      * Resolve a sync target to a ContentAddressedStore.
      * Accepts either a raw store or a MindooDB instance (calls getStore()).
      */
-    getStoreForKind(storeKind = types_1.StoreKind.docs) {
-        return storeKind === types_1.StoreKind.attachments ? this.attachmentStore : this.store;
+    getStoreForKind(storeKind = types_2.StoreKind.docs) {
+        return storeKind === types_2.StoreKind.attachments ? this.attachmentStore : this.store;
     }
-    resolveStore(remote, storeKind = types_1.StoreKind.docs) {
+    resolveStore(remote, storeKind = types_2.StoreKind.docs) {
         if ('getStore' in remote && typeof remote.getStore === 'function') {
-            return storeKind === types_1.StoreKind.attachments
+            return storeKind === types_2.StoreKind.attachments
                 ? remote.getAttachmentStore()
                 : remote.getStore();
         }
@@ -3768,7 +4082,7 @@ class BaseMindooDB {
      * @return A promise that resolves with the sync result
      */
     async pullChangesFrom(remote, options) {
-        const storeKind = options?.storeKind ?? types_1.StoreKind.docs;
+        const storeKind = options?.storeKind ?? types_2.StoreKind.docs;
         const localStore = this.getStoreForKind(storeKind);
         const remoteStore = this.resolveStore(remote, storeKind);
         if (localStore.getId() !== remoteStore.getId() || localStore.getStoreKind() !== remoteStore.getStoreKind()) {
@@ -3807,7 +4121,7 @@ class BaseMindooDB {
                     cancelled: true,
                 };
             }
-            if (storeKind === types_1.StoreKind.docs) {
+            if (storeKind === types_2.StoreKind.docs) {
                 await this.syncStoreChanges();
             }
             if (options?.signal?.aborted) {
@@ -3851,7 +4165,7 @@ class BaseMindooDB {
      * @return A promise that resolves with the sync result
      */
     async pushChangesTo(remote, options) {
-        const storeKind = options?.storeKind ?? types_1.StoreKind.docs;
+        const storeKind = options?.storeKind ?? types_2.StoreKind.docs;
         const localStore = this.getStoreForKind(storeKind);
         const remoteStore = this.resolveStore(remote, storeKind);
         if (localStore.getId() !== remoteStore.getId() || localStore.getStoreKind() !== remoteStore.getStoreKind()) {