@powersync/service-module-mongodb 0.0.0-dev-20260602073133 → 0.0.0-dev-20260803144812

package/test/src/change_stream.test.ts

@@ -3,12 +3,14 @@ import { setTimeout } from 'node:timers/promises';
 import { describe, expect, test, vi } from 'vitest';
 
 import { mongo } from '@powersync/lib-service-mongodb';
-import { createWriteCheckpoint, storage } from '@powersync/service-core';
+import { createWriteCheckpoint, storage, WriteCheckpointBatcher } from '@powersync/service-core';
 import { test_utils } from '@powersync/service-core-tests';
 
 import { MongoRouteAPIAdapter } from '@module/api/MongoRouteAPIAdapter.js';
 import { PostImagesOption } from '@module/types/types.js';
 import { ChangeStreamTestContext } from './change_stream_utils.js';
+import { DATABASE_TYPE, DatabaseType } from './DatabaseType.js';
+import { testTimeout } from './test-timeouts.js';
 import { describeWithStorage, StorageVersionTestContext, TEST_CONNECTION_OPTIONS } from './util.js';
 
 const BASIC_SYNC_RULES = `
@@ -19,7 +21,7 @@ bucket_definitions:
 `;
 
 describe('change stream', () => {
-  describeWithStorage({ timeout: 20_000 }, defineChangeStreamTests);
+  describeWithStorage({ timeout: testTimeout(20_000, { cloudOverride: 40_000 }) }, defineChangeStreamTests);
 });
 
 function defineChangeStreamTests({ factory, storageVersion }: StorageVersionTestContext) {
@@ -28,7 +30,8 @@ function defineChangeStreamTests({ factory, storageVersion }: StorageVersionTest
   const openContext = (options?: Parameters<typeof ChangeStreamTestContext.open>[1]) => {
     return ChangeStreamTestContext.open(factory, { ...options, storageVersion });
   };
-  test('replicating basic values', async () => {
+  // DocumentDB does not support changeStreamPreAndPostImages, which this test requires via postImages: READ_ONLY.
+  test.skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)('replicating basic values', async () => {
     await using context = await openContext({
       mongoOptions: { postImages: PostImagesOption.READ_ONLY }
     });
@@ -74,7 +77,10 @@ bucket_definitions:
       - SELECT _id as id, description, num FROM "test_%"`);
 
     await db.createCollection('test_data', {
-      changeStreamPreAndPostImages: { enabled: false }
+      // DocumentDB does not support changeStreamPreAndPostImages, even when
+      // explicitly disabled. This test only needs a collection to exercise
+      // fatal error recovery, so omit the option in DocumentDB mode.
+      ...(DATABASE_TYPE == DatabaseType.MONGODB ? { changeStreamPreAndPostImages: { enabled: false } } : {})
     });
     const collection = db.collection('test_data');
 
@@ -152,7 +158,7 @@ bucket_definitions:
     await context.updateSyncRules(BASIC_SYNC_RULES);
 
     await db.createCollection('test_data', {
-      changeStreamPreAndPostImages: { enabled: false }
+      changeStreamPreAndPostImages: DATABASE_TYPE == DatabaseType.MONGODB ? { enabled: false } : undefined
     });
     testId = new mongo.ObjectId();
     collection = db.collection('test_data');
@@ -167,7 +173,9 @@ bucket_definitions:
     expect(test_utils.reduceBucket(data).slice(1)).toEqual([]);
   });
 
-  test('updateLookup - no fullDocument available', async () => {
+  // DocumentDB always materializes a write-time post-image for updateLookup, so the 'fullDocument unavailable'
+  // case this test exercises (update treated as a remove) cannot occur there.
+  test.skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)('updateLookup - no fullDocument available', async () => {
     await using context = await openContext({
       mongoOptions: { postImages: PostImagesOption.OFF }
     });
@@ -179,6 +187,9 @@ bucket_definitions:
       - SELECT _id as id, description, num FROM "test_data"`);
 
     await db.createCollection('test_data', {
+      // DocumentDB does not support changeStreamPreAndPostImages, even when
+      // explicitly disabled. This test only needs a collection to exercise
+      // fatal error recovery, so omit the option in DocumentDB mode.
       changeStreamPreAndPostImages: { enabled: false }
     });
     const collection = db.collection('test_data');
@@ -211,7 +222,8 @@ bucket_definitions:
     ]);
   });
 
