@vrtmrz/livesync-commonlib 0.1.18 → 0.1.19

package/dist/serviceModules/Rebuilder.js

@@ -26,6 +26,7 @@ class ServiceRebuilder extends ServiceModuleBase {
   replication;
   database;
   fileHandler;
+  fileProcessing;
   control;
   constructor(services) {
     super(services);
@@ -42,6 +43,7 @@ class ServiceRebuilder extends ServiceModuleBase {
     this.replication = services.replication;
     this.database = services.database;
     this.fileHandler = services.fileHandler;
+    this.fileProcessing = services.fileProcessing;
     this.control = services.control;
     services.database.onDatabaseReset.addHandler(this._onResetLocalDatabase.bind(this));
     services.setting.suspendAllSync.addHandler(this._allSuspendAllSync.bind(this));
@@ -100,6 +102,7 @@ Please enable them from the settings screen after setup is complete.`,
     await this.informOptionalFeatures();
   }
   async performRebuildEverything() {
+    this.appLifecycle.resetIsReady();
     await this.setting.suspendExtraSync();
     await this.setting.applyPartial({
       isConfigured: true,
@@ -108,8 +111,11 @@ Please enable them from the settings screen after setup is complete.`,
     await this.control.applySettings();
     await this.resetLocalDatabase();
     await delay(1e3);
-    await this.databaseEvents.initialiseDatabase(true, true, true);
+    await this.prepareLocalDatabaseForRebuild();
     if (this.setting.currentSettings().remoteType === REMOTE_P2P) {
+      if (!await this.completePreparedRebuild()) {
+        throw new Error("The local P2P rebuild could not be finalised.");
+      }
       return;
     }
     await this.replication.markLocked();
@@ -117,9 +123,16 @@ Please enable them from the settings screen after setup is complete.`,
     await this.replication.markLocked();
     await delay(500);
     await delay(1e3);
-    await this.replication.replicateAllToRemote(true);
+    if (!await this.replication.replicateAllToRemoteForRebuild(true)) {
+      throw new Error("The first rebuild upload did not complete.");
+    }
     await delay(1e3);
-    await this.replication.replicateAllToRemote(true);
+    if (!await this.replication.replicateAllToRemoteForRebuild(true)) {
+      throw new Error("The final rebuild upload did not complete.");
+    }
+    if (!await this.completePreparedRebuild()) {
+      throw new Error("The rebuild could not be finalised.");
+    }
   }
   $rebuildEverything() {
     return this.rebuildEverything();
@@ -208,18 +221,51 @@ Please enable them from the settings screen after setup is complete.`,
     });
     await this.setting.saveSettingData();
   }
