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

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/dist/serviceModules/ServiceFileHandlerBase.js

@@ -188,7 +188,8 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
         await this.conflict.queueCheckFor(file.path);
         return true;
       }
-      const currentRevision = entry && entry._rev;
+      const currentEntry = entry || await this.db.fetchEntryMeta(file, void 0, true);
+      const currentRevision = currentEntry && currentEntry._rev;
       if (!currentRevision) {
         this._log(
           `Could not preserve the unknown conflict branch for ${file.path}; no current revision is available`,

package/docs/conflict-resolution.md

@@ -18,6 +18,12 @@ A1
 
 Resolving a conflict writes the selected or merged result on one branch and deletes every losing live leaf which the resolver has observed. Deleted leaves remain part of the tree until compaction removes their bodies. A stale client can therefore receive the resolved branch and the tombstone for a branch whose old content is still present in its storage.
 
+## Chunk reachability during conflicts
+
+A host which collects unreferenced chunks must include the current winner, every other live conflict leaf, their available divergent revisions, and their nearest available shared ancestor in its reachability scan. This preserves the content and merge base required to review an unresolved conflict. Chunk identifiers are shared across documents, so one reachability set must cover the whole database.
+
+After the conflict is resolved, the deleted losing branch and no-longer-needed merge ancestry stop protecting their unique chunks. An ordinary superseded linear revision also does not protect its former chunks. A host must keep garbage collection separate from repair because collection cannot reconstruct content which is already unavailable.
+
 ## Safety invariants
 
 Commonlib follows these rules:
@@ -50,6 +56,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:
@@ -77,6 +91,8 @@ With a proven displayed revision:
 
 When edit provenance cannot be reconstructed, the new bytes are preserved as another manual-resolution branch instead of being attached silently to the deterministic winner. A deletion has no remaining file body from which to reconstruct provenance, so an unproven deletion preserves every live branch and requests conflict review. A cross-path rename with an unproven source keeps the newly stored target and preserves every source branch for review.
 
+If chunks needed to reconstruct the winning body are missing, the document metadata and revision tree may still identify the exact winning revision and its parent. In that case, an edited storage file is preserved as a sibling branch from the shared parent without treating the unavailable body as trusted content. A generation-one revision has no parent from which a sibling can be created. If the parent or revision metadata is unavailable, Commonlib refuses the write and requests conflict review rather than inventing a base revision. A host may offer a separately confirmed exact-revision discard: logical deletion needs the revision metadata, not its chunks, and a confirmed replacement can then be stored. This is a recovery decision and must not be performed automatically.
+
 These fallbacks favour recoverability. They may temporarily leave a duplicate target or a still-visible source conflict, but they do not discard a branch whose relationship to the user's operation cannot be proved.
 
 ## Worked revision-tree scenarios
@@ -150,4 +166,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, missing-body preservation from available parent metadata, refusal to invent a parent for a generation-one revision, exact logical deletion and replacement of an unreadable generation-one live leaf, 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. `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,9 @@ 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. 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 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.
 
 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.12",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "license": "MIT",