@vrtmrz/livesync-commonlib 0.1.25 → 0.1.27

package/dist/serviceModules/ServiceFileHandlerBase.js

@@ -1,10 +1,8 @@
 import { LOG_LEVEL_INFO, LOG_LEVEL_NOTICE, LOG_LEVEL_VERBOSE } from "octagonal-wheels/common/logger";
 import { serialized } from "octagonal-wheels/concurrency/lock";
 import {
-  createBlob,
   getDocDataAsArray,
   isDocContentSame,
-  isTextBlob,
   readAsBlob,
   readContent
 } from "../common/utils.js";
@@ -15,16 +13,6 @@ import { ServiceModuleBase } from "./ServiceModuleBase.js";
 import { getStoragePathFromUXFileInfo } from "../common/typeUtils.js";
 import { EVEN } from "../common/models/shared.const.symbols.js";
 import { tryGetFilePath } from "../common/utils.doc.js";
-async function isIncomingTextClearExtension(incomingContent, localContent) {
-  const incomingBlob = createBlob(incomingContent);
-  const localBlob = createBlob(localContent);
-  if (!isTextBlob(incomingBlob) || !isTextBlob(localBlob)) {
-    return false;
-  }
-  const incomingText = await incomingBlob.text();
-  const localText = await localBlob.text();
-  return incomingText.startsWith(localText) || incomingText.endsWith(localText);
-}
 async function serializedByKeys(keys, callback) {
   const [key, ...remainingKeys] = keys;
   if (key === void 0) return await callback();
@@ -46,6 +34,7 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
   setting;
   vault;
   fileReflectionProvenance;
+  deferredConflictChecks = /* @__PURE__ */ new Map();
   constructor(services) {
     super(services);
     this.events = services.events;
@@ -125,6 +114,91 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
     }
     return void 0;
   }
+  /**
+   * Classify a storage read against its displayed database branch.
+   *
+   * A recorded revision identifies the branch and therefore takes precedence
+   * over byte matches. Without a readable base, only current live leaves are
+   * considered. Any match avoids a duplicate write, but only a unique match
+   * identifies provenance; no match is `unknown`.
+   * `preferredPath` selects the provenance key during a rename, and
+   * `currentLoaded` supplies an already decoded candidate body when available.
+   * Missing chunks do not clear provenance unless their metadata is also
+   * missing or deleted.
+   */
+  async classifyStorageContent(file, currentEntry, preferredPath, recordedRevision, currentLoaded) {
+    const path = preferredPath ?? file.path;
+    if (recordedRevision) {
+      const loadedContentIsDecoded = currentLoaded?._rev === recordedRevision;
+      const base = loadedContentIsDecoded ? currentLoaded : await this.db.fetchEntry(file, recordedRevision, true, true, true);
+      if (base && base._rev === recordedRevision && !("deleted" in base && base.deleted) && !("_deleted" in base && base._deleted)) {
+        const baseContent = loadedContentIsDecoded ? base.data : readContent(base);
+        return await isDocContentSame(baseContent, file.body) ? { kind: "unchanged", revision: recordedRevision } : { kind: "edited", revision: recordedRevision };
+      }
+      if (!base) {
+        const meta = await this.db.fetchEntryMeta(file, recordedRevision, true);
+        if (!meta || meta.deleted || meta._deleted) await this.deleteProvenance(path);
+      }
+    }
+    const matches = currentEntry ? await this.db.findLiveContentRevisions(file, file.body) : [];
+    if (matches.length) {
+      return { kind: "matching-leaf", revision: matches.length === 1 ? matches[0] : void 0 };
+    }
+    return { kind: "unknown" };
+  }
+  /** Record provenance only when storage matches one unambiguous live leaf. */
+  async rememberMatchingLeaf(path, revision, mtime) {
+    if (revision) await this.setProvenance(path, revision, mtime);
+  }
+  /**
+   * Read the raw provenance value used by an optimistic storage snapshot.
+   * Unlike `getProvenance`, this does not validate or remove the referenced
+   * database revision; an unreadable value is represented as `undefined`.
+   */
+  async readProvenanceSnapshot(path) {
+    try {
+      return (await this.fileReflectionProvenance?.get(path))?.revision;
+    } catch {
+      return void 0;
+    }
+  }
+  /**
+   * Check that storage still has the same path, bytes, timestamp, and
+   * provenance as a previously captured snapshot.
+   */
+  async currentStorageSnapshotMatches(file, revision) {
+    const current = await this.storage.getStub(file.path);
+    if (!current || isFolderInfo(current) || current.path !== file.path) return false;
+    const readCurrent = await this.readFileFromStub(current);
+    return readCurrent.stat.mtime === file.stat.mtime && await isDocContentSame(readCurrent.body, file.body) && await this.readProvenanceSnapshot(file.path) === revision;
+  }
+  /**
+   * Publish provenance after a durable database write if storage is unchanged.
+   * A failed revalidation leaves the database revision stored and asks the
+   * caller to reread storage before proceeding.
+   */
+  async finaliseStoredRevision(file, observedProvenance, storedRevision) {
+    if (await this.currentStorageSnapshotMatches(file, observedProvenance)) {
+      await this.setProvenance(file.path, storedRevision, file.stat.mtime);
+      return true;
+    } else {
+      return false;
+    }
+  }
+  /**
+   * Reread storage after a restored startup snapshot changed and retry a save.
+   * The bounded counter prevents an unstable file from causing an endless
+   * startup loop; the next event or scan can reconcile a final refusal.
+   */
+  async retryCurrentStorage(path, preferredBasePath, snapshotRetry) {
+    if (snapshotRetry >= 2) {
+      this._log(`Storage kept changing while saving ${path}; a fresh event is required`, LOG_LEVEL_NOTICE);
+      return false;
+    }
+    const fresh = await this.storage.getStub(path);
+    if (!fresh || isFolderInfo(fresh)) return false;
+    return await this.storeFileToDBFromRevision(fresh, false, false, preferredBasePath, true, snapshotRetry + 1);
+  }
   getPath(entry) {
     return this.path.getPath(entry);
   }
