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

package/test/src/object_storage_usage.test.ts

@@ -0,0 +1,267 @@
+import { MongoSyncBucketStorage } from '@module/storage/implementation/createMongoSyncBucketStorage.js';
+import { BucketDataDocumentV3, ObjectStorageUsageDocument } from '@module/storage/implementation/v3/models.js';
+import {
+  OBJECT_STORAGE_USAGE_BASE_WRITER_ID,
+  ObjectStorageUsage
+} from '@module/storage/implementation/v3/object-storage/ObjectStorageUsage.js';
+import { VersionedPowerSyncMongoV3 } from '@module/storage/implementation/v3/VersionedPowerSyncMongoV3.js';
+import * as lib_mongo from '@powersync/lib-service-mongodb';
+import { mongo } from '@powersync/lib-service-mongodb';
+import { updateSyncRulesFromYaml } from '@powersync/service-core';
+import { BucketDefinitionId } from '@powersync/service-sync-rules';
+import { describe, expect, test } from 'vitest';
+import { INITIALIZED_MONGO_STORAGE_FACTORY } from './util.js';
+
+const SYNC_RULES_YAML = `
+bucket_definitions:
+  global:
+    data:
+      - SELECT id FROM items
+`;
+
+type UsageContext = {
+  db: VersionedPowerSyncMongoV3;
+  bucketStorage: MongoSyncBucketStorage;
+  definitionId: BucketDefinitionId;
+};
+
+type UsageEntry = {
+  definition_id: BucketDefinitionId;
+  active_bytes: bigint;
+};
+
+async function withUsageContext<T>(callback: (context: UsageContext) => Promise<T>): Promise<T> {
+  await using factory = await INITIALIZED_MONGO_STORAGE_FACTORY.factory();
+  const syncRules = await factory.updateSyncRules(updateSyncRulesFromYaml(SYNC_RULES_YAML, { storageVersion: 3 }));
+  const bucketStorage = factory.getInstance(syncRules) as MongoSyncBucketStorage;
+  const db = bucketStorage.db as VersionedPowerSyncMongoV3;
+  const definitionId = syncRules.syncConfigContent[0].mapping.allBucketDefinitionIds()[0];
+  return callback({ db, bucketStorage, definitionId });
+}
+
+async function withTransaction<T>(
+  db: VersionedPowerSyncMongoV3,
+  callback: (session: mongo.ClientSession) => Promise<T>
+): Promise<T> {
+  const session = db.client.startSession();
+  try {
+    return await session.withTransaction(() => callback(session));
+  } finally {
+    await session.endSession();
+  }
+}
+
+async function readUsageEntries(
+  db: VersionedPowerSyncMongoV3,
+  replicationStreamId: number,
+  session?: mongo.ClientSession
+): Promise<UsageEntry[]> {
+  const entries = await db.objectStorageUsage
+    .aggregate<{ _id: BucketDefinitionId; active_bytes: bigint }>(
+      [
+        { $match: { '_id.g': replicationStreamId } },
+        { $project: { definitions: { $objectToArray: '$definitions' } } },
+        { $unwind: '$definitions' },
+        { $group: { _id: '$definitions.k', active_bytes: { $sum: '$definitions.v' } } }
+      ],
+      { session, readConcern: 'snapshot' }
+    )
+    .toArray()
+    .catch((error) => {
+      if (lib_mongo.isMongoNamespaceNotFoundError(error)) {
+        return [];
+      }
+      throw error;
+    });
+
+  return entries.map((entry) => ({
+    definition_id: entry._id,
+    active_bytes: BigInt(entry.active_bytes ?? 0)
+  }));
+}
+
+function usageDocument(
+  replicationStreamId: number,
+  writerId: string,
+  definitions: Record<string, bigint>,
+  updatedAt = new Date(0)
+): ObjectStorageUsageDocument {
+  return {
+    _id: { g: replicationStreamId, w: writerId },
+    updated_at: updatedAt,
+    definitions
+  };
+}
+
+function bucketDataDocument(
+  replicationStreamId: number,
+  definitionId: BucketDefinitionId,
+  fileSize: number
+): BucketDataDocumentV3 {
+  return {
+    _id: { b: `${replicationStreamId}-${definitionId}`, o: 1n },
+    min_op: 1n,
+    checksum: 1n,
+    count: 1,
+    size: fileSize,
+    storage_ref: {
+      path: `bucket-data/${replicationStreamId}/${definitionId}/1.bson`,
+      file_size: fileSize
+    }
+  };
+}
+
+describe('ObjectStorageUsage', () => {
+  test('counts a committed reference exactly once after an aborted transaction is retried', async () => {
+    await withUsageContext(async ({ db, bucketStorage, definitionId }) => {
+      const replicationStreamId = bucketStorage.replicationStreamId;
+      const writerId = 'replication-writer';
+      const usage = new ObjectStorageUsage(db, replicationStreamId, writerId);
+      const bucketData = db.bucketData(replicationStreamId, definitionId);
+      const document = bucketDataDocument(replicationStreamId, definitionId, 123);
+
+      await expect(
+        withTransaction(db, async (session) => {
+          await bucketData.insertOne(document, { session });
+          const writes = db.createWriteBatch(session, { ordered: false });
+          usage.applyDelta(definitionId, 123n, writes);
+          await writes.execute();
+          throw new Error('abort this attempt');
+        })
+      ).rejects.toThrow('abort this attempt');
+
+      await withTransaction(db, async (session) => {
+        await bucketData.insertOne(document, { session });
+        const writes = db.createWriteBatch(session, { ordered: false });
+        usage.applyDelta(definitionId, 123n, writes);
+        await writes.execute();
+      });
+
+      expect(await bucketData.countDocuments({ storage_ref: { $exists: true } })).toBe(1);
+      await expect(readUsageEntries(db, replicationStreamId)).resolves.toEqual([
+        { definition_id: definitionId, active_bytes: 123n }
+      ]);
+    });
+  });
+
+  test('snapshot usage reads observe a complete pre-fold view', async () => {
+    await withUsageContext(async ({ db, bucketStorage, definitionId }) => {
+      const replicationStreamId = bucketStorage.replicationStreamId;
+      const usage = new ObjectStorageUsage(db, replicationStreamId);
+      await db.objectStorageUsage.insertMany([
+        usageDocument(replicationStreamId, OBJECT_STORAGE_USAGE_BASE_WRITER_ID, { [definitionId]: 100n }),
+        usageDocument(replicationStreamId, 'replication', { [definitionId]: 20n }),
+        usageDocument(replicationStreamId, 'compactor', { [definitionId]: -5n })
+      ]);
+
+      const readSession = db.client.startSession();
+      try {
+        readSession.startTransaction({ readConcern: { level: 'snapshot' } });
+        await db.objectStorageUsage.findOne(
+          { _id: { g: replicationStreamId, w: OBJECT_STORAGE_USAGE_BASE_WRITER_ID } },
+          { session: readSession }
+        );
+
+        await usage.foldStaleWriterDeltas({ staleWriterMs: 0 });
+        const entries = await readUsageEntries(db, replicationStreamId, readSession);
+
+        await readSession.commitTransaction();
+        expect(entries).toEqual([{ definition_id: definitionId, active_bytes: 115n }]);
+      } catch (error) {
+        await readSession.abortTransaction().catch(() => undefined);
+        throw error;
+      } finally {
+        await readSession.endSession();
+      }
+
+      await expect(readUsageEntries(db, replicationStreamId)).resolves.toEqual([
+        { definition_id: definitionId, active_bytes: 115n }
+      ]);
+    });
+  });
+
+  test('folding preserves totals across both writer/folder commit orders', async () => {
+    await withUsageContext(async ({ db, bucketStorage, definitionId }) => {
+      const replicationStreamId = bucketStorage.replicationStreamId;
+      const writerId = 'reused-writer';
+      const usage = new ObjectStorageUsage(db, replicationStreamId, writerId);
+
+      await withTransaction(db, async (session) => {
+        const writes = db.createWriteBatch(session, { ordered: false });
+        usage.applyDelta(definitionId, 10n, writes);
+        await writes.execute();
+      });
+      await db.objectStorageUsage.updateOne(
+        { _id: { g: replicationStreamId, w: writerId } },
+        { $set: { updated_at: new Date(0) } }
+      );
+      await usage.foldStaleWriterDeltas({ staleWriterMs: 0 });
+
+      // The folder committed first and deleted the writer shard. The writer's
+      // next transaction must recreate it through the upsert.
+      await withTransaction(db, async (session) => {
+        const writes = db.createWriteBatch(session, { ordered: false });
+        usage.applyDelta(definitionId, 4n, writes);
+        await writes.execute();
+      });
+      expect((await readUsageEntries(db, replicationStreamId))[0].active_bytes).toBe(14n);
+
+      await db.objectStorageUsage.updateOne(
+        { _id: { g: replicationStreamId, w: writerId } },
+        { $set: { updated_at: new Date(0) } }
+      );
+      await usage.foldStaleWriterDeltas({ staleWriterMs: 0 });
+
+      // The writer committed before the folder. Folding the recreated shard
+      // must preserve the same visible total.
+      expect((await readUsageEntries(db, replicationStreamId))[0].active_bytes).toBe(14n);
+    });
+  });
+
+  test('definition cleanup racing a fold removes only that definition, and stream clear is isolated', async () => {
+    await withUsageContext(async ({ db, bucketStorage, definitionId }) => {
+      const replicationStreamId = bucketStorage.replicationStreamId;
+      const otherStreamId = replicationStreamId + 1;
+      const otherDefinitionId = 'other_definition';
+      const usage = new ObjectStorageUsage(db, replicationStreamId);
+
+      await db.objectStorageUsage.insertMany([
+        usageDocument(replicationStreamId, OBJECT_STORAGE_USAGE_BASE_WRITER_ID, {
+          [definitionId]: 3n,
+          [otherDefinitionId]: 7n
+        }),
+        usageDocument(replicationStreamId, 'writer', { [definitionId]: 20n, [otherDefinitionId]: 11n }),
+        usageDocument(otherStreamId, 'other-writer', { [definitionId]: 50n })
+      ]);
+
+      await Promise.all([
+        usage.foldStaleWriterDeltas({ staleWriterMs: 0 }),
+        withTransaction(db, (session) => usage.removeDefinition(definitionId, session))
+      ]);
+
+      await expect(readUsageEntries(db, replicationStreamId)).resolves.toEqual([
+        { definition_id: otherDefinitionId, active_bytes: 18n }
+      ]);
+
+      await withTransaction(db, async (session) => {
+        await new ObjectStorageUsage(db, otherStreamId).removeStream(session);
+      });
+      await db.objectStorageUsage.insertOne(usageDocument(otherStreamId, 'other-writer', { [definitionId]: 50n }));
+
+      await withTransaction(db, async (session) => {
+        await usage.removeStream(session);
+      });
+
+      await expect(ObjectStorageUsage.readAllDefinitionUsage(db)).resolves.toEqual([
+        { replication_stream_id: otherStreamId, definition_id: definitionId, active_bytes: 50n }
+      ]);
+    });
+  });
+
+  test('returns no entries for an absent usage collection', async () => {
+    await withUsageContext(async ({ db, bucketStorage }) => {
+      await db.objectStorageUsage.drop().catch(() => undefined);
+      await expect(readUsageEntries(db, bucketStorage.replicationStreamId)).resolves.toEqual([]);
+    });
+  });
+});

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