+  /**
+   * 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.
+   */
   async resumeReflectingDatabase(ignoreMinIO = false) {
     const settings = this.setting.currentSettings();
-    if (settings.doNotSuspendOnFetching) return;
-    if (!ignoreMinIO && settings.remoteType == REMOTE_MINIO) return;
+    if (settings.doNotSuspendOnFetching) return true;
+    if (!ignoreMinIO && settings.remoteType == REMOTE_MINIO) return true;
     this._log(`Database and storage reflection has been resumed!`, LOG_LEVEL_NOTICE);
     await this.setting.applyPartial({
       suspendParseReplicationResult: false,
       suspendFileWatching: false
     });
-    await this.vault.scanVault(true);
-    await this.replication.onBeforeReplicate(false);
-    await this.setting.saveSettingData();
+    if (!await this.vault.scanVault(true)) return false;
+    if (!await this.replication.onBeforeReplicate(false)) return false;
+    return true;
+  }
+  async prepareLocalDatabaseForRebuild() {
+    if (!this.database.isDatabaseReady()) {
+      throw new Error("The selected local database is not ready for rebuild preparation.");
+    }
+    if (!await this.vault.scanVault(true, true)) {
+      throw new Error("The Vault could not be scanned for rebuild preparation.");
+    }
+    if (!await this.databaseEvents.onDatabaseInitialised(true)) {
+      throw new Error("The local database completion hooks failed during rebuild preparation.");
+    }
+    if (!await this.fileProcessing.commitPendingFileEvents()) {
+      throw new Error("The current file-event batch could not be released for rebuild preparation.");
+    }
+  }
+  async completePreparedRebuild() {
+    this.appLifecycle.resetIsReady();
+    if (!this.database.isDatabaseReady()) return false;
+    if (!await this.fileProcessing.commitPendingFileEvents()) return false;
+    this.appLifecycle.markIsReady();
+    return true;
   }
   async fetchLocal(makeLocalChunkBeforeSync, preventMakeLocalFilesBeforeSync, autoResume = true) {
     await this.setting.suspendExtraSync();
@@ -259,31 +305,33 @@ Are you sure you wish to proceed?`;
     );
   }
   async performFetchLocal(makeLocalChunkBeforeSync, preventMakeLocalFilesBeforeSync, autoResume = true) {
+    this.appLifecycle.resetIsReady();
     await this.suspendReflectingDatabase(!autoResume);
     await this.control.applySettings();
     await this.resetLocalDatabase();
     this.clearFastFetchCheckpoint();
     await delay(1e3);
-    await this.database.openDatabase({
-      databaseEvents: this.databaseEvents,
-      replicator: this.replicator
-    });
-    this.appLifecycle.markIsReady();
     if (makeLocalChunkBeforeSync) {
       await this.fileHandler.createAllChunks(true);
     } else if (!preventMakeLocalFilesBeforeSync) {
-      await this.databaseEvents.initialiseDatabase(true, true, true);
+      await this.prepareLocalDatabaseForRebuild();
     } else {
     }
     await this.replication.markResolved();
     await delay(500);
-    await this.replication.replicateAllFromRemote(true);
+    if (!await this.replication.replicateAllFromRemoteForRebuild(true)) {
+      throw new Error("The first Standard Fetch pass did not complete.");
+    }
     if (this.setting.currentSettings().remoteType !== REMOTE_P2P) {
       await delay(1e3);
-      await this.replication.replicateAllFromRemote(true);
+      if (!await this.replication.replicateAllFromRemoteForRebuild(true)) {
+        throw new Error("The final Standard Fetch pass did not complete.");
+      }
     }
     if (autoResume) {
-      await this.finishRebuild();
+      if (!await this.finishRebuild()) {
+        throw new Error("Standard Fetch could not be finalised.");
+      }
     }
   }
   async fetchLocalDBFast(autoResume) {
@@ -314,6 +362,7 @@ Are you sure you wish to proceed?`;
     });
   }
   async performFetchLocalDBFast(settings, autoResume) {
+    this.appLifecycle.resetIsReady();
     const remote = settings.couchDB_URI.replace(/\/+$/, "") + (settings.couchDB_DBNAME == "" ? "" : "/" + settings.couchDB_DBNAME);
     let checkpoint = this.getFastFetchCheckpoint(remote);
     await this.suspendReflectingDatabase();
@@ -325,15 +374,16 @@ Are you sure you wish to proceed?`;
         LOG_LEVEL_NOTICE,
         "fetch-init-resume"
       );
+      if (!await this.database.openDatabase({
+        databaseEvents: this.databaseEvents,
+        replicator: this.replicator
+      })) {
+        throw new Error("The selected local database could not be opened for Fast Fetch.");
+      }
     } else {
       await this.resetLocalDatabase();
       await delay(1e3);
     }
-    await this.database.openDatabase({
-      databaseEvents: this.databaseEvents,
-      replicator: this.replicator
-    });
-    this.appLifecycle.markIsReady();
     let localDB = this.database.localDatabase.localDatabase;
     if (checkpoint && (await localDB.info()).doc_count == 0) {
       this._log(
@@ -344,10 +394,6 @@ Are you sure you wish to proceed?`;
       this.clearFastFetchCheckpoint();
       await this.resetLocalDatabase();
       await delay(1e3);
-      await this.database.openDatabase({
-        databaseEvents: this.databaseEvents,
-        replicator: this.replicator
-      });
       localDB = this.database.localDatabase.localDatabase;
       since = "0";
     }