@@ -147,9 +221,23 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
     return file;
   }
   async storeFileToDB(info, force = false, onlyChunks = false) {
-    return await this.storeFileToDBFromRevision(info, force, onlyChunks);
+    return await this.serializedByFileEventPaths(
+      [getStoragePathFromUXFileInfo(info)],
+      () => this.storeFileToDBFromRevision(info, force, onlyChunks)
+    );
   }
   async storeFileToDBWithBaseRevision(info, baseRevision, createIfDifferent = true) {
+    return await this.serializedByFileEventPaths(
+      [getStoragePathFromUXFileInfo(info)],
+      () => this.storeFileToDBWithBaseRevisionCore(info, baseRevision, createIfDifferent)
+    );
+  }
+  /**
+   * Store current storage content below an exact live revision. A differing
+   * body is rejected when `createIfDifferent` is false; callers hold the
+   * document lock for this core operation.
+   */
+  async storeFileToDBWithBaseRevisionCore(info, baseRevision, createIfDifferent) {
     const file = await this.infoToStub(info);
     if (file == null) {
       this._log(`File ${tryGetFilePath(info)} is not exist on the storage`, LOG_LEVEL_VERBOSE);
@@ -183,7 +271,7 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       const loadedBase = await this.db.fetchEntry(file, baseRevision, true, true);
       if (loadedBase && await isDocContentSame(getDocDataAsArray(loadedBase.data), readFile.body)) {
         await this.setProvenance(file.path, baseRevision, readFile.stat.mtime);
-        await this.conflict.queueCheckFor(file.path);
+        await this.queueConflictCheckFor(file.path);
         return true;
       }
     }
@@ -199,10 +287,16 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       return false;
     }
     await this.setProvenance(file.path, storedRevision, readFile.stat.mtime);
-    await this.conflict.queueCheckFor(file.path);
+    await this.queueConflictCheckFor(file.path);
     return true;
   }