-  test('postImages - autoConfigure', async () => {
+  // DocumentDB does not support changeStreamPreAndPostImages (post-images).
+  test.skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)('postImages - autoConfigure', async () => {
     // Similar to the above test, but with postImages enabled.
     // This resolves the consistency issue.
     await using context = await openContext({
@@ -259,7 +271,8 @@ bucket_definitions:
     ]);
   });
 
-  test('postImages - on', async () => {
+  // DocumentDB does not support changeStreamPreAndPostImages (post-images).
+  test.skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)('postImages - on', async () => {
     // Similar to postImages - autoConfigure, but does not auto-configure.
     // changeStreamPreAndPostImages must be manually configured.
     await using context = await openContext({
@@ -408,7 +421,9 @@ bucket_definitions:
     ]);
   });
 
-  test('replicating dropCollection', async () => {
+  // Collection drop events are not currently replicated on DocumentDB: they are not delivered through the
+  // cluster-level change stream the way standard MongoDB delivers them, so the drop is not applied as a remove.
+  test.skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)('replicating dropCollection', async () => {
     await using context = await openContext();
     const { db } = context;
     const syncRuleContent = `
@@ -440,7 +455,9 @@ bucket_definitions:
     ]);
   });
 
-  test('replicating renameCollection', async () => {
+  // Collection rename events are not currently replicated on DocumentDB: they are not delivered through the
+  // cluster-level change stream the way standard MongoDB delivers them.
+  test.skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)('replicating renameCollection', async () => {
     await using context = await openContext();
     const { db } = context;
     const syncRuleContent = `
@@ -471,7 +488,9 @@ bucket_definitions:
     ]);
   });
 
-  test.runIf(supportsConcurrentSnapshots)(
+  // Concurrent-snapshot regression test driven by collection drop/recreate DDL events, which DocumentDB does
+  // not deliver through the cluster-level change stream the way standard MongoDB does.
+  test.runIf(supportsConcurrentSnapshots && DATABASE_TYPE != DatabaseType.DOCUMENTDB)(
     'collection recreated while queued snapshot is waiting does not stall checkpoints',
     async () => {
       // This is a regression test for a specific timing issue in concurrent snapshot logic.
@@ -625,6 +644,10 @@ bucket_definitions:
       type: 'mongodb',
       ...TEST_CONNECTION_OPTIONS
     });
+    const writeCheckpointBatcher = new WriteCheckpointBatcher(
+      () => api,
+      () => context.factory
+    );
 
     context.startStreaming();
 
@@ -641,8 +664,7 @@ bucket_definitions:
         createWriteCheckpoint({
           userId: 'test_user',
           clientId: 'test_client' + i,
-          api,
-          storage: context.factory
+          batcher: writeCheckpointBatcher
         })
       )
     );
@@ -652,12 +674,14 @@ bucket_definitions:
 
     // We need at least 1 commit.
     expect(commitCount).toBeGreaterThan(0);
-    // The previous implementation greated 1 commit per checkpoint, which is bad for performance.
+    // The previous implementation created 1 commit per checkpoint, which is bad for performance.
     // We expect a small number here - typically 2-10, but allow for anything less than the total number of checkpoints.
     expect(commitCount).toBeLessThan(checkpointCount + 1);
   });
 
