@powersync/service-module-mongodb-storage 0.20.0 → 0.21.0

package/test/src/parameter_compacting_v1.test.ts

@@ -0,0 +1,120 @@
+import { storage, updateSyncRulesFromYaml } from '@powersync/service-core';
+import { test_utils } from '@powersync/service-core-tests';
+import * as bson from 'bson';
+import { describe, expect, test } from 'vitest';
+import type { SyncRuleDocumentV1 } from '../../src/storage/implementation/v1/models.js';
+import { MongoParameterCompactorV1 } from '../../src/storage/implementation/v1/MongoParameterCompactorV1.js';
+import { MongoSyncBucketStorageV1 } from '../../src/storage/implementation/v1/MongoSyncBucketStorageV1.js';
+import type { VersionedPowerSyncMongoV1 } from '../../src/storage/implementation/v1/VersionedPowerSyncMongoV1.js';
+import { INITIALIZED_MONGO_STORAGE_FACTORY } from './util.js';
+
+const PARAMETER_RULES = `
+bucket_definitions:
+  test:
+    parameters: select id from test where id = request.user_id()
+    data: []
+`;
+
+async function createActiveStorage() {
+  const factory = await INITIALIZED_MONGO_STORAGE_FACTORY.factory();
+  const syncRules = await factory.updateSyncRules(
+    updateSyncRulesFromYaml(PARAMETER_RULES, { storageVersion: storage.STORAGE_VERSION_2 })
+  );
+  const processingStorage = factory.getInstance(syncRules);
+  await using writer = await processingStorage.createWriter(test_utils.BATCH_OPTIONS);
+  await writer.markAllSnapshotDone('1/1');
+  await writer.commit('1/1');
+
+  const active = await factory.getActiveSyncConfig();
+  if (active == null) {
+    throw new Error('Expected an active sync config');
+  }
+  return { factory, storage: active.storage as MongoSyncBucketStorageV1, streamId: syncRules.replicationStreamId };
+}
+
+function parameterDocument(
+  id: bigint,
+  groupId: number,
+  key: { t: bson.ObjectId; k: string },
+  lookup: bson.Binary,
+  bucket_parameters: Record<string, string>[]
+): Record<string, unknown> {
+  return { _id: id, key: { ...key, g: groupId }, lookup, bucket_parameters };
+}
+
+describe('Mongo parameter compaction V1', () => {
+  test('compacts incrementally with an _id-only scan and persists the cursor', async () => {
+    const { factory, storage: bucketStorage, streamId } = await createActiveStorage();
+    await using _factory = factory;
+
+    const db = bucketStorage.db as VersionedPowerSyncMongoV1;
+    const collection = db.parameterIndexV1 as any;
+    const key = { t: new bson.ObjectId(), k: 'row' };
+    const lookup = new bson.Binary(Buffer.from('lookup'));
+
+    await collection.insertMany([
+      parameterDocument(90n, streamId + 1, key, lookup, [{ id: 'other-stream' }]),
+      parameterDocument(100n, streamId, key, lookup, [{ id: 'old' }]),
+      parameterDocument(110n, streamId, key, lookup, [{ id: 'new' }]),
+      parameterDocument(120n, streamId, { ...key, k: 'deleted' }, lookup, [{ id: 'delete-me' }]),
+      parameterDocument(130n, streamId, { ...key, k: 'deleted' }, lookup, []),
+      parameterDocument(200n, streamId, key, lookup, [{ id: 'at-target' }])
+    ]);
+
+    await bucketStorage.compact({
+      compactBuckets: [],
+      compactParameterData: true,
+      incrementalOnly: true,
+      maxOpId: 200n
+    });
+
+    const firstPass = await collection.find({}, { sort: { _id: 1 } }).toArray();
+    expect(firstPass.map((document: any) => BigInt(document._id))).toEqual([90n, 110n, 200n]);
+    const firstStreamDoc = (await db.sync_rules.findOne({ _id: streamId })) as SyncRuleDocumentV1;
+    expect(BigInt(firstStreamDoc.parameter_compaction!.compacted_before)).toBe(200n);
+
+    await collection.insertMany([
+      parameterDocument(210n, streamId, key, lookup, [{ id: 'later' }]),
+      parameterDocument(220n, streamId, { ...key, k: 'row' }, lookup, [])
+    ]);
+    const incremental = new MongoParameterCompactorV1(db, streamId, 300n, {});
+    await incremental.compact();
+
+    const secondPass = await collection.find({}, { sort: { _id: 1 } }).toArray();
+    expect(secondPass.map((document: any) => BigInt(document._id))).toEqual([90n]);
+    const secondStreamDoc = (await db.sync_rules.findOne({ _id: streamId })) as SyncRuleDocumentV1;
+    expect(BigInt(secondStreamDoc.parameter_compaction!.compacted_before)).toBe(300n);
+  });
+
+  test('seeds the compaction cursor when a V1 stream is created', async () => {
+    await using factory = await INITIALIZED_MONGO_STORAGE_FACTORY.factory();
+    // Stand in for parameter history written by earlier deployments: all V1 streams share the
+    // `main` op id sequence and the `bucket_parameters` collection.
+    await factory.db.op_id_sequence.updateOne({ _id: 'main' }, { $set: { op_id: 500n } }, { upsert: true });
+
+    const syncRules = await factory.updateSyncRules(
+      updateSyncRulesFromYaml(PARAMETER_RULES, { storageVersion: storage.STORAGE_VERSION_2 })
+    );
+
+    // Entries for this stream can only be written above the sequence head, so its first compaction
+    // does not have to scan the older entries of other streams.
+    const streamDoc = (await factory.db.sync_rules.findOne({
+      _id: syncRules.replicationStreamId
+    })) as SyncRuleDocumentV1;
+    expect(BigInt(streamDoc.parameter_compaction!.compacted_before)).toBe(500n);
+  });
+
+  test('clearing a V1 stream clears the parameter compaction cursor', async () => {
+    const { factory, storage: bucketStorage, streamId } = await createActiveStorage();
+    await using _factory = factory;
+
+    const db = bucketStorage.db as VersionedPowerSyncMongoV1;
+    await db.sync_rules.updateOne({ _id: streamId }, {
+      $set: { 'parameter_compaction.compacted_before': 123n }
+    } as any);
+    await bucketStorage.clear();
+
+    const streamDoc = (await db.sync_rules.findOne({ _id: streamId })) as SyncRuleDocumentV1;
+    expect(streamDoc.parameter_compaction).toBeUndefined();
+  });
+});

