@vrtmrz/livesync-commonlib 0.1.15 → 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/replication/couchdb/LiveSyncReplicator.d.ts

@@ -1,10 +1,31 @@
 import { type EntryDoc, type RemoteDBSettings, type EntryLeaf, type SyncParameters, type DatabaseEntry, type NodeData, type RemotePreferredTweakResult } from "../../common/types.js";
 import { LiveSyncAbstractReplicator, type LiveSyncReplicatorEnv, type RemoteDBStatus } from "../LiveSyncAbstractReplicator.js";
 import type { ServiceHub } from "../../services/ServiceHub.js";
+import type { OwnedCouchDBConnection, RemoteConnectionOpenOptions } from "../../services/base/RemoteConnection.js";
+export type { OwnedCouchDBConnection, RemoteConnectionOpenOptions } from "../../services/base/RemoteConnection.js";
 export interface LiveSyncCouchDBReplicatorEnv extends LiveSyncReplicatorEnv {
     services: ServiceHub;
+    /** Internal injection point for the bounded one-shot connectivity preflight. */
+    oneShotConnectivityTimeoutMs?: number;
+}
+/**
+ * An owned CouchDB connection which has passed LiveSync's compatibility checks
+ * and carries the options required to start replication.
+ *
+ * @remarks
+ * The caller must transfer ownership or call
+ * {@link OwnedCouchDBConnection.close}.
+ * The connection retains the same `close()` implementation while compatibility
+ * checks add replication options to it.
+ */
+export interface CouchDBReplicationConnection extends OwnedCouchDBConnection<EntryDoc> {
+    /** Base options shared by finite and continuous replication. */
+    readonly syncOptionBase: PouchDB.Replication.SyncOptions;
+    /** Options selected for the requested finite or continuous replication. */
+    readonly syncOption: PouchDB.Replication.SyncOptions;
 }
 export declare class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicator {
+    env: LiveSyncCouchDBReplicatorEnv;
     isMobile(): boolean;
     constructor(env: LiveSyncCouchDBReplicatorEnv);
     getInitialSyncParameters(setting: RemoteDBSettings): Promise<SyncParameters>;
@@ -32,26 +53,28 @@ export declare class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicato
     updateMaxTransferredSeqOnChunks(localDB: PouchDB.Database, remoteID: number, seqStatusMap: Record<number, boolean>): Promise<ReturnType<typeof this.getEmptyMaxEntry>>;
     sendChunks(setting: RemoteDBSettings, remoteDB: PouchDB.Database<EntryDoc> | undefined, showResult: boolean, fromSeq?: number | string): Promise<boolean>;
     openOneShotReplication(setting: RemoteDBSettings, showResult: boolean, retrying: boolean, syncMode: "sync" | "pullOnly" | "pushOnly", ignoreCleanLock?: boolean): Promise<boolean>;
-    private closeRemoteDatabase;
-    private withRemoteDatabase;
+    private checkOneShotReplicationConnectivity;
+    private closeRemoteConnection;
+    private withRemoteConnection;
     replicateAllToServer(setting: RemoteDBSettings, showingNotice?: boolean): Promise<boolean>;
     replicateAllFromServer(setting: RemoteDBSettings, showingNotice?: boolean): Promise<boolean>;
-    checkReplicationConnectivity(setting: RemoteDBSettings, keepAlive: boolean, skipCheck: boolean, showResult: boolean, ignoreCleanLock?: boolean): Promise<false | {
-        db: PouchDB.Database<EntryDoc>;
-        info: PouchDB.Core.DatabaseInfo;
-        syncOptionBase: PouchDB.Replication.SyncOptions;
-        syncOption: PouchDB.Replication.SyncOptions;
-    }>;
+    private reportConnectivityPreflightTimeout;
+    checkReplicationConnectivity(setting: RemoteDBSettings, keepAlive: boolean, skipCheck: boolean, showResult: boolean, ignoreCleanLock?: boolean, connectionOptions?: RemoteConnectionOpenOptions): Promise<false | CouchDBReplicationConnection>;
     openContinuousReplication(setting: RemoteDBSettings, showResult: boolean, retrying: boolean): Promise<boolean>;
     closeReplication(): void;
     tryResetRemoteDatabase(setting: RemoteDBSettings): Promise<void>;
     tryCreateRemoteDatabase(setting: RemoteDBSettings): Promise<void>;
     markRemoteLocked(setting: RemoteDBSettings, locked: boolean, lockByClean: boolean): Promise<void>;
     markRemoteResolved(setting: RemoteDBSettings): Promise<void>;
-    connectRemoteCouchDBWithSetting(settings: RemoteDBSettings, isMobile: boolean, performSetup?: boolean, skipInfo?: boolean): Promise<string | {
-        db: PouchDB.Database<EntryDoc>;
-        info: PouchDB.Core.DatabaseInfo;
-    }> | "Empty passphrases cannot be used without explicit permission";
+    connectRemoteCouchDBWithSetting(settings: RemoteDBSettings, isMobile: boolean, performSetup?: boolean, skipInfo?: boolean, connectionOptions?: RemoteConnectionOpenOptions): Promise<string | OwnedCouchDBConnection<EntryDoc>> | "Empty passphrases cannot be used without explicit permission";
+    private openOwnedConnection;
+    /**
+     * Opens a raw PouchDB handle for compatibility with earlier Commonlib
+     * consumers.
+     *
+     * @deprecated Use {@link connectRemoteCouchDBWithSetting} and close the
+     * complete owned connection after use.
+     */
     _ensureConnection<T extends DatabaseEntry>(settings: RemoteDBSettings, performSetup?: boolean): Promise<PouchDB.Database<T>>;
     /**
      * Fetch a document from the remote database directly.

package/dist/replication/couchdb/LiveSyncReplicator.js

@@ -41,12 +41,20 @@ import {
   SyncParamsNotFoundError,
   SyncParamsUpdateError
 } from "../SyncParamsHandler.js";
+import { compatGlobal } from "../../common/coreEnvFunctions.js";
 const currentVersionRange = {
   min: 0,
   max: 2400,
   current: 2
 };
 const selectorOnDemandPull = { selector: { type: { $ne: "leaf" } } };
+const DEFAULT_ONE_SHOT_CONNECTIVITY_TIMEOUT_MS = 6e4;
+class OneShotConnectivityPreflightTimeoutError extends Error {
+  constructor(timeoutMs) {
+    super(`Remote connectivity preflight exceeded ${timeoutMs} ms.`);
+    this.name = "OneShotConnectivityPreflightTimeoutError";
+  }
+}
 async function* genReplication(s, signal) {
   const inbox = new StreamInbox({ capacity: 1e4 });
   const push = function(e) {
@@ -379,11 +387,11 @@ class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicator {
         );
         return false;
       }
-      return await this.withRemoteDatabase(d.db, async (db) => this.sendChunks(setting, db, showResult, fromSeq));
+      return await this.withRemoteConnection(d, async (db) => this.sendChunks(setting, db, showResult, fromSeq));
     }
     const connectivity = await this.checkReplicationConnectivity(setting, false, false, false, false);
     if (connectivity !== false) {
-      await this.closeRemoteDatabase(connectivity.db);
+      await this.closeRemoteConnection(connectivity);
     }
     Logger(`Bulk sending chunks to remote database...`, showResult ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO, "fetch");
     const remoteMilestone = await remoteDB.get(MILESTONE_DOCID);
@@ -534,7 +542,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       }
       const localDB = this.rawDatabase;
       Logger(this.translate("liveSyncReplicator.oneShotSyncBegin", { syncMode }));
-      const ret = await this.checkReplicationConnectivity(setting, false, retrying, showResult, ignoreCleanLock);
+      const ret = await this.checkOneShotReplicationConnectivity(setting, retrying, showResult, ignoreCleanLock);
       if (ret === false) {
         Logger(
           this.translate("liveSyncReplicator.couldNotConnectToServer"),
@@ -613,7 +621,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
         }
         return false;
       } finally {
-        await this.closeRemoteDatabase(db);
+        await this.closeRemoteConnection(ret);
       }
     });
     if (typeof next === "boolean") {
@@ -621,21 +629,38 @@ ${sendingDocs}/(${sentDocsCount} done)`,
     }
     return await next();
   }
-  // One-shot attempts own their temporary remote handle. Continuous replication
-  // keeps its handle until the replication controller terminates it.
-  async closeRemoteDatabase(db) {
+  async checkOneShotReplicationConnectivity(setting, skipCheck, showResult, ignoreCleanLock) {
+    if (setting.useRequestAPI) {
+      return await this.checkReplicationConnectivity(setting, false, skipCheck, showResult, ignoreCleanLock);
+    }
+    const timeoutMs = this.env.oneShotConnectivityTimeoutMs ?? DEFAULT_ONE_SHOT_CONNECTIVITY_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timeout = compatGlobal.setTimeout(
+      () => controller.abort(new OneShotConnectivityPreflightTimeoutError(timeoutMs)),
+      timeoutMs
+    );
+    try {
+      return await this.checkReplicationConnectivity(setting, false, skipCheck, showResult, ignoreCleanLock, {
+        signal: controller.signal,
+        allowNativeFallback: false
+      });
+    } finally {
+      compatGlobal.clearTimeout(timeout);
+    }
+  }
+  async closeRemoteConnection(connection) {
     try {
-      await db.close();
+      await connection.close();
     } catch (ex) {
       Logger("Failed to close remote database.", LOG_LEVEL_INFO, "sync");
       Logger(ex, LOG_LEVEL_VERBOSE, "sync");
     }
   }
-  async withRemoteDatabase(db, task) {
+  async withRemoteConnection(connection, task) {
     try {
-      return await task(db);
+      return await task(connection.db);
     } finally {
-      await this.closeRemoteDatabase(db);
+      await this.closeRemoteConnection(connection);
     }
   }
   replicateAllToServer(setting, showingNotice) {
@@ -644,7 +669,17 @@ ${sendingDocs}/(${sentDocsCount} done)`,
   replicateAllFromServer(setting, showingNotice) {
     return this.openOneShotReplication(setting, showingNotice ?? false, false, "pullOnly");
   }
-  async checkReplicationConnectivity(setting, keepAlive, skipCheck, showResult, ignoreCleanLock = false) {
+  reportConnectivityPreflightTimeout(connectionOptions, showResult, error) {
+    if (!connectionOptions?.signal?.aborted || !(connectionOptions.signal.reason instanceof OneShotConnectivityPreflightTimeoutError)) {
+      return false;
+    }
+    Logger("The remote connectivity check timed out.", showResult ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO, "sync");
+    if (error !== void 0) {
+      Logger(error, LOG_LEVEL_VERBOSE, "sync");
+    }
+    return true;
+  }
+  async checkReplicationConnectivity(setting, keepAlive, skipCheck, showResult, ignoreCleanLock = false, connectionOptions) {
     if (setting.versionUpFlash != "") {
       Logger(this.translate("Replicator.Message.VersionUpFlash"), LOG_LEVEL_NOTICE);
       return false;
@@ -654,8 +689,25 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       Logger("Another replication running.");
       return false;
     }
-    const dbRet = await this.connectRemoteCouchDBWithSetting(setting, this.isMobile(), true);
+    let dbRet;
+    try {
+      dbRet = await this.connectRemoteCouchDBWithSetting(
+        setting,
+        this.isMobile(),
+        true,
+        false,
+        connectionOptions
+      );
+    } catch (ex) {
+      if (this.reportConnectivityPreflightTimeout(connectionOptions, showResult, ex)) {
+        return false;
+      }
+      throw ex;
+    }
     if (typeof dbRet === "string") {
+      if (this.reportConnectivityPreflightTimeout(connectionOptions, showResult)) {
+        return false;
+      }
       Logger(
         this.translate("liveSyncReplicator.couldNotConnectToURI", { uri, dbRet }),
         showResult ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO
@@ -734,13 +786,25 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       if (setting.readChunksOnline) {
         syncOptionBase.pull = { ...selectorOnDemandPull };
       }
+      if (this.reportConnectivityPreflightTimeout(connectionOptions, showResult)) {
+        return false;
+      }
       const syncOption = keepAlive ? { live: true, retry: true, heartbeat: setting.useTimeouts ? false : 3e4, ...syncOptionBase } : { ...syncOptionBase };
-      const connection = { db: dbRet.db, info: dbRet.info, syncOptionBase, syncOption };
+      const connection = {
+        ...dbRet,
+        syncOptionBase,
+        syncOption
+      };
       ownershipTransferred = true;
       return connection;
+    } catch (ex) {
+      if (this.reportConnectivityPreflightTimeout(connectionOptions, showResult, ex)) {
+        return false;
+      }
+      throw ex;
     } finally {
       if (!ownershipTransferred) {
-        await this.closeRemoteDatabase(dbRet.db);
+        await this.closeRemoteConnection(dbRet);
       }
     }
   }
@@ -828,7 +892,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
             }
           }
         } finally {
-          await this.closeRemoteDatabase(db);
+          await this.closeRemoteConnection(ret);
         }
       }
       return false;
@@ -862,7 +926,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
         Logger(ex, LOG_LEVEL_NOTICE);
       }
     } finally {
-      await this.closeRemoteDatabase(con.db);
+      await this.closeRemoteConnection(con);
     }
     clearHandlers();
     await this.ensurePBKDF2Salt(setting, true, false);
@@ -871,7 +935,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
     this.closeReplication();
     const con2 = await this.connectRemoteCouchDBWithSetting(setting, this.isMobile(), true);
     if (typeof con2 === "string") return;
-    await this.closeRemoteDatabase(con2.db);
+    await this.closeRemoteConnection(con2);
     clearHandlers();
     await this.ensurePBKDF2Salt(setting, true, false);
     Logger(this.translate("liveSyncReplicator.remoteDbCreatedOrConnected"), LOG_LEVEL_NOTICE);
@@ -883,7 +947,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       Logger(this.translate("liveSyncReplicator.couldNotConnectToURI", { uri, dbRet }), LOG_LEVEL_NOTICE);
       return;
     }
-    await this.withRemoteDatabase(dbRet.db, async (db) => {
+    await this.withRemoteConnection(dbRet, async (db) => {
       if (!await checkRemoteVersion(db, this.migrate.bind(this), VER)) {
         Logger(this.translate("liveSyncReplicator.remoteDbCorrupted"), LOG_LEVEL_NOTICE);
         return;
@@ -922,7 +986,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       Logger(this.translate("liveSyncReplicator.couldNotConnectToURI", { uri, dbRet }), LOG_LEVEL_NOTICE);
       return;
     }
-    await this.withRemoteDatabase(dbRet.db, async (db) => {
+    await this.withRemoteConnection(dbRet, async (db) => {
       if (!await checkRemoteVersion(db, this.migrate.bind(this), VER)) {
         Logger(this.translate("liveSyncReplicator.remoteDbCorrupted"), LOG_LEVEL_NOTICE);
         return;
@@ -952,7 +1016,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       }
     });
   }
-  connectRemoteCouchDBWithSetting(settings, isMobile, performSetup = false, skipInfo = false) {
+  connectRemoteCouchDBWithSetting(settings, isMobile, performSetup = false, skipInfo = false, connectionOptions) {
     if (settings.encrypt && settings.passphrase == "" && !settings.permitEmptyPassphrase) {
       return "Empty passphrases cannot be used without explicit permission";
     }
@@ -980,15 +1044,26 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       settings.enableCompression,
       customHeaders,
       settings.useRequestAPI,
-      async () => await this.getReplicationPBKDF2Salt(settings)
+      async () => await this.getReplicationPBKDF2Salt(settings),
+      connectionOptions
     );
   }
-  async _ensureConnection(settings, performSetup = false) {
+  async openOwnedConnection(settings, performSetup = false) {
     const ret = await this.connectRemoteCouchDBWithSetting(settings, this.isMobile(), performSetup, true);
     if (typeof ret === "string") {
       throw new Error(`${this.translate("liveSyncReplicator.couldNotConnectToServer")}:${ret}`);
     }
-    return ret.db;
+    return ret;
+  }
+  /**
+   * Opens a raw PouchDB handle for compatibility with earlier Commonlib
+   * consumers.
+   *
+   * @deprecated Use {@link connectRemoteCouchDBWithSetting} and close the
+   * complete owned connection after use.
+   */
+  async _ensureConnection(settings, performSetup = false) {
+    return (await this.openOwnedConnection(settings, performSetup)).db;
   }
   /**
    * Fetch a document from the remote database directly.
@@ -999,8 +1074,8 @@ ${sendingDocs}/(${sentDocsCount} done)`,
    * @throws {Error} Other errors that may occur during the fetch operation.
    */
   async fetchRemoteDocument(settings, id, db) {
-    const ownsConnection = db === void 0;
-    const connDB = db ?? await this._ensureConnection(settings);
+    const connection = db === void 0 ? await this.openOwnedConnection(settings) : void 0;
+    const connDB = db ?? connection.db;
     try {
       return await connDB.get(id);
     } catch (ex) {
@@ -1009,8 +1084,8 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       }
       throw ex;
     } finally {
-      if (ownsConnection) {
-        await this.closeRemoteDatabase(connDB);
+      if (connection) {
+        await this.closeRemoteConnection(connection);
       }
     }
   }
@@ -1023,13 +1098,13 @@ ${sendingDocs}/(${sentDocsCount} done)`,
    * @throws {Error} If the document could not be put.
    */
   async putRemoteDocument(settings, doc, db) {
-    const ownsConnection = db === void 0;
-    const connDB = db ?? await this._ensureConnection(settings, true);
+    const connection = db === void 0 ? await this.openOwnedConnection(settings, true) : void 0;
+    const connDB = db ?? connection.db;
     try {
       return await connDB.put(doc);
     } finally {
-      if (ownsConnection) {
-        await this.closeRemoteDatabase(connDB);
+      if (connection) {
+        await this.closeRemoteConnection(connection);
       }
     }
   }
@@ -1043,7 +1118,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       );
       return false;
     }
-    return await this.withRemoteDatabase(ret.db, async (db) => {
+    return await this.withRemoteConnection(ret, async (db) => {
       const remoteChunks = await db.allDocs({ keys: missingChunks, include_docs: true });
       const errorRows = remoteChunks.rows.filter((e) => "error" in e);
       if (errorRows.length > 0) {
@@ -1074,7 +1149,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       );
       return false;
     }
-    return await this.withRemoteDatabase(db.db, async () => {
+    return await this.withRemoteConnection(db, async () => {
       Logger(`Connected to ${db.info.db_name} successfully`, LOG_LEVEL_NOTICE);
       return true;
     });
@@ -1086,7 +1161,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       Logger(this.translate("liveSyncReplicator.couldNotConnectToURI", { uri, dbRet }), LOG_LEVEL_NOTICE);
       return;
     }
-    await this.withRemoteDatabase(dbRet.db, async (db) => {
+    await this.withRemoteConnection(dbRet, async (db) => {
       if (!await checkRemoteVersion(db, this.migrate.bind(this), VER)) {
         Logger(this.translate("liveSyncReplicator.remoteDbCorrupted"), LOG_LEVEL_NOTICE);
         return;
@@ -1109,7 +1184,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       Logger(this.translate("liveSyncReplicator.couldNotConnectToURI", { uri, dbRet }), LOG_LEVEL_NOTICE);
       return;
     }
-    await this.withRemoteDatabase(dbRet.db, async (db) => {
+    await this.withRemoteConnection(dbRet, async (db) => {
       if (!await checkRemoteVersion(db, this.migrate.bind(this), VER)) {
         Logger(this.translate("liveSyncReplicator.remoteDbCorrupted"), LOG_LEVEL_NOTICE);
         return;
@@ -1145,7 +1220,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
         error: new Error(dbRet)
       };
     }
-    return await this.withRemoteDatabase(dbRet.db, async (db) => {
+    return await this.withRemoteConnection(dbRet, async (db) => {
       try {
         if (!await checkRemoteVersion(db, this.migrate.bind(this), VER)) {
           const error = new Error("The remote database version is not compatible");
@@ -1205,7 +1280,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       Logger(this.translate("liveSyncReplicator.couldNotConnectToURI", { uri, dbRet }), LOG_LEVEL_NOTICE);
       return false;
     }
-    return await this.withRemoteDatabase(dbRet.db, async (db) => (await db.compact({ interval: 1e3 })).ok);
+    return await this.withRemoteConnection(dbRet, async (db) => (await db.compact({ interval: 1e3 })).ok);
   }
   async getRemoteStatus(setting) {
     const dbRet = await this.connectRemoteCouchDBWithSetting(setting, this.isMobile(), true);
@@ -1214,7 +1289,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       Logger(this.translate("liveSyncReplicator.couldNotConnectToURI", { uri, dbRet }), LOG_LEVEL_NOTICE);
       return false;
     }
-    return await this.withRemoteDatabase(dbRet.db, async (db) => {
+    return await this.withRemoteConnection(dbRet, async (db) => {
       const info = await db.info();
       return {
         ...info,
@@ -1229,7 +1304,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       Logger(this.translate("liveSyncReplicator.couldNotConnectToURI", { uri, dbRet }), LOG_LEVEL_NOTICE);
       return false;
     }
-    return await this.withRemoteDatabase(dbRet.db, countCompromisedChunks);
+    return await this.withRemoteConnection(dbRet, countCompromisedChunks);
   }
   async getConnectedDeviceList(setting = this.currentSettings) {
     const dbRet = await this.connectRemoteCouchDBWithSetting(setting, this.isMobile(), true);
@@ -1238,7 +1313,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       Logger(this.translate("liveSyncReplicator.couldNotConnectToURI", { uri, dbRet }), LOG_LEVEL_NOTICE);
       return false;
     }
-    return await this.withRemoteDatabase(dbRet.db, async (db) => {
+    return await this.withRemoteConnection(dbRet, async (db) => {
       const milestoneDoc = await db.get(MILESTONE_DOCID);
       if (!milestoneDoc) {
         Logger("Could not retrieve remote milestone", LOG_LEVEL_NOTICE);

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/dist/services/base/IService.d.ts

@@ -11,6 +11,7 @@ import type { ReplicatorService } from "./ReplicatorService.js";
 import type { DatabaseEventService } from "./DatabaseEventService.js";
 import type { BASE_IS_NEW, EVEN, TARGET_IS_NEW } from "../../common/models/shared.const.symbols.js";
 import type { AsyncActivityOptions } from "../../interfaces/AsyncActivityRunner.js";
+import type { OwnedCouchDBConnection, RemoteConnectionOpenOptions } from "./RemoteConnection.js";
 declare global {
     interface OPTIONAL_SYNC_FEATURES {
         DISABLE: "DISABLE";
@@ -135,10 +136,23 @@ export interface IReplicationService {
     markResolved(): Promise<void>;
 }
 export interface IRemoteService {
-    connect(uri: string, auth: CouchDBCredentials, disableRequestURI: boolean, passphrase: string | false, useDynamicIterationCount: boolean, performSetup: boolean, skipInfo: boolean, compression: boolean, customHeaders: Record<string, string>, useRequestAPI: boolean, getPBKDF2Salt: () => Promise<Uint8Array<ArrayBuffer>>): Promise<string | {
-        db: PouchDB.Database<EntryDoc>;
-        info: PouchDB.Core.DatabaseInfo;
-    }>;
+    /**
+     * Opens an owned remote CouchDB connection.
+     *
+     * @remarks
+     * The caller must transfer ownership or call `close()` on the returned
+     * connection. Closing it aborts outstanding abort-capable requests before
+     * closing the PouchDB handle. Host-native request adapters may not honour
+     * `AbortSignal`; callers must not report those requests as cancelled without
+     * a host guarantee.
+     *
+     * @returns An error description, or an owned remote connection. When
+     * `skipInfo` is true, the `info` field retains its compatibility placeholder.
+     *
+     * @throws When PouchDB construction or local connection configuration fails
+     * before a connection result can be produced.
+     */
+    connect(uri: string, auth: CouchDBCredentials, disableRequestURI: boolean, passphrase: string | false, useDynamicIterationCount: boolean, performSetup: boolean, skipInfo: boolean, compression: boolean, customHeaders: Record<string, string>, useRequestAPI: boolean, getPBKDF2Salt: () => Promise<Uint8Array<ArrayBuffer>>, options?: RemoteConnectionOpenOptions): Promise<string | OwnedCouchDBConnection<EntryDoc>>;
     /**
      * State if the last POST request failed due to payload size.
      */

package/dist/services/base/RemoteConnection.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Options which bind requests made through a remote CouchDB connection to the
+ * operation which owns it.
+ */
+export interface RemoteConnectionOpenOptions {
+    /**
+     * Cancels abort-capable requests made through the connection when the
+     * owning operation is cancelled.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * Allows the diagnostic fallback to a host-native request API after a
+     * web-compatible request reports a network `TypeError`.
+     *
+     * Set this to `false` when the owner must retain an abortable request path.
+     * A host-native adapter is not assumed to honour `AbortSignal`.
+     */
+    readonly allowNativeFallback?: boolean;
+}
+/**
+ * A remote PouchDB handle together with the lifecycle of requests created
+ * through that handle.
+ *
+ * @remarks
+ * The caller owns this connection and must call
+ * {@link OwnedCouchDBConnection.close} when ownership is not transferred.
+ * `close()` is idempotent: it first cancels abort-capable requests within this
+ * connection, then closes the PouchDB handle. Closing the PouchDB handle retains
+ * its normal `closed` event behaviour. This contract does not imply exclusive
+ * ownership of a physical HTTP socket.
+ *
+ * @typeParam T - The document type stored in the remote database.
+ */
+export interface OwnedCouchDBConnection<T extends object> {
+    /** The remote PouchDB database handle. */
+    readonly db: PouchDB.Database<T>;
+    /**
+     * The database information read while opening the connection. When the
+     * caller skips that read, compatibility placeholders are returned.
+     */
+    readonly info: PouchDB.Core.DatabaseInfo;
+    /** Cancels scoped requests and closes the PouchDB handle exactly once. */
+    close(): Promise<void>;
+}

package/dist/services/base/RemoteService.d.ts

@@ -9,6 +9,7 @@ import type { SettingService } from "./SettingService.js";
 import { UnresolvedErrorManager } from "./UnresolvedErrorManager.js";
 import { type LogFunction } from "../lib/logUtils.js";
 import type { PouchDBConstructor } from "../../pouchdb/PouchDBConstructor.js";
+import type { OwnedCouchDBConnection, RemoteConnectionOpenOptions } from "./RemoteConnection.js";
 export interface RemoteServiceDependencies {
     /** PouchDB with the HTTP adapter required by the host runtime already registered. */
     pouchDB: PouchDBConstructor;
@@ -25,21 +26,6 @@ type FetchMethod = (typeof FetchMethod)[keyof typeof FetchMethod];
  * The RemoteService provides methods for interacting with the remote database.
  */
 export declare abstract class RemoteService<T extends ServiceContext = ServiceContext> extends ServiceBase<T> implements IRemoteService {
-    /**
-     * Connect to the remote database with the provided settings.
-     * @param uri  The URI of the remote database.
-     * @param auth  The authentication credentials for the remote database.
-     * @param disableRequestURI  Whether to disable the request URI.
-     * @param passphrase  The passphrase for the remote database.
-     * @param useDynamicIterationCount  Whether to use dynamic iteration count.
-     * @param performSetup  Whether to perform setup.
-     * @param skipInfo  Whether to skip information retrieval.
-     * @param compression  Whether to enable compression.
-     * @param customHeaders  Custom headers to include in the request.
-     * @param useRequestAPI  Whether to use the request API.
-     * @param getPBKDF2Salt  Function to retrieve the PBKDF2 salt.
-     * Note that this function is used for CouchDB and compatible only.
-     */
     protected _log: LogFunction;
     protected _authHeader: AuthorizationHeaderGenerator;
     protected _APIService: APIService;
@@ -53,9 +39,27 @@ export declare abstract class RemoteService<T extends ServiceContext = ServiceCo
     showError(msg: string, max_log_level?: LOG_LEVEL): void;
     clearErrors(): void;
     performFetch(req: string | Request, opts?: RequestInit, fetchMethod?: FetchMethod): Promise<Response>;
-    connect(uri: string, auth: CouchDBCredentials, disableRequestURI: boolean, passphrase: string | false, useDynamicIterationCount: boolean, performSetup: boolean, skipInfo: boolean, compression: boolean, customHeaders: Record<string, string>, useRequestAPI: boolean, getPBKDF2Salt: () => Promise<Uint8Array<ArrayBuffer>>): Promise<string | {
-        db: PouchDB.Database<EntryDoc>;
-        info: PouchDB.Core.DatabaseInfo;
-    }>;
+    /**
+     * Opens a remote CouchDB connection with request cancellation bound to its
+     * owner.
+     *
+     * @param uri - The URI of the remote database.
+     * @param auth - Authentication credentials for the remote database.
+     * @param disableRequestURI - Whether request URI handling is disabled.
+     * @param passphrase - The database encryption passphrase, or `false` when
+     * encryption is disabled.
+     * @param useDynamicIterationCount - Whether legacy dynamic iteration counts
+     * are enabled.
+     * @param performSetup - Whether PouchDB may set up a missing database.
+     * @param skipInfo - Whether to omit the opening database information request.
+     * @param compression - Whether chunk compression is enabled.
+     * @param customHeaders - Additional HTTP headers for every request.
+     * @param useRequestAPI - Whether to use the host-native request adapter.
+     * @param getPBKDF2Salt - Resolves the PBKDF2 salt when encryption needs it.
+     * @param connectionOptions - Ownership and request fallback options.
+     * @returns An error description, or the owned connection. The caller must
+     * transfer ownership or call `close()`.
+     */
+    connect(uri: string, auth: CouchDBCredentials, disableRequestURI: boolean, passphrase: string | false, useDynamicIterationCount: boolean, performSetup: boolean, skipInfo: boolean, compression: boolean, customHeaders: Record<string, string>, useRequestAPI: boolean, getPBKDF2Salt: () => Promise<Uint8Array<ArrayBuffer>>, connectionOptions?: RemoteConnectionOpenOptions): Promise<string | OwnedCouchDBConnection<EntryDoc>>;
 }
 export {};

package/dist/services/base/RemoteService.js

@@ -13,26 +13,84 @@ import { UnresolvedErrorManager } from "./UnresolvedErrorManager.js";
 import { createInstanceLogFunction, MARK_LOG_NETWORK_ERROR } from "../lib/logUtils.js";
 import { runWithTrackedPhysicalRequest } from "../lib/remoteActivity.js";
 import { LiveSyncError } from "../../common/LSError.js";
+function createRemoteConnectionScope(ownerSignal) {
+  const controller = new AbortController();
+  const combinedSignals = /* @__PURE__ */ new WeakMap();
+  let detachOwner = () => {
+  };
+  const abort = (reason) => {
+    detachOwner();
+    if (!controller.signal.aborted) {
+      controller.abort(reason);
+    }
+  };
+  if (ownerSignal?.aborted) {
+    abort(ownerSignal.reason);
+  } else if (ownerSignal) {
+    const onOwnerAbort = () => abort(ownerSignal.reason);
+    ownerSignal.addEventListener("abort", onOwnerAbort, { once: true });
+    detachOwner = () => ownerSignal.removeEventListener("abort", onOwnerAbort);
+  }
+  const combine = (signal) => {
+    if (!signal || signal === controller.signal) return controller.signal;
+    const cached = combinedSignals.get(signal);
+    if (cached) return cached;
+    const combined = combineAbortSignals(signal, controller.signal);
+    combinedSignals.set(signal, combined);
+    return combined;
+  };
+  return { signal: controller.signal, combine, abort };
+}
+function combineAbortSignals(first, second) {
+  if (first === second) return first;
+  const abortSignalWithAny = AbortSignal;
+  if (typeof abortSignalWithAny.any === "function") {
+    return abortSignalWithAny.any([first, second]);
+  }
+  const controller = new AbortController();
+  const listeners = /* @__PURE__ */ new Map();
+  const detach = () => {
+    for (const [signal, listener] of listeners) {
+      signal.removeEventListener("abort", listener);
+    }
+    listeners.clear();
+  };
+  const abortFrom = (signal) => {
+    detach();
+    if (!controller.signal.aborted) {
+      controller.abort(signal.reason);
+    }
+  };
+  for (const signal of [first, second]) {
+    if (signal.aborted) {
+      abortFrom(signal);
+      break;
+    }
+    const listener = () => abortFrom(signal);
+    listeners.set(signal, listener);
+    signal.addEventListener("abort", listener, { once: true });
+  }
+  return controller.signal;
+}
+function createCouchDBConnection(db, info, scope) {
+  let closePromise;
+  return {
+    db,
+    info,
+    close: () => {
+      closePromise ??= (async () => {
+        scope.abort(new Error("Remote connection closed."));
+        await db.close();
+      })();
+      return closePromise;
+    }
+  };
+}
 const FetchMethod = {
   webCompat: 0,
   native: 1
 };
 class RemoteService extends ServiceBase {
-  /**
-   * Connect to the remote database with the provided settings.
-   * @param uri  The URI of the remote database.
-   * @param auth  The authentication credentials for the remote database.
-   * @param disableRequestURI  Whether to disable the request URI.
-   * @param passphrase  The passphrase for the remote database.
-   * @param useDynamicIterationCount  Whether to use dynamic iteration count.
-   * @param performSetup  Whether to perform setup.
-   * @param skipInfo  Whether to skip information retrieval.
-   * @param compression  Whether to enable compression.
-   * @param customHeaders  Custom headers to include in the request.
-   * @param useRequestAPI  Whether to use the request API.
-   * @param getPBKDF2Salt  Function to retrieve the PBKDF2 salt.
-   * Note that this function is used for CouchDB and compatible only.
-   */
   _log;
   _authHeader = new AuthorizationHeaderGenerator();
   _APIService;
@@ -101,13 +159,35 @@ class RemoteService extends ServiceBase {
       return response;
     });
   }
-  async connect(uri, auth, disableRequestURI, passphrase, useDynamicIterationCount, performSetup, skipInfo, compression, customHeaders, useRequestAPI, getPBKDF2Salt) {
+  /**
+   * Opens a remote CouchDB connection with request cancellation bound to its
+   * owner.
+   *
+   * @param uri - The URI of the remote database.
+   * @param auth - Authentication credentials for the remote database.
+   * @param disableRequestURI - Whether request URI handling is disabled.
+   * @param passphrase - The database encryption passphrase, or `false` when
+   * encryption is disabled.
+   * @param useDynamicIterationCount - Whether legacy dynamic iteration counts
+   * are enabled.
+   * @param performSetup - Whether PouchDB may set up a missing database.
+   * @param skipInfo - Whether to omit the opening database information request.
+   * @param compression - Whether chunk compression is enabled.
+   * @param customHeaders - Additional HTTP headers for every request.
+   * @param useRequestAPI - Whether to use the host-native request adapter.
+   * @param getPBKDF2Salt - Resolves the PBKDF2 salt when encryption needs it.
+   * @param connectionOptions - Ownership and request fallback options.
+   * @returns An error description, or the owned connection. The caller must
+   * transfer ownership or call `close()`.
+   */
+  async connect(uri, auth, disableRequestURI, passphrase, useDynamicIterationCount, performSetup, skipInfo, compression, customHeaders, useRequestAPI, getPBKDF2Salt, connectionOptions = {}) {
     if (!isValidRemoteCouchDBURI(uri)) return "Remote URI is not valid";
     if (uri.toLowerCase() != uri) return "Remote URI and database name could not contain capital letters.";
     if (uri.indexOf(" ") !== -1) return "Remote URI and database name could not contain spaces.";
     if (!this._APIService.isOnline) {
       return "Network is offline";
     }
+    const connectionScope = createRemoteConnectionScope(connectionOptions.signal);
     const conf = {
       adapter: "http",
       auth: "username" in auth ? auth : void 0,
@@ -143,14 +223,18 @@ class RemoteService extends ServiceBase {
             headers.append("authorization", authHeader);
           }
           try {
+            const signal = connectionScope.combine(opts?.signal);
             const response = await this.performFetch(
               requestSrc,
-              { ...opts, headers },
+              { ...opts, headers, signal },
               useRequestAPI ? FetchMethod.native : FetchMethod.webCompat
             );
             return response;
           } catch (ex) {
             if (ex instanceof TypeError) {
+              if (connectionScope.signal.aborted || connectionOptions.allowNativeFallback === false) {
+                throw ex;
+              }
               if (useRequestAPI) {
                 this._log("Failed to request by API.");
                 throw ex;
@@ -176,7 +260,12 @@ class RemoteService extends ServiceBase {
         } catch (ex) {
           this._log(`HTTP:${method}${size} to:${localURL} -> failed`, LOG_LEVEL_VERBOSE);
           const msg = ex instanceof Error ? `${ex?.name}:${ex?.message}` : ex?.toString();
-          this.showError(`${MARK_LOG_NETWORK_ERROR}Network Error: Failed to fetch: ${msg}`, LOG_LEVEL_INFO);
+          if (!connectionScope.signal.aborted) {
+            this.showError(
+              `${MARK_LOG_NETWORK_ERROR}Network Error: Failed to fetch: ${msg}`,
+              LOG_LEVEL_INFO
+            );
+          }
           this._log(ex, LOG_LEVEL_VERBOSE);
           if (url.toString().indexOf("_bulk_docs") !== -1) {
             this.last_successful_post = false;
@@ -187,28 +276,44 @@ class RemoteService extends ServiceBase {
       }
     };
     const setting = this._settingService.currentSettings();
-    const db = new this._pouchDB(uri, conf);
-    replicationFilter(db, compression);
-    disableEncryption();
-    if (passphrase !== "false" && typeof passphrase === "string") {
-      enableEncryption(db, passphrase, useDynamicIterationCount, false, getPBKDF2Salt, setting.E2EEAlgorithm);
+    let db;
+    try {
+      db = new this._pouchDB(uri, conf);
+    } catch (ex) {
+      connectionScope.abort(ex);
+      throw ex;
+    }
+    const compatibilityInfo = { db_name: "", doc_count: 0, update_seq: "" };
+    const connection = createCouchDBConnection(db, compatibilityInfo, connectionScope);
+    const closeAfterConnectionFailure = async () => {
+      try {
+        await connection.close();
+      } catch (closeError) {
+        this._log("Failed to close remote database after connection failure.", LOG_LEVEL_INFO);
+        this._log(closeError, LOG_LEVEL_VERBOSE);
+      }
+    };
+    try {
+      replicationFilter(db, compression);
+      disableEncryption();
+      if (passphrase !== "false" && typeof passphrase === "string") {
+        enableEncryption(db, passphrase, useDynamicIterationCount, false, getPBKDF2Salt, setting.E2EEAlgorithm);
+      }
+    } catch (ex) {
+      await closeAfterConnectionFailure();
+      throw ex;
     }
     if (skipInfo) {
-      return { db, info: { db_name: "", doc_count: 0, update_seq: "" } };
+      return connection;
     }
     try {
       const info = await db.info();
-      return { db, info };
+      return { ...connection, info };
     } catch (ex) {
       const exMsg = ex instanceof Error ? ex : LiveSyncError.fromError(ex);
       const msg = `${exMsg.name}:${exMsg.message}`;
       this._log(ex, LOG_LEVEL_VERBOSE);
-      try {
-        await db.close();
-      } catch (closeError) {
-        this._log("Failed to close remote database after connection failure.", LOG_LEVEL_INFO);
-        this._log(closeError, LOG_LEVEL_VERBOSE);
-      }
+      await closeAfterConnectionFailure();
       return msg;
     }
   }

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,10 +59,14 @@ 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.
 
+`RemoteService.connect()` returns an owned CouchDB connection as the existing flat `{ db, info }` result with an idempotent `close()` method. `close()` first aborts outstanding abort-capable requests in that connection, then closes the PouchDB handle. The owner must transfer or close the complete connection; passing only `db` loses the cancellation boundary. A skipped information request retains the established placeholder in `info` for compatibility. `OwnedCouchDBConnection`, its opening options, and the checked `CouchDBReplicationConnection` are Commonlib-owned types exported by the existing CouchDB replicator module. The legacy `_ensureConnection()` helper continues to return a raw PouchDB handle for source compatibility; new Commonlib code must retain and close the complete owned connection instead.
+
+The one-shot CouchDB connectivity preflight is the first bounded consumer. It applies an internal 60-second safety fuse to the complete preflight on the web-compatible fetch path, disables fallback into the non-abortable native request adapter, and clears the fuse before transferring the connection to replication. The fuse is a last-resort wall-clock bound on an owner which would otherwise remain pending indefinitely; it is not the expected completion time, a per-request inactivity timeout, a user setting, or the `useTimeouts` changes-feed setting. The explicitly selected native Request API retains its previous unbounded behaviour because its current host adapter cannot honour `AbortSignal`. Extend `RemoteService.unit.spec.ts` and the one-shot ownership table in `LiveSyncReplicator.unit.spec.ts` when changing this boundary. Do not use `Promise.race()` to report a mutating native request as cancelled while it can still complete remotely.
+
 `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.
 
 ### P2P composition ownership

package/docs/proven-in-use.md

@@ -14,12 +14,14 @@ 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.
 
 Commonlib's injected CouchDB tests verify that a mixed remote chunk batch preserves available documents when another requested ID is absent. Its chunk-delivery tests separately verify that available chunks reach local storage and only absent IDs are marked unavailable. Self-hosted LiveSync supplies the real CouchDB connection and start-up composition, so device-specific replication timing remains downstream integration evidence rather than Commonlib unit coverage.
 
+Commonlib's injected remote-service tests verify that an owning operation can abort a pending CouchDB request, that closing the flat connection interrupts a response body which is already being consumed, that repeated closure closes PouchDB once, and that a bounded request does not fall back into the non-abortable native adapter. Its one-shot replicator tests verify deadline expiry, distinct timeout reporting, cleanup before release of the shared attempt, later invocation, successful ownership transfer, and the unchanged native-request boundary. Self-hosted LiveSync still supplies the actual Obsidian fetch adapters and real CouchDB environment; confirmation on the reporter's platform remains downstream evidence rather than a Commonlib guarantee.
+
 Commonlib's remote-preference result contract distinguishes available synchronisation settings, a remote which has not stored those settings yet, a failed read, and a remote type which does not support central preferences. Focused CouchDB and Object Storage tests cover absent milestone data separately from transport failures, while Self-hosted LiveSync owns the initialisation choices, cancellation policy, and user-facing explanation.
 
 Commonlib's full offline scanner distinguishes completed, deliberately skipped, and failed storage/database pairs. Before pair construction, it withholds Metadata whose actual document ID disagrees with its recorded path, without reflection, deletion, or last-seen side effects. A consistently addressed entry for the same logical path continues through the established path-based flow; only a path without such an entry also withholds storage processing. The read-only actual-ID Inspector and separately invoked one-entry repair retain ambiguous states for review, revalidate an exact source revision, verify a target-first copy, and preserve the source on failure. Self-hosted LiveSync keeps the existing Fast Setup aggregate policy and owns confirmation and presentation in its file/database repair interface.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "types": "./dist/index.d.ts",