@vrtmrz/livesync-commonlib 0.1.17 → 0.1.19-rc.0

package/dist/API/DirectFileManipulatorV2.js

@@ -48,7 +48,9 @@ class DirectFileManipulator {
   async init() {
     try {
       await this.services.appLifecycle.onReady();
-      await this.liveSyncLocalDB.initializeDatabase();
+      if (!await this.liveSyncLocalDB.initializeDatabase()) {
+        throw new Error("Direct database initialisation was rejected.");
+      }
       this.liveSyncLocalDB.refreshSettings();
       this.ready.resolve();
     } catch (error) {

package/dist/common/ConnectionString.js

@@ -1,3 +1,4 @@
+import { normaliseP2PConnectionPath, normaliseP2PMaxWirePayloadBytes } from "./models/setting.p2p.js";
 const PROXY_SCHEME = "https";
 function parseSlsUri(uriString) {
   const match = uriString.match(/^sls\+([^:]+):(.*)$/);
@@ -155,7 +156,9 @@ class ConnectionStringParser {
       P2P_AutoBroadcast: searchParams.get("autoBroadcast") === "true",
       P2P_turnServers: searchParams.get("turnServers") || "",
       P2P_turnUsername: searchParams.get("turnUser") || "",
-      P2P_turnCredential: searchParams.get("turnPass") || ""
+      P2P_turnCredential: searchParams.get("turnPass") || "",
+      P2P_maxWirePayloadBytes: normaliseP2PMaxWirePayloadBytes(Number(searchParams.get("maxWirePayloadBytes"))),
+      P2P_connectionPath: normaliseP2PConnectionPath(searchParams.get("connectionPath"))
     };
   }
   static serializeP2P(settings) {
@@ -168,6 +171,11 @@ class ConnectionStringParser {
     if (settings.P2P_turnServers) searchParams.set("turnServers", settings.P2P_turnServers);
     if (settings.P2P_turnUsername) searchParams.set("turnUser", settings.P2P_turnUsername);
     if (settings.P2P_turnCredential) searchParams.set("turnPass", settings.P2P_turnCredential);
+    searchParams.set(
+      "maxWirePayloadBytes",
+      String(normaliseP2PMaxWirePayloadBytes(settings.P2P_maxWirePayloadBytes))
+    );
+    searchParams.set("connectionPath", normaliseP2PConnectionPath(settings.P2P_connectionPath));
     const credentials = settings.P2P_passphrase ? `:${encodeURIComponent(settings.P2P_passphrase)}@` : "";
     const host = encodeURIComponent(settings.P2P_roomID);
     const query = searchParams.toString() ? `?${searchParams.toString()}` : "";

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

@@ -59,6 +59,13 @@ export type FileEventItem = {
     type: FileEventType;
     args: FileEventArgs;
     key: string;
+    /**
+     * The event was loaded from the persisted storage-operation snapshot.
+     *
+     * A restored event records pending operation intent, not current storage
+     * state. File handlers must revalidate it before applying side effects.
+     */
+    restoredFromPreviousRuntime?: true;
     skipBatchWait?: boolean;
     cancelled?: boolean;
     batched?: boolean;

package/dist/common/models/setting.const.d.ts

@@ -9,6 +9,24 @@ export declare const RemoteTypes: {
 export declare const REMOTE_COUCHDB: "";
 export declare const REMOTE_MINIO: "MINIO";
 export declare const REMOTE_P2P: "ONLY_P2P";
+/** ICE route policies supported by a P2P connection profile. */
+export declare const P2PConnectionPaths: {
+    readonly Automatic: "automatic";
+    readonly Relay: "relay";
+};
+export type P2PConnectionPath = (typeof P2PConnectionPaths)[keyof typeof P2PConnectionPaths];
+/**
+ * User-facing message-size presets for the P2P RPC transport.
+ *
+ * These values limit Commonlib wire payloads before Trystero applies its own
+ * framing. They are not file Chunk sizes or network MTUs.
+ */
+export declare const P2PMessageSizePresets: {
+    readonly Standard: 15360;
+    readonly Reduced: 2048;
+    readonly Conservative: 1024;
+    readonly MaximumCompatibility: 800;
+};
 export declare const E2EEAlgorithmNames: {
     readonly "": "V1: Legacy";
     readonly v2: "V2: AES-256-GCM With HKDF";

package/dist/common/models/setting.const.defaults.js

@@ -1,4 +1,11 @@
-import { ChunkAlgorithms, CURRENT_SETTING_VERSION, E2EEAlgorithms, REMOTE_COUCHDB } from "./setting.const.js";
+import {
+  ChunkAlgorithms,
+  CURRENT_SETTING_VERSION,
+  E2EEAlgorithms,
+  P2PConnectionPaths,
+  P2PMessageSizePresets,
+  REMOTE_COUCHDB
+} from "./setting.const.js";
 import { PREFERRED_BASE } from "./setting.const.preferred.js";
 import { AutoAccepting } from "./setting.type.js";
 const P2P_DEFAULT_SETTINGS = {
@@ -21,6 +28,8 @@ const P2P_DEFAULT_SETTINGS = {
   P2P_turnServers: "",
   P2P_turnUsername: "",
   P2P_turnCredential: "",
+  P2P_maxWirePayloadBytes: P2PMessageSizePresets.Standard,
+  P2P_connectionPath: P2PConnectionPaths.Automatic,
   P2P_useDiagRTC: false
 };
 const SETTINGS_SCHEMA_DEFAULTS = {

package/dist/common/models/setting.const.js

@@ -9,6 +9,16 @@ const RemoteTypes = {
 const REMOTE_COUCHDB = RemoteTypes.REMOTE_COUCHDB;
 const REMOTE_MINIO = RemoteTypes.REMOTE_MINIO;
 const REMOTE_P2P = RemoteTypes.REMOTE_P2P;
+const P2PConnectionPaths = {
+  Automatic: "automatic",
+  Relay: "relay"
+};
+const P2PMessageSizePresets = {
+  Standard: 15360,
+  Reduced: 2048,
+  Conservative: 1024,
+  MaximumCompatibility: 800
+};
 const E2EEAlgorithmNames = {
   "": "V1: Legacy",
   v2: "V2: AES-256-GCM With HKDF",
@@ -59,6 +69,8 @@ export {
   MODE_SELECTIVE,
   MODE_SHINY,
   NetworkWarningStyles,
+  P2PConnectionPaths,
+  P2PMessageSizePresets,
   REMOTE_COUCHDB,
   REMOTE_MINIO,
   REMOTE_P2P,

package/dist/common/models/setting.const.qr.js

@@ -168,8 +168,10 @@ const KeyIndexOfSettings = {
   P2P_ActiveRemoteConfigurationId: 159,
   autoAcceptCompatibleTweak: 160,
   tweakModified: -1,
-  P2P_useDiagRTC: -1
+  P2P_useDiagRTC: -1,
   // Do not encode into the QR Code.
+  P2P_maxWirePayloadBytes: 163,
+  P2P_connectionPath: 164
 };
 export {
   KeyIndexOfSettings

package/dist/common/models/setting.p2p.d.ts

@@ -0,0 +1,21 @@
+import { type P2PConnectionPath } from "./setting.const.js";
+/**
+ * Return a safe outgoing RPC wire-payload bound for Trystero.
+ *
+ * Existing profiles can omit this value. Invalid, excessively small, and
+ * excessively large values retain the established 15,360-byte behaviour.
+ */
+export declare function normaliseP2PMaxWirePayloadBytes(value: unknown): number;
+/** Return a recognised P2P connection path, defaulting legacy values to automatic selection. */
+export declare function normaliseP2PConnectionPath(value: unknown): P2PConnectionPath;
+/** Split the stored comma-separated TURN server list without changing its entries. */
+export declare function splitP2PTurnServerUrls(value: string): string[];
+/**
+ * Report whether a value is a minimally valid TURN or TURN-over-TLS URL.
+ *
+ * Full allocation validation remains the responsibility of WebRTC. This
+ * check only prevents relay-only mode when no TURN endpoint can be attempted.
+ */
+export declare function isValidP2PTurnServerUrl(value: string): boolean;
+/** Report whether a stored TURN server list contains at least one usable TURN URL. */
+export declare function hasValidP2PTurnServerUrl(value: string): boolean;

package/dist/common/models/setting.p2p.js

@@ -0,0 +1,35 @@
+import { P2PConnectionPaths, P2PMessageSizePresets } from "./setting.const.js";
+function normaliseP2PMaxWirePayloadBytes(value) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < P2PMessageSizePresets.MaximumCompatibility || value > P2PMessageSizePresets.Standard) {
+    return P2PMessageSizePresets.Standard;
+  }
+  return value;
+}
+function normaliseP2PConnectionPath(value) {
+  return value === P2PConnectionPaths.Relay ? P2PConnectionPaths.Relay : P2PConnectionPaths.Automatic;
+}
+function splitP2PTurnServerUrls(value) {
+  return value.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+}
+function isValidP2PTurnServerUrl(value) {
+  const candidate = value.trim();
+  if (!candidate || /\s/.test(candidate)) return false;
+  try {
+    const parsed = new URL(candidate);
+    const protocol = parsed.protocol.toLowerCase();
+    if (protocol !== "turn:" && protocol !== "turns:") return false;
+    return (parsed.hostname || parsed.pathname).length > 0;
+  } catch {
+    return false;
+  }
+}
+function hasValidP2PTurnServerUrl(value) {
+  return splitP2PTurnServerUrls(value).some(isValidP2PTurnServerUrl);
+}
+export {
+  hasValidP2PTurnServerUrl,
+  isValidP2PTurnServerUrl,
+  normaliseP2PConnectionPath,
+  normaliseP2PMaxWirePayloadBytes,
+  splitP2PTurnServerUrls
+};

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

@@ -1,4 +1,4 @@
-import type { ChunkAlgorithms, E2EEAlgorithms, HashAlgorithms, MODE_AUTOMATIC, MODE_PAUSED, MODE_SELECTIVE, MODE_SHINY, RemoteTypes } from "./setting.const.js";
+import type { ChunkAlgorithms, E2EEAlgorithms, HashAlgorithms, MODE_AUTOMATIC, MODE_PAUSED, MODE_SELECTIVE, MODE_SHINY, P2PConnectionPath, RemoteTypes } from "./setting.const.js";
 import type { CustomRegExpSourceList } from "./shared.type.util.js";
 import type { JWTAlgorithm } from "./auth.type.js";
 /** Display languages recognised by the current LiveSync settings schema. */
@@ -528,6 +528,16 @@ export interface P2PConnectionInfo {
      * The TURN credential (password, secret, etc...) for the P2P connection.
      */
     P2P_turnCredential: string;
+    /**
+     * Maximum serialised RPC wire payload sent through Trystero before
+     * Commonlib splits it. Applies to outgoing messages.
+     */
+    P2P_maxWirePayloadBytes?: number;
+    /**
+     * ICE route policy for this P2P profile. Relay-only mode is effective only
+     * when the profile contains at least one valid TURN URL.
+     */
+    P2P_connectionPath?: P2PConnectionPath;
     /**
      * Use Diagnostic Wrapper for RTCPeerConnection to collect statistics.
      */

package/dist/common/models/shared.definition.configNames.js

@@ -152,6 +152,14 @@ const configurationNames = {
     desc: "The credential/password for the TURN servers.",
     isHidden: true
   },
+  P2P_maxWirePayloadBytes: {
+    name: "P2P Message Size",
+    desc: "The maximum outgoing RPC wire payload before Commonlib splits it for the P2P transport."
+  },
+  P2P_connectionPath: {
+    name: "Connection Path",
+    desc: "Select the WebRTC route automatically or require a configured TURN relay."
+  },
   useOnlyLocalChunk: {
     name: "Use Only Local Chunks",
     desc: "If enabled, the plugin will not attempt to connect to the remote database even if the chunk was not found locally.",

package/dist/common/models/tweak.definition.d.ts

@@ -186,6 +186,8 @@ export declare const TweakValuesTemplate: {
     P2P_turnServers?: string;
     P2P_turnUsername?: string;
     P2P_turnCredential?: string;
+    P2P_maxWirePayloadBytes?: number;
+    P2P_connectionPath?: import("./setting.const.js").P2PConnectionPath;
     P2P_useDiagRTC?: boolean;
 };
 export type TweakValues = Partial<typeof TweakValuesTemplate>;

package/dist/common/settingConstants.d.ts

@@ -196,6 +196,8 @@ export declare const AllSettingDefault: {
     P2P_turnServers: string;
     P2P_turnUsername: string;
     P2P_turnCredential: string;
+    P2P_maxWirePayloadBytes?: number;
+    P2P_connectionPath?: import("./types.js").P2PConnectionPath;
     P2P_useDiagRTC?: boolean;
 };
 export type AllSettings = ObsidianLiveSyncSettings & OnDialogSettings;

package/dist/common/types.d.ts

@@ -8,7 +8,8 @@ import { ChunkTypes, EntryTypes, MILESTONE_DOCID, NODEINFO_DOCID, NoteTypes, SYN
 import { AUTO_MERGED, CANCELLED, LEAVE_TO_SUBSEQUENT, MISSING_OR_ERROR, NOT_CONFLICTED, TIME_ARGUMENT_INFINITY } from "./models/shared.const.symbols.js";
 import { IDPrefixes, LEAF_WAIT_ONLY_REMOTE, LEAF_WAIT_TIMEOUT, LEAF_WAIT_TIMEOUT_SEQUENTIAL_REPLICATOR, MAX_DOC_SIZE, MAX_DOC_SIZE_BIN, PREFIX_CHUNK, PREFIX_ENCRYPTED_CHUNK, PREFIX_OBFUSCATED, RECENT_MODIFIED_DOCS_QTY, REPLICATION_BUSY_TIMEOUT, SALT_OF_ID, SALT_OF_PASSPHRASE, SEED_MURMURHASH, VER } from "./models/shared.const.behabiour.js";
 import { AutoAccepting, type BucketSyncSetting, type ChunkSplitterVersion, type ConfigPassphraseStore, type CouchDBConnection, type E2EEAlgorithm, type EncryptionSettings, type HashAlgorithm, type HasSettings, type LocalDBSettings, type ObsidianLiveSyncSettings, type P2PConnectionInfo, type P2PSyncSetting, type PluginSyncSettingEntry, type RemoteDBSettings, type RemoteType, type RemoteTypeSettings, type SYNC_MODE } from "./models/setting.type.js";
-import { ChunkAlgorithmNames, ChunkAlgorithms, CURRENT_SETTING_VERSION, E2EEAlgorithmNames, E2EEAlgorithms, HashAlgorithms, REMOTE_COUCHDB, REMOTE_MINIO, REMOTE_P2P, RemoteTypes, SETTING_VERSION_INITIAL, SETTING_VERSION_SUPPORT_CASE_INSENSITIVE, MODE_AUTOMATIC, MODE_PAUSED, MODE_SELECTIVE, MODE_SHINY } from "./models/setting.const.js";
+import { ChunkAlgorithmNames, ChunkAlgorithms, CURRENT_SETTING_VERSION, E2EEAlgorithmNames, E2EEAlgorithms, HashAlgorithms, REMOTE_COUCHDB, REMOTE_MINIO, REMOTE_P2P, RemoteTypes, SETTING_VERSION_INITIAL, SETTING_VERSION_SUPPORT_CASE_INSENSITIVE, MODE_AUTOMATIC, MODE_PAUSED, MODE_SELECTIVE, MODE_SHINY, P2PConnectionPaths, P2PMessageSizePresets, type P2PConnectionPath } from "./models/setting.const.js";
+import { hasValidP2PTurnServerUrl, isValidP2PTurnServerUrl, normaliseP2PConnectionPath, normaliseP2PMaxWirePayloadBytes, splitP2PTurnServerUrls } from "./models/setting.p2p.js";
 import { PREFERRED_BASE, PREFERRED_JOURNAL_SYNC, PREFERRED_SETTING_CLOUDANT, PREFERRED_SETTING_SELF_HOSTED } from "./models/setting.const.preferred.js";
 import { P2P_DEFAULT_SETTINGS, DEFAULT_SETTINGS, NEW_VAULT_SETTINGS, SETTINGS_SCHEMA_DEFAULTS, createNewVaultSettings } from "./models/setting.const.defaults.js";
 import { prepareSettingsForLoad, SettingsMigrationReviewCodes, type PreparedSettings, type SettingsMigrationReviewCode, type SettingsMigrationReviewReason, type SettingsMigrationState } from "./models/setting.lifecycle.js";
@@ -34,8 +35,9 @@ export { MODE_SELECTIVE, MODE_AUTOMATIC, MODE_PAUSED, MODE_SHINY, type SYNC_MODE
 export { type PluginSyncSettingEntry };
 export { SETTING_VERSION_INITIAL, SETTING_VERSION_SUPPORT_CASE_INSENSITIVE, CURRENT_SETTING_VERSION };
 export type { BucketSyncSetting, LocalDBSettings };
-export { RemoteTypes, REMOTE_COUCHDB, REMOTE_MINIO, REMOTE_P2P, type RemoteType, AutoAccepting };
-export type { P2PConnectionInfo, P2PSyncSetting };
+export { RemoteTypes, REMOTE_COUCHDB, REMOTE_MINIO, REMOTE_P2P, P2PConnectionPaths, P2PMessageSizePresets, type RemoteType, AutoAccepting, };
+export type { P2PConnectionInfo, P2PConnectionPath, P2PSyncSetting };
+export { hasValidP2PTurnServerUrl, isValidP2PTurnServerUrl, normaliseP2PConnectionPath, normaliseP2PMaxWirePayloadBytes, splitP2PTurnServerUrls, };
 export { P2P_DEFAULT_SETTINGS };
 export type { RemoteTypeSettings };
 export { E2EEAlgorithmNames, E2EEAlgorithms, type E2EEAlgorithm };

package/dist/common/types.js

@@ -59,8 +59,17 @@ import {
   MODE_AUTOMATIC,
   MODE_PAUSED,
   MODE_SELECTIVE,
-  MODE_SHINY
+  MODE_SHINY,
+  P2PConnectionPaths,
+  P2PMessageSizePresets
 } from "./models/setting.const.js";
+import {
+  hasValidP2PTurnServerUrl,
+  isValidP2PTurnServerUrl,
+  normaliseP2PConnectionPath,
+  normaliseP2PMaxWirePayloadBytes,
+  splitP2PTurnServerUrls
+} from "./models/setting.p2p.js";
 import {
   PREFERRED_BASE,
   PREFERRED_JOURNAL_SYNC,
@@ -181,6 +190,8 @@ export {
   NODEINFO_DOCID,
   NOT_CONFLICTED,
   NoteTypes,
+  P2PConnectionPaths,
+  P2PMessageSizePresets,
   P2P_DEFAULT_SETTINGS,
   PREFERRED_BASE,
   PREFERRED_JOURNAL_SYNC,
@@ -225,7 +236,12 @@ export {
   configURIBaseQR,
   configurationNames,
   createNewVaultSettings,
+  hasValidP2PTurnServerUrl,
   isMetaEntry,
+  isValidP2PTurnServerUrl,
+  normaliseP2PConnectionPath,
+  normaliseP2PMaxWirePayloadBytes,
   prepareSettingsForLoad,
+  splitP2PTurnServerUrls,
   statusDisplay
 };

package/dist/common/utils.js

@@ -7,6 +7,7 @@ import {
   PREFIX_OBFUSCATED,
   SYNCINFO_ID
 } from "./types.js";
+import { normaliseP2PConnectionPath, normaliseP2PMaxWirePayloadBytes } from "./models/setting.p2p.js";
 import { isErrorOfMissingDoc } from "../pouchdb/utils_couchdb.js";
 import { replaceAll, replaceAllPairs } from "octagonal-wheels/string";
 import { concatUInt8Array } from "octagonal-wheels/binary";
@@ -459,7 +460,9 @@ function pickP2PSyncSettings(setting) {
     P2P_DevicePeerName: setting.P2P_DevicePeerName || "",
     P2P_turnServers: setting.P2P_turnServers,
     P2P_turnUsername: setting.P2P_turnUsername,
-    P2P_turnCredential: setting.P2P_turnCredential
+    P2P_turnCredential: setting.P2P_turnCredential,
+    P2P_maxWirePayloadBytes: normaliseP2PMaxWirePayloadBytes(setting.P2P_maxWirePayloadBytes),
+    P2P_connectionPath: normaliseP2PConnectionPath(setting.P2P_connectionPath)
   };
 }
 function wrapByDefault(func, onError) {

package/dist/interfaces/DatabaseRebuilder.d.ts

@@ -17,7 +17,9 @@ export interface Rebuilder {
     /** See {@link scheduleRebuild}; this variant writes the Fetch flag. */
     scheduleFetch(prepareBeforeRestart?: () => Promise<void>): Promise<boolean>;
     /**
-     * Declares the finish of the rebuild process and unlock remote, resume reflecting the changes.
+     * Complete the final reflection scan and checks owned by a fetch, then establish application readiness.
+     *
+     * @returns `true` when every required completion phase succeeded; otherwise, `false`.
      */
-    finishRebuild(): Promise<void>;
+    finishRebuild(): Promise<boolean>;
 }

package/dist/managers/StorageEventManager.d.ts

@@ -21,6 +21,9 @@ type FileEventItemSentinelFlush = {
     type: typeof TYPE_SENTINEL_FLUSH;
 };
 export type FileEventItemSentinel = FileEventItemSentinelFlush;
+type RunQueuedEventsOptions = {
+    waitForProcessing?: boolean;
+};
 export interface StorageEventManagerBaseDependencies {
     setting: SettingService;
     vaultService: IVaultService;
@@ -61,13 +64,11 @@ export declare abstract class StorageEventManagerBase<TAdapter extends IStorageE
     protected updateStatus(): void;
     /**
      * Snapshot restoration promise.
-     * Snapshot will be restored before starting to watch vault changes.
-     * In designed time, this has been called from Initialisation process, which has been implemented on `ModuleInitializerFile.ts`.
+     * It resolves after the restored file operations have finished, before Vault watching begins.
      */
     snapShotRestored: Promise<void> | null;
     /**
-     * Restore the previous snapshot if exists.
-     * @returns
+     * Restore and complete the previous storage-event snapshot when it exists.
      */
     restoreState(): Promise<void>;
     appendQueue(params: FileEvent[], ctx?: unknown): Promise<void>;
@@ -111,7 +112,17 @@ export declare abstract class StorageEventManagerBase<TAdapter extends IStorageE
     processFileEvent(fei: FileEventItem): Promise<void>;
     _takeSnapshot(): Promise<void>;
     _restoreFromSnapshot(): Promise<void>;
-    protected runQueuedEvents(): Promise<void>;
+    /**
+     * Dispatch buffered storage events.
+     *
+     * Ordinary watcher events retain the existing fire-and-forget behaviour.
+     * Snapshot restoration requests completion so its caller can use the replay as
+     * a lifecycle boundary. In that mode, a sentinel also waits for every operation
+     * dispatched before it, preserving the ordering represented by the snapshot.
+     * An individual restored operation failure is logged but does not prevent the
+     * following Offline Scanner from reconciling the resulting current state.
+     */
+    protected runQueuedEvents(options?: RunQueuedEventsOptions): Promise<void>;
     protected processingCount: number;
     protected requestProcessQueue(fei: FileEventItem): Promise<void>;
     isWaiting(filename: FilePath): boolean;

package/dist/managers/StorageEventManager.js

@@ -72,13 +72,11 @@ class StorageEventManagerBase extends StorageEventManager {
   }
   /**
    * Snapshot restoration promise.
-   * Snapshot will be restored before starting to watch vault changes.
-   * In designed time, this has been called from Initialisation process, which has been implemented on `ModuleInitializerFile.ts`.
+   * It resolves after the restored file operations have finished, before Vault watching begins.
    */
   snapShotRestored = null;
   /**
-   * Restore the previous snapshot if exists.
-   * @returns
+   * Restore and complete the previous storage-event snapshot when it exists.
    */
   restoreState() {
     this.snapShotRestored = this._restoreFromSnapshot();
@@ -371,15 +369,44 @@ class StorageEventManagerBase extends StorageEventManager {
     const snapShot = await this._loadSnapshot();
     if (snapShot && Array.isArray(snapShot) && snapShot.length > 0) {
       this._log(`Restoring storage operation snapshot: ${snapShot.length} items`, LOG_LEVEL_VERBOSE);
-      this.bufferedQueuedItems = snapShot.map((e) => ({ ...e, skipBatchWait: true }));
+      this.bufferedQueuedItems = snapShot.map(
+        (event) => event.type === TYPE_SENTINEL_FLUSH ? event : { ...event, restoredFromPreviousRuntime: true, skipBatchWait: true }
+      );
       this.updateStatus();
-      await this.runQueuedEvents();
+      await this.runQueuedEvents({ waitForProcessing: true });
     } else {
       this._log(`No snapshot to restore`, LOG_LEVEL_VERBOSE);
     }
   }
-  runQueuedEvents() {
+  /**
+   * Dispatch buffered storage events.
+   *
+   * Ordinary watcher events retain the existing fire-and-forget behaviour.
+   * Snapshot restoration requests completion so its caller can use the replay as
+   * a lifecycle boundary. In that mode, a sentinel also waits for every operation
+   * dispatched before it, preserving the ordering represented by the snapshot.
+   * An individual restored operation failure is logged but does not prevent the
+   * following Offline Scanner from reconciling the resulting current state.
+   */
+  runQueuedEvents(options = {}) {
+    const waitForProcessing = options.waitForProcessing ?? false;
     return skipIfDuplicated("storage-event-manager-run-queued-events", async () => {
+      let dispatched = [];
+      const waitForDispatched = async () => {
+        if (dispatched.length === 0) return;
+        const pending = dispatched;
+        dispatched = [];
+        const results = await Promise.allSettled(pending.map(({ processing }) => processing));
+        for (const [index, result] of results.entries()) {
+          if (result.status === "rejected") {
+            this._log(
+              `Restored storage operation failed for ${pending[index].path}; the Offline Scanner will reconcile the current state`,
+              LOG_LEVEL_NOTICE
+            );
+            this._log(result.reason, LOG_LEVEL_VERBOSE);
+          }
+        }
+      };
       do {
         if (this.bufferedQueuedItems.length === 0) {
           break;
@@ -392,12 +419,23 @@ class StorageEventManagerBase extends StorageEventManager {
         this.updateStatus();
         if (fei.type === TYPE_SENTINEL_FLUSH) {
           this._log(`Waiting for idle`, LOG_LEVEL_VERBOSE);
+          if (waitForProcessing) {
+            await waitForDispatched();
+          }
           await this.waitForIdle();
           this.updateStatus();
           continue;
         }
-        fireAndForget(() => this.processFileEvent(fei));
+        const processing = this.processFileEvent(fei);
+        if (waitForProcessing) {
+          dispatched.push({ path: fei.args.file.path, processing });
+        } else {
+          fireAndForget(processing);
+        }
       } while (this.bufferedQueuedItems.length > 0);
+      if (waitForProcessing) {
+        await waitForDispatched();
+      }
     });
   }
   processingCount = 0;

package/dist/pouchdb/LiveSyncLocalDB.d.ts

@@ -46,11 +46,17 @@ export declare class LiveSyncLocalDB {
     env: LiveSyncLocalDBEnv;
     clearCaches(): void;
     _prepareHashFunctions(): Promise<void>;
-    onunload(): void;
     refreshSettings(): void;
     offRemoteChunkFetchedHandler?: ReturnType<LiveSyncEventHub["onEvent"]>;
+    private databaseCloseCleanup?;
+    private databaseUnloadNotification?;
     constructor(dbname: string, env: LiveSyncLocalDBEnv);
+    /** Notify dependent services at most once for each physical database lifecycle. */
+    private notifyDatabaseUnload;
+    onunload(): void;
     close(): Promise<void>;
+    private teardownDatabaseDependencies;
+    private rollbackFailedInitialisation;
     onNewLeaf(chunk: EntryLeaf): void;
     initializeDatabase(): Promise<boolean>;
     /**