-  async storeFileToDBFromRevision(info, force = false, onlyChunks = false, preferredBasePath) {
+  /**
+   * Save one storage snapshot while the caller holds its document lock.
+   * Ordinary saves read once inside the lock and leave retries disabled.
+   * Restored startup events retain bounded rereads because file watching has
+   * not yet started and cannot supply a new event for a concurrent edit.
+   */
+  async storeFileToDBFromRevision(info, force = false, onlyChunks = false, preferredBasePath, retryIfStorageChanges = false, snapshotRetry = 0) {
     const file = await this.infoToStub(info);
     if (file == null) {
       this._log(`File ${tryGetFilePath(info)} is not exist on the storage`, LOG_LEVEL_VERBOSE);
@@ -219,10 +313,51 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       const readFile2 = await this.readFileFromStub(file);
       return await this.db.createChunks(readFile2, force, true);
     }
+    const observedProvenance = await this.readProvenanceSnapshot(
+      preferredBasePath ?? file.path
+    );
     const readFile = await this.readFileFromStub(file);
-    const entry = await this.db.fetchEntry(file, void 0, true, true);
+    const entry = await this.db.fetchEntry(file, void 0, true, true, true);
+    const currentEntry = entry || await this.db.fetchEntryMeta(file, void 0, true);
     const conflictedRevs = await this.db.getConflictedRevs(file);
     const isConflicted = conflictedRevs.length > 0;
+    if (!force && currentEntry && !currentEntry.deleted && !currentEntry._deleted) {
+      const classification = await this.classifyStorageContent(
+        readFile,
+        currentEntry,
+        preferredBasePath,
+        observedProvenance,
+        entry ? { _rev: entry._rev, data: readContent(entry) } : void 0
+      );
+      if (retryIfStorageChanges && !await this.currentStorageSnapshotMatches(readFile, observedProvenance)) {
+        return await this.retryCurrentStorage(file.path, preferredBasePath, snapshotRetry);
+      }
+      if (classification.kind === "unchanged") {
+        if (isConflicted) {
+          await this.queueConflictCheckFor(file.path);
+        } else if (classification.revision !== currentEntry._rev) {
+          if (!entry) return false;
+          return await this.dbToStorageCore(file.path, file);
+        } else {
+          this.path.markChangesAreSame(readFile, readFile.stat.mtime, currentEntry.mtime);
+        }
+        return true;
+      }
+      if (classification.kind === "matching-leaf") {
+        await this.rememberMatchingLeaf(file.path, classification.revision, readFile.stat.mtime);
+        if (isConflicted) await this.queueConflictCheckFor(file.path);
+        return true;
+      }
+      const storedRevision2 = classification.kind === "edited" ? await this.db.storeWithBaseRevision(readFile, classification.revision, true) : await this.db.storeIndependentRevision(readFile, true);
+      if (storedRevision2 === false) return false;
+      if (preferredBasePath && preferredBasePath !== file.path) await this.deleteProvenance(preferredBasePath);
+      if (retryIfStorageChanges && !await this.finaliseStoredRevision(readFile, observedProvenance, storedRevision2)) {
+        return await this.retryCurrentStorage(file.path, preferredBasePath, snapshotRetry);
+      }
+      if (!retryIfStorageChanges) await this.setProvenance(file.path, storedRevision2, readFile.stat.mtime);
+      if (isConflicted || classification.kind === "unknown") await this.queueConflictCheckFor(file.path);
+      return true;
+    }
     if (isConflicted) {
       const baseRevision = await this.getProvenBaseRevision(readFile, preferredBasePath);
       if (baseRevision) {
@@ -238,33 +373,33 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
           await this.deleteProvenance(preferredBasePath);
         }
         await this.setProvenance(file.path, storedRevision3, readFile.stat.mtime);
-        await this.conflict.queueCheckFor(file.path);
+        await this.queueConflictCheckFor(file.path);
         return true;
       }
-      const currentEntry = entry || await this.db.fetchEntryMeta(file, void 0, true);
-      const currentRevision = currentEntry && currentEntry._rev;
+      const currentEntry2 = entry || await this.db.fetchEntryMeta(file, void 0, true);
+      const currentRevision = currentEntry2 && currentEntry2._rev;
       if (!currentRevision) {
         this._log(
           `Could not preserve the unknown conflict branch for ${file.path}; no current revision is available`,
           LOG_LEVEL_NOTICE
         );
-        await this.conflict.queueCheckFor(file.path);
+        await this.queueConflictCheckFor(file.path);
         return false;
       }
       const storedRevision2 = await this.db.storeAsConflictedRevisionWithResult(readFile, currentRevision, true);
       if (storedRevision2 === false) {
         this._log(`Could not preserve the unknown conflict branch for ${file.path}`, LOG_LEVEL_NOTICE);
-        await this.conflict.queueCheckFor(file.path);
+        await this.queueConflictCheckFor(file.path);
         return false;
       }
       if (preferredBasePath && preferredBasePath !== file.path) {
         await this.deleteProvenance(preferredBasePath);
       }
       await this.setProvenance(file.path, storedRevision2, readFile.stat.mtime);
-      await this.conflict.queueCheckFor(file.path);
+      await this.queueConflictCheckFor(file.path);
       return true;
     }
-    if (!entry || entry.deleted || entry._deleted) {
+    if (!currentEntry || currentEntry.deleted || currentEntry._deleted) {
       const storedRevision2 = await this.db.storeWithBaseRevision(readFile, entry && entry._rev, true);
       if (storedRevision2 === false) return false;
       if (preferredBasePath && preferredBasePath !== file.path) {
@@ -274,7 +409,7 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       return true;
     }
     let shouldApplied = false;
-    if (!force && !onlyChunks) {
+    if (!force && !onlyChunks && entry) {
       if (this.path.compareFileFreshness(file, entry) !== EVEN) {
         shouldApplied = true;
       }
@@ -291,7 +426,7 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
         return true;
       }
     }
-    const storedRevision = await this.db.storeWithBaseRevision(readFile, entry._rev, true);
+    const storedRevision = await this.db.storeWithBaseRevision(readFile, currentEntry._rev, true);
     if (storedRevision === false) return false;
     if (preferredBasePath && preferredBasePath !== file.path) {
       await this.deleteProvenance(preferredBasePath);
@@ -300,6 +435,16 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
     return true;
   }
   async deleteFileFromDB(info) {
+    return await this.serializedByFileEventPaths(
+      [getStoragePathFromUXFileInfo(info)],
+      () => this.deleteFileFromDBCore(info)
+    );
+  }
+  /**
+   * Record a storage deletion under the caller's document lock, preserving
+   * the displayed conflict branch when its provenance is known.
+   */
+  async deleteFileFromDBCore(info) {
     const file = await this.infoToStub(info);
     const path = typeof info === "string" ? info : tryGetFilePath(info);
     if (file == null) {
@@ -323,13 +468,13 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
             `The deleted storage file ${path} has conflicts, but its displayed revision is unknown; preserving every database branch`,
             LOG_LEVEL_NOTICE
           );
-          await this.conflict.queueCheckFor(path);
+          await this.queueConflictCheckFor(path);
           return true;
         }
         const storedRevision = await this.db.storeDeletionWithBaseRevision(path, provenance.revision);
         if (storedRevision === false) return false;
         await this.deleteProvenance(path);
-        await this.conflict.queueCheckFor(path);
+        await this.queueConflictCheckFor(path);
         return true;
       }
       this._log(`File ${path} is missing on storage; deleting from the database by path`, LOG_LEVEL_INFO);
@@ -364,13 +509,13 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
           `The deleted storage file ${file.path} has conflicts, but its displayed revision is unknown; preserving every database branch`,
           LOG_LEVEL_NOTICE
         );
-        await this.conflict.queueCheckFor(file.path);
+        await this.queueConflictCheckFor(file.path);
         return true;
       }
       const storedRevision = await this.db.storeDeletionWithBaseRevision(file.path, baseRevision);
       if (storedRevision === false) return false;
       await this.deleteProvenance(file.path);
