@vrtmrz/livesync-commonlib 0.1.0-rc.12 → 0.1.0-rc.13

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/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/ServiceFileHandlerBase.d.ts

@@ -57,12 +57,13 @@ export declare abstract class ServiceFileHandlerBase extends ServiceModuleBase<S
     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;

package/dist/serviceModules/ServiceFileHandlerBase.js

@@ -149,6 +149,59 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
   async storeFileToDB(info, force = false, onlyChunks = false) {
     return await this.storeFileToDBFromRevision(info, force, onlyChunks);
   }
+  async storeFileToDBWithBaseRevision(info, baseRevision, createIfDifferent = true) {
+    const file = await this.infoToStub(info);
+    if (file == null) {
+      this._log(`File ${tryGetFilePath(info)} is not exist on the storage`, LOG_LEVEL_VERBOSE);
+      return false;
+    }
+    if (file.isInternal) {
+      this._log(
+        `Internal file ${file.path} is not allowed to be stored through the ordinary file handler`,
+        LOG_LEVEL_VERBOSE
+      );
+      return false;
+    }
+    const [baseEntry, currentEntry, conflictedRevisions] = await Promise.all([
+      this.db.fetchEntryMeta(file, baseRevision, true),
+      this.db.fetchEntryMeta(file, void 0, true),
+      this.db.getConflictedRevs(file)
+    ]);
+    const liveRevisions = /* @__PURE__ */ new Set([
+      ...currentEntry && currentEntry._rev ? [currentEntry._rev] : [],
+      ...conflictedRevisions
+    ]);
+    if (!baseEntry || baseEntry._rev !== baseRevision || !liveRevisions.has(baseRevision)) {
+      this._log(
+        `Could not store ${file.path} on revision ${baseRevision}; the selected revision is no longer live`,
+        LOG_LEVEL_NOTICE
+      );
+      return false;
+    }
+    const readFile = await this.readFileFromStub(file);
+    if (!baseEntry.deleted && !baseEntry._deleted) {
+      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);
+        return true;
+      }
+    }
+    if (!createIfDifferent) {
+      this._log(
+        `Could not mark ${file.path} as revision ${baseRevision}; the storage content differs`,
+        LOG_LEVEL_NOTICE
+      );
+      return false;
+    }
+    const storedRevision = await this.db.storeWithBaseRevision(readFile, baseRevision, true);
+    if (storedRevision === false) {
+      return false;
+    }
+    await this.setProvenance(file.path, storedRevision, readFile.stat.mtime);
+    await this.conflict.queueCheckFor(file.path);
+    return true;
+  }
   async storeFileToDBFromRevision(info, force = false, onlyChunks = false, preferredBasePath) {
     const file = await this.infoToStub(info);
     if (file == null) {
@@ -381,31 +434,60 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
     return deleted;
   }
   async deleteRevisionFromDB(info, rev) {
-    return await this.db.delete(info, rev);
+    const path = getStoragePathFromUXFileInfo(info);
+    const provenance = await this.getProvenance(path);
+    const deleted = await this.db.delete(info, rev);
+    if (deleted && provenance?.revision === rev) {
+      await this.deleteProvenance(path);
+    }
+    return deleted;
   }
   async resolveConflictedByDeletingRevision(info, rev) {
     const path = getStoragePathFromUXFileInfo(info);
+    const file = await this.infoToStub(info);
+    const docEntry = await this.db.fetchEntryMeta(file ?? info, rev, true);
+    if (!docEntry) {
+      this._log(`Failed to read the conflicted revision ${rev} of ${path}`, LOG_LEVEL_VERBOSE);
+      return false;
+    }
     if (!await this.deleteRevisionFromDB(info, rev)) {
       this._log(`Failed to delete the conflicted revision ${rev} of ${path}`, LOG_LEVEL_VERBOSE);
       return false;
     }
-    if (!await this.dbToStorageWithSpecificRev(info, rev, true)) {
+    if (!await this.applyDatabaseEntryToStorage(docEntry, file, true)) {
       this._log(`Failed to apply the resolved revision ${rev} of ${path} to the storage`, LOG_LEVEL_VERBOSE);
       return false;
     }
+    await this.deleteProvenance(path);
   }
   async dbToStorageWithSpecificRev(info, rev, force) {
-    const file = await this.infoToStub(info);
-    if (file == null) {
-      this._log(`File ${tryGetFilePath(info)} is not exist on the storage`, LOG_LEVEL_VERBOSE);
+    if (info == null) {
+      this._log(`Cannot select database revision ${rev} without a file path`, LOG_LEVEL_VERBOSE);
       return false;
     }
-    const docEntry = await this.db.fetchEntryMeta(file, rev, true);
+    const file = await this.infoToStub(info);
+    const databaseTarget = file ?? info;
+    const [docEntry, currentEntry, conflictedRevisions] = await Promise.all([
+      this.db.fetchEntryMeta(databaseTarget, rev, true),
+      this.db.fetchEntryMeta(databaseTarget, void 0, true),
+      this.db.getConflictedRevs(databaseTarget)
+    ]);
     if (!docEntry) {
-      this._log(`File ${file.path} is not exist on the database`, LOG_LEVEL_VERBOSE);
+      this._log(`File ${tryGetFilePath(info)} is not exist on the database`, LOG_LEVEL_VERBOSE);
       return false;
     }
-    return await this.applyDatabaseEntryToStorage(docEntry, file, force);
+    const liveRevisions = /* @__PURE__ */ new Set([
+      ...currentEntry && currentEntry._rev ? [currentEntry._rev] : [],
+      ...conflictedRevisions
+    ]);
+    if (!liveRevisions.has(rev)) {
+      this._log(
+        `Could not apply ${tryGetFilePath(info)} revision ${rev}; the selected revision is no longer live`,
+        LOG_LEVEL_NOTICE
+      );
+      return false;
+    }
+    return await this.applyDatabaseEntryToStorage(docEntry, file, force, true);
   }
   async dbToStorage(entryInfo, info, force) {
     const file = await this.infoToStub(info);
@@ -417,12 +499,12 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
     }
     return await this.applyDatabaseEntryToStorage(docEntry, file, force);
   }
-  async applyDatabaseEntryToStorage(docEntry, file, force) {
+  async applyDatabaseEntryToStorage(docEntry, file, force, allowExistingConflicts = false) {
     const mode = file == null ? "create" : "modify";
     const path = this.getPath(docEntry);
     const settings = this.setting.currentSettings();
     const revs = await this.db.getConflictedRevs(path);
-    if (revs.length > 0) {
+    if (revs.length > 0 && !allowExistingConflicts) {
       if (settings.writeDocumentsIfConflicted) {
       } else {
         await this.conflict.queueCheckForIfOpen(path);
@@ -490,6 +572,14 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       }
     }
     const docData = readContent(docRead);
+    if (allowExistingConflicts && existDoc && !force) {
+      const readFile = await this.readFileFromStub(existDoc);
+      if (await isDocContentSame(docData, readFile.body)) {
+        await this.setProvenance(path, docEntry._rev, existDoc.stat.mtime);
+        this.path.markChangesAreSame(docRead, docRead.mtime, existDoc.stat.mtime);
+        return true;
+      }
+    }
     if (existDoc && !force) {
       let shouldApplied = false;
       const freshness = this.path.compareFileFreshness(existDoc, docEntry);

package/docs/conflict-resolution.md

@@ -76,6 +76,10 @@ path -> { revision, observedStorageMtime? }
 
 The record is updated only after a successful database-to-storage reflection or storage-to-database write. A plain read does not change provenance. A record remains authoritative when a user edits the displayed file to bytes which happen to equal another branch; content equality must not silently change the branch being extended.
 
+User-directed reconciliation may select any exact current live revision, including a conflict leaf rather than the deterministic winner. `dbToStorageWithSpecificRev()` rechecks that the selected revision is still live before reflecting its content. `storeFileToDBWithBaseRevision()` performs the same live check before storing current storage content as a child of that revision. If the content already matches the selected non-deleted revision, it records that revision directly without creating a child. A host can set `createIfDifferent` to `false` when it intends only to record an exact content match; differing content then fails instead of changing the revision tree. A host may also create a logical deletion on an explicitly selected branch with `deleteRevisionFromDB()` after performing its own current-live-revision check. This leaves storage unchanged and clears device-local provenance only when that record names the deleted revision.
+
+A successful non-deleted reconciliation records the exact selected or newly created revision as provenance. Applying a logical deletion removes the storage item and its provenance record. Deletion provenance is not retained indefinitely: an absent storage item and a current logical-deletion winner already agree and need no further reconciliation.
+
 Hosts may construct the namespaced store handle during service composition, before its backing database is open. Store operations begin only after the host's storage lifecycle is ready. They fail rather than wait when that lifecycle contract is violated, because an implicit readiness wait could hang after failed initialisation or wait on its own initialisation handler. Database reset is a transient unavailable boundary; the host must avoid file processing during it and reconstruct derived provenance after reopening.
 
 When a record is absent, the implementation reconstructs it only if the current storage bytes match exactly one available revision body. No match, or more than one match, leaves the branch identity unknown.

package/docs/development.md

@@ -57,7 +57,7 @@ The settings lifecycle has an additional focused unit table in `src/common/model
 
 The multiple-remote profile contract has focused unit coverage in `src/serviceFeatures/remoteConfig.unit.spec.ts`. Extend it whenever profile identity, generated display names, activation, P2P selection, URI serialisation, or legacy migration changes. New hosts should import the reviewed primitives through `/remote-configurations`; `compat/serviceFeatures/remoteConfig` remains the wider migration surface used by existing clients.
 
-The revision-tree safety rules are documented in [Conflict resolution and file provenance](conflict-resolution.md). `ConflictManager.unit.spec.ts` owns common-ancestor and conservative merge behaviour, deterministic pair selection for multiple live leaves, and reconstruction from the committed tree between stages. `ServiceDatabaseFileAccessBase.unit.spec.ts` owns all-branch content discovery and exact-revision logical deletion. `ServiceFileHandlerBase.unit.spec.ts` owns the injected provenance policy for edit, deletion, and rename operations. `LiveSyncLocalDB.unit.spec.ts` owns chunk reachability across current winners, shared chunks, live conflicts, available merge ancestry, conflict resolution, and PouchDB replication of collection and recreation. Extend the relevant sides when changing conflict resolution, compaction handling, provenance, chunk collection, or database-to-storage overwrite protection.
+The revision-tree safety rules are documented in [Conflict resolution and file provenance](conflict-resolution.md). `ConflictManager.unit.spec.ts` owns common-ancestor and conservative merge behaviour, deterministic pair selection for multiple live leaves, and reconstruction from the committed tree between stages. `ServiceDatabaseFileAccessBase.unit.spec.ts` owns all-branch content discovery and exact-revision logical deletion. `ServiceFileHandlerBase.unit.spec.ts` owns the injected provenance policy for edit, deletion, and rename operations, together with user-selected reflection, child creation, strict matching, matching-provenance cleanup after exact branch deletion, and stale-revision refusal. `LiveSyncLocalDB.unit.spec.ts` owns chunk reachability across current winners, shared chunks, live conflicts, available merge ancestry, conflict resolution, and PouchDB replication of collection and recreation. Extend the relevant sides when changing conflict resolution, compaction handling, provenance, chunk collection, or database-to-storage overwrite protection.
 
 `openSimpleStore()` may create an inert namespace handle during composition, before the backing key-value database has opened. Maintained hosts must complete their sequential settings lifecycle before scans, watchers, or replication invoke the handle. Operations fail on a lifecycle violation rather than waiting for readiness; do not introduce an implicit wait which can hang after failed initialisation or become self-referential from an initialisation handler. Treat database reset as a transient unavailable boundary and reconstruct derived local state after reopening.
 

package/docs/proven-in-use.md

@@ -12,7 +12,7 @@ The plug-in extends the neutral `ServiceContext` with Obsidian-owned capabilitie
 
 The consumer contract in `test/contracts/serviceContext.ts` checks shared result semantics and exact context identity across the composed services. The real-Obsidian suite documented in `test/e2e-obsidian/README.md` then covers plug-in loading, representative Svelte dialogue mounts, Vault reflection, CouchDB and Object Storage synchronisation, a two-device P2P Setup URI round-trip, two-Vault behaviour, and other Obsidian-owned boundaries.
 
-Commonlib's real-PouchDB and injected-boundary unit tests prove that conservative merge uses the nearest revision actually shared by both conflict leaves, multiple remaining leaves are selected in a deterministic order, each completed pair is reconstructed from the committed tree, storage content from a deleted losing branch remains recognisable after resolution, and conflict-time operations retain the exact displayed branch or preserve every branch when that identity cannot be proved. They also verify that a local edit remains a readable sibling branch when the winning body is unavailable but its exact revision and parent metadata remain, that a generation-one revision without a parent is left unresolved, and that a separately confirmed exact deletion of that unreadable live leaf permits a replacement to be stored without reading the missing chunk. Self-hosted LiveSync supplies the host composition and persistent device-local provenance. Its optional two-Vault scopes cover post-resolution propagation and edit, logical deletion, case-only rename, and cross-path rename while conflicts remain active. The conflict-operation scope passes in real Obsidian against the exact locally packed Commonlib artefact, including replicated parent revisions and preservation of the other live branches.
+Commonlib's real-PouchDB and injected-boundary unit tests prove that conservative merge uses the nearest revision actually shared by both conflict leaves, multiple remaining leaves are selected in a deterministic order, each completed pair is reconstructed from the committed tree, storage content from a deleted losing branch remains recognisable after resolution, and conflict-time operations retain the exact displayed branch or preserve every branch when that identity cannot be proved. They also verify that a local edit remains a readable sibling branch when the winning body is unavailable but its exact revision and parent metadata remain, that a generation-one revision without a parent is left unresolved, and that a separately confirmed exact deletion of that unreadable live leaf permits a replacement to be stored without reading the missing chunk. Exact reconciliation tests cover reflecting a selected live leaf, storing Vault content as its child, recording a matching leaf without creating a revision, clearing matching provenance after exact branch deletion, and refusing to record a stale revision or a revision whose content differs. Self-hosted LiveSync supplies the host composition, persistent device-local provenance, and the per-revision repair interface. Its optional two-Vault scopes cover post-resolution propagation and edit, logical deletion, case-only rename, and cross-path rename while conflicts remain active. The conflict-operation scope passes in real Obsidian against the exact locally packed Commonlib artefact, including replicated parent revisions and preservation of the other live branches.
 
 Commonlib's chunk-reachability tests use real PouchDB revision trees. They verify that an ordinary superseded revision releases its unique chunks, a chunk shared by current files remains reachable, live conflict branches and their nearest available shared ancestor remain protected, and losing-branch ancestry becomes eligible after resolution. They also replicate a collected chunk deletion to another PouchDB database and verify that writing the same content can recreate and replicate the content-addressed chunk. Self-hosted LiveSync owns the CouchDB-specific Garbage Collection V3 workflow, including device checks, confirmation, deletion, push-only replication, and remote compaction.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.1.0-rc.12",
+  "version": "0.1.0-rc.13",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "license": "MIT",