@powersync/service-module-mongodb 0.18.2 → 0.20.0

package/src/replication/MongoSnapshotter.ts

@@ -14,11 +14,13 @@ import { performance } from 'node:perf_hooks';
 import { MongoLSN } from '../common/MongoLSN.js';
 import { PostImagesOption } from '../types/types.js';
 import { escapeRegExp } from '../utils.js';
+import { CheckpointImplementation } from './checkpoints/CheckpointImplementation.js';
+import { createCheckpointImplementation } from './checkpoints/create-checkpoint-implementation.js';
 import { MongoManager } from './MongoManager.js';
-import { createCheckpoint, getMongoRelation, STANDALONE_CHECKPOINT_ID } from './MongoRelation.js';
+import { getMongoRelation } from './MongoRelation.js';
 import { ChunkedSnapshotQuery } from './MongoSnapshotQuery.js';
 import { ChangeStreamBatch, parseChangeDocument, rawChangeStream } from './RawChangeStream.js';
-import { CHECKPOINTS_COLLECTION } from './replication-utils.js';
+import { CHECKPOINTS_COLLECTION, detectDocumentDb } from './replication-utils.js';
 import { DirectSourceRowConverter, SourceRowConverter } from './SourceRowConverter.js';
 
 export interface MongoSnapshotterOptions {
@@ -72,6 +74,9 @@ export class MongoSnapshotter {
   private nextItemQueued: PromiseWithResolvers<void> | null = null;
   private lastTouchedAt = performance.now();
 
+  private isDocumentDb = false;
+  private _checkpointImplementation: CheckpointImplementation | null = null;
+
   constructor(options: MongoSnapshotterOptions) {
     this.storage = options.storage;
     this.metrics = options.metrics;
@@ -94,6 +99,9 @@ export class MongoSnapshotter {
     this.abortSignal.addEventListener('abort', () => {
       this.nextItemQueued?.resolve();
     });
+
+    // Errors here should not result in uncaught rejection - calling waitForInitialSnapshot is optional.
+    void this.initialSnapshotDone.promise.catch(() => {});
   }
 
   private get usePostImages() {
@@ -108,6 +116,48 @@ export class MongoSnapshotter {
     return this.storage.storageConfig.softDeleteCurrentData;
   }
 
+  /** The active checkpoint strategy. Only valid after ensureDetected(). */
+  private get checkpointImplementation(): CheckpointImplementation {
+    if (this._checkpointImplementation == null) {
+      throw new ServiceError(
+        ErrorCode.PSYNC_S1301,
+        'Checkpoint implementation not initialized - call ensureDetected() first'
+      );
+    }
+    return this._checkpointImplementation;
+  }
+
+  /**
+   * Detect DocumentDB and select the checkpoint implementation. Idempotent.
+   * Also validates server topology (sharded/standalone) for standard MongoDB.
+   */
+  private async ensureDetected(): Promise<void> {
+    if (this._checkpointImplementation != null) {
+      return;
+    }
+    this.isDocumentDb = await detectDocumentDb(this.defaultDb);
+    if (!this.isDocumentDb) {
+      const hello = await this.defaultDb.command({ hello: 1 });
+      if (hello.msg == 'isdbgrid') {
+        throw new ServiceError(
+          ErrorCode.PSYNC_S1341,
+          'Sharded MongoDB Clusters are not supported yet (including MongoDB Serverless instances).'
+        );
+      } else if (hello.setName == null) {
+        throw new ServiceError(
+          ErrorCode.PSYNC_S1342,
+          'Standalone MongoDB instances are not supported - use a replicaset.'
+        );
+      }
+    }
+    this._checkpointImplementation = createCheckpointImplementation(this.isDocumentDb, {
+      client: this.client,
+      db: this.defaultDb,
+      checkpointStreamId: this.checkpointStreamId,
+      logger: this.logger
+    });
+  }
+
   async checkSlot(): Promise<InitResult> {
     const status = await this.storage.getStatus();
     if (status.snapshotDone) {
@@ -119,12 +169,18 @@ export class MongoSnapshotter {
   }
 
   async setupCheckpointsCollection() {
+    await this.ensureDetected();
     const collection = await this.getCollectionInfo(this.defaultDb.databaseName, CHECKPOINTS_COLLECTION);
     if (collection == null) {
       await this.defaultDb.createCollection(CHECKPOINTS_COLLECTION, {
-        changeStreamPreAndPostImages: { enabled: true }
+        // DocumentDB does not support changeStreamPreAndPostImages.
+        ...(this.isDocumentDb ? {} : { changeStreamPreAndPostImages: { enabled: true } })
       });
-    } else if (this.usePostImages && collection.options?.changeStreamPreAndPostImages?.enabled != true) {
+    } else if (
+      !this.isDocumentDb &&
+      this.usePostImages &&
+      collection.options?.changeStreamPreAndPostImages?.enabled != true
+    ) {
       // Drop + create requires less permissions than collMod,
       // and we don't care about the data in this collection.
       await this.defaultDb.dropCollection(CHECKPOINTS_COLLECTION);
@@ -135,12 +191,22 @@ export class MongoSnapshotter {
       // Clear the collection on startup, to keep it clean
       // We never query this collection directly, and don't want to keep the data around.
       // We only use this to get data into the oplog/changestream.
-      await this.defaultDb.collection(CHECKPOINTS_COLLECTION).deleteMany({});
+      //
+      // The implementation supplies the filter: the sentinel implementation must
+      // preserve the sentinel checkpoint document, since its counter is the
+      // globally-ordered component of every committed DocumentDB LSN.
+      await this.defaultDb
+        .collection(CHECKPOINTS_COLLECTION)
+        .deleteMany(this.checkpointImplementation.checkpointClearFilter);
     }
   }
 
   async queueSnapshotTables(snapshotLsn: string | null) {
     await this.client.connect();
+    // Ensure isDocumentDb is set before any getSourceNamespaceFilters() call below
+    // (notably the validateSnapshotLsn resume path, which does not go through
+    // getSnapshotLsn). Idempotent.
+    await this.ensureDetected();
     await using writer = await this.storage.createWriter({
       zeroLSN: MongoLSN.ZERO.comparable,
       defaultSchema: this.defaultDb.databaseName,
@@ -256,7 +322,7 @@ export class MongoSnapshotter {
       for (const table of tables) {
         await this.snapshotTable(batch, table);
       }
-      const noCheckpointBefore = await createCheckpoint(this.client, this.defaultDb, STANDALONE_CHECKPOINT_ID);
+      const noCheckpointBefore = await this.checkpointImplementation.createStandaloneCheckpoint();
 
       await batch.markTableSnapshotDone(tables, noCheckpointBefore);
     }
@@ -300,7 +366,7 @@ export class MongoSnapshotter {
 
     // The checkpoint here is a marker - we need to replicate up to at least this
     // point before the data can be considered consistent.
-    const checkpoint = await createCheckpoint(this.client, this.defaultDb, STANDALONE_CHECKPOINT_ID);
+    const checkpoint = await this.checkpointImplementation.createStandaloneCheckpoint();
     if (this.queue.size != 0) {
       return;
     }
@@ -312,7 +378,7 @@ export class MongoSnapshotter {
     // KLUDGE: We need to create an extra checkpoint _after_ marking the snapshot done, to fix
     // issues with order of processing commits(). This is picked up by tests on postgres storage,
     // the issue may be specific to that storage engine.
-    await createCheckpoint(this.client, this.defaultDb, STANDALONE_CHECKPOINT_ID);
+    await this.checkpointImplementation.createStandaloneCheckpoint();
   }
 
   private async replicateTable(tableRequest: SourceTable) {
@@ -336,7 +402,7 @@ export class MongoSnapshotter {
     }
 
     await this.snapshotTable(writer, table);
-    const noCheckpointBefore = await createCheckpoint(this.client, this.defaultDb, STANDALONE_CHECKPOINT_ID);
+    const noCheckpointBefore = await this.checkpointImplementation.createStandaloneCheckpoint();
     await writer.markTableSnapshotDone([table], noCheckpointBefore);
 
     // This commit durably records the persisted ops, so a later checkpoint covers them.
@@ -355,6 +421,13 @@ export class MongoSnapshotter {
       return [];
     }
 
+    if (tablePattern.isSchemaWildcard) {
+      throw new ServiceError(
+        ErrorCode.PSYNC_R2201,
+        'Schema wildcards ("%") in table patterns are not supported for MongoDB connections.'
+      );
+    }
+
     const nameFilter = tablePattern.isWildcard
       ? new RegExp('^' + escapeRegExp(tablePattern.tablePrefix))
       : tablePattern.name;
@@ -516,19 +589,7 @@ export class MongoSnapshotter {
   }
 
   private async getSnapshotLsn(): Promise<string> {
-    const hello = await this.defaultDb.command({ hello: 1 });
-    // Basic sanity check
-    if (hello.msg == 'isdbgrid') {
-      throw new ServiceError(
-        ErrorCode.PSYNC_S1341,
-        'Sharded MongoDB Clusters are not supported yet (including MongoDB Serverless instances).'
-      );
-    } else if (hello.setName == null) {
-      throw new ServiceError(
-        ErrorCode.PSYNC_S1342,
-        'Standalone MongoDB instances are not supported - use a replicaset.'
-      );
-    }
+    await this.ensureDetected();
 
     // Open a change stream just to get a resume token for later use.
     // We could use clusterTime from the hello command, but that won't tell us if the
@@ -541,14 +602,19 @@ export class MongoSnapshotter {
     // Instead, we create a new checkpoint document, and wait until we get that document back in the stream.
     // To avoid potential race conditions with the checkpoint creation, we create a new checkpoint document
     // periodically until the timeout is reached.
+    //
+    // For the sentinel implementation (DocumentDB) there is no
+    // startAtOperationTime: the stream opens from "now" (lsn null) and the
+    // retry loop below re-creates checkpoints until one is observed.
 
     const LSN_TIMEOUT_SECONDS = 60;
     const LSN_CREATE_INTERVAL_SECONDS = 1;
 
-    const firstCheckpointLsn = await createCheckpoint(this.client, this.defaultDb, this.checkpointStreamId);
+    this.checkpointImplementation.seedPosition(null);
+    const startStreamFromLsn = await this.checkpointImplementation.createFirstBarrier();
     const filters = this.getSourceNamespaceFilters();
     const iter = this.rawChangeStreamBatches({
-      lsn: firstCheckpointLsn,
+      lsn: startStreamFromLsn,
       maxAwaitTimeMS: 0,
       signal: this.abortSignal,
       filters
@@ -563,7 +629,7 @@ export class MongoSnapshotter {
         break;
       }
       if (performance.now() - lastCheckpointCreated >= LSN_CREATE_INTERVAL_SECONDS * 1000) {
-        await createCheckpoint(this.client, this.defaultDb, this.checkpointStreamId);
+        await this.checkpointImplementation.createBatchCheckpoint();
         lastCheckpointCreated = performance.now();
       }
       batchesSeen += 1;
@@ -573,14 +639,15 @@ export class MongoSnapshotter {
         const ns = 'ns' in changeDocument && 'coll' in changeDocument.ns ? changeDocument.ns : undefined;
 
         if (ns?.coll == CHECKPOINTS_COLLECTION && 'documentKey' in changeDocument) {
-          const checkpointId = changeDocument.documentKey._id as string | mongo.ObjectId;
-          if (!this.checkpointStreamId.equals(checkpointId)) {
+          const kind = this.checkpointImplementation.event.observe(changeDocument);
+          if (kind != 'own-barrier') {
+            // Standalone events still feed the implementation's coordinate via
+            // event.observe above; we only resolve on our own barrier.
             continue;
           }
-          return new MongoLSN({
-            timestamp: changeDocument.clusterTime!,
-            resume_token: changeDocument._id
-          }).comparable;
+          // Observing our own barrier has set the coordinate (the barrier event
+          // carries the sentinel counter directly), so the LSN is ready.
+          return this.checkpointImplementation.event.lsn(changeDocument);
         }
 
         eventsSeen += 1;
@@ -638,7 +705,12 @@ export class MongoSnapshotter {
       }
     }
 
-    const nsFilter = multipleDatabases
+    // DocumentDB always opens a cluster-level change stream, even in single-database
+    // mode, so a coll-only filter would match same-named collections in other
+    // databases of the cluster. Filter on the full namespace whenever the stream
+    // is cluster-scoped. See ChangeStream.getSourceNamespaceFilters for details.
+    const useFullNamespaceFilter = this.isDocumentDb || multipleDatabases;
+    const nsFilter = useFullNamespaceFilter
       ? { ns: { $in: inFilters } }
       : { 'ns.coll': { $in: inFilters.map((ns) => ns.coll) } };
     if (regexFilters.length > 0) {
@@ -655,12 +727,15 @@ export class MongoSnapshotter {
     signal?: AbortSignal;
     tracer?: PerformanceTracer<'changestream'>;
   }): AsyncIterableIterator<ChangeStreamBatch> {
-    const lastLsn = options.lsn ? MongoLSN.fromSerialized(options.lsn) : null;
-    const startAfter = lastLsn?.timestamp;
-    const resumeAfter = lastLsn?.resumeToken;
+    const position = options.lsn ? this.checkpointImplementation.parseResumePosition(options.lsn) : null;
+    const startAfter = position?.startAfter ?? undefined;
+    const resumeAfter = position?.resumeAfter ?? undefined;
 
     let fullDocument: 'required' | 'updateLookup';
-    if (this.usePostImages) {
+    if (this.isDocumentDb) {
+      // DocumentDB does not support changeStreamPreAndPostImages, so 'required' won't work.
+      fullDocument = 'updateLookup';
+    } else if (this.usePostImages) {
       // 'read_only' or 'auto_configure'
       // Configuration happens during snapshot, or when we see new
       // collections.
@@ -669,27 +744,32 @@ export class MongoSnapshotter {
       fullDocument = 'updateLookup';
     }
     const streamOptions: mongo.ChangeStreamOptions & mongo.Document = {
-      showExpandedEvents: true,
       fullDocument
     };
-    const pipeline: mongo.Document[] = [
-      { $changeStream: streamOptions },
-      { $match: options.filters.$match },
-      { $changeStreamSplitLargeEvent: {} }
-    ];
+    if (!this.isDocumentDb) {
+      // DocumentDB does not support showExpandedEvents.
+      streamOptions.showExpandedEvents = true;
+    }
+    const pipeline: mongo.Document[] = [{ $changeStream: streamOptions }, { $match: options.filters.$match }];
+    if (!this.isDocumentDb) {
+      // DocumentDB does not support $changeStreamSplitLargeEvent.
+      pipeline.push({ $changeStreamSplitLargeEvent: {} });
+    }
 
     // Only one of these options can be supplied at a time.
     if (resumeAfter) {
       streamOptions.resumeAfter = resumeAfter;
-    } else {
+    } else if (startAfter != null) {
       // Legacy: We don't persist lsns without resumeTokens anymore, but we do still handle the
-      // case if we have an old one.
+      // case if we have an old one. The sentinel implementation never produces a startAfter,
+      // and a fresh DocumentDB stream opens from "now" with neither option set.
       streamOptions.startAtOperationTime = startAfter;
     }
 
     let watchDb: mongo.Db;
-    if (options.filters.multipleDatabases) {
-      // Requires readAnyDatabase@admin on Atlas
+    if (this.isDocumentDb || options.filters.multipleDatabases) {
+      // DocumentDB only supports cluster-level change streams.
+      // Requires readAnyDatabase@admin on Atlas.
       watchDb = this.client.db('admin');
       streamOptions.allChangesForCluster = true;
     } else {
@@ -697,9 +777,14 @@ export class MongoSnapshotter {
       watchDb = this.defaultDb;
     }
 
+    const maxAwaitTimeMS = options.maxAwaitTimeMS ?? this.maxAwaitTimeMS;
+
     return rawChangeStream(watchDb, pipeline, {
       batchSize: options.batchSize ?? this.snapshotChunkLength,
-      maxAwaitTimeMS: options.maxAwaitTimeMS ?? this.maxAwaitTimeMS,
+      maxAwaitTimeMS,
+      // maxAwaitTimeMS can be 0 for probe-style streams that do not want an idle wait.
+      // In that case there is no client-side wait to emulate for DocumentDB.
+      clientSideMaxAwaitTimeMS: this.isDocumentDb && maxAwaitTimeMS > 0,
       maxTimeMS: this.changeStreamTimeout,
       signal: options.signal,
       logger: this.logger,

package/src/replication/RawChangeStream.ts

@@ -1,4 +1,4 @@
-import { isMongoNetworkTimeoutError, isMongoServerError, mongo } from '@powersync/lib-service-mongodb';
+import { isMaxTimeMSExpiredError, isMongoServerError, isTimeoutError, mongo } from '@powersync/lib-service-mongodb';
 import {
   DatabaseConnectionError,
   ErrorCode,
@@ -6,18 +6,36 @@ import {
   ReplicationAssertionError
 } from '@powersync/lib-services-framework';
 import { PerformanceTracer } from '@powersync/service-core';
+import { performance } from 'node:perf_hooks';
+import { setTimeout as delay } from 'node:timers/promises';
 import { ChangeStreamInvalidatedError } from './ChangeStream.js';
 
+// Keep the DocumentDB idle-poll workaround from adding the full maxAwaitTimeMS
+// as local latency when an update arrives just after an empty batch.
+const CLIENT_SIDE_MAX_AWAIT_TIME_MS_DELAY_CAP_MS = 1_000;
+
 export interface RawChangeStreamOptions {
   signal?: AbortSignal;
 
   /**
    * How long to wait for new data per batch (max time for long-polling).
+   * This is sent as maxTimeMS for the getMore command.
    *
-   * This is used for maxTimeMS for the getMore command.
+   * A value of 0 is allowed for probe-style streams that do not want an idle
+   * wait; in that case PowerSync also skips the local empty-batch delay.
    */
   maxAwaitTimeMS: number;
 
+  /**
+   * Also enforce maxAwaitTimeMS on the client for empty getMore batches.
+   *
+   * Azure DocumentDB currently returns idle getMore calls before maxTimeMS. When
+   * this is enabled, empty batches are delayed locally (capped at 1s) to avoid
+   * tight polling. We still send maxTimeMS so this remains compatible with
+   * servers that handle maxAwaitTimeMS correctly.
+   */
+  clientSideMaxAwaitTimeMS?: boolean;
+
   /**
    * Timeout for the initial aggregate command.
    */
@@ -212,31 +230,32 @@ async function* rawChangeStreamInner(
       options.signal?.throwIfAborted();
 
       using commandSpan = options.tracer?.span('changestream', 'getmore');
-      const getMoreResult: mongo.Document = await db
-        .command(
-          {
-            getMore: cursorId,
-            collection: nsCollection,
-            batchSize: batchSizer.next(),
-            maxTimeMS: options.maxAwaitTimeMS
-          },
-          { session, raw: true }
-        )
-        .catch((e) => {
-          if (isMongoServerError(e) && e.codeName == 'CursorKilled') {
-            // This may be due to the killCursors command issued when aborting.
-            // In that case, use the abort error instead.
-            options.signal?.throwIfAborted();
+      const getMoreStartedAt = performance.now();
+      const getMoreCommand: mongo.Document = {
+        getMore: cursorId,
+        collection: nsCollection,
+        batchSize: batchSizer.next(),
+        maxTimeMS: options.maxAwaitTimeMS
+      };
+      // Azure DocumentDB currently returns empty getMore batches before
+      // maxTimeMS expires. Keep maxTimeMS for forward compatibility with the
+      // server-side behavior, and when client-side mode is enabled, enforce the
+      // capped idle wait locally for empty batches below.
+      const getMoreResult: mongo.Document = await db.command(getMoreCommand, { session, raw: true }).catch((e) => {
+        if (isMongoServerError(e) && e.codeName == 'CursorKilled') {
+          // This may be due to the killCursors command issued when aborting.
+          // In that case, use the abort error instead.
+          options.signal?.throwIfAborted();
+        }
+
+        if (isResumableChangeStreamError(e)) {
+          if (isTimeoutError(e)) {
+            batchSizer.reduceAfterError();
           }
-
-          if (isResumableChangeStreamError(e)) {
-            if (isTimeoutError(e)) {
-              batchSizer.reduceAfterError();
-            }
-            throw new ResumableChangeStreamError(e.message, { cause: e });
-          }
-          throw mapChangeStreamError(e);
-        });
+          throw new ResumableChangeStreamError(e.message, { cause: e });
+        }
+        throw mapChangeStreamError(e);
+      });
 
       commandSpan?.end();
 
@@ -249,6 +268,13 @@ async function* rawChangeStreamInner(
         // postBatchResumeToken is returned in MongoDB 4.0.7 and later, and we support 6.0+
         throw new ReplicationAssertionError(`postBatchResumeToken from aggregate response`);
       }
+      if (options.clientSideMaxAwaitTimeMS && nextBatch.length == 0) {
+        const remainingMaxAwaitTimeMS = Math.ceil(options.maxAwaitTimeMS - (performance.now() - getMoreStartedAt));
+        if (remainingMaxAwaitTimeMS > 0) {
+          const clientSideDelayMs = Math.min(remainingMaxAwaitTimeMS, CLIENT_SIDE_MAX_AWAIT_TIME_MS_DELAY_CAP_MS);
+          await delay(clientSideDelayMs, undefined, { signal: options.signal });
+        }
+      }
       yield {
         events: nextBatch,
         resumeToken: cursor.postBatchResumeToken,
@@ -400,10 +426,6 @@ export function parseChangeDocument(buffer: Buffer): ProjectedChangeStreamDocume
   return doc as any;
 }
 
-function isTimeoutError(e: unknown) {
-  return isMongoNetworkTimeoutError(e) || (isMongoServerError(e) && e.codeName == 'MaxTimeMSExpired');
-}
-
 function isResumableChangeStreamError(e: unknown) {
   // See: https://github.com/mongodb/specifications/blob/master/source/change-streams/change-streams.md#resumable-error
   if (!isMongoServerError(e)) {
@@ -415,8 +437,8 @@ function isResumableChangeStreamError(e: unknown) {
   } else if (e.hasErrorLabel('ResumableChangeStreamError')) {
     // For servers with wire version 9 or higher (server version 4.4 or higher), any server error with the ResumableChangeStreamError error label.
     return true;
-  } else if (e.codeName == 'MaxTimeMSExpired') {
-    // Our own exception for MaxTimeMSExpired.
+  } else if (isMaxTimeMSExpiredError(e)) {
+    // Our own exception for maxTimeMS timeouts.
     // This can help us retry faster, with a smaller batch size (if initialBatchSize is set to 1), which should hopefully avoid the timeout.
     return true;
   } else {

package/src/replication/checkpoints/CheckpointImplementation.ts

@@ -0,0 +1,167 @@
+import { mongo } from '@powersync/lib-service-mongodb';
+import { Logger } from '@powersync/lib-services-framework';
+import { ReplicationHeadCallback, storage } from '@powersync/service-core';
+
+import { ProjectedChangeStreamDocument } from '../RawChangeStream.js';
+
+/**
+ * Classification of an event on the `_powersync_checkpoints` collection.
+ *
+ * - 'standalone': source-wide checkpoint (write checkpoints, keepalive bumps,
+ *   snapshot markers). Processed regardless of which process created it.
+ * - 'own-barrier': this stream's private batch barrier document.
+ * - 'foreign': another stream's barrier document — ignore.
+ */
+export type CheckpointEventKind = 'standalone' | 'own-barrier' | 'foreign';
+
+export interface StreamResumePosition {
+  resumeAfter: mongo.ResumeToken | null;
+  /**
+   * Legacy startAtOperationTime fallback. Only produced by the timestamp implementation,
+   * and only for old LSNs persisted without a resume token.
+   */
+  startAfter: mongo.Timestamp | null;
+}
+
+export interface CheckpointImplementationContext {
+  client: mongo.MongoClient;
+  db: mongo.Db;
+  checkpointStreamId: mongo.ObjectId;
+  logger: Logger;
+}
+
+/**
+ * Event-interpretation surface of a {@link CheckpointImplementation}. Every method
+ * operates on a single raw change event.
+ *
+ * Ordering contract: {@link observe} must be called before {@link lsn} for a given
+ * event, so the sentinel implementation's coordinate is current.
+ */
+export interface CheckpointEventApi {
+  /**
+   * Classify a checkpoint-collection event and absorb any coordinate it
+   * carries (sentinel implementation). Must be called for every checkpoint event, in
+   * stream order.
+   */
+  observe(doc: ProjectedChangeStreamDocument): CheckpointEventKind;
+
+  /**
+   * Comparable LSN for committing/resuming at this event.
+   *
+   * Note this is not purely a function of `doc`. The timestamp implementation
+   * derives the whole LSN from the event (its coordinate is the event's
+   * clusterTime). The sentinel implementation pairs the *tracked* coordinate
+   * (updated by {@link observe}) with the event's resume token, because data
+   * events carry no coordinate of their own — hence the observe-before-lsn
+   * contract.
+   */
+  lsn(doc: ProjectedChangeStreamDocument): string;
+
+  /** Whether a barrier marker from {@link CheckpointImplementation.createBatchCheckpoint} is resolved by this event. */
+  resolvesBarrier(marker: string, doc: ProjectedChangeStreamDocument): boolean;
+}
+
+/**
+ * Strategy for producing and interpreting replication checkpoints.
+ *
+ * Two implementations exist:
+ *
+ * - {@link TimestampCheckpointImplementation}: standard MongoDB. The ordered LSN
+ *   coordinate is the oplog clusterTime, which is unique per operation and
+ *   parseable from resume tokens.
+ * - {@link SentinelCheckpointImplementation}: for sources without a usable clusterTime
+ *   (DocumentDB, and technically usable on any MongoDB). The ordered coordinate
+ *   is a shared monotonic counter document, observed through the change
+ *   stream itself.
+ *
+ * An implementation instance belongs to a single ChangeStream (or API adapter) and may
+ * hold per-stream coordinate state; call {@link seedPosition} at the start of
+ * each streaming loop.
+ */
+export interface CheckpointImplementation {
+  /** LSN representing "before any data". */
+  readonly zeroLsn: string;
+
+  /** Parse a stored LSN into change stream resume options. Pure. */
+  parseResumePosition(lsn: string): StreamResumePosition;
+
+  /** Reset/seed the implementation's coordinate state for a new stream loop. */
+  seedPosition(lsn: string | null): void;
+
+  /** Log the resume position at the start of a streaming loop. */
+  logResume(lsn: string): void;
+
+  /**
+   * Create a source-wide consistency checkpoint (snapshot boundaries,
+   * `no_checkpoint_before` markers). Returns a comparable LSN.
+   */
+  createStandaloneCheckpoint(): Promise<string>;
+
+  /**
+   * Create a batch barrier for this stream. Returns a marker that is resolved
+   * by a later change stream event via {@link CheckpointEventApi.resolvesBarrier}.
+   */
+  createBatchCheckpoint(): Promise<string>;
+
+  /**
+   * Create the first batch barrier for snapshot-LSN acquisition and return the
+   * LSN to open the change stream from, or null to open from "now".
+   *
+   * The timestamp implementation's barrier marker is itself a comparable LSN, so
+   * the stream resumes from it. The sentinel implementation's marker is opaque
+   * (content-matched) and carries no resume position, so it returns null and the
+   * stream opens from the current point.
+   */
+  createFirstBarrier(): Promise<string | null>;
+
+  /**
+   * Idle keepalive for an empty change stream batch. May persist a checkpoint
+   * directly (timestamp implementation) or nudge the source so that a later event
+   * commits (sentinel implementation).
+   */
+  keepalive(batch: storage.BucketStorageBatch, resumeToken: mongo.ResumeToken): Promise<void>;
+
+  /**
+   * Build a comparable LSN from a bare batch-level resume token (no change
+   * event). Used for the per-batch `setResumeLsn` progress marker.
+   *
+   * The timestamp implementation parses the timestamp embedded in the token.
+   * The sentinel implementation pairs the token with the current coordinate.
+   */
+  lsnFromResumeToken(resumeToken: mongo.ResumeToken): { lsn: string; timestamp: Date | null };
+
+  /**
+   * Source-side replication head for write checkpoints. The LSN passed to the
+   * callback must compare at or below any LSN committed after the caller's
+   * preceding writes.
+   */
+  createReplicationHead<T>(callback: ReplicationHeadCallback<T>): Promise<T>;
+
+  /** Event-interpretation methods, all operating on a single raw change event. */
+  readonly event: CheckpointEventApi;
+
+  /** Filter for clearing the checkpoints collection on startup. */
+  readonly checkpointClearFilter: mongo.Filter<mongo.Document>;
+}
+
+/**
+ * Extract the event timestamp: clusterTime when present, otherwise wallTime
+ * truncated to second precision.
+ */
+export function getEventTimestamp(changeDocument: ProjectedChangeStreamDocument): mongo.Timestamp {
+  if (changeDocument.clusterTime) {
+    return changeDocument.clusterTime;
+  }
+  const wallTime = (changeDocument as any).wallTime as Date | undefined;
+  if (wallTime != null) {
+    return mongo.Timestamp.fromBits(0, Math.floor(wallTime.getTime() / 1000));
+  }
+  throw new Error('Change event has neither clusterTime nor wallTime');
+}
+
+export function getCheckpointId(doc: ProjectedChangeStreamDocument): string | mongo.ObjectId | null {
+  if (!('documentKey' in doc)) {
+    return null;
+  }
+  return doc.documentKey._id as string | mongo.ObjectId;
+}