@@ -407,17 +453,47 @@ Total bytes fetched: ${sizeToHumanReadable(progress.totalBytes)}`,
     );
     await this.replication.markResolved();
     if (autoResume) {
-      await this.resumeReflectingDatabase(true);
+      if (!await this.finishRebuild()) {
+        throw new Error("Fast Fetch could not be finalised.");
+      }
     }
     this.clearFastFetchCheckpoint();
   }
   /**
-   * Finish rebuild process with resuming the reflection.
+   * Complete the final rebuild phases and establish application readiness.
    *
-   * @param ignoreMinIO Whether to ignore minio for resuming the reflection.
+   * 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 resume reflection for a MinIO remote.
+   * @returns `true` when finalisation completed; otherwise, `false`.
    */
   async finishRebuild(ignoreMinIO = true) {
-    await this.resumeReflectingDatabase(ignoreMinIO);
+    this.appLifecycle.resetIsReady();
+    const settings = this.setting.currentSettings();
+    const controlsReflection = !settings.doNotSuspendOnFetching && (ignoreMinIO || settings.remoteType !== REMOTE_MINIO);
+    const previousReflectionState = {
+      suspendParseReplicationResult: settings.suspendParseReplicationResult,
+      suspendFileWatching: settings.suspendFileWatching
+    };
+    let completed = false;
+    try {
+      if (!this.database.isDatabaseReady()) return false;
+      if (!await this.resumeReflectingDatabase(ignoreMinIO)) return false;
+      if (!await this.fileProcessing.commitPendingFileEvents()) return false;
+      if (controlsReflection) {
+        await this.setting.saveSettingData();
+      }
+      this.appLifecycle.markIsReady();
+      completed = true;
+      return true;
+    } finally {
+      if (!completed && controlsReflection) {
+        await this.setting.applyPartial(previousReflectionState);
+      }
+    }
   }
   /**
    * Fetch local database with making all chunks.
@@ -433,13 +509,15 @@ Total bytes fetched: ${sizeToHumanReadable(progress.totalBytes)}`,
     return true;
   }
   async resetLocalDatabase() {
-    const settings = this.setting.currentSettings();
-    if (settings.isConfigured && settings.additionalSuffixOfDatabaseName == "") {
-      await this.database.resetDatabase();
-    }
     const suffix = this.API.getAppID() || "";
     await this.setting.applyPartial({ additionalSuffixOfDatabaseName: suffix });
-    await this.database.resetDatabase();
+    const reset = await this.database.resetDatabaseForCurrentSettings({
+      databaseEvents: this.databaseEvents,
+      replicator: this.replicator
+    });
+    if (!reset) {
+      throw new Error("The local database selected by the current settings could not be reset.");
+    }
     this.events.emitEvent(EVENT_DATABASE_REBUILT);
   }
   getFastFetchCheckpoint(remote) {

package/dist/serviceModules/ServiceFileHandlerBase.d.ts

@@ -68,6 +68,23 @@ export declare abstract class ServiceFileHandlerBase extends ServiceModuleBase<S
     private applyDatabaseEntryToStorage;
     private preserveUnsyncedStorageAsConflict;
     private _anyHandlerProcessesFileEvent;
+    private serializedByFileEventPaths;
+    /**
+     * Revalidate a persisted storage operation against the current storage state.
+     *
+     * Snapshot entries preserve operation intent and ordering only. Their file
+     * stub, timestamps, and existence assumptions can be stale after a restart.
+     * Current inclusion is therefore read from storage, while destructive work
+     * is allowed only after current absence has been observed.
+     */
+    private _processRestoredFileEvent;
+    private _planRestoredFileEvent;
+    private _planRestoredRename;
+    private getExactCurrentFile;
+    private isCurrentFileSelected;
+    private isCurrentPathSelected;
+    private canApplyRestoredDeletion;
+    private logRestoredEventValidationFailure;
     _anyProcessReplicatedDoc(entry: MetaEntry): Promise<boolean>;
     createAllChunks(showingNotice?: boolean): Promise<void>;
 }

