@vrtmrz/livesync-commonlib 0.1.44 → 0.2.1

package/dist/replication/LiveSyncAbstractReplicator.d.ts

@@ -1,3 +1,4 @@
+import type { ReplicationStatics } from "../common/models/shared.definition.js";
 import { type EntryDoc, type DatabaseConnectingStatus, type RemoteDBSettings, type TweakValues, type RemotePreferredTweakResult, type NodeData } from "../common/types.js";
 import type { RequiredServices } from "../interfaces/ServiceModule.js";
 import type { TranslationParameters } from "../services/base/MessageTranslator.js";
@@ -62,6 +63,7 @@ export declare abstract class LiveSyncAbstractReplicator implements ReplicatorIn
     constructor(env: LiveSyncReplicatorEnv);
     abstract terminateSync(): void | Promise<void>;
     abstract openReplication(setting: RemoteDBSettings, keepAlive: boolean, showResult: boolean, ignoreCleanLock: boolean): Promise<void | boolean>;
+    protected getReplicationStatics(): ReplicationStatics;
     updateInfo: () => void;
     abstract tryConnectRemote(setting: RemoteDBSettings, showResult?: boolean): Promise<boolean>;
     abstract replicateAllToServer(setting: RemoteDBSettings, showingNotice?: boolean): Promise<boolean>;

package/dist/replication/LiveSyncAbstractReplicator.js

