@powersync/service-core 0.0.0-dev-20260602073133 → 0.0.0-dev-20260909133214

package/test/src/routes/admin.test.ts

@@ -1,27 +1,94 @@
-import { BasicRouterRequest, Context, JwtPayload } from '@/index.js';
+import { BasicRouterRequest, Context, JwtPayload, ParsedSyncConfigSet, storage } from '@/index.js';
 import { logger } from '@powersync/lib-services-framework';
-import { describe, expect, it } from 'vitest';
-import { validate } from '../../../src/routes/endpoints/admin.js';
+import { SqlSyncRules } from '@powersync/service-sync-rules';
+import { describe, expect, it, vi } from 'vitest';
+import { diagnostics, reprocess, validate } from '../../../src/routes/endpoints/admin.js';
 import { mockServiceContext } from './mocks.js';
 
 describe('admin routes', () => {
+  const request: BasicRouterRequest = {
+    headers: {},
+    hostname: '',
+    protocol: 'http'
+  };
+
+  function makeContext(activeBucketStorage?: any): Context {
+    const service_context = mockServiceContext(null);
+    if (activeBucketStorage != null) {
+      (service_context.storageEngine as any).activeBucketStorage = activeBucketStorage;
+    }
+
+    return {
+      logger: logger,
+      service_context,
+      token_payload: new JwtPayload({
+        sub: '',
+        exp: 0,
+        iat: 0
+      })
+    };
+  }
+
+  function makeSyncConfigContent(options: {
+    id?: number;
+    syncConfigId?: string;
+    active?: boolean;
+    content?: string;
+    version_label?: string;
+  }): storage.PersistedSyncConfigContent {
+    const id = options.id ?? 1;
+    const syncConfigId = options.syncConfigId ?? String(id);
+    const active = options.active ?? true;
+    const state = active ? storage.SyncRuleState.ACTIVE : storage.SyncRuleState.PROCESSING;
+    const lastKeepaliveTs = new Date('2026-01-01T00:00:00.000Z');
+    const lastCheckpointTs = new Date('2026-01-01T00:00:00.000Z');
+    const syncConfigStatus = {
+      id: syncConfigId,
+      replicationStreamId: id,
+      state,
+      last_checkpoint_lsn: null,
+      last_fatal_error: null,
+      last_fatal_error_ts: null,
+      last_keepalive_ts: lastKeepaliveTs,
+      last_checkpoint_ts: lastCheckpointTs
+    };
+    const content = {
+      replicationStreamId: id,
+      syncConfigId,
+      replicationStreamName: `slot_${id}`,
+      sync_rules_content:
+        options.content ??
+        `
+bucket_definitions:
+  global:
+    data:
+      - SELECT id FROM test
+`,
+      compiled_plan: null,
+      storageVersion: storage.LEGACY_STORAGE_VERSION,
+      syncConfigState: syncConfigStatus.state,
+      version_label: options.version_label,
+      parsed(options?: any) {
+        const syncRules = SqlSyncRules.fromYaml(content.sync_rules_content, {
+          ...options,
+          defaultSchema: 'public'
+        });
+        return {
+          syncConfigs: [syncRules]
+        } as ParsedSyncConfigSet;
+      },
+      asUpdateOptions: vi.fn(),
+      getStorageConfig: vi.fn(),
+      async getSyncConfigStatus() {
+        return syncConfigStatus;
+      }
+    };
+    return content as unknown as storage.PersistedSyncConfigContent;
+  }
+
   describe('validate', () => {
     it('reports errors with source location', async () => {
-      const context: Context = {
-        logger: logger,
-        service_context: mockServiceContext(null),
-        token_payload: new JwtPayload({
-          sub: '',
-          exp: 0,
-          iat: 0
-        })
-      };
-
-      const request: BasicRouterRequest = {
-        headers: {},
-        hostname: '',
-        protocol: 'http'
-      };
+      const context = makeContext();
 
       const response = await validate.handler({
         context,
@@ -45,4 +112,107 @@ bucket_definitions:
       ]);
     });
   });
+
+  describe('diagnostics', () => {
+    it('returns deploying config status', async () => {
+      const active = makeSyncConfigContent({ id: 1, syncConfigId: 'active-config', version_label: 'v5' });
+      const deploying = makeSyncConfigContent({ id: 2, syncConfigId: 'deploying-config', active: false });
+      const getInstance = vi.fn(() => ({
+        async getStatus() {
+          return {
+            snapshotDone: false,
+            resumeLsn: null
+          };
+        }
+      }));
+      const activeBucketStorage = {
+        getActiveSyncConfig: vi.fn(async () => ({
+          content: active,
+          replicationStream: {},
+          storage: getInstance()
+        })),
+        getDeployingSyncConfig: vi.fn(async () => ({
+          content: deploying,
+          replicationStream: {},
+          storage: getInstance()
+        }))
+      };
+
+      const response = await diagnostics.handler({
+        context: makeContext(activeBucketStorage),
+        params: {},
+        request
+      });
+
+      expect(response.deploying_sync_rules?.connections[0].slot_name).toBe('slot_2');
+      expect(response.active_sync_rules?.connections[0].slot_name).toBe('slot_1');
+      expect(response.active_sync_rules?.version_label).toBe('v5');
+    });
+  });
+
+  describe('reprocess', () => {
+    it('reprocesses the active sync config', async () => {
+      const active = makeSyncConfigContent({ id: 7, syncConfigId: 'active-config', version_label: 'v6' });
+      const updateSyncRules = vi.fn(async () => ({
+        replicationStreamId: 8,
+        replicationStreamName: 'new_slot',
+        state: storage.SyncRuleState.PROCESSING,
+        storageVersion: storage.LEGACY_STORAGE_VERSION,
+        replicationJobId: '8',
+        current_lock: null
+      }));
+      const activeBucketStorage = {
+        getDeployingSyncConfig: vi.fn(async () => null),
+        getActiveSyncConfig: vi.fn(async () => ({
+          content: active,
+          replicationStream: {},
+          storage: {}
+        })),
+        getSyncConfigContent: vi.fn(),
+        updateSyncRules
+      };
+
+      const response = await reprocess.handler({
+        context: makeContext(activeBucketStorage),
+        params: {},
+        request
+      });
+
+      expect(activeBucketStorage.getActiveSyncConfig).toHaveBeenCalledTimes(1);
+      expect(activeBucketStorage.getSyncConfigContent).not.toHaveBeenCalled();
+      expect(updateSyncRules).toHaveBeenCalledTimes(1);
+      expect(updateSyncRules).toHaveBeenCalledWith(
+        expect.objectContaining({ version_label: 'v6', forceNewReplicationStream: true })
+      );
+      expect(response.connections[0].slot_name).toBe('new_slot');
+    });
+
+    it('rejects reprocess while a sync config is deploying', async () => {
+      const activeBucketStorage = {
+        getDeployingSyncConfig: vi.fn(async () => ({
+          content: makeSyncConfigContent({ id: 2, active: false }),
+          replicationStream: {},
+          storage: {}
+        })),
+        getActiveSyncConfig: vi.fn(),
+        updateSyncRules: vi.fn()
+      };
+
+      await expect(
+        reprocess.handler({
+          context: makeContext(activeBucketStorage),
+          params: {},
+          request
+        })
+      ).rejects.toMatchObject({
+        errorData: {
+          status: 409,
+          code: 'PSYNC_S4106',
+          description: 'Busy processing sync config - cannot reprocess'
+        }
+      });
+      expect(activeBucketStorage.getActiveSyncConfig).not.toHaveBeenCalled();
+      expect(activeBucketStorage.updateSyncRules).not.toHaveBeenCalled();
+    });
+  });
 });