package/test/src/parameter_compacting_v3.test.ts

@@ -0,0 +1,192 @@
+import { storage, updateSyncRulesFromYaml } from '@powersync/service-core';
+import { test_utils } from '@powersync/service-core-tests';
+import * as bson from 'bson';
+import { describe, expect, test } from 'vitest';
+import { MongoParameterCompactorV3 } from '../../src/storage/implementation/v3/MongoParameterCompactorV3.js';
+import { MongoSyncBucketStorageV3 } from '../../src/storage/implementation/v3/MongoSyncBucketStorageV3.js';
+import type { VersionedPowerSyncMongoV3 } from '../../src/storage/implementation/v3/VersionedPowerSyncMongoV3.js';
+import type { ReplicationStreamDocumentV3 } from '../../src/storage/implementation/v3/models.js';
+import { INITIALIZED_MONGO_STORAGE_FACTORY } from './util.js';
+
+const PARAMETER_RULES = `
+bucket_definitions:
+  test:
+    parameters: select id from test where id = request.user_id()
+    data: []
+`;
+
+/** Two parameter indexes over the same lookup values, so both store identical (key, lookup) pairs. */
+const TWO_INDEX_PARAMETER_RULES = `
+bucket_definitions:
+  test1:
+    parameters: select id from test where id = request.user_id()
+    data: []
+  test2:
+    parameters: select id from test where id = request.user_id()
+    data: []
+`;
+
+async function createActiveStorage(rules = PARAMETER_RULES) {
+  const factory = await INITIALIZED_MONGO_STORAGE_FACTORY.factory();
+  const syncRules = await factory.updateSyncRules(
+    updateSyncRulesFromYaml(rules, { storageVersion: storage.STORAGE_VERSION_3 })
+  );
+  const processingStorage = factory.getInstance(syncRules);
+  await using writer = await processingStorage.createWriter(test_utils.BATCH_OPTIONS);
+  await writer.markAllSnapshotDone('1/1');
+  await writer.commit('1/1');
+
+  const active = await factory.getActiveSyncConfig();
+  if (active == null) {
+    throw new Error('Expected an active sync config');
+  }
+
+  return { factory, storage: active.storage as MongoSyncBucketStorageV3, streamId: syncRules.replicationStreamId };
+}
+
+function parameterDocument(
+  id: bigint,
+  key: { t: bson.ObjectId; k: string },
+  lookup: bson.Binary,
+  bucket_parameters: Record<string, string>[]
+): Record<string, unknown> {
+  return { _id: id, key, lookup, bucket_parameters };
+}
+
+describe('Mongo parameter compaction V3', () => {
+  test('compacts incrementally, honors the target boundary, and persists the cursor', async () => {
+    const { factory, storage: bucketStorage, streamId } = await createActiveStorage();
+    await using _factory = factory;
+
+    const db = bucketStorage.db as VersionedPowerSyncMongoV3;
+    const parameterCollections = await db.listParameterIndexCollections(streamId);
+    expect(parameterCollections).toHaveLength(1);
+    const collection = parameterCollections[0].collection as any;
+    const key = { t: new bson.ObjectId(), k: 'row' };
+    const lookup = new bson.Binary(Buffer.from('lookup'));
+
+    await collection.insertMany([
+      parameterDocument(100n, key, lookup, [{ id: 'old' }]),
+      parameterDocument(110n, key, lookup, [{ id: 'new' }]),
+      parameterDocument(120n, { ...key, k: 'deleted' }, lookup, [{ id: 'delete-me' }]),
+      parameterDocument(130n, { ...key, k: 'deleted' }, lookup, []),
+      parameterDocument(200n, key, lookup, [{ id: 'at-target' }])
+    ]);
+
+    await bucketStorage.compact({
+      compactBuckets: [],
+      compactParameterData: true,
+      maxOpId: 200n
+    });
+
+    const firstPass = await collection.find({}, { sort: { _id: 1 } }).toArray();
+    expect(firstPass.map((document: any) => BigInt(document._id))).toEqual([110n, 200n]);
+    const firstStreamDoc = (await db.sync_rules.findOne({ _id: streamId })) as ReplicationStreamDocumentV3;
+    expect(BigInt(firstStreamDoc.parameter_compaction!.compacted_before)).toBe(200n);
+
+    // A repeated pass at the same target has no eligible range to scan.
+    await bucketStorage.compact({
+      compactBuckets: [],
+      compactParameterData: true,
+      maxOpId: 200n
+    });
+    await expect(collection.countDocuments({})).resolves.toBe(2);
+
+    await collection.insertMany([
+      parameterDocument(210n, key, lookup, [{ id: 'later' }]),
+      parameterDocument(220n, { ...key, k: 'row' }, lookup, [])
+    ]);
+
+    // Use a small batch to exercise identities that span multiple reads. The exact-target entry
+    // becomes eligible only after the target advances.
+    const incremental = new MongoParameterCompactorV3(db, streamId, 300n, {}, 2);
+    await incremental.compact();
+
+    const secondPass = await collection.find({}, { sort: { _id: 1 } }).toArray();
+    expect(secondPass.map((document: any) => BigInt(document._id))).toEqual([]);
+    const secondStreamDoc = (await db.sync_rules.findOne({ _id: streamId })) as ReplicationStreamDocumentV3;
+    expect(BigInt(secondStreamDoc.parameter_compaction!.compacted_before)).toBe(300n);
+  });
+
+  test('keeps identities scoped per parameter index while compacting them in lock-step', async () => {
+    const { factory, storage: bucketStorage, streamId } = await createActiveStorage(TWO_INDEX_PARAMETER_RULES);
+    await using _factory = factory;
+
+    const db = bucketStorage.db as VersionedPowerSyncMongoV3;
+    const parameterCollections = await db.listParameterIndexCollections(streamId);
+    expect(parameterCollections).toHaveLength(2);
+    const [first, second] = parameterCollections.map(({ collection }) => collection as any);
+
+    // The same source row and lookup values in both indexes. V3 keeps the index id in the
+    // collection name rather than in the lookup, so these documents are byte-identical apart from
+    // their op ids - the compactor must not carry what it deleted in one index over to the other.
+    const key = { t: new bson.ObjectId(), k: 'row' };
+    const lookup = new bson.Binary(Buffer.from('lookup'));
+    await first.insertMany([
+      parameterDocument(10n, key, lookup, [{ id: 'first' }]),
+      parameterDocument(40n, key, lookup, [])
+    ]);
+    await second.insertMany([
+      parameterDocument(20n, key, lookup, [{ id: 'second' }]),
+      parameterDocument(30n, key, lookup, [])
+    ]);
+
+    // One document per batch, so the two indexes are processed in interleaved turns.
+    await new MongoParameterCompactorV3(db, streamId, 100n, {}, 1).compact();
+
+    // Each tombstone removed its own index's history, and only that.
+    await expect(first.countDocuments({})).resolves.toBe(0);
+    await expect(second.countDocuments({})).resolves.toBe(0);
+  });
+
+  test('persists progress during a pass', async () => {
+    const { factory, storage: bucketStorage, streamId } = await createActiveStorage(TWO_INDEX_PARAMETER_RULES);
+    await using _factory = factory;
+
+    const db = bucketStorage.db as VersionedPowerSyncMongoV3;
+    const parameterCollections = await db.listParameterIndexCollections(streamId);
+    const [first, second] = parameterCollections.map(({ collection }) => collection as any);
+    const lookup = new bson.Binary(Buffer.from('lookup'));
+    const key = (k: string) => ({ t: new bson.ObjectId(), k });
+    await first.insertMany([
+      parameterDocument(10n, key('a'), lookup, [{ id: 'a' }]),
+      parameterDocument(30n, key('b'), lookup, [{ id: 'b' }])
+    ]);
+    await second.insertMany([
+      parameterDocument(20n, key('c'), lookup, [{ id: 'c' }]),
+      parameterDocument(40n, key('d'), lookup, [{ id: 'd' }])
+    ]);
+
+    const persisted: bigint[] = [];
+    class RecordingCompactor extends MongoParameterCompactorV3 {
+      protected override async persistCompactedBefore(compactedBefore: bigint): Promise<void> {
+        persisted.push(compactedBefore);
+        return super.persistCompactedBefore(compactedBefore);
+      }
+    }
+
+    // One document per batch, and no throttling of progress writes.
+    await new RecordingCompactor(db, streamId, 100n, {}, 1, 0).compact();
+
+    // The cursor only ever covers what both indexes have passed, and it moves before the pass
+    // completes, so an interruption does not lose all progress.
+    expect(persisted).toEqual([...persisted].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)));
+    expect(persisted.some((value) => value > 0n && value < 100n)).toBe(true);
+    expect(persisted.at(-1)).toBe(100n);
+  });
+
+  test('clearing a V3 stream clears the parameter compaction cursor', async () => {
+    const { factory, storage: bucketStorage, streamId } = await createActiveStorage();
+    await using _factory = factory;
+
+    const db = bucketStorage.db as VersionedPowerSyncMongoV3;
+    await db.sync_rules.updateOne({ _id: streamId }, {
+      $set: { 'parameter_compaction.compacted_before': 123n }
+    } as any);
+
+    await bucketStorage.clear();
+
+    const streamDoc = (await db.sync_rules.findOne({ _id: streamId })) as ReplicationStreamDocumentV3;
+    expect(streamDoc.parameter_compaction).toBeUndefined();
+  });
+});