-      await this.conflict.queueCheckFor(file.path);
+      await this.queueConflictCheckFor(file.path);
       return true;
     }
     const deleted = await this.db.delete(file);
@@ -378,6 +523,18 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
     return deleted;
   }
   async renameFileInDB(info, oldPath) {
+    const newPath = getStoragePathFromUXFileInfo(info);
+    return await this.serializedByFileEventPaths(
+      [oldPath, newPath],
+      () => this.renameFileInDBCore(info, oldPath)
+    );
+  }
+  /**
+   * Record a rename under the caller's source and target locks. Case-only
+   * renames retain the source provenance while other renames handle the
+   * source conflict before deleting its old path.
+   */
+  async renameFileInDBCore(info, oldPath, retryIfStorageChanges = false) {
     const newPath = getStoragePathFromUXFileInfo(info);
     const [oldDocumentId, newDocumentId] = await Promise.all([
       this.path.path2id(oldPath),
@@ -385,7 +542,13 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
     ]);
     if (oldDocumentId === newDocumentId) {
       this._log(`Updating the stored path for case-only rename: ${oldPath} -> ${newPath}`, LOG_LEVEL_VERBOSE);
-      return await this.storeFileToDBFromRevision(info, true, false, oldPath);
+      return await this.storeFileToDBFromRevision(
+        info,
+        true,
+        false,
+        oldPath,
+        retryIfStorageChanges
+      );
     }
     const oldEntry = await this.db.fetchEntryMeta(oldPath, void 0, true);
     const newEntry = await this.db.fetchEntryMeta(newPath, void 0, true);
@@ -396,7 +559,7 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       );
       return false;
     }
-    if (!await this.storeFileToDB(info, true)) {
+    if (!await this.storeFileToDBFromRevision(info, true, false, void 0, retryIfStorageChanges)) {
       this._log(`Failed to store rename target; preserving source in the database: ${oldPath}`, LOG_LEVEL_NOTICE);
       return false;
     }
@@ -417,7 +580,7 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
           `Renamed ${oldPath} to ${newPath}, but preserved every conflicted source branch because the displayed source revision is unknown`,
           LOG_LEVEL_NOTICE
         );
-        await this.conflict.queueCheckFor(oldPath);
+        await this.queueConflictCheckFor(oldPath);
         return true;
       }
       const storedRevision = await this.db.storeDeletionWithBaseRevision(
@@ -426,7 +589,7 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       );
       if (storedRevision === false) return false;
       await this.deleteProvenance(oldPath);
-      await this.conflict.queueCheckFor(oldPath);
+      await this.queueConflictCheckFor(oldPath);
       return true;
     }
     const deleted = await this.db.delete(oldPath);