package/test/src/routes/checkpointing.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it, vi } from 'vitest';
+import { CheckpointRequestPayload, checkpointRequest } from '../../../src/routes/endpoints/checkpointing.js';
+
+describe('checkpoint request route', () => {
+  const payload = (checkpointRequestId: string | number | bigint) => ({
+    client_id: 'client-a',
+    checkpoint_request_id: checkpointRequestId
+  });
+
+  it.each([
+    ['safe JSON number', 1, 1n],
+    ['max int64 string', '9223372036854775807', 9_223_372_036_854_775_807n],
+    ['bigint value', 42n, 42n]
+  ])('decodes a positive int64 checkpoint request id from a %s', (_description, checkpointRequestId, expected) => {
+    expect(CheckpointRequestPayload.decode(payload(checkpointRequestId)).checkpoint_request_id).toEqual(expected);
+  });
+
+  it.each([1, '9223372036854775807'])(
+    'accepts API payloads with positive int64 checkpoint request id %s',
+    (checkpointRequestId) => {
+      expect(checkpointRequest.validator!.validate(payload(checkpointRequestId)).valid).toBe(true);
+    }
+  );
+
+  it.each([
+    0,
+    -1,
+    '0',
+    '-1',
+    '9223372036854775808',
+    '999999999999999999999999999999999999999999999',
+    Number.MAX_SAFE_INTEGER + 1
+  ])('rejects invalid API checkpoint request id %s', (checkpointRequestId) => {
+    expect(checkpointRequest.validator!.validate(payload(checkpointRequestId)).valid).toBe(false);
+  });
+
+  it('returns the stored checkpoint request id from the checkpoint request route', async () => {
+    const writeCheckpointBatcher = {
+      enqueue: vi.fn(async () => ({ replicationHead: 'head-1', writeCheckpoint: '43' }))
+    };
+
+    await expect(
+      checkpointRequest.handler({
+        context: {
+          token_payload: { userIdString: 'user-a' },
+          service_context: { writeCheckpointBatcher }
+        },
+        params: payload(42)
+      } as any)
+    ).resolves.toEqual({ checkpoint_request_id: '43' });
+
+    expect(writeCheckpointBatcher.enqueue).toHaveBeenCalledWith('user-a/client-a', 42n);
+  });
+});