package/test/src/parameter_compaction_fence.test.ts

@@ -0,0 +1,276 @@
+import { mongo } from '@powersync/lib-service-mongodb';
+import { InternalOpId, storage, updateSyncRulesFromYaml } from '@powersync/service-core';
+import { test_utils } from '@powersync/service-core-tests';
+import { describe, expect, test } from 'vitest';
+import type { VersionedPowerSyncMongo } from '../../src/storage/implementation/db.js';
+import type { SyncRuleDocumentBase } from '../../src/storage/implementation/models.js';
+import { MongoParameterCompactor } from '../../src/storage/implementation/MongoParameterCompactor.js';
+import { MongoSyncBucketStorage } from '../../src/storage/implementation/MongoSyncBucketStorage.js';
+import { MongoParameterCompactorV1 } from '../../src/storage/implementation/v1/MongoParameterCompactorV1.js';
+import { MongoParameterCompactorV3 } from '../../src/storage/implementation/v3/MongoParameterCompactorV3.js';
+import { MongoBucketStorage } from '../../src/storage/MongoBucketStorage.js';
+import { INITIALIZED_MONGO_STORAGE_FACTORY, TEST_STORAGE_VERSIONS } from './util.js';
+
+const PARAMETER_RULES = `
+bucket_definitions:
+  test:
+    parameters: select id from test where id = request.user_id()
+    data: []
+`;
+
+/**
+ * Wraps a collection so that any delete fails. Used to check that an interrupted compaction pass
+ * leaves the invalidation fence advanced, but not the compaction cursor.
+ */
+function withFailingDeletes<T extends object>(collection: T): T {
+  return new Proxy(collection, {
+    get(target, property) {
+      if (property == 'deleteMany' || property == 'bulkWrite') {
+        return () => Promise.reject(new Error('simulated delete failure'));
+      }
+      const value = Reflect.get(target, property, target);
+      // Bind to the target: the driver's collection uses private fields internally.
+      return typeof value == 'function' ? value.bind(target) : value;
+    }
+  }) as T;
+}
+
+class FailingParameterCompactorV1 extends MongoParameterCompactorV1 {
+  protected override async getCollections(): Promise<mongo.Collection<mongo.Document>[]> {
+    return (await super.getCollections()).map(withFailingDeletes);
+  }
+}
+
+class FailingParameterCompactorV3 extends MongoParameterCompactorV3 {
+  protected override async getCollections(): Promise<mongo.Collection<mongo.Document>[]> {
+    return (await super.getCollections()).map(withFailingDeletes);
+  }
+}
+
+describe('parameter compaction invalidation fence', () => {
+  for (const storageVersion of TEST_STORAGE_VERSIONS) {
+    describe(`storage v${storageVersion}`, () => {
+      function createCompactor(
+        db: VersionedPowerSyncMongo,
+        streamId: number,
+        checkpoint: InternalOpId,
+        options: storage.CompactOptions & { failDeletes?: boolean } = {}
+      ): MongoParameterCompactor {
+        const { failDeletes, ...compactOptions } = options;
+        if (storageVersion >= 3) {
+          const Compactor = failDeletes ? FailingParameterCompactorV3 : MongoParameterCompactorV3;
+          return new Compactor(db, streamId, checkpoint, compactOptions);
+        }
+        const Compactor = failDeletes ? FailingParameterCompactorV1 : MongoParameterCompactorV1;
+        return new Compactor(db, streamId, checkpoint, compactOptions);
+      }
+
+      async function readCompactionState(db: VersionedPowerSyncMongo, streamId: number) {
+        const doc = (await db.sync_rules.findOne({ _id: streamId })) as SyncRuleDocumentBase;
+        return {
+          compactedBefore: doc.parameter_compaction?.compacted_before ?? null,
+          invalidBefore: doc.parameter_compaction?.checkpoint_changes_invalid_before ?? null
+        };
+      }
+
+      /**
+       * Replicates three checkpoints:
+       *
+       * 1. `checkpoint1`: t1 and t2 inserted.
+       * 2. t2 deleted - this writes a parameter tombstone, the only remaining record of t2's lookup.
+       * 3. `checkpoint3`: t3 inserted, which puts the tombstone strictly below the checkpoint,
+       *    making it eligible for compaction.
+       */
+      async function replicateParameterHistory(factory: storage.BucketStorageFactory) {
+        const syncRules = await factory.updateSyncRules(updateSyncRulesFromYaml(PARAMETER_RULES, { storageVersion }));
+        const processingStorage = factory.getInstance(syncRules);
+        const writer = await processingStorage.createWriter(test_utils.BATCH_OPTIONS);
+        const testTable = await test_utils.resolveTestTable(writer, 'test', ['id'], INITIALIZED_MONGO_STORAGE_FACTORY);
+
+        await writer.markAllSnapshotDone('1/1');
+        for (const id of ['t1', 't2']) {
+          await writer.save({
+            sourceTable: testTable,
+            tag: storage.SaveOperationTag.INSERT,
+            after: { id },
+            afterReplicaId: test_utils.rid(id)
+          });
+        }
+        await writer.commit('1/1');
+
+        const active = await factory.getActiveSyncConfig();
+        if (active == null) {
+          throw new Error('Expected an active sync config');
+        }
+        const bucketStorage = active.storage as MongoSyncBucketStorage;
+        const checkpoint1 = await bucketStorage.getCheckpoint();
+
+        await writer.save({
+          sourceTable: testTable,
+          tag: storage.SaveOperationTag.DELETE,
+          before: { id: 't2' },
+          beforeReplicaId: test_utils.rid('t2')
+        });
+        await writer.commit('1/2');
+
+        await writer.save({
+          sourceTable: testTable,
+          tag: storage.SaveOperationTag.INSERT,
+          after: { id: 't3' },
+          afterReplicaId: test_utils.rid('t3')
+        });
+        await writer.commit('1/3');
+        await writer.dispose();
+
+        const checkpoint3 = await bucketStorage.getCheckpoint();
+        expect(checkpoint3.checkpoint).toBeGreaterThan(checkpoint1.checkpoint);
+
+        return {
+          bucketStorage,
+          replicationStream: active.replicationStream,
+          streamId: syncRules.replicationStreamId,
+          checkpoint1,
+          checkpoint3
+        };
+      }
+
+      test('invalidates parameter buckets for checkpoints below the fence', async () => {
+        await using factory = await INITIALIZED_MONGO_STORAGE_FACTORY.factory();
+        const { bucketStorage, streamId, checkpoint1, checkpoint3 } = await replicateParameterHistory(factory);
+        const db = bucketStorage.db;
+
+        // The tombstone for t2 and the new entry for t3 are both in this range.
+        const baseline = await bucketStorage.getCheckpointChanges({
+          lastCheckpoint: checkpoint1,
+          nextCheckpoint: checkpoint3
+        });
+        expect(baseline.invalidateParameterBuckets).toBe(false);
+        expect(baseline.updatedParameterLookups.size).toBe(2);
+
+        await createCompactor(db, streamId, checkpoint3.checkpoint).compact();
+
+        // The fence is advanced because the pass deleted parameter entries.
+        expect(await readCompactionState(db, streamId)).toEqual({
+          compactedBefore: checkpoint3.checkpoint,
+          invalidBefore: checkpoint3.checkpoint
+        });
+
+        // A checkpoint read after compaction captures the fence. The transition from checkpoint1
+        // can no longer be resolved to individual lookups, so all parameter buckets are
+        // invalidated. This is a different cache entry from the baseline above, even though the
+        // checkpoint and LSN are unchanged.
+        const checkpoint3After = await bucketStorage.getCheckpoint();
+        expect(checkpoint3After.checkpoint).toBe(checkpoint3.checkpoint);
+        const afterCompaction = await bucketStorage.getCheckpointChanges({
+          lastCheckpoint: checkpoint1,
+          nextCheckpoint: checkpoint3After
+        });
+        expect(afterCompaction.invalidateParameterBuckets).toBe(true);
+        expect(afterCompaction.updatedParameterLookups.size).toBe(0);
+
+        // A transition starting at the fence is not affected by it.
+        const atFence = await bucketStorage.getCheckpointChanges({
+          lastCheckpoint: checkpoint3After,
+          nextCheckpoint: checkpoint3After
+        });
+        expect(atFence.invalidateParameterBuckets).toBe(false);
+        expect(atFence.updatedParameterLookups.size).toBe(0);
+      });
+
+      test('reads changes at the checkpoint snapshot, including compacted entries', async () => {
+        await using factory = await INITIALIZED_MONGO_STORAGE_FACTORY.factory();
+        const { bucketStorage, replicationStream, streamId, checkpoint1, checkpoint3 } =
+          await replicateParameterHistory(factory);
+        const db = bucketStorage.db;
+
+        const baseline = await bucketStorage.getCheckpointChanges({
+          lastCheckpoint: checkpoint1,
+          nextCheckpoint: checkpoint3
+        });
+        expect(baseline.updatedParameterLookups.size).toBe(2);
+
+        await createCompactor(db, streamId, checkpoint3.checkpoint).compact();
+
+        // checkpoint3 was captured before compaction, so it does not have the fence and the
+        // change query runs at its snapshot. That snapshot still contains the deleted tombstone,
+        // which is the only record of t2's lookup.
+        //
+        // A separate storage instance is used to get a cold checkpoint-changes cache.
+        const coldStorage = (factory as MongoBucketStorage).getInstance(replicationStream);
+        const atSnapshot = await coldStorage.getCheckpointChanges({
+          lastCheckpoint: checkpoint1,
+          nextCheckpoint: checkpoint3
+        });
+        expect(atSnapshot.invalidateParameterBuckets).toBe(false);
+        expect(atSnapshot.updatedParameterLookups).toEqual(baseline.updatedParameterLookups);
+      });
+
+      test('advances the fence before the first delete, and the cursor only after the last', async () => {
+        await using factory = await INITIALIZED_MONGO_STORAGE_FACTORY.factory();
+        const { bucketStorage, streamId, checkpoint3 } = await replicateParameterHistory(factory);
+        const db = bucketStorage.db;
+
+        // V1 seeds the cursor when the stream is created, V3 leaves it unset.
+        const initialState = await readCompactionState(db, streamId);
+        expect(initialState.invalidBefore).toBeNull();
+
+        await expect(
+          createCompactor(db, streamId, checkpoint3.checkpoint, { failDeletes: true }).compact()
+        ).rejects.toThrow('simulated delete failure');
+
+        // The fence was committed before the first delete was attempted, but the interrupted pass
+        // may not skip any deletion work on a retry, so the cursor stays where it was.
+        expect(await readCompactionState(db, streamId)).toEqual({
+          compactedBefore: initialState.compactedBefore,
+          invalidBefore: checkpoint3.checkpoint
+        });
+
+        // Retrying completes the pass.
+        await createCompactor(db, streamId, checkpoint3.checkpoint).compact();
+        expect(await readCompactionState(db, streamId)).toEqual({
+          compactedBefore: checkpoint3.checkpoint,
+          invalidBefore: checkpoint3.checkpoint
+        });
+      });
+
+      test('an aborted pass does not advance the cursor', async () => {
+        await using factory = await INITIALIZED_MONGO_STORAGE_FACTORY.factory();
+        const { bucketStorage, streamId, checkpoint3 } = await replicateParameterHistory(factory);
+        const db = bucketStorage.db;
+
+        const initialState = await readCompactionState(db, streamId);
+        const controller = new AbortController();
+        controller.abort();
+        await expect(
+          createCompactor(db, streamId, checkpoint3.checkpoint, { signal: controller.signal }).compact()
+        ).rejects.toThrow();
+
+        expect(await readCompactionState(db, streamId)).toEqual(initialState);
+        expect(initialState.invalidBefore).toBeNull();
+      });
+
+      test('does not advance the fence for a pass without deletes', async () => {
+        await using factory = await INITIALIZED_MONGO_STORAGE_FACTORY.factory();
+        const { bucketStorage, streamId, checkpoint3 } = await replicateParameterHistory(factory);
+        const db = bucketStorage.db;
+
+        // Compact past every persisted entry, so that the next pass has an empty range.
+        const firstTarget = checkpoint3.checkpoint + 1000n;
+        await createCompactor(db, streamId, firstTarget).compact();
+        expect(await readCompactionState(db, streamId)).toEqual({
+          compactedBefore: firstTarget,
+          invalidBefore: firstTarget
+        });
+
+        const secondTarget = firstTarget + 1000n;
+        await createCompactor(db, streamId, secondTarget).compact();
+        // The cursor advances, but nothing was deleted, so checkpoint change detection stays
+        // available for everything above the previous fence.
+        expect(await readCompactionState(db, streamId)).toEqual({
+          compactedBefore: secondTarget,
+          invalidBefore: firstTarget
+        });
+      });
+    });
+  }
+});