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

package/src/migrations/PowerSyncMigrationManager.ts

@@ -1,6 +1,7 @@
 import * as framework from '@powersync/lib-services-framework';
 import fs from 'fs/promises';
 import path from 'path';
+import { pathToFileURL } from 'url';
 import * as system from '../system/system-index.js';
 
 /**
@@ -28,7 +29,7 @@ export abstract class AbstractPowerSyncMigrationAgent extends framework.Abstract
 
     return await Promise.all(
       migrations.map(async (migration) => {
-        const module = await import(path.resolve(migrationsDir, migration));
+        const module = await import(pathToFileURL(path.resolve(migrationsDir, migration)).href);
         return {
           name: path.basename(migration).replace(path.extname(migration), ''),
           up: module.up,

package/src/replication/AbstractReplicator.ts

@@ -165,10 +165,14 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
         // versions before that check was added, so we keep the lock for now - for where te service version and sync config is updated at
         // the same time.
 
+        const parsed = this.options.storageEngine.activeBucketStorage.syncConfigParser.parseContent(loadedSyncConfig, {
+          schema: undefined,
+          defaultSchema: 'not_applicable',
+          throwOnError: this.syncRuleProvider.exitOnError
+        });
         const { lock } = await this.storage.configureSyncRules(
-          storage.updateSyncRulesFromYaml(loadedSyncConfig, {
+          storage.updateSyncRulesFromConfig(parsed, {
             lock: true,
-            validate: this.syncRuleProvider.exitOnError,
             version_label: versionLabel
           })
         );
@@ -182,7 +186,7 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
         throw e;
       }
     } else {
-      this.logger.info('No sync streams or rules configured - configure via API');
+      this.logger.info('No sync config configured - configure via API');
     }
     let useFastRefresh = true;
     const fastRefreshDeadline = Date.now() + FAST_REFRESH_TIMEOUT_MS;
@@ -290,7 +294,7 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
         } else {
           lock = await replicationStream.lock();
         }
-        const syncRuleStorage = this.storage.getInstance(replicationStream);
+        const syncRuleStorage = this.storage.getInstance(replicationStream, { replicationLock: lock });
         const newJob = this.createJob({
           lock: lock,
           storage: syncRuleStorage

package/src/replication/ReplicationModule.ts

@@ -63,14 +63,6 @@ export abstract class ReplicationModule<TConfig extends types.configFile.DataSou
    */
   protected abstract createReplicator(context: system.ServiceContext): AbstractReplicator;
 