@@ -434,6 +597,13 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
     return deleted;
   }
   async deleteRevisionFromDB(info, rev) {
+    return await this.serializedByFileEventPaths(
+      [getStoragePathFromUXFileInfo(info)],
+      () => this.deleteRevisionFromDBCore(info, rev)
+    );
+  }
+  /** Delete one selected revision and clear matching provenance under the caller's document lock. */
+  async deleteRevisionFromDBCore(info, rev) {
     const path = getStoragePathFromUXFileInfo(info);
     const provenance = await this.getProvenance(path);
     const deleted = await this.db.delete(info, rev);
@@ -443,6 +613,16 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
     return deleted;
   }
   async resolveConflictedByDeletingRevision(info, rev) {
+    return await this.serializedByFileEventPaths(
+      [getStoragePathFromUXFileInfo(info)],
+      () => this.resolveConflictedByDeletingRevisionCore(info, rev)
+    );
+  }
+  /**
+   * Apply the legacy resolve-by-delete sequence while holding one document
+   * lock; metadata is captured before the selected revision is removed.
+   */
+  async resolveConflictedByDeletingRevisionCore(info, rev) {
     const path = getStoragePathFromUXFileInfo(info);
     const file = await this.infoToStub(info);
     const docEntry = await this.db.fetchEntryMeta(file ?? info, rev, true);
@@ -450,7 +630,7 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       this._log(`Failed to read the conflicted revision ${rev} of ${path}`, LOG_LEVEL_VERBOSE);
       return false;
     }
-    if (!await this.deleteRevisionFromDB(info, rev)) {
+    if (!await this.deleteRevisionFromDBCore(info, rev)) {
       this._log(`Failed to delete the conflicted revision ${rev} of ${path}`, LOG_LEVEL_VERBOSE);
       return false;
     }
@@ -465,6 +645,16 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       this._log(`Cannot select database revision ${rev} without a file path`, LOG_LEVEL_VERBOSE);
       return false;
     }
