@vrtmrz/livesync-commonlib 0.1.21 → 0.1.22

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/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,7 +349,7 @@ 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>;
     isTargetFileInExtra(file: string | UXFileInfoStub): Promise<boolean>;

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.

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.

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/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.
 

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/package.json

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