@vrtmrz/livesync-commonlib 0.1.0-rc.10 → 0.1.0-rc.11

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) {
@@ -311,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/docs/conflict-resolution.md

@@ -50,6 +50,14 @@ A client can resolve only the leaves which it has observed. If it resolves an ol
 
 This is expected conflict behaviour, not a replication reset. A resolver should process the current leaves repeatedly until one live result remains or user action is required.
 
+## More than two live versions
+
+When a document has three or more live leaves, Commonlib compares the current PouchDB winner with one remaining leaf at a time. The remaining candidates are ordered by revision generation ascending, original leaf modification time ascending, then the complete revision ID in code-unit lexical order. A missing or non-finite modification time sorts before a finite time. This order makes the next pair reproducible; it does not make an earlier modification time authoritative.
+
+Each duplicate collapse, conservative merge, or host-directed manual choice is committed to the ordinary revision tree before the next pair is considered. The resolver then reads the current live leaves again instead of retaining a separate accumulator. Completed stages therefore survive a process restart, while a new or externally resolved leaf is considered from the tree which actually exists at the next check.
+
+A host must not apply a dialogue result after either compared revision has ceased to be the current pair. It should discard that stale result, refresh its warning or dialogue state, and queue the path again when conflicts remain.
+
 ## File-reflection provenance
 
 The compatibility implementation accepts an injected, device-local `FileReflectionProvenance` capability owned by the database-to-storage composition rather than by a filesystem adapter. Maintained hosts persist:
@@ -150,4 +158,4 @@ Do not:
 
 ## Verification ownership
 
-Commonlib unit tests build real in-memory PouchDB trees and inject provenance fakes at the file-handler boundary. They cover unequal branch lengths, nearest shared ancestry, content retained below a deleted losing leaf, recorded and reconstructed branch identity, ambiguous content, conflict-time editing, logical deletion, case-only rename, cross-path rename, and safe unproven fallbacks. A maintained host should additionally verify its composition: persistent device-local provenance, real file events, replication of the resulting revision trees, and dialogue policy.
+Commonlib unit tests build real in-memory PouchDB trees and inject provenance fakes at the file-handler boundary. They cover unequal branch lengths, nearest shared ancestry, deterministic selection from multiple live leaves, reconstruction of a later manual pair after an earlier sensible merge, content retained below a deleted losing leaf, recorded and reconstructed branch identity, ambiguous content, conflict-time editing, logical deletion, case-only rename, cross-path rename, and safe unproven fallbacks. A maintained host should additionally verify its composition: persistent device-local provenance, real file events, replication of the resulting revision trees, and dialogue policy.

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. `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. Extend the relevant sides when changing conflict resolution, compaction handling, provenance, 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. Extend the relevant sides when changing conflict resolution, compaction handling, provenance, 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, 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. 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. 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.
 
 Most replication and storage services used by the plug-in still enter through explicit `compat/*` paths. Those imports prove that the published compatibility boundary supports the current migration; they are not examples of a finished high-level client API.
 

package/package.json

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