+    return await this.serializedByFileEventPaths(
+      [getStoragePathFromUXFileInfo(info)],
+      () => this.dbToStorageWithSpecificRevCore(info, rev, force)
+    );
+  }
+  /**
+   * Reflect a selected live revision under the caller's document lock.
+   * The public wrapper performs the same lock acquisition before entering here.
+   */
+  async dbToStorageWithSpecificRevCore(info, rev, force) {
     const file = await this.infoToStub(info);
     const databaseTarget = file ?? info;
     const [docEntry, currentEntry, conflictedRevisions] = await Promise.all([
@@ -490,6 +680,14 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
     return await this.applyDatabaseEntryToStorage(docEntry, file, force, true);
   }
   async dbToStorage(entryInfo, info, force) {
+    const pathFromEntryInfo = typeof entryInfo === "string" ? entryInfo : this.getPath(entryInfo);
+    return await this.serializedByFileEventPaths(
+      [pathFromEntryInfo],
+      () => this.dbToStorageCore(entryInfo, info, force)
+    );
+  }
+  /** Fetch the current metadata and reflect it while the caller holds its lock. */
+  async dbToStorageCore(entryInfo, info, force) {
     const file = await this.infoToStub(info);
     const pathFromEntryInfo = typeof entryInfo === "string" ? entryInfo : this.getPath(entryInfo);
     const docEntry = await this.db.fetchEntryMeta(pathFromEntryInfo, void 0, true);
@@ -499,7 +697,13 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
     }
     return await this.applyDatabaseEntryToStorage(docEntry, file, force);
   }
-  async applyDatabaseEntryToStorage(docEntry, file, force, allowExistingConflicts = false) {
+  /**
+   * Reflect one database revision while protecting concurrent storage edits.
+   * Overwrite and deletion paths preserve changed bytes first, then revalidate
+   * their snapshot and the current database revision immediately before the
+   * destructive operation.
+   */
+  async applyDatabaseEntryToStorage(docEntry, file, force, allowExistingConflicts = false, incomingRetry = 0) {
     const mode = file == null ? "create" : "modify";
     const path = this.getPath(docEntry);
     const settings = this.setting.currentSettings();
@@ -507,7 +711,7 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
     if (revs.length > 0 && !allowExistingConflicts) {
       if (settings.writeDocumentsIfConflicted) {
       } else {
-        await this.conflict.queueCheckForIfOpen(path);
+        await this.queueConflictCheckFor(path, true);
         return true;
       }
     }
@@ -523,8 +727,45 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       return true;
     }
     if (!existOnDB && existDoc) {
-      if (!force && !settings.writeDocumentsIfConflicted && await this.preserveUnsyncedStorageAsConflict(path, existDoc, docEntry)) {
-        return true;
+      let safeDeletionSnapshot;
+      if (!force && !settings.writeDocumentsIfConflicted) {
+        let protection = await this.preserveUnsyncedStorageAsConflict(path, existDoc, docEntry);
+        if (protection.preserved) return true;
+        if (!protection.snapshot || !await this.currentStorageSnapshotMatches(protection.snapshot.file, protection.snapshot.revision)) {
+          protection = await this.recheckIncomingStorage(path, docEntry, void 0, allowExistingConflicts);
+          if (protection.preserved) return true;
+          if (!protection.snapshot || !await this.currentStorageSnapshotMatches(protection.snapshot.file, protection.snapshot.revision)) {
+            return false;
+          }
+        }
+        safeDeletionSnapshot = protection.snapshot;
+      }
+      let latest2 = await this.reconcileAdvancedIncomingRevision(
+        docEntry,
+        path,
+        force,
+        allowExistingConflicts,
+        incomingRetry
+      );
+      if (latest2 !== void 0) return latest2;
+      if (safeDeletionSnapshot && !await this.currentStorageSnapshotMatches(safeDeletionSnapshot.file, safeDeletionSnapshot.revision)) {
+        const protection = await this.recheckIncomingStorage(path, docEntry, void 0, allowExistingConflicts);
+        if (protection.preserved) return true;
+        if (!protection.snapshot || !await this.currentStorageSnapshotMatches(protection.snapshot.file, protection.snapshot.revision)) {
+          return false;
+        }
+        safeDeletionSnapshot = protection.snapshot;
+        latest2 = await this.reconcileAdvancedIncomingRevision(
+          docEntry,
+          path,
+          force,
+          allowExistingConflicts,
+          incomingRetry
+        );
+        if (latest2 !== void 0) return latest2;
+        if (!await this.currentStorageSnapshotMatches(safeDeletionSnapshot.file, safeDeletionSnapshot.revision)) {
+          return false;
+        }
       }
       await this.storage.deleteVaultItem(path);
       await this.deleteProvenance(path);
@@ -580,6 +821,7 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
         return true;
       }
     }
+    let safeSnapshot;
     if (existDoc && !force) {
       let shouldApplied = false;
       const freshness = this.path.compareFileFreshness(existDoc, docEntry);
@@ -600,8 +842,15 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
         this._log(`File ${docRead.path} is not changed`, LOG_LEVEL_VERBOSE);
         return true;
       }
-      if (!force && !settings.writeDocumentsIfConflicted && await this.preserveUnsyncedStorageAsConflict(path, existDoc, docEntry, docData)) {
-        return true;
+      if (!force && !settings.writeDocumentsIfConflicted) {
+        let protection = await this.preserveUnsyncedStorageAsConflict(path, existDoc, docEntry, docData);
+        if (protection.preserved) return true;
+        if (!protection.snapshot) {
+          protection = await this.recheckIncomingStorage(path, docEntry, docData, allowExistingConflicts);
+          if (protection.preserved) return true;
+          if (!protection.snapshot) return false;
+        }
+        safeSnapshot = protection.snapshot;
       }
     } else {
       this._log(
@@ -610,38 +859,121 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       );
     }
     await this.storage.ensureDir(path);
+    if (safeSnapshot && !await this.currentStorageSnapshotMatches(safeSnapshot.file, safeSnapshot.revision)) {
+      const protection = await this.recheckIncomingStorage(path, docEntry, docData, allowExistingConflicts);
+      if (protection.preserved) return true;
+      if (!protection.snapshot || !await this.currentStorageSnapshotMatches(protection.snapshot.file, protection.snapshot.revision)) {
+        return false;
+      }
+      safeSnapshot = protection.snapshot;
+    }
+    const latest = await this.reconcileAdvancedIncomingRevision(
+      docEntry,
+      path,
+      force,
+      allowExistingConflicts,
+      incomingRetry
+    );
+    if (latest !== void 0) return latest;
+    if (safeSnapshot && !await this.currentStorageSnapshotMatches(safeSnapshot.file, safeSnapshot.revision)) {
+      return false;
+    }
     const ret = await this.storage.writeFileAuto(path, docData, { ctime: docRead.ctime, mtime: docRead.mtime });
     await this.storage.touched(path);
     this.storage.triggerFileEvent(mode, path);
     if (ret && this.fileReflectionProvenance) {
       const storedStat = await this.storage.stat(path);
+      if (safeSnapshot && await this.readProvenanceSnapshot(path) !== safeSnapshot.revision) {
+        return ret;
+      }
       await this.setProvenance(path, docEntry._rev, storedStat?.mtime);
     }
     return ret;
   }
+  /**
+   * Preserve storage bytes before an incoming reflection can replace them.
+   *
+   * The initial read and provenance form one candidate snapshot. Classification
+   * gives a recorded branch priority, deduplicates matching live leaves, or
+   * creates an independent root for unknown origin. Optional `incomingContent` avoids
+   * re-reading an already loaded incoming body. Storage is revalidated before
+   * and after the database write; `preserved: true` stops the incoming write,
+   * while a returned `snapshot` lets the caller continue only after revalidation.
+   */
   async preserveUnsyncedStorageAsConflict(path, existDoc, incomingEntry, incomingContent) {
+    const observedProvenance = await this.readProvenanceSnapshot(path);
     const readFile = await this.readFileFromStub(existDoc);
+    const snapshot = { file: readFile, revision: observedProvenance };
     if (incomingContent && await isDocContentSame(incomingContent, readFile.body)) {
-      return false;
-    }
-    if (incomingContent && await isIncomingTextClearExtension(incomingContent, readFile.body)) {
-      return false;
+      return await this.currentStorageSnapshotMatches(readFile, observedProvenance) ? { preserved: false, snapshot } : { preserved: false };
     }
     if (!incomingEntry._rev) {
-      return false;
+      return { preserved: false };
+    }
+    const classification = await this.classifyStorageContent(
+      readFile,
+      incomingEntry,
+      void 0,
+      observedProvenance,
+      incomingContent ? { _rev: incomingEntry._rev, data: incomingContent } : void 0
+    );
+    if (!await this.currentStorageSnapshotMatches(readFile, observedProvenance)) {
+      return { preserved: false };
     }
-    if (await this.db.hasContentInRevisionHistory(path, readFile.body, incomingEntry._rev)) {
-      return false;
+    if (classification.kind === "unchanged") {
+      return { preserved: false, snapshot };
     }
-    const storedRevision = await this.db.storeAsConflictedRevisionWithResult(readFile, incomingEntry._rev, true);
+    if (classification.kind === "matching-leaf") {
+      await this.rememberMatchingLeaf(path, classification.revision, readFile.stat.mtime);
+      await this.queueConflictCheckFor(path);
+      return { preserved: true };
+    }
+    const storedRevision = classification.kind === "edited" ? await this.db.storeWithBaseRevision(readFile, classification.revision, true) : await this.db.storeIndependentRevision(readFile, true);
     if (storedRevision === false) {
       this._log(`Prevented overwriting unsynchronised local changes for ${path}`, LOG_LEVEL_NOTICE);
-      return true;
+      return { preserved: true };
+    }
+    if (!await this.finaliseStoredRevision(readFile, observedProvenance, storedRevision)) {
+      return { preserved: false };
     }
-    await this.setProvenance(path, storedRevision, readFile.stat.mtime);
     this._log(`Preserved unsynchronised local changes as a conflict for ${path}`, LOG_LEVEL_NOTICE);
-    await this.conflict.queueCheckFor(path);
-    return true;
+    await this.queueConflictCheckFor(path);
+    return { preserved: true };
+  }
+  /**
+   * Repeat overwrite protection from a fresh storage read after a snapshot
+   * becomes stale. Existing conflicts may defer reflection and request an
+   * open-only check while leaving the current storage untouched.
+   */
+  async recheckIncomingStorage(path, incomingEntry, incomingContent, allowExistingConflicts) {
+    const current = await this.storage.getStub(path);
+    if (!current || isFolderInfo(current)) return { preserved: false };
+    const protection = await this.preserveUnsyncedStorageAsConflict(path, current, incomingEntry, incomingContent);
+    if (protection.preserved || !protection.snapshot) return protection;
+    if (!allowExistingConflicts && !this.setting.currentSettings().writeDocumentsIfConflicted && (await this.db.getConflictedRevs(path)).length > 0) {
+      await this.queueConflictCheckFor(path, true);
+      return { preserved: true };
+    }
+    return protection;
+  }
+  /**
+   * Re-read database metadata immediately before reflecting an incoming entry.
+   * If the current revision advanced, recurse with fresh storage; force and
+   * explicitly allowed conflict writes retain the caller's selected entry.
+   * `incomingRetry` bounds repeated database churn.
+   */
+  async reconcileAdvancedIncomingRevision(incomingEntry, path, force, allowExistingConflicts, incomingRetry) {
+    if (force || allowExistingConflicts) return void 0;
+    const current = await this.db.fetchEntryMeta(path, void 0, true);
+    if (!current) return false;
+    if (current._rev === incomingEntry._rev) return void 0;
+    if (incomingRetry >= 2) {
+      this._log(`Database kept changing while reflecting ${path}`, LOG_LEVEL_NOTICE);
+      return false;
+    }
+    const storage = await this.storage.getStub(path);
+    if (isFolderInfo(storage)) return false;
+    return await this.applyDatabaseEntryToStorage(current, storage, force, allowExistingConflicts, incomingRetry + 1);
   }
   async _anyHandlerProcessesFileEvent(item) {
     if (item.restoredFromPreviousRuntime) {
@@ -650,9 +982,6 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
     const eventItem = item.args;
     const type = item.type;
     const path = eventItem.file.path;
-    if (!await this.isCurrentPathSelected(path)) {
-      return false;
-    }
     if (type === "RENAME" && !eventItem.oldPath) {
       this._log(`Rename event for ${path} has no source path`, LOG_LEVEL_VERBOSE);
       return false;
@@ -660,15 +989,16 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
     const relatedPath = type === "RENAME" ? eventItem.oldPath : type === "DELETE" ? eventItem.renameTarget : void 0;
     const eventPaths = relatedPath === void 0 ? [path] : [path, relatedPath];
     return await this.serializedByFileEventPaths(eventPaths, async () => {
+      if (!await this.isCurrentPathSelected(path)) return false;
       switch (type) {
         case "CREATE":
         case "CHANGED":
-          return await this.storeFileToDB(item.args.file);
+          return await this.storeFileToDBFromRevision(item.args.file);
         case "DELETE":
           if (!await this.canRecordStorageDeletion(item)) return true;
-          return await this.deleteFileFromDB(item.args.file);
+          return await this.deleteFileFromDBCore(item.args.file);
         case "RENAME":
-          return await this.renameFileInDB(
+          return await this.renameFileInDBCore(
             item.args.file,
             item.args.oldPath
           );
@@ -719,13 +1049,61 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       return false;
     }
   }
+  /**
+   * Serialise work by every document ID represented by the supplied paths.
+   * IDs are deduplicated and sorted so aliases take one lock and cross-document renames have one order.
+   * The callback runs under those locks and must use core methods; conflict
+   * hooks requested inside it are deferred until all locks have been released.
+   */
   async serializedByFileEventPaths(eventPaths, callback) {
     const documentIds = await Promise.all(eventPaths.map((eventPath) => this.path.path2id(eventPath)));
-    const lockKeys = [...new Set(documentIds)].sort().map((documentId) => `processFileEvent-${documentId}`);
-    return await serializedByKeys(
-      lockKeys,
-      () => callback(documentIds.length === 2 && documentIds[0] === documentIds[1])
-    );
+    const uniqueIds = [...new Set(documentIds)].sort();
+    const lockKeys = uniqueIds.map((documentId) => `processFileEvent-${documentId}`);
+    const pending = [];
+    let result;
+    let failed = false;
+    let failure;
+    try {
+      result = await serializedByKeys(lockKeys, async () => {
+        for (const id of uniqueIds) this.deferredConflictChecks.set(id, pending);
+        try {
+          return await callback(documentIds.length === 2 && documentIds[0] === documentIds[1]);
+        } finally {
+          for (const id of uniqueIds) this.deferredConflictChecks.delete(id);
+        }
+      });
+    } catch (ex) {
+      failed = true;
+      failure = ex;
+    }
+    for (const check of pending) {
+      try {
+        if (check.ifOpen) await this.conflict.queueCheckForIfOpen(check.path);
+        else await this.conflict.queueCheckFor(check.path);
+      } catch (ex) {
+        if (!failed) {
+          failed = true;
+          failure = ex;
+        }
+        break;
+      }
+    }
+    if (failed) throw failure;
+    return result;
+  }
+  /**
+   * Queue a conflict hook while its document lock is held, or run it directly
+   * when no matching lock is active. Preserve `ifOpen` across deferral.
+   */
+  async queueConflictCheckFor(path, ifOpen = false) {
+    const documentId = await this.path.path2id(path);
+    const pending = this.deferredConflictChecks.get(documentId);
+    if (pending) {
+      pending.push({ path, ifOpen });
+      return;
+    }
+    if (ifOpen) await this.conflict.queueCheckForIfOpen(path);
+    else await this.conflict.queueCheckFor(path);
   }
   /**
    * Revalidate a persisted storage operation against the current storage state.
@@ -733,7 +1111,9 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
    * Snapshot entries preserve operation intent and ordering only. Their file
    * stub, timestamps, and existence assumptions can be stale after a restart.
    * Current inclusion is therefore read from storage, while destructive work
-   * is allowed only after current absence has been observed.
+   * is allowed only after current absence has been observed. Store and rename
+   * actions use the fresh reread with bounded retry because no later watcher
+   * event is guaranteed after startup reconciliation.
    */
   async _processRestoredFileEvent(item) {
     const eventItem = item.args;
@@ -757,11 +1137,11 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
         case "none":
           return true;
         case "store":
-          return await this.storeFileToDB(action.file);
+          return await this.storeFileToDBFromRevision(action.file, false, false, void 0, true);
         case "delete":
-          return await this.deleteFileFromDB(action.path);
+          return await this.deleteFileFromDBCore(action.path);
         case "rename":
-          return await this.renameFileInDB(action.file, action.oldPath);
+          return await this.renameFileInDBCore(action.file, action.oldPath, true);
       }
     });
   }
@@ -864,7 +1244,7 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
     this._log(ex, LOG_LEVEL_VERBOSE);
   }
   async _anyProcessReplicatedDoc(entry) {
-    return await serialized(`processReplicatedDoc-${entry._id}`, async () => {
+    return await this.serializedByFileEventPaths([this.getPath(entry)], async () => {
       if (!await this.vault.isTargetFile(entry.path)) {
         this._log(`File ${entry.path} is not the target file`, LOG_LEVEL_VERBOSE);
         return false;
@@ -892,7 +1272,7 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
           LOG_LEVEL_VERBOSE
         );
         this.events.emitEvent(EVENT_CONFLICT_CANCELLED, path);
-        const ret = await this.dbToStorage(entry, targetFile);
+        const ret = await this.dbToStorageCore(entry, targetFile);
         this._log(`Processing ${path} (${entry._id.substring(0, 8)} :${entry._rev?.substring(0, 5)}) : Done`);
         return ret;
       }