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

package/src/storage/implementation/BucketDefinitionMapping.ts

@@ -0,0 +1,539 @@
+import { ServiceAssertionError } from '@powersync/lib-services-framework';
+import {
+  BucketDataSource,
+  BucketDefinitionId,
+  EventDefinitionId,
+  HashMap,
+  ParameterIndexId,
+  ParameterIndexLookupCreator,
+  ParameterLookupDefinitionId,
+  SerializedBucketDataSourceWithDataSources,
+  serializedEventDefinitionEquality,
+  SerializedEventDescriptor,
+  SerializedParameterIndexLookupCreator,
+  serializedStreamBucketDataSourceEquality,
+  serializedStreamParameterIndexLookupCreatorEquality,
+  SerializedSyncPlan,
+  SourceTableRef,
+  SyncConfigWithErrors
+} from '@powersync/service-sync-rules';
+
+/** Minimal shape required to resolve an event's assigned id: its name is the per-config key. */
+export interface NamedEventDefinition {
+  readonly name: string;
+}
+
+export interface SerializedSyncConfigWithMapping {
+  plan: SerializedSyncPlan;
+  mapping: SingleSyncConfigBucketDefinitionMapping;
+}
+
+export type IncrementalMappingDefinitionType = 'bucket_data' | 'parameter_lookup' | 'event';
+
+export interface IncrementalMappingDefinitionChange {
+  type: IncrementalMappingDefinitionType;
+  name: string;
+  id: BucketDefinitionId | ParameterIndexId | EventDefinitionId;
+}
+
+export interface IncrementalMappingChanges {
+  reusedDefinitions: IncrementalMappingDefinitionChange[];
+  addedDefinitions: IncrementalMappingDefinitionChange[];
+}
+
+export interface IncrementalMappingResult {
+  mapping: SingleSyncConfigBucketDefinitionMapping;
+  changes: IncrementalMappingChanges;
+}
+export interface SyncConfigWithMapping {
+  syncConfigId?: string;
+  syncConfig: SyncConfigWithErrors;
+  mapping: SingleSyncConfigBucketDefinitionMapping | null;
+}
+
+export interface SyncConfigWithRequiredMapping {
+  syncConfigId: string;
+  syncConfig: SyncConfigWithErrors;
+  mapping: SingleSyncConfigBucketDefinitionMapping;
+}
+
+export interface PersistedDefinitionMapping {
+  /**
+   * Map of uniqueName -> id, unique per replication stream.
+   */
+  definitions: Record<string, string>;
+  /**
+   * Map of (lookupName, queryId) -> id, unique per replication stream.
+   */
+  parameter_indexes: Record<string, string>;
+  /**
+   * Map of event name -> id, unique per replication stream. Absent for mappings persisted before events were tracked.
+   */
+  events?: Record<string, string>;
+}
+
+/**
+ * Represents a mapping from bucket data sources and parameter lookup sources to stable IDs used for bucket definition and parameter index persistence.
+ *
+ * Usage is deliberately restricted: writer/batch paths resolve through their own parsed
+ * sync config set's mapping, and read paths resolve through the persisted
+ * {@link SingleSyncConfigBucketDefinitionMapping} of the single sync config they serve.
+ * Do not construct ad-hoc resolution paths from parsed sources.
+ */
+export interface BucketDefinitionMapping {
+  /**
+   * Given a BucketDataSource within the associated SyncConfig(s), return the BucketDefinitionId, or throw if not found.
+   */
+  bucketSourceId(source: BucketDataSource): BucketDefinitionId;
+
+  parameterLookupId(source: ParameterIndexLookupCreator): ParameterIndexId;
+
+  allBucketDefinitionIds(): BucketDefinitionId[];
+
+  allParameterIndexIds(): ParameterIndexId[];
+
+  allEventDefinitionIds(): EventDefinitionId[];
+
+  syncConfigIdsForSourceTable(
+    selectedSyncConfigIds: string[],
+    table: SourceTableRef,
+    bucketDataSourceIds: BucketDefinitionId[],
+    parameterLookupSourceIds: ParameterIndexId[],
+    eventDefinitionIds: EventDefinitionId[]
+  ): string[];
+
+  snapshotBlockingSourceTablesFilter(syncConfigId: string): Record<string, unknown>;
+}
+
+/**
+ * A BucketDefinitionMapping associated with a single SyncConfig.
+ *
+ * Within a single SyncConfig, unique names are the persistence key for bucket definitions,
+ * so lookups here are name-based by design. MongoHydrationState and
+ * MultiSyncConfigBucketDefinitionMapping handle the mapping across multiple SyncConfigs in
+ * the same replication stream, where names are not unique.
+ */
+export class SingleSyncConfigBucketDefinitionMapping implements BucketDefinitionMapping {
+  static fromPersistedMapping(mapping: PersistedDefinitionMapping): SingleSyncConfigBucketDefinitionMapping {
+    return new SingleSyncConfigBucketDefinitionMapping(
+      mapping.definitions ?? {},
+      mapping.parameter_indexes ?? {},
+      mapping.events ?? {}
+    );
+  }
+
+  static fromParsedSyncConfig(syncConfig: SyncConfigWithErrors): SingleSyncConfigBucketDefinitionMapping {
+    const definitionNames = syncConfig.config.bucketDataSources.map((source) => source.uniqueName).sort();
+    const parameterKeys = syncConfig.config.bucketParameterLookupSources
+      .map((source) => `${source.sourceId.lookupName}#${source.sourceId.queryId}`)
+      .sort();
+    const eventNames = syncConfig.config.eventDefinitions.map((event) => event.name).sort();
+
+    const definitions: Record<string, BucketDefinitionId> = {};
+    const parameterLookups: Record<string, ParameterIndexId> = {};
+    const events: Record<string, EventDefinitionId> = {};
+
+    for (const [index, uniqueName] of definitionNames.entries()) {
+      definitions[uniqueName] = (index + 1).toString(16);
+    }
+    for (const [index, key] of parameterKeys.entries()) {
+      parameterLookups[key] = (index + 1).toString(16);
+    }
+    for (const [index, name] of eventNames.entries()) {
+      events[name] = (index + 1).toString(16);
+    }
+
+    return new SingleSyncConfigBucketDefinitionMapping(definitions, parameterLookups, events);
+  }
+
+  /**
+   *
+   * @param compatibleConfigs SyncConfigs with definitions that may be re-used
+   * @param newPlan
+   * @param reservedMappings _all_ mappings used currently and historically for the replication stream; used to construct new ids
+   * @returns
+   */
+  static constructIncrementalMappingFromSerializedPlans(
+    compatibleConfigs: SerializedSyncConfigWithMapping[],
+    newPlan: SerializedSyncPlan,
+    reservedMappings: SingleSyncConfigBucketDefinitionMapping[]
+  ): SingleSyncConfigBucketDefinitionMapping {
+    return this.constructIncrementalMappingWithChanges(compatibleConfigs, newPlan, reservedMappings).mapping;
+  }
+
+  static constructIncrementalMappingWithChanges(
+    compatibleConfigs: SerializedSyncConfigWithMapping[],
+    newPlan: SerializedSyncPlan,
+    reservedMappings: SingleSyncConfigBucketDefinitionMapping[]
+  ): IncrementalMappingResult {
+    let nextBucketDefinitionId =
+      reservedMappings
+        .map((mapping) => mapping.allBucketDefinitionIds())
+        .flat()
+        .reduce((maxId, id) => Math.max(maxId, parseInt(id, 16)), 0) + 1;
+    function generateNewBucketDefinitionId(): BucketDefinitionId {
+      const id = nextBucketDefinitionId.toString(16);
+      nextBucketDefinitionId++;
+      return id;
+    }
+    let nextParameterIndexId =
+      reservedMappings
+        .map((mapping) => mapping.allParameterIndexIds())
+        .flat()
+        .reduce((maxId, id) => Math.max(maxId, parseInt(id, 16)), 0) + 1;
+    function generateNewParameterIndexId(): ParameterIndexId {
+      const id = nextParameterIndexId.toString(16);
+      nextParameterIndexId++;
+      return id;
+    }
+    // Event ids are deliberately allocated per replication stream instead of being hashes or UUIDs derived from a
+    // compiled plan. Compatibility decides whether to reuse an existing id, keeping the storage identifier separate
+    // from event content and allowing the comparison to evolve independently. That comparison must remain
+    // conservative: a false negative only causes a new id and resnapshot, while a false positive could incorrectly
+    // reuse existing event state.
+    let nextEventDefinitionId =
+      reservedMappings
+        .map((mapping) => mapping.allEventDefinitionIds())
+        .flat()
+        .reduce((maxId, id) => Math.max(maxId, parseInt(id, 16)), 0) + 1;
+    function generateNewEventDefinitionId(): EventDefinitionId {
+      const id = nextEventDefinitionId.toString(16);
+      nextEventDefinitionId++;
+      return id;
+    }
+
+    const definitions: Record<string, BucketDefinitionId> = {};
+    const parameterLookups: Record<string, ParameterIndexId> = {};
+    const events: Record<string, EventDefinitionId> = {};
+    const changes: IncrementalMappingChanges = {
+      reusedDefinitions: [],
+      addedDefinitions: []
+    };
+    const compatibleBuckets = new HashMap<SerializedBucketDataSourceWithDataSources, BucketDefinitionId>(
+      serializedStreamBucketDataSourceEquality
+    );
+    const compatibleParameterLookups = new HashMap<SerializedParameterIndexLookupCreator, ParameterIndexId>(
+      serializedStreamParameterIndexLookupCreatorEquality
+    );
+    const compatibleEvents = new HashMap<SerializedEventDescriptor, EventDefinitionId>(
+      serializedEventDefinitionEquality
+    );
+
+    for (const config of compatibleConfigs) {
+      for (const bucket of config.plan.buckets) {
+        compatibleBuckets.putIfAbsent({ bucket, dataSources: config.plan.dataSources }, () =>
+          config.mapping.bucketSourceIdByName(bucket.uniqueName)
+        );
+      }
+
+      for (const parameterLookup of config.plan.parameterIndexes) {
+        compatibleParameterLookups.putIfAbsent(parameterLookup, () =>
+          config.mapping.parameterLookupIdByKey(parameterLookupKey(parameterLookup.lookupScope))
+        );
+      }
+
+      for (const event of config.plan.events ?? []) {
+        compatibleEvents.putIfAbsent(event, () => config.mapping.eventDefinitionIdByName(event.name));
+      }
+    }
+
+    for (const bucket of newPlan.buckets) {
+      const compatibleId = compatibleBuckets.get({ bucket, dataSources: newPlan.dataSources });
+      const id = compatibleId ?? generateNewBucketDefinitionId();
+      definitions[bucket.uniqueName] = id;
+      const change: IncrementalMappingDefinitionChange = {
+        type: 'bucket_data',
+        name: bucket.uniqueName,
+        id
+      };
+      if (compatibleId == null) {
+        changes.addedDefinitions.push(change);
+      } else {
+        changes.reusedDefinitions.push(change);
+      }
+    }
+
+    for (const parameterLookup of newPlan.parameterIndexes) {
+      const compatibleId = compatibleParameterLookups.get(parameterLookup);
+      const id = compatibleId ?? generateNewParameterIndexId();
+      const key = parameterLookupKey(parameterLookup.lookupScope);
+      parameterLookups[key] = id;
+      const change: IncrementalMappingDefinitionChange = {
+        type: 'parameter_lookup',
+        name: key,
+        id
+      };
+      if (compatibleId == null) {
+        changes.addedDefinitions.push(change);
+      } else {
+        changes.reusedDefinitions.push(change);
+      }
+    }
+
+    for (const event of newPlan.events ?? []) {
+      const compatibleId = compatibleEvents.get(event);
+      const id = compatibleId ?? generateNewEventDefinitionId();
+      events[event.name] = id;
+      const change: IncrementalMappingDefinitionChange = {
+        type: 'event',
+        name: event.name,
+        id
+      };
+      if (compatibleId == null) {
+        changes.addedDefinitions.push(change);
+      } else {
+        changes.reusedDefinitions.push(change);
+      }
+    }
+
+    return {
+      mapping: new SingleSyncConfigBucketDefinitionMapping(definitions, parameterLookups, events),
+      changes
+    };
+  }
+
+  constructor(
+    private definitions: Record<string, BucketDefinitionId> = {},
+    private parameterLookupMapping: Record<string, ParameterIndexId> = {},
+    private events: Record<string, EventDefinitionId> = {}
+  ) {}
+
+  bucketSourceId(source: BucketDataSource): BucketDefinitionId {
+    return this.bucketSourceIdByName(source.uniqueName);
+  }
+
+  bucketSourceIdByName(uniqueName: string): BucketDefinitionId {
+    const defId = this.definitions[uniqueName];
+    if (defId == null) {
+      throw new ServiceAssertionError(`No mapping found for bucket source ${uniqueName}`);
+    }
+    return defId;
+  }
+
+  allBucketDefinitionIds(): BucketDefinitionId[] {
+    return Object.values(this.definitions);
+  }
+
+  bucketDefinitionEntries(): IncrementalMappingDefinitionChange[] {
+    return Object.entries(this.definitions).map(([name, id]) => ({
+      type: 'bucket_data',
+      name,
+      id
+    }));
+  }
+
+  allParameterIndexIds(): ParameterIndexId[] {
+    return Object.values(this.parameterLookupMapping);
+  }
+
+  parameterIndexEntries(): IncrementalMappingDefinitionChange[] {
+    return Object.entries(this.parameterLookupMapping).map(([name, id]) => ({
+      type: 'parameter_lookup',
+      name,
+      id
+    }));
+  }
+
+  allEventDefinitionIds(): EventDefinitionId[] {
+    return Object.values(this.events);
+  }
+
+  eventDefinitionEntries(): IncrementalMappingDefinitionChange[] {
+    return Object.entries(this.events).map(([name, id]) => ({
+      type: 'event',
+      name,
+      id
+    }));
+  }
+
+  allDefinitionEntries(): IncrementalMappingDefinitionChange[] {
+    return [...this.bucketDefinitionEntries(), ...this.parameterIndexEntries(), ...this.eventDefinitionEntries()];
+  }
+
+  parameterLookupId(source: ParameterIndexLookupCreator): ParameterIndexId {
+    return this.parameterLookupIdByKey(parameterLookupKey(source.sourceId));
+  }
+
+  parameterLookupIdByKey(key: string): ParameterIndexId {
+    const defId = this.parameterLookupMapping[key];
+    if (defId == null) {
+      throw new ServiceAssertionError(`No mapping found for parameter lookup source ${key}`);
+    }
+    return defId;
+  }
+
+  eventId(event: NamedEventDefinition): EventDefinitionId {
+    return this.eventDefinitionIdByName(event.name);
+  }
+
+  eventDefinitionIdByName(name: string): EventDefinitionId {
+    const id = this.events[name];
+    if (id == null) {
+      throw new ServiceAssertionError(`No mapping found for event definition ${name}`);
+    }
+    return id;
+  }
+
+  serialize(): PersistedDefinitionMapping {
+    return {
+      definitions: { ...this.definitions },
+      parameter_indexes: { ...this.parameterLookupMapping },
+      events: { ...this.events }
+    };
+  }
+
+  syncConfigIdsForSourceTable(
+    selectedSyncConfigIds: string[],
+    _table: SourceTableRef,
+    bucketDataSourceIds: BucketDefinitionId[],
+    parameterLookupSourceIds: ParameterIndexId[],
+    eventDefinitionIds: EventDefinitionId[]
+  ): string[] {
+    return bucketDataSourceIds.length > 0 || parameterLookupSourceIds.length > 0 || eventDefinitionIds.length > 0
+      ? selectedSyncConfigIds
+      : [];
+  }
+
+  snapshotBlockingSourceTablesFilter(_syncConfigId: string): Record<string, unknown> {
+    const clauses: Record<string, unknown>[] = [];
+    const bucketDataSourceIds = this.allBucketDefinitionIds();
+    if (bucketDataSourceIds.length > 0) {
+      clauses.push({ bucket_data_source_ids: { $in: bucketDataSourceIds } });
+    }
+    const parameterLookupSourceIds = this.allParameterIndexIds();
+    if (parameterLookupSourceIds.length > 0) {
+      clauses.push({ parameter_lookup_source_ids: { $in: parameterLookupSourceIds } });
+    }
+    const eventDefinitionIds = this.allEventDefinitionIds();
+    if (eventDefinitionIds.length > 0) {
+      clauses.push({ event_definition_ids: { $in: eventDefinitionIds } });
+    }
+    if (clauses.length == 0) {
+      return {
+        snapshot_done: false,
+        _id: { $exists: false }
+      };
+    }
+    return {
+      snapshot_done: false,
+      $or: clauses
+    };
+  }
+}
+
+/**
+ * A BucketDefinitionMapping across all SyncConfigs of one parse of a replication stream.
+ *
+ * Source lookups are strictly identity-based: a source that did not come from the parse
+ * this mapping was constructed with is an error. Unique names are not unique across sync
+ * configs in a replication stream, so there is deliberately no name-based fallback.
+ */
+export class MultiSyncConfigBucketDefinitionMapping implements BucketDefinitionMapping {
+  private bucketDataSourceMappings = new WeakMap<BucketDataSource, SingleSyncConfigBucketDefinitionMapping>();
+  private bucketDataSourceSyncConfigIdsById = new Map<BucketDefinitionId, Set<string>>();
+  private parameterLookupMappings = new WeakMap<ParameterIndexLookupCreator, SingleSyncConfigBucketDefinitionMapping>();
+  private parameterLookupSyncConfigIdsById = new Map<ParameterIndexId, Set<string>>();
+  private eventDefinitionSyncConfigIdsById = new Map<EventDefinitionId, Set<string>>();
+  private syncConfigsById = new Map<string, SyncConfigWithRequiredMapping>();
+  private mappings: SingleSyncConfigBucketDefinitionMapping[];
+
+  constructor(syncConfigs: SyncConfigWithRequiredMapping[]) {
+    this.mappings = syncConfigs.map((config) => config.mapping);
+
+    for (const config of syncConfigs) {
+      this.syncConfigsById.set(config.syncConfigId, config);
+      for (const source of config.syncConfig.config.bucketDataSources) {
+        this.bucketDataSourceMappings.set(source, config.mapping);
+        addSetEntry(this.bucketDataSourceSyncConfigIdsById, config.mapping.bucketSourceId(source), config.syncConfigId);
+      }
+      for (const source of config.syncConfig.config.bucketParameterLookupSources) {
+        this.parameterLookupMappings.set(source, config.mapping);
+        addSetEntry(
+          this.parameterLookupSyncConfigIdsById,
+          config.mapping.parameterLookupId(source),
+          config.syncConfigId
+        );
+      }
+      for (const event of config.syncConfig.config.eventDefinitions) {
+        addSetEntry(this.eventDefinitionSyncConfigIdsById, config.mapping.eventId(event), config.syncConfigId);
+      }
+    }
+  }
+
+  bucketSourceId(source: BucketDataSource): BucketDefinitionId {
+    const mapping = this.bucketDataSourceMappings.get(source);
+    if (mapping == null) {
+      throw new ServiceAssertionError(
+        `Bucket source ${source.uniqueName} is not associated with this parse of the sync configs`
+      );
+    }
+    return mapping.bucketSourceId(source);
+  }
+
+  allBucketDefinitionIds(): BucketDefinitionId[] {
+    return [...new Set(this.mappings.flatMap((mapping) => mapping.allBucketDefinitionIds()))];
+  }
+
+  parameterLookupId(source: ParameterIndexLookupCreator): ParameterIndexId {
+    const mapping = this.parameterLookupMappings.get(source);
+    if (mapping == null) {
+      throw new ServiceAssertionError(
+        `Parameter lookup source ${source.sourceId.lookupName}#${source.sourceId.queryId} is not associated with this parse of the sync configs`
+      );
+    }
+    return mapping.parameterLookupId(source);
+  }
+
+  allParameterIndexIds(): ParameterIndexId[] {
+    return [...new Set(this.mappings.flatMap((mapping) => mapping.allParameterIndexIds()))];
+  }
+
+  allEventDefinitionIds(): EventDefinitionId[] {
+    return [...new Set(this.mappings.flatMap((mapping) => mapping.allEventDefinitionIds()))];
+  }
+
+  syncConfigIdsForSourceTable(
+    _selectedSyncConfigIds: string[],
+    _table: SourceTableRef,
+    bucketDataSourceIds: BucketDefinitionId[],
+    parameterLookupSourceIds: ParameterIndexId[],
+    eventDefinitionIds: EventDefinitionId[]
+  ): string[] {
+    const ids = new Set<string>();
+    for (const sourceId of bucketDataSourceIds) {
+      addAll(ids, this.bucketDataSourceSyncConfigIdsById.get(sourceId));
+    }
+    for (const sourceId of parameterLookupSourceIds) {
+      addAll(ids, this.parameterLookupSyncConfigIdsById.get(sourceId));
+    }
+    for (const eventDefinitionId of eventDefinitionIds) {
+      addAll(ids, this.eventDefinitionSyncConfigIdsById.get(eventDefinitionId));
+    }
+    return [...ids];
+  }
+
+  snapshotBlockingSourceTablesFilter(syncConfigId: string): Record<string, unknown> {
+    const config = this.syncConfigsById.get(syncConfigId);
+    if (config == null) {
+      throw new ServiceAssertionError(`No mapping found for sync config ${syncConfigId}`);
+    }
+
+    return config.mapping.snapshotBlockingSourceTablesFilter(syncConfigId);
+  }
+}
+
+export function parameterLookupKey(id: ParameterLookupDefinitionId) {
+  return `${id.lookupName}#${id.queryId}`;
+}
+
+function addSetEntry<K, V>(map: Map<K, Set<V>>, key: K, value: V) {
+  const existing = map.get(key) ?? new Set<V>();
+  existing.add(value);
+  map.set(key, existing);
+}
+
+function addAll<T>(target: Set<T>, values: Iterable<T> | undefined) {
+  for (const value of values ?? []) {
+    target.add(value);
+  }
+}