@@ -75,8 +75,8 @@ class LiveSyncAbstractReplicator {
   constructor(env) {
     this.env = env;
   }
-  updateInfo = () => {
-    this.env.services.replicator.replicationStatics.value = {
+  getReplicationStatics() {
+    return {
       sent: this.docSent,
       arrived: this.docArrived,
       maxPullSeq: this.maxPullSeq,
@@ -85,6 +85,9 @@ class LiveSyncAbstractReplicator {
       lastSyncPushSeq: this.lastSyncPushSeq,
       syncStatus: this.syncStatus
     };
+  }
+  updateInfo = () => {
+    this.env.services.replicator.replicationStatics.value = this.getReplicationStatics();
   };
 }
 export {

package/dist/replication/RemoteResource.d.ts

@@ -1,12 +1,16 @@
 import type { RemoteDBSettings, RemotePreferredTweakResult } from "../common/types.js";
+import type { JoinedDevicesSnapshot, ForgetJoinedDeviceResult } from "./joinedDevices.js";
 import type { RemoteDBStatus } from "./LiveSyncAbstractReplicator.js";
 import { type CapabilitySupport } from "./ProviderCapability.js";
+import type { InitialFetchFastForward } from "./couchdb/fastForward.js";
 /** Stable machine identifiers for finite provider-owned remote resources. */
 export declare const REMOTE_RESOURCE_KINDS: Readonly<{
     readonly CONNECTION: "connection";
+    readonly JOINED_DEVICES: "joined-devices";
     readonly PREFERRED_TWEAK: "preferred-tweak";
     readonly SECURITY_SEED: "security-seed";
     readonly SYNCHRONISATION_INFORMATION: "synchronisation-information";
+    readonly INITIAL_FETCH_FAST_FORWARD: "initial-fetch-fast-forward";
 }>;
 export type RemoteResourceKind = (typeof REMOTE_RESOURCE_KINDS)[keyof typeof REMOTE_RESOURCE_KINDS];
 /** Options understood by a provider's finite remote-connection resource. */
@@ -64,22 +68,39 @@ export interface SynchronisationInformationResource {
     check(): Promise<boolean>;
     dispose(): Promise<void>;
 }
+/** Checkpoint handoff owned exclusively by one fresh Fast Fetch. */
+export interface InitialFetchFastForwardResource {
+    prepare(): Promise<InitialFetchFastForward | undefined>;
+    dispose(): Promise<void>;
+}
+/** An owned reader and editor of device records for one remote settings snapshot. */
+export interface JoinedDevicesResource {
+    read(): Promise<JoinedDevicesSnapshot>;
+    forget(deviceId: string): Promise<ForgetJoinedDeviceResult>;
+    dispose(): Promise<void>;
+}
 export type RemoteResourceMap = {
+    readonly [REMOTE_RESOURCE_KINDS.JOINED_DEVICES]: JoinedDevicesResource;
     readonly [REMOTE_RESOURCE_KINDS.CONNECTION]: RemoteConnectionProbe;
     readonly [REMOTE_RESOURCE_KINDS.PREFERRED_TWEAK]: PreferredTweakProbe;
     readonly [REMOTE_RESOURCE_KINDS.SECURITY_SEED]: SecuritySeedResource;
     readonly [REMOTE_RESOURCE_KINDS.SYNCHRONISATION_INFORMATION]: SynchronisationInformationResource;
+    readonly [REMOTE_RESOURCE_KINDS.INITIAL_FETCH_FAST_FORWARD]: InitialFetchFastForwardResource;
 };
 export type RemoteResourceFactoryMap = {
     readonly [K in RemoteResourceKind]: (setting: RemoteDBSettings) => Promise<RemoteResourceMap[K]>;
 };
-/** Exhaustive resource support catalogue supplied by one provider. */
+/** Resource support catalogue; older hosts may omit the initial-fetch optimisation. */
 export type RemoteResourceCapabilities = {
-    readonly [K in RemoteResourceKind]: CapabilitySupport<RemoteResourceFactoryMap[K]>;
+    readonly [K in Exclude<RemoteResourceKind, typeof REMOTE_RESOURCE_KINDS.INITIAL_FETCH_FAST_FORWARD>]: CapabilitySupport<RemoteResourceFactoryMap[K]>;
+} & {
+    readonly [REMOTE_RESOURCE_KINDS.INITIAL_FETCH_FAST_FORWARD]?: CapabilitySupport<RemoteResourceFactoryMap[typeof REMOTE_RESOURCE_KINDS.INITIAL_FETCH_FAST_FORWARD]>;
 };
 /** Explicit catalogue for providers which own no finite remote resources. */
 export declare const NO_REMOTE_RESOURCE_CAPABILITIES: RemoteResourceCapabilities;
 export type ConnectionProbeFactory = RemoteResourceFactoryMap[typeof REMOTE_RESOURCE_KINDS.CONNECTION];
 export type PreferredTweakProbeFactory = RemoteResourceFactoryMap[typeof REMOTE_RESOURCE_KINDS.PREFERRED_TWEAK];
 export type SecuritySeedResourceFactory = RemoteResourceFactoryMap[typeof REMOTE_RESOURCE_KINDS.SECURITY_SEED];
+export type InitialFetchFastForwardResourceFactory = RemoteResourceFactoryMap[typeof REMOTE_RESOURCE_KINDS.INITIAL_FETCH_FAST_FORWARD];
 export type SynchronisationInformationResourceFactory = RemoteResourceFactoryMap[typeof REMOTE_RESOURCE_KINDS.SYNCHRONISATION_INFORMATION];
+export type JoinedDevicesResourceFactory = RemoteResourceFactoryMap[typeof REMOTE_RESOURCE_KINDS.JOINED_DEVICES];

package/dist/replication/RemoteResource.js

@@ -1,15 +1,19 @@
 import { CAPABILITY_NOT_APPLICABLE } from "./ProviderCapability.js";
 const REMOTE_RESOURCE_KINDS = Object.freeze({
   CONNECTION: "connection",
+  JOINED_DEVICES: "joined-devices",
   PREFERRED_TWEAK: "preferred-tweak",
   SECURITY_SEED: "security-seed",
-  SYNCHRONISATION_INFORMATION: "synchronisation-information"
+  SYNCHRONISATION_INFORMATION: "synchronisation-information",
+  INITIAL_FETCH_FAST_FORWARD: "initial-fetch-fast-forward"
 });
 const NO_REMOTE_RESOURCE_CAPABILITIES = Object.freeze({
   [REMOTE_RESOURCE_KINDS.CONNECTION]: CAPABILITY_NOT_APPLICABLE,
+  [REMOTE_RESOURCE_KINDS.JOINED_DEVICES]: CAPABILITY_NOT_APPLICABLE,
   [REMOTE_RESOURCE_KINDS.PREFERRED_TWEAK]: CAPABILITY_NOT_APPLICABLE,
   [REMOTE_RESOURCE_KINDS.SECURITY_SEED]: CAPABILITY_NOT_APPLICABLE,
-  [REMOTE_RESOURCE_KINDS.SYNCHRONISATION_INFORMATION]: CAPABILITY_NOT_APPLICABLE
+  [REMOTE_RESOURCE_KINDS.SYNCHRONISATION_INFORMATION]: CAPABILITY_NOT_APPLICABLE,
+  [REMOTE_RESOURCE_KINDS.INITIAL_FETCH_FAST_FORWARD]: CAPABILITY_NOT_APPLICABLE
 });
 export {
   NO_REMOTE_RESOURCE_CAPABILITIES,

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

@@ -1,9 +1,12 @@
+import type { ReplicationStatics } from "../../common/models/shared.definition.js";
 import { type EntryDoc, type RemoteDBSettings, type EntryLeaf, type SyncParameters, type DatabaseEntry, type NodeData, type RemotePreferredTweakResult } from "../../common/types.js";
+import type { InitialFetchFastForwardResource } from "../RemoteResource.js";
 import { LiveSyncAbstractReplicator, type LiveSyncReplicatorEnv, type RemoteDBStatus } from "../LiveSyncAbstractReplicator.js";
 import type { OwnedCouchDBConnection, RemoteConnectionOpenOptions } from "../../services/base/RemoteConnection.js";
 import type { IPathService } from "../../services/base/IService.js";
 import { type CentralCompatibilityDecisionRecorder } from "../CentralCompatibility.js";
 import { type ReplicationOutcome } from "../ReplicatorProvider.js";
+import { type ForgetJoinedDeviceResult, type JoinedDevicesSnapshot } from "../joinedDevices.js";
 export type { OwnedCouchDBConnection, RemoteConnectionOpenOptions } from "../../services/base/RemoteConnection.js";
 /**
  * Compatibility constructor environment for the CouchDB Replicator facade.
@@ -43,8 +46,15 @@ export declare class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicato
     private continuousTask;
     private continuousStopWaiter;
     private continuousStopRequested;
+    private continuousPhase?;
+    private couchDBProgress?;
+    protected getReplicationStatics(): ReplicationStatics;
+    private publishPreparationPhase;
+    private finishReplicationProgress;
     isMobile(): boolean;
     constructor(env: LiveSyncCouchDBReplicatorEnv);
+    /** Own the checkpoint handoff for one fresh, suspended Fast Fetch only. */
+    createInitialFetchFastForwardResource(setting: RemoteDBSettings): InitialFetchFastForwardResource;
     getInitialSyncParameters(setting: RemoteDBSettings): Promise<SyncParameters>;
     getSyncParameters(setting: RemoteDBSettings): Promise<SyncParameters>;
     putSyncParameters(setting: RemoteDBSettings, params: SyncParameters): Promise<boolean>;
@@ -152,6 +162,10 @@ export declare class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicato
     compactRemote(setting: RemoteDBSettings): Promise<boolean>;
     getRemoteStatus(setting: RemoteDBSettings): Promise<RemoteDBStatus | false>;
     countCompromisedChunks(setting?: RemoteDBSettings): Promise<number | boolean>;
+    private connectForJoinedDevices;
+    private getOwnJoinedDeviceId;
+    getJoinedDevices(setting: RemoteDBSettings): Promise<JoinedDevicesSnapshot>;
+    forgetJoinedDevice(setting: RemoteDBSettings, deviceId: string): Promise<ForgetJoinedDeviceResult>;
     getConnectedDeviceList(setting?: RemoteDBSettings): Promise<false | {
         node_info: Record<string, NodeData>;
         accepted_nodes: string[];

package/dist/replication/couchdb/LiveSyncReplicator.js

@@ -1,6 +1,8 @@
+import { observeReplicationProgress } from "./replicationProgress.js";
 import {
   VER,
   MILESTONE_DOCID,
+  NODEINFO_DOCID,
   REPLICATION_BUSY_TIMEOUT,
   LOG_LEVEL_INFO,
   LOG_LEVEL_NOTICE,
@@ -26,6 +28,7 @@ import { requiredRemoteFeatures, usesEncryptedInternalMetadata } from "../../pou
 import { assessRemoteDocumentIds } from "../../pouchdb/remoteIdCompatibility.js";
 import { isErrorOfMissingDoc } from "../../pouchdb/utils_couchdb.js";
 import { preprocessOutgoing } from "../../pouchdb/encryption.js";
+import { prepareInitialFetchFastForward } from "./fastForward.js";
 import { ensureDatabaseIsCompatible, getEffectiveTweakValues } from "../../pouchdb/LiveSyncDBFunctions.js";
 import {
   LiveSyncAbstractReplicator
@@ -54,6 +57,10 @@ import {
   replicationBlocked,
   replicationFailed
 } from "../ReplicatorProvider.js";
+import {
+  forgetJoinedDevice as forgetJoinedDeviceFromStore,
+  projectJoinedDevices
+} from "../joinedDevices.js";
 const currentVersionRange = {
   min: 0,
   max: 2400,
@@ -116,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();
   }
@@ -123,6 +148,59 @@ class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicator {
     super(env);
     this.env = env;
   }
+  /** Own the checkpoint handoff for one fresh, suspended Fast Fetch only. */
+  createInitialFetchFastForwardResource(setting) {
+    const snapshot = { ...setting };
+    const identity = (value) => JSON.stringify([
+      value.couchDB_URI,
+      value.couchDB_DBNAME,
+      value.couchDB_USER,
+      value.couchDB_PASSWORD,
+      value.couchDB_CustomHeaders,
+      value.useJWT,
+      value.jwtAlgorithm,
+      value.jwtKey,
+      value.jwtExpDuration,
+      value.jwtKid,
+      value.jwtSub,
+      value.encrypt,
+      value.passphrase,
+      value.E2EEAlgorithm,
+      value.enableCompression,
+      value.pathNormalizationVersion,
+      value.readChunksOnline,
+      value.useRequestAPI
+    ]);
+    const binding = identity(snapshot);
+    let connection;
+    let prepared = false;
+    let disposed = false;
+    return {
+      prepare: async () => {
+        if (prepared || disposed) return void 0;
+        prepared = true;
+        if (this.currentSettings.doNotSuspendOnFetching || snapshot.useRequestAPI) return void 0;
+        const local = this.rawDatabase;
+        const isCurrent = () => !disposed && this.rawDatabase === local && this.currentSettings.suspendFileWatching && this.currentSettings.suspendParseReplicationResult && identity(this.currentSettings) === binding;
+        if (!isCurrent()) return void 0;
+        const openedConnection = await this.openOwnedConnection(snapshot);
+        if (disposed) {
+          await openedConnection.close();
+          return void 0;
+        }
+        connection = openedConnection;
+        return await prepareInitialFetchFastForward(local, connection.db, {
+          push: {},
+          ...snapshot.readChunksOnline ? { pull: { ...selectorOnDemandPull } } : {}
+        }, isCurrent);
+      },
+      dispose: async () => {
+        if (disposed) return;
+        disposed = true;
+        if (connection) await connection.close();
+      }
+    };
+  }
   getInitialSyncParameters(setting) {
     return Promise.resolve({
       ...DEFAULT_SYNC_PARAMETERS,
@@ -182,6 +260,7 @@ class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicator {
       this.continuousStopRequested = true;
     }
     this.abortController();
+    this.finishReplicationProgress();
     if (!task) {
       return Promise.resolve();
     }
@@ -293,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) {
@@ -302,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) {
@@ -381,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) {
@@ -925,7 +1017,8 @@ ${sendingDocs}/(${sentDocsCount} done)`,
           plugin_version: this.env.services.API.getPluginVersion(),
           vault_name: this.env.services.vault.vaultName(),
           device_name: this.env.services.vault.getVaultName(),
-          progress
+          progress,
+          platform: this.env.services.API.getPlatform()
         };
         let tweakAssessment;
         const ensure = await ensureDatabaseIsCompatible(
@@ -1058,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;
@@ -1071,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(
@@ -1086,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) {
@@ -1608,6 +1705,77 @@ ${sendingDocs}/(${sentDocsCount} done)`,
     }
     return await this.withRemoteConnection(dbRet, countCompromisedChunks);
   }
+  async connectForJoinedDevices(setting) {
+    let result;
+    try {
+      result = await this.connectRemoteCouchDBWithSetting(setting, this.isMobile(), false);
+    } catch {
+      throw new Error("Could not connect to remote CouchDB for joined-device management.");
+    }
+    if (typeof result === "string") {
+      throw new Error("Could not connect to remote CouchDB for joined-device management.");
+    }
+    return result;
+  }
+  async getOwnJoinedDeviceId() {
+    const nodeInfo = await this.rawDatabase.get(NODEINFO_DOCID);
+    const nodeId = nodeInfo?.nodeid;
+    if (typeof nodeId !== "string" || nodeId.trim().length === 0) {
+      throw new Error("The local node identity is unavailable.");
+    }
+    return nodeId;
+  }
+  async getJoinedDevices(setting) {
+    const connection = await this.connectForJoinedDevices(setting);
+    return await this.withRemoteConnection(connection, async (db) => {
+      let milestone;
+      try {
+        milestone = await db.get(MILESTONE_DOCID);
+      } catch (ex) {
+        if (!isErrorOfMissingDoc(ex)) throw ex;
+      }
+      return projectJoinedDevices(milestone);
+    });
+  }
+  async forgetJoinedDevice(setting, deviceId) {
+    const ownDeviceId = await this.getOwnJoinedDeviceId();
+    const connection = await this.connectForJoinedDevices(setting);
+    return await this.withRemoteConnection(connection, async (db) => {
+      const store = {
+        read: async () => {
+          let milestone;
+          try {
+            milestone = await db.get(MILESTONE_DOCID);
+          } catch (ex) {
+            if (isErrorOfMissingDoc(ex)) return void 0;
+            throw ex;
+          }
+          return { milestone, revision: milestone._rev };
+        },
+        write: async (milestone, revision) => {
+          try {
+            await db.put({ ...milestone, _rev: revision });
+          } catch (ex) {
+            if (ex && typeof ex === "object" && ex.status === 409) {
+              return "conflict";
+            }
+            throw ex;
+          }
+          let verifiedMilestone;
+          try {
+            verifiedMilestone = await db.get(MILESTONE_DOCID);
+          } catch {
+            throw new Error("Could not verify joined-device removal.");
+          }
+          if (projectJoinedDevices(verifiedMilestone).devices.some((device) => device.id === deviceId)) {
+            throw new Error("Could not verify joined-device removal.");
+          }
+          return "updated";
+        }
+      };
+      return await forgetJoinedDeviceFromStore(store, deviceId, ownDeviceId);
+    });
+  }
   async getConnectedDeviceList(setting = this.currentSettings) {
     const dbRet = await this.connectRemoteCouchDBWithSetting(setting, this.isMobile(), true);
     if (typeof dbRet === "string") {

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

@@ -0,0 +1,19 @@
+import type { EntryDoc } from "../../common/types.js";
+type Sequence = string | number;
+/** Evidence retained only for the currently running, fresh Fast Fetch. */
+export interface InitialFetchFastForward {
+    recordStoredRevisions(revisions: readonly {
+        id: string;
+        rev: string;
+    }[]): void;
+    recordCheckpoint(sequence: Sequence): void;
+    fastForward(): Promise<boolean>;
+}
+/**
+ * Prepare ordinary checkpoint pairs before a fresh import into an empty database.
+ * The importer must remain the sole writer until fastForward settles.
+ * The remote database must remain in place throughout the import and handoff:
+ * PouchDB's HTTP ID identifies a server and database name, not its incarnation.
+ */
+export declare function prepareInitialFetchFastForward(localDatabase: PouchDB.Database<EntryDoc>, remoteDatabase: PouchDB.Database<EntryDoc>, options: PouchDB.Replication.SyncOptions, isCurrent: () => boolean): Promise<InitialFetchFastForward | undefined>;
+export {};

package/dist/replication/couchdb/fastForward.js

@@ -0,0 +1,119 @@
+import generateReplicationId from "pouchdb-generate-replication-id";
+import Checkpointer from "pouchdb-checkpointer";
+import { uuid } from "pouchdb-utils";
+const MAX_TRACKED_REVISIONS = 1e5;
+async function prepareInitialFetchFastForward(localDatabase, remoteDatabase, options, isCurrent) {
+  const local = localDatabase;
+  const remote = remoteDatabase;
+  if ((await local.info()).doc_count !== 0 || !isCurrent()) return void 0;
+  const localId = await local.id();
+  const remoteId = await remote.id();
+  const pairs = [
+    { source: local, target: remote, options: { ...options, ...options.push } },
+    { source: remote, target: local, options: { ...options, ...options.pull } }
+  ];
+  const checkpoints = [];
+  for (const pair of pairs) {
+    const id = await generateReplicationId(pair.source, pair.target, pair.options);
+    for (const database of [local, remote]) {
+      try {
+        await database.get(id);
+        return void 0;
+      } catch (error) {
+        if (error.status !== 404) throw error;
+      }
+    }
+    const session = uuid();
+    await new Checkpointer(pair.source, pair.target, id, { cancelled: false }).writeCheckpoint(0, session);
+    checkpoints.push({
+      id,
+      session,
+      localRevision: (await local.get(id))._rev,
+      remoteRevision: (await remote.get(id))._rev
+    });
+  }
+  const imported = /* @__PURE__ */ new Set();
+  let withinBudget = true;
+  let lastSequence;
+  let consumed = false;
+  const key = (id, rev) => JSON.stringify([id, rev]);
+  return {
+    recordStoredRevisions(revisions) {
+      if (!withinBudget) return;
+      for (const revision of revisions) {
+        imported.add(key(revision.id, revision.rev));
+        if (imported.size > MAX_TRACKED_REVISIONS) {
+          imported.clear();
+          withinBudget = false;
+          return;
+        }
+      }
+    },
+    recordCheckpoint(sequence) {
+      lastSequence = sequence;
+    },
+    async fastForward() {
+      if (consumed) return false;
+      consumed = true;
+      if (!withinBudget || lastSequence === void 0 || !isCurrent()) return false;
+      if (await local.id() !== localId || await remote.id() !== remoteId) return false;
+      const localSequence = (await local.info()).update_seq;
+      let since = 0;
+      while (true) {
+        const changes = await local.changes({
+          since,
+          limit: 1e3,
+          style: "all_docs",
+          return_docs: true
+        });
+        for (const change of changes.results) {
+          for (const revision of change.changes) {
+            if (!imported.has(key(change.id, revision.rev))) return false;
+          }
+        }
+        if (changes.results.length < 1e3) break;
+        since = changes.last_seq;
+      }
+      if (!isCurrent() || (await local.info()).update_seq !== localSequence) return false;
+      const guard = (database, id, expectedRevision, session) => ({
+        adapter: database.adapter,
+        async get(requestedId) {
+          let document;
+          try {
+            document = await database.get(requestedId);
+          } catch (cause) {
+            throw new Error("The initial-fetch checkpoint is no longer available.", { cause });
+          }
+          if (requestedId !== id || document._rev !== expectedRevision || document.session_id !== session) {
+            throw new Error("The initial-fetch checkpoint changed before fast-forwarding.");
+          }
+          return document;
+        },
+        async put(document) {
+          if (document._id !== id || document._rev !== expectedRevision) {
+            throw new Error("The initial-fetch checkpoint no longer matches its import.");
+          }
+          const response = await database.put(document);
+          expectedRevision = response.rev;
+          return response;
+        }
+      });
+      for (const [index, checkpoint] of checkpoints.entries()) {
+        if (!isCurrent() || (await local.info()).update_seq !== localSequence) return false;
+        const guardedLocal = guard(local, checkpoint.id, checkpoint.localRevision, checkpoint.session);
+        const guardedRemote = guard(remote, checkpoint.id, checkpoint.remoteRevision, checkpoint.session);
+        const source = index === 0 ? guardedLocal : guardedRemote;
+        const target = index === 0 ? guardedRemote : guardedLocal;
+        await new Checkpointer(source, target, checkpoint.id, { cancelled: false }).writeCheckpoint(
+          index === 0 ? localSequence : lastSequence,
+          checkpoint.session
+        );
+      }
+      imported.clear();
+      return true;
+    }
+  };
+}
+export {
+  prepareInitialFetchFastForward
+};

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
+};