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

package/src/storage/implementation/IncrementalReprocessingCompatibility.ts

@@ -1,4 +1,4 @@
-import { CompatibilityContext } from '@powersync/service-sync-rules';
+import { CompatibilityContext, connectionConfigsEqual } from '@powersync/service-sync-rules';
 import { Logger } from 'winston';
 import { SerializedSyncPlan, UpdateSyncRulesOptions } from '../BucketStorageFactory.js';
 
@@ -11,8 +11,8 @@ export function isCompatible(
   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`);
+    // Only support Sync Streams with serialized plans
+    logger.info(`Not using current Sync Streams - incremental reprocessing not supported`);
     return false;
   }
 
@@ -23,8 +23,8 @@ export function isCompatible(
   }
 
   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`);
+    // Only support Sync Streams with serialized plans
+    logger.info(`Existing replication stream not using current Sync Streams - incremental reprocessing not supported`);
     return false;
   }
 
@@ -37,5 +37,14 @@ export function isCompatible(
     return false;
   }
 
+  if (
+    existingPlans.some(
+      (existing) =>
+        !connectionConfigsEqual(existing!.plan.connectionConfig ?? {}, updateConfig.plan!.plan.connectionConfig ?? {})
+    )
+  ) {
+    logger.info('Connection configuration changed - incremental reprocessing not supported');
+    return false;
+  }
   return true;
 }

package/src/storage/storage-index.ts

@@ -25,3 +25,4 @@ export * from './implementation/BucketDefinitionMapping.js';
 export * from './implementation/IncrementalReprocessingCompatibility.js';
 export * from './implementation/IncrementalReprocessingSyncConfigLog.js';
 export * from './implementation/ReplicationStreamStorageIds.js';
+export * from './SyncConfigParser.js';

package/src/sync/BucketChecksumState.ts

@@ -89,7 +89,7 @@ export class BucketChecksumState {
    * subscribed to, we keep an index of the stream names to their index in that array.
    *
    * This is used to compress the representation of buckets in `checkpoint` and `checkpoint_diff` lines: For buckets
-   * that are part of sync rules or default streams, we need to include the name of the defining sync rule or definition
+   * that are part of legacy Sync Rules or default streams, we need to include the name of the defining bucket definition or stream
    * yielding that bucket (so that clients can track progress for default streams).
    * But instead of sending the name for each bucket, we use the fact that it's part of the streams array and only send
    * their index, reducing the size of those messages.
@@ -747,7 +747,8 @@ export class BucketParameterState {
         }
       }
     }
