@vrtmrz/livesync-commonlib 0.2.0 → 0.2.2

package/dist/replication/couchdb/LiveSyncReplicator.js

@@ -1,3 +1,4 @@
+import { observeReplicationProgress } from "./replicationProgress.js";
 import {
   VER,
   MILESTONE_DOCID,
@@ -122,6 +123,24 @@ class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicator {
   continuousTask;
   continuousStopWaiter;
   continuousStopRequested = false;
+  continuousPhase;
+  couchDBProgress;
+  getReplicationStatics() {
+    return {
+      ...super.getReplicationStatics(),
+      ...this.couchDBProgress ? { couchDB: this.couchDBProgress } : {}
+    };
+  }
+  publishPreparationPhase(phase) {
+    this.continuousPhase = phase;
+    this.couchDBProgress = { phase };
+    this.updateInfo();
+  }
+  finishReplicationProgress() {
+    if (!this.couchDBProgress || this.couchDBProgress.phase === "idle") return;
+    this.couchDBProgress = { ...this.couchDBProgress, phase: "idle" };
+    this.updateInfo();
+  }
   isMobile() {
     return this.env.services.API.isMobile();
   }
@@ -241,6 +260,7 @@ class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicator {
       this.continuousStopRequested = true;
     }
     this.abortController();
+    this.finishReplicationProgress();
     if (!task) {
       return Promise.resolve();
     }
@@ -352,6 +372,17 @@ class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicator {
       this.controller.abort();
     }
     this.controller = controller;
+    const progress = observeReplicationProgress(
+      syncHandler,
+      syncMode,
+      this.continuousPhase ?? "one-shot",
+      controller.signal,
+      (snapshot) => {
+        if (this.controller !== controller) return;
+        this.couchDBProgress = snapshot;
+        this.updateInfo();
+      }
+    );
     const gen = genReplication(syncHandler, controller.signal);
     try {
       for await (const [type, e] of gen) {
@@ -361,6 +392,7 @@ class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicator {
           return "FAILED";
         }
         releaser();
+        if (controller.signal.aborted || this.controller !== controller) break;
         switch (type) {
           case "change":
             if ("direction" in e) {
@@ -440,8 +472,9 @@ class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicator {
       Logger(ex, LOG_LEVEL_VERBOSE);
       return "FAILED";
     } finally {
-      this.abortController();
-      this.controller = void 0;
+      progress.dispose();
+      controller.abort();
+      if (this.controller === controller) this.controller = void 0;
     }
   }
   getEmptyMaxEntry(remoteID) {
@@ -1118,6 +1151,8 @@ ${sendingDocs}/(${sentDocsCount} done)`,
     if (this.continuousTask !== task) {
       return;
     }
+    this.finishReplicationProgress();
+    this.continuousPhase = void 0;
     this.continuousTask = void 0;
     this.continuousStopWaiter = void 0;
     this.continuousStopRequested = false;
@@ -1131,6 +1166,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
         );
         return false;
       }
+      this.publishPreparationPhase("catch-up");
       const localDB = this.rawDatabase;
       Logger(this.translate("liveSyncReplicator.beforeLiveSync"));
       const caughtUp = await this.env.services.replicator.runFiniteReplicationActivity(
@@ -1146,6 +1182,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
         { label: "replication" }
       );
       if (caughtUp && !this.continuousStopRequested) {
+        this.publishPreparationPhase("continuous");
         Logger(this.translate("liveSyncReplicator.liveSyncBegin"));
         const ret = await this.checkReplicationConnectivity(setting, true, false, showResult);
         if (ret === false || this.continuousStopRequested) {

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

@@ -0,0 +1,6 @@
+import type { EntryDoc } from "../../common/types.js";
+import type { CouchDBReplicationPhase, CouchDBReplicationProgress } from "../../common/models/shared.definition.js";
+/** Observe one handler without adding its high-volume checkpoint events to the replication inbox. */
+export declare function observeReplicationProgress(handler: PouchDB.Replication.Sync<EntryDoc> | PouchDB.Replication.Replication<EntryDoc>, mode: "sync" | "pullOnly" | "pushOnly", phase: Exclude<CouchDBReplicationPhase, "idle">, signal: AbortSignal, publish: (progress: CouchDBReplicationProgress) => void): {
+    dispose(): void;
+};

package/dist/replication/couchdb/replicationProgress.js

@@ -0,0 +1,105 @@
+import { compatGlobal } from "../../common/coreEnvFunctions.js";
+const PROGRESS_PUBLICATION_INTERVAL_MS = 200;
+function asEmitter(value) {
+  if (typeof value !== "object" || value === null) return void 0;
+  if (!("on" in value) || typeof value.on !== "function") return void 0;
+  if (!("removeListener" in value) || typeof value.removeListener !== "function") return void 0;
+  return value;
+}
+function isSequence(value) {
+  return typeof value === "string" || typeof value === "number" && Number.isFinite(value);
+}
+function observeReplicationProgress(handler, mode, phase, signal, publish) {
+  const progress = {};
+  const detach = [];
+  let timer;
+  let dirty = false;
+  let disposed = false;
+  let currentPhase = phase;
+  const cancelTimer = () => {
+    if (timer === void 0) return;
+    compatGlobal.clearTimeout(timer);
+    timer = void 0;
+  };
+  const flush = () => {
+    cancelTimer();
+    if (!dirty) return;
+    dirty = false;
+    publish({
+      phase: currentPhase,
+      ...progress.pull ? { pull: { ...progress.pull } } : {},
+      ...progress.push ? { push: { ...progress.push } } : {}
+    });
+  };
+  const schedule = () => {
+    dirty = true;
+    timer ??= compatGlobal.setTimeout(flush, PROGRESS_PUBLICATION_INTERVAL_MS);
+  };
+  const listen = (emitter, event, listener) => {
+    emitter.on(event, listener);
+    detach.push(() => emitter.removeListener(event, listener));
+  };
+  const observeDirection = (direction, emitter) => {
+    if (!emitter) return;
+    const value = { checkedChanges: 0, completedBatches: 0, checking: false };
+    progress[direction] = value;
+    listen(emitter, "checkpoint", (event) => {
+      if (disposed || signal.aborted || typeof event !== "object" || event === null) return;
+      if ("revs_diff" in event && typeof event.revs_diff === "object" && event.revs_diff !== null && "id" in event.revs_diff && typeof event.revs_diff.id === "string") {
+        value.checkedChanges++;
+        value.checking = true;
+      } else if ("start_next_batch" in event && isSequence(event.start_next_batch)) {
+        value.checking = true;
+      } else if ("checkpoint" in event && isSequence(event.checkpoint)) {
+        value.completedBatches++;
+        value.lastSeq = event.checkpoint;
+      } else {
+        return;
+      }
+      schedule();
+    });
+    const stopChecking = () => {
+      if (disposed || signal.aborted) return;
+      if (value.checking) {
+        value.checking = false;
+        dirty = true;
+      }
+      flush();
+    };
+    listen(emitter, "change", stopChecking);
+    listen(emitter, "paused", stopChecking);
+  };
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    cancelTimer();
+    for (const remove of detach) remove();
+    signal.removeEventListener("abort", dispose);
+    currentPhase = "idle";
+    if (progress.pull) progress.pull.checking = false;
+    if (progress.push) progress.push.checking = false;
+    dirty = true;
+    flush();
+  };
+  if (mode === "sync") {
+    const duplex = handler;
+    observeDirection("pull", asEmitter(duplex.pull));
+    observeDirection("push", asEmitter(duplex.push));
+  } else {
+    observeDirection(mode === "pullOnly" ? "pull" : "push", asEmitter(handler));
+  }
+  const outer = asEmitter(handler);
+  if (outer) {
+    listen(outer, "complete", dispose);
+    listen(outer, "error", dispose);
+    listen(outer, "denied", dispose);
+  }
+  signal.addEventListener("abort", dispose, { once: true });
+  dirty = true;
+  if (signal.aborted) dispose();
+  else flush();
+  return { dispose };
+}
+export {
+  observeReplicationProgress
+};

package/dist/replication/index.d.ts

@@ -12,3 +12,4 @@ export type { CentralCompatibilityRecoveryHint, CentralCompatibilityRejectionRea
 export { assessRemoteFeatureDocument, describeRemoteFeatureRejection, ENCRYPTED_INTERNAL_METADATA_FEATURE, NFC_PATH_IDENTITY_FEATURE, REMOTE_FEATURE_GENERATION, usesEncryptedInternalMetadata, } from "../pouchdb/remoteFeatureCompatibility.js";
 export type { RemoteFeatureAssessment } from "../pouchdb/remoteFeatureCompatibility.js";
 export type { JoinedDevice, JoinedDevicesSnapshot, ForgetJoinedDeviceResult } from "./joinedDevices.js";
+export type { ReplicationStatics, CouchDBReplicationPhase, CouchDBReplicationProgress, ReplicationCheckpointProgress, } from "../common/models/shared.definition.js";

package/dist/replication/trystero/TrysteroReplicator.d.ts

@@ -144,8 +144,10 @@ export declare class TrysteroReplicator {
         idDerivationVersion: 0 | 1;
         idDerivationProof: string;
         liveSync?: boolean;
+        batchSaveInLiveSync?: boolean;
         syncOnSave?: boolean;
         syncOnStart?: boolean;
+        strictContentCheckOnStartup?: boolean;
         syncOnFileOpen?: boolean;
         syncOnEditorSave?: boolean;
         keepReplicationActiveInBackground?: boolean;
@@ -332,8 +334,10 @@ export declare class TrysteroReplicator {
             idDerivationVersion: 0 | 1;
             idDerivationProof: string;
             liveSync?: boolean;
+            batchSaveInLiveSync?: boolean;
             syncOnSave?: boolean;
             syncOnStart?: boolean;
+            strictContentCheckOnStartup?: boolean;
             syncOnFileOpen?: boolean;
             syncOnEditorSave?: boolean;
             keepReplicationActiveInBackground?: boolean;

package/dist/serviceFeatures/offlineScanner.d.ts

@@ -3,7 +3,7 @@ import { type LogFunction } from "../services/lib/logUtils.js";
 import type { NecessaryServices } from "../interfaces/ServiceModule.js";
 import type { IPathService } from "../services/base/IService.js";
 import { UnresolvedErrorManager } from "../services/base/UnresolvedErrorManager.js";
-import { VaultScanResults, type VaultScanResult } from "../services/base/VaultScanResult.js";
+import { VaultScanResults, type VaultScanResult, type VaultScanOptions } from "../services/base/VaultScanResult.js";
 export { VaultScanResults };
 export type { VaultScanResult };
 /**
@@ -156,7 +156,7 @@ export declare function getPathFromEntry(host: {
  * @param file Storage file information
  * @param doc Database entry
  */
-export declare function syncFileBetweenDBandStorage(host: NecessaryServices<"setting" | "vault" | "path", "storageAccess" | "fileHandler">, log: LogFunction, file: UXFileInfoStub, doc: MetaEntry): Promise<FilePairProcessResult>;
+export declare function syncFileBetweenDBandStorage(host: NecessaryServices<"setting" | "vault" | "path", "storageAccess" | "fileHandler">, log: LogFunction, file: UXFileInfoStub, doc: MetaEntry, scanOptions?: VaultScanOptions): Promise<FilePairProcessResult>;
 export declare function canProceedScan(host: NecessaryServices<"keyValueDB" | "setting", never>, errorManager: UnresolvedErrorManager, log: LogFunction, showingNotice?: boolean, ignoreSuspending?: boolean): boolean;
 /**
  * Normalise the logical comparison key and lower case it when filename case should be handled insensitively.
@@ -180,7 +180,7 @@ export declare function collectDatabaseFiles(host: NecessaryServices<"database"
 }>;
 export declare function updateToDatabase(host: NecessaryServices<"vault", "fileHandler">, log: LogFunction, logLevel: LOG_LEVEL, file: UXFileInfoStub): Promise<FilePairProcessResult>;
 export declare function updateToStorage(host: NecessaryServices<"vault" | "path", "fileHandler">, log: LogFunction, logLevel: LOG_LEVEL, w: MetaEntry): Promise<FilePairProcessResult>;
-export declare function syncStorageAndDatabase(host: NecessaryServices<"setting" | "vault" | "path", "storageAccess" | "fileHandler">, log: LogFunction, file: UXFileInfoStub, logLevel: LOG_LEVEL, doc: MetaEntry): Promise<FilePairProcessResult>;
+export declare function syncStorageAndDatabase(host: NecessaryServices<"setting" | "vault" | "path", "storageAccess" | "fileHandler">, log: LogFunction, file: UXFileInfoStub, logLevel: LOG_LEVEL, doc: MetaEntry, scanOptions?: VaultScanOptions): Promise<FilePairProcessResult>;
 export declare const FullScanModes: {
     readonly DB_APPLY: "db-apply";
     readonly NEWER_WINS: "newer-wins";
@@ -205,7 +205,7 @@ export declare const ExtraOnLocal: {
      */
     readonly APPEND_STORAGE_ONLY: "append-storage-only";
 };
-export interface FullScanOptions {
+export interface FullScanOptions extends VaultScanOptions {
     mode: FullScanMode;
     extraOnLocal?: (typeof ExtraOnLocal)[keyof typeof ExtraOnLocal];
     extraOnRemote?: (typeof ExtraOnRemote)[keyof typeof ExtraOnRemote];

package/dist/serviceFeatures/offlineScanner.js

@@ -350,7 +350,7 @@ function getPathFromEntry(host, doc) {
   const path = host.services.path.getPath(doc);
   return path;
 }
-async function syncFileBetweenDBandStorage(host, log, file, doc) {
+async function syncFileBetweenDBandStorage(host, log, file, doc, scanOptions) {
   const docPath = getPathFromEntry(host, doc);
   if (!doc) {
     throw new Error(`Missing doc:${docPath}`);
@@ -360,8 +360,7 @@ async function syncFileBetweenDBandStorage(host, log, file, doc) {
     case BASE_IS_NEW:
       if (!host.services.vault.isFileSizeTooLarge(file.stat.size)) {
         log("STORAGE -> DB :" + file.path);
-        await host.serviceModules.fileHandler.storeFileToDB(file);
-        return FilePairProcessResults.COMPLETED;
+        return await host.serviceModules.fileHandler.storeFileToDB(file) ? FilePairProcessResults.COMPLETED : FilePairProcessResults.FAILED;
       } else {
         log(
           `STORAGE -> DB : ${file.path} has been skipped due to file size exceeding the limit`,
@@ -390,11 +389,26 @@ async function syncFileBetweenDBandStorage(host, log, file, doc) {
         return FilePairProcessResults.SKIPPED;
       }
     case EVEN:
-      if (doc._rev) {
-        await host.serviceModules.fileHandler.tryRecordUntrackedFileRevision(file, doc._rev);
+      if (host.services.vault.isFileSizeTooLarge(file.stat.size) || host.services.vault.isFileSizeTooLarge(doc.size)) {
+        log(`STORAGE ? DB : ${file.path} has been skipped due to file size exceeding the limit`, LOG_LEVEL_NOTICE);
+        return FilePairProcessResults.SKIPPED;
+      }
+      if (scanOptions?.strictContentCheck === false && await host.serviceModules.fileHandler.canSkipUnchangedFile?.(file, doc)) {
+        log(`STORAGE ? DB : ${file.path} skipped using unchanged storage and revision metadata`, LOG_LEVEL_DEBUG);
+        return FilePairProcessResults.SKIPPED;
+      }
+      if (doc._rev && await host.serviceModules.fileHandler.tryRecordUntrackedFileRevision(file, doc._rev)) {
+        log("STORAGE == DB :" + file.path, LOG_LEVEL_DEBUG);
+        return FilePairProcessResults.COMPLETED;
+      }
+      log("STORAGE ? DB :" + file.path + " Checking content", LOG_LEVEL_DEBUG);
+      try {
+        return await host.serviceModules.fileHandler.storeFileToDB(file, false, false, { revalidateStorage: true }) ? FilePairProcessResults.COMPLETED : FilePairProcessResults.FAILED;
+      } catch (error) {
+        log(`STORAGE ? DB : Could not reconcile ${file.path}`, LOG_LEVEL_NOTICE);
+        log(error, LOG_LEVEL_VERBOSE);
+        return FilePairProcessResults.FAILED;
       }
-      log("STORAGE == DB :" + file.path, LOG_LEVEL_DEBUG);
-      return FilePairProcessResults.COMPLETED;
     default:
       log("STORAGE ?? DB :" + file.path + " Something got weird");
       return FilePairProcessResults.FAILED;
@@ -501,7 +515,9 @@ async function collectDatabaseFiles(host, settings, log, showingNotice) {
 async function updateToDatabase(host, log, logLevel, file) {
   if (!host.services.vault.isFileSizeTooLarge(file.stat.size)) {
     const path = file.path;
-    await host.serviceModules.fileHandler.storeFileToDB(file);
+    if (!await host.serviceModules.fileHandler.storeFileToDB(file)) {
+      return FilePairProcessResults.FAILED;
+    }
     host.services.context.events.emitEvent("event-file-changed", { file: path, automated: true });
     return FilePairProcessResults.COMPLETED;
   } else {
@@ -537,13 +553,13 @@ async function updateToStorage(host, log, logLevel, w) {
     return FilePairProcessResults.FAILED;
   }
 }
-async function syncStorageAndDatabase(host, log, file, logLevel, doc) {
+async function syncStorageAndDatabase(host, log, file, logLevel, doc, scanOptions) {
   if ((doc._conflicts?.length ?? 0) > 0) {
     log(`SYNC DATABASE AND STORAGE: ${file.path} has conflicts. skipped`, LOG_LEVEL_INFO);
     return FilePairProcessResults.SKIPPED;
   }
   if (!host.services.vault.isFileSizeTooLarge(file.stat.size) && !host.services.vault.isFileSizeTooLarge(doc.size)) {
-    return await syncFileBetweenDBandStorage(host, log, file, doc);
+    return await syncFileBetweenDBandStorage(host, log, file, doc, scanOptions);
   } else {
     log(
       `SYNC DATABASE AND STORAGE: ${getPathFromEntry(host, doc)} has been skipped due to file size exceeding the limit`,
@@ -686,7 +702,7 @@ async function processFilePair(host, log, pair, options) {
         if (!file || !doc) {
           throw new Error(`Cannot compare freshness for ${path}`);
         }
-        const syncResult = await syncStorageAndDatabase(host, log, file, LOG_LEVEL_INFO, doc);
+        const syncResult = await syncStorageAndDatabase(host, log, file, LOG_LEVEL_INFO, doc, options);
         if (syncResult === FilePairProcessResults.COMPLETED) {
           updateFileMTimeInMap(host, fileMapKey, Math.max(file.stat.mtime, doc.mtime));
         }
@@ -910,11 +926,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, continueOnFileFailure = false) => {
+  const handleScanVault = async (showingNotice, ignoreSuspending = false, continueOnFileFailure = false, scanOptions) => {
     return await performFullScan(host, log, errorManager, {
       showingNotice,
       ignoreSuspending,
-      continueOnFileFailure
+      continueOnFileFailure,
+      strictContentCheck: scanOptions?.strictContentCheck
     });
   };
   host.services.vault.scanVault.addHandler(handleScanVault);

package/dist/serviceFeatures/prepareDatabaseForUse.d.ts

@@ -1,7 +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";
+import { type VaultScanResult, type VaultScanOptions } from "../services/base/VaultScanResult.js";
 /**
  * Initialise the database and trigger a full vault scan.
  * @param host Services container
@@ -11,9 +11,10 @@ import { type VaultScanResult } from "../services/base/VaultScanResult.js";
  * @param reopenDatabase Whether to reopen the database connection
  * @param ignoreSuspending Whether to ignore suspension settings
  * @param continueOnFileFailure Whether individual file failures may satisfy application readiness
+ * @param scanOptions Optional content-check policy; omitted options keep strict checks
  * @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, continueOnFileFailure?: boolean): Promise<VaultScanResult>;
+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, scanOptions?: VaultScanOptions): 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

@@ -6,7 +6,7 @@ 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) {
+async function prepareDatabaseForUse(host, log, errorManager, showingNotice = false, reopenDatabase = true, ignoreSuspending = false, continueOnFileFailure = false, scanOptions) {
   const appLifecycle = host.services.appLifecycle;
   appLifecycle.resetIsReady();
   try {
@@ -25,7 +25,7 @@ async function prepareDatabaseForUse(host, log, errorManager, showingNotice = fa
         "Database preparation stopped because the local database is not ready."
       );
     }
-    const scanResult = await host.services.vault.scanVault(showingNotice, ignoreSuspending, continueOnFileFailure);
+    const scanResult = await host.services.vault.scanVault(showingNotice, ignoreSuspending, continueOnFileFailure, scanOptions);
     if (scanResult === VaultScanResults.FAILED) {
       return reportPreparationFailure(log, "Database preparation stopped because the Vault scan failed.");
     }
@@ -57,7 +57,7 @@ async function prepareDatabaseForUse(host, log, errorManager, showingNotice = fa
 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, continueOnFileFailure = false) => {
+  const initialiseDatabaseHandler = async (showingNotice = false, reopenDatabase = true, ignoreSuspending = false, continueOnFileFailure = false, scanOptions) => {
     return await prepareDatabaseForUse(
       host,
       log,
@@ -65,7 +65,8 @@ function usePrepareDatabaseForUse(host) {
       showingNotice,
       reopenDatabase,
       ignoreSuspending,
-      continueOnFileFailure
+      continueOnFileFailure,
+      scanOptions
     );
   };
   host.services.databaseEvents.initialiseDatabase.addHandler(initialiseDatabaseHandler);

package/dist/serviceModules/ServiceFileAccessBase.d.ts

@@ -26,6 +26,7 @@ export declare class ServiceFileAccessBase<TAdapter extends IFileSystemAdapter<a
     private vault;
     private setting;
     constructor(services: StorageAccessBaseDependencies<TAdapter>);
+    hasPendingFileEvent(path: FilePath): boolean;
     restoreState(): Promise<void>;
     _everyOnFirstInitialize(): Promise<boolean>;
     _everyCommitPendingFileEvent(): Promise<boolean>;

package/dist/serviceModules/ServiceFileAccessBase.js

@@ -15,6 +15,14 @@ class ServiceFileAccessBase extends ServiceModuleBase {
     this.vaultAccess = services.vaultAccess;
     services.appLifecycle.onFirstInitialise.addHandler(this._everyOnFirstInitialize.bind(this));
     services.fileProcessing.commitPendingFileEvents.addHandler(this._everyCommitPendingFileEvent.bind(this));
+    services.appLifecycle.onBeforeUnload.addHandler(async () => {
+      if (this.vaultManager.stopWatching) await this.vaultManager.stopWatching();
+      else await this.vaultManager.waitForIdle();
+      return true;
+    });
+  }
+  hasPendingFileEvent(path) {
+    return this.vaultManager.hasPendingFileEvent?.(path) ?? true;
   }
   restoreState() {
     return this.vaultManager.restoreState();

package/dist/serviceModules/ServiceFileHandlerBase.d.ts

@@ -1,6 +1,6 @@
 import type { AnyEntry, FilePath, FilePathWithPrefix, MetaEntry, UXFileInfo, UXFileInfoStub, UXInternalFileInfoStub } from "../common/types.js";
 import type { LiveSyncEventHub } from "../hub/hub.js";
-import type { IFileHandler } from "../interfaces/FileHandler.js";
+import type { IFileHandler, StoreFileOptions } from "../interfaces/FileHandler.js";
 import { ServiceModuleBase } from "./ServiceModuleBase.js";
 import type { APIService } from "../services/base/APIService.js";
 import type { DatabaseFileAccess } from "../interfaces/DatabaseFileAccess.js";
@@ -74,7 +74,8 @@ export declare abstract class ServiceFileHandlerBase extends ServiceModuleBase<S
     /**
      * 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.
      */
     private readProvenanceSnapshot;
     /**
@@ -97,9 +98,10 @@ export declare abstract class ServiceFileHandlerBase extends ServiceModuleBase<S
     getPath(entry: AnyEntry): FilePathWithPrefix;
     getPathWithoutPrefix(entry: AnyEntry): FilePathWithPrefix;
     readFileFromStub(file: UXFileInfoStub | UXFileInfo): Promise<UXFileInfo>;
+    canSkipUnchangedFile(info: UXFileInfoStub, expected: MetaEntry): Promise<boolean>;
     tryRecordUntrackedFileRevision(info: UXFileInfoStub | UXFileInfo, expectedRevision: string): Promise<boolean>;
     private infoToStub;
-    storeFileToDB(info: UXFileInfoStub | UXFileInfo | UXInternalFileInfoStub | FilePathWithPrefix, force?: boolean, onlyChunks?: boolean): Promise<boolean>;
+    storeFileToDB(info: UXFileInfoStub | UXFileInfo | UXInternalFileInfoStub | FilePathWithPrefix, force?: boolean, onlyChunks?: boolean, options?: StoreFileOptions): Promise<boolean>;
     storeFileToDBWithBaseRevision(info: UXFileInfoStub | UXFileInfo | FilePathWithPrefix, baseRevision: string, createIfDifferent?: boolean): Promise<boolean>;
     /**
      * Store current storage content below an exact live revision. A differing
@@ -110,11 +112,13 @@ export declare abstract class ServiceFileHandlerBase extends ServiceModuleBase<S
     /**
      * 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.
      */
     private storeFileToDBFromRevision;
     deleteFileFromDB(info: UXFileInfoStub | UXInternalFileInfoStub | FilePath): Promise<boolean>;
+    /** Complete a validated storage deletion when its database effect is already represented. */
+    private deleteFileFromDBIfPresent;
     /**
      * Record a storage deletion under the caller's document lock, preserving
      * the displayed conflict branch when its provenance is known.