@vrtmrz/livesync-commonlib 0.1.16 → 0.1.17

package/dist/interfaces/DatabaseFileAccess.d.ts

@@ -4,6 +4,16 @@ export interface DatabaseFileAccess {
     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>;
+    /**
+     * Store a file as a child of an exact revision only while that revision remains a live leaf.
+     *
+     * Unlike {@link storeWithBaseRevision}, this method does not force a branch below an obsolete
+     * revision. 'Live leaf' means any current revision-tree leaf, including a non-winning conflict
+     * leaf or a logical-deletion leaf. In particular, it returns `false` when another writer has
+     * already advanced the supplied base; ordinary target and Chunk validation can also refuse the
+     * write without creating a Metadata successor.
+     */
+    storeWithLiveBaseRevision: (file: UXFileInfo, baseRevision: string, 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>;

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

@@ -35,4 +35,5 @@ export declare class EntryManager {
     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>;
+    putDBEntryWithLiveBaseRevision(note: SavingEntry, baseRevision: string, onlyChunks?: boolean): Promise<false | PouchDB.Core.Response>;
 }

package/dist/managers/EntryManager/EntryManager.js

@@ -9,6 +9,7 @@ import {
   isTargetFile,
   prepareChunk,
   putDBEntry,
+  putDBEntryWithLiveBaseRevision,
   storeDeletionByPathAtRevision
 } from "./EntryManagerImpls.js";
 class EntryManager {
@@ -71,6 +72,9 @@ class EntryManager {
   async putDBEntry(note, onlyChunks, conflictBaseRev) {
     return await putDBEntry(this.serviceHost, this, note, onlyChunks, conflictBaseRev);
   }
+  async putDBEntryWithLiveBaseRevision(note, baseRevision, onlyChunks) {
+    return await putDBEntryWithLiveBaseRevision(this.serviceHost, this, note, baseRevision, onlyChunks);
+  }
 }
 export {
   EntryManager

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

@@ -13,6 +13,13 @@ type Managers = {
 type NecessaryManagers<T extends keyof Managers> = Pick<Managers, T>;
 export declare function createChunks(managers: NecessaryManagers<"chunkManager" | "hashManager" | "splitter">, dispFilename: string, note: SavingEntry): Promise<false | DocumentID[]>;
 export declare function putDBEntry(host: NecessaryServicesInterfaces<"path" | "setting", never>, managers: NecessaryManagers<"localDatabase" | "chunkManager" | "hashManager" | "splitter">, note: SavingEntry, onlyChunks?: boolean, conflictBaseRev?: string): Promise<false | PouchDB.Core.Response>;
+/**
+ * Store an entry below an exact revision only while that revision remains a live leaf.
+ *
+ * PouchDB's ordinary MVCC write is the authority for this check. A 409 response means that the
+ * base has already been advanced, so the caller receives `false` and can retry from fresh state.
+ */
+export declare function putDBEntryWithLiveBaseRevision(host: NecessaryServicesInterfaces<"path" | "setting", never>, managers: NecessaryManagers<"localDatabase" | "chunkManager" | "hashManager" | "splitter">, note: SavingEntry, baseRevision: string, onlyChunks?: boolean): Promise<false | PouchDB.Core.Response>;
 export declare function isTargetFile(host: NecessaryServicesInterfaces<"setting", never>, filenameSrc: string): boolean;
 export declare function prepareChunk({ chunkManager, hashManager }: NecessaryManagers<"chunkManager" | "hashManager">, piece: string): Promise<GeneratedChunk>;
 export declare function getDBEntryMetaByPath(host: NecessaryServicesInterfaces<"path" | "setting", never>, { localDatabase }: NecessaryManagers<"localDatabase">, path: FilePathWithPrefix | FilePath, opt?: PouchDB.Core.GetOptions, includeDeleted?: boolean): Promise<false | LoadedEntry>;

package/dist/managers/EntryManager/EntryManagerImpls.js

@@ -110,6 +110,23 @@ async function createChunks(managers, dispFilename, note) {
   return chunks;
 }
 async function putDBEntry(host, managers, note, onlyChunks, conflictBaseRev) {
+  const revisionTarget = conflictBaseRev ? { mode: "force-base", baseRevision: conflictBaseRev } : { mode: "latest" };
+  return await putDBEntryInternal(host, managers, note, onlyChunks, revisionTarget);
+}
+async function putDBEntryWithLiveBaseRevision(host, managers, note, baseRevision, onlyChunks) {
+  try {
+    return await putDBEntryInternal(host, managers, note, onlyChunks, {
+      mode: "live-base",
+      baseRevision
+    });
+  } catch (ex) {
+    if (ex && typeof ex === "object" && "status" in ex && ex.status === 409) {
+      return false;
+    }
+    throw ex;
+  }
+}
+async function putDBEntryInternal(host, managers, note, onlyChunks, revisionTarget) {
   const { localDatabase, chunkManager, splitter } = managers;
   const filename = host.services.path.id2path(note._id, note);
   const dispFilename = stripAllPrefixes(filename);
@@ -146,8 +163,8 @@ async function putDBEntry(host, managers, note, onlyChunks, conflictBaseRev) {
       eden: {}
     };
     return await serialized("file:" + filename, async () => {
-      if (conflictBaseRev) {
-        newDoc._rev = conflictBaseRev;
+      if (revisionTarget.mode !== "latest") {
+        newDoc._rev = revisionTarget.baseRevision;
       } else {
         try {
           const old = await localDatabase.get(newDoc._id);
@@ -159,7 +176,7 @@ async function putDBEntry(host, managers, note, onlyChunks, conflictBaseRev) {
           }
         }
       }
-      const r = await localDatabase.put(newDoc, { force: true });
+      const r = revisionTarget.mode === "live-base" ? await localDatabase.put(newDoc) : await localDatabase.put(newDoc, { force: true });
       if (r.ok) {
         return r;
       } else {
@@ -523,5 +540,6 @@ export {
   isTargetFile,
   prepareChunk,
   putDBEntry,
+  putDBEntryWithLiveBaseRevision,
   storeDeletionByPathAtRevision
 };

package/dist/pouchdb/LiveSyncLocalDB.d.ts

@@ -192,6 +192,7 @@ export declare class LiveSyncLocalDB {
     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>;
+    putDBEntryWithLiveBaseRevision(note: SavingEntry, baseRevision: string, onlyChunks?: boolean): 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

@@ -370,6 +370,9 @@ class LiveSyncLocalDB {
   async putDBEntry(note, onlyChunks, conflictBaseRev) {
     return await this.managers.entryManager.putDBEntry(note, onlyChunks, conflictBaseRev);
   }
+  async putDBEntryWithLiveBaseRevision(note, baseRevision, onlyChunks) {
+    return await this.managers.entryManager.putDBEntryWithLiveBaseRevision(note, baseRevision, onlyChunks);
+  }
   async getConflictedDoc(path, rev) {
     return await this.managers.conflictManager.getConflictedDoc(path, rev);
   }

package/dist/serviceModules/ServiceDatabaseFileAccessBase.d.ts

@@ -27,6 +27,7 @@ export declare class ServiceDatabaseFileAccessBase extends ServiceModuleBase<Ser
     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>;
+    storeWithLiveBaseRevision(file: UXFileInfo, baseRevision: string, 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>;

package/dist/serviceModules/ServiceDatabaseFileAccessBase.js

@@ -53,7 +53,17 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
     return await this.__store(file, force, skipCheck, false) !== false;
   }
   async storeWithBaseRevision(file, baseRevision, skipCheck) {
-    const result = await this.__store(file, true, skipCheck, false, baseRevision);
+    const result = await this.__store(file, true, skipCheck, false, {
+      mode: "force-base",
+      baseRevision
+    });
+    return result !== null && typeof result === "object" && "rev" in result ? result.rev : false;
+  }
+  async storeWithLiveBaseRevision(file, baseRevision, skipCheck) {
+    const result = await this.__store(file, true, skipCheck, false, {
+      mode: "live-base",
+      baseRevision
+    });
     return result !== null && typeof result === "object" && "rev" in result ? result.rev : false;
   }
   async storeAsConflictedRevision(file, currentRev, skipCheck) {
@@ -97,7 +107,7 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
     };
     return await this.__store(dummyUXFileInfo, true, false, false) !== false;
   }
-  async __store(file, force = false, skipCheck, onlyChunks, conflictBaseRev) {
+  async __store(file, force = false, skipCheck, onlyChunks, revisionTarget = { mode: "default" }) {
     if (!skipCheck) {
       if (!await this.checkIsTargetFile(file)) {
         return true;
@@ -148,7 +158,7 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
     };
     const msg = `STORAGE -> DB (${datatype}) `;
     const isNotChanged = await serialized("file-" + fullPath, async () => {
-      if (conflictBaseRev) {
+      if (revisionTarget.mode !== "default") {
         return false;
       }
       if (force) {
@@ -183,7 +193,15 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
       this._log(msg + " Skip " + fullPath, LOG_LEVEL_VERBOSE);
       return true;
     }
-    const ret = await this.database.localDatabase.putDBEntry(d, onlyChunks, conflictBaseRev);
+    const ret = revisionTarget.mode === "live-base" ? await this.database.localDatabase.putDBEntryWithLiveBaseRevision(
+      d,
+      revisionTarget.baseRevision,
+      onlyChunks
+    ) : await this.database.localDatabase.putDBEntry(
+      d,
+      onlyChunks,
+      revisionTarget.mode === "force-base" ? revisionTarget.baseRevision : void 0
+    );
     if (ret !== false) {
       this._log(msg + fullPath);
       this.events.emitEvent(EVENT_FILE_SAVED);

package/docs/conflict-resolution.md

@@ -80,6 +80,8 @@ The record is updated only after a successful database-to-storage reflection or
 
 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.
 
+`storeWithBaseRevision()` is the force-write primitive for deliberately preserving a branch below an exact revision, including a revision which is no longer a leaf. It must not be used when an operation means 'advance this revision only if it is still current'. For that compare-and-store boundary, `storeWithLiveBaseRevision()` uses PouchDB's ordinary revision check and returns `false` if the supplied base has already been advanced. Any current revision-tree leaf is eligible, including a non-winning conflict leaf or a logical-deletion leaf. The caller must refresh its state after refusal rather than silently falling back to the deterministic winner.
+
 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.

package/docs/development.md

@@ -59,7 +59,7 @@ The multiple-remote profile contract has focused unit coverage in `src/serviceFe
 
 The full offline scanner applies both the host's target-file policy and Commonlib's built-in `shouldBeIgnored` policy before constructing storage/database pairs. This keeps legacy LiveSync log files and flag files outside ordinary create, restore, and delete decisions even when a host accepts their file extension. Lower-level write guards remain a defence for direct calls; they are not the normal full-scan filter. The complete pair-state decision matrix and database-to-storage reflection result contract are documented in [Full offline scan](offline-scanner.md). Extend that document, the Cartesian action test, and both collection-side tests whenever the policy changes.
 
-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, short-circuiting history existence checks after an exact match, 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.
+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. `EntryManagerImpls.unit.spec.ts` owns the distinction between force-writing below an exact revision and conditionally advancing a current live leaf through PouchDB's ordinary revision check. `ServiceDatabaseFileAccessBase.unit.spec.ts` owns all-branch content discovery, short-circuiting history existence checks after an exact match, exact-revision logical deletion, and the public live-base result and event boundary. `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.
 
 `LiveSyncReplicator.unit.spec.ts` owns the CouchDB remote-chunk batch contract: a mixed `_all_docs` result must return each available document even when another keyed row reports an error. `ChunkFetcher.unit.spec.ts` owns the consumer behaviour: it writes valid returned chunks and emits `missingChunkRemote` only for requested IDs which are absent from the returned set. Extend both sides when changing remote chunk acquisition or missing-chunk delivery.
 

package/docs/proven-in-use.md

@@ -14,7 +14,7 @@ The consumer contract in `test/contracts/serviceContext.ts` checks shared result
 
 Commonlib supplies the two sleep preferences and preserves them through Setup URI encoding. Self-hosted LiveSync applies those values once at its injected bounded-activity runner, so remote operations and downloaded-document application share the same host-owned Wake Lock policy. Focused downstream tests cover the platform preference table and both activity categories; operating-system suspend behaviour remains real-platform integration evidence rather than a Commonlib guarantee.
 
-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 boolean history check stops after its first exact content match without reading an older unavailable revision, while revision enumeration still returns every match. A local edit remains a readable sibling branch when the winning body is unavailable but its exact revision and parent metadata remain, a generation-one revision without a parent is left unresolved, and 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 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 boolean history check stops after its first exact content match without reading an older unavailable revision, while revision enumeration still returns every match. A local edit remains a readable sibling branch when the winning body is unavailable but its exact revision and parent metadata remain, a generation-one revision without a parent is left unresolved, and 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. Separate live-base tests advance a selected conflict leaf or logical-deletion leaf through PouchDB's ordinary revision check, retain the other live leaf, and reject reuse of a stale base. 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. Its Document History scenario restores readable historical bytes as a new live successor and reflects that exact revision to the Vault.
 
 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.16",
+  "version": "0.1.17",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "types": "./dist/index.d.ts",