@vrtmrz/livesync-commonlib 0.1.9 → 0.1.11

package/dist/replication/couchdb/LiveSyncReplicator.d.ts

@@ -32,6 +32,7 @@ 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;
     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 | {

package/dist/replication/couchdb/LiveSyncReplicator.js

@@ -540,80 +540,94 @@ ${sendingDocs}/(${sentDocsCount} done)`,
         );
         return false;
       }
-      this.maxPullSeq = Number(`${ret.info.update_seq}`.split("-")[0]);
-      this.maxPushSeq = Number(`${(await localDB.info()).update_seq}`.split("-")[0]);
-      if (showResult) {
-        Logger(this.translate("liveSyncReplicator.checkingLastSyncPoint"), LOG_LEVEL_NOTICE, "sync");
-      }
       const { db, syncOptionBase } = ret;
-      this.syncStatus = "STARTED";
-      this.updateInfo();
-      const docArrivedOnStart = this.docArrived;
-      const docSentOnStart = this.docSent;
-      if (!retrying) {
-        this.originalSetting = setting;
-      }
-      this.terminateSync();
-      const syncHandler = syncMode == "sync" ? localDB.sync(db, { ...syncOptionBase }) : syncMode == "pullOnly" ? localDB.replicate.from(db, {
-        ...syncOptionBase,
-        ...setting.readChunksOnline ? selectorOnDemandPull : {}
-      }) : syncMode == "pushOnly" ? localDB.replicate.to(db, { ...syncOptionBase }) : void 0;
-      const syncResult = await this.processSync(
-        syncHandler,
-        showResult,
-        docSentOnStart,
-        docArrivedOnStart,
-        syncMode,
-        retrying,
-        false
-      );
-      if (syncResult == "DONE") {
-        return true;
-      }
-      if (syncResult == "CANCELLED") {
-        return false;
-      }
-      if (syncResult == "FAILED") {
-        return false;
-      }
-      if (syncResult == "NEED_RESURRECT") {
+      try {
+        this.maxPullSeq = Number(`${ret.info.update_seq}`.split("-")[0]);
+        this.maxPushSeq = Number(`${(await localDB.info()).update_seq}`.split("-")[0]);
+        if (showResult) {
+          Logger(this.translate("liveSyncReplicator.checkingLastSyncPoint"), LOG_LEVEL_NOTICE, "sync");
+        }
+        this.syncStatus = "STARTED";
+        this.updateInfo();
+        const docArrivedOnStart = this.docArrived;
+        const docSentOnStart = this.docSent;
+        if (!retrying) {
+          this.originalSetting = setting;
+        }
         this.terminateSync();
-        return async () => await this.openOneShotReplication(
-          this.originalSetting,
+        const syncHandler = syncMode == "sync" ? localDB.sync(db, { ...syncOptionBase }) : syncMode == "pullOnly" ? localDB.replicate.from(db, {
+          ...syncOptionBase,
+          ...setting.readChunksOnline ? selectorOnDemandPull : {}
+        }) : syncMode == "pushOnly" ? localDB.replicate.to(db, { ...syncOptionBase }) : void 0;
+        const syncResult = await this.processSync(
+          syncHandler,
           showResult,
-          false,
+          docSentOnStart,
+          docArrivedOnStart,
           syncMode,
-          ignoreCleanLock
+          retrying,
+          false
         );
-      }
-      if (syncResult == "NEED_RETRY") {
-        const tempSetting = JSON.parse(JSON.stringify(setting));
-        tempSetting.batch_size = Math.ceil(tempSetting.batch_size / 2) + 2;
-        tempSetting.batches_limit = Math.ceil(tempSetting.batches_limit / 2) + 2;
-        if (tempSetting.batch_size <= 5 && tempSetting.batches_limit <= 5) {
-          Logger(
-            this.translate("liveSyncReplicator.cantReplicateLowerValue"),
-            showResult ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO
-          );
+        if (syncResult == "DONE") {
+          return true;
+        }
+        if (syncResult == "CANCELLED") {
           return false;
-        } else {
-          Logger(
-            this.translate("liveSyncReplicator.retryLowerBatchSize", {
-              batch_size: tempSetting.batch_size.toString(),
-              batches_limit: tempSetting.batches_limit.toString()
-            }),
-            showResult ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO
+        }
+        if (syncResult == "FAILED") {
+          return false;
+        }
+        if (syncResult == "NEED_RESURRECT") {
+          this.terminateSync();
+          return async () => await this.openOneShotReplication(
+            this.originalSetting,
+            showResult,
+            false,
+            syncMode,
+            ignoreCleanLock
           );
-          return async () => await this.openOneShotReplication(tempSetting, showResult, true, syncMode, ignoreCleanLock);
         }
+        if (syncResult == "NEED_RETRY") {
+          const tempSetting = JSON.parse(JSON.stringify(setting));
+          tempSetting.batch_size = Math.ceil(tempSetting.batch_size / 2) + 2;
+          tempSetting.batches_limit = Math.ceil(tempSetting.batches_limit / 2) + 2;
+          if (tempSetting.batch_size <= 5 && tempSetting.batches_limit <= 5) {
+            Logger(
+              this.translate("liveSyncReplicator.cantReplicateLowerValue"),
+              showResult ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO
+            );
+            return false;
+          } else {
+            Logger(
+              this.translate("liveSyncReplicator.retryLowerBatchSize", {
+                batch_size: tempSetting.batch_size.toString(),
+                batches_limit: tempSetting.batches_limit.toString()
+              }),
+              showResult ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO
+            );
+            return async () => await this.openOneShotReplication(tempSetting, showResult, true, syncMode, ignoreCleanLock);
+          }
+        }
+        return false;
+      } finally {
+        await this.closeRemoteDatabase(db);
       }
-      return false;
     });
     if (typeof next === "boolean") {
       return next;
     }
     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) {
+    try {
+      await db.close();
+    } catch (ex) {
+      Logger("Failed to close remote database.", LOG_LEVEL_INFO, "sync");
+      Logger(ex, LOG_LEVEL_VERBOSE, "sync");
+    }
+  }
   replicateAllToServer(setting, showingNotice) {
     return this.openOneShotReplication(setting, showingNotice ?? false, false, "pushOnly");
   }
@@ -638,72 +652,87 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       );
       return false;
     }
-    if (!skipCheck) {
-      if (!await checkRemoteVersion(dbRet.db, this.migrate.bind(this), VER)) {
-        Logger(this.translate("liveSyncReplicator.remoteDbCorrupted"), LOG_LEVEL_NOTICE);
-        return false;
-      }
-      this.remoteCleaned = false;
-      this.remoteLocked = false;
-      this.remoteLockedAndDeviceNotAccepted = false;
-      this.tweakSettingsMismatched = false;
-      this.preferredTweakValue = void 0;
-      const progress = `${dbRet.info.update_seq}`;
-      const info = {
-        app_version: this.env.services.API.getAppVersion(),
-        plugin_version: this.env.services.API.getPluginVersion(),
-        vault_name: this.env.services.vault.vaultName(),
-        device_name: this.env.services.vault.getVaultName(),
-        progress
-      };
-      const ensure = await ensureDatabaseIsCompatible(dbRet.db, setting, this.nodeid, currentVersionRange, info);
-      if (ensure == "INCOMPATIBLE") {
-        Logger(
-          "The remote database has no compatibility with the running version. Please upgrade the plugin.",
-          LOG_LEVEL_NOTICE
-        );
-        return false;
-      } else if (ensure == "NODE_LOCKED") {
-        Logger(
-          "The remote database has been rebuilt or corrupted since we have synchronized last time. Fetch rebuilt DB, explicit unlocking or chunk clean-up is required.",
-          LOG_LEVEL_NOTICE
+    let ownershipTransferred = false;
+    try {
+      if (!skipCheck) {
+        if (!await checkRemoteVersion(dbRet.db, this.migrate.bind(this), VER)) {
+          Logger(this.translate("liveSyncReplicator.remoteDbCorrupted"), LOG_LEVEL_NOTICE);
+          return false;
+        }
+        this.remoteCleaned = false;
+        this.remoteLocked = false;
+        this.remoteLockedAndDeviceNotAccepted = false;
+        this.tweakSettingsMismatched = false;
+        this.preferredTweakValue = void 0;
+        const progress = `${dbRet.info.update_seq}`;
+        const info = {
+          app_version: this.env.services.API.getAppVersion(),
+          plugin_version: this.env.services.API.getPluginVersion(),
+          vault_name: this.env.services.vault.vaultName(),
+          device_name: this.env.services.vault.getVaultName(),
+          progress
+        };
+        const ensure = await ensureDatabaseIsCompatible(
+          dbRet.db,
+          setting,
+          this.nodeid,
+          currentVersionRange,
+          info
         );
-        this.remoteLockedAndDeviceNotAccepted = true;
-        this.remoteLocked = true;
-        return false;
-      } else if (ensure == "LOCKED") {
-        this.remoteLocked = true;
-      } else if (ensure == "NODE_CLEANED") {
-        if (ignoreCleanLock) {
-          this.remoteLocked = true;
-        } else {
+        if (ensure == "INCOMPATIBLE") {
+          Logger(
+            "The remote database has no compatibility with the running version. Please upgrade the plugin.",
+            LOG_LEVEL_NOTICE
+          );
+          return false;
+        } else if (ensure == "NODE_LOCKED") {
           Logger(
-            "The remote database has been cleaned up. Fetch rebuilt DB, explicit unlocking or chunk clean-up is required.",
+            "The remote database has been rebuilt or corrupted since we have synchronized last time. Fetch rebuilt DB, explicit unlocking or chunk clean-up is required.",
             LOG_LEVEL_NOTICE
           );
           this.remoteLockedAndDeviceNotAccepted = true;
           this.remoteLocked = true;
-          this.remoteCleaned = true;
+          return false;
+        } else if (ensure == "LOCKED") {
+          this.remoteLocked = true;
+        } else if (ensure == "NODE_CLEANED") {
+          if (ignoreCleanLock) {
+            this.remoteLocked = true;
+          } else {
+            Logger(
+              "The remote database has been cleaned up. Fetch rebuilt DB, explicit unlocking or chunk clean-up is required.",
+              LOG_LEVEL_NOTICE
+            );
+            this.remoteLockedAndDeviceNotAccepted = true;
+            this.remoteLocked = true;
+            this.remoteCleaned = true;
+            return false;
+          }
+        } else if (ensure == "OK") {
+        } else if (ensure[0] == "MISMATCHED") {
+          Logger(this.translate("liveSyncReplicator.mismatchedTweakDetected"), LOG_LEVEL_NOTICE);
+          this.tweakSettingsMismatched = true;
+          this.preferredTweakValue = ensure[1];
           return false;
         }
-      } else if (ensure == "OK") {
-      } else if (ensure[0] == "MISMATCHED") {
-        Logger(this.translate("liveSyncReplicator.mismatchedTweakDetected"), LOG_LEVEL_NOTICE);
-        this.tweakSettingsMismatched = true;
-        this.preferredTweakValue = ensure[1];
-        return false;
+      }
+      const syncOptionBase = {
+        batches_limit: setting.batches_limit,
+        batch_size: setting.batch_size
+      };
+      syncOptionBase.push = {};
+      if (setting.readChunksOnline) {
+        syncOptionBase.pull = { ...selectorOnDemandPull };
+      }
+      const syncOption = keepAlive ? { live: true, retry: true, heartbeat: setting.useTimeouts ? false : 3e4, ...syncOptionBase } : { ...syncOptionBase };
+      const connection = { db: dbRet.db, info: dbRet.info, syncOptionBase, syncOption };
+      ownershipTransferred = true;
+      return connection;
+    } finally {
+      if (!ownershipTransferred) {
+        await this.closeRemoteDatabase(dbRet.db);
       }
     }
-    const syncOptionBase = {
-      batches_limit: setting.batches_limit,
-      batch_size: setting.batch_size
-    };
-    syncOptionBase.push = {};
-    if (setting.readChunksOnline) {
-      syncOptionBase.pull = { ...selectorOnDemandPull };
-    }
-    const syncOption = keepAlive ? { live: true, retry: true, heartbeat: setting.useTimeouts ? false : 3e4, ...syncOptionBase } : { ...syncOptionBase };
-    return { db: dbRet.db, info: dbRet.info, syncOptionBase, syncOption };
   }
   async openContinuousReplication(setting, showResult, retrying) {
     const next = await shareRunningResult("continuousReplication", async () => {

package/dist/serviceFeatures/offlineScanner.d.ts

@@ -2,6 +2,19 @@ import { type FilePathWithPrefix, type FilePathWithPrefixLC, type MetaEntry, typ
 import { type LogFunction } from "../services/lib/logUtils.js";
 import type { NecessaryServices } from "../interfaces/ServiceModule.js";
 import { UnresolvedErrorManager } from "../services/base/UnresolvedErrorManager.js";
+/**
+ * Outcome of processing one storage/database pair during an offline scan.
+ *
+ * A skipped pair is intentionally left unchanged by scanner policy. It is not
+ * a scan failure, but it must not receive success side effects which would
+ * claim that database content was reflected to storage.
+ */
+export declare const FilePairProcessResults: {
+    readonly COMPLETED: "completed";
+    readonly SKIPPED: "skipped";
+    readonly FAILED: "failed";
+};
+export type FilePairProcessResult = (typeof FilePairProcessResults)[keyof typeof FilePairProcessResults];
 /**
  * Collect deleted files that have expired according to retention policy.
  * @param host Services container
@@ -23,7 +36,7 @@ export declare function getPathFromEntry(host: NecessaryServices<"path", never>,
  * @param file Storage file information
  * @param doc Database entry
  */
-export declare function syncFileBetweenDBandStorage(host: NecessaryServices<"setting" | "vault" | "path", "storageAccess" | "fileHandler">, log: LogFunction, file: UXFileInfoStub, doc: MetaEntry): Promise<void>;
+export declare function syncFileBetweenDBandStorage(host: NecessaryServices<"setting" | "vault" | "path", "storageAccess" | "fileHandler">, log: LogFunction, file: UXFileInfoStub, doc: MetaEntry): Promise<FilePairProcessResult>;
 export declare function canProceedScan(host: NecessaryServices<"keyValueDB" | "setting", never>, errorManager: UnresolvedErrorManager, log: LogFunction, showingNotice?: boolean, ignoreSuspending?: boolean): boolean;
 /**
  * Convert file path to lower case if the settings indicate that filename case should be handled insensitively.
@@ -46,9 +59,9 @@ export declare function collectDatabaseFiles(host: NecessaryServices<"database"
     databaseFileNames: FilePathWithPrefix[];
     databaseFileNameCI2CS: Record<FilePathWithPrefix, FilePathWithPrefixLC>;
 }>;
-export declare function updateToDatabase(host: NecessaryServices<"vault", "fileHandler">, log: LogFunction, logLevel: LOG_LEVEL, file: UXFileInfoStub): Promise<void>;
-export declare function updateToStorage(host: NecessaryServices<"vault" | "path", "fileHandler">, log: LogFunction, logLevel: LOG_LEVEL, w: MetaEntry): Promise<void>;
-export declare function syncStorageAndDatabase(host: NecessaryServices<"setting" | "vault" | "path", "storageAccess" | "fileHandler">, log: LogFunction, file: UXFileInfoStub, logLevel: LOG_LEVEL, doc: MetaEntry): Promise<void>;
+export declare function updateToDatabase(host: NecessaryServices<"vault", "fileHandler">, log: LogFunction, logLevel: LOG_LEVEL, file: UXFileInfoStub): Promise<FilePairProcessResult>;
+export declare function updateToStorage(host: NecessaryServices<"vault" | "path", "fileHandler">, log: LogFunction, logLevel: LOG_LEVEL, w: MetaEntry): Promise<FilePairProcessResult>;
+export declare function syncStorageAndDatabase(host: NecessaryServices<"setting" | "vault" | "path", "storageAccess" | "fileHandler">, log: LogFunction, file: UXFileInfoStub, logLevel: LOG_LEVEL, doc: MetaEntry): Promise<FilePairProcessResult>;
 export declare const FullScanModes: {
     readonly DB_APPLY: "db-apply";
     readonly NEWER_WINS: "newer-wins";
@@ -105,6 +118,7 @@ export declare function resolveFilePairAction(state: FilePairState, options: Ful
  * @param log Logging function
  * @param errorManager Error manager
  * @param options Full scan options
+ * @returns True when every pair completed or was deliberately skipped; false when any pair failed
  */
 export declare function synchroniseAllFilesBetweenDBandStorage(host: NecessaryServices<"setting" | "vault" | "path" | "fileProcessing" | "database" | "keyValueDB", "storageAccess" | "fileHandler">, log: LogFunction, errorManager: UnresolvedErrorManager, options: FullScanOptions): Promise<boolean>;
 export declare function normaliseFullScanOptions(showingNoticeOrOptions: Partial<FullScanOptions> | boolean | undefined, ignoreSuspending?: boolean): FullScanOptions;
@@ -115,7 +129,7 @@ export declare function normaliseFullScanOptions(showingNoticeOrOptions: Partial
  * @param errorManager Error manager
  * @param showingNotice Whether to show notices during scanning
  * @param ignoreSuspending Whether to ignore suspension settings
- * @returns True if scan completed successfully
+ * @returns True when the scan was permitted and no selected pair failed
  */
 export declare function performFullScan(host: NecessaryServices<"setting" | "vault" | "path" | "fileProcessing" | "database" | "keyValueDB", "storageAccess" | "fileHandler">, log: LogFunction, errorManager: UnresolvedErrorManager, options?: Partial<FullScanOptions>): Promise<boolean>;
 export declare function performFullScan(host: NecessaryServices<"setting" | "vault" | "path" | "fileProcessing" | "database" | "keyValueDB", "storageAccess" | "fileHandler">, log: LogFunction, errorManager: UnresolvedErrorManager, showingNotice?: boolean, ignoreSuspending?: boolean): Promise<boolean>;

package/dist/serviceFeatures/offlineScanner.js

@@ -13,6 +13,11 @@ import { createInstanceLogFunction } from "../services/lib/logUtils.js";
 import { BASE_IS_NEW, EVEN, TARGET_IS_NEW } from "../common/models/shared.const.symbols.js";
 import { UnresolvedErrorManager } from "../services/base/UnresolvedErrorManager.js";
 import { compatGlobal } from "../common/coreEnvFunctions.js";
+const FilePairProcessResults = {
+  COMPLETED: "completed",
+  SKIPPED: "skipped",
+  FAILED: "failed"
+};
 async function collectDeletedFiles(host, log) {
   const limitDays = host.services.setting.currentSettings().automaticallyDeleteMetadataOfDeletedFiles;
   if (limitDays <= 0) return;
@@ -59,13 +64,14 @@ async function syncFileBetweenDBandStorage(host, log, file, doc) {
       if (!host.services.vault.isFileSizeTooLarge(file.stat.size)) {
         log("STORAGE -> DB :" + file.path);
         await host.serviceModules.fileHandler.storeFileToDB(file);
+        return FilePairProcessResults.COMPLETED;
       } else {
         log(
           `STORAGE -> DB : ${file.path} has been skipped due to file size exceeding the limit`,
           LOG_LEVEL_NOTICE
         );
+        return FilePairProcessResults.SKIPPED;
       }
-      break;
     case TARGET_IS_NEW:
       if (!host.services.vault.isFileSizeTooLarge(doc.size)) {
         log("STORAGE <- DB :" + docPath);
@@ -74,21 +80,24 @@ async function syncFileBetweenDBandStorage(host, log, file, doc) {
             file: file.path,
             automated: true
           });
+          return FilePairProcessResults.COMPLETED;
         } else {
           log(`STORAGE <- DB : Cloud not read ${file.path}, possibly deleted`, LOG_LEVEL_NOTICE);
+          return FilePairProcessResults.FAILED;
         }
       } else {
         log(
           `STORAGE <- DB : ${file.path} has been skipped due to file size exceeding the limit`,
           LOG_LEVEL_NOTICE
         );
+        return FilePairProcessResults.SKIPPED;
       }
-      break;
     case EVEN:
       log("STORAGE == DB :" + file.path, LOG_LEVEL_DEBUG);
-      break;
+      return FilePairProcessResults.COMPLETED;
     default:
       log("STORAGE ?? DB :" + file.path + " Something got weird");
+      return FilePairProcessResults.FAILED;
   }
 }
 function canProceedScan(host, errorManager, log, showingNotice = false, ignoreSuspending = false) {
@@ -167,8 +176,10 @@ async function updateToDatabase(host, log, logLevel, file) {
     const path = file.path;
     await host.serviceModules.fileHandler.storeFileToDB(file);
     host.services.context.events.emitEvent("event-file-changed", { file: path, automated: true });
+    return FilePairProcessResults.COMPLETED;
   } else {
     log(`UPDATE DATABASE: ${file.path} has been skipped due to file size exceeding the limit`, logLevel);
+    return FilePairProcessResults.SKIPPED;
   }
 }
 async function updateToStorage(host, log, logLevel, w) {
@@ -177,35 +188,41 @@ async function updateToStorage(host, log, logLevel, w) {
     if (!host.services.vault.isFileSizeTooLarge(w.size)) {
       if ((w._conflicts?.length ?? 0) > 0) {
         log(`UPDATE STORAGE: ${path} has conflicts. skipped (x)`, LOG_LEVEL_INFO);
-        return;
+        return FilePairProcessResults.SKIPPED;
       }
-      await host.serviceModules.fileHandler.dbToStorage(path, null, true);
+      const reflected = await host.serviceModules.fileHandler.dbToStorage(path, null, true);
+      if (!reflected) return FilePairProcessResults.FAILED;
       host.services.context.events.emitEvent("event-file-changed", {
         file: path,
         automated: true
       });
       log(`Check or pull from db:${path} OK`);
+      return FilePairProcessResults.COMPLETED;
     } else {
       log(`UPDATE STORAGE: ${path} has been skipped due to file size exceeding the limit`, logLevel);
+      return FilePairProcessResults.SKIPPED;
     }
   } else if (w) {
     log(`Deletion history skipped: ${path}`, LOG_LEVEL_VERBOSE);
+    return FilePairProcessResults.SKIPPED;
   } else {
     log(`entry not found: ${path}`);
+    return FilePairProcessResults.FAILED;
   }
 }
 async function syncStorageAndDatabase(host, log, file, logLevel, doc) {
   if ((doc._conflicts?.length ?? 0) > 0) {
     log(`SYNC DATABASE AND STORAGE: ${file.path} has conflicts. skipped`, LOG_LEVEL_INFO);
-    return;
+    return FilePairProcessResults.SKIPPED;
   }
   if (!host.services.vault.isFileSizeTooLarge(file.stat.size) && !host.services.vault.isFileSizeTooLarge(doc.size)) {
-    await syncFileBetweenDBandStorage(host, log, file, doc);
+    return await syncFileBetweenDBandStorage(host, log, file, doc);
   } else {
     log(
       `SYNC DATABASE AND STORAGE: ${getPathFromEntry(host, doc)} has been skipped due to file size exceeding the limit`,
       logLevel
     );
+    return FilePairProcessResults.SKIPPED;
   }
 }
 const FullScanModes = {
@@ -308,7 +325,7 @@ async function processFilePair(host, log, pair, options) {
   }
   if (doc && (doc._conflicts?.length ?? 0) > 0) {
     log(`SKIP ${options.mode}: ${path} has conflicts`, LOG_LEVEL_INFO);
-    return true;
+    return FilePairProcessResults.SKIPPED;
   }
   const state = getFilePairState(pair);
   let action = resolveFilePairAction(state, options);
@@ -328,32 +345,35 @@ async function processFilePair(host, log, pair, options) {
         if (!file) {
           throw new Error(`Missing storage file for ${path}`);
         }
-        await updateToDatabase(host, log, LOG_LEVEL_INFO, file);
-        return true;
+        return await updateToDatabase(host, log, LOG_LEVEL_INFO, file);
       case "update-storage":
         if (!doc) {
           throw new Error(`Missing database entry for ${path}`);
         }
-        await updateToStorage(host, log, LOG_LEVEL_INFO, doc);
-        updateFileMTimeInMap(host, fileMapKey, doc.mtime);
-        return true;
+        const updateStorageResult = await updateToStorage(host, log, LOG_LEVEL_INFO, doc);
+        if (updateStorageResult === FilePairProcessResults.COMPLETED) {
+          updateFileMTimeInMap(host, fileMapKey, doc.mtime);
+        }
+        return updateStorageResult;
       case "sync-newer":
         if (!file || !doc) {
           throw new Error(`Cannot compare freshness for ${path}`);
         }
-        await syncStorageAndDatabase(host, log, file, LOG_LEVEL_INFO, doc);
-        updateFileMTimeInMap(host, fileMapKey, Math.max(file.stat.mtime, doc.mtime));
-        return true;
+        const syncResult = await syncStorageAndDatabase(host, log, file, LOG_LEVEL_INFO, doc);
+        if (syncResult === FilePairProcessResults.COMPLETED) {
+          updateFileMTimeInMap(host, fileMapKey, Math.max(file.stat.mtime, doc.mtime));
+        }
+        return syncResult;
       case "delete-local":
         if (!file) {
           log(`DELETE LOCAL: ${path} is already absent from storage`, LOG_LEVEL_VERBOSE);
-          return true;
+          return FilePairProcessResults.COMPLETED;
         }
         log(`DELETE LOCAL: ${file.path}`, LOG_LEVEL_INFO);
         await host.serviceModules.storageAccess.delete(file.path, true);
         fileMaps.delete(fileMapKey);
         saveFileStatus(host);
-        return true;
+        return FilePairProcessResults.COMPLETED;
       case "delete-db": {
         if (!doc) {
           throw new Error(`Missing database entry for ${path}`);
@@ -363,22 +383,23 @@ async function processFilePair(host, log, pair, options) {
         if (dbDeleted) {
           fileMaps.delete(fileMapKey);
           saveFileStatus(host);
+          return FilePairProcessResults.COMPLETED;
         } else {
           log(
             `DELETE DATABASE did not delete ${path}; keeping last-seen record to avoid resurrecting the file`,
             LOG_LEVEL_NOTICE
           );
+          return FilePairProcessResults.FAILED;
         }
-        return true;
       }
       case "skip":
         log(`SKIP ${options.mode}: ${path} (${state})`, LOG_LEVEL_VERBOSE);
-        return true;
+        return FilePairProcessResults.SKIPPED;
     }
   } catch (ex) {
     log(`Error processing ${path} with action ${action}`, LOG_LEVEL_NOTICE);
     log(ex, LOG_LEVEL_VERBOSE);
-    return false;
+    return FilePairProcessResults.FAILED;
   }
 }
 async function synchroniseAllFilesBetweenDBandStorage(host, log, errorManager, options) {
@@ -405,7 +426,9 @@ async function synchroniseAllFilesBetweenDBandStorage(host, log, errorManager, o
     pairs.push(pair);
   }
   log(`Total files to synchronise: ${pairs.length}`, LOG_LEVEL_VERBOSE, "syncAll");
-  let successCount = 0;
+  let completedCount = 0;
+  let skippedCount = 0;
+  let failedCount = 0;
   let processedCount = 0;
   for await (const result of withConcurrency(
     pairs,
@@ -415,14 +438,22 @@ async function synchroniseAllFilesBetweenDBandStorage(host, log, errorManager, o
       } catch (ex) {
         log(`Error while synchronising files`, LOG_LEVEL_NOTICE);
         log(ex, LOG_LEVEL_VERBOSE);
-        return false;
+        return FilePairProcessResults.FAILED;
       }
     },
     10
   )) {
     processedCount++;
-    if (result) {
-      successCount++;
+    switch (result) {
+      case FilePairProcessResults.COMPLETED:
+        completedCount++;
+        break;
+      case FilePairProcessResults.SKIPPED:
+        skippedCount++;
+        break;
+      case FilePairProcessResults.FAILED:
+        failedCount++;
+        break;
     }
     if (processedCount % 25 === 0) {
       log(
@@ -433,12 +464,12 @@ async function synchroniseAllFilesBetweenDBandStorage(host, log, errorManager, o
     }
   }
   log(
-    `Synchronisation completed: ${successCount}/${processedCount} files processed successfully`,
+    `Synchronisation completed: ${processedCount} files processed (${completedCount} completed, ${skippedCount} skipped, ${failedCount} failed)`,
     showingNotice ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO,
     "syncAll"
   );
   saveFileStatus(host, true);
-  return successCount === processedCount;
+  return failedCount === 0;
 }
 function normaliseFullScanOptions(showingNoticeOrOptions, ignoreSuspending = false) {
   if (typeof showingNoticeOrOptions === "object") {
@@ -513,7 +544,7 @@ async function performFullScan(host, log, errorManager, showingNoticeOrOptions =
   log("Initialize and checking database files");
   log("Checking deleted files");
   await collectDeletedFiles(host, log);
-  await synchroniseAllFilesBetweenDBandStorage(host, log, errorManager, options);
+  const scanResult = await synchroniseAllFilesBetweenDBandStorage(host, log, errorManager, options);
   log("Initialized, NOW TRACKING!");
   if (!isInitialized) {
     await host.services.keyValueDB.kvDB.set("initialized", true);
@@ -521,7 +552,7 @@ async function performFullScan(host, log, errorManager, showingNoticeOrOptions =
   if (showingNotice) {
     log("Initialize done!", LOG_LEVEL_NOTICE, "syncAll");
   }
-  return true;
+  return scanResult;
 }
 function useOfflineScanner(host) {
   const log = createInstanceLogFunction("SF:OfflineScanner", host.services.API);
@@ -534,6 +565,7 @@ function useOfflineScanner(host) {
 export {
   ExtraOnLocal,
   ExtraOnRemote,
+  FilePairProcessResults,
   FullScanModes,
   canProceedScan,
   collectDatabaseFiles,

package/dist/serviceModules/Rebuilder.js

@@ -262,6 +262,7 @@ Are you sure you wish to proceed?`;
     await this.suspendReflectingDatabase(!autoResume);
     await this.control.applySettings();
     await this.resetLocalDatabase();
+    this.clearFastFetchCheckpoint();
     await delay(1e3);
     await this.database.openDatabase({
       databaseEvents: this.databaseEvents,
@@ -300,6 +301,14 @@ Are you sure you wish to proceed?`;
       await this.fetchLocal(false, true, autoResume);
       return;
     }
+    if (settings.useRequestAPI) {
+      this._log(
+        "Fast database fetch is unavailable while 'Use Internal API' is enabled. Falling back to Standard Fetch.",
+        LOG_LEVEL_NOTICE
+      );
+      await this.fetchLocal(false, true, autoResume);
+      return;
+    }
     await this.replicator.runBoundedRemoteActivity(() => this.performFetchLocalDBFast(settings, autoResume), {
       label: "fast-fetch"
     });

package/docs/development.md

@@ -57,7 +57,7 @@ The settings lifecycle has an additional focused unit table in `src/common/model
 
 The multiple-remote profile contract has focused unit coverage in `src/serviceFeatures/remoteConfig.unit.spec.ts`. Extend it whenever profile identity, generated display names, activation, P2P selection, URI serialisation, or legacy migration changes. New hosts should import the reviewed primitives through `/remote-configurations`; `compat/serviceFeatures/remoteConfig` remains the wider migration surface used by existing clients.
 
-The 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. Extend both storage-collection and database-collection tests whenever the built-in exclusions change.
+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.
 

package/docs/proven-in-use.md

@@ -22,6 +22,8 @@ Commonlib's injected CouchDB tests verify that a mixed remote chunk batch preser
 
 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. It continues processing after individual failures, returns a failed aggregate only for actual failures, and records a database mtime as local provenance only after database content has been reflected successfully. Self-hosted LiveSync consumes the aggregate directly during Fast Setup, where an actual reflection failure reaches the host-owned recovery choice without treating conflict or size-policy skips as failures.
+
 Most replication and storage services used by the plug-in still enter through explicit `compat/*` paths. Those imports prove that the published compatibility boundary supports the current migration; they are not examples of a finished high-level client API.
 
 The plug-in's manual onboarding and Remote Databases pane use the focused `/remote-configurations` entry to create opaque profile IDs, retain user-visible names, and select main and P2P remotes. Commonlib owns the in-memory profile result contract; Self-hosted LiveSync adds dialogue, Setup URI classification, Fetch or Rebuild scheduling, persistence, restart ordering, and real-Obsidian presentation checks.
@@ -38,6 +40,8 @@ The CLI filesystem composition receives a configured base directory and construc
 
 The maintained CLI checks include unit tests, Deno-driven CLI E2E, Compose-based compatibility runs, and the CLI-to-real-Obsidian synchronisation scenario in `test/e2e-obsidian/scripts/cli-to-obsidian-sync.ts`. The latter is the strongest current evidence that the CLI and plug-in compose compatible Commonlib behaviour across two hosts.
 
+The CLI mirror command returns Commonlib's full-scan aggregate, and daemon start-up stops when that aggregate reports an actual pair failure. Deliberately skipped pairs remain a successful scan result. Commonlib owns the pair classification and aggregate; the CLI owns its command and process policy.
+
 ## WebApp
 
 WebApp receives an already authorised `FileSystemDirectoryHandle` from its host and constructs `FileSystemAccessStorageAdapter` inside `src/apps/webapp/adapters/FSAPIFileSystemAdapter.ts`. The adapter does not call `showDirectoryPicker()`, choose a directory, or persist the handle. This is the maintained application example for the browser entry's root-ownership rule.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "license": "MIT",