@vrtmrz/livesync-commonlib 0.1.21 → 0.1.23

package/dist/common/models/fileaccess.type.d.ts

@@ -53,6 +53,8 @@ export type FileEventArgs = {
     file: UXFileInfoStub | UXInternalFileInfoStub;
     cache?: CacheData;
     oldPath?: string;
+    /** The destination of a rename converted to DELETE after target filtering. */
+    renameTarget?: string;
     ctx?: unknown;
 };
 export type FileEventItem = {

package/dist/managers/StorageEventManager.js

@@ -166,6 +166,7 @@ class StorageEventManagerBase extends StorageEventManager {
         args: {
           file,
           oldPath: type === "RENAME" ? oldPath : void 0,
+          ...param.type === "RENAME" && type === "DELETE" ? { renameTarget: param.file.path } : {},
           cache,
           ctx
         },

package/dist/serviceFeatures/offlineScanner.d.ts

@@ -2,6 +2,9 @@ import { type DocumentID, type FilePathWithPrefix, type FilePathWithPrefixLC, ty
 import { type LogFunction } from "../services/lib/logUtils.js";
 import type { NecessaryServices } from "../interfaces/ServiceModule.js";
 import { UnresolvedErrorManager } from "../services/base/UnresolvedErrorManager.js";
+import { VaultScanResults, type VaultScanResult } from "../services/base/VaultScanResult.js";
+export { VaultScanResults };
+export type { VaultScanResult };
 /**
  * Outcome of processing one storage/database pair during an offline scan.
  *
@@ -200,6 +203,12 @@ export interface FullScanOptions {
     omitEvents?: boolean;
     showingNotice?: boolean;
     ignoreSuspending?: boolean;
+    /**
+     * Allow a completed scan containing individual file-pair failures to
+     * satisfy ordinary application readiness. Scan preconditions remain
+     * strict, and failed pairs remain retryable.
+     */
+    continueOnFileFailure?: boolean;
 }
 export type FullScanMode = (typeof FullScanModes)[keyof typeof FullScanModes];
 type FilePair = {
@@ -225,9 +234,9 @@ 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
+ * @returns The scan result for all file pairs
  */
-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 synchroniseAllFilesBetweenDBandStorage(host: NecessaryServices<"setting" | "vault" | "path" | "fileProcessing" | "database" | "keyValueDB", "storageAccess" | "fileHandler">, log: LogFunction, errorManager: UnresolvedErrorManager, options: FullScanOptions): Promise<VaultScanResult>;
 export declare function normaliseFullScanOptions(showingNoticeOrOptions: Partial<FullScanOptions> | boolean | undefined, ignoreSuspending?: boolean): FullScanOptions;
 /**
  * Remove one path from the Offline Scanner's durable last-seen state.
@@ -242,16 +251,15 @@ export declare function clearOfflineScannerLastSeen(host: NecessaryServices<"set
  * @param host Services container
  * @param log Logging function
  * @param errorManager Error manager
- * @param showingNotice Whether to show notices during scanning
- * @param ignoreSuspending Whether to ignore suspension settings
- * @returns True when the scan was permitted and no selected pair failed
+ * @param showingNoticeOrOptions Full-scan options, or the legacy notice flag
+ * @param ignoreSuspending Legacy suspension flag used with the notice flag
+ * @returns The scan outcome, including accepted individual file failures
  */
-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>;
+export declare function performFullScan(host: NecessaryServices<"setting" | "vault" | "path" | "fileProcessing" | "database" | "keyValueDB", "storageAccess" | "fileHandler">, log: LogFunction, errorManager: UnresolvedErrorManager, options?: Partial<FullScanOptions>): Promise<VaultScanResult>;
+export declare function performFullScan(host: NecessaryServices<"setting" | "vault" | "path" | "fileProcessing" | "database" | "keyValueDB", "storageAccess" | "fileHandler">, log: LogFunction, errorManager: UnresolvedErrorManager, showingNotice?: boolean, ignoreSuspending?: boolean): Promise<VaultScanResult>;
 /**
  * Associate the initialiser file feature with the app lifecycle events.
  * This function binds initialization handlers to the appropriate lifecycle events.
  * @param host Services container with required dependencies
  */
 export declare function useOfflineScanner(host: NecessaryServices<"API" | "appLifecycle" | "setting" | "vault" | "path" | "database" | "databaseEvents" | "fileProcessing" | "keyValueDB" | "replicator", "storageAccess" | "fileHandler">): void;
-export {};

package/dist/serviceFeatures/offlineScanner.js

@@ -15,6 +15,7 @@ import { UnresolvedErrorManager } from "../services/base/UnresolvedErrorManager.
 import { compatGlobal } from "../common/coreEnvFunctions.js";
 import { ICHeader, ICXHeader, PSCHeader } from "../common/models/fileaccess.const.js";
 import { serialized } from "octagonal-wheels/concurrency/lock";
+import { VaultScanResults } from "../services/base/VaultScanResult.js";
 const FilePairProcessResults = {
   COMPLETED: "completed",
   SKIPPED: "skipped",
@@ -749,15 +750,16 @@ async function synchroniseAllFilesBetweenDBandStorage(host, log, errorManager, o
   let skippedCount = 0;
   let failedCount = 0;
   let processedCount = 0;
-  for await (const result of withConcurrency(
+  for await (const { path, result } of withConcurrency(
     pairs,
     async (e) => {
+      const path2 = e.file?.path ?? getPathFromEntry(host, e.doc);
       try {
-        return await processFilePair(host, log, e, options);
+        return { path: path2, result: await processFilePair(host, log, e, options) };
       } catch (ex) {
         log(`Error while synchronising files`, LOG_LEVEL_NOTICE);
         log(ex, LOG_LEVEL_VERBOSE);
-        return FilePairProcessResults.FAILED;
+        return { path: path2, result: FilePairProcessResults.FAILED };
       }
     },
     10
@@ -772,6 +774,10 @@ async function synchroniseAllFilesBetweenDBandStorage(host, log, errorManager, o
         break;
       case FilePairProcessResults.FAILED:
         failedCount++;
+        log(
+          `Offline scan failed to synchronise ${path} between storage and the local database; this path remains eligible for a later scan.`,
+          LOG_LEVEL_VERBOSE
+        );
         break;
     }
     if (processedCount % 25 === 0) {
@@ -788,7 +794,8 @@ async function synchroniseAllFilesBetweenDBandStorage(host, log, errorManager, o
     "syncAll"
   );
   saveFileStatus(host, true);
-  return failedCount === 0;
+  if (failedCount === 0) return VaultScanResults.COMPLETED;
+  return options.continueOnFileFailure === true ? VaultScanResults.COMPLETED_WITH_FILE_FAILURES : VaultScanResults.FAILED;
 }
 function normaliseFullScanOptions(showingNoticeOrOptions, ignoreSuspending = false) {
   if (typeof showingNoticeOrOptions === "object") {
@@ -898,8 +905,12 @@ async function performFullScan(host, log, errorManager, showingNoticeOrOptions =
 function useOfflineScanner(host) {
   const log = createInstanceLogFunction("SF:OfflineScanner", host.services.API);
   const errorManager = new UnresolvedErrorManager(host.services.appLifecycle, host.services.context.events);
-  const handleScanVault = async (showingNotice, ignoreSuspending = false) => {
-    return await performFullScan(host, log, errorManager, showingNotice, ignoreSuspending);
+  const handleScanVault = async (showingNotice, ignoreSuspending = false, continueOnFileFailure = false) => {
+    return await performFullScan(host, log, errorManager, {
+      showingNotice,
+      ignoreSuspending,
+      continueOnFileFailure
+    });
   };
   host.services.vault.scanVault.addHandler(handleScanVault);
 }
@@ -912,6 +923,7 @@ export {
   MetadataDocumentNamespaces,
   MetadataDocumentRepairResults,
   OfflineScanUnresolvedReasons,
+  VaultScanResults,
   canProceedScan,
   clearOfflineScannerLastSeen,
   collectDatabaseFiles,

package/dist/serviceFeatures/prepareDatabaseForUse.d.ts

@@ -1,6 +1,7 @@
 import type { NecessaryServices } from "../interfaces/ServiceModule.js";
 import { UnresolvedErrorManager } from "../services/base/UnresolvedErrorManager.js";
 import { type LogFunction } from "../services/lib/logUtils.js";
+import { type VaultScanResult } from "../services/base/VaultScanResult.js";
 /**
  * Initialise the database and trigger a full vault scan.
  * @param host Services container
@@ -9,9 +10,10 @@ import { type LogFunction } from "../services/lib/logUtils.js";
  * @param showingNotice Whether to show notices during initialisation
  * @param reopenDatabase Whether to reopen the database connection
  * @param ignoreSuspending Whether to ignore suspension settings
- * @returns True if initialisation succeeded
+ * @param continueOnFileFailure Whether individual file failures may satisfy application readiness
+ * @returns The initialisation outcome, including accepted individual file failures
  */
-export declare function prepareDatabaseForUse(host: NecessaryServices<"appLifecycle" | "setting" | "vault" | "path" | "database" | "databaseEvents" | "fileProcessing" | "replicator", never>, log: LogFunction, errorManager: UnresolvedErrorManager, showingNotice?: boolean, reopenDatabase?: boolean, ignoreSuspending?: boolean): Promise<boolean>;
+export declare function prepareDatabaseForUse(host: NecessaryServices<"appLifecycle" | "setting" | "vault" | "path" | "database" | "databaseEvents" | "fileProcessing" | "replicator", never>, log: LogFunction, errorManager: UnresolvedErrorManager, showingNotice?: boolean, reopenDatabase?: boolean, ignoreSuspending?: boolean, continueOnFileFailure?: boolean): Promise<VaultScanResult>;
 /**
  * Associate the initialiser file feature with the app lifecycle events.
  * This function binds initialization handlers to the appropriate lifecycle events.

package/dist/serviceFeatures/prepareDatabaseForUse.js

@@ -1,38 +1,72 @@
-import { LOG_LEVEL_NOTICE } from "octagonal-wheels/common/logger";
+import { LOG_LEVEL_VERBOSE } from "octagonal-wheels/common/logger";
 import { UnresolvedErrorManager } from "../services/base/UnresolvedErrorManager.js";
 import { createInstanceLogFunction } from "../services/lib/logUtils.js";
-async function prepareDatabaseForUse(host, log, errorManager, showingNotice = false, reopenDatabase = true, ignoreSuspending = false) {
+import { VaultScanResults } from "../services/base/VaultScanResult.js";
+function reportPreparationFailure(log, message) {
+  log(message, LOG_LEVEL_VERBOSE);
+  return false;
+}
+async function prepareDatabaseForUse(host, log, errorManager, showingNotice = false, reopenDatabase = true, ignoreSuspending = false, continueOnFileFailure = false) {
   const appLifecycle = host.services.appLifecycle;
   appLifecycle.resetIsReady();
-  if (reopenDatabase && !await host.services.database.openDatabase({
-    databaseEvents: host.services.databaseEvents,
-    replicator: host.services.replicator
-  })) {
-    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;
+  try {
+    if (reopenDatabase && !await host.services.database.openDatabase({
+      databaseEvents: host.services.databaseEvents,
+      replicator: host.services.replicator
+    })) {
+      return reportPreparationFailure(
+        log,
+        "Database preparation stopped because the local database could not be opened."
+      );
+    }
+    if (!host.services.database.isDatabaseReady()) {
+      return reportPreparationFailure(
+        log,
+        "Database preparation stopped because the local database is not ready."
+      );
+    }
+    const scanResult = await host.services.vault.scanVault(showingNotice, ignoreSuspending, continueOnFileFailure);
+    if (scanResult === VaultScanResults.FAILED) {
+      return reportPreparationFailure(log, "Database preparation stopped because the Vault scan failed.");
+    }
+    if (scanResult === VaultScanResults.COMPLETED_WITH_FILE_FAILURES && continueOnFileFailure !== true) {
+      return reportPreparationFailure(
+        log,
+        "Database preparation stopped because the Vault scan could not process every file."
+      );
+    }
+    if (!await host.services.databaseEvents.onDatabaseInitialised(showingNotice)) {
+      return reportPreparationFailure(
+        log,
+        "Database preparation stopped because an initialisation handler failed."
+      );
+    }
+    if (!await host.services.fileProcessing.commitPendingFileEvents()) {
+      return reportPreparationFailure(
+        log,
+        "Database preparation stopped because pending file events could not be committed."
+      );
+    }
+    appLifecycle.markIsReady();
+    return scanResult;
+  } catch (error) {
+    log(error, LOG_LEVEL_VERBOSE);
+    throw error;
   }
-  appLifecycle.markIsReady();
-  return true;
 }
 function usePrepareDatabaseForUse(host) {
   const log = createInstanceLogFunction("SF:prepareDatabaseForUse", host.services.API);
   const errorManager = new UnresolvedErrorManager(host.services.appLifecycle, host.services.context.events);
-  const initialiseDatabaseHandler = async (showingNotice = false, reopenDatabase = true, ignoreSuspending = false) => {
-    return await prepareDatabaseForUse(host, log, errorManager, showingNotice, reopenDatabase, ignoreSuspending);
+  const initialiseDatabaseHandler = async (showingNotice = false, reopenDatabase = true, ignoreSuspending = false, continueOnFileFailure = false) => {
+    return await prepareDatabaseForUse(
+      host,
+      log,
+      errorManager,
+      showingNotice,
+      reopenDatabase,
+      ignoreSuspending,
+      continueOnFileFailure
+    );
   };
   host.services.databaseEvents.initialiseDatabase.addHandler(initialiseDatabaseHandler);
 }

package/dist/serviceFeatures/targetFilter.d.ts

@@ -1,6 +1,7 @@
 import { type UXFileInfoStub } from "../common/types.js";
 import { type LogFunction } from "../services/lib/logUtils.js";
 import type { NecessaryServices } from "../interfaces/ServiceModule.js";
+import type { IVaultService } from "../services/base/IService.js";
 /**
  * This is a simple handler that accepts all files.
  */
@@ -8,7 +9,7 @@ export declare function isAcceptedAlwaysFactory(host: NecessaryServices<never, n
 /**
  * Check if a file is accepted based on filename duplication in the vault.
  */
-export declare function isAcceptedInFilenameDuplicationFactory(host: NecessaryServices<"vault" | "fileProcessing", "storageAccess">, log: LogFunction): (file: string | UXFileInfoStub) => Promise<boolean>;
+export declare function isAcceptedInFilenameDuplicationFactory(host: NecessaryServices<"vault" | "fileProcessing", "storageAccess">, log: LogFunction): (file: string | UXFileInfoStub, options?: Parameters<IVaultService["isTargetFile"]>[1]) => Promise<boolean>;
 /**
  * Check if a file is accepted by the local database (e.g., not rejected by the local DB's target file check).
  * Local database responsible for non-internal files, syncOnlyRegEx, syncIgnoreRegEx

package/dist/serviceFeatures/targetFilter.js

@@ -35,7 +35,8 @@ function isAcceptedInFilenameDuplicationFactory(host, log) {
       return true;
     }
   });
-  return async function isAcceptedInFilenameDuplication(file) {
+  return async function isAcceptedInFilenameDuplication(file, options) {
+    if (options?.skipCaseCollisionCheck) return true;
     const fileCountMap = (await fileCountMapComputed.update(host.services.fileProcessing.totalStorageFileEventCount)).value;
     const filepath = getStoragePathFromUXFileInfo(file);
     const lc = filepath.toLowerCase();

package/dist/serviceModules/ServiceFileHandlerBase.d.ts

@@ -68,6 +68,7 @@ export declare abstract class ServiceFileHandlerBase extends ServiceModuleBase<S
     private applyDatabaseEntryToStorage;
     private preserveUnsyncedStorageAsConflict;
     private _anyHandlerProcessesFileEvent;
+    private canRecordStorageDeletion;
     private serializedByFileEventPaths;
     /**
      * Revalidate a persisted storage operation against the current storage state.

package/dist/serviceModules/ServiceFileHandlerBase.js

@@ -657,13 +657,15 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       this._log(`Rename event for ${path} has no source path`, LOG_LEVEL_VERBOSE);
       return false;
     }
-    const eventPaths = type === "RENAME" ? [path, eventItem.oldPath] : [path];
+    const relatedPath = type === "RENAME" ? eventItem.oldPath : type === "DELETE" ? eventItem.renameTarget : void 0;
+    const eventPaths = relatedPath === void 0 ? [path] : [path, relatedPath];
     return await this.serializedByFileEventPaths(eventPaths, async () => {
       switch (type) {
         case "CREATE":
         case "CHANGED":
           return await this.storeFileToDB(item.args.file);
         case "DELETE":
+          if (!await this.canRecordStorageDeletion(item)) return true;
           return await this.deleteFileFromDB(item.args.file);
         case "RENAME":
           return await this.renameFileInDB(
@@ -678,6 +680,45 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       }
     });
   }
+  async canRecordStorageDeletion(item) {
+    const path = item.args.file.path;
+    try {
+      const current = await this.storage.getStub(path);
+      let excludedRenameTarget = null;
+      if (item.args.renameTarget !== void 0) {
+        const targetPath = item.args.renameTarget;
+        const targetItem = await this.storage.getStub(targetPath);
+        const target = this.getExactCurrentFile(targetItem, targetPath);
+        if (targetItem !== null && !target) {
+          this._log(`Preserved ${path}: the rename target no longer resolves to ${targetPath}`, LOG_LEVEL_NOTICE);
+          return false;
+        }
+        const targetIsSelected = !shouldBeIgnored(targetPath) && await this.vault.isTargetFile(targetPath, { skipCaseCollisionCheck: true }) && !(target && this.vault.isFileSizeTooLarge(target.stat.size));
+        if (targetIsSelected) {
+          this._log(`Preserved ${path}: rename target ${targetPath} is still selected`, LOG_LEVEL_NOTICE);
+          return false;
+        }
+        excludedRenameTarget = target;
+      }
+      if (current === null) return true;
+      if (!isFolderInfo(current)) {
+        const [currentId, deletedId] = await Promise.all([
+          this.path.path2id(current.path),
+          this.path.path2id(path)
+        ]);
+        if (currentId !== deletedId) return true;
+        if (excludedRenameTarget && this.storage.normalisePath(current.path) !== this.storage.normalisePath(path) && this.storage.normalisePath(current.path) === this.storage.normalisePath(excludedRenameTarget.path)) {
+          return true;
+        }
+      }
+      this._log(`Preserved ${path}: a current storage item contradicts its deletion event`, LOG_LEVEL_NOTICE);
+      return false;
+    } catch (ex) {
+      this._log(`Could not validate deletion of ${path}; preserved the database entry`, LOG_LEVEL_NOTICE);
+      this._log(ex, LOG_LEVEL_VERBOSE);
+      return false;
+    }
+  }
   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}`);
@@ -702,7 +743,8 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       this._log(`Rename event for ${path} has no source path`, LOG_LEVEL_VERBOSE);
       return true;
     }
-    const eventPaths = type === "RENAME" ? [path, eventItem.oldPath] : [path];
+    const relatedPath = type === "RENAME" ? eventItem.oldPath : type === "DELETE" ? eventItem.renameTarget : void 0;
+    const eventPaths = relatedPath === void 0 ? [path] : [path, relatedPath];
     return await this.serializedByFileEventPaths(eventPaths, async (isSameDocument) => {
       let action;
       try {
@@ -732,6 +774,9 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
         return current && await this.isCurrentFileSelected(current) ? { kind: "store", file: current } : { kind: "none" };
       }
       case "DELETE": {
+        if (item.args.renameTarget !== void 0) {
+          return await this.canRecordStorageDeletion(item) && await this.canApplyRestoredDeletion(path) ? { kind: "delete", path } : { kind: "none" };
+        }
         const current = await this.storage.getStub(path);
         return current === null && await this.canApplyRestoredDeletion(path) ? { kind: "delete", path } : { kind: "none" };
       }

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

@@ -34,5 +34,5 @@ export declare abstract class DatabaseEventService<T extends ServiceContext = Se
      * @param reopenDatabase Whether to reopen the database if it is already open.
      * @param ignoreSuspending Whether to ignore any suspending state.
      */
-    readonly initialiseDatabase: import("../lib/HandlerUtils.js").BooleanMultipleHandlerFunction<(showingNotice?: boolean, reopenDatabase?: boolean, ignoreSuspending?: boolean) => Promise<boolean>>;
+    readonly initialiseDatabase: import("../lib/HandlerUtils.js").MultipleHandlerFunction<(showingNotice?: boolean, reopenDatabase?: boolean, ignoreSuspending?: boolean, continueOnFileFailure?: boolean) => Promise<import("./VaultScanResult.js").VaultScanResult>, unknown>;
 }

package/dist/services/base/DatabaseEventService.js

@@ -31,7 +31,7 @@ class DatabaseEventService extends ServiceBase {
    * @param reopenDatabase Whether to reopen the database if it is already open.
    * @param ignoreSuspending Whether to ignore any suspending state.
    */
-  initialiseDatabase = handlers().bailFirstFailure("initialiseDatabase");
+  initialiseDatabase = handlers().bailFirstFailureWithResult("initialiseDatabase");
 }
 export {
   DatabaseEventService

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

@@ -16,6 +16,7 @@ import type { ActiveReplicatorContext, ContinuousReplicationRequest, Replication
 import type { RemoteResourceKind, RemoteResourceMap } from "../../replication/RemoteResource.js";
 import type { CentralRemoteAdministrationRequest, CentralRemoteAdministrationResult } from "../../replication/CentralRemoteAdministration.js";
 import type { MultipleHandlerFunction } from "../lib/HandlerUtils.js";
+import type { VaultScanResult } from "./VaultScanResult.js";
 declare global {
     interface OPTIONAL_SYNC_FEATURES {
         DISABLE: "DISABLE";
@@ -86,7 +87,7 @@ export interface IDatabaseEventService {
     onDatabaseInitialised(showNotice: boolean): Promise<boolean>;
     onDatabaseHasReady(): Promise<boolean>;
     onResetDatabase(db: LiveSyncLocalDB): Promise<boolean>;
-    initialiseDatabase(showingNotice?: boolean, reopenDatabase?: boolean, ignoreSuspending?: boolean): Promise<boolean>;
+    initialiseDatabase(showingNotice?: boolean, reopenDatabase?: boolean, ignoreSuspending?: boolean, continueOnFileFailure?: boolean): Promise<VaultScanResult>;
 }
 export interface IKeyValueDBService {
     openSimpleStore<T>(kind: string): SimpleStore<T>;
@@ -348,9 +349,13 @@ export interface ITweakValueService {
 export interface IVaultService {
     vaultName(): string;
     getVaultName(): string;
-    scanVault(showingNotice?: boolean, ignoreSuspending?: boolean): Promise<boolean>;
+    scanVault(showingNotice?: boolean, ignoreSuspending?: boolean, continueOnFileFailure?: boolean): Promise<VaultScanResult>;
     isIgnoredByIgnoreFile(file: string | UXFileInfoStub): Promise<boolean>;
-    isTargetFile(file: string | UXFileInfoStub): Promise<boolean>;
+    isTargetFile(file: string | UXFileInfoStub, 
+    /** Inspect selection policy without treating a filename collision as an exclusion. */
+    options?: {
+        skipCaseCollisionCheck?: boolean;
+    }): Promise<boolean>;
     isTargetFileInExtra(file: string | UXFileInfoStub): Promise<boolean>;
     isFileSizeTooLarge(size: number): boolean;
     getActiveFilePath(): FilePath | undefined;

package/dist/services/base/ReplicationService.readiness.js

@@ -20,7 +20,7 @@ function createReplicationReadinessEvaluator(dependencies) {
       name: "application-ready",
       evaluate: () => {
         if (gates.isApplicationReady()) return true;
-        diagnostics.log("Not ready");
+        diagnostics.log("Replication is not ready because application initialisation has not completed.");
         return false;
       }
     },

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

@@ -0,0 +1,13 @@
+/**
+ * Outcome of scanning the Vault against the local database.
+ *
+ * Boolean values preserve the existing success and failure contract. The
+ * additional value lets an ordinary start-up remain ready while reporting
+ * that one or more individual files still require attention.
+ */
+export declare const VaultScanResults: {
+    readonly FAILED: false;
+    readonly COMPLETED: true;
+    readonly COMPLETED_WITH_FILE_FAILURES: "completed-with-file-failures";
+};
+export type VaultScanResult = (typeof VaultScanResults)[keyof typeof VaultScanResults];

package/dist/services/base/VaultScanResult.js

@@ -0,0 +1,8 @@
+const VaultScanResults = {
+  FAILED: false,
+  COMPLETED: true,
+  COMPLETED_WITH_FILE_FAILURES: "completed-with-file-failures"
+};
+export {
+  VaultScanResults
+};

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

@@ -26,7 +26,7 @@ export declare abstract class VaultService<T extends ServiceContext = ServiceCon
      * @param showingNotice Whether to show a notice to the user.
      * @param ignoreSuspending Whether to ignore any suspending state.
      */
-    readonly scanVault: import("../lib/HandlerUtils.js").BooleanMultipleHandlerFunction<(showingNotice?: boolean, ignoreSuspending?: boolean) => Promise<boolean>>;
+    readonly scanVault: import("../lib/HandlerUtils.js").MultipleHandlerFunction<(showingNotice?: boolean, ignoreSuspending?: boolean, continueOnFileFailure?: boolean) => Promise<import("./VaultScanResult.js").VaultScanResult>, unknown>;
     /**
      * Check if a file is ignored by the ignore file (e.g., .gitignore, .obsidianignore).
      * @param file The file path or file info stub to check.
@@ -35,9 +35,11 @@ export declare abstract class VaultService<T extends ServiceContext = ServiceCon
     /**
      * Check if a file is a target file for synchronisation.
      * @param file The file path or file info stub to check.
-     * @param keepFileCheckList Whether to keep the file in the check list.
+     * @param options Optional selection inspection without filename collision rejection.
      */
-    readonly isTargetFile: import("../lib/HandlerUtils.js").BooleanMultipleHandlerFunction<(file: string | import("../../common/types.js").UXFileInfoStub) => Promise<boolean>>;
+    readonly isTargetFile: import("../lib/HandlerUtils.js").BooleanMultipleHandlerFunction<(file: string | import("../../common/types.js").UXFileInfoStub, options?: {
+        skipCaseCollisionCheck?: boolean;
+    }) => Promise<boolean>>;
     /**
      * Check if a file is a target file for some extra feature
      */

package/dist/services/base/VaultService.js

@@ -28,7 +28,7 @@ class VaultService extends ServiceBase {
    * @param showingNotice Whether to show a notice to the user.
    * @param ignoreSuspending Whether to ignore any suspending state.
    */
-  scanVault = handlers().bailFirstFailure("scanVault");
+  scanVault = handlers().bailFirstFailureWithResult("scanVault");
   /**
    * Check if a file is ignored by the ignore file (e.g., .gitignore, .obsidianignore).
    * @param file The file path or file info stub to check.
@@ -37,7 +37,7 @@ class VaultService extends ServiceBase {
   /**
    * Check if a file is a target file for synchronisation.
    * @param file The file path or file info stub to check.
-   * @param keepFileCheckList Whether to keep the file in the check list.
+   * @param options Optional selection inspection without filename collision rejection.
    */
   isTargetFile = handlers().bailFirstFailure("isTargetFile");
   /**

package/dist/services/lib/HandlerUtils.d.ts

@@ -182,6 +182,19 @@ export declare class AllHandler<T extends unknown[]> extends BooleanHandlerBase<
      */
     invoke(...args: T): Promise<boolean>;
 }
+/**
+ * A handler that preserves a non-boolean continuation result while continuing
+ * to give false results and exceptions veto power.
+ */
+export declare class AllWithResultHandler<T extends unknown[], U extends boolean | string> extends MultiBinder<BooleanHandlerFunc<T, U>> implements InvokableHandler<T, U> {
+    /**
+     * Invokes every handler in order. The first non-boolean continuation result
+     * is retained, but every remaining handler can still reject the operation.
+     * @param args The arguments to pass to the handlers.
+     * @returns False after any failure, otherwise the retained result or true.
+     */
+    invoke(...args: T): Promise<U>;
+}
 /**
  * A handler that invokes every added handler sequentially and reports whether
  * all of them succeeded.
@@ -276,7 +289,7 @@ export interface MultipleHandlerFunction<TFunc extends (...args: any[]) => U | P
      * @param callback The handler function to add.
      * @returns A function to remove the added handler.
      */
-    addHandler: (callback: TFunc) => () => void;
+    addHandler: (callback: TFunc, priority?: number) => () => void;
     /**
      * Removes a handler function.
      * @param callback The handler function to remove.
@@ -334,6 +347,7 @@ export interface BooleanMultiBinderInstance<T extends unknown[]> extends Invokab
 export declare function allFunction<TFunc extends (...args: any[]) => Promise<boolean>>(name?: string): BooleanMultipleHandlerFunction<TFunc>;
 export declare function allSettledFunction<TFunc extends (...args: any[]) => Promise<boolean>>(name?: string): BooleanMultipleHandlerFunction<TFunc>;
 export declare function bailFirstFailureFunction<TFunc extends (...args: any[]) => Promise<boolean>>(name?: string): BooleanMultipleHandlerFunction<TFunc>;
+export declare function bailFirstFailureWithResultFunction<TFunc extends (...args: any[]) => Promise<boolean | string>>(name?: string): MultipleHandlerFunction<TFunc>;
 export declare function allParallelFunction<TFunc extends (...args: any[]) => Promise<boolean>>(name?: string): BooleanMultipleHandlerFunction<TFunc>;
 export declare function anySuccessFunction<TFunc extends (...args: any[]) => Promise<boolean>>(name?: string): BooleanMultipleHandlerFunction<TFunc>;
 export declare function firstResultFunction<TFunc extends (...args: any[]) => Promise<unknown>>(name?: string): MultipleHandlerFunction<TFunc>;
@@ -369,6 +383,14 @@ export declare function handlers<T extends object>(): {
      * @returns
      */
     bailFirstFailure<K extends FunctionKeys<T>>(name: K): BooleanMultipleHandlerFunction<Extract<T[K], (...args: any[]) => Promise<boolean>>>;
+    /**
+     * Create a handler that preserves a non-boolean continuation result, but
+     * still invokes later handlers so that false results and exceptions
+     * can reject the operation.
+     * @param name
+     * @returns
+     */
+    bailFirstFailureWithResult<K extends FunctionKeys<T>>(name: K): MultipleHandlerFunction<Extract<T[K], (...args: any[]) => Promise<boolean | string>>>;
     /**
      * Create a handler that invokes all added handler functions sequentially until one returns true.
      * @param name

package/dist/services/lib/HandlerUtils.js

@@ -207,6 +207,34 @@ class AllHandler extends BooleanHandlerBase {
     return true;
   }
 }
+class AllWithResultHandler extends MultiBinder {
+  /**
+   * Invokes every handler in order. The first non-boolean continuation result
+   * is retained, but every remaining handler can still reject the operation.
+   * @param args The arguments to pass to the handlers.
+   * @returns False after any failure, otherwise the retained result or true.
+   */
+  async invoke(...args) {
+    let aggregateResult = true;
+    const callbacks = [...this._callbacks];
+    for (const callback of callbacks) {
+      try {
+        const result = await Promise.resolve(callback(...args));
+        if (result === false) {
+          return false;
+        }
+        if (aggregateResult === true && result !== true) {
+          aggregateResult = result;
+        }
+      } catch (error) {
+        Logger(`AllWithResultHandler ${this._name} treated error as failure!`, LOG_LEVEL_VERBOSE);
+        Logger(error, LOG_LEVEL_VERBOSE);
+        return false;
+      }
+    }
+    return aggregateResult;
+  }
+}
 class SettledAllHandler extends BooleanHandlerBase {
   /**
    * Invokes every handler in order, treating a false result or an exception
@@ -321,6 +349,12 @@ function bailFirstFailureFunction(name) {
   const handler = new AllHandler(name ?? "bailFirstFailureFunction");
   return getMultipleBound(handler);
 }
+function bailFirstFailureWithResultFunction(name) {
+  const handler = new AllWithResultHandler(
+    name ?? "bailFirstFailureWithResultFunction"
+  );
+  return getMultipleBound(handler);
+}
 function allParallelFunction(name) {
   const handler = new ParallelAllHandler(name ?? "allParallelFunction");
   return getMultipleBound(handler);
@@ -390,6 +424,18 @@ function handlers() {
     bailFirstFailure(name) {
       return bailFirstFailureFunction(String(name));
     },
+    /**
+     * Create a handler that preserves a non-boolean continuation result, but
+     * still invokes later handlers so that false results and exceptions
+     * can reject the operation.
+     * @param name
+     * @returns
+     */
+    bailFirstFailureWithResult(name) {
+      return bailFirstFailureWithResultFunction(
+        String(name)
+      );
+    },
     /**
      * Create a handler that invokes all added handler functions sequentially until one returns true.
      * @param name
@@ -429,6 +475,7 @@ function handlers() {
 }
 export {
   AllHandler,
+  AllWithResultHandler,
   AnySuccessHandler,
   Binder,
   BooleanHandlerBase,
@@ -444,6 +491,7 @@ export {
   allSettledFunction,
   anySuccessFunction,
   bailFirstFailureFunction,
+  bailFirstFailureWithResultFunction,
   bindableFunction,
   dispatchParallelFunction,
   firstResultFunction,

package/docs/development.md

@@ -83,6 +83,8 @@ 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 unreleased watcher deletion checks and the separate database-to-storage reflection path are recorded in [Storage events and database-to-storage reflection](storage-events-and-reflection.md).
+
 The revision-tree safety rules are documented in [Conflict resolution and file provenance](conflict-resolution.md). `ConflictManager.unit.spec.ts` owns common-ancestor and conservative merge behaviour, deterministic pair selection for multiple live leaves, and reconstruction from the committed tree between stages. `EntryManagerImpls.unit.spec.ts` owns the distinction between force-writing below an exact revision and conditionally advancing a current live leaf through PouchDB's ordinary revision check. `ServiceDatabaseFileAccessBase.unit.spec.ts` owns all-branch content discovery, short-circuiting history existence checks after an exact match, exact-revision logical deletion, and the public live-base result and event boundary. `ServiceFileHandlerBase.unit.spec.ts` owns the injected provenance policy for edit, deletion, and rename operations, together with user-selected reflection, child creation, strict matching, matching-provenance cleanup after exact branch deletion, and stale-revision refusal. `LiveSyncLocalDB.unit.spec.ts` owns chunk reachability across current winners, shared chunks, live conflicts, available merge ancestry, conflict resolution, and PouchDB replication of collection and recreation. Extend the relevant sides when changing conflict resolution, compaction handling, provenance, chunk collection, or database-to-storage overwrite protection.
 
 `LiveSyncReplicator.unit.spec.ts` owns the CouchDB remote-chunk batch contract: a mixed `_all_docs` result must return each available document even when another keyed row reports an error. `ChunkFetcher.unit.spec.ts` owns the consumer behaviour: it writes valid returned chunks and emits `missingChunkRemote` only for requested IDs which are absent from the returned set. Extend both sides when changing remote chunk acquisition or missing-chunk delivery.

package/docs/offline-scanner.md

@@ -0,0 +1,159 @@
+---
+date: 2026-09-04
+commonlib-version: "0.1.21"
+self-hosted-livesync-version: "1.0.24"
+status: unreleased
+---
+
+# Full offline scan
+
+This document defines the developer contract for `synchroniseAllFilesBetweenDBandStorage`. It describes how the scanner classifies each selected path, chooses an action, and records a database-to-storage reflection. Host-specific setup dialogue and recovery choices remain outside this contract.
+
+Before applying the host's target-file policy, the scanner validates each decoded Metadata document against its actual local document ID. Consistent internal, customisation, and plug-in storage namespaces remain owned by their dedicated features. A namespace disagreement, or a normal-file ID which does not match the ID derived from its recorded path, is quarantined.
+
+The malformed Metadata entry never enters pair processing. If consistent, selected Metadata represents the same case-normalised path, that entry and its storage file continue through the established path-based flow. Otherwise, the storage path is also quarantined. The scanner performs no storage write, database deletion, or last-seen update for an unresolved path, and it retains expired logical deletion history whose identity is inconsistent. This does not add a fourth pair result: quarantined entries do not enter pair processing, and the complete-scan result retains its meaning.
+
+`inspectMetadataDocumentIdentities` provides the separate read-only, actual-ID-first report used by a host repair interface. `repairMetadataDocumentIdentity` revalidates one exact source revision, clears its last-seen state, writes and verifies the expected target, and only then tombstones the obsolete ID. It does not provide batch repair. An exact target left by an interrupted attempt permits the same one-entry repair to finish safely.
+
+The tables below cover only paths which remain after identity validation, the host's target-file policy, and Commonlib's built-in exclusions.
+
+## Full-scan lifecycle
+
+`performFullScan` owns the lifecycle around the pair processor:
+
+1. confirm that settings permit the scan;
+2. read the scanner's `initialized` marker;
+3. when the marker is present, load and complete the stored storage-event operations from the previous runtime;
+4. process expired logical deletion history;
+5. collect and process the selected storage and database entries;
+6. after the first permitted invocation reaches its aggregate-result boundary, record `initialized = true`; and
+7. return the aggregate pair result under the caller's selected handling of file failures.
+
+The `initialized` marker records that a full-scan invocation has reached its aggregate-result boundary and that later invocations may restore stored storage-event operations. It is not a successful-scan marker: the first invocation records it after an aggregate `false` result, `true`, or an accepted partial result. An exception before the aggregate result is produced does not reach that write.
+
+Storage-event restoration is a bounded start-up recovery step. Restored events bypass their former batch delay, but `restoreState()` waits for their actual file operations to finish and preserves snapshot sentinel ordering before the file collections are compared. Saved events run first because a deletion or rename can carry operation intent which is no longer visible in the current storage listing. An individual restored operation failure is logged and does not prevent the scan from examining the resulting current state. The following full scan then makes the final reconciliation decision.
+
+This ordering does not mean that storage unconditionally overwrites the replay result. The action matrix remains authoritative: when a replayed operation leaves an ambiguous pair, such as a storage file alongside a deleted database entry, the selected policy may deliberately return `skipped` rather than guess which side is intended. This boundary does not include events which are buffered or received later, and it must not be confused with a host's separate replication-result queue.
+
+### Stored event interpretation
+
+The storage-event snapshot contains operations which the previous runtime observed but had not begun or which were still waiting for their batch boundary. It is not a file-content journal and does not discover changes made while the application was stopped. An operation which had already been removed from the queue and entered file processing is also outside the persisted boundary. The following full scan remains responsible for observing the current storage state across all of these gaps.
+
+A restored event is an operation intent which must be revalidated against the current exact storage path before it can cause a database side effect. Its saved file stub, timestamps, and optional editor cache describe the earlier observation; they are not authoritative file content after a restart. Whenever an inclusion is still applicable, the handler reads a fresh stub and content from current storage. Whenever an ordinary deletion's expected absence is contradicted by a current storage item, that deletion is suppressed and the full scan evaluates that current item instead.
+
+For this check, an exact path means that the canonical path returned by storage has the saved spelling after ordinary separator normalisation. A file returned only through a case-insensitive lookup does not prove the saved inclusion path. A same-ID rename remains the explicit case-change path described below.
+
+The standard-file revalidation contract is:
+
+| Saved operation                         | Current exact storage state                                         | Operation admitted before the full scan                                              |
+| --------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `CREATE` or `CHANGED`                   | The path is still a selected regular file                           | Store the current stub and content; do not use saved content as a historical version |
+| `CREATE` or `CHANGED`                   | The path is absent, no longer selected, or no longer a regular file | Do not replay the inclusion                                                          |
+| `DELETE` without `renameTarget`          | The selected path remains absent                                    | Apply the saved path's deletion intent                                               |
+| `DELETE` without `renameTarget`          | Any current storage item occupies the path                          | Suppress the stale deletion                                                          |
+| `DELETE` retaining `renameTarget`       | Current source selection and rename-exclusion checks permit deletion | Apply the old document's deletion, including a deliberately excluded same-ID destination |
+| `RENAME` between distinct document IDs  | The new selected path exists                                        | Admit the inclusion half using the new path's current stub and content               |
+| `RENAME` between distinct document IDs  | The old selected path is absent                                     | Admit the deletion half for the old path                                             |
+| `RENAME` between distinct document IDs  | Either half is contradicted by current storage                      | Suppress only that half; the other independently validated half may proceed          |
+| Case-only or otherwise same-ID `RENAME` | A current selected file resolves to the renamed canonical path      | Update that single document's path and current content without a separate deletion   |
+| Case-only or otherwise same-ID `RENAME` | The current identity does not support the saved rename              | Do not replay the rename; let the full scan evaluate the current path                |
+
+An inability to inspect the current path is not proof of absence. Revalidation therefore suppresses a destructive half when storage inspection fails, records the failure, and leaves the following scan to report whether reconciliation can proceed. Target-file policy and file-size limits are evaluated from current settings rather than inherited from the saved event.
+
+The unreleased rename-exclusion guard retains `renameTarget` when a rename is converted to deletion during target filtering. Unlike an ordinary deletion, this intent can remove a file from synchronisation without removing it from storage. The guard distinguishes deliberate exclusion from transient case-collision rejection, preserves a recreated source, and permits a deliberately excluded same-ID destination without requiring that destination to disappear. Older snapshots without this optional field retain the absence-only rule. See [Storage events and database-to-storage reflection](storage-events-and-reflection.md) for the exact admission conditions and the separate ordinary watcher boundary.
+
+Independent validation of rename halves does not remove target-first execution. When the new path currently exists, its inclusion must finish successfully before the old-path deletion may run. A failed inclusion preserves the old database entry. When the new path is currently absent, there is no inclusion to publish, and a separately validated absence at the old path may be applied as deletion intent.
+
+`INTERNAL` operations remain owned by the host feature which registered the optional-file handler. That owner must read its current internal storage state; the ordinary file-pair scan does not make a recovery guarantee for an internal path. `SENTINEL_FLUSH` carries ordering only and never represents file state.
+
+The full scan is not a transaction. Expired deletion history may be updated before a later pair fails, and the device-local last-seen map is saved asynchronously after pair processing. The aggregate result does not promise rollback of those earlier side effects or durable completion of that deferred map save.
+
+## Pair states
+
+| State             | Storage             | Local database                   |
+| ----------------- | ------------------- | -------------------------------- |
+| `both`            | File exists         | Live metadata entry exists       |
+| `storage-only`    | File exists         | No metadata entry exists         |
+| `db-only`         | File does not exist | Live metadata entry exists       |
+| `both-db-deleted` | File exists         | Entry records a logical deletion |
+| `db-only-deleted` | File does not exist | Entry records a logical deletion |
+
+A metadata entry with live conflicts is skipped before the ordinary action is selected. It must not be applied to storage by a full scan.
+
+## Option predicates
+
+The action matrix uses these predicates:
+
+- `delete-when-remote-missing` is enabled by `ExtraOnRemote.DELETE_LOCAL_MISSING` or `ExtraOnLocal.DELETE_DB_MISSING`;
+- `delete-when-remote-deleted` is enabled by `ExtraOnRemote.DELETE_LOCAL_MISSING`, `ExtraOnLocal.DELETE_DB_DELETED`, or `ExtraOnLocal.DELETE_DB_MISSING`; and
+- `append-storage-only` is enabled by `ExtraOnLocal.APPEND_STORAGE_ONLY`.
+
+These names explain the table only. The source constants remain the API.
+
+## Action matrix
+
+| Pair state        | `DB_APPLY`                                                         | `NEWER_WINS`                                                                                                  |
+| ----------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| `both`            | `update-storage`                                                   | `sync-newer`                                                                                                  |
+| `storage-only`    | `delete-local` when `delete-when-remote-missing`; otherwise `skip` | `delete-local` when `delete-when-remote-missing`; otherwise `update-db`                                       |
+| `db-only`         | `update-storage`                                                   | `update-storage`, subject to the device-local offline-deletion override described below                       |
+| `both-db-deleted` | `delete-local` when `delete-when-remote-deleted`; otherwise `skip` | `delete-local` when `delete-when-remote-deleted`; otherwise `update-db` when `append-storage-only`, or `skip` |
+| `db-only-deleted` | `skip`                                                             | `skip`                                                                                                        |
+
+`NEWER_WINS` changes a `db-only` action to `delete-db` only when the device-local last-seen map proves that the file existed on an earlier scan and that observed storage mtime is not older than the database mtime under `compareMTime`. This represents a file deleted while the scanner was offline. A database mtime copied from a failed reflection is not such evidence.
+
+The Cartesian `resolveFilePairAction` unit test is the executable counterpart of this matrix. Change the implementation, table, and test together.
+
+## Pair processing result
+
+Each selected pair finishes in one of three states:
+
+| Result      | Meaning                                                                               | Complete-scan result |
+| ----------- | ------------------------------------------------------------------------------------- | -------------------- |
+| `completed` | The selected action completed, or storage and the database were already equal         | Success              |
+| `skipped`   | Scanner policy deliberately left the pair unchanged                                   | Success              |
+| `failed`    | The selected action could not complete, returned a failure result, or raised an error | Failure              |
+
+Conflict guards, size limits, and the explicit `skip` action produce `skipped`. They allow the scan to finish successfully, but do not establish that database content was reflected to storage. In particular, skipping a `db-only` entry must not copy its database mtime into the device-local last-seen map.
+
+An actual storage file remains valid evidence of its own observed mtime even when another action for that pair is skipped. This is distinct from recording the database mtime after a successful database-to-storage reflection.
+
+## Database-to-storage reflection result
+
+When `update-storage` invokes `dbToStorage`, its result controls every success side effect:
+
+| `dbToStorage` outcome | Pair result | Success event and log | Last-seen entry for the database mtime | Later `NEWER_WINS` scan                           |
+| --------------------- | ----------- | --------------------- | -------------------------------------- | ------------------------------------------------- |
+| `true`                | `completed` | Emitted               | Recorded                               | May recognise a later absence as a local deletion |
+| `false`               | `failed`    | Not emitted           | Not recorded                           | Retries `update-storage` while the file is absent |
+| Throws                | `failed`    | Not emitted           | Not recorded                           | Retries after the failed scan can be run again    |
+
+The same result applies when `sync-newer` finds an existing storage file and attempts to reflect a newer database entry. A `false` result must not be converted into `completed`, emit a success event, or replace the observed storage mtime with the database mtime.
+
+By default, the complete scan returns `false` when any pair is `failed`, and returns `true` when every pair is either `completed` or `skipped`. Quarantined entries do not enter this aggregate, so a strict `true` means that no selected pair failed rather than that every discovered entry was resolved or that storage and the database fully converge.
+
+`continueOnFileFailure` is an explicit host completion policy. When it is `true`, the scanner still processes every selected pair, logs each failed path at verbose level, preserves every failed pair and its retry state, and then returns `completed-with-file-failures` from the aggregate boundary. The existing completion log records the total failed count. The option does not turn a failed pair into `completed`, create success events or last-seen evidence, bypass a rejected scan precondition, or accept an exception raised before the aggregate boundary.
+
+`VaultScanResult` therefore has three outcomes: `false` for a rejected or strict failure, `true` for a complete scan without pair failures, and `completed-with-file-failures` when the caller explicitly accepts readiness after one or more pair failures. The non-boolean outcome lets the host present an actionable warning without making Commonlib responsible for user-facing notices.
+
+Self-hosted LiveSync enables this policy only for ordinary Obsidian start-up, where one unavailable path must not prevent unaffected files from synchronising. Fast Setup, Fetch, Rebuild, direct scans, and CLI mirror or daemon paths retain the strict default.
+
+## Result-state verification
+
+Focused two-pass coverage starts with a `DB_APPLY` reflection whose file handler returns `false`, persists the resulting scanner state, and then runs `NEWER_WINS`. It verifies that:
+
+- both scans report failure;
+- the failed path is retried through `dbToStorage`;
+- no success event or success log is emitted;
+- the database mtime does not enter the last-seen map; and
+- `deleteFileFromDB` is not called.
+
+Full-scan coverage also verifies that the strict default returns `false`, an ordinary-start-up scan which explicitly continues returns `completed-with-file-failures` while logging the affected path at verbose level, and a later clean scan returns `true`.
+
+A second two-pass case starts with a `db-only` entry skipped by the size limit. It then removes that limit and verifies that the entry is reflected to storage rather than misclassified as an offline local deletion. Coverage for an existing storage file verifies that a failed `sync-newer` reflection retains the observed storage mtime, and full-scan coverage verifies that the aggregate failure reaches its caller after scanner initialisation completes.
+
+Identity coverage verifies early quarantine when no consistent target exists, continued processing when consistent Metadata represents the same logical path, expired-deletion retention, special-namespace routing, actual-ID-first inspection, stale and ambiguous repair rejection, target-first ordering, exact-target retry, source preservation after failure, and last-seen clearing.
+
+Stored-event coverage verifies that current storage content replaces saved observations, a recreated path suppresses a stale deletion, distinct-ID rename halves are admitted independently from current path state, and a same-ID rename never performs a separate deletion. It also verifies that a storage-inspection failure does not become evidence for a destructive operation and that an individual replay failure does not prevent the full scan from running.
+
+Maintain that interaction boundary when changing file-handler results, last-seen persistence, Fast Setup reflection, or offline deletion detection.

package/docs/proven-in-use.md

@@ -24,9 +24,11 @@ Commonlib's injected remote-service tests verify that an owning operation can ab
 
 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. Snapshot-restoration tests additionally verify that restored inclusions use current storage content, stale deletions are suppressed, rename halves are admitted from their current path states, and an inspection failure does not become evidence of absence. The following full scan remains the final reconciliation step. Self-hosted LiveSync keeps the existing Fast Setup aggregate policy and owns confirmation and presentation in its file/database repair interface.
+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. Snapshot-restoration tests additionally verify that restored inclusions use current storage content, stale deletions are suppressed, rename halves are admitted from their current path states, and an inspection failure does not become evidence of absence. The following full scan remains the final reconciliation step.
 
-Commonlib's local-database lifecycle tests distinguish the settings-selected database from the active wrapper. They verify replacement before a changed-suffix reset, fail-closed cleanup after rejected physical preparation, application readiness after the requested scan and completion hooks, and the prevention of rebuilt events and later remote mutation after a failed local reset. Self-hosted LiveSync owns settings persistence, setup flags, recovery dialogue, and real-Obsidian rebuild confirmation; those host results remain downstream evidence rather than Commonlib guarantees.
+The strict aggregate remains the default for Fast Setup, Fetch, Rebuild, direct scans, and CLI mirror or daemon paths. Self-hosted LiveSync opts only ordinary Obsidian start-up into continuing after individual pair failures. Commonlib returns the distinct `completed-with-file-failures` result, retains each failed result and retry state, records each affected path at verbose level, and leaves any user-facing notice to the host. Focused Commonlib tests cover the default and an explicitly continuing scan; downstream type checks, unit tests, and builds exercise the exact packed implementation and host call. Android-specific storage behaviour remains real-device and reporter-environment evidence rather than a Commonlib guarantee.
+
+Commonlib's local-database lifecycle tests distinguish the settings-selected database from the active wrapper. They verify replacement before a changed-suffix reset, fail-closed cleanup after rejected physical preparation, application readiness after the requested scan and completion hooks, verbose diagnostics for rejected preparation stages, and the prevention of rebuilt events and later remote mutation after a failed local reset. Replication readiness tests verify that a descriptive application-initialisation diagnostic replaces the former bare diagnostic. Self-hosted LiveSync owns settings persistence, setup flags, user-facing notices, recovery dialogue, and real-Obsidian rebuild confirmation; those host results remain downstream evidence rather than Commonlib guarantees.
 
 The focused `/replication` entry defines the provider capability, configuration identity, same-kind reconciliation, interaction authority, and truthful outcome contracts used when a host composes replication. A host selects its fixed provider subset and registers each definition during composition; an omitted role remains an explicit unsupported result rather than falling back to another provider. Commonlib serialises active replacement, rejects a candidate whose configuration changes before publication, and provides a transition-aware context acquisition boundary. The entry does not own user dialogue, P2P room policy, or selection of unknown providers.
 
@@ -38,6 +40,10 @@ Commonlib's confirmation contract can also convey a host-neutral vertical action
 
 Self-hosted LiveSync's Obsidian and browser dialogue hosts now share an application-owned `SvelteDialogSession` lifecycle. They continue to consume Commonlib's dialogue types and manager base, but no maintained LiveSync path uses `SvelteDialogMixIn`. The dynamic-inheritance helper remains available through the compatibility boundary and is deprecated in favour of host-owned composition.
 
+Commonlib's storage-event tests verify that a current file with the same canonical document ID suppresses a watcher deletion, while observed absence still permits deletion and inspection failure preserves Metadata. Rename-derived deletions retain their destination and distinguish deliberate target exclusion from transient filename collision rejection, including after snapshot restoration. A separate reflection test preserves incoming logical-deletion behaviour. These injected-boundary tests establish the [storage-event admission contract](storage-events-and-reflection.md), not the native event ordering of an external folder rename in a particular Obsidian version.
+
+The downstream `E2E_OBSIDIAN_ONLY_PARENT_CASE_DELETION` scenario additionally exercises an external parent-directory case change in real Linux Obsidian 1.12.7. With released Commonlib 0.1.21, native `create` events for the new paths followed by `delete` events for the old paths produce logically deleted Metadata. The `delete` notification carries no `renameTarget`; the guard preserves current same-ID storage without inferring a causal link from the earlier `create`. With the implementation included in Commonlib 0.1.23 installed from its checked package artefact, the same sequence preserves Metadata, Chunks, and unchanged content locally, in CouchDB, on a second Vault, and after restart. This establishes the tested build's deletion protection, not full directory rename support or confirmation in the reporter's Obsidian 1.13.7 environment.
+
 ## CLI
 
 The CLI extends the same neutral context with its database path and injected `StandardIo` in `src/apps/cli/services/NodeServiceContext.ts`. Its entry point creates the Node standard-I/O adapter once and passes it to command composition, while unit tests provide stream-independent fakes for parsing, prompts, standard output, and standard error.

package/docs/service-feature-composition.md

@@ -1,8 +1,8 @@
 ---
-date: 2026-08-30
-commonlib-version: "0.1.20"
-self-hosted-livesync-version: "1.0.21"
-status: accepted
+date: 2026-09-04
+commonlib-version: "0.1.21"
+self-hosted-livesync-version: "1.0.24"
+status: unreleased
 ---
 
 # Service feature composition
@@ -76,8 +76,9 @@ export async function prepareDatabaseForUse(
     errorManager: UnresolvedErrorManager,
     showingNotice = false,
     reopenDatabase = true,
-    ignoreSuspending = false
-): Promise<boolean> {
+    ignoreSuspending = false,
+    continueOnFileFailure = false
+): Promise<VaultScanResult> {
     // Open, scan, run completion handlers, commit pending events, and mark ready.
 }
 ```
@@ -90,14 +91,26 @@ export function usePrepareDatabaseForUse(host: PrepareDatabaseHost): void {
     const errorManager = new UnresolvedErrorManager(host.services.appLifecycle, host.services.context.events);
 
     host.services.databaseEvents.initialiseDatabase.addHandler(
-        (showingNotice = false, reopenDatabase = true, ignoreSuspending = false) =>
-            prepareDatabaseForUse(host, log, errorManager, showingNotice, reopenDatabase, ignoreSuspending)
+        (showingNotice = false, reopenDatabase = true, ignoreSuspending = false, continueOnFileFailure = false) =>
+            prepareDatabaseForUse(
+                host,
+                log,
+                errorManager,
+                showingNotice,
+                reopenDatabase,
+                ignoreSuspending,
+                continueOnFileFailure
+            )
     );
 }
 ```
 
 Test the operation's sequencing and failure short-circuiting separately from the handler registration. This keeps a lifecycle rename from forcing every domain test through an application-shaped fixture.
 
+Database preparation and full scanning remain strict by default. A host may set `continueOnFileFailure` only when its ordinary start-up policy deliberately permits readiness after individual file-pair failures. In that case, the operation returns `completed-with-file-failures` after all later initialisation steps succeed; it does not collapse the result into `true`. That option does not admit a failed scan precondition or a later initialisation step, and explicit recovery workflows retain the default.
+
+The `scanVault` and `initialiseDatabase` services use a failure-veto result aggregator for this contract. It preserves the first non-boolean continuation result but still invokes later handlers, so a later `false` result or exception rejects the operation. `firstResult` is not suitable here because it would return the partial result before those handlers can veto it.
+
 ## Keep feature-local state private
 
 State which exists for one predicate, cache, queue, or scheduling policy can remain in a factory or private context. It does not need to become a property on the application core.

package/docs/storage-events-and-reflection.md

@@ -0,0 +1,107 @@
+---
+date: 2026-09-05
+commonlib-version: "0.1.23"
+self-hosted-livesync-version: "1.0.25"
+---
+
+# Storage events and database-to-storage reflection
+
+This note separates storage-to-database event handling from
+database-to-storage reflection. It describes the Commonlib 0.1.23 guard against
+a stale `DELETE` notification logically deleting Metadata while the same file
+is still present in storage. The version fields identify the reviewed source
+versions.
+
+## Processing directions
+
+`StorageEventManager.appendQueue` receives watcher events, applies target and
+ignore policies, and queues `CREATE`, `CHANGED`, `DELETE`, or `RENAME` work. A
+rename from a selected path to a rejected path becomes a `DELETE` with an
+old-path deleted stub and the destination in `FileEventArgs.renameTarget`.
+A rename from an excluded path to a selected path becomes a `CREATE`.
+
+`renameTarget` is recorded only when one incoming `RENAME` is converted in
+this way. It is not inferred by pairing independent `CREATE` and `DELETE`
+notifications. A `DELETE` without it cannot establish that a current same-ID
+file is the deliberately excluded destination of a rename. The ordinary
+current-storage check therefore suppresses that deletion, even when the
+current file's path would itself be excluded from synchronisation.
+
+`ServiceFileHandlerBase` serialises this work by the canonical document ID
+derived from each path. Before a watcher `DELETE` reaches `deleteFileFromDB`,
+the handler rechecks current storage under that lock. Rename-derived deletions
+lock both source and destination document IDs. This direction updates database
+Metadata; it does not remove the physical file from storage.
+
+An event marked `restoredFromPreviousRuntime` is separately revalidated against
+current storage and selection before the full offline scan. An ordinary
+restored deletion requires current absence; one retaining `renameTarget` uses
+the rename-exclusion checks below as well as current source selection. Older
+snapshots without that field keep their conservative absence-only rule.
+
+Database-to-storage work follows the opposite direction. Replicated Metadata
+reaches `_anyProcessReplicatedDoc`, which applies target and size checks,
+obtains a storage stub, and calls `dbToStorage`. Logical deletion, conflicts,
+and unsynchronised storage content retain their existing reflection rules.
+The watcher guard does not intercept this path or general explicit database
+deletion operations.
+
+## Event intent and current storage state
+
+| Event intent | Current storage observation | Admitted operation |
+| --- | --- | --- |
+| Watcher `CREATE` or `CHANGED` | A selected regular file is present | Keep the existing storage-to-database write. |
+| Watcher `DELETE` without `renameTarget` | A current file resolves to the same canonical document ID, including at an excluded path, or a folder occupies the path | Suppress the database deletion; no rename destination is known. |
+| Watcher `DELETE` without `renameTarget` | The host lookup reports no current item, or a file belonging to a distinct document ID | Use the existing deletion operation. |
+| Watcher `DELETE` without `renameTarget` | Lookup fails | Leave the database unchanged; failure is unknown, not absence. |
+| `RENAME` converted to `DELETE` | The destination is still selected when case-collision rejection is omitted | Suppress the database deletion. |
+| `RENAME` converted to `DELETE` | The destination is deliberately excluded, and the source is absent | Apply the old document's deletion. |
+| Case-only `RENAME` converted to `DELETE` | Source lookup resolves to the exact deliberately excluded destination, not the original path | Apply the old document's deletion despite the shared ID. |
+| Restored `DELETE` without `renameTarget` | A current item occupies the saved path | Keep the existing restored-event suppression. |
+| Replicated logical deletion | Storage contains a file | Keep the existing database-to-storage conflict and preservation rules. |
+
+## Rename exclusion and preservation
+
+The retained destination distinguishes deliberate exclusion from temporary
+rejection by the filename collision check, which counts the host's indexed
+paths. The handler queries `isTargetFile` with `skipCaseCollisionCheck` only
+for that classification; other target policies, built-in exclusions, and the
+current file-size limit still apply. This option does not authorise storing a
+duplicate file.
+
+A target lookup which resolves to another spelling or a folder is ambiguous
+and preserves the database entry. A file recreated at the exact original path
+also prevents deletion. The same-ID exception in the table applies only when
+source lookup resolves to the exact excluded destination instead.
+
+Suppression leaves storage and Metadata unchanged and records a notice. It
+does not automatically write content, schedule a retry, or converge path
+spelling. A later scan or event may reconcile the state, subject to its own
+policy. The storage lookup may be a host index rather than an operating-system
+existence check: the observation is made under the application lock, not in
+an atomic filesystem transaction.
+
+## Verification and scope
+
+Focused unit tests cover a current canonical file, absence, lookup failure,
+distinct document IDs, an excluded same-ID file without inferred rename
+intent, retained rename destinations, transient collision rejection,
+deliberate exclusion, and source recreation. Live and restored deletions are
+exercised separately. A database-to-storage test also verifies that an
+incoming logical deletion can still remove unchanged storage content.
+
+These tests do not establish the native watcher event sequence reported in
+Issue 1168. Real-runtime verification belongs to the host and must distinguish
+observed events from inferred causes. This change does not promise path-case
+convergence or full folder-rename support. It does not rewrite the queue,
+introduce a retry subsystem, or change the database schema.
+
+The maintained host's real-runtime comparison is recorded in
+[Proven in maintained hosts](proven-in-use.md#obsidian-plug-in), separately
+from these unit-test guarantees.
+
+## Related documents
+
+- [Full offline scan](offline-scanner.md), especially [Stored event interpretation](offline-scanner.md#stored-event-interpretation).
+- [Conflict resolution and file provenance](conflict-resolution.md).
+- [Commonlib development](development.md).

package/package.json

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