@vrtmrz/livesync-commonlib 0.2.0 → 0.2.2

package/dist/serviceModules/ServiceFileHandlerBase.js

@@ -1,9 +1,9 @@
 import { LOG_LEVEL_INFO, LOG_LEVEL_NOTICE, LOG_LEVEL_VERBOSE } from "octagonal-wheels/common/logger";
 import { serialized } from "octagonal-wheels/concurrency/lock";
 import {
+  createBlob,
   getDocDataAsArray,
   isDocContentSame,
-  readAsBlob,
   readContent
 } from "../common/utils.js";
 import { computeFileContentHash } from "../common/fileContentHash.js";
@@ -158,7 +158,7 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
    * A valid saved content hash can prove unchanged bytes after revision
    * pruning. It cannot reconstruct ancestry for an edited file.
    */
-  async classifyStorageContent(file, currentEntry, preferredPath, recorded, currentLoaded) {
+  async classifyStorageContent(file, currentEntry, preferredPath, recorded, currentLoaded, requireReadableContent = false) {
     const path = preferredPath ?? file.path;
     const recordedRevision = recorded?.revision;
     if (recordedRevision) {
@@ -173,6 +173,9 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       }
       if (!base) {
         const meta = await this.db.fetchEntryMeta(file, recordedRevision, true);
+        if (requireReadableContent && meta && !meta.deleted && !meta._deleted) {
+          throw new Error(`Could not read the recorded file revision for ${file.path}`);
+        }
         if ((!meta || meta.deleted || meta._deleted) && !hasContentHash(recorded)) await this.deleteProvenance(path);
       }
     }
@@ -189,13 +192,15 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
   /**
    * Read the raw provenance value used by an optimistic storage snapshot.
    * Unlike `getProvenance`, this does not validate or remove the referenced
-   * database revision; an unreadable value is represented as `undefined`.
+   * database revision. Recovery callers require a readable value so a store
+   * failure cannot be mistaken for absent provenance.
    */
-  async readProvenanceSnapshot(path) {
+  async readProvenanceSnapshot(path, requireReadable = false) {
     try {
       const record = await this.fileReflectionProvenance?.get(this.getProvenancePath(path));
       return record ? { ...record } : void 0;
-    } catch {
+    } catch (error) {
+      if (requireReadable) throw error;
       return void 0;
     }
   }
@@ -203,20 +208,20 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
    * Check that storage still has the same path, bytes, timestamp, and
    * provenance as a previously captured snapshot.
    */
-  async currentStorageSnapshotMatches(file, revision) {
+  async currentStorageSnapshotMatches(file, revision, requireReadableProvenance = false) {
     const current = await this.storage.getStub(file.path);
     if (!current || isFolderInfo(current) || current.path !== file.path) return false;
     const readCurrent = await this.readFileFromStub(current);
-    return readCurrent.stat.mtime === file.stat.mtime && await isDocContentSame(readCurrent.body, file.body) && sameProvenance(await this.readProvenanceSnapshot(file.path), revision);
+    return readCurrent.stat.mtime === file.stat.mtime && await isDocContentSame(readCurrent.body, file.body) && sameProvenance(await this.readProvenanceSnapshot(file.path, requireReadableProvenance), revision);
   }
   /**
    * Publish provenance after a durable database write if storage is unchanged.
    * A failed revalidation leaves the database revision stored and asks the
    * caller to reread storage before proceeding.
    */
-  async finaliseStoredRevision(file, observedProvenance, storedRevision) {
+  async finaliseStoredRevision(file, observedProvenance, storedRevision, requireReadableProvenance = false) {
     const evidence = await this.contentEvidence(file.body);
-    if (await this.currentStorageSnapshotMatches(file, observedProvenance)) {
+    if (await this.currentStorageSnapshotMatches(file, observedProvenance, requireReadableProvenance)) {
       await this.setProvenance(file.path, storedRevision, file.stat.mtime, file.body, evidence);
       return true;
     } else {
@@ -253,6 +258,27 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
     }
     return readFile;
   }
+  async canSkipUnchangedFile(info, expected) {
+    const path = getStoragePathFromUXFileInfo(info);
+    const provenance = this.fileReflectionProvenance;
+    if (!provenance || !expected._rev || expected.deleted || expected._deleted || expected._conflicts?.length || this.storage.hasPendingFileEvent?.(path) !== false) return false;
+    try {
+      return await this.serializedByFileEventPaths([path], async () => {
+        const provenancePath = this.getProvenancePath(path);
+        const record = await provenance.get(provenancePath);
+        if (!record || !hasContentHash(record) || record.revision !== expected._rev || !Number.isFinite(record.observedStorageMtime) || record.observedStorageMtime !== info.stat.mtime || record.contentSize !== info.stat.size) return false;
+        const current = await this.db.fetchEntryMeta(path, void 0, true);
+        if (!current || current._rev !== record.revision || current.deleted || current._deleted || (await this.db.getConflictedRevs(path)).length > 0) return false;
+        const stat = await this.storage.stat(path);
+        if (!stat || stat.type !== "file" || stat.mtime !== record.observedStorageMtime || stat.size !== record.contentSize) return false;
+        return sameProvenance(await provenance.get(provenancePath), record) && this.storage.hasPendingFileEvent?.(path) === false;
+      });
+    } catch (error) {
+      this._log(`Could not inspect unchanged file metadata for ${path}`, LOG_LEVEL_VERBOSE);
+      this._log(error, LOG_LEVEL_VERBOSE);
+      return false;
+    }
+  }
   async tryRecordUntrackedFileRevision(info, expectedRevision) {
     if (!this.fileReflectionProvenance || !expectedRevision) return false;
     const path = getStoragePathFromUXFileInfo(info);
@@ -293,10 +319,10 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
     const file = typeof info === "string" ? await this.storage.getFileStub(info) : info;
     return file;
   }
-  async storeFileToDB(info, force = false, onlyChunks = false) {
+  async storeFileToDB(info, force = false, onlyChunks = false, options = {}) {
     return await this.serializedByFileEventPaths(
       [getStoragePathFromUXFileInfo(info)],
-      () => this.storeFileToDBFromRevision(info, force, onlyChunks)
+      () => this.storeFileToDBFromRevision(info, force, onlyChunks, void 0, options.revalidateStorage)
     );
   }
   async storeFileToDBWithBaseRevision(info, baseRevision, createIfDifferent = true) {
@@ -366,8 +392,8 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
   /**
    * Save one storage snapshot while the caller holds its document lock.
    * Ordinary saves read once inside the lock and leave retries disabled.
-   * Restored startup events retain bounded rereads because file watching has
-   * not yet started and cannot supply a new event for a concurrent edit.
+   * Restored start-up events and recovery scans retain bounded rereads
+   * because a watcher event may not cover a concurrent edit.
    */
   async storeFileToDBFromRevision(info, force = false, onlyChunks = false, preferredBasePath, retryIfStorageChanges = false, snapshotRetry = 0) {
     const file = await this.infoToStub(info);
@@ -387,32 +413,36 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       return await this.db.createChunks(readFile2, force, true);
     }
     const observedProvenance = await this.readProvenanceSnapshot(
-      preferredBasePath ?? file.path
+      preferredBasePath ?? file.path,
+      retryIfStorageChanges
     );
     const readFile = await this.readFileFromStub(file);
     const entry = await this.db.fetchEntry(file, void 0, true, true, true);
     const currentEntry = entry || await this.db.fetchEntryMeta(file, void 0, true);
     const conflictedRevs = await this.db.getConflictedRevs(file);
     const isConflicted = conflictedRevs.length > 0;
-    if (!force && currentEntry && !currentEntry.deleted && !currentEntry._deleted) {
+    const currentIsLive = currentEntry && !currentEntry.deleted && !currentEntry._deleted;
+    if (!force && (currentIsLive || retryIfStorageChanges)) {
+      if (retryIfStorageChanges && currentIsLive && !entry) return false;
       const classification = await this.classifyStorageContent(
         readFile,
         currentEntry,
         preferredBasePath,
         observedProvenance,
-        entry ? { _rev: entry._rev, data: readContent(entry) } : void 0
+        entry ? { _rev: entry._rev, data: readContent(entry) } : void 0,
+        retryIfStorageChanges
       );
-      const upgradeCurrentRecord = classification.kind === "unchanged" && !isConflicted && classification.revision === currentEntry._rev && !hasContentHash(observedProvenance);
+      const upgradeCurrentRecord = classification.kind === "unchanged" && !isConflicted && currentEntry && !currentEntry.deleted && !currentEntry._deleted && classification.revision === currentEntry._rev && !hasContentHash(observedProvenance);
       const evidence = upgradeCurrentRecord || classification.kind === "matching-leaf" && classification.revision ? await this.contentEvidence(readFile.body) : void 0;
-      const snapshotMatches = retryIfStorageChanges || upgradeCurrentRecord ? await this.currentStorageSnapshotMatches(readFile, observedProvenance) : true;
+      const snapshotMatches = retryIfStorageChanges || upgradeCurrentRecord ? await this.currentStorageSnapshotMatches(readFile, observedProvenance, retryIfStorageChanges) : true;
       if (retryIfStorageChanges && !snapshotMatches) {
         return await this.retryCurrentStorage(file.path, preferredBasePath, snapshotRetry);
       }
       if (classification.kind === "unchanged") {
         if (isConflicted) {
           await this.queueConflictCheckFor(file.path);
-        } else if (classification.revision !== currentEntry._rev) {
-          if (!entry) return false;
+        } else if (!currentEntry || currentEntry.deleted || currentEntry._deleted || classification.revision !== currentEntry._rev) {
+          if (!currentEntry) return false;
           return await this.dbToStorageCore(file.path, file);
         } else {
           if (upgradeCurrentRecord && snapshotMatches) {
@@ -430,7 +460,7 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       const storedRevision2 = classification.kind === "edited" ? await this.db.storeWithBaseRevision(readFile, classification.revision, true) : await this.db.storeIndependentRevision(readFile, true);
       if (storedRevision2 === false) return false;
       if (preferredBasePath && preferredBasePath !== file.path) await this.deleteProvenance(preferredBasePath);
-      if (retryIfStorageChanges && !await this.finaliseStoredRevision(readFile, observedProvenance, storedRevision2)) {
+      if (retryIfStorageChanges && !await this.finaliseStoredRevision(readFile, observedProvenance, storedRevision2, true)) {
         return await this.retryCurrentStorage(file.path, preferredBasePath, snapshotRetry);
       }
       if (!retryIfStorageChanges) await this.setProvenance(file.path, storedRevision2, readFile.stat.mtime, readFile.body);
@@ -519,6 +549,12 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       () => this.deleteFileFromDBCore(info)
     );
   }
+  /** Complete a validated storage deletion when its database effect is already represented. */
+  async deleteFileFromDBIfPresent(info) {
+    const entry = await this.db.fetchEntryMeta(info, void 0, true);
+    if (!entry || entry.deleted || entry._deleted) return true;
+    return await this.deleteFileFromDBCore(info);
+  }
   /**
    * Record a storage deletion under the caller's document lock, preserving
    * the displayed conflict branch when its provenance is known.
@@ -892,17 +928,17 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       this._log(`File ${path} is not exist on the database`, LOG_LEVEL_VERBOSE);
       return false;
     }
+    const docData = readContent(docRead);
+    const reflectedContent = createBlob(docData);
     if (!settings.processSizeMismatchedFiles) {
-      if (docRead.size != 0 && docRead.size !== readAsBlob(docRead).size) {
+      if (docRead.size != 0 && docRead.size !== reflectedContent.size) {
         this._log(
-          `File ${path} seems to be corrupted! Writing prevented. (${docRead.size} != ${readAsBlob(docRead).size})`,
+          `File ${path} seems to be corrupted! Writing prevented. (${docRead.size} != ${reflectedContent.size})`,
           LOG_LEVEL_NOTICE
         );
         return false;
       }
     }
-    const docData = readContent(docRead);
-    const reflectedContent = readAsBlob(docRead);
     const reflectedEvidence = await this.contentEvidence(reflectedContent);
     if (allowExistingConflicts && existDoc && !force) {
       const readFile = await this.readFileFromStub(existDoc);
@@ -1080,14 +1116,23 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
     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 () => {
-      if (!await this.isCurrentPathSelected(path)) return false;
+      if (!await this.isCurrentPathSelected(path)) {
+        return shouldBeIgnored(path) || !await this.vault.isTargetFile(path, { skipCaseCollisionCheck: true });
+      }
       switch (type) {
         case "CREATE":
-        case "CHANGED":
-          return await this.storeFileToDBFromRevision(item.args.file);
+        case "CHANGED": {
+          const current = this.getExactCurrentFile(await this.storage.getStub(path), path);
+          if (!current || this.vault.isFileSizeTooLarge(current.stat.size)) return true;
+          return await this.storeFileToDBFromRevision(current);
+        }
         case "DELETE":
-          if (!await this.canRecordStorageDeletion(item)) return true;
-          return await this.deleteFileFromDBCore(item.args.file);
+          try {
+            if (!await this.canRecordStorageDeletion(item)) return true;
+          } catch {
+            return false;
+          }
+          return await this.deleteFileFromDBIfPresent(item.args.file);
         case "RENAME":
           return await this.renameFileInDBCore(
             item.args.file,
@@ -1137,7 +1182,7 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
     } 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;
+      throw ex;
     }
   }
   /**
@@ -1222,15 +1267,19 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
         action = await this._planRestoredFileEvent(item, isSameDocument);
       } catch (ex) {
         this.logRestoredEventValidationFailure(path, ex);
-        return true;
+        return false;
       }
       switch (action.kind) {
         case "none":
           return true;
-        case "store":
-          return await this.storeFileToDBFromRevision(action.file, false, false, void 0, true);
+        case "unresolved":
+          return false;
+        case "store": {
+          const stored = await this.storeFileToDBFromRevision(action.file, false, false, void 0, true);
+          return stored && action.complete !== false;
+        }
         case "delete":
-          return await this.deleteFileFromDBCore(action.path);
+          return await this.deleteFileFromDBIfPresent(action.path);
         case "rename":
           return await this.renameFileInDBCore(action.file, action.oldPath, true);
       }
@@ -1266,6 +1315,10 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       if (!currentTarget2 || !await this.isCurrentFileSelected(currentTarget2)) {
         return { kind: "none" };
       }
+      const entry = await this.db.fetchEntryMeta(newPath, void 0, true);
+      if (entry && !entry.deleted && !entry._deleted && this.storage.normalisePath(this.getPath(entry)) === this.storage.normalisePath(newPath)) {
+        return { kind: "store", file: currentTarget2 };
+      }
       return { kind: "rename", file: currentTarget2, oldPath };
     }
     const currentTargetItem = await this.storage.getStub(newPath);
@@ -1283,11 +1336,16 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
         return { kind: "none" };
       }
       if (!sourceWasInspected || currentSourceItem !== null || !await this.canApplyRestoredDeletion(oldPath)) {
+        return { kind: "store", file: currentTarget, complete: sourceWasInspected };
+      }
+      const sourceEntry = await this.db.fetchEntryMeta(oldPath, void 0, true);
+      if (!sourceEntry || sourceEntry.deleted || sourceEntry._deleted) {
         return { kind: "store", file: currentTarget };
       }
       return { kind: "rename", file: currentTarget, oldPath };
     }
-    if (!sourceWasInspected || currentSourceItem !== null || !await this.canApplyRestoredDeletion(oldPath)) {
+    if (!sourceWasInspected) return { kind: "unresolved" };
+    if (currentSourceItem !== null || !await this.canApplyRestoredDeletion(oldPath)) {
       return { kind: "none" };
     }
     return { kind: "delete", path: oldPath };
@@ -1324,12 +1382,12 @@ class ServiceFileHandlerBase extends ServiceModuleBase {
       return await this.isCurrentPathSelected(path);
     } catch (ex) {
       this.logRestoredEventValidationFailure(path, ex);
-      return false;
+      throw ex;
     }
   }
   logRestoredEventValidationFailure(path, ex) {
     this._log(
-      `Could not validate the saved storage operation for ${path} against current storage; the Offline Scanner will reconcile the current state`,
+      `Could not validate the saved storage operation for ${path} against current storage; the operation remains pending for recovery`,
       LOG_LEVEL_NOTICE
     );
     this._log(ex, LOG_LEVEL_VERBOSE);

package/dist/services/base/AppLifecycleService.js

@@ -60,7 +60,7 @@ class AppLifecycleService extends ServiceBase {
    * Event triggered before the plug-in is unloaded.
    * This is typically used to perform any necessary cleanup or save state before the plug-in is unloaded.
    */
-  onBeforeUnload = handlers().all("onBeforeUnload");
+  onBeforeUnload = handlers().allSettled("onBeforeUnload");
   /**
    * Event triggered when the plug-in is being unloaded.
    *

package/dist/services/base/ControlService.js

@@ -40,7 +40,9 @@ class ControlService extends ServiceBase {
     await this.services.appLifecycleService.onSuspending();
     await this.services.settingService.onBeforeRealiseSetting();
     this.services.databaseService.localDatabase.refreshSettings();
-    await this.services.fileProcessingService.commitPendingFileEvents();
+    if (!await this.services.fileProcessingService.commitPendingFileEvents()) {
+      throw new Error("Pending local file operations could not be completed before applying settings");
+    }
     await this.services.settingService.onRealiseSetting();
     if (this.services.appLifecycleService.isSuspended()) return;
     await this.services.appLifecycleService.onResuming();
@@ -49,7 +51,8 @@ class ControlService extends ServiceBase {
   }
   async _onLiveSyncUnload() {
     this.context.events.emitEvent(EVENT_PLUGIN_UNLOADED);
-    await this.services.appLifecycleService.onBeforeUnload();
+    const prepared = await this.services.appLifecycleService.onBeforeUnload();
+    if (!prepared) this._log("Unload preparation failed; pending storage work may require recovery", LOG_LEVEL_URGENT);
     await Promise.resolve(this.services.appLifecycleService.onAppUnload());
     cancelAllPeriodicTask();
     cancelAllTasks();
@@ -64,6 +67,7 @@ class ControlService extends ServiceBase {
     this.context.events.emitEvent(EVENT_PLATFORM_UNLOADED);
     this.context.events.offAll();
     this._log(this.context.translate("moduleLiveSyncMain.logUnloadingPlugin"));
+    if (!prepared) throw new Error("Unload preparation failed");
     return;
   }
   /**

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").MultipleHandlerFunction<(showingNotice?: boolean, reopenDatabase?: boolean, ignoreSuspending?: boolean, continueOnFileFailure?: boolean) => Promise<import("./VaultScanResult.js").VaultScanResult>, unknown>;
+    readonly initialiseDatabase: import("../lib/HandlerUtils.js").MultipleHandlerFunction<(showingNotice?: boolean, reopenDatabase?: boolean, ignoreSuspending?: boolean, continueOnFileFailure?: boolean, scanOptions?: import("./VaultScanResult.js").VaultScanOptions) => Promise<import("./VaultScanResult.js").VaultScanResult>, unknown>;
 }

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

@@ -9,10 +9,16 @@ export declare class FileProcessingService<T extends ServiceContext = ServiceCon
      */
     readonly processFileEvent: import("../lib/HandlerUtils.js").BooleanMultipleHandlerFunction<(item: import("../../common/types.js").FileEventItem) => Promise<boolean>>;
     /**
-     * Process a file event item optionally, if any handler is registered.
+     * Dispatch a legacy optional notification, without confirming persistence.
      * i.e., hidden files synchronisation or customisation sync.
      */
     readonly processOptionalFileEvent: import("../lib/HandlerUtils.js").BooleanMultipleHandlerFunction<(path: import("../../common/types.js").FilePath) => Promise<boolean>>;
+    /**
+     * Complete optional file operations through the first applicable handler.
+     * Hosts migrate all optional providers together. Once any typed provider is
+     * registered, dispatch uses this contract exclusively.
+     */
+    readonly processOptionalFileEventWithResult?: import("../lib/HandlerUtils.js").FirstHandledFunction<(path: import("../../common/types.js").FilePath, options?: import("./IService.js").OptionalFileEventOptions) => Promise<import("../lib/HandlerUtils.js").HandlerOutcome<void, string>>>;
     /**
      * Commit any pending file events that have been queued for processing.
      */

package/dist/services/base/FileProcessingService.js

@@ -7,10 +7,18 @@ class FileProcessingService extends ServiceBase {
    */
   processFileEvent = handlers().anySuccess("processFileEvent");
   /**
-   * Process a file event item optionally, if any handler is registered.
+   * Dispatch a legacy optional notification, without confirming persistence.
    * i.e., hidden files synchronisation or customisation sync.
    */
   processOptionalFileEvent = handlers().anySuccess("processOptionalFileEvent");
+  /**
+   * Complete optional file operations through the first applicable handler.
+   * Hosts migrate all optional providers together. Once any typed provider is
+   * registered, dispatch uses this contract exclusively.
+   */
+  processOptionalFileEventWithResult = handlers().firstHandled(
+    "processOptionalFileEventWithResult"
+  );
   /**
    * Commit any pending file events that have been queued for processing.
    */

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

@@ -16,8 +16,8 @@ import type { OwnedCouchDBConnection, RemoteConnectionOpenOptions } from "./Remo
 import type { ActiveReplicatorContext, ContinuousReplicationRequest, ReplicationAttemptFailure, ReplicationFailureRequest, ReplicatorProviderDefinitionMap, ReplicationOutcome, ReplicationReadinessRequirements, UnattendedOneShotRequest, UserInitiatedOneShotRequest } from "../../replication/ReplicatorProvider.js";
 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";
+import type { HandlerOutcome, MultipleHandlerFunction } from "../lib/HandlerUtils.js";
+import type { VaultScanResult, VaultScanOptions } from "./VaultScanResult.js";
 import type { UICommandRegistry } from "../../uiCommands.js";
 declare global {
     interface OPTIONAL_SYNC_FEATURES {
@@ -91,15 +91,23 @@ export interface IDatabaseEventService {
     onDatabaseInitialised(showNotice: boolean): Promise<boolean>;
     onDatabaseHasReady(): Promise<boolean>;
     onResetDatabase(db: LiveSyncLocalDB): Promise<boolean>;
-    initialiseDatabase(showingNotice?: boolean, reopenDatabase?: boolean, ignoreSuspending?: boolean, continueOnFileFailure?: boolean): Promise<VaultScanResult>;
+    initialiseDatabase(showingNotice?: boolean, reopenDatabase?: boolean, ignoreSuspending?: boolean, continueOnFileFailure?: boolean, scanOptions?: VaultScanOptions): Promise<VaultScanResult>;
 }
 export interface IKeyValueDBService {
     openSimpleStore<T>(kind: string): SimpleStore<T>;
     simpleStore: SimpleStore<unknown>;
 }
+/** Options for completing an admitted optional file event. */
+export interface OptionalFileEventOptions {
+    /** Resolves when a finite flush needs this event to finish without its debounce delay. */
+    whenFlushRequested?: Promise<void>;
+}
 export interface IFileProcessingService {
     processFileEvent(item: FileEventItem): Promise<boolean>;
+    /** Legacy notification contract; its boolean does not confirm persistence. */
     processOptionalFileEvent(path: FilePath): Promise<boolean>;
+    /** Complete the actual optional file operation, or explain why it is not completed. */
+    processOptionalFileEventWithResult?(path: FilePath, options?: OptionalFileEventOptions): Promise<HandlerOutcome<void, string>>;
     commitPendingFileEvents(): Promise<boolean>;
     batched: ReactiveSource<number>;
     processing: ReactiveSource<number>;
@@ -347,7 +355,7 @@ export interface ITweakValueService {
 export interface IVaultService {
     vaultName(): string;
     getVaultName(): string;
-    scanVault(showingNotice?: boolean, ignoreSuspending?: boolean, continueOnFileFailure?: boolean): Promise<VaultScanResult>;
+    scanVault(showingNotice?: boolean, ignoreSuspending?: boolean, continueOnFileFailure?: boolean, scanOptions?: VaultScanOptions): Promise<VaultScanResult>;
     isIgnoredByIgnoreFile(file: string | UXFileInfoStub): Promise<boolean>;
     isTargetFile(file: string | UXFileInfoStub, 
     /** Inspect selection policy without treating a filename collision as an exclusion. */

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

@@ -125,5 +125,6 @@ export declare abstract class ReplicatorService<T extends ServiceContext = Servi
         lastSyncPullSeq: number;
         lastSyncPushSeq: number;
         syncStatus: import("../../common/types.js").DatabaseConnectingStatus;
+        couchDB?: import("../../common/models/shared.definition.js").CouchDBReplicationProgress;
     }>;
 }

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

@@ -10,4 +10,9 @@ export declare const VaultScanResults: {
     readonly COMPLETED: true;
     readonly COMPLETED_WITH_FILE_FAILURES: "completed-with-file-failures";
 };
+/** Optional policy for an ordinary scan; omitted options retain strict content checks. */
+export interface VaultScanOptions {
+    /** False permits unchanged tracked files to be skipped using storage and revision metadata. */
+    strictContentCheck?: boolean;
+}
 export type VaultScanResult = (typeof VaultScanResults)[keyof typeof 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").MultipleHandlerFunction<(showingNotice?: boolean, ignoreSuspending?: boolean, continueOnFileFailure?: boolean) => Promise<import("./VaultScanResult.js").VaultScanResult>, unknown>;
+    readonly scanVault: import("../lib/HandlerUtils.js").MultipleHandlerFunction<(showingNotice?: boolean, ignoreSuspending?: boolean, continueOnFileFailure?: boolean, scanOptions?: import("./VaultScanResult.js").VaultScanOptions) => 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/lib/HandlerUtils.d.ts

@@ -2,6 +2,27 @@
  * A function type that can be used as a handler.
  */
 type HandlerFunc<TArg extends unknown[], TResult> = (...args: TArg) => TResult | Promise<TResult>;
+/**
+ * The outcome of a handler.
+ *
+ * A completed outcome carries a value when `TValue` is not void, and a veto
+ * carries a reason when `TVetoReason` is not void. Not-applicable outcomes
+ * always continue to the next registered handler.
+ */
+export type HandlerOutcome<TValue = void, TVetoReason = void> = {
+    kind: "not-applicable";
+} | ([TValue] extends [void] ? {
+    kind: "completed";
+} : {
+    kind: "completed";
+    value: TValue;
+}) | ([TVetoReason] extends [void] ? {
+    kind: "veto";
+} : {
+    kind: "veto";
+    value: TVetoReason;
+});
+type AnyHandlerOutcome = HandlerOutcome | HandlerOutcome<unknown, unknown>;
 /**
  * A function type that returns a boolean or a Promise of boolean.
  */
@@ -244,6 +265,29 @@ export declare class FirstResultHandler<T extends unknown[], U> extends MultiBin
      */
     invoke(...args: T): Promise<U | false>;
 }
+/**
+ * Invokes registered handlers in priority and registration order until one
+ * completes or vetoes. Each invocation uses a snapshot of registrations.
+ * Callback errors and rejections propagate unchanged, and registrations are
+ * owned by this handler.
+ */
+export declare class FirstHandledHandler<T extends unknown[], U extends AnyHandlerOutcome = HandlerOutcome> extends MultiBinder<HandlerFunc<T, U>> implements InvokableHandler<T, U | {
+    kind: "not-applicable";
+}> {
+    /**
+     * Whether at least one callback is currently registered.
+     */
+    get hasHandlers(): boolean;
+    /**
+     * Invokes handlers until one returns a completed or veto outcome.
+     * @param args The arguments to pass to the handlers.
+     * @returns The first handled outcome, or a not-applicable outcome when no handler applies.
+     * @throws Any synchronous callback error or rejected callback value, unchanged.
+     */
+    invoke(...args: T): Promise<U | {
+        kind: "not-applicable";
+    }>;
+}
 /**
  * A function type that can be used as a handler with assignable functionality.
  */
@@ -297,6 +341,11 @@ export interface MultipleHandlerFunction<TFunc extends (...args: any[]) => U | P
      */
     removeHandler: (callback: TFunc) => void;
 }
+export type FirstHandledFunction<TFunc extends (...args: any[]) => AnyHandlerOutcome | Promise<AnyHandlerOutcome>> = ((...args: Parameters<TFunc>) => Promise<Awaited<ReturnType<TFunc>> | {
+    kind: "not-applicable";
+}>) & Pick<MultipleHandlerFunction<TFunc>, "addHandler" | "removeHandler"> & {
+    readonly hasHandlers: boolean;
+};
 /**
  * A function type that can be used as a value-collecting handler with add/remove functionality.
  */
@@ -351,12 +400,16 @@ export declare function bailFirstFailureWithResultFunction<TFunc extends (...arg
 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>;
+export declare function firstHandledFunction<TFunc extends (...args: any[]) => AnyHandlerOutcome | Promise<AnyHandlerOutcome>>(name?: string): FirstHandledFunction<TFunc>;
 export declare function dispatchParallelFunction<TFunc extends (...args: any[]) => Promise<unknown[]>>(name?: string): CollectiveHandlerFunction<TFunc>;
 export declare function bindableFunction<TFunc extends (...args: any[]) => any>(name?: string): HandlerFunction<TFunc>;
 export declare function lazyBindableFunction<TFunc extends (...args: any[]) => any>(name?: string): LazyHandlerFunction<TFunc>;
 type FunctionKeys<T> = Extract<{
     [K in keyof T]: T[K] extends (...args: any[]) => any ? K : never;
 }[keyof T], string>;
+type FirstHandledFunctionKeys<T> = Extract<{
+    [K in keyof T]: [NonNullable<T[K]>] extends [never] ? never : NonNullable<T[K]> extends (...args: any[]) => AnyHandlerOutcome | Promise<AnyHandlerOutcome> ? K : never;
+}[keyof T], string>;
 export declare function handlers<T extends object>(): {
     /**
      * Create a handler that invokes all added handler functions sequentially until one returns false.
@@ -403,6 +456,13 @@ export declare function handlers<T extends object>(): {
      * @returns
      */
     firstResult<K extends FunctionKeys<T>>(name: K): MultipleHandlerFunction<Extract<T[K], (...args: any[]) => Promise<unknown>>>;
+    /**
+     * Create a handler that invokes registered handlers until one completes or vetoes.
+     * Callback errors and rejections propagate unchanged.
+     * @param name The name of the callback on `T`.
+     * @returns A bound handler with a live `hasHandlers` property.
+     */
+    firstHandled<K extends FirstHandledFunctionKeys<T>>(name: K): FirstHandledFunction<Extract<NonNullable<T[K]>, (...args: any[]) => AnyHandlerOutcome | Promise<AnyHandlerOutcome>>>;
     /**
      * Create a handler that invokes all added handler functions in parallel.
      * @param name