package/dist/serviceModules/ServiceFileHandlerBase.js

@@ -644,15 +644,13 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
     return true;
   }
   async _anyHandlerProcessesFileEvent(item) {
+    if (item.restoredFromPreviousRuntime) {
+      return await this._processRestoredFileEvent(item);
+    }
     const eventItem = item.args;
     const type = item.type;
     const path = eventItem.file.path;
-    if (!await this.vault.isTargetFile(path)) {
-      this._log(`File ${path} is not the target file`, LOG_LEVEL_VERBOSE);
-      return false;
-    }
-    if (shouldBeIgnored(path)) {
-      this._log(`File ${path} should be ignored`, LOG_LEVEL_VERBOSE);
+    if (!await this.isCurrentPathSelected(path)) {
       return false;
     }
     if (type === "RENAME" && !eventItem.oldPath) {
@@ -660,9 +658,7 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       return false;
     }
     const eventPaths = type === "RENAME" ? [path, eventItem.oldPath] : [path];
-    const documentIds = await Promise.all(eventPaths.map((eventPath) => this.path.path2id(eventPath)));
-    const lockKeys = [...new Set(documentIds)].sort().map((documentId) => `processFileEvent-${documentId}`);
-    return await serializedByKeys(lockKeys, async () => {
+    return await this.serializedByFileEventPaths(eventPaths, async () => {
       switch (type) {
         case "CREATE":
         case "CHANGED":
@@ -682,6 +678,146 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       }
     });
   }
+  async serializedByFileEventPaths(eventPaths, callback) {
+    const documentIds = await Promise.all(eventPaths.map((eventPath) => this.path.path2id(eventPath)));
+    const lockKeys = [...new Set(documentIds)].sort().map((documentId) => `processFileEvent-${documentId}`);
+    return await serializedByKeys(
+      lockKeys,
+      () => callback(documentIds.length === 2 && documentIds[0] === documentIds[1])
+    );
+  }
+  /**
+   * Revalidate a persisted storage operation against the current storage state.
+   *
+   * Snapshot entries preserve operation intent and ordering only. Their file
+   * stub, timestamps, and existence assumptions can be stale after a restart.
+   * Current inclusion is therefore read from storage, while destructive work
+   * is allowed only after current absence has been observed.
+   */
+  async _processRestoredFileEvent(item) {
+    const eventItem = item.args;
+    const type = item.type;
+    const path = eventItem.file.path;
+    if (type === "RENAME" && !eventItem.oldPath) {
+      this._log(`Rename event for ${path} has no source path`, LOG_LEVEL_VERBOSE);
+      return true;
+    }
+    const eventPaths = type === "RENAME" ? [path, eventItem.oldPath] : [path];
+    return await this.serializedByFileEventPaths(eventPaths, async (isSameDocument) => {
+      let action;
+      try {
+        action = await this._planRestoredFileEvent(item, isSameDocument);
+      } catch (ex) {
+        this.logRestoredEventValidationFailure(path, ex);
+        return true;
+      }
+      switch (action.kind) {
+        case "none":
+          return true;
+        case "store":
+          return await this.storeFileToDB(action.file);
+        case "delete":
+          return await this.deleteFileFromDB(action.path);
+        case "rename":
+          return await this.renameFileInDB(action.file, action.oldPath);
+      }
+    });
+  }
+  async _planRestoredFileEvent(item, isSameDocument) {
+    const path = item.args.file.path;
+    switch (item.type) {
+      case "CREATE":
+      case "CHANGED": {
+        const current = this.getExactCurrentFile(await this.storage.getStub(path), path);
+        return current && await this.isCurrentFileSelected(current) ? { kind: "store", file: current } : { kind: "none" };
+      }
+      case "DELETE": {
+        const current = await this.storage.getStub(path);
+        return current === null && await this.canApplyRestoredDeletion(path) ? { kind: "delete", path } : { kind: "none" };
+      }
+      case "RENAME":
+        return await this._planRestoredRename(path, item.args.oldPath, isSameDocument);
+      case "INTERNAL":
+        return { kind: "none" };
+      default:
+        this._log(`Unsupported event type: ${item.type}`, LOG_LEVEL_VERBOSE);
+        return { kind: "none" };
+    }
+  }
+  async _planRestoredRename(newPath, oldPath, isSameDocument) {
+    if (isSameDocument) {
+      const currentTarget2 = this.getExactCurrentFile(await this.storage.getStub(newPath), newPath);
+      if (!currentTarget2 || !await this.isCurrentFileSelected(currentTarget2)) {
+        return { kind: "none" };
+      }
+      return { kind: "rename", file: currentTarget2, oldPath };
+    }
+    const currentTargetItem = await this.storage.getStub(newPath);
+    let currentSourceItem = null;
+    let sourceWasInspected = true;
+    try {
+      currentSourceItem = await this.storage.getStub(oldPath);
+    } catch (ex) {
+      sourceWasInspected = false;
+      this.logRestoredEventValidationFailure(oldPath, ex);
+    }
+    const currentTarget = this.getExactCurrentFile(currentTargetItem, newPath);
+    if (currentTargetItem !== null) {
+      if (!currentTarget || !await this.isCurrentFileSelected(currentTarget)) {
+        return { kind: "none" };
+      }
+      if (!sourceWasInspected || currentSourceItem !== null || !await this.canApplyRestoredDeletion(oldPath)) {
+        return { kind: "store", file: currentTarget };
+      }
+      return { kind: "rename", file: currentTarget, oldPath };
+    }
+    if (!sourceWasInspected || currentSourceItem !== null || !await this.canApplyRestoredDeletion(oldPath)) {
+      return { kind: "none" };
+    }
+    return { kind: "delete", path: oldPath };
+  }
+  getExactCurrentFile(current, expectedPath) {
+    if (current === null || isFolderInfo(current)) {
+      return null;
+    }
+    return this.storage.normalisePath(current.path) === this.storage.normalisePath(expectedPath) ? current : null;
+  }
+  async isCurrentFileSelected(file) {
+    if (!await this.isCurrentPathSelected(file.path)) {
+      return false;
+    }
+    if (this.vault.isFileSizeTooLarge(file.stat.size)) {
+      this._log(`File ${file.path} exceeds the current maximum size`, LOG_LEVEL_VERBOSE);
+      return false;
+    }
+    return true;
+  }
+  async isCurrentPathSelected(path) {
+    if (!await this.vault.isTargetFile(path)) {
+      this._log(`File ${path} is not the target file`, LOG_LEVEL_VERBOSE);
+      return false;
+    }
+    if (shouldBeIgnored(path)) {
+      this._log(`File ${path} should be ignored`, LOG_LEVEL_VERBOSE);
+      return false;
+    }
+    return true;
+  }
+  async canApplyRestoredDeletion(path) {
+    try {
+      return await this.isCurrentPathSelected(path);
+    } catch (ex) {
+      this.logRestoredEventValidationFailure(path, ex);
+      return false;
+    }
+  }
+  logRestoredEventValidationFailure(path, ex) {
+    this._log(
+      `Could not validate the saved storage operation for ${path} against current storage; the Offline Scanner will reconcile the current state`,
+      LOG_LEVEL_NOTICE
+    );
+    this._log(ex, LOG_LEVEL_VERBOSE);
+  }
   async _anyProcessReplicatedDoc(entry) {
     return await serialized(`processReplicatedDoc-${entry._id}`, async () => {
       if (!await this.vault.isTargetFile(entry.path)) {

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

@@ -23,9 +23,7 @@ export declare abstract class DatabaseService<T extends ServiceContext = Service
     protected _localDatabase: LiveSyncLocalDB | null;
     protected services: DatabaseServiceDependencies;
     onOpenDatabase: import("../lib/HandlerUtils.js").BooleanMultipleHandlerFunction<(vaultName: string) => Promise<boolean>>;
-    /**
-     * Called after the local database has been reset.
-     */
+    /** Called after the active database has been reset and successfully reinitialised. */
     onDatabaseReset: import("../lib/HandlerUtils.js").BooleanMultipleHandlerFunction<() => Promise<boolean>>;
     get localDatabase(): LiveSyncLocalDB;
     get localDatabaseDirect(): LiveSyncLocalDB;
@@ -36,5 +34,15 @@ export declare abstract class DatabaseService<T extends ServiceContext = Service
     createPouchDBInstance<T extends object>(name?: string, options?: PouchDB.Configuration.DatabaseConfiguration): PouchDB.Database<T>;
     openDatabase(params: openDatabaseParameters): Promise<boolean>;
     isDatabaseReady(): boolean;
+    private discardFailedActiveDatabase;
     resetDatabase(): Promise<boolean>;
+    /**
+     * Reset the database selected by the current settings.
+     *
+     * A `LiveSyncLocalDB` captures its name when constructed, so changing a
+     * suffix does not retarget the active instance. This operation selects and
+     * opens the settings-derived database before resetting it when necessary.
+     * The formerly active physical database is closed but not destroyed.
+     */
+    resetDatabaseForCurrentSettings(params: openDatabaseParameters): Promise<boolean>;
 }

package/dist/services/base/DatabaseService.js

@@ -3,6 +3,7 @@ import { LiveSyncLocalDB } from "../../pouchdb/LiveSyncLocalDB.js";
 import { handlers } from "../lib/HandlerUtils.js";
 import { createInstanceLogFunction } from "../lib/logUtils.js";
 import { ExtraSuffixIndexedDB } from "../../common/models/shared.const.js";
+import { LOG_LEVEL_VERBOSE } from "../../common/logger.js";
 class DatabaseService extends ServiceBase {
   _log = createInstanceLogFunction("InjectableDatabaseService");
   constructor(context, dependencies) {
@@ -13,9 +14,7 @@ class DatabaseService extends ServiceBase {
   services;
   // Additional process when opening database, such as initialising managers or local database instance.
   onOpenDatabase = handlers().bailFirstFailure("onOpenDatabase");
-  /**
-   * Called after the local database has been reset.
-   */
+  /** Called after the active database has been reset and successfully reinitialised. */
   onDatabaseReset = handlers().bailFirstFailure("onDatabaseReset");
   get localDatabase() {
     if (!this._localDatabase) {
@@ -60,18 +59,75 @@ class DatabaseService extends ServiceBase {
         database: this
       }
     };
-    this._localDatabase = new LiveSyncLocalDB(vaultName, env);
-    await this.onOpenDatabase(vaultName);
-    return await this.localDatabase.initializeDatabase();
+    const selectedDatabase = new LiveSyncLocalDB(vaultName, env);
+    this._localDatabase = selectedDatabase;
+    try {
+      await this.onOpenDatabase(vaultName);
+      const initialised = await selectedDatabase.initializeDatabase();
+      if (!initialised && this._localDatabase === selectedDatabase) {
+        this._localDatabase = null;
+      }
+      return initialised;
+    } catch (error) {
+      if (this._localDatabase === selectedDatabase) {
+        this._localDatabase = null;
+      }
+      throw error;
+    }
   }
   isDatabaseReady() {
     return this._localDatabase != null && this._localDatabase.isReady;
   }
+  async discardFailedActiveDatabase(database) {
+    if (this._localDatabase === database) {
+      this._localDatabase = null;
+    }
+    try {
+      await database.close();
+    } catch (error) {
+      this._log("Failed to close the active database after a rejected lifecycle transition.", LOG_LEVEL_VERBOSE);
+      this._log(error, LOG_LEVEL_VERBOSE);
+    }
+  }
   async resetDatabase() {
     if (!this._localDatabase) {
       return Promise.resolve(true);
     }
-    return await this._localDatabase.resetDatabase();
+    const activeDatabase = this._localDatabase;
+    try {
+      if (!await activeDatabase.resetDatabase()) {
+        await this.discardFailedActiveDatabase(activeDatabase);
+        return false;
+      }
+      if (!await this.onDatabaseReset()) {
+        await this.discardFailedActiveDatabase(activeDatabase);
+        return false;
+      }
+      return true;
+    } catch (error) {
+      await this.discardFailedActiveDatabase(activeDatabase);
+      throw error;
+    }
+  }
+  /**
+   * Reset the database selected by the current settings.
+   *
+   * A `LiveSyncLocalDB` captures its name when constructed, so changing a
+   * suffix does not retarget the active instance. This operation selects and
+   * opens the settings-derived database before resetting it when necessary.
+   * The formerly active physical database is closed but not destroyed.
+   */
+  async resetDatabaseForCurrentSettings(params) {
+    const selectedDatabaseName = this.services.vault.getVaultName();
+    if (this._localDatabase?.dbname !== selectedDatabaseName) {
+      if (!await this.openDatabase(params)) {
+        return false;
+      }
+      if (this._localDatabase?.dbname !== selectedDatabaseName) {
+        return false;
+      }
+    }
+    return await this.resetDatabase();
   }
 }
 export {

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

@@ -70,6 +70,7 @@ export interface IDatabaseService {
     createPouchDBInstance<T extends object>(name?: string, options?: PouchDB.Configuration.DatabaseConfiguration): PouchDB.Database<T>;
     openDatabase(params: openDatabaseParameters): Promise<boolean>;
     resetDatabase(): Promise<boolean>;
+    resetDatabaseForCurrentSettings(params: openDatabaseParameters): Promise<boolean>;
     onDatabaseReset: () => Promise<boolean>;
     onOpenDatabase: (vaultName: string) => Promise<boolean>;
     isDatabaseReady(): boolean;

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

@@ -85,8 +85,24 @@ export declare abstract class ReplicationService<T extends ServiceContext = Serv
     storageApplyingCount: import("octagonal-wheels/dataobject/reactive_v2").ReactiveSource<number>;
     replicationResultCount: import("octagonal-wheels/dataobject/reactive_v2").ReactiveSource<number>;
     getActiveReplicatorFor(usage: string): false | LiveSyncAbstractReplicator;
+    private performReplicateAllToRemote;
+    private performReplicateAllFromRemote;
     replicateAllToRemote(showingNotice?: boolean): Promise<boolean>;
     replicateAllFromRemote(showingNotice?: boolean): Promise<boolean>;
+    /**
+     * Perform a full upload owned by an active rebuild while the physical database is ready.
+     *
+     * This concrete maintenance entry point is intentionally absent from `IReplicationService`;
+     * it is not a general application-readiness bypass.
+     */
+    replicateAllToRemoteForRebuild(showingNotice?: boolean): Promise<boolean>;
+    /**
+     * Perform a full download owned by an active rebuild while the physical database is ready.
+     *
+     * This concrete maintenance entry point is intentionally absent from `IReplicationService`;
+     * it is not a general application-readiness bypass.
+     */
+    replicateAllFromRemoteForRebuild(showingNotice?: boolean): Promise<boolean>;
     private _getReplicatorAndPerform;
     markLocked(lockByClean?: boolean): Promise<void>;
     markUnlocked(): Promise<void>;