-  test('large record', async () => {
+  test
+    // DocumentDBDB does not support changeStreamSplitLargeEvent
+    .skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)('large record', async () => {
     // Test a large update.
 
     // Without $changeStreamSplitLargeEvent, we get this error:
@@ -729,75 +753,83 @@ bucket_definitions:
     expect(data).toMatchObject([]);
   });
 
-  test('postImages - new collection with postImages enabled', async () => {
-    await using context = await openContext({
-      mongoOptions: { postImages: PostImagesOption.AUTO_CONFIGURE }
-    });
-    const { db } = context;
-    await context.updateSyncRules(`
+  // DocumentDB does not support changeStreamPreAndPostImages (post-images).
+  test.skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)(
+    'postImages - new collection with postImages enabled',
+    async () => {
+      await using context = await openContext({
+        mongoOptions: { postImages: PostImagesOption.AUTO_CONFIGURE }
+      });
+      const { db } = context;
+      await context.updateSyncRules(`
 bucket_definitions:
   global:
     data:
       - SELECT _id as id, description FROM "test_%"`);
 
-    await context.replicateSnapshot();
+      await context.replicateSnapshot();
 
-    await db.createCollection('test_data', {
-      // enabled: true here - everything should work
-      changeStreamPreAndPostImages: { enabled: true }
-    });
-    const collection = db.collection('test_data');
-    const result = await collection.insertOne({ description: 'test1' });
-    const test_id = result.insertedId;
-    await collection.updateOne({ _id: test_id }, { $set: { description: 'test2' } });
+      await db.createCollection('test_data', {
+        // enabled: true here - everything should work
+        changeStreamPreAndPostImages: { enabled: true }
+      });
+      const collection = db.collection('test_data');
+      const result = await collection.insertOne({ description: 'test1' });
+      const test_id = result.insertedId;
+      await collection.updateOne({ _id: test_id }, { $set: { description: 'test2' } });
 
-    context.startStreaming();
+      context.startStreaming();
 
-    const data = await context.getBucketData('global[]');
-    if (data.length == 3) {
-      expect(data).toMatchObject([
-        // An extra op here, since this triggers a snapshot in addition to getting the event.
-        test_utils.putOp('test_data', { id: test_id!.toHexString(), description: 'test2' }),
-        test_utils.putOp('test_data', { id: test_id!.toHexString(), description: 'test1' }),
-        test_utils.putOp('test_data', { id: test_id!.toHexString(), description: 'test2' })
-      ]);
-    } else {
-      expect(data).toMatchObject([
-        test_utils.putOp('test_data', { id: test_id!.toHexString(), description: 'test1' }),
-        test_utils.putOp('test_data', { id: test_id!.toHexString(), description: 'test2' })
-      ]);
+      const data = await context.getBucketData('global[]');
+      if (data.length == 3) {
+        expect(data).toMatchObject([
+          // An extra op here, since this triggers a snapshot in addition to getting the event.
+          test_utils.putOp('test_data', { id: test_id!.toHexString(), description: 'test2' }),
+          test_utils.putOp('test_data', { id: test_id!.toHexString(), description: 'test1' }),
+          test_utils.putOp('test_data', { id: test_id!.toHexString(), description: 'test2' })
+        ]);
+      } else {
+        expect(data).toMatchObject([
+          test_utils.putOp('test_data', { id: test_id!.toHexString(), description: 'test1' }),
+          test_utils.putOp('test_data', { id: test_id!.toHexString(), description: 'test2' })
+        ]);
+      }
     }
-  });
+  );
 
-  test('postImages - new collection with postImages disabled', async () => {
-    await using context = await openContext({
-      mongoOptions: { postImages: PostImagesOption.AUTO_CONFIGURE }
-    });
-    const { db } = context;
-    await context.updateSyncRules(`
+  // DocumentDB does not support changeStreamPreAndPostImages (post-images).
+  test.skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)(
+    'postImages - new collection with postImages disabled',
+    async () => {
+      await using context = await openContext({
+        mongoOptions: { postImages: PostImagesOption.AUTO_CONFIGURE }
+      });
+      const { db } = context;
+      await context.updateSyncRules(`
 bucket_definitions:
   global:
     data:
       - SELECT _id as id, description FROM "test_data%"`);
 
-    await context.replicateSnapshot();
+      await context.replicateSnapshot();
 
-    await db.createCollection('test_data', {
-      // enabled: false here, but autoConfigure will enable it.
-      // Unfortunately, that is too late, and replication must be restarted.
-      changeStreamPreAndPostImages: { enabled: false }
-    });
-    const collection = db.collection('test_data');
-    const result = await collection.insertOne({ description: 'test1' });
-    const test_id = result.insertedId;
-    await collection.updateOne({ _id: test_id }, { $set: { description: 'test2' } });
+      await db.createCollection('test_data', {
+        // enabled: false here, but autoConfigure will enable it.
+        // Unfortunately, that is too late, and replication must be restarted.
+        changeStreamPreAndPostImages: { enabled: false }
+      });
+      const collection = db.collection('test_data');
+      const result = await collection.insertOne({ description: 'test1' });
+      const test_id = result.insertedId;
+      await collection.updateOne({ _id: test_id }, { $set: { description: 'test2' } });
 
-    context.startStreaming();
+      context.startStreaming();
 
-    await expect(() => context.getBucketData('global[]')).rejects.toMatchObject({
-      message: expect.stringContaining('stream was configured to require a post-image for all update events')
-    });
-  });
+      await expect(() => context.getBucketData('global[]')).rejects.toMatchObject({
+        message: expect.stringContaining('stream was configured to require a post-image for all update events')
+      });
+    }
+  );
 
   test('recover from error', async () => {
     await using context = await openContext();
@@ -809,7 +841,10 @@ bucket_definitions:
       - SELECT _id as id, description, num FROM "test_data"`);
 
     await db.createCollection('test_data', {
-      changeStreamPreAndPostImages: { enabled: false }
+      // DocumentDB does not support changeStreamPreAndPostImages, even when
+      // explicitly disabled. This test only needs a collection to exercise
+      // fatal error recovery, so omit the option in DocumentDB mode.
+      changeStreamPreAndPostImages: DATABASE_TYPE == DatabaseType.MONGODB ? { enabled: false } : undefined
     });
 
     const collection = db.collection('test_data');
@@ -820,9 +855,9 @@ bucket_definitions:
 
     // Simulate an error
     await context.storage!.reportError(new Error('simulated error'));
-    const syncRules = await context.factory.getActiveSyncRulesContent();
+    const syncRules = (await context.factory.getActiveSyncConfig())?.content;
     expect(syncRules).toBeTruthy();
-    expect(syncRules?.last_fatal_error).toEqual('simulated error');
+    expect((await syncRules?.getSyncConfigStatus())?.last_fatal_error).toEqual('simulated error');
 
     // The next checkpoint should clear the error.
     await context.getCheckpoint();
@@ -830,10 +865,11 @@ bucket_definitions:
     // Just wait, and check that the error is cleared automatically.
     await vi.waitUntil(
       async () => {
-        const error = (await context.factory.getActiveSyncRulesContent())?.last_fatal_error;
+        const syncRules = (await context.factory.getActiveSyncConfig())?.content;
+        const error = (await syncRules?.getSyncConfigStatus())?.last_fatal_error;
         return error == null;
       },
-      { timeout: 2_000 }
+      { timeout: testTimeout(2_000, { cloudOverride: 5_000 }) }
     );
   });
 }

package/test/src/change_stream_utils.ts

@@ -5,6 +5,7 @@ import {
   createCoreReplicationMetrics,
   initializeCoreReplicationMetrics,
   InternalOpId,
+  isBatchEnd,
   LEGACY_STORAGE_VERSION,
   OplogEntry,
   ProtocolOpId,
@@ -19,9 +20,15 @@ import {
 } from '@powersync/service-core';
 import { bucketRequest, METRICS_HELPER, test_utils } from '@powersync/service-core-tests';
 
+import { SentinelLSN } from '@module/common/SentinelLSN.js';
 import { ChangeStream, ChangeStreamOptions } from '@module/replication/ChangeStream.js';
 import { MongoManager } from '@module/replication/MongoManager.js';
-import { createCheckpoint, STANDALONE_CHECKPOINT_ID } from '@module/replication/MongoRelation.js';
+import {
+  createCheckpoint,
+  createSentinelCheckpointLsn,
+  STANDALONE_CHECKPOINT_ID
+} from '@module/replication/MongoRelation.js';
+import { detectDocumentDb } from '@module/replication/replication-utils.js';
 import { NormalizedMongoConnectionConfig } from '@module/types/types.js';
 
 import { clearTestDb, TEST_CONNECTION_OPTIONS } from './util.js';
@@ -30,7 +37,7 @@ export class ChangeStreamTestContext {
   private _walStream?: ChangeStream;
   private abortController = new AbortController();
   private settledReplicationPromise?: Promise<PromiseSettledResult<void>>;
-  private syncRulesContent?: storage.PersistedSyncRulesContent;
+  private syncRulesContent?: storage.PersistedSyncConfigContent;
   public storage?: SyncRulesBucketStorage;
 
   /**
@@ -46,6 +53,11 @@ export class ChangeStreamTestContext {
       storageVersion?: number;
       mongoOptions?: Partial<NormalizedMongoConnectionConfig>;
       streamOptions?: Partial<ChangeStreamOptions>;
+      /**
+       * Optional override for tests that need to force a mode. By default the
+       * test context detects DocumentDB from the hello response.
+       */
+      documentDbMode?: boolean;
     }
   ) {
     const f = await factory({ doNotClear: options?.doNotClear });
@@ -56,15 +68,17 @@ export class ChangeStreamTestContext {
     }
 
     const storageVersion = options?.storageVersion ?? LEGACY_STORAGE_VERSION;
+    const documentDbMode = options?.documentDbMode ?? (await detectDocumentDb(connectionManager.db));
 
-    return new ChangeStreamTestContext(f, connectionManager, options?.streamOptions, storageVersion);
+    return new ChangeStreamTestContext(f, connectionManager, options?.streamOptions, storageVersion, documentDbMode);
   }
 
   constructor(
     public factory: BucketStorageFactory,
     public connectionManager: MongoManager,
     private streamOptions: Partial<ChangeStreamOptions> = {},
-    private storageVersion: number = LEGACY_STORAGE_VERSION
+    private storageVersion: number = LEGACY_STORAGE_VERSION,
+    private documentDbMode: boolean = false
   ) {
     createCoreReplicationMetrics(METRICS_HELPER.metricsEngine);
     initializeCoreReplicationMetrics(METRICS_HELPER.metricsEngine);
@@ -101,26 +115,37 @@ export class ChangeStreamTestContext {
   }
 
   async updateSyncRules(content: string) {
-    const syncRules = await this.factory.updateSyncRules(
+    const replicationStream = await this.factory.updateSyncRules(
       updateSyncRulesFromYaml(content, { validate: true, storageVersion: this.storageVersion })
     );
-    this.syncRulesContent = syncRules;
-    this.storage = this.factory.getInstance(syncRules);
+    this.syncRulesContent = replicationStream.syncConfigContent[0];
+    this.storage = this.factory.getInstance(replicationStream);
     return this.storage!;
   }
 
   async loadNextSyncRules() {
-    const syncRules = await this.factory.getNextSyncRulesContent();
-    if (syncRules == null) {
+    const syncConfig = await this.factory.getDeployingSyncConfig();
+    if (syncConfig == null) {
       throw new Error(`Next sync config not available`);
     }
 
-    this.syncRulesContent = syncRules;
-    this.storage = this.factory.getInstance(syncRules);
+    this.syncRulesContent = syncConfig.content;
+    this.storage = syncConfig.storage;
+    return this.storage!;
+  }
+
+  async loadActiveSyncRules() {
+    const syncConfig = await this.factory.getActiveSyncConfig();
+    if (syncConfig == null) {
+      throw new Error(`Active sync config not found`);
+    }
+
+    this.syncRulesContent = syncConfig.content;
+    this.storage = syncConfig.storage;
     return this.storage!;
   }
 
-  private getSyncRulesContent(): storage.PersistedSyncRulesContent {
+  private getSyncConfigContent(): storage.PersistedSyncConfigContent {
     if (this.syncRulesContent == null) {
       throw new Error('Sync config not configured - call updateSyncRules() first');
     }
@@ -143,6 +168,7 @@ export class ChangeStreamTestContext {
       // a long time to abort the stream.
       maxAwaitTimeMS: this.streamOptions?.maxAwaitTimeMS ?? 200,
       snapshotChunkLength: this.streamOptions?.snapshotChunkLength,
+      keepaliveIntervalMs: this.streamOptions?.keepaliveIntervalMs,
       storageHooks: this.streamOptions?.storageHooks,
       snapshotHooks: this.streamOptions?.snapshotHooks,
       logger: this.streamOptions?.logger
@@ -170,7 +196,24 @@ export class ChangeStreamTestContext {
    * would result in inconsistent data.
    */
   async markSnapshotConsistent() {
-    const checkpoint = await createCheckpoint(this.client, this.db, STANDALONE_CHECKPOINT_ID);
+    let checkpoint: string;
+    if (this.documentDbMode) {
+      const sentinelCheckpoint = SentinelLSN.fromSerialized(await createSentinelCheckpointLsn(this.client, this.db));
+      const status = await this.storage!.getStatus();
+      const resumeFrom = status.resumeLsn;
+      const resumeToken = resumeFrom ? SentinelLSN.fromSerialized(resumeFrom).resumeToken : null;
+
+      // This helper artificially marks the snapshot as consistent without
+      // waiting for the stream to observe the sentinel. Keep the sentinel as the
+      // comparable position, but carry forward the existing snapshot resume
+      // token so later DocumentDB streaming still resumes from a real token.
+      checkpoint = new SentinelLSN({
+        sentinel: sentinelCheckpoint.sentinel,
+        resume_token: resumeToken
+      }).comparable;
+    } else {
+      checkpoint = await createCheckpoint(this.db, STANDALONE_CHECKPOINT_ID);
+    }
 
     await using writer = await this.storage!.createWriter(test_utils.BATCH_OPTIONS);
     await writer.keepalive(checkpoint);
@@ -197,37 +240,65 @@ export class ChangeStreamTestContext {
 
   async getBucketsDataBatch(buckets: Record<string, InternalOpId>, options?: { timeout?: number }) {
     let checkpoint = await this.getCheckpoint(options);
-    const syncRules = this.getSyncRulesContent();
-    const map = Object.entries(buckets).map(([bucket, start]) => bucketRequest(syncRules, bucket, start));
+    const syncConfigContent = this.getSyncConfigContent();
+    const map = Object.entries(buckets).map(([bucket, start]) => bucketRequest(syncConfigContent, bucket, start));
     return test_utils.fromAsync(this.storage!.getBucketDataBatch(checkpoint, map));
   }
 
   async getBucketData(bucket: string, start?: ProtocolOpId | InternalOpId | undefined, options?: { timeout?: number }) {
+    const checkpoint = await this.getCheckpoint(options);
+    return this.getBucketDataAtCheckpoint(bucket, checkpoint, start);
+  }
+
+  async getBucketDataAtLatestCheckpoint(bucket: string, start?: ProtocolOpId | InternalOpId | undefined) {
+    if (this.storage == null) {
+      throw new Error('updateSyncRules() first');
+    }
+
+    const checkpoint = await this.storage.getCheckpoint();
+    return this.getBucketDataAtCheckpoint(bucket, checkpoint, start);
+  }
+
+  async getBucketDataAtCheckpoint(
+    bucket: string,
+    checkpoint: ReplicationCheckpoint,
+    start?: ProtocolOpId | InternalOpId | undefined
+  ) {
     start ??= 0n;
     if (typeof start == 'string') {
       start = BigInt(start);
     }
-    const syncRules = this.getSyncRulesContent();
-    const checkpoint = await this.getCheckpoint(options);
-    let map = [bucketRequest(syncRules, bucket, start)];
+    const syncConfigContent = this.getSyncConfigContent();
+    let map = [bucketRequest(syncConfigContent, bucket, start)];
     let data: OplogEntry[] = [];
     while (true) {
       const batch = this.storage!.getBucketDataBatch(checkpoint, map);
 
-      const batches = await test_utils.fromAsync(batch);
-      data = data.concat(batches[0]?.chunkData.data ?? []);
-      if (batches.length == 0 || !batches[0]!.chunkData.has_more) {
+      const chunks = await test_utils.fromAsync(batch);
+      if (chunks.length == 0) {
         break;
       }
-      map = [bucketRequest(syncRules, bucket, BigInt(batches[0]!.chunkData.next_after))];
+      for (let chunk of chunks) {
+        if (isBatchEnd(chunk)) {
+          if (!chunk.hasMore) {
+            return data;
+          }
+        } else {
+          data = data.concat(chunk.chunkData.data ?? []);
+          map = [bucketRequest(syncConfigContent, bucket, BigInt(chunk.chunkData.next_after))];
+          if (!chunk.chunkData.has_more) {
+            return data;
+          }
+        }
+      }
     }
     return data;
   }
 
   async getChecksums(buckets: string[], options?: { timeout?: number }): Promise<utils.ChecksumMap> {
     let checkpoint = await this.getCheckpoint(options);
-    const syncRules = this.getSyncRulesContent();
-    const versionedBuckets = buckets.map((bucket) => bucketRequest(syncRules, bucket, 0n));
+    const syncConfigContent = this.getSyncConfigContent();
+    const versionedBuckets = buckets.map((bucket) => bucketRequest(syncConfigContent, bucket, 0n));
     const checksums = await this.storage!.getChecksums(checkpoint, versionedBuckets);
 
     const unversioned: utils.ChecksumMap = new Map();
@@ -247,25 +318,42 @@ export async function getClientCheckpoint(
   client: mongo.MongoClient,
   db: mongo.Db,
   storageFactory: BucketStorageFactory,
-  options?: { timeout?: number }
-): Promise<InternalOpId> {
+  options?: { timeout?: number; documentDbMode?: boolean; storage?: SyncRulesBucketStorage }
+): Promise<ReplicationCheckpoint> {
   const start = Date.now();
-  const lsn = await createCheckpoint(client, db, STANDALONE_CHECKPOINT_ID);
+  const documentDbMode = options?.documentDbMode ?? (await detectDocumentDb(db));
+
+  const lsn = documentDbMode
+    ? await createSentinelCheckpointLsn(client, db)
+    : await createCheckpoint(db, STANDALONE_CHECKPOINT_ID);
   // This old API needs a persisted checkpoint id.
   // Since we don't use LSNs anymore, the only way to get that is to wait.
 
   const timeout = options?.timeout ?? 50_000;
+  // DocumentDB: the streaming loop skips standalone checkpoint events while a
+  // batch barrier is pending (see ChangeStream.ts), so a single sentinel bump
+  // can be missed on an idle stream with no later event to advance the
+  // checkpoint. Periodically re-bump the sentinel so a standalone event
+  // eventually commits past `lsn`, mirroring getSnapshotLsn's retry loop.
+  const NUDGE_INTERVAL_MS = 1000;
+  let lastNudge = Date.now();
   let lastCp: ReplicationCheckpoint | null = null;
 
   while (Date.now() - start < timeout) {
-    const storage = await storageFactory.getActiveStorage();
+    const storage = (await storageFactory.getActiveSyncConfig())?.storage;
     const cp = await storage?.getCheckpoint();
     if (cp != null) {
       lastCp = cp;
       if (cp.lsn && cp.lsn >= lsn) {
-        return cp.checkpoint;
+        return cp;
       }
     }
+
+    if (documentDbMode && Date.now() - lastNudge >= NUDGE_INTERVAL_MS) {
+      await createSentinelCheckpointLsn(client, db);
+      lastNudge = Date.now();
+    }
+
     await new Promise((resolve) => setTimeout(resolve, 30));
   }