-  /**
-   *  Any additional initialization specific to the module should be added here. Will be called if necessary after the
-   *  main initialization has been completed
-   *  @param context
-   *  @protected
-   */
-  protected abstract onInitialized(context: system.ServiceContext): Promise<void>;
-
   public abstract testConnection(config: TConfig): Promise<ConnectionTestResult>;
 
   /**
@@ -100,8 +92,6 @@ export abstract class ReplicationModule<TConfig extends types.configFile.DataSou
 
     context.replicationEngine?.register(this.createReplicator(context));
     context.routerEngine?.registerAPI(this.createRouteAPIAdapter());
-
-    await this.onInitialized(context);
   }
 
   protected decodeConfig(config: TConfig): void {

package/src/routes/endpoints/admin.ts

@@ -1,13 +1,7 @@
 import * as sqlite from 'node:sqlite';
 
 import { ErrorCode, errors, router, schema } from '@powersync/lib-services-framework';
-import {
-  HydratedSyncConfig,
-  nodeSqlite,
-  SourceSchema,
-  SqlSyncRules,
-  StaticSchema
-} from '@powersync/service-sync-rules';
+import { HydratedSyncConfig, nodeSqlite, SourceSchema, StaticSchema } from '@powersync/service-sync-rules';
 import { internal_routes } from '@powersync/service-types';
 
 import { DEFAULT_HYDRATION_STATE } from '@powersync/service-sync-rules';
@@ -158,14 +152,18 @@ export const reprocess = routeDefinition({
       });
     }
     // There are some differences between this and using asUpdateOptions():
-    // 1. This always re-parses the source YAML. If there are changes to the sync stream compiler, that can affect the sync plan.
+    // 1. This always re-parses the source YAML. If there are changes to the Sync Streams compiler, that can affect the sync plan.
     // 2. If the source does not set the storage version, this will update it do the current version.
     // We can consider tweaking this behavior in the future.
+    const parsed = service_context.syncConfigParser.parseContent(active.content.sync_rules_content, {
+      ...apiHandler.getParseSyncRulesOptions(),
+      schema: undefined,
+      // This sync config already passed validation. But if the config is not valid anymore due
+      // to a service change, we do want to report the error here.
+      throwOnError: true
+    });
     const new_rules = await activeBucketStorage.updateSyncRules(
-      storage.updateSyncRulesFromYaml(active.content.sync_rules_content, {
-        // This sync config already passed validation. But if the config is not valid anymore due
-        // to a service change, we do want to report the error here.
-        validate: true,
+      storage.updateSyncRulesFromConfig(parsed, {
         version_label: active.content.version_label,
         forceNewReplicationStream: true
       })
@@ -188,16 +186,16 @@ export const reprocess = routeDefinition({
 
 class FakeSyncRulesContentForValidation extends storage.PersistedSyncConfigContent {
   constructor(
-    private readonly apiHandler: api.RouteAPI,
+    private readonly validationParser: storage.SyncConfigParser,
     private readonly schema: SourceSchema,
     data: storage.PersistedSyncConfigContentData
   ) {
-    super(data);
+    super(data, validationParser);
   }
 
   parsed(options: storage.ParseSyncConfigOptions): storage.ParsedSyncConfigSet {
-    const syncConfig = SqlSyncRules.fromYaml(this.sync_rules_content, {
-      ...this.apiHandler.getParseSyncRulesOptions(),
+    const syncConfig = this.validationParser.parseContent(this.sync_rules_content, {
+      ...options,
       schema: this.schema
     });
 
@@ -237,7 +235,7 @@ export const validate = routeDefinition({
     const schemaData = await api.getConnectionsSchema(apiHandler);
     const schema = new StaticSchema(schemaData.connections);
 
-    const sync_rules = new FakeSyncRulesContentForValidation(apiHandler, schema, {
+    const sync_rules = new FakeSyncRulesContentForValidation(service_context.syncConfigParser, schema, {
       // Dummy values
       replicationStreamId: 0,
       replicationStreamName: '',

package/src/routes/endpoints/socket-route.ts

@@ -16,6 +16,10 @@ export const syncStreamReactive: SocketRouteGenerator = (router) =>
       const { routerEngine, metricsEngine, syncContext } = service_context;
       const streamStart = Date.now();
 
+      // Format client-controlled values before registering connection resources.
+      const formattedAppMetadata = params.app_metadata ? limitParamsForLogging(params.app_metadata) : undefined;
+      const formattedClientParams = params.parameters ? limitParamsForLogging(params.parameters) : undefined;
+
       logger.defaultMeta = {
         ...logger.defaultMeta,
         user_id: context.token_payload!.userIdJson,
@@ -99,13 +103,12 @@ export const syncStreamReactive: SocketRouteGenerator = (router) =>
         tracker.setCompressed(connection.tracker.encoding);
       }
 
-      const formattedAppMetadata = params.app_metadata ? limitParamsForLogging(params.app_metadata) : undefined;
-      logger.info('Sync stream started', {
-        app_metadata: formattedAppMetadata,
-        client_params: params.parameters ? limitParamsForLogging(params.parameters) : undefined
-      });
-
       try {
+        logger.info('Sync stream started', {
+          app_metadata: formattedAppMetadata,
+          client_params: formattedClientParams
+        });
+
         for await (const data of sync.streamResponse({
           syncContext: syncContext,
           bucketStorage: bucketStorage,

package/src/routes/endpoints/sync-rules.ts

@@ -1,10 +1,11 @@
 import { ErrorCode, errors, router, schema } from '@powersync/lib-services-framework';
-import { SqlSyncRules, SyncConfigWithErrors, SyncRulesErrors } from '@powersync/service-sync-rules';
+import { SyncConfigWithErrors, SyncRulesErrors } from '@powersync/service-sync-rules';
 import type { FastifyPluginAsync } from 'fastify';
 import * as t from 'ts-codec';
 
 import { RouteAPI } from '../../api/RouteAPI.js';
-import { updateSyncRulesFromConfig, updateSyncRulesFromYaml } from '../../storage/BucketStorageFactory.js';
+import { updateSyncRulesFromConfig } from '../../storage/BucketStorageFactory.js';
+import { SyncConfigParser } from '../../storage/SyncConfigParser.js';
 import { authApi } from '../auth.js';
 import { routeDefinition } from '../router.js';
 
@@ -56,7 +57,7 @@ export const deploySyncRules = routeDefinition({
 
     try {
       const apiHandler = service_context.routerEngine.getAPI();
-      syncConfig = SqlSyncRules.fromYaml(content, {
+      syncConfig = service_context.syncConfigParser.parseContent(content, {
         ...apiHandler.getParseSyncRulesOptions(),
         // We don't do any schema-level validation at this point
         schema: undefined
@@ -94,7 +95,7 @@ export const validateSyncRules = routeDefinition({
     const { service_context } = payload.context;
     const apiHandler = service_context.routerEngine.getAPI();
 
-    const info = await debugSyncRules(apiHandler, content);
+    const info = await debugSyncRules(apiHandler, content, service_context.syncConfigParser);
 
     return replyPrettyJson(info);
   }
@@ -121,10 +122,12 @@ export const currentSyncRules = routeDefinition({
 
     const sync_rules = active.content;
     const apiHandler = service_context.routerEngine.getAPI();
-    const info = await debugSyncRules(apiHandler, sync_rules.sync_rules_content);
+    const info = await debugSyncRules(apiHandler, sync_rules.sync_rules_content, service_context.syncConfigParser);
     const next = await activeBucketStorage.getDeployingSyncConfig();
 
-    const next_info = next ? await debugSyncRules(apiHandler, next.content.sync_rules_content) : null;
+    const next_info = next
+      ? await debugSyncRules(apiHandler, next.content.sync_rules_content, service_context.syncConfigParser)
+      : null;
 
     const response = {
       current: {
@@ -176,11 +179,15 @@ export const reprocessSyncRules = routeDefinition({
     }
 
     const sync_rules = active.content;
+    const parsed = payload.context.service_context.syncConfigParser.parseContent(sync_rules.sync_rules_content, {
+      ...payload.context.service_context.routerEngine.getAPI().getParseSyncRulesOptions(),
+      schema: undefined,
+      // This sync config already passed validation. But if the rules are not valid anymore due
+      // to a service change, we do want to report the error here.
+      throwOnError: true
+    });
     const new_rules = await activeBucketStorage.updateSyncRules(
-      updateSyncRulesFromYaml(sync_rules.sync_rules_content, {
-        // This sync config already passed validation. But if the rules are not valid anymore due
-        // to a service change, we do want to report the error here.
-        validate: true,
+      updateSyncRulesFromConfig(parsed, {
         version_label: sync_rules.version_label,
         forceNewReplicationStream: true
       })
@@ -201,9 +208,9 @@ function replyPrettyJson(payload: any) {
   });
 }
 
-async function debugSyncRules(apiHandler: RouteAPI, sync_rules: string) {
+async function debugSyncRules(apiHandler: RouteAPI, sync_rules: string, syncConfigParser: SyncConfigParser) {
   try {
-    const rules = SqlSyncRules.fromYaml(sync_rules, {
+    const rules = syncConfigParser.parseContent(sync_rules, {
       ...apiHandler.getParseSyncRulesOptions(),
       // No schema-based validation at this point
       schema: undefined

package/src/storage/BucketStorageFactory.ts

@@ -4,7 +4,6 @@ import {
   SerializedSyncPlan as RawSerializedSyncPlan,
   SerializedCompatibilityContext,
   serializeSyncPlan,
-  SqlSyncRules,
   SyncConfigWithErrors
 } from '@powersync/service-sync-rules';
 import { ReplicationError } from '@powersync/service-types';
@@ -14,8 +13,16 @@ import { PersistedSyncConfigContent } from './PersistedSyncConfigContent.js';
 import { ReplicationEventPayload } from './ReplicationEventPayload.js';
 import { ReplicationLock } from './ReplicationLock.js';
 import { ReportStorage } from './ReportStorage.js';
+import { SqlSyncConfigParser, SyncConfigParser } from './SyncConfigParser.js';
 import { SyncRulesBucketStorage } from './SyncRulesBucketStorage.js';
 
+export interface BucketStorageFactoryOptions {
+  /**
+   * Service-wide parser assembled before storage startup.
+   */
+  syncConfigParser: SyncConfigParser;
+}
+
 /**
  * Represents a configured storage provider.
  *
@@ -28,6 +35,16 @@ export abstract class BucketStorageFactory
   extends BaseObserver<BucketStorageFactoryListener>
   implements AsyncDisposable
 {
+  readonly syncConfigParser: SyncConfigParser;
+
+  /**
+   * Creates a storage factory using the service-wide parser assembled before storage startup.
+   */
+  constructor(options: BucketStorageFactoryOptions) {
+    super();
+    this.syncConfigParser = options.syncConfigParser;
+  }
+
   /**
    * Update sync config from configuration, if changed.
    */