package/src/storage/implementation/IncrementalReprocessingCompatibility.ts

@@ -0,0 +1,41 @@
+import { CompatibilityContext } from '@powersync/service-sync-rules';
+import { Logger } from 'winston';
+import { SerializedSyncPlan, UpdateSyncRulesOptions } from '../BucketStorageFactory.js';
+
+/**
+ * Check if a sync config update can use incremental reprocessing.
+ */
+export function isCompatible(
+  existingPlans: (SerializedSyncPlan | null)[],
+  updateConfig: UpdateSyncRulesOptions['config'],
+  logger: Logger
+): boolean {
+  if (updateConfig.plan == null) {
+    // Only support sync streams with serialized plans
+    logger.info(`Not using current sync streams - incremental reprocessing not supported`);
+    return false;
+  }
+
+  // We don't check the storage version here - that is checked upstream.
+  if (existingPlans.length == 0) {
+    // Could technically be compatible, but there is no reason to re-use this stream.
+    return false;
+  }
+
+  if (existingPlans.some((plan) => plan == null)) {
+    // Only support sync streams with serialized plans
+    logger.info(`Existing replication stream not using current sync streams - incremental reprocessing not supported`);
+    return false;
+  }
+
+  // Technically we can compare the serialized compatibility versions? But this does not add much overhead.
+  const first = existingPlans[0];
+  const streamCompatibility = CompatibilityContext.deserialize(first!.compatibility);
+  if (!streamCompatibility.equals(updateConfig.parsed.config.compatibility)) {
+    // Compatibility options must match
+    logger.info(`Compatibility options changed - incremental reprocessing not supported`);
+    return false;
+  }
+
+  return true;
+}

