@vrtmrz/livesync-commonlib 0.1.17 → 0.1.19-rc.0

package/dist/pouchdb/LiveSyncLocalDB.js

@@ -37,16 +37,14 @@ class LiveSyncLocalDB {
   async _prepareHashFunctions() {
     await this._managers?.prepareHashFunction();
   }
-  onunload() {
-    void this.env.services.databaseEvents.onUnloadDatabase(this);
-    this.localDatabase.removeAllListeners();
-  }
   refreshSettings() {
     const settings = this.env.services.setting.currentSettings();
     this.settings = settings;
     void this._prepareHashFunctions();
   }
   offRemoteChunkFetchedHandler;
+  databaseCloseCleanup;
+  databaseUnloadNotification;
   constructor(dbname, env) {
     this.auth = {
       username: "",
@@ -57,14 +55,79 @@ class LiveSyncLocalDB {
     this._log = createInstanceLogFunction("LiveSyncLocalDB", this.env.services.API);
     this.refreshSettings();
   }
+  /** Notify dependent services at most once for each physical database lifecycle. */
+  notifyDatabaseUnload() {
+    if (!this.databaseUnloadNotification) {
+      this.databaseUnloadNotification = Promise.resolve().then(async () => {
+        await this.env.services.databaseEvents.onUnloadDatabase(this);
+      });
+    }
+    return this.databaseUnloadNotification;
+  }
+  onunload() {
+    void this.notifyDatabaseUnload();
+  }
   async close() {
     this._log("Database closed (by close)");
     this.isReady = false;
     this.offRemoteChunkFetchedHandler?.();
+    this.offRemoteChunkFetchedHandler = void 0;
     if (this.localDatabase != null) {
-      await this.localDatabase.close();
+      const database = this.localDatabase;
+      await database.close();
+      if (this.databaseCloseCleanup?.database === database) {
+        await this.databaseCloseCleanup.promise;
+      }
+      if (this.localDatabase === database) {
+        this.localDatabase = null;
+      }
+    }
+    this._managers = void 0;
+    await this.notifyDatabaseUnload();
+  }
+  async teardownDatabaseDependencies(managers) {
+    try {
+      await Promise.resolve(this.env.services.replicator.getActiveReplicator()?.closeReplication());
+    } catch (error) {
+      this._log("Failed to close replication while tearing down the local database.", LOG_LEVEL_VERBOSE);
+      this._log(error, LOG_LEVEL_VERBOSE);
+    }
+    try {
+      await managers.teardownManagers();
+    } catch (error) {
+      this._log("Failed to tear down managers while closing the local database.", LOG_LEVEL_VERBOSE);
+      this._log(error, LOG_LEVEL_VERBOSE);
+    }
+  }
+  async rollbackFailedInitialisation(database, managers) {
+    this.isReady = false;
+    this.offRemoteChunkFetchedHandler?.();
+    this.offRemoteChunkFetchedHandler = void 0;
+    const closeCleanup = this.databaseCloseCleanup?.database === database ? this.databaseCloseCleanup : void 0;
+    if (closeCleanup) {
+      await closeCleanup.promise;
+    } else {
+      database.removeAllListeners();
+      await this.teardownDatabaseDependencies(managers);
+      try {
+        await database.close();
+      } catch (error) {
+        this._log("Failed to close the database after its initialisation was rejected.", LOG_LEVEL_VERBOSE);
+        this._log(error, LOG_LEVEL_VERBOSE);
+      }
+    }
+    if (this.localDatabase === database) {
+      this.localDatabase = null;
+    }
+    if (this._managers === managers) {
+      this._managers = void 0;
+    }
+    try {
+      await this.notifyDatabaseUnload();
+    } catch (error) {
+      this._log("A database unload handler failed after initialisation was rejected.", LOG_LEVEL_VERBOSE);
+      this._log(error, LOG_LEVEL_VERBOSE);
     }
-    await this.env.services.databaseEvents.onUnloadDatabase(this);
   }
   onNewLeaf(chunk) {
     this.managers.chunkManager?.emitEvent(EVENT_CHUNK_FETCHED, chunk);
@@ -84,6 +147,7 @@ class LiveSyncLocalDB {
         deterministic_revs: true
       }
     );
+    this.databaseUnloadNotification = void 0;
     const manager = new LiveSyncManagers({
       database: this.localDatabase,
       APIService: this.env.services.API,
@@ -93,38 +157,53 @@ class LiveSyncLocalDB {
       databaseService: this.env.services.database
     });
     this._managers = manager;
-    if (!await this.env.services.databaseEvents.onDatabaseInitialisation(this)) {
-      this._log("Initializing Database has been failed on some module", LOG_LEVEL_NOTICE);
-    }
-    this._log("Opening Database...");
-    this._log("Database info", LOG_LEVEL_VERBOSE);
-    this._log(JSON.stringify(await this.localDatabase.info(), null, 2), LOG_LEVEL_VERBOSE);
-    await this.managers.initialise();
-    this.localDatabase.on("close", () => {
-      this._log("Database closed.");
-      this.isReady = false;
-      this.localDatabase.removeAllListeners();
-      this.env.services.replicator.getActiveReplicator()?.closeReplication();
-      void this.managers.teardownManagers();
-    });
-    const _instance = new FallbackWeakRef(this);
-    const unload = this.env.services.context.events.onEvent(REMOTE_CHUNK_FETCHED, (chunk) => {
-      if (_instance.deref() == null) {
-        unload();
+    const openedDatabase = this.localDatabase;
+    this.databaseCloseCleanup = void 0;
+    try {
+      if (!await this.env.services.databaseEvents.onDatabaseInitialisation(this)) {
+        await this.rollbackFailedInitialisation(openedDatabase, manager);
+        this._log("Database initialisation was rejected by a required module.", LOG_LEVEL_NOTICE);
+        return false;
       }
-      _instance.deref()?.onNewLeaf(chunk);
-    });
-    this.offRemoteChunkFetchedHandler = unload;
-    this.isReady = true;
-    if (!await this.env.services.databaseEvents.onDatabaseHasReady()) {
-      this._log(
-        "Some module has prevented the database from being ready. The database is initialised but not ready for use.",
-        LOG_LEVEL_NOTICE
-      );
-      return false;
+      this._log("Opening Database...");
+      this._log("Database info", LOG_LEVEL_VERBOSE);
+      this._log(JSON.stringify(await openedDatabase.info(), null, 2), LOG_LEVEL_VERBOSE);
+      await manager.initialise();
+      openedDatabase.on("close", () => {
+        this._log("Database closed.");
+        this.isReady = false;
+        openedDatabase.removeAllListeners();
+        if (this.databaseCloseCleanup?.database !== openedDatabase) {
+          this.databaseCloseCleanup = {
+            database: openedDatabase,
+            promise: this.teardownDatabaseDependencies(manager)
+          };
+        }
+      });
+      const _instance = new FallbackWeakRef(this);
+      const unload = this.env.services.context.events.onEvent(REMOTE_CHUNK_FETCHED, (chunk) => {
+        if (_instance.deref() == null) {
+          unload();
+        }
+        _instance.deref()?.onNewLeaf(chunk);
+      });
+      this.offRemoteChunkFetchedHandler = unload;
+      this.isReady = true;
+      const readyAccepted = await this.env.services.databaseEvents.onDatabaseHasReady();
+      if (!readyAccepted || this.localDatabase !== openedDatabase || !this.isReady) {
+        await this.rollbackFailedInitialisation(openedDatabase, manager);
+        this._log(
+          "Some module has prevented the database from being ready. The database is initialised but not ready for use.",
+          LOG_LEVEL_NOTICE
+        );
+        return false;
+      }
+      this._log("Database is now ready.");
+      return true;
+    } catch (error) {
+      await this.rollbackFailedInitialisation(openedDatabase, manager);
+      throw error;
     }
-    this._log("Database is now ready.");
-    return true;
   }
   /**
    * Retrieve all used and existing chunks in the database.
@@ -212,6 +291,7 @@ class LiveSyncLocalDB {
     return { used, existing };
   }
   async resetDatabase() {
+    this.isReady = false;
     await this.managers.teardownManagers();
     this.env.services.replicator.getActiveReplicator()?.closeReplication();
     if (!await this.env.services.databaseEvents.onResetDatabase(this)) {
@@ -219,10 +299,12 @@ class LiveSyncLocalDB {
       return false;
     }
     Logger("Database closed for reset Database.");
-    this.isReady = false;
     await this.localDatabase.destroy();
     this.localDatabase = null;
-    await this.initializeDatabase();
+    if (!await this.initializeDatabase()) {
+      this._log("Local Database could not be reinitialised after reset.", LOG_LEVEL_NOTICE);
+      return false;
+    }
     this._log("Local Database Reset", LOG_LEVEL_NOTICE);
     return true;
   }

package/dist/replication/trystero/LiveSyncTrysteroReplicator.d.ts

@@ -20,6 +20,7 @@ export declare class LiveSyncTrysteroReplicator extends LiveSyncAbstractReplicat
     private _replicator?;
     private _lifecycleOperation;
     private _shouldBeOpen;
+    private _activeTransportCompatibilitySignature?;
     get openReplicationUI(): (showResult: boolean) => Promise<boolean | void>;
     get rawReplicator(): TrysteroReplicator;
     get rawHost(): P2PHost;
@@ -27,6 +28,13 @@ export declare class LiveSyncTrysteroReplicator extends LiveSyncAbstractReplicat
     terminateSync(): void;
     private _buildEnv;
     private _enqueueLifecycleOperation;
+    /**
+     * Capture settings which are fixed when the active P2P transport joins its room.
+     * A later open request can remain idempotent only while these effective values match.
+     */
+    private _getTransportCompatibilitySignature;
+    /** Close and forget the transport without changing the requested lifecycle state. */
+    private _closeTransport;
     open(): Promise<void>;
     close(): Promise<void>;
     closeReplication(): void;

package/dist/replication/trystero/LiveSyncTrysteroReplicator.js

@@ -16,11 +16,18 @@ import {
   P2PHost
 } from "./TrysteroReplicatorP2PServer.js";
 import { delay } from "octagonal-wheels/promises";
+import {
+  hasValidP2PTurnServerUrl,
+  normaliseP2PConnectionPath,
+  normaliseP2PMaxWirePayloadBytes
+} from "../../common/models/setting.p2p.js";
+import { P2PConnectionPaths } from "../../common/models/setting.const.js";
 class LiveSyncTrysteroReplicator extends LiveSyncAbstractReplicator {
   _p2pHost;
   _replicator;
   _lifecycleOperation = Promise.resolve();
   _shouldBeOpen = false;
+  _activeTransportCompatibilitySignature;
   get openReplicationUI() {
     return this.env.openReplicationUI;
   }
@@ -81,6 +88,26 @@ class LiveSyncTrysteroReplicator extends LiveSyncAbstractReplicator {
     this._lifecycleOperation = queued.catch(() => void 0);
     return queued;
   }
+  /**
+   * Capture settings which are fixed when the active P2P transport joins its room.
+   * A later open request can remain idempotent only while these effective values match.
+   */
+  _getTransportCompatibilitySignature() {
+    const settings = this.env.services.setting.currentSettings();
+    const configuredPath = normaliseP2PConnectionPath(settings.P2P_connectionPath);
+    const effectivePath = configuredPath === P2PConnectionPaths.Relay && hasValidP2PTurnServerUrl(settings.P2P_turnServers ?? "") ? P2PConnectionPaths.Relay : P2PConnectionPaths.Automatic;
+    return `${normaliseP2PMaxWirePayloadBytes(settings.P2P_maxWirePayloadBytes)}:${effectivePath}`;
+  }
+  /** Close and forget the transport without changing the requested lifecycle state. */
+  async _closeTransport() {
+    if (this._replicator) {
+      this._replicator.disableBroadcastChanges();
+      await this._replicator.close();
+      this._replicator = void 0;
+    }
+    this._p2pHost = void 0;
+    this._activeTransportCompatibilitySignature = void 0;
+  }
   async open() {
     if (!this.env.services.setting.currentSettings().P2P_Enabled) {
       Logger(this.translate("P2P.NotEnabled"), LOG_LEVEL_NOTICE);
@@ -89,9 +116,13 @@ class LiveSyncTrysteroReplicator extends LiveSyncAbstractReplicator {
     this._shouldBeOpen = true;
     await this._enqueueLifecycleOperation(async () => {
       if (!this._shouldBeOpen) return;
+      const compatibilitySignature = this._getTransportCompatibilitySignature();
       if (this._replicator && this._p2pHost?.isServing) {
-        Logger("P2P replicator is already open.");
-        return;
+        if (this._activeTransportCompatibilitySignature === compatibilitySignature) {
+          Logger("P2P replicator is already open.");
+          return;
+        }
+        await this._closeTransport();
       }
       try {
         const env = this._buildEnv();
@@ -100,23 +131,20 @@ class LiveSyncTrysteroReplicator extends LiveSyncAbstractReplicator {
         this._p2pHost = host;
         this._replicator = replicator;
         await replicator.open();
+        this._activeTransportCompatibilitySignature = compatibilitySignature;
       } catch (e) {
         Logger(e instanceof Error ? e.message : "Error while opening P2P connection", LOG_LEVEL_NOTICE);
         Logger(e, LOG_LEVEL_VERBOSE);
         this._p2pHost = void 0;
         this._replicator = void 0;
+        this._activeTransportCompatibilitySignature = void 0;
       }
     });
   }
   async close() {
     this._shouldBeOpen = false;
     await this._enqueueLifecycleOperation(async () => {
-      if (this._replicator) {
-        this._replicator.disableBroadcastChanges();
-        await this._replicator.close();
-        this._replicator = void 0;
-      }
-      this._p2pHost = void 0;
+      await this._closeTransport();
     });
   }
   closeReplication() {

package/dist/replication/trystero/TrysteroReplicatorP2PServer.js

@@ -13,7 +13,7 @@ import { EVENT_PLATFORM_UNLOADED } from "../../events/coreEvents.js";
 import { shareRunningResult } from "octagonal-wheels/concurrency/lock_v2";
 import { Computed } from "octagonal-wheels/dataobject/Computed";
 import { RpcRoom } from "../../rpc/index.js";
-import { TRYSTERO_RPC_DEFAULTS } from "../../rpc/transports/TrysteroTransport.js";
+import { resolveTrysteroRpcOptions } from "../../rpc/transports/TrysteroTransport.js";
 import { subscribeTrysteroPeerEvents } from "../../rpc/transports/trysteroRoomEvents.js";
 import { toRpcMethodName } from "./rpcCompat.js";
 import { generateJoinRoomOptions } from "../../rpc/transports/trysteroUtils.js";
@@ -379,7 +379,7 @@ You can chose as follows:
     };
     this._rpcRoom?.close();
     this._rpcRoom = new RpcRoom({
-      ...TRYSTERO_RPC_DEFAULTS,
+      ...resolveTrysteroRpcOptions(this.settings),
       transport,
       canAcceptRequest: async (peerId, method) => {
         if (method === toRpcMethodName("!reqAuth")) return true;

package/dist/rpc/transports/TrysteroTransport.d.ts

@@ -68,6 +68,8 @@ export declare const TRYSTERO_RPC_DEFAULTS: {
     /** SCTP guarantees delivery; retransmission is a last-resort safety net. */
     readonly chunkMissingRetryMs: 150;
 };
+/** Resolve the RpcRoom defaults contributed by one P2P connection profile. */
+export declare function resolveTrysteroRpcOptions(settings: Pick<P2PConnectionInfo, "P2P_maxWirePayloadBytes">): Required<Pick<RpcRoomOptions, "maxWirePayloadBytes" | "chunkMissingRetryMs">>;
 /**
  * Wrap an already-joined Trystero `Room` as a `TransportAdapter` for `RpcRoom`.
  *

package/dist/rpc/transports/TrysteroTransport.js

@@ -2,6 +2,7 @@ import { joinRoom, selfId } from "@trystero-p2p/nostr";
 import { RpcRoom } from "../RpcRoom.js";
 import { exposeDB } from "../pouchdb/RpcPouchDBServer.js";
 import { RpcPouchDBProxy } from "../pouchdb/RpcPouchDBProxy.js";
+import { normaliseP2PMaxWirePayloadBytes } from "../../common/models/setting.p2p.js";
 import { ConnectionStringParser } from "../../common/ConnectionString.js";
 import { compatGlobal } from "../../common/coreEnvFunctions.js";
 import { generateJoinRoomOptions } from "./trysteroUtils.js";
@@ -46,6 +47,12 @@ const TRYSTERO_RPC_DEFAULTS = {
   /** SCTP guarantees delivery; retransmission is a last-resort safety net. */
   chunkMissingRetryMs: 150
 };
+function resolveTrysteroRpcOptions(settings) {
+  return {
+    ...TRYSTERO_RPC_DEFAULTS,
+    maxWirePayloadBytes: normaliseP2PMaxWirePayloadBytes(settings.P2P_maxWirePayloadBytes)
+  };
+}
 function wrapTrysteroRoom(room) {
   const rpcAction = room.makeAction(RPC_ACTION_NAME);
   return {
@@ -93,7 +100,11 @@ function joinTrysteroRoomFromUrl(url) {
 }
 function serveTrysteroDB(settings, db, ns = "pdb", options) {
   const roomHandle = joinTrysteroRoom(settings);
-  const rpcRoom = new RpcRoom({ ...TRYSTERO_RPC_DEFAULTS, transport: roomHandle.transport, ...options });
+  const rpcRoom = new RpcRoom({
+    ...resolveTrysteroRpcOptions(settings),
+    transport: roomHandle.transport,
+    ...options
+  });
   exposeDB(rpcRoom, db, ns);
   return {
     peerId: roomHandle.peerId,
@@ -107,7 +118,11 @@ function serveTrysteroDB(settings, db, ns = "pdb", options) {
 }
 function connectTrysteroDBClient(settings, serverPeerId, dbName, ns = "pdb", options) {
   const roomHandle = joinTrysteroRoom(settings);
-  const rpcRoom = new RpcRoom({ ...TRYSTERO_RPC_DEFAULTS, transport: roomHandle.transport, ...options });
+  const rpcRoom = new RpcRoom({
+    ...resolveTrysteroRpcOptions(settings),
+    transport: roomHandle.transport,
+    ...options
+  });
   const proxy = new RpcPouchDBProxy(rpcRoom.session(serverPeerId), dbName, ns);
   return {
     proxy,
@@ -136,6 +151,7 @@ export {
   connectTrysteroDBClient,
   joinTrysteroRoom,
   joinTrysteroRoomFromUrl,
+  resolveTrysteroRpcOptions,
   serveTrysteroDB,
   wrapTrysteroRoom
 };

package/dist/rpc/transports/trysteroUtils.js

@@ -1,3 +1,9 @@
+import { P2PConnectionPaths } from "../../common/models/setting.const.js";
+import {
+  hasValidP2PTurnServerUrl,
+  normaliseP2PConnectionPath,
+  splitP2PTurnServerUrls
+} from "../../common/models/setting.p2p.js";
 import { mixedHash } from "octagonal-wheels/hash/purejs";
 import { compatGlobal } from "../../common/coreEnvFunctions.js";
 import { createDiagRTCPeerConnectionConstructor } from "./DiagRTCPeerConnections.js";
@@ -5,7 +11,7 @@ function generateJoinRoomOptions(settings) {
   const passphraseNumbers = mixedHash(settings.P2P_passphrase, 0);
   const passphrase = passphraseNumbers[0].toString(36) + passphraseNumbers[1].toString(36);
   const relays = settings.P2P_relays.split(",").map((e) => e.trim()).filter((e) => e.length > 0);
-  const turnServers = settings.P2P_turnServers.split(",").map((e) => e.trim()).filter((e) => e.length > 0);
+  const turnServers = splitP2PTurnServerUrls(settings.P2P_turnServers);
   const relayConfig = {
     manualReconnection: true,
     urls: relays
@@ -30,6 +36,11 @@ function generateJoinRoomOptions(settings) {
       }
     ];
   }
+  if (normaliseP2PConnectionPath(settings.P2P_connectionPath) === P2PConnectionPaths.Relay && hasValidP2PTurnServerUrl(settings.P2P_turnServers)) {
+    options.rtcConfig = {
+      iceTransportPolicy: "relay"
+    };
+  }
   return options;
 }
 export {

package/dist/serviceFeatures/prepareDatabaseForUse.js

@@ -4,26 +4,29 @@ import { createInstanceLogFunction } from "../services/lib/logUtils.js";
 async function prepareDatabaseForUse(host, log, errorManager, showingNotice = false, reopenDatabase = true, ignoreSuspending = false) {
   const appLifecycle = host.services.appLifecycle;
   appLifecycle.resetIsReady();
-  if (!reopenDatabase || await host.services.database.openDatabase({
+  if (reopenDatabase && !await host.services.database.openDatabase({
     databaseEvents: host.services.databaseEvents,
     replicator: host.services.replicator
   })) {
-    if (host.services.database.localDatabase.isReady) {
-      await host.services.vault.scanVault(showingNotice, ignoreSuspending);
-    }
-    const ERR_INITIALISATION_FAILED = `Initializing database has been failed on some module!`;
-    if (!await host.services.databaseEvents.onDatabaseInitialised(showingNotice)) {
-      errorManager.showError(ERR_INITIALISATION_FAILED, LOG_LEVEL_NOTICE);
-      return false;
-    }
-    errorManager.clearError(ERR_INITIALISATION_FAILED);
-    appLifecycle.markIsReady();
-    await host.services.fileProcessing.commitPendingFileEvents();
-    return true;
-  } else {
-    appLifecycle.resetIsReady();
     return false;
   }
+  if (!host.services.database.isDatabaseReady()) {
+    return false;
+  }
+  if (!await host.services.vault.scanVault(showingNotice, ignoreSuspending)) {
+    return false;
+  }
+  const ERR_INITIALISATION_FAILED = `Initializing database has been failed on some module!`;
+  if (!await host.services.databaseEvents.onDatabaseInitialised(showingNotice)) {
+    errorManager.showError(ERR_INITIALISATION_FAILED, LOG_LEVEL_NOTICE);
+    return false;
+  }
+  errorManager.clearError(ERR_INITIALISATION_FAILED);
+  if (!await host.services.fileProcessing.commitPendingFileEvents()) {
+    return false;
+  }
+  appLifecycle.markIsReady();
+  return true;
 }
 function usePrepareDatabaseForUse(host) {
   const log = createInstanceLogFunction("SF:prepareDatabaseForUse", host.services.API);

package/dist/serviceModules/Rebuilder.d.ts

@@ -14,6 +14,7 @@ import type { StorageAccess } from "../interfaces/StorageAccess.js";
 import type { LiveSyncEventHub } from "../hub/hub.js";
 import { ServiceModuleBase } from "./ServiceModuleBase.js";
 import type { ControlService } from "../services/base/ControlService.js";
+import type { IFileProcessingService } from "../services/base/IService.js";
 export interface ServiceRebuilderDependencies {
     events: LiveSyncEventHub;
     appLifecycle: AppLifecycleService;
@@ -28,6 +29,7 @@ export interface ServiceRebuilderDependencies {
     replication: ReplicationService;
     database: DatabaseService;
     fileHandler: IFileHandler;
+    fileProcessing: IFileProcessingService;
     control: ControlService;
 }
 export declare class ServiceRebuilder extends ServiceModuleBase<ServiceRebuilderDependencies> implements Rebuilder {
@@ -44,6 +46,7 @@ export declare class ServiceRebuilder extends ServiceModuleBase<ServiceRebuilder
     private replication;
     private database;
     private fileHandler;
+    private fileProcessing;
     private control;
     constructor(services: ServiceRebuilderDependencies);
     $performRebuildDB(method: "localOnly" | "remoteOnly" | "rebuildBothByThisDevice" | "localOnlyWithChunks"): Promise<void>;
@@ -63,17 +66,37 @@ export declare class ServiceRebuilder extends ServiceModuleBase<ServiceRebuilder
     private _onResetLocalDatabase;
     suspendAllSync(): Promise<void>;
     suspendReflectingDatabase(ignoreMinIO?: boolean): Promise<void>;
-    resumeReflectingDatabase(ignoreMinIO?: boolean): Promise<void>;
+    /**
+     * Stage reflection resumption and perform the final reconciliation checks.
+     *
+     * File watching is resumed in memory before the final scan so that changes
+     * made while the scan is running can enter the storage-event queue. This
+     * phase deliberately does not persist the resumed settings. The owning
+     * completion boundary persists them only after the scan, replication
+     * pre-check, and current batch-wait release have succeeded.
+     *
+     * @param ignoreMinIO Whether to resume reflection for a MinIO remote.
+     * @returns `true` when the applicable reconciliation checks succeeded.
+     */
+    resumeReflectingDatabase(ignoreMinIO?: boolean): Promise<boolean>;
+    private prepareLocalDatabaseForRebuild;
+    private completePreparedRebuild;
     fetchLocal(makeLocalChunkBeforeSync?: boolean, preventMakeLocalFilesBeforeSync?: boolean, autoResume?: boolean): Promise<void>;
     private performFetchLocal;
     fetchLocalDBFast(autoResume: boolean): Promise<void>;
     private performFetchLocalDBFast;
     /**
-     * Finish rebuild process with resuming the reflection.
+     * Complete the final rebuild phases and establish application readiness.
+     *
+     * A failed completion restores the previous reflection settings in memory.
+     * Persistence atomicity remains a responsibility of the host setting store;
+     * Commonlib cannot roll back a store which writes successfully and then
+     * reports an error.
      *
-     * @param ignoreMinIO Whether to ignore minio for resuming the reflection.
+     * @param ignoreMinIO Whether to resume reflection for a MinIO remote.
+     * @returns `true` when finalisation completed; otherwise, `false`.
      */
-    finishRebuild(ignoreMinIO?: boolean): Promise<void>;
+    finishRebuild(ignoreMinIO?: boolean): Promise<boolean>;
     /**
      * Fetch local database with making all chunks.
      * This is a wrapper for {@link fetchLocal} with makeLocalChunkBeforeSync = true.