-    const allBuckets = [...staticBuckets, ...mergeBuckets(dynamicBuckets)];
+    // A stream can reach the same bucket through both static and dynamic parameters.
+    const allBuckets = mergeBuckets([...staticBuckets, ...dynamicBuckets]);
 
     if (invalidateDataBuckets) {
       return {
@@ -816,7 +817,7 @@ function logCheckpoint(
 }
 
 /**
- * Format a breakdown of dynamic buckets by sync stream or legacy bucket definition.
+ * Format a breakdown of dynamic buckets by Sync Stream or legacy bucket definition.
  *
  * Sorts definitions by count (descending), includes the top 100, and returns both the
  * formatted message string and the counts record suitable for structured log data.
@@ -834,7 +835,7 @@ function formatBucketDefinitionBreakdown(
   const allSorted = Array.from(bucketsByDefinition.entries()).sort((a, b) => b[1] - a[1]);
   const sortedDefinitions = allSorted.slice(0, maxLoggedDefinitions);
 
-  const sourceLabel = bucketSourceType == BucketSourceType.SYNC_STREAM ? 'sync stream' : 'bucket definition';
+  const sourceLabel = bucketSourceType == BucketSourceType.SYNC_STREAM ? 'Sync Stream' : 'bucket definition';
   let message = `\nBuckets by ${sourceLabel}:`;
   const countsByDefinition: Record<string, number> = {};
   for (const [definition, count] of sortedDefinitions) {

package/src/sync/util.ts

@@ -144,8 +144,11 @@ export async function* transformToBytesTracked(
 
 export function acquireSemaphoreAbortable(
   semaphone: SemaphoreInterface,
-  abort: AbortSignal
+  abort?: AbortSignal
 ): Promise<[number, SemaphoreInterface.Releaser] | 'aborted'> {
+  if (abort == null) {
+    return semaphone.acquire();
+  }
   return new Promise((resolve, reject) => {
     // An already-aborted signal never fires its listener, and we would wait for the semaphore
     // indefinitely.

package/src/system/ServiceContext.ts

@@ -1,4 +1,5 @@
 import { container, LifeCycledSystem, MigrationManager, ServiceIdentifier } from '@powersync/lib-services-framework';
+import type { AdditionalSyncConfigParser } from '@powersync/service-sync-rules';
 
 import { EventsEngine } from '../events/EventsEngine.js';
 import { framework } from '../index.js';
@@ -10,6 +11,16 @@ import * as storage from '../storage/storage-index.js';
 import { SyncContext } from '../sync/SyncContext.js';
 import * as utils from '../util/util-index.js';
 
+/**
+ * Registration-capable sync-config parser exposed to modules through the service context.
+ */
+export interface ServiceContextSyncConfigParser extends storage.SyncConfigParser {
+  /**
+   * Registers a deterministic parser extension during module initialization, before storage starts.
+   */
+  registerParser(extension: AdditionalSyncConfigParser): void;
+}
+
 export interface ServiceContext {
   configuration: utils.ResolvedPowerSyncConfig;
   lifeCycleEngine: LifeCycledSystem;
@@ -22,6 +33,11 @@ export interface ServiceContext {
   writeCheckpointBatcher: utils.WriteCheckpointBatcher;
   serviceMode: ServiceContextMode;
   eventsEngine: EventsEngine;
+  /**
+   * Service-wide parser shared by routes, replication, and storage. Source modules register parser extensions on this
+   * instance during module initialization.
+   */
+  readonly syncConfigParser: ServiceContextSyncConfigParser;
 }
 
 export enum ServiceContextMode {
@@ -53,16 +69,20 @@ export class ServiceContextContainer implements ServiceContext {
   routerEngine: routes.RouterEngine;
   writeCheckpointBatcher: utils.WriteCheckpointBatcher;
   serviceMode: ServiceContextMode;
+  readonly #syncConfigParser: ServiceContextSyncConfigParser;
 
   constructor(options: ServiceContextOptions) {
     this.serviceMode = options.serviceMode;
     const { configuration } = options;
     this.configuration = configuration;
 
+    this.#syncConfigParser = new ServiceContextSyncConfigParserImpl(() => this.storageEngine.started);
+
     this.lifeCycleEngine = new LifeCycledSystem();
 
     this.storageEngine = new storage.StorageEngine({
-      configuration
+      configuration,
+      syncConfigParser: this.#syncConfigParser
     });
     this.storageEngine.registerListener({
       storageFatalError: (error) => {
@@ -114,6 +134,13 @@ export class ServiceContextContainer implements ServiceContext {
     return container.getOptional(replication.ReplicationEngine);
   }
 
+  /**
+   * Returns the service-wide parser shared by routes, replication, and storage.
+   */
+  get syncConfigParser(): ServiceContextSyncConfigParser {
+    return this.#syncConfigParser;
+  }
+
   get metricsEngine(): metrics.MetricsEngine {
     return container.getImplementation(metrics.MetricsEngine);
   }
@@ -137,3 +164,22 @@ export class ServiceContextContainer implements ServiceContext {
     return container.getImplementation(identifier);
   }
 }
+
+/**
+ * Registration-capable parser exposed by the service context during module initialization.
+ */
+class ServiceContextSyncConfigParserImpl extends storage.SqlSyncConfigParser implements ServiceContextSyncConfigParser {
+  constructor(private readonly isStorageStarted: () => boolean) {
+    super();
+  }
+
+  /**
+   * Registers an extension while preserving one parser definition for the service lifetime.
+   */
+  override registerParser(extension: AdditionalSyncConfigParser): void {
+    if (this.isStorageStarted()) {
+      throw new Error('A sync config parser extension cannot be registered after the storage engine has started.');
+    }
+    super.registerParser(extension);
+  }
+}

package/src/util/param-logging.ts

@@ -18,8 +18,9 @@ export const DEFAULT_PARAM_LOGGING_FORMAT_OPTIONS: ParamLoggingFormatOptions = {
  * Formats potentially arbitrary parameters for logging.
  * This limits the number of keys and strings to a maximum length.
  * A warning key-value is added if the number of keys exceeds the maximum.
- * String values exceeding the maximum length are truncated.
+ * Keys and string values exceeding the maximum length are truncated.
  * Non-String values are stringified, the maximum length is then applied.
+ * Values that cannot be serialized are replaced with a placeholder.
  * @param params - The parameters to format.
  * @param options - The options to use.
  * @default DEFAULT_PARAM_LOGGING_FORMAT_OPTIONS
@@ -41,20 +42,26 @@ export function limitParamsForLogging(
     return value;
   }
 
-  return Object.fromEntries(
-    Object.entries(params).map(([key, value], index) => {
-      if (index == maxKeyCount) {
-        return ['⚠️', 'Additional parameters omitted'];
-      }
+  function formatValue(value: unknown): string {
+    if (typeof value == 'string') {
+      return trimString(value);
+    }
+    try {
+      return trimString(JSON.stringify(value) ?? '[undefined]');
+    } catch {
+      return trimString('[unserializable]');
+    }
+  }
 
-      if (index > maxKeyCount) {
-        return [];
-      }
+  return Object.fromEntries(
+    Object.entries(params)
+      .slice(0, maxKeyCount + 1)
+      .map(([key, value], index) => {
+        if (index == maxKeyCount) {
+          return ['⚠️', 'Additional parameters omitted'];
+        }
 
-      if (typeof value == 'string') {
-        return [key, trimString(value)];
-      }
-      return [key, trimString(JSON.stringify(value))];
-    })
+        return [trimString(key), formatValue(value)];
+      })
   );
 }

package/src/util/protocol-types.ts

@@ -19,7 +19,7 @@ export type BucketRequest = t.Decoded<typeof BucketRequest>;
  */
 export const RequestedStreamSubscription = t.object({
   /**
-   * The defined name of the stream as it appears in sync stream definitions.
+   * The defined name of the stream as it appears in Sync Stream definitions.
    */
   stream: t.string,
   /**
@@ -29,7 +29,7 @@ export const RequestedStreamSubscription = t.object({
   /**
    * Set when the client wishes to re-assign a different priority to this stream.
    *
-   * Streams and sync rules can also assign a default priority, but clients are allowed to override those. This can be
+   * Sync Streams and legacy bucket definitions can also assign a default priority, but clients are allowed to override those. This can be
    * useful when the priority for partial syncs depends on e.g. the current page opened in a client.
    */
   override_priority: orNull(t.number)
@@ -49,7 +49,7 @@ export const StreamSubscriptionRequest = t.object({
   include_defaults: t.boolean.optional(),
 
   /**
-   * An array of sync streams the client has opened explicitly.
+   * An array of Sync Streams the client has opened explicitly.
    */
   subscriptions: t.array(RequestedStreamSubscription)
 });
@@ -253,8 +253,8 @@ export interface BucketChecksum {
 /**
  * The reason a particular bucket is included in a checkpoint.
  *
- * This information allows clients to associate individual buckets with sync streams they're subscribed to. Having that
- * association is useful because it enables clients to track progress for individual sync streams.
+ * This information allows clients to associate individual buckets with Sync Streams they're subscribed to. Having that
+ * association is useful because it enables clients to track progress for individual Sync Streams.
  */
 export type BucketSubscriptionReason = BucketDerivedFromDefaultStream | BucketDerivedFromExplicitSubscription;
 

package/test/src/PersistedSyncConfigContent.test.ts

@@ -11,6 +11,7 @@ import { describe, expect, test } from 'vitest';
 import {
   parsePersistedSyncConfigContent,
   SerializedSyncPlan,
+  SqlSyncConfigParser,
   updateSyncRulesFromConfig
 } from '../../src/storage/storage-index.js';
 
@@ -147,6 +148,7 @@ function restore(compiledPlan: SerializedSyncPlan) {
     content: yamlWithEvents,
     compiledPlan,
     storageVersion: 1,
-    parseOptions: { defaultSchema: 'test_schema' }
+    parseOptions: { defaultSchema: 'test_schema' },
+    syncConfigParser: new SqlSyncConfigParser()
   });
 }

package/test/src/SyncConfigParser.test.ts

@@ -0,0 +1,330 @@
+import { SqlSyncConfigParser } from '@/storage/SyncConfigParser.js';
+import { isCompatible, parsePersistedSyncConfigContent, updateSyncRulesFromConfig } from '@/storage/storage-index.js';
+import { ServiceContextContainer, ServiceContextMode } from '@/system/ServiceContext.js';
+import { logger } from '@powersync/lib-services-framework';
+import * as syncRules from '@powersync/service-sync-rules';
+import {
+  AdditionalSyncConfigParser,
+  DEFAULT_HYDRATION_STATE,
+  HydratedSyncConfig,
+  nodeSqlite,
+  normalizeConnectionConfig,
+  PrecompiledSyncConfig,
+  SyncConfig
+} from '@powersync/service-sync-rules';
+import * as sqlite from 'node:sqlite';
+import { describe, expect, test, vi } from 'vitest';
+
+const STREAMS = /* yaml */ `
+  config: { edition: 3 }
+  streams:
+    orders:
+      query: SELECT * FROM orders
+`;
+const CONFIGURED = /* yaml */ `
+  config:
+    edition: 3
+    connections:
+      default:
+        type: example
+        tables:
+          orders: { sample: 10 }
+  streams:
+    orders:
+      query: SELECT * FROM orders
+`;
+
+// This fixture represents an external module. Core only knows the connection/table maps; sample is module-owned.
+function additionalParser(): AdditionalSyncConfigParser {
+  const check = (config: SyncConfig) => {
+    for (const connection of Object.values(config.connectionConfig)) {
+      if (connection?.type != 'example') continue;
+      for (const table of Object.values(connection.tables ?? {})) {
+        if (typeof (table as { sample?: number })?.sample != 'number') throw new Error('Invalid persisted sample.');
+        if ((table as { sample?: number })?.sample === 13) throw new Error('Sample 13 is unsupported.');
+      }
+    }
+  };
+  return {
+    id: 'example.tables',
+    extendJsonSchema({ schema }) {
+      const map = (schema.properties as any).config.properties.connections;
+      map.additionalProperties = {
+        if: { type: 'object', required: ['type'], properties: { type: { const: 'example' } } },
+        then: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['type'],
+          properties: {
+            type: { const: 'example' },
+            tables: {
+              type: 'object',
+              propertyNames: { minLength: 1 },
+              additionalProperties: {
+                type: 'object',
+                additionalProperties: false,
+                properties: { sample: { type: 'number' } }
+              }
+            }
+          }
+        },
+        else: map.additionalProperties
+      };
+    },
+    parse({ config, context }) {
+      const connections = normalizeConnectionConfig(
+        (config as { config?: { connections?: unknown } }).config?.connections
+      );
+      for (const [tag, connection] of Object.entries(connections)) {
+        if (connection?.type != 'example') continue;
+        context.parsedConfig.connectionConfig = { ...context.parsedConfig.connectionConfig, [tag]: connection };
+        const { plan } = context.parsedConfig as PrecompiledSyncConfig;
+        plan.moduleData = { ...plan.moduleData, ['example.tables']: null };
+      }
+      check(context.parsedConfig);
+    },
+    validatePersisted({ config }) {
+      check(config);
+    }
+  };
+}
+
+function deployOptions(yaml = CONFIGURED, parser = new SqlSyncConfigParser([additionalParser()])) {
+  return updateSyncRulesFromConfig(parser.parseContent(yaml, { defaultSchema: 'app' }));
+}
+
+describe('service sync config parser', () => {
+  test('reuses compiled validation until a parser is registered', () => {
+    const compile = vi.spyOn(syncRules, 'compileSyncRulesSchemaValidator');
+    try {
+      const parser = new SqlSyncConfigParser();
+      expect(compile).toHaveBeenCalledTimes(1);
+      for (let i = 0; i < 2; i++) {
+        expect(parser.parseContent(STREAMS, { defaultSchema: 'app' }).errors).toEqual([]);
+        expect(() => parser.parseContent(CONFIGURED, { defaultSchema: 'app' })).toThrow();
+      }
+      expect(compile).toHaveBeenCalledTimes(1);
+
+      parser.registerParser(additionalParser());
+      expect(compile).toHaveBeenCalledTimes(2);
+      for (let i = 0; i < 2; i++) {
+        expect(parser.parseContent(CONFIGURED, { defaultSchema: 'app' }).errors).toEqual([]);
+        expect(() =>
+          parser.parseContent(CONFIGURED.replace('sample: 10', 'sample: wrong'), { defaultSchema: 'app' })
+        ).toThrow();
+      }
+      expect(compile).toHaveBeenCalledTimes(2);
+    } finally {
+      compile.mockRestore();
+    }
+  });
+
+  test('composes generic registrations atomically and keeps returned schema copies isolated', () => {
+    const parser = new SqlSyncConfigParser();
+    const baseSchema = parser.jsonSchema;
+    expect(() => parser.parseContent(CONFIGURED, { defaultSchema: 'app' })).toThrow();
+    parser.registerParser(additionalParser());
+    expect(parser.parseContent(CONFIGURED, { defaultSchema: 'app' }).errors).toEqual([]);
+    expect(baseSchema).toEqual(new SqlSyncConfigParser().jsonSchema);
+    const composed = parser.jsonSchema;
+    delete (composed.properties as any).config.properties.connections;
+    expect(parser.parseContent(CONFIGURED, { defaultSchema: 'app' }).errors).toEqual([]);
+
+    expect(() => parser.registerParser(additionalParser())).toThrow('already registered');
+    expect(() => parser.registerParser({ id: '', parse() {} })).toThrow('must not be empty');
+    expect(() =>
+      parser.registerParser({
+        id: 'bad-schema',
+        parse() {},
+        extendJsonSchema({ schema }) {
+          schema.misspelledKeyword = true;
+        }
+      })
+    ).toThrow();
+    // The failed schema is not retained and its ID can be used by a corrected registration.
+    parser.registerParser({ id: 'bad-schema', parse() {} });
+    expect(parser.parseContent(CONFIGURED, { defaultSchema: 'app' }).errors).toEqual([]);
+  });
+
+  test('supplies one parser to storage and closes registration before asynchronous startup completes', async () => {
+    const context = new ServiceContextContainer({
+      serviceMode: ServiceContextMode.TEST_CONNECTION,
+      configuration: {
+        storage: { type: 'example' },
+        api_parameters: {
+          max_data_fetch_concurrency: 1,
+          max_buckets_per_connection: 1,
+          max_parameter_query_results: 1
+        }
+      } as never
+    });
+    const parser = context.syncConfigParser;
+    parser.registerParser(additionalParser());
+    let finish!: () => void;
+    const ready = new Promise<void>((resolve) => {
+      finish = resolve;
+    });
+    const getStorage = vi.fn(async () => {
+      await ready;
+      return { storage: {} as never, reportStorage: {} as never, shutDown: async () => {}, tearDown: async () => true };
+    });
+    context.storageEngine.registerProvider({ type: 'example', getStorage });
+    const startup = context.storageEngine.start();
+    try {
+      expect(() => parser.registerParser({ id: 'too-late', parse() {} })).toThrow(
+        'after the storage engine has started'
+      );
+      finish();
+      await startup;
+      expect(getStorage).toHaveBeenCalledWith({ resolvedConfig: context.configuration, syncConfigParser: parser });
+      expect(context.syncConfigParser).toBe(parser);
+    } finally {
+      finish();
+      await startup;
+      await context.storageEngine.shutDown();
+    }
+  });
+
+  test('requires recorded modules and semantic validation when restoring a saved plan', () => {
+    const parser = new SqlSyncConfigParser([additionalParser()]);
+    const compiled = deployOptions();
+    const restore = (syncConfigParser = parser, compiledPlan = compiled.config.plan) =>
+      parsePersistedSyncConfigContent({
+        content: CONFIGURED,
+        compiledPlan,
+        storageVersion: 2,
+        parseOptions: { defaultSchema: 'app' },
+        syncConfigParser
+      });
+    const restored = restore();
+    expect(restored.config.connectionConfig).toEqual(compiled.config.parsed.config.connectionConfig);
+    expect(
+      restored.config.hydrate({ hydrationState: DEFAULT_HYDRATION_STATE, sqlite: nodeSqlite(sqlite) }).connectionConfig
+    ).toEqual(restored.config.connectionConfig);
+    expect(() => restore(new SqlSyncConfigParser())).toThrow('Missing required sync config parsers: example.tables');
+    const malformed = structuredClone(compiled.config.plan!);
+    (malformed.plan.connectionConfig!.default!.tables!.orders as any).sample = 'wrong';
+    expect(() => restore(parser, malformed)).toThrow();
+    (malformed.plan.connectionConfig!.default!.tables!.orders as any).sample = 13;
+    expect(() => restore(parser, malformed)).toThrow('Sample 13');
+    // A compiled plan is authoritative; its failure must not be hidden by reparsing valid source YAML.
+    expect(() => restore(new SqlSyncConfigParser(), null)).toThrow();
+    expect(restore(parser, null).config.connectionConfig).toEqual(restored.config.connectionConfig);
+  });
+
+  test('checks all dependencies before hooks and ignores unused registered parsers', () => {
+    const validatePersisted = vi.fn();
+    const parser = new SqlSyncConfigParser([{ id: 'installed', parse() {}, validatePersisted }]);
+    const { config } = parser.parseContent(STREAMS, { defaultSchema: 'app' });
+    expect(parser.validatePersisted({ config, context: { defaultSchema: 'app' } })).toEqual([]);
+    expect(validatePersisted).not.toHaveBeenCalled();
+    (config as PrecompiledSyncConfig).plan.moduleData = { installed: null, missing: null, 'also-missing': null };
+    expect(() => parser.validatePersisted({ config, context: { defaultSchema: 'app' } })).toThrow(
+      'Missing required sync config parsers: missing, also-missing'
+    );
+    expect(validatePersisted).not.toHaveBeenCalled();
+  });
+
+  test('restores transformed module state without applying the authoring schema', () => {
+    const parser = new SqlSyncConfigParser([
+      {
+        id: 'transformed',
+        parse({ context }) {
+          const { plan } = context.parsedConfig as PrecompiledSyncConfig;
+          plan.moduleData = { ...plan.moduleData, ['transformed']: null };
+          context.parsedConfig.connectionConfig = {
+            default: { type: 'transformed', tables: { orders: { compiled: true } } }
+          };
+        }
+      }
+    ]);
+    const compiled = deployOptions(STREAMS, parser);
+    const restore = (syncConfigParser: SqlSyncConfigParser) =>
+      parsePersistedSyncConfigContent({
+        content: STREAMS,
+        compiledPlan: compiled.config.plan,
+        storageVersion: 2,
+        parseOptions: { defaultSchema: 'app' },
+        syncConfigParser
+      });
+    expect((restore(parser).config as PrecompiledSyncConfig).plan.moduleData).toEqual({ transformed: null });
+    expect(restore(parser).config.connectionConfig).toEqual(compiled.config.parsed.config.connectionConfig);
+    expect(() => restore(new SqlSyncConfigParser())).toThrow('Missing required sync config parsers: transformed');
+  });
+
+  test('persists module dependencies without connection options and accepts legacy plans without module data', () => {
+    const parser = new SqlSyncConfigParser([
+      {
+        id: 'required',
+        parse({ context }) {
+          const { plan } = context.parsedConfig as PrecompiledSyncConfig;
+          plan.moduleData = { ...plan.moduleData, ['required']: null };
+        }
+      }
+    ]);
+    const compiled = deployOptions(STREAMS, parser);
+    expect(compiled.config.plan!.plan.version).toBe(3);
+    expect(compiled.config.plan!.plan.moduleData).toEqual({ required: null });
+    const restore = (compiledPlan = compiled.config.plan) =>
+      parsePersistedSyncConfigContent({
+        content: STREAMS,
+        compiledPlan,
+        storageVersion: 2,
+        parseOptions: { defaultSchema: 'app' },
+        syncConfigParser: new SqlSyncConfigParser()
+      });
+    expect(() => restore()).toThrow('Missing required sync config parsers: required');
+    const malformed = structuredClone(compiled.config.plan!);
+    (malformed.plan as any).moduleData = 'required';
+    expect(() => restore(malformed)).toThrow('Invalid sync config module data');
+    const legacy = deployOptions(STREAMS, new SqlSyncConfigParser());
+    expect((restore(legacy.config.plan).config as PrecompiledSyncConfig).plan.moduleData).toBeUndefined();
+  });
+
+  test('runs generic persisted validators with context and retains their warnings', () => {
+    const hook: AdditionalSyncConfigParser = {
+      id: 'core-check',
+      parse({ context }) {
+        const { plan } = context.parsedConfig as PrecompiledSyncConfig;
+        plan.moduleData = { ...plan.moduleData, ['core-check']: null };
+      },
+      validatePersisted({ config, context }) {
+        expect(config.getSourceTables()[0].name).toBe('orders');
+        expect(context.defaultSchema).toBe('app');
+        context.reportDiagnostic({ level: 'warning', message: 'Review this configuration.' });
+      }
+    };
+    const parser = new SqlSyncConfigParser([hook]);
+    const parsed = parser.parseContent(STREAMS, { defaultSchema: 'app' });
+    expect(parser.validatePersisted({ config: parsed.config, context: { defaultSchema: 'app' } })).toEqual([
+      expect.objectContaining({ type: 'warning', message: 'Review this configuration.' })
+    ]);
+    hook.validatePersisted = ({ context }) => context.reportDiagnostic({ level: 'fatal', message: 'Rejected.' });
+    expect(() => parser.validatePersisted({ config: parsed.config, context: { defaultSchema: 'app' } })).toThrow(
+      'Rejected.'
+    );
+  });
+
+  test('reuses equal connection options but requires replacement for additions, changes and removals', () => {
+    const first = deployOptions();
+    const same = deployOptions(CONFIGURED.replace('SELECT * FROM orders', 'SELECT id FROM orders'));
+    const changed = deployOptions(CONFIGURED.replace('sample: 10', 'sample: 20'));
+    const absent = deployOptions(STREAMS);
+    expect(isCompatible([first.config.plan], same.config, logger)).toBe(true);
+    expect(isCompatible([first.config.plan], changed.config, logger)).toBe(false);
+    expect(isCompatible([first.config.plan], absent.config, logger)).toBe(false);
+    expect(isCompatible([absent.config.plan], first.config, logger)).toBe(false);
+  });
+
+  test('merges equal connection config once', () => {
+    const first = deployOptions().config.parsed.config;
+    const same = deployOptions(CONFIGURED.replace('SELECT * FROM orders', 'SELECT id FROM orders')).config.parsed
+      .config;
+    const hydrate = (definitions: SyncConfig[]) =>
+      new HydratedSyncConfig({
+        definitions,
+        createParams: { hydrationState: DEFAULT_HYDRATION_STATE, sqlite: nodeSqlite(sqlite) }
+      });
+    expect(hydrate([first, same]).connectionConfig).toEqual(first.connectionConfig);
+  });
+});