package/src/storage/implementation/IncrementalReprocessingSyncConfigLog.ts

@@ -0,0 +1,126 @@
+import {
+  BucketDataSource,
+  EventDefinition,
+  ParameterIndexLookupCreator,
+  SyncConfigWithErrors
+} from '@powersync/service-sync-rules';
+import {
+  IncrementalMappingChanges,
+  IncrementalMappingDefinitionChange,
+  SingleSyncConfigBucketDefinitionMapping
+} from './BucketDefinitionMapping.js';
+
+export interface IncrementalDefinitionLogEntry extends IncrementalMappingDefinitionChange {
+  sourceTables?: string[];
+}
+
+export interface IncrementalSyncConfigUpdateLog {
+  reusedDefinitions: IncrementalDefinitionLogEntry[];
+  addedDefinitions: IncrementalDefinitionLogEntry[];
+  droppedDefinitions: IncrementalDefinitionLogEntry[];
+}
+
+export function formatIncrementalSyncConfigUpdateLog(log: IncrementalSyncConfigUpdateLog) {
+  return [
+    formatDefinitionSection('Reused definitions', log.reusedDefinitions),
+    formatDefinitionSection('New definitions', log.addedDefinitions, { includeSnapshotTables: true }),
+    formatDefinitionSection('Definitions to drop after switching', log.droppedDefinitions)
+  ].join('\n');
+}
+
+export function describeIncrementalSyncConfigUpdate(options: {
+  activeMappings: SingleSyncConfigBucketDefinitionMapping[];
+  newMapping: SingleSyncConfigBucketDefinitionMapping;
+  newSyncConfig: SyncConfigWithErrors;
+  mappingChanges: IncrementalMappingChanges;
+}): IncrementalSyncConfigUpdateLog {
+  const { activeMappings, newMapping, newSyncConfig, mappingChanges } = options;
+  // Buckets, parameter lookups and events all flow through the mapping's assigned ids, so their changes are
+  // already present in mappingChanges and allDefinitionEntries().
+  const newDefinitionKeys = new Set(newMapping.allDefinitionEntries().map(definitionKey));
+  const activeDefinitions = uniqueDefinitions(activeMappings.flatMap((mapping) => mapping.allDefinitionEntries()));
+
+  return {
+    reusedDefinitions: mappingChanges.reusedDefinitions,
+    addedDefinitions: mappingChanges.addedDefinitions.map((definition) => {
+      const sourceTables = sourceTablesForDefinition(newSyncConfig, newMapping, definition);
+      return {
+        ...definition,
+        sourceTables
+      };
+    }),
+    droppedDefinitions: activeDefinitions.filter((definition) => !newDefinitionKeys.has(definitionKey(definition)))
+  };
+}
+
+function sourceTablesForDefinition(
+  syncConfig: SyncConfigWithErrors,
+  mapping: SingleSyncConfigBucketDefinitionMapping,
+  definition: IncrementalMappingDefinitionChange
+) {
+  if (definition.type == 'bucket_data') {
+    return sourceTablesForSources(
+      syncConfig.config.bucketDataSources.filter((source) => mapping.bucketSourceId(source) == definition.id)
+    );
+  }
+
+  if (definition.type == 'parameter_lookup') {
+    return sourceTablesForSources(
+      syncConfig.config.bucketParameterLookupSources.filter(
+        (source) => mapping.parameterLookupId(source) == definition.id
+      )
+    );
+  }
+
+  return sourceTablesForEvents(
+    syncConfig.config.eventDefinitions.filter((event) => mapping.eventId(event) == definition.id)
+  );
+}
+
+function sourceTablesForSources(sources: Array<BucketDataSource | ParameterIndexLookupCreator>) {
+  return uniqueSorted(sources.flatMap((source) => [...source.getSourceTables()].map((table) => table.tablePattern)));
+}
+
+function sourceTablesForEvents(events: EventDefinition[]) {
+  return uniqueSorted(events.flatMap((event) => [...event.getSourceTables()].map((table) => table.tablePattern)));
+}
+
+function definitionKey(definition: IncrementalMappingDefinitionChange) {
+  return `${definition.type}:${definition.id}`;
+}
+
+function uniqueSorted(values: string[]) {
+  return [...new Set(values)].sort();
+}
+
+function uniqueDefinitions(definitions: IncrementalMappingDefinitionChange[]) {
+  const byKey = new Map<string, IncrementalMappingDefinitionChange>();
+  for (const definition of definitions) {
+    byKey.set(definitionKey(definition), definition);
+  }
+  return [...byKey.values()];
+}
+
+function formatDefinitionSection(
+  title: string,
+  definitions: IncrementalDefinitionLogEntry[],
+  options: { includeSnapshotTables?: boolean } = {}
+) {
+  if (definitions.length == 0) {
+    return `${title}: none`;
+  }
+
+  return [`${title}:`, ...definitions.map((definition) => `  - ${formatDefinition(definition, options)}`)].join('\n');
+}
+
+function formatDefinition(definition: IncrementalDefinitionLogEntry, options: { includeSnapshotTables?: boolean }) {
+  const details = [`type=${definition.type}`, `id=${definition.id}`, `name=${definition.name}`];
+  if (definition.sourceTables != null) {
+    details.push(`tables=${formatList(definition.sourceTables)}`);
+  }
+  return details.join(', ');
+}
+
+function formatList(values: string[]) {
+  return values.length == 0 ? 'none' : values.join(', ');
+}