@@ -117,10 +134,14 @@ export abstract class BucketStorageFactory
    */
   abstract getSystemIdentifier(): Promise<BucketStorageSystemIdentifier>;
 
-  abstract [Symbol.asyncDispose](): PromiseLike<void>;
+  async [Symbol.asyncDispose](): Promise<void> {
+    await this.iterateAsyncListeners(async (listener) => listener.beforeDispose?.());
+  }
 }
 
 export interface BucketStorageFactoryListener {
+  /** Release owned resources before the factory closes its database connections. */
+  beforeDispose: () => Promise<void>;
   syncStorageCreated: (storage: SyncRulesBucketStorage) => void;
   replicationEvent: (event: ReplicationEventPayload) => void;
 }
@@ -177,7 +198,7 @@ export interface UpdateSyncRulesOptions {
   config: {
     yaml: string;
     /**
-     * The serialized sync plan for the sync configuration, or `null` for configurations not using the sync stream
+     * The serialized sync plan for the sync configuration, or `null` for configurations not using the Sync Streams
      * compiler.
      */
     plan: SerializedSyncPlan | null;
@@ -223,14 +244,15 @@ export function updateSyncRulesFromYaml(
   content: string,
   options?: Omit<UpdateSyncRulesOptions, 'config'> & { validate?: boolean }
 ): UpdateSyncRulesOptions {
-  const config = SqlSyncRules.fromYaml(content, {
+  const { validate, ...updateOptions } = options ?? {};
+  const config = new SqlSyncConfigParser().parseContent(content, {
     // No schema-based validation at this point
     schema: undefined,
     defaultSchema: options?.defaultSchema ?? 'not_applicable', // Not needed for validation
-    throwOnError: options?.validate ?? false
+    throwOnError: validate ?? false
   });
 
-  return updateSyncRulesFromConfig(config, options);
+  return updateSyncRulesFromConfig(config, updateOptions);
 }
 
 export function updateSyncRulesFromConfig(
@@ -258,6 +280,11 @@ export function updateSyncRulesFromConfig(
 }
 
 export interface GetIntanceOptions {
+  /**
+   * The job lease, including a lease acquired during initial configuration.
+   * Required for writing; optional for reading.
+   */
+  replicationLock?: ReplicationLock;
   /**
    * Set to true to skip trigger any events for creating the instance.
    *

package/src/storage/PersistedReplicationStream.ts

@@ -2,9 +2,10 @@ import { logger as defaultLogger, ErrorCode, ServiceError } from '@powersync/lib
 import { Logger } from 'winston';
 import { SyncRuleState } from './BucketStorage.js';
 import type { ParsedSyncConfigSet } from './ParsedSyncConfigSet.js';
-import type { ParseSyncConfigOptions, PersistedSyncConfigContent } from './PersistedSyncConfigContent.js';
+import type { PersistedSyncConfigContent } from './PersistedSyncConfigContent.js';
 import { ReplicationLock } from './ReplicationLock.js';
 import { STORAGE_VERSION_CONFIG, StorageVersionConfig } from './StorageVersionConfig.js';
+import type { ParseSyncConfigOptions } from './SyncConfigParser.js';
 
 export abstract class PersistedReplicationStream implements PersistedReplicationStreamData {
   readonly replicationStreamId: number;

package/src/storage/PersistedSyncConfigContent.ts

@@ -10,7 +10,6 @@ import {
   HydrationState,
   nodeSqlite,
   PrecompiledSyncConfig,
-  SqlSyncRules,
   SyncConfigWithErrors,
   versionedHydrationState,
   YamlError
@@ -22,20 +21,22 @@ import { SerializedSyncPlan, UpdateSyncRulesOptions } from './BucketStorageFacto
 import { ParsedSyncConfigSet } from './ParsedSyncConfigSet.js';
 import { PersistedSyncConfigStatus } from './PersistedSyncConfigStatus.js';
 import { STORAGE_VERSION_CONFIG, StorageVersionConfig } from './StorageVersionConfig.js';
+import { ParseSyncConfigOptions, SyncConfigParser } from './SyncConfigParser.js';
 
 export interface ParsePersistedSyncConfigContentOptions {
   content: string;
   compiledPlan: SerializedSyncPlan | null;
   storageVersion: number;
   parseOptions: ParseSyncConfigOptions;
+  syncConfigParser: SyncConfigParser;
 }
 
 export function parsePersistedSyncConfigContent(options: ParsePersistedSyncConfigContentOptions): SyncConfigWithErrors {
-  const { content, compiledPlan, storageVersion, parseOptions } = options;
+  const { content, compiledPlan, storageVersion, parseOptions, syncConfigParser } = options;
 
   if (compiledPlan == null) {
     // Fallback: Only parse from YAML if no compiled plan is available.
-    return SqlSyncRules.fromYaml(content, parseOptions);
+    return syncConfigParser.parseContent(content, parseOptions);
   }
 
   const plan = deserializeSyncPlan(compiledPlan.plan);
@@ -69,6 +70,12 @@ export function parsePersistedSyncConfigContent(options: ParsePersistedSyncConfi
   // Note: If the original content did not define a storage version, this will still set the storage version.
   // This means asUpdateOptions will not change the storage version, even if the default changes.
   precompiled.storageVersion = storageVersion;
+  errors.push(
+    ...syncConfigParser.validatePersisted({
+      config: precompiled,
+      context: { defaultSchema: parseOptions.defaultSchema }
+    })
+  );
 
   if (compiledPlan.errors) {
     for (const error of compiledPlan.errors) {
@@ -105,7 +112,10 @@ export abstract class PersistedSyncConfigContent implements PersistedSyncConfigC
   readonly syncConfigState: SyncRuleState;
   readonly version_label: string | undefined;
 
-  constructor(data: PersistedSyncConfigContentData) {
+  constructor(
+    data: PersistedSyncConfigContentData,
+    private readonly syncConfigParser: SyncConfigParser
+  ) {
     this.replicationStreamId = data.replicationStreamId;
     this.sync_rules_content = data.sync_rules_content;
     this.compiled_plan = data.compiled_plan;
@@ -144,7 +154,8 @@ export abstract class PersistedSyncConfigContent implements PersistedSyncConfigC
       content: this.sync_rules_content,
       compiledPlan: this.compiled_plan,
       storageVersion: this.storageVersion,
-      parseOptions: options
+      parseOptions: options,
+      syncConfigParser: this.syncConfigParser
     });
   }
 
@@ -202,6 +213,3 @@ export interface PersistedSyncConfigContentData {
   readonly version_label?: string;
 }
 export type PersistedSyncConfigId = string;
-export interface ParseSyncConfigOptions {
-  defaultSchema: string;
-}

package/src/storage/StorageEngine.ts

@@ -2,9 +2,11 @@ import { BaseObserver, logger, ServiceError } from '@powersync/lib-services-fram
 import { ResolvedPowerSyncConfig } from '../util/util-index.js';
 import { BucketStorageFactory } from './BucketStorageFactory.js';
 import { ActiveStorage, StorageProvider } from './StorageProvider.js';
+import { SyncConfigParser } from './SyncConfigParser.js';
 
 export type StorageEngineOptions = {
   configuration: ResolvedPowerSyncConfig;
+  syncConfigParser: SyncConfigParser;
 };
 
 export interface StorageEngineListener {
@@ -15,6 +17,7 @@ export interface StorageEngineListener {
 export class StorageEngine extends BaseObserver<StorageEngineListener> {
   // TODO: This will need to revisited when we actually support multiple storage providers.
   private storageProviders: Map<string, StorageProvider> = new Map();
+  private startupStarted = false;
   private currentActiveStorage: ActiveStorage | null = null;
 
   constructor(private options: StorageEngineOptions) {
@@ -33,6 +36,10 @@ export class StorageEngine extends BaseObserver<StorageEngineListener> {
     return this.currentActiveStorage;
   }
 
+  get started(): boolean {
+    return this.startupStarted;
+  }
+
   /**
    * Register a provider which generates a {@link BucketStorageFactory}
    * given the matching config specified in the loaded {@link ResolvedPowerSyncConfig}
@@ -42,10 +49,12 @@ export class StorageEngine extends BaseObserver<StorageEngineListener> {
   }
 
   public async start(): Promise<void> {
+    this.startupStarted = true;
     logger.info('Starting Storage Engine...');
     const { configuration } = this.options;
     this.currentActiveStorage = await this.storageProviders.get(configuration.storage.type)!.getStorage({
-      resolvedConfig: configuration
+      resolvedConfig: configuration,
+      syncConfigParser: this.options.syncConfigParser
     });
     this.iterateListeners((cb) => cb.storageActivated?.(this.activeBucketStorage));
     this.currentActiveStorage.onFatalError?.((error) => {

package/src/storage/StorageProvider.ts

@@ -2,6 +2,7 @@ import { ServiceError } from '@powersync/lib-services-framework';
 import * as util from '../util/util-index.js';
 import { BucketStorageFactory } from './BucketStorageFactory.js';
 import { ReportStorage } from './ReportStorage.js';
+import { SyncConfigParser } from './SyncConfigParser.js';
 
 export interface ActiveStorage {
   storage: BucketStorageFactory;
@@ -19,6 +20,10 @@ export interface ActiveStorage {
 export interface GetStorageOptions {
   // TODO: This should just be the storage config. Update once the slot name prefix coupling has been removed from the storage
   resolvedConfig: util.ResolvedPowerSyncConfig;
+  /**
+   * Service-wide parser containing every extension registered during module initialization.
+   */
+  syncConfigParser: SyncConfigParser;
 }
 
 /**
@@ -31,5 +36,8 @@ export interface StorageProvider {
    */
   type: string;
 
+  /**
+   * Creates active storage during storage-engine startup using the fully assembled service parser.
+   */
   getStorage(options: GetStorageOptions): Promise<ActiveStorage>;
 }

package/src/storage/SyncConfigParser.ts

@@ -0,0 +1,121 @@
+import {
+  AdditionalSyncConfigParser,
+  compileSyncRulesSchemaValidator,
+  createSyncRulesSchema,
+  JsonObject,
+  PrecompiledSyncConfig,
+  SqlSyncRules,
+  SyncConfig,
+  SyncConfigDiagnostic,
+  SyncConfigWithErrors,
+  SyncRulesErrors,
+  SyncRulesOptions,
+  SyncRulesSchemaValidator,
+  validateAdditionalSyncConfigParsers,
+  YamlError
+} from '@powersync/service-sync-rules';
+
+export type ParseSyncConfigOptions = Omit<SyncRulesOptions, 'parsers' | 'schemaValidator'>;
+
+/**
+ * Shared by service routes, deployment, replication and persisted storage; only initialization can register hooks.
+ */
+export interface SyncConfigParser {
+  /**
+   * A JSON schema which can be used to validate the format of a supplied sync config.
+   */
+  readonly jsonSchema: JsonObject;
+
+  /**
+   * Parses string content.
+   *
+   * @returns The parsed {@link SyncConfigWithErrors}
+   */
+  parseContent(content: string, options: ParseSyncConfigOptions): SyncConfigWithErrors;
+
+  /**
+   * Validates a persisted/parsed sync config.
+   *
+   * @returns Any errors detected.
+   */
+  validatePersisted(options: { config: SyncConfig; context: { defaultSchema: string } }): YamlError[];
+}
+
+export class SqlSyncConfigParser implements SyncConfigParser {
+  readonly #parsers: AdditionalSyncConfigParser[];
+  #jsonSchema: JsonObject;
+  #schemaValidator: SyncRulesSchemaValidator;
+
+  constructor(parsers: readonly AdditionalSyncConfigParser[] = []) {
+    validateAdditionalSyncConfigParsers(parsers);
+    this.#parsers = [...parsers];
+    this.#jsonSchema = createSyncRulesSchema(parsers);
+    this.#schemaValidator = compileSyncRulesSchemaValidator(this.#jsonSchema);
+  }
+
+  get jsonSchema(): JsonObject {
+    // Tooling can customize its copy without changing validation for the running service.
+    return structuredClone(this.#jsonSchema);
+  }
+
+  /**
+   * Validate the candidate composition before mutating the registry.
+   */
+  registerParser(parser: AdditionalSyncConfigParser): void {
+    const parsers = [...this.#parsers, parser];
+    validateAdditionalSyncConfigParsers(parsers);
+    const schema = createSyncRulesSchema(parsers);
+    const validator = compileSyncRulesSchemaValidator(schema);
+    this.#parsers.push(parser);
+    this.#jsonSchema = schema;
+    this.#schemaValidator = validator;
+  }
+
+  parseContent(content: string, options: ParseSyncConfigOptions): SyncConfigWithErrors {
+    return SqlSyncRules.fromYaml(content, {
+      ...options,
+      parsers: this.#parsers,
+      schemaValidator: this.#schemaValidator
+    });
+  }
+
+  validatePersisted({ config, context }: { config: SyncConfig; context: { defaultSchema: string } }): YamlError[] {
+    /**
+     * Ensure that all modules which created a persisted SyncConfig
+     * are currently loaded.
+     * This prevents a case for a SyncConfig with missing external modules to be loaded.
+     */
+    const requiredIds = new Set(
+      config instanceof PrecompiledSyncConfig ? Object.keys(config.plan.moduleData ?? {}) : []
+    );
+    const registeredIds = new Set(this.#parsers.map((parser) => parser.id));
+    const missingIds = [...requiredIds].filter((id) => !registeredIds.has(id));
+    if (missingIds.length != 0) {
+      throw new Error(`Missing required sync config parsers: ${missingIds.join(', ')}`);
+    }
+
+    const errors: YamlError[] = [];
+    const reportDiagnostic = (diagnostic: SyncConfigDiagnostic) => {
+      const location = diagnostic.location;
+      const error = new YamlError(
+        new Error(diagnostic.message),
+        location && {
+          start: location.start_offset,
+          end: location.end_offset
+        }
+      );
+      error.type = diagnostic.level;
+      errors.push(error);
+    };
+
+    for (const parser of this.#parsers) {
+      if (!requiredIds.has(parser.id)) continue;
+      /**
+       * This allows additional validation of module specific semantics
+       */
+      parser.validatePersisted?.({ config, context: { ...context, reportDiagnostic } });
+    }
+    if (errors.some((error) => error.type == 'fatal')) throw new SyncRulesErrors(errors);
+    return errors;
+  }
+}

package/src/storage/SyncRulesBucketStorage.ts

@@ -11,11 +11,11 @@ import * as util from '../util/util-index.js';
 import { BucketStorageBatch, FlushedResult, SaveUpdate } from './BucketStorageBatch.js';
 import { BucketStorageFactory } from './BucketStorageFactory.js';
 import { ParsedSyncConfigSet } from './ParsedSyncConfigSet.js';
-import { ParseSyncConfigOptions } from './PersistedSyncConfigContent.js';
 import { SourceEntityDescriptor } from './SourceEntity.js';
 import { SourceTable } from './SourceTable.js';
 import { SourceTableCandidateReconciler } from './SourceTableReconciler.js';
 import { StorageVersionConfig } from './StorageVersionConfig.js';
+import { ParseSyncConfigOptions } from './SyncConfigParser.js';
 import { SyncStorageWriteCheckpointAPI } from './WriteCheckpointAPI.js';
 
 /**
@@ -402,6 +402,8 @@ export interface CompactOptions {
 }
 
 export interface CompactInitialReplicationOptions {
+  /** Internal/testing use: bypass the new-chunk threshold in MongoDB V3/V4 storage. */
+  forceChunkCompaction?: boolean;
   /**
    * Compact data up to this op id.
    *