@vrtmrz/livesync-commonlib 0.1.0-rc.9 → 0.1.0

package/README.md

@@ -9,6 +9,9 @@ This package is primarily for maintainers of those clients and for integrations
 >
 > Existing contributions remain welcome and the normal contribution process has not changed. Pull requests which touch packaging, host lifecycle, or compatibility boundaries may need coordination or a rebase while this boundary settles; maintainers will identify affected work rather than asking contributors to adopt a new process pre-emptively.
 
+> [!NOTE]
+> The multilingual translation resources and application dialogues are now maintained in the main application repository, [Self-hosted LiveSync](https://github.com/vrtmrz/obsidian-livesync). New pull requests for them are welcome there. Thank you to everyone who has contributed translations and dialogue improvements here.
+
 ## Status and versioning
 
 The package is pre-1.0. Pin an exact reviewed version, and review changes before upgrading. An entry in the package export map means that the import is deliberate and package-tested; it does not make every semantic detail of that entry a final 1.0 guarantee.
@@ -114,13 +117,13 @@ See [the remote configuration profile guide](docs/remote-configurations.md) for
 
 ## Contract scope
 
-The package is currently an infrastructure and compatibility boundary. The context, rooted-storage, and standard-I/O result contracts have focused cross-platform or instance-isolation tests. Platform details which cannot be shared, such as file timestamp fidelity and browser permission handling, remain host concerns and are documented separately.
+The package is currently an infrastructure and compatibility boundary. The context, rooted-storage, standard-I/O, and revision-tree safety contracts have focused cross-platform, instance-isolation, or real-PouchDB tests. Platform details which cannot be shared, such as file timestamp fidelity and browser permission handling, remain host concerns and are documented separately.
 
 `DirectFileManipulator` is useful for existing integrations, but its enumeration, watch ownership, failure, conflict, concurrency, readiness, and disposal semantics are not a stable high-level SDK contract. It is the migration source for the planned file client, not the shape to preserve as the new API.
 
 The accepted replacement direction is an asynchronously created file client with stable `list`, `get`, `put`, `delete`, `watch`, and `close` operations. The operation result, conflict, concurrency, watch checkpoint, retry, and error contracts still require focused decisions and tests before that client can be published.
 
-Package developers should read [the developer guide](docs/development.md). The focused contracts are described in [the storage guide](docs/platform-storage.md), [the standard-I/O guide](docs/platform-standard-io.md), [the settings lifecycle guide](docs/settings-lifecycle.md), and [the remote configuration profile guide](docs/remote-configurations.md).
+Package developers should read [the developer guide](docs/development.md). The focused contracts are described in [the storage guide](docs/platform-storage.md), [the standard-I/O guide](docs/platform-standard-io.md), [the settings lifecycle guide](docs/settings-lifecycle.md), [the remote configuration profile guide](docs/remote-configurations.md), and [the conflict-resolution guide](docs/conflict-resolution.md).
 
 ## Proven in maintained hosts
 

package/dist/interfaces/DatabaseFileAccess.d.ts

@@ -2,10 +2,18 @@ import type { FilePathWithPrefix, LoadedEntry, MetaEntry, UXFileInfo, UXFileInfo
 export interface DatabaseFileAccess {
     delete: (file: UXFileInfoStub | FilePathWithPrefix, rev?: string) => Promise<boolean>;
     store: (file: UXFileInfo, force?: boolean, skipCheck?: boolean) => Promise<boolean>;
+    /** Store a file as a child of an exact revision and return the created revision. */
+    storeWithBaseRevision: (file: UXFileInfo, baseRevision: string | undefined, skipCheck?: boolean) => Promise<string | false>;
     storeAsConflictedRevision: (file: UXFileInfo, currentRev: string, skipCheck?: boolean) => Promise<boolean>;
+    /** Preserve unknown storage content as a conflict and return its exact revision. */
+    storeAsConflictedRevisionWithResult: (file: UXFileInfo, currentRev: string, skipCheck?: boolean) => Promise<string | false>;
+    /** Store a user deletion as a visible logical-deletion child of an exact revision. */
+    storeDeletionWithBaseRevision: (file: UXFileInfoStub | FilePathWithPrefix, baseRevision: string) => Promise<string | false>;
     storeContent(path: FilePathWithPrefix, content: string): Promise<boolean>;
     createChunks: (file: UXFileInfo, force?: boolean, skipCheck?: boolean) => Promise<boolean>;
     hasContentInRevisionHistory: (file: UXFileInfoStub | FilePathWithPrefix, content: string | string[] | Blob | ArrayBuffer, currentRev?: string) => Promise<boolean>;
+    /** Return every available revision whose content exactly matches the supplied bytes. */
+    findContentRevisions: (file: UXFileInfoStub | FilePathWithPrefix, content: string | string[] | Blob | ArrayBuffer, currentRev?: string) => Promise<string[]>;
     fetch: (file: UXFileInfoStub | FilePathWithPrefix, rev?: string, waitForReady?: boolean, skipCheck?: boolean) => Promise<UXFileInfo | false>;
     fetchEntryFromMeta: (meta: MetaEntry, waitForReady?: boolean, skipCheck?: boolean) => Promise<LoadedEntry | false>;
     fetchEntryMeta: (file: UXFileInfoStub | FilePathWithPrefix, rev?: string, skipCheck?: boolean) => Promise<MetaEntry | false>;

package/dist/interfaces/FileHandler.d.ts

@@ -3,11 +3,27 @@ import type { UXFileInfo, UXFileInfoStub, UXInternalFileInfoStub } from "../comm
 export interface IFileHandler {
     readFileFromStub(file: UXFileInfoStub | UXFileInfo): Promise<UXFileInfo>;
     storeFileToDB(info: UXFileInfoStub | UXFileInfo | UXInternalFileInfoStub | FilePathWithPrefix, force?: boolean, onlyChunks?: boolean): Promise<boolean>;
+    /**
+     * Store the current storage content as a child of an exact live database revision.
+     *
+     * This explicit branch-selection boundary is intended for user-directed
+     * reconciliation. It rechecks that the selected revision is still live,
+     * and records the resulting revision as the storage provenance. When
+     * `createIfDifferent` is false, differing storage content is rejected
+     * instead of creating a child revision.
+     */
+    storeFileToDBWithBaseRevision(info: UXFileInfoStub | UXFileInfo | FilePathWithPrefix, baseRevision: string, createIfDifferent?: boolean): Promise<boolean>;
     deleteFileFromDB(info: UXFileInfoStub | UXInternalFileInfoStub | FilePath): Promise<boolean>;
     renameFileInDB(info: UXFileInfoStub | UXFileInfo, oldPath: FilePath | FilePathWithPrefix): Promise<boolean>;
+    /**
+     * Create a logical deletion on one exact database revision.
+     *
+     * When device-local storage provenance names the deleted revision, the
+     * implementation clears that stale provenance without changing storage.
+     */
     deleteRevisionFromDB(info: UXFileInfoStub | FilePath | FilePathWithPrefix, rev: string): Promise<boolean | undefined>;
     resolveConflictedByDeletingRevision(info: UXFileInfoStub | FilePath, rev: string): Promise<boolean | undefined>;
-    dbToStorageWithSpecificRev(info: UXFileInfoStub | UXFileInfo | FilePath | null, rev: string, force?: boolean): Promise<boolean>;
+    dbToStorageWithSpecificRev(info: UXFileInfoStub | UXFileInfo | FilePath | FilePathWithPrefix | null, rev: string, force?: boolean): Promise<boolean>;
     dbToStorage(entryInfo: MetaEntry | FilePathWithPrefix, info: UXFileInfoStub | UXFileInfo | FilePath | null, force?: boolean): Promise<boolean>;
     createAllChunks(showingNotice?: boolean): Promise<void>;
 }

package/dist/interfaces/FileReflectionProvenance.d.ts

@@ -0,0 +1,32 @@
+import type { FilePathWithPrefix } from "../common/types.js";
+import type { SimpleStore } from "../common/utils.js";
+export type FileReflectionProvenanceRecord = {
+    /** Exact database revision which most recently produced the storage state. */
+    revision: string;
+    /** Raw modification time observed from this device's storage after reflection. */
+    observedStorageMtime?: number;
+};
+export interface FileReflectionProvenance {
+    get(path: FilePathWithPrefix): Promise<FileReflectionProvenanceRecord | undefined>;
+    set(path: FilePathWithPrefix, record: FileReflectionProvenanceRecord): Promise<void>;
+    delete(path: FilePathWithPrefix): Promise<void>;
+    move(from: FilePathWithPrefix, to: FilePathWithPrefix): Promise<void>;
+}
+/**
+ * Device-local provenance backed by an existing host-owned key-value store.
+ *
+ * The revision is authoritative. The raw storage mtime is diagnostic and may
+ * be used as a fast change hint, but it never proves content or branch identity.
+ * The host may construct this object before opening its store, but it must not
+ * invoke provenance operations until its normal storage lifecycle is ready.
+ * Store failures are reported to the caller rather than hidden by readiness
+ * waits, so lifecycle violations and reset races cannot hang file processing.
+ */
+export declare class StoredFileReflectionProvenance implements FileReflectionProvenance {
+    private readonly store;
+    constructor(store: SimpleStore<FileReflectionProvenanceRecord>);
+    get(path: FilePathWithPrefix): Promise<FileReflectionProvenanceRecord | undefined>;
+    set(path: FilePathWithPrefix, record: FileReflectionProvenanceRecord): Promise<void>;
+    delete(path: FilePathWithPrefix): Promise<void>;
+    move(from: FilePathWithPrefix, to: FilePathWithPrefix): Promise<void>;
+}

package/dist/interfaces/FileReflectionProvenance.js

@@ -0,0 +1,25 @@
+class StoredFileReflectionProvenance {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  async get(path) {
+    return await this.store.get(path) ?? void 0;
+  }
+  async set(path, record) {
+    await this.store.set(path, record);
+  }
+  async delete(path) {
+    await this.store.delete(path);
+  }
+  async move(from, to) {
+    const record = await this.get(from);
+    if (record) {
+      await this.set(to, record);
+    }
+    await this.delete(from);
+  }
+}
+export {
+  StoredFileReflectionProvenance
+};

package/dist/managers/ConflictManager.js

@@ -15,6 +15,21 @@ import {
   isObjectMargeApplicable
 } from "../common/utils.js";
 import { isErrorOfMissingDoc } from "../pouchdb/utils_couchdb.js";
+function revisionGeneration(revision) {
+  const generation = Number(revision.split("-", 1)[0]);
+  return Number.isFinite(generation) ? generation : Number.MAX_SAFE_INTEGER;
+}
+function compareConflictCandidates(left, right) {
+  const generationDifference = revisionGeneration(left.revision) - revisionGeneration(right.revision);
+  if (generationDifference !== 0) return generationDifference;
+  const leftMtime = left.leaf === false || !Number.isFinite(left.leaf.mtime) ? Number.NEGATIVE_INFINITY : left.leaf.mtime;
+  const rightMtime = right.leaf === false || !Number.isFinite(right.leaf.mtime) ? Number.NEGATIVE_INFINITY : right.leaf.mtime;
+  const mtimeDifference = leftMtime - rightMtime;
+  if (mtimeDifference !== 0) return mtimeDifference;
+  if (left.revision < right.revision) return -1;
+  if (left.revision > right.revision) return 1;
+  return 0;
+}
 class ConflictManager {
   options;
   constructor(options) {
@@ -258,13 +273,22 @@ class ConflictManager {
   }
   async tryAutoMergeSensibly(path, test, conflicts) {
     const conflictedRev = conflicts[0];
-    const conflictedRevNo = Number(conflictedRev.split("-")[0]);
-    const revFrom = await this.database.get(await this.options.pathService.path2id(path), {
-      revs_info: true
-    });
-    const commonBase = (revFrom._revs_info || []).filter(
-      (e) => e.status == "available" && Number(e.rev.split("-")[0]) < conflictedRevNo
-    )?.[0]?.rev ?? "";
+    let commonBase = "";
+    try {
+      const documentId = await this.options.pathService.path2id(path);
+      const [currentBranch, conflictedBranch] = await Promise.all([
+        this.database.get(documentId, { rev: test._rev, revs_info: true }),
+        this.database.get(documentId, { rev: conflictedRev, revs_info: true })
+      ]);
+      const currentAvailable = new Set(
+        (currentBranch._revs_info || []).filter((revision) => revision.status === "available").map((revision) => revision.rev)
+      );
+      commonBase = (conflictedBranch._revs_info || []).filter((revision) => revision.status === "available" && currentAvailable.has(revision.rev)).sort((left, right) => Number(right.rev.split("-")[0]) - Number(left.rev.split("-")[0]))[0]?.rev ?? "";
+    } catch (ex) {
+      Logger(`Could not determine the common revision for ${path}`, LOG_LEVEL_VERBOSE);
+      Logger(ex, LOG_LEVEL_VERBOSE);
+      return false;
+    }
     let p = void 0;
     if (commonBase) {
       if (isSensibleMargeApplicable(path)) {
@@ -302,9 +326,18 @@ class ConflictManager {
     if (test == null) return { ok: MISSING_OR_ERROR };
     if (!test._conflicts) return { ok: NOT_CONFLICTED };
     if (test._conflicts.length == 0) return { ok: NOT_CONFLICTED };
-    const conflicts = test._conflicts.sort((a, b) => Number(a.split("-")[0]) - Number(b.split("-")[0]));
+    const conflictCandidates = await Promise.all(
+      test._conflicts.map(
+        async (revision) => ({
+          revision,
+          leaf: await this.getConflictedDoc(path, revision)
+        })
+      )
+    );
+    conflictCandidates.sort(compareConflictCandidates);
+    const conflicts = conflictCandidates.map(({ revision }) => revision);
     const leftLeaf = await this.getConflictedDoc(path, test._rev);
-    const rightLeaf = await this.getConflictedDoc(path, conflicts[0]);
+    const rightLeaf = conflictCandidates[0].leaf;
     if (leftLeaf !== false && rightLeaf !== false && leftLeaf.data == rightLeaf.data && leftLeaf.deleted == rightLeaf.deleted) {
       return { leftRev: test._rev, rightRev: conflicts[0], leftLeaf, rightLeaf };
     }

package/dist/managers/EntryManager/EntryManager.d.ts

@@ -33,5 +33,6 @@ export declare class EntryManager {
     getDBEntry(path: FilePathWithPrefix | FilePath, opt?: PouchDB.Core.GetOptions, dump?: boolean, waitForReady?: boolean, includeDeleted?: boolean): Promise<false | LoadedEntry>;
     getDBEntryFromMeta(meta: LoadedEntry | MetaEntry, dump?: boolean, waitForReady?: boolean): Promise<false | LoadedEntry>;
     deleteDBEntry(path: FilePathWithPrefix | FilePath, opt?: PouchDB.Core.GetOptions): Promise<boolean>;
+    storeDeletionAtRevision(path: FilePathWithPrefix | FilePath, baseRevision: string): Promise<false | PouchDB.Core.Response>;
     putDBEntry(note: SavingEntry, onlyChunks?: boolean, conflictBaseRev?: string): Promise<false | PouchDB.Core.Response>;
 }

package/dist/managers/EntryManager/EntryManager.js

@@ -8,7 +8,8 @@ import {
   getDBEntryMetaByPath,
   isTargetFile,
   prepareChunk,
-  putDBEntry
+  putDBEntry,
+  storeDeletionByPathAtRevision
 } from "./EntryManagerImpls.js";
 class EntryManager {
   options;
@@ -64,6 +65,9 @@ class EntryManager {
   async deleteDBEntry(path, opt) {
     return await deleteDBEntryByPath(this.serviceHost, this, path, opt);
   }
+  async storeDeletionAtRevision(path, baseRevision) {
+    return await storeDeletionByPathAtRevision(this.serviceHost, this, path, baseRevision);
+  }
   async putDBEntry(note, onlyChunks, conflictBaseRev) {
     return await putDBEntry(this.serviceHost, this, note, onlyChunks, conflictBaseRev);
   }

package/dist/managers/EntryManager/EntryManagerImpls.d.ts

@@ -71,4 +71,5 @@ export declare function getDBEntryByPath(host: NecessaryServicesInterfaces<"path
     datatype: import("../../common/types.js").EntryTypeNotes;
 } & PouchDB.Core.IdMeta)>;
 export declare function deleteDBEntryByPath(host: NecessaryServicesInterfaces<"path" | "setting", never>, { localDatabase }: NecessaryManagers<"localDatabase">, path: FilePathWithPrefix | FilePath, opt?: PouchDB.Core.GetOptions): Promise<boolean>;
+export declare function storeDeletionByPathAtRevision(host: NecessaryServicesInterfaces<"path" | "setting", never>, { localDatabase }: NecessaryManagers<"localDatabase">, path: FilePathWithPrefix | FilePath, baseRevision: string): Promise<PouchDB.Core.Response | false>;
 export {};

package/dist/managers/EntryManager/EntryManagerImpls.js

@@ -484,6 +484,33 @@ async function deleteDBEntryByPath(host, { localDatabase }, path, opt) {
     throw ex;
   }
 }
+async function storeDeletionByPathAtRevision(host, { localDatabase }, path, baseRevision) {
+  if (!isTargetFile(host, path)) {
+    return false;
+  }
+  const id = await host.services.path.path2id(path);
+  try {
+    return await serialized("file:" + path, async () => {
+      const obj = await localDatabase.get(id, {
+        rev: baseRevision
+      });
+      if (obj.type === "leaf") {
+        return false;
+      }
+      delete obj._deleted;
+      obj.deleted = true;
+      obj.mtime = Date.now();
+      const result = await localDatabase.put(obj, { force: true });
+      Logger(`Entry soft-deleted from revision: ${path} (${obj._id.substring(0, 8)}-${result.rev})`);
+      return result;
+    }) ?? false;
+  } catch (ex) {
+    if (isErrorOfMissingDoc(ex)) {
+      return false;
+    }
+    throw ex;
+  }
+}
 export {
   canUseOnDemandChunking,
   computeChunkRetrievalMethod,
@@ -495,5 +522,6 @@ export {
   isLegacyNote,
   isTargetFile,
   prepareChunk,
-  putDBEntry
+  putDBEntry,
+  storeDeletionByPathAtRevision
 };

package/dist/pouchdb/LiveSyncLocalDB.d.ts

@@ -190,6 +190,7 @@ export declare class LiveSyncLocalDB {
     getDBEntry(path: FilePathWithPrefix | FilePath, opt?: PouchDB.Core.GetOptions, dump?: boolean, waitForReady?: boolean, includeDeleted?: boolean): Promise<false | LoadedEntry>;
     getDBEntryFromMeta(meta: LoadedEntry | MetaEntry, dump?: boolean, waitForReady?: boolean): Promise<false | LoadedEntry>;
     deleteDBEntry(path: FilePathWithPrefix | FilePath, opt?: PouchDB.Core.GetOptions): Promise<boolean>;
+    storeDeletionAtRevision(path: FilePathWithPrefix | FilePath, baseRevision: string): Promise<false | PouchDB.Core.Response>;
     putDBEntry(note: SavingEntry, onlyChunks?: boolean, conflictBaseRev?: string): Promise<false | PouchDB.Core.Response>;
     getConflictedDoc(path: FilePathWithPrefix, rev: string): Promise<false | diff_result_leaf>;
     tryAutoMerge(path: FilePathWithPrefix, enableMarkdownAutoMerge: boolean): AutoMergeResult;

package/dist/pouchdb/LiveSyncLocalDB.js

@@ -364,6 +364,9 @@ class LiveSyncLocalDB {
   async deleteDBEntry(path, opt) {
     return await this.managers.entryManager.deleteDBEntry(path, opt);
   }
+  async storeDeletionAtRevision(path, baseRevision) {
+    return await this.managers.entryManager.storeDeletionAtRevision(path, baseRevision);
+  }
   async putDBEntry(note, onlyChunks, conflictBaseRev) {
     return await this.managers.entryManager.putDBEntry(note, onlyChunks, conflictBaseRev);
   }

package/dist/serviceFeatures/offlineScanner.js

@@ -8,7 +8,7 @@ import {
   isMetaEntry
 } from "../common/types.js";
 import { compareMTime, isAnyNote } from "../common/utils.js";
-import { stripAllPrefixes } from "../string_and_binary/path.js";
+import { shouldBeIgnored, stripAllPrefixes } from "../string_and_binary/path.js";
 import { createInstanceLogFunction } from "../services/lib/logUtils.js";
 import { BASE_IS_NEW, EVEN, TARGET_IS_NEW } from "../common/models/shared.const.symbols.js";
 import { UnresolvedErrorManager } from "../services/base/UnresolvedErrorManager.js";
@@ -124,6 +124,7 @@ async function collectFilesOnStorage(host, settings, log) {
   const filesStorageSrc = await host.serviceModules.storageAccess.getFiles();
   const _filesStorage = [];
   for (const f of filesStorageSrc) {
+    if (shouldBeIgnored(f.path)) continue;
     if (await host.services.vault.isTargetFile(f.path)) {
       _filesStorage.push(f);
     }
@@ -147,7 +148,7 @@ async function collectDatabaseFiles(host, settings, log, showingNotice) {
         "syncAll"
       );
     const path = getPathFromEntry(host, doc);
-    if (host.services.vault.isValidPath(path) && await host.services.vault.isTargetFile(path)) {
+    if (host.services.vault.isValidPath(path) && !shouldBeIgnored(path) && await host.services.vault.isTargetFile(path)) {
       if (!isMetaEntry(doc)) {
         log(`Invalid entry: ${path}`, LOG_LEVEL_INFO);
         continue;

package/dist/serviceFeatures/remoteConfig.d.ts

@@ -65,11 +65,11 @@ export declare function activateRemoteConfiguration(settings: ObsidianLiveSyncSe
  */
 export declare function activateP2PRemoteConfiguration(settings: ObsidianLiveSyncSettings, id: string): ObsidianLiveSyncSettings | false;
 /**
- * Command: Switch Active Remote
+ * Command: Switch active connection
  */
 export declare function commandSwitchActiveRemote(host: RemoteConfigHost): Promise<void>;
 /**
- * Command: Replicate with specific remote
+ * Command: Sync with a saved connection
  */
 export declare function commandReplicateWithSpecificRemote(host: RemoteConfigHost): Promise<void>;
 /**

package/dist/serviceFeatures/remoteConfig.js

@@ -311,12 +311,12 @@ function useRemoteConfigurationMigration(host) {
 function useRemoteConfiguration(host) {
   host.services.API.addCommand({
     id: "livesync-switch-remote",
-    name: "Switch Active Remote",
+    name: "Switch active connection",
     callback: () => commandSwitchActiveRemote(host)
   });
   host.services.API.addCommand({
     id: "livesync-replicate-with-specific",
-    name: "Replicate with specific remote",
+    name: "Sync with a saved connection",
     callback: () => commandReplicateWithSpecificRemote(host)
   });
   return true;

package/dist/serviceModules/ServiceDatabaseFileAccessBase.d.ts

@@ -26,10 +26,15 @@ export declare class ServiceDatabaseFileAccessBase extends ServiceModuleBase<Ser
     delete(file: UXFileInfoStub | FilePathWithPrefix, rev?: string): Promise<boolean>;
     createChunks(file: UXFileInfo, force?: boolean, skipCheck?: boolean): Promise<boolean>;
     store(file: UXFileInfo, force?: boolean, skipCheck?: boolean): Promise<boolean>;
+    storeWithBaseRevision(file: UXFileInfo, baseRevision: string | undefined, skipCheck?: boolean): Promise<string | false>;
     storeAsConflictedRevision(file: UXFileInfo, currentRev: string, skipCheck?: boolean): Promise<boolean>;
+    storeAsConflictedRevisionWithResult(file: UXFileInfo, currentRev: string, skipCheck?: boolean): Promise<string | false>;
+    storeDeletionWithBaseRevision(file: UXFileInfoStub | FilePathWithPrefix, baseRevision: string): Promise<string | false>;
     storeContent(path: FilePathWithPrefix, content: string): Promise<boolean>;
     private __store;
     private getParentRev;
+    private findContentRevisionsInternal;
+    findContentRevisions(file: UXFileInfoStub | FilePathWithPrefix, content: string | string[] | Blob | ArrayBuffer, currentRev?: string): Promise<string[]>;
     hasContentInRevisionHistory(file: UXFileInfoStub | FilePathWithPrefix, content: string | string[] | Blob | ArrayBuffer, currentRev?: string): Promise<boolean>;
     getConflictedRevs(file: UXFileInfoStub | FilePathWithPrefix): Promise<string[]>;
     fetch(file: UXFileInfoStub | FilePathWithPrefix, rev?: string, waitForReady?: boolean, skipCheck?: boolean): Promise<UXFileInfo | false>;

package/dist/serviceModules/ServiceDatabaseFileAccessBase.js

@@ -47,18 +47,37 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
     }
   }
   async createChunks(file, force = false, skipCheck) {
-    return await this.__store(file, force, skipCheck, true);
+    return await this.__store(file, force, skipCheck, true) !== false;
   }
   async store(file, force = false, skipCheck) {
-    return await this.__store(file, force, skipCheck, false);
+    return await this.__store(file, force, skipCheck, false) !== false;
+  }
+  async storeWithBaseRevision(file, baseRevision, skipCheck) {
+    const result = await this.__store(file, true, skipCheck, false, baseRevision);
+    return result !== null && typeof result === "object" && "rev" in result ? result.rev : false;
   }
   async storeAsConflictedRevision(file, currentRev, skipCheck) {
+    return await this.storeAsConflictedRevisionWithResult(file, currentRev, skipCheck) !== false;
+  }
+  async storeAsConflictedRevisionWithResult(file, currentRev, skipCheck) {
     const conflictBaseRev = await this.getParentRev(file, currentRev);
     if (!conflictBaseRev) {
       this._log(`Could not find parent revision for ${file.path} (${currentRev})`, LOG_LEVEL_VERBOSE);
       return false;
     }
-    return await this.__store(file, true, skipCheck, false, conflictBaseRev);
+    return await this.storeWithBaseRevision(file, conflictBaseRev, skipCheck);
+  }
+  async storeDeletionWithBaseRevision(file, baseRevision) {
+    if (!await this.checkIsTargetFile(file)) {
+      return false;
+    }
+    const fullPath = getDatabasePathFromUXFileInfo(file);
+    const result = await this.database.localDatabase.storeDeletionAtRevision(fullPath, baseRevision);
+    if (result === false) {
+      return false;
+    }
+    this.events.emitEvent(EVENT_FILE_SAVED);
+    return result.rev;
   }
   async storeContent(path, content) {
     const blob = createTextBlob(content);
@@ -76,7 +95,7 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
       body: blob,
       isInternal
     };
-    return await this.__store(dummyUXFileInfo, true, false, false);
+    return await this.__store(dummyUXFileInfo, true, false, false) !== false;
   }
   async __store(file, force = false, skipCheck, onlyChunks, conflictBaseRev) {
     if (!skipCheck) {
@@ -169,7 +188,7 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
       this._log(msg + fullPath);
       this.events.emitEvent(EVENT_FILE_SAVED);
     }
-    return ret != false;
+    return ret;
   }
   async getParentRev(file, rev) {
     const filename = getDatabasePathFromUXFileInfo(file);
@@ -189,10 +208,7 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
       return false;
     }
   }
-  async hasContentInRevisionHistory(file, content, currentRev) {
-    if (!await this.checkIsTargetFile(file)) {
-      return true;
-    }
+  async findContentRevisionsInternal(file, content, currentRev) {
     const filename = getDatabasePathFromUXFileInfo(file);
     try {
       const doc = await this.database.localDatabase.getDBEntryMeta(
@@ -201,24 +217,64 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
         true
       );
       if (doc === false) {
-        return false;
+        return [];
       }
       const revisions = doc._revs_info;
       const availableRevs = new Set((revisions || []).filter((e) => e.status === "available").map((e) => e.rev));
       if (currentRev) {
         availableRevs.add(currentRev);
       }
+      const leaves = await this.database.localDatabase.getRaw(doc._id, {
+        open_revs: "all"
+      });
+      if (!Array.isArray(leaves)) {
+        return [];
+      }
+      for (const leaf of leaves) {
+        const leafRev = leaf.ok?._rev;
+        if (!leafRev) {
+          continue;
+        }
+        const branch = await this.database.localDatabase.getDBEntryMeta(
+          filename,
+          { rev: leafRev, revs_info: true },
+          true
+        );
+        if (branch === false) {
+          continue;
+        }
+        const branchRevisions = branch._revs_info;
+        for (const revision of branchRevisions || []) {
+          if (revision.status === "available") {
+            availableRevs.add(revision.rev);
+          }
+        }
+      }
+      const matchingRevisions = [];
       for (const rev of availableRevs) {
         const entry = await this.database.localDatabase.getDBEntry(filename, { rev }, false, true, true);
-        if (entry !== false && await isDocContentSame(readContent(entry), content)) {
-          return true;
+        if (entry !== false && !entry._deleted && await isDocContentSame(readContent(entry), content)) {
+          matchingRevisions.push(rev);
         }
       }
+      return matchingRevisions;
     } catch (ex) {
       this._log(`Could not check revision history for ${filename}`, LOG_LEVEL_VERBOSE);
       this._log(ex, LOG_LEVEL_VERBOSE);
     }
-    return false;
+    return [];
+  }
+  async findContentRevisions(file, content, currentRev) {
+    if (!await this.checkIsTargetFile(file)) {
+      return [];
+    }
+    return await this.findContentRevisionsInternal(file, content, currentRev);
+  }
+  async hasContentInRevisionHistory(file, content, currentRev) {
+    if (!await this.checkIsTargetFile(file)) {
+      return true;
+    }
+    return (await this.findContentRevisionsInternal(file, content, currentRev)).length > 0;
   }
   async getConflictedRevs(file) {
     if (!await this.checkIsTargetFile(file)) {

package/dist/serviceModules/ServiceFileHandlerBase.d.ts

@@ -11,6 +11,7 @@ import type { ConflictService } from "../services/base/ConflictService.js";
 import type { PathService } from "../services/base/PathService.js";
 import type { SettingService } from "../services/base/SettingService.js";
 import type { VaultService } from "../services/base/VaultService.js";
+import type { FileReflectionProvenance } from "../interfaces/FileReflectionProvenance.js";
 export interface ServiceFileHandlerDependencies {
     events: LiveSyncEventHub;
     API: APIService;
@@ -22,6 +23,17 @@ export interface ServiceFileHandlerDependencies {
     path: PathService;
     setting: SettingService;
     vault: VaultService;
+    /**
+     * Device-local record of the exact database revision reflected in storage.
+     *
+     * This is optional for compatibility hosts. Maintained hosts should provide
+     * it so edits made while a document is conflicted extend the displayed
+     * branch instead of whichever branch PouchDB currently selects as winner.
+     * The host must finish opening its backing store before it dispatches file
+     * or replication events; provenance does not hide lifecycle violations by
+     * waiting for readiness.
+     */
+    fileReflectionProvenance?: FileReflectionProvenance;
 }
 export declare abstract class ServiceFileHandlerBase extends ServiceModuleBase<ServiceFileHandlerDependencies> implements IFileHandler {
     private events;
@@ -31,20 +43,29 @@ export declare abstract class ServiceFileHandlerBase extends ServiceModuleBase<S
     private path;
     private setting;
     private vault;
+    private fileReflectionProvenance?;
     constructor(services: ServiceFileHandlerDependencies);
     get db(): DatabaseFileAccess;
     get storage(): StorageAccess;
+    private getProvenance;
+    private setProvenance;
+    private deleteProvenance;
+    private findUniqueContentRevision;
+    private getProvenBaseRevision;
     getPath(entry: AnyEntry): FilePathWithPrefix;
     getPathWithoutPrefix(entry: AnyEntry): FilePathWithPrefix;
     readFileFromStub(file: UXFileInfoStub | UXFileInfo): Promise<UXFileInfo>;
     private infoToStub;
     storeFileToDB(info: UXFileInfoStub | UXFileInfo | UXInternalFileInfoStub | FilePathWithPrefix, force?: boolean, onlyChunks?: boolean): Promise<boolean>;
+    storeFileToDBWithBaseRevision(info: UXFileInfoStub | UXFileInfo | FilePathWithPrefix, baseRevision: string, createIfDifferent?: boolean): Promise<boolean>;
+    private storeFileToDBFromRevision;
     deleteFileFromDB(info: UXFileInfoStub | UXInternalFileInfoStub | FilePath): Promise<boolean>;
     renameFileInDB(info: UXFileInfoStub | UXFileInfo, oldPath: FilePath | FilePathWithPrefix): Promise<boolean>;
     deleteRevisionFromDB(info: UXFileInfoStub | FilePath | FilePathWithPrefix, rev: string): Promise<boolean | undefined>;
     resolveConflictedByDeletingRevision(info: UXFileInfoStub | FilePath, rev: string): Promise<boolean | undefined>;
-    dbToStorageWithSpecificRev(info: UXFileInfoStub | UXFileInfo | FilePath | null, rev: string, force?: boolean): Promise<boolean>;
+    dbToStorageWithSpecificRev(info: UXFileInfoStub | UXFileInfo | FilePath | FilePathWithPrefix | null, rev: string, force?: boolean): Promise<boolean>;
     dbToStorage(entryInfo: MetaEntry | FilePathWithPrefix, info: UXFileInfoStub | UXFileInfo | FilePath | null, force?: boolean): Promise<boolean>;
+    private applyDatabaseEntryToStorage;
     private preserveUnsyncedStorageAsConflict;
     private _anyHandlerProcessesFileEvent;
     _anyProcessReplicatedDoc(entry: MetaEntry): Promise<boolean>;