package/test/src/routes/mocks.ts

@@ -18,8 +18,12 @@ export function mockServiceContext(storage: Partial<SyncRulesBucketStorage> | nu
 
   const storageEngine: StorageEngine = {
     activeBucketStorage: {
-      async getActiveStorage() {
-        return storage;
+      async getActiveSyncConfig() {
+        return storage == null
+          ? null
+          : {
+              storage
+            };
       }
     } as Partial<BucketStorageFactory>
   } as any;

package/test/src/routes/stream.test.ts

@@ -1,4 +1,12 @@
-import { BasicRouterRequest, Context, JwtPayload, SyncRulesBucketStorage } from '@/index.js';
+import {
+  BasicRouterRequest,
+  CHECKPOINT_INVALIDATE_ALL,
+  Context,
+  JwtPayload,
+  RequestTracker,
+  streamResponse,
+  SyncRulesBucketStorage
+} from '@/index.js';
 import { logger, RouterResponse, ServiceError } from '@powersync/lib-services-framework';
 import {
   DEFAULT_HYDRATION_STATE,
@@ -9,7 +17,7 @@ import {
 import * as sqlite from 'node:sqlite';
 import { Readable, Writable } from 'stream';
 import { pipeline } from 'stream/promises';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import winston from 'winston';
 import { syncStreamed } from '../../../src/routes/endpoints/sync-stream.js';
 import { DEFAULT_PARAM_LOGGING_FORMAT_OPTIONS, limitParamsForLogging } from '../../../src/util/param-logging.js';
@@ -182,6 +190,119 @@ describe('Stream Route', () => {
       );
     });
   });
+
+  it('closes after a data fetch error while waiting for a new checkpoint', async () => {
+    // After 1,000 operations, the sync stream concurrently calls next() on the
+    // checkpoint watcher. This test then fails the next data fetch without
+    // producing another checkpoint. Before the fix, awaiting watcher.return()
+    // during cleanup queued it behind that pending next(), leaving the response
+    // open until an unrelated checkpoint was written.
+    const syncRules = SqlSyncRules.fromYaml(
+      `
+bucket_definitions:
+  global:
+    data: []
+      `,
+      { defaultSchema: 'public' }
+    ).config.hydrate(defaultHydrationOptions);
+
+    let checkpointWatcherAborted = false;
+    let dataFetches = 0;
+    const storage = {
+      watchCheckpointChanges: async function* ({ signal }) {
+        yield {
+          base: {
+            checkpoint: 1n,
+            lsn: '1',
+            getParameterSets: async () => []
+          },
+          writeCheckpoint: null,
+          update: CHECKPOINT_INVALIDATE_ALL
+        };
+
+        await new Promise<void>((_resolve, reject) => {
+          // There is intentionally no next checkpoint: cleanup must abort this
+          // pending wait rather than wait for it to complete naturally.
+          signal.addEventListener(
+            'abort',
+            () => {
+              checkpointWatcherAborted = true;
+              reject(new Error('Checkpoint watcher aborted'));
+            },
+            { once: true }
+          );
+        });
+      },
+      getChecksums: async (_checkpoint, buckets) =>
+        new Map(buckets.map(({ bucket }) => [bucket, { bucket, checksum: 1, count: 1000 }])),
+      getBucketDataBatch: async function* () {
+        if (dataFetches++ > 0) {
+          throw new Error('Simulated data fetch failure');
+        }
+
+        yield {
+          chunkData: {
+            bucket: 'global[]',
+            data: Array.from({ length: 1000 }, () => ({ op: 'PUT' })),
+            has_more: true,
+            after: '0',
+            next_after: '1000'
+          },
+          targetOp: null
+        };
+        yield { hasMore: true };
+      }
+    } as Partial<SyncRulesBucketStorage>;
+    const serviceContext = mockServiceContext(storage);
+    const controller = new AbortController();
+    const checkpointLogger = logger.child({});
+    const checkpointLogSpy = vi.spyOn(checkpointLogger, 'info');
+
+    const response = (async () => {
+      for await (const _line of streamResponse({
+        syncContext: serviceContext.syncContext,
+        bucketStorage: storage as SyncRulesBucketStorage,
+        syncRules,
+        params: { client_id: 'test-client', raw_data: true },
+        token: new JwtPayload({ sub: 'test-user', exp: Date.now() / 1000 + 10_000 }),
+        tracker: new RequestTracker(serviceContext.metricsEngine),
+        isEncodingAsBson: false,
+        signal: controller.signal,
+        logger: checkpointLogger
+      })) {
+        // Consume the response until the simulated data fetch error is propagated.
+      }
+    })();
+
+    let timeout: NodeJS.Timeout | undefined;
+    const outcome = await Promise.race([
+      response.then(
+        () => new Error('Sync stream unexpectedly completed'),
+        (error) => error
+      ),
+      new Promise((resolve) => {
+        timeout = setTimeout(() => resolve(new Error('Sync stream did not close')), 500);
+      })
+    ]);
+    clearTimeout(timeout);
+
+    // Capture this before aborting below, which would set it regardless of the stream cleanup.
+    const abortedByCleanup = checkpointWatcherAborted;
+
+    controller.abort();
+    await response.catch(() => {});
+
+    expect(outcome).toBeInstanceOf(Error);
+    expect((outcome as Error).message).toContain('Simulated data fetch failure');
+    expect(abortedByCleanup).toBe(true);
+    expect(checkpointLogSpy).toHaveBeenCalledWith('checkpoint_interrupted: 1', {
+      checkpoint: 1n,
+      user_id: 'test-user',
+      operations_synced: 1000,
+      data_synced_bytes: 0,
+      ms: expect.any(Object)
+    });
+  });
 });
 
 export async function drainWithTimeout(readable: Readable, ms = 2_000) {

package/test/src/source-table-reconciler.test.ts

@@ -0,0 +1,244 @@
+import { SourceEntityDescriptor } from '@/storage/SourceEntity.js';
+import { SourceTable, sourceTableIdEquals } from '@/storage/SourceTable.js';
+import {
+  defaultSourceTableReconciler,
+  diffSourceTableUpdates,
+  materializeSourceTableResolution,
+  sourceIdentityCompatible,
+  validateSourceTableCandidateResolution
+} from '@/storage/SourceTableReconciler.js';
+import * as bson from 'bson';
+import { describe, expect, it } from 'vitest';
+
+function descriptor(overrides: Partial<SourceEntityDescriptor> = {}): SourceEntityDescriptor {
+  return {
+    connectionTag: 'default',
+    schema: 'public',
+    name: 'users',
+    objectId: 100,
+    replicaIdColumns: [{ name: 'id', type: 'int', typeId: 23 }],
+    ...overrides
+  };
+}
+
+function candidate(overrides: Partial<ConstructorParameters<typeof SourceTable>[0]> = {}): SourceTable {
+  return new SourceTable({
+    id: overrides.id ?? 'table-1',
+    ref: overrides.ref ?? { connectionTag: 'default', schema: 'public', name: 'users' },
+    objectId: 'objectId' in overrides ? overrides.objectId! : 100,
+    replicaIdColumns: overrides.replicaIdColumns ?? [{ name: 'id', type: 'int', typeId: 23 }],
+    snapshotComplete: overrides.snapshotComplete ?? true,
+    bucketDataSources: overrides.bucketDataSources ?? [],
+    parameterLookupSources: overrides.parameterLookupSources ?? [],
+    sourceMetadata: overrides.sourceMetadata
+  });
+}
+
+describe('sourceIdentityCompatible', () => {
+  it('matches identical identity', () => {
+    expect(sourceIdentityCompatible(descriptor(), candidate())).toBe(true);
+  });
+
+  it('rejects a different object id', () => {
+    expect(sourceIdentityCompatible(descriptor({ objectId: 200 }), candidate({ objectId: 100 }))).toBe(false);
+  });
+
+  it('rejects a different schema/name', () => {
+    expect(sourceIdentityCompatible(descriptor({ name: 'accounts' }), candidate())).toBe(false);
+  });
+
+  it('rejects changed replica-id columns', () => {
+    expect(
+      sourceIdentityCompatible(
+        descriptor(),
+        candidate({ replicaIdColumns: [{ name: 'id', type: 'bigint', typeId: 20 }] })
+      )
+    ).toBe(false);
+  });
+
+  it('treats an undefined descriptor object id as a wildcard on object id', () => {
+    expect(sourceIdentityCompatible(descriptor({ objectId: undefined }), candidate({ objectId: 999 }))).toBe(true);
+  });
+});
+
+describe('defaultSourceTableReconciler', () => {
+  it('returns all identity-compatible candidates and no metadata', async () => {
+    const a = candidate({ id: 'a' });
+    const b = candidate({ id: 'b', ref: { connectionTag: 'default', schema: 'public', name: 'accounts' } });
+    const resolution = await defaultSourceTableReconciler({ source: descriptor(), candidates: [a, b] });
+    expect(resolution.compatibleTables).toEqual([a]);
+    expect(resolution.incompatibleTables).toEqual([b]);
+    expect(resolution.newTableValues).toEqual({ sourceMetadata: null });
+  });
+
+  it('returns an empty set when nothing matches', async () => {
+    const resolution = await defaultSourceTableReconciler({
+      source: descriptor({ objectId: 200 }),
+      candidates: [candidate({ objectId: 100 })]
+    });
+    expect(resolution.compatibleTables).toHaveLength(0);
+    expect(resolution.incompatibleTables.map((table) => table.id)).toEqual(['table-1']);
+  });
+});
+
+describe('validateSourceTableCandidateResolution', () => {
+  it('accepts an explicit compatible/incompatible partition', () => {
+    const a = candidate({ id: 'a' });
+    const b = candidate({ id: 'b' });
+    expect(() =>
+      validateSourceTableCandidateResolution([a, b], {
+        compatibleTables: [a],
+        incompatibleTables: [b],
+        newTableValues: { sourceMetadata: null }
+      })
+    ).not.toThrow();
+  });
+
+  it('rejects omitted, duplicate, and unknown candidates', () => {
+    const a = candidate({ id: 'a' });
+    expect(() =>
+      validateSourceTableCandidateResolution([a], {
+        compatibleTables: [],
+        incompatibleTables: [],
+        newTableValues: { sourceMetadata: null }
+      })
+    ).toThrow(/exactly once/);
+    expect(() =>
+      validateSourceTableCandidateResolution([a], {
+        compatibleTables: [a],
+        incompatibleTables: [a],
+        newTableValues: { sourceMetadata: null }
+      })
+    ).toThrow(/exactly once/);
+    expect(() =>
+      validateSourceTableCandidateResolution([a], {
+        compatibleTables: [a],
+        incompatibleTables: [candidate({ id: 'unknown' })],
+        newTableValues: { sourceMetadata: null }
+      })
+    ).toThrow(/unknown candidate/);
+  });
+});
+
+describe('diffSourceTableUpdates', () => {
+  function resolution(compatibleTables: SourceTable[]) {
+    return { compatibleTables, incompatibleTables: [], newTableValues: { sourceMetadata: null } };
+  }
+
+  it('returns nothing when the reconciler returned the candidates untouched', () => {
+    const a = candidate({ id: 'a', sourceMetadata: { captureTableObjectId: 7 } });
+    expect(diffSourceTableUpdates([a], resolution([a]))).toEqual([]);
+  });
+
+  it('compares by value, not by reference', () => {
+    // A new object with equal metadata should not cause a write.
+    const a = candidate({ id: 'a', sourceMetadata: { captureTableObjectId: 7 } });
+    const rebuilt = a.withSourceMetadata({ captureTableObjectId: 7 });
+
+    expect(rebuilt.sourceMetadata).not.toBe(a.sourceMetadata);
+    expect(diffSourceTableUpdates([a], resolution([rebuilt]))).toEqual([]);
+  });
+
+  it('returns changed metadata', () => {
+    const a = candidate({ id: 'a', sourceMetadata: { captureTableObjectId: 7 } });
+    expect(diffSourceTableUpdates([a], resolution([a.withSourceMetadata({ captureTableObjectId: 8 })]))).toEqual([
+      { id: 'a', sourceMetadata: { captureTableObjectId: 8 } }
+    ]);
+  });
+
+  it('returns metadata added to a legacy record', () => {
+    const legacy = candidate({ id: 'a' });
+    expect(legacy.sourceMetadata).toBeNull();
+    expect(
+      diffSourceTableUpdates([legacy], resolution([legacy.withSourceMetadata({ captureTableObjectId: 7 })]))
+    ).toEqual([{ id: 'a', sourceMetadata: { captureTableObjectId: 7 } }]);
+  });
+
+  it('returns cleared metadata as null', () => {
+    const a = candidate({ id: 'a', sourceMetadata: { captureTableObjectId: 7 } });
+    expect(diffSourceTableUpdates([a], resolution([a.withSourceMetadata(null)]))).toEqual([
+      { id: 'a', sourceMetadata: null }
+    ]);
+  });
+
+  it('materializes only source metadata from reconciler results', () => {
+    const persisted = candidate({ id: 'a', snapshotComplete: false });
+    const modified = persisted.withSourceMetadata({ captureTableObjectId: 8 });
+    modified.snapshotComplete = true;
+    modified.syncData = false;
+
+    const [materialized] = materializeSourceTableResolution([persisted], resolution([modified])).compatibleTables;
+
+    expect(materialized.sourceMetadata).toEqual({ captureTableObjectId: 8 });
+    expect(materialized.snapshotComplete).toBe(false);
+    expect(materialized.syncData).toBe(persisted.syncData);
+  });
+
+  it('does not trust incompatible candidate mutations made through a cast', () => {
+    const persisted = candidate({ id: 'a', snapshotComplete: false });
+    const exposed = persisted.clone();
+    // Simulate callback code bypassing the read-only type boundary.
+    (exposed as any).snapshotComplete = true;
+
+    const materialized = materializeSourceTableResolution([persisted], {
+      compatibleTables: [],
+      incompatibleTables: [exposed],
+      newTableValues: { sourceMetadata: null }
+    }).incompatibleTables[0];
+
+    expect(exposed.snapshotComplete).toBe(true);
+    expect(materialized).toBe(persisted);
+    expect(materialized.snapshotComplete).toBe(false);
+    expect(materialized.syncData).toBe(persisted.syncData);
+  });
+
+  it('only reports the candidates that changed', () => {
+    const a = candidate({ id: 'a', sourceMetadata: { captureTableObjectId: 7 } });
+    const b = candidate({ id: 'b', sourceMetadata: { captureTableObjectId: 7 } });
+    const updates = diffSourceTableUpdates([a, b], resolution([a, b.withSourceMetadata({ captureTableObjectId: 9 })]));
+    expect(updates).toEqual([{ id: 'b', sourceMetadata: { captureTableObjectId: 9 } }]);
+  });
+
+  it('rejects a compatible table that was never a candidate', () => {
+    expect(() => diffSourceTableUpdates([candidate({ id: 'a' })], resolution([candidate({ id: 'ghost' })]))).toThrow(
+      /unknown candidate/
+    );
+  });
+});
+
+describe('SourceTable.clone', () => {
+  it('isolates mutable identity and metadata values', () => {
+    const persisted = candidate({ id: 'a', sourceMetadata: { captureTableObjectId: 7 } });
+    const exposed = persisted.clone();
+
+    (exposed.ref as any).name = 'changed';
+    exposed.replicaIdColumns[0].name = 'changed';
+    (exposed.sourceMetadata as any).captureTableObjectId = 8;
+
+    expect(persisted.name).toBe('users');
+    expect(persisted.replicaIdColumns[0].name).toBe('id');
+    expect(persisted.sourceMetadata).toEqual({ captureTableObjectId: 7 });
+  });
+});
+
+describe('sourceTableIdEquals', () => {
+  it('compares string ids by value', () => {
+    expect(sourceTableIdEquals('table-1', 'table-1')).toBe(true);
+    expect(sourceTableIdEquals('table-1', 'table-2')).toBe(false);
+  });
+
+  it('compares BSON ObjectIds by value', () => {
+    const id = new bson.ObjectId();
+    const copy = new bson.ObjectId(id.toHexString());
+
+    expect(id).not.toBe(copy);
+    expect(sourceTableIdEquals(id, copy)).toBe(true);
+  });
+
+  it('does not mix string and BSON ObjectId representations', () => {
+    const id = new bson.ObjectId();
+
+    expect(sourceTableIdEquals(id.toHexString(), id)).toBe(false);
+    expect(sourceTableIdEquals(id, id.toHexString())).toBe(false);
+  });
+});