@powersync/service-core 0.0.0-dev-20260203155513 → 0.0.0-dev-20260223080959

package/src/routes/configure-fastify.ts

@@ -61,7 +61,6 @@ export function configureFastifyServer(server: fastify.FastifyInstance, options:
 
   const generateContext: ContextProvider = async (request, options) => {
     return {
-      user_id: undefined,
       service_context: service_context,
       logger: options.logger
     };

package/src/routes/endpoints/admin.ts

@@ -1,12 +1,16 @@
 import { ErrorCode, errors, router, schema } from '@powersync/lib-services-framework';
-import { SqlSyncRules, StaticSchema } from '@powersync/service-sync-rules';
+import { SourceSchema, SqlSyncRules, StaticSchema } from '@powersync/service-sync-rules';
 import { internal_routes } from '@powersync/service-types';
 
+import { DEFAULT_HYDRATION_STATE } from '@powersync/service-sync-rules';
 import * as api from '../../api/api-index.js';
 import * as storage from '../../storage/storage-index.js';
 import { authApi } from '../auth.js';
 import { routeDefinition } from '../router.js';
 
+/**
+ * @deprecated This will be removed in a future release
+ */
 export const executeSql = routeDefinition({
   path: '/api/admin/v1/execute-sql',
   method: router.HTTPMethod.POST,
@@ -127,12 +131,13 @@ export const reprocess = routeDefinition({
       });
     }
 
-    const new_rules = await activeBucketStorage.updateSyncRules({
-      content: active.sync_rules.content,
-      // These sync rules 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
-    });
+    const new_rules = await activeBucketStorage.updateSyncRules(
+      storage.updateSyncRulesFromYaml(active.sync_rules.config.content, {
+        // These sync rules 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
+      })
+    );
 
     const baseConfig = await apiHandler.getSourceConfig();
 
@@ -149,6 +154,35 @@ export const reprocess = routeDefinition({
   }
 });
 
+class FakeSyncRulesContentForValidation extends storage.PersistedSyncRulesContent {
+  constructor(
+    private readonly apiHandler: api.RouteAPI,
+    private readonly schema: SourceSchema,
+    data: storage.PersistedSyncRulesContentData
+  ) {
+    super(data);
+  }
+
+  current_lock: storage.ReplicationLock | null = null;
+
+  async lock(): Promise<storage.ReplicationLock> {
+    throw new Error('Lock not implemented');
+  }
+
+  parsed(options: storage.ParseSyncRulesOptions): storage.PersistedSyncRules {
+    return {
+      ...this,
+      sync_rules: SqlSyncRules.fromYaml(this.sync_rules_content, {
+        ...this.apiHandler.getParseSyncRulesOptions(),
+        schema: this.schema
+      }),
+      hydratedSyncRules() {
+        return this.sync_rules.config.hydrate({ hydrationState: DEFAULT_HYDRATION_STATE });
+      }
+    };
+  }
+}
+
 export const validate = routeDefinition({
   path: '/api/admin/v1/validate',
   method: router.HTTPMethod.POST,
@@ -164,30 +198,15 @@ export const validate = routeDefinition({
     const schemaData = await api.getConnectionsSchema(apiHandler);
     const schema = new StaticSchema(schemaData.connections);
 
-    const sync_rules: storage.PersistedSyncRulesContent = {
+    const sync_rules = new FakeSyncRulesContentForValidation(apiHandler, schema, {
       // Dummy values
       id: 0,
       slot_name: '',
       active: false,
       last_checkpoint_lsn: '',
-
-      parsed() {
-        return {
-          ...this,
-          sync_rules: SqlSyncRules.fromYaml(content, {
-            ...apiHandler.getParseSyncRulesOptions(),
-            schema
-          }),
-          hydratedSyncRules() {
-            return this.sync_rules.hydrate();
-          }
-        };
-      },
-      sync_rules_content: content,
-      async lock() {
-        throw new Error('Lock not implemented');
-      }
-    };
+      storageVersion: storage.LEGACY_STORAGE_VERSION,
+      sync_rules_content: content
+    });
 
     const connectionStatus = await apiHandler.getConnectionStatus();
     if (!connectionStatus) {

package/src/routes/endpoints/checkpointing.ts

@@ -52,18 +52,20 @@ export const writeCheckpoint2 = routeDefinition({
   authorize: authUser,
   validator: schema.createTsCodecValidator(WriteCheckpointRequest, { allowAdditional: true }),
   handler: async (payload) => {
-    const { user_id, service_context } = payload.context;
+    const { token_payload, service_context } = payload.context;
 
     const apiHandler = service_context.routerEngine.getAPI();
 
     const { replicationHead, writeCheckpoint } = await util.createWriteCheckpoint({
-      userId: user_id,
+      userId: token_payload!.userIdString,
       clientId: payload.params.client_id,
       api: apiHandler,
       storage: service_context.storageEngine.activeBucketStorage
     });
 
-    logger.info(`Write checkpoint for ${user_id}/${payload.params.client_id}: ${writeCheckpoint} | ${replicationHead}`);
+    logger.info(
+      `Write checkpoint for ${token_payload!.userIdString}/${payload.params.client_id}: ${writeCheckpoint} | ${replicationHead}`
+    );
 
     return {
       write_checkpoint: String(writeCheckpoint)

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

@@ -18,19 +18,18 @@ export const syncStreamReactive: SocketRouteGenerator = (router) =>
 
       logger.defaultMeta = {
         ...logger.defaultMeta,
-        user_id: context.token_payload?.sub,
+        user_id: context.token_payload!.userIdJson,
         client_id: params.client_id,
         user_agent: context.user_agent
       };
 
       const sdkData: event_types.ConnectedUserData & event_types.ClientConnectionEventData = {
         client_id: params.client_id ?? '',
-        user_id: context.user_id!,
+        user_id: context.token_payload!.userIdString,
         user_agent: context.user_agent,
         // At this point the token_payload is guaranteed to be present
         jwt_exp: new Date(context.token_payload!.exp * 1000),
-        connected_at: new Date(streamStart),
-        app_metadata: params.app_metadata
+        connected_at: new Date(streamStart)
       };
 
       // Best effort guess on why the stream was closed.
@@ -122,12 +121,7 @@ export const syncStreamReactive: SocketRouteGenerator = (router) =>
           tracker,
           signal,
           logger,
-          isEncodingAsBson: true,
-          event: {
-            engine: service_context.eventsEngine,
-            user_id: sdkData.user_id,
-            client_id: sdkData.client_id
-          }
+          isEncodingAsBson: true
         })) {
           if (signal.aborted) {
             break;
@@ -138,7 +132,6 @@ export const syncStreamReactive: SocketRouteGenerator = (router) =>
 
           {
             const serialized = sync.syncLineToBson(data);
-
             responder.onNext({ data: serialized }, false);
             requestedN--;
             tracker.addPlaintextDataSynced(serialized.length);

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

@@ -1,11 +1,12 @@
 import { ErrorCode, errors, router, schema } from '@powersync/lib-services-framework';
-import { SqlSyncRules, SyncRulesErrors } from '@powersync/service-sync-rules';
+import { SqlSyncRules, 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 { authApi } from '../auth.js';
 import { routeDefinition } from '../router.js';
+import { updateSyncRulesFromConfig, updateSyncRulesFromYaml } from '../../storage/BucketStorageFactory.js';
 
 const DeploySyncRulesRequest = t.object({
   content: t.string
@@ -51,10 +52,11 @@ export const deploySyncRules = routeDefinition({
       });
     }
     const content = payload.params.content;
+    let syncConfig: SyncConfigWithErrors;
 
     try {
       const apiHandler = service_context.routerEngine.getAPI();
-      SqlSyncRules.fromYaml(payload.params.content, {
+      syncConfig = SqlSyncRules.fromYaml(payload.params.content, {
         ...apiHandler.getParseSyncRulesOptions(),
         // We don't do any schema-level validation at this point
         schema: undefined
@@ -68,11 +70,9 @@ export const deploySyncRules = routeDefinition({
       });
     }
 
-    const sync_rules = await storageEngine.activeBucketStorage.updateSyncRules({
-      content: content,
-      // Aready validated above
-      validate: false
-    });
+    const sync_rules = await storageEngine.activeBucketStorage.updateSyncRules(
+      updateSyncRulesFromConfig(syncConfig.config)
+    );
 
     return {
       slot_name: sync_rules.slot_name
@@ -168,12 +168,13 @@ export const reprocessSyncRules = routeDefinition({
       });
     }
 
-    const new_rules = await activeBucketStorage.updateSyncRules({
-      content: sync_rules.sync_rules.content,
-      // These sync rules 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
-    });
+    const new_rules = await activeBucketStorage.updateSyncRules(
+      updateSyncRulesFromYaml(sync_rules.sync_rules.config.content, {
+        // These sync rules 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
+      })
+    );
     return {
       slot_name: new_rules.slot_name
     };
@@ -197,14 +198,14 @@ async function debugSyncRules(apiHandler: RouteAPI, sync_rules: string) {
       // No schema-based validation at this point
       schema: undefined
     });
-    const source_table_patterns = rules.getSourceTables();
-    const resolved_tables = await apiHandler.getDebugTablesInfo(source_table_patterns, rules);
+    const source_table_patterns = rules.config.getSourceTables();
+    const resolved_tables = await apiHandler.getDebugTablesInfo(source_table_patterns, rules.config);
 
     return {
       valid: true,
-      bucket_definitions: rules.debugRepresentation(),
+      bucket_definitions: rules.config.debugRepresentation(),
       source_tables: resolved_tables,
-      data_tables: rules.debugGetOutputTables()
+      data_tables: rules.config.debugGetOutputTables()
     };
   } catch (e) {
     if (e instanceof SyncRulesErrors) {

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

@@ -42,12 +42,12 @@ export const syncStreamed = routeDefinition({
       ...logger.defaultMeta,
       user_agent: userAgent,
       client_id: clientId,
-      user_id: payload.context.user_id,
+      user_id: payload.context.token_payload!.userIdJson,
       bson: useBson
     };
     const sdkData: event_types.ConnectedUserData & event_types.ClientConnectionEventData = {
       client_id: clientId ?? '',
-      user_id: payload.context.user_id!,
+      user_id: payload.context.token_payload!.userIdString,
       user_agent: userAgent as string,
       // At this point the token_payload is guaranteed to be present
       jwt_exp: new Date(token_payload!.exp * 1000),
@@ -98,12 +98,7 @@ export const syncStreamed = routeDefinition({
         tracker,
         signal: controller.signal,
         logger,
-        isEncodingAsBson: useBson,
-        event: {
-          engine: service_context.eventsEngine,
-          user_id: sdkData.user_id,
-          client_id: sdkData.client_id
-        }
+        isEncodingAsBson: useBson
       });
 
       const byteContents = useBson ? sync.bsonLines(syncLines) : sync.ndjson(syncLines);
@@ -142,6 +137,7 @@ export const syncStreamed = routeDefinition({
           logger.error('Streaming sync request failed', error);
         }
       });
+
       return new router.RouterResponse({
         status: 200,
         headers: {

package/src/routes/router.ts

@@ -12,8 +12,6 @@ export type RouterServiceContext = ServiceContext;
  * Common context for routes
  */
 export type Context = {
-  user_id?: string;
-
   service_context: RouterServiceContext;
 
   token_payload?: JwtPayload;

package/src/storage/BucketStorageFactory.ts

@@ -1,9 +1,10 @@
-import { ObserverClient } from '@powersync/lib-services-framework';
+import { BaseObserver, logger } from '@powersync/lib-services-framework';
 import { ParseSyncRulesOptions, PersistedSyncRules, PersistedSyncRulesContent } from './PersistedSyncRulesContent.js';
 import { ReplicationEventPayload } from './ReplicationEventPayload.js';
 import { ReplicationLock } from './ReplicationLock.js';
 import { SyncRulesBucketStorage } from './SyncRulesBucketStorage.js';
 import { ReportStorage } from './ReportStorage.js';
+import { SqlSyncRules, SyncConfig } from '@powersync/service-sync-rules';
 
 /**
  * Represents a configured storage provider.
@@ -13,23 +14,41 @@ import { ReportStorage } from './ReportStorage.js';
  *
  * Storage APIs for a specific copy of sync rules are provided by the `SyncRulesBucketStorage` instances.
  */
-export interface BucketStorageFactory extends ObserverClient<BucketStorageFactoryListener>, AsyncDisposable {
+export abstract class BucketStorageFactory
+  extends BaseObserver<BucketStorageFactoryListener>
+  implements AsyncDisposable
+{
   /**
    * Update sync rules from configuration, if changed.
    */
-  configureSyncRules(
+  async configureSyncRules(
     options: UpdateSyncRulesOptions
-  ): Promise<{ updated: boolean; persisted_sync_rules?: PersistedSyncRulesContent; lock?: ReplicationLock }>;
+  ): Promise<{ updated: boolean; persisted_sync_rules?: PersistedSyncRulesContent; lock?: ReplicationLock }> {
+    const next = await this.getNextSyncRulesContent();
+    const active = await this.getActiveSyncRulesContent();
+
+    if (next?.sync_rules_content == options.config.yaml) {
+      logger.info('Sync rules from configuration unchanged');
+      return { updated: false };
+    } else if (next == null && active?.sync_rules_content == options.config.yaml) {
+      logger.info('Sync rules from configuration unchanged');
+      return { updated: false };
+    } else {
+      logger.info('Sync rules updated from configuration');
+      const persisted_sync_rules = await this.updateSyncRules(options);
+      return { updated: true, persisted_sync_rules, lock: persisted_sync_rules.current_lock ?? undefined };
+    }
+  }
 
   /**
    * Get a storage instance to query sync data for specific sync rules.
    */
-  getInstance(syncRules: PersistedSyncRulesContent, options?: GetIntanceOptions): SyncRulesBucketStorage;
+  abstract getInstance(syncRules: PersistedSyncRulesContent, options?: GetIntanceOptions): SyncRulesBucketStorage;
 
   /**
    * Deploy new sync rules.
    */
-  updateSyncRules(options: UpdateSyncRulesOptions): Promise<PersistedSyncRulesContent>;
+  abstract updateSyncRules(options: UpdateSyncRulesOptions): Promise<PersistedSyncRulesContent>;
 
   /**
    * Indicate that a slot was removed, and we should re-sync by creating
@@ -41,57 +60,65 @@ export interface BucketStorageFactory extends ObserverClient<BucketStorageFactor
    *
    * Replication should be restarted after this.
    */
-  restartReplication(sync_rules_group_id: number): Promise<void>;
+  abstract restartReplication(sync_rules_group_id: number): Promise<void>;
 
   /**
    * Get the sync rules used for querying.
    */
-  getActiveSyncRules(options: ParseSyncRulesOptions): Promise<PersistedSyncRules | null>;
+  async getActiveSyncRules(options: ParseSyncRulesOptions): Promise<PersistedSyncRules | null> {
+    const content = await this.getActiveSyncRulesContent();
+    return content?.parsed(options) ?? null;
+  }
 
   /**
    * Get the sync rules used for querying.
    */
-  getActiveSyncRulesContent(): Promise<PersistedSyncRulesContent | null>;
+  abstract getActiveSyncRulesContent(): Promise<PersistedSyncRulesContent | null>;
 
   /**
    * Get the sync rules that will be active next once done with initial replicatino.
    */
-  getNextSyncRules(options: ParseSyncRulesOptions): Promise<PersistedSyncRules | null>;
+  async getNextSyncRules(options: ParseSyncRulesOptions): Promise<PersistedSyncRules | null> {
+    const content = await this.getNextSyncRulesContent();
+    return content?.parsed(options) ?? null;
+  }
 
   /**
    * Get the sync rules that will be active next once done with initial replicatino.
    */
-  getNextSyncRulesContent(): Promise<PersistedSyncRulesContent | null>;
+  abstract getNextSyncRulesContent(): Promise<PersistedSyncRulesContent | null>;
 
   /**
    * Get all sync rules currently replicating. Typically this is the "active" and "next" sync rules.
    */
-  getReplicatingSyncRules(): Promise<PersistedSyncRulesContent[]>;
+  abstract getReplicatingSyncRules(): Promise<PersistedSyncRulesContent[]>;
 
   /**
    * Get all sync rules stopped but not terminated yet.
    */
-  getStoppedSyncRules(): Promise<PersistedSyncRulesContent[]>;
+  abstract getStoppedSyncRules(): Promise<PersistedSyncRulesContent[]>;
 
   /**
    * Get the active storage instance.
    */
-  getActiveStorage(): Promise<SyncRulesBucketStorage | null>;
+  abstract getActiveStorage(): Promise<SyncRulesBucketStorage | null>;
 
   /**
    * Get storage size of active sync rules.
    */
-  getStorageMetrics(): Promise<StorageMetrics>;
+  abstract getStorageMetrics(): Promise<StorageMetrics>;
 
   /**
    * Get the unique identifier for this instance of Powersync
    */
-  getPowerSyncInstanceId(): Promise<string>;
+  abstract getPowerSyncInstanceId(): Promise<string>;
 
   /**
    * Get a unique identifier for the system used for storage.
    */
-  getSystemIdentifier(): Promise<BucketStorageSystemIdentifier>;
+  abstract getSystemIdentifier(): Promise<BucketStorageSystemIdentifier>;
+
+  abstract [Symbol.asyncDispose](): PromiseLike<void>;
 }
 
 export interface BucketStorageFactoryListener {
@@ -119,9 +146,30 @@ export interface StorageMetrics {
 }
 
 export interface UpdateSyncRulesOptions {
-  content: string;
+  config: {
+    yaml: string;
+    // TODO: Add serialized sync plan if available
+  };
   lock?: boolean;
-  validate?: boolean;
+  storageVersion?: number;
+}
+
+export function updateSyncRulesFromYaml(
+  content: string,
+  options?: Omit<UpdateSyncRulesOptions, 'config'> & { validate?: boolean }
+): UpdateSyncRulesOptions {
+  const { config } = SqlSyncRules.fromYaml(content, {
+    // No schema-based validation at this point
+    schema: undefined,
+    defaultSchema: 'not_applicable', // Not needed for validation
+    throwOnError: options?.validate ?? false
+  });
+
+  return updateSyncRulesFromConfig(config, options);
+}
+
+export function updateSyncRulesFromConfig(parsed: SyncConfig, options?: Omit<UpdateSyncRulesOptions, 'config'>) {
+  return { config: { yaml: parsed.content }, ...options };
 }
 
 export interface GetIntanceOptions {

package/src/storage/PersistedSyncRulesContent.ts

@@ -1,11 +1,22 @@
-import { SqlSyncRules, HydratedSyncRules } from '@powersync/service-sync-rules';
+import {
+  CompatibilityOption,
+  DEFAULT_HYDRATION_STATE,
+  HydratedSyncRules,
+  HydrationState,
+  SqlSyncRules,
+  SyncConfigWithErrors,
+  versionedHydrationState
+} from '@powersync/service-sync-rules';
 import { ReplicationLock } from './ReplicationLock.js';
+import { STORAGE_VERSION_CONFIG, StorageVersionConfig } from './StorageVersionConfig.js';
+import { ErrorCode, ServiceError } from '@powersync/lib-services-framework';
+import { UpdateSyncRulesOptions } from './BucketStorageFactory.js';
 
 export interface ParseSyncRulesOptions {
   defaultSchema: string;
 }
 
-export interface PersistedSyncRulesContent {
+export interface PersistedSyncRulesContentData {
   readonly id: number;
   readonly sync_rules_content: string;
   readonly slot_name: string;
@@ -13,6 +24,7 @@ export interface PersistedSyncRulesContent {
    * True if this is the "active" copy of the sync rules.
    */
   readonly active: boolean;
+  readonly storageVersion: number;
 
   readonly last_checkpoint_lsn: string | null;
 
@@ -20,15 +32,80 @@ export interface PersistedSyncRulesContent {
   readonly last_fatal_error_ts?: Date | null;
   readonly last_keepalive_ts?: Date | null;
   readonly last_checkpoint_ts?: Date | null;
+}
+
+export abstract class PersistedSyncRulesContent implements PersistedSyncRulesContentData {
+  readonly id!: number;
+  readonly sync_rules_content!: string;
+  readonly slot_name!: string;
+  readonly active!: boolean;
+  readonly storageVersion!: number;
+
+  readonly last_checkpoint_lsn!: string | null;
+
+  readonly last_fatal_error?: string | null;
+  readonly last_fatal_error_ts?: Date | null;
+  readonly last_keepalive_ts?: Date | null;
+  readonly last_checkpoint_ts?: Date | null;
+
+  abstract readonly current_lock: ReplicationLock | null;
+
+  constructor(data: PersistedSyncRulesContentData) {
+    Object.assign(this, data);
+  }
+
+  /**
+   * Load the storage config.
+   *
+   * This may throw if the persisted storage version is not supported.
+   */
+  getStorageConfig(): StorageVersionConfig {
+    const storageConfig = STORAGE_VERSION_CONFIG[this.storageVersion];
+    if (storageConfig == null) {
+      throw new ServiceError(
+        ErrorCode.PSYNC_S1005,
+        `Unsupported storage version ${this.storageVersion} for sync rules ${this.id}`
+      );
+    }
+    return storageConfig;
+  }
+
+  parsed(options: ParseSyncRulesOptions): PersistedSyncRules {
+    let hydrationState: HydrationState;
+    const syncRules = SqlSyncRules.fromYaml(this.sync_rules_content, options);
+    const storageConfig = this.getStorageConfig();
+    if (
+      storageConfig.versionedBuckets ||
+      syncRules.config.compatibility.isEnabled(CompatibilityOption.versionedBucketIds)
+    ) {
+      hydrationState = versionedHydrationState(this.id);
+    } else {
+      hydrationState = DEFAULT_HYDRATION_STATE;
+    }
+
+    return {
+      id: this.id,
+      slot_name: this.slot_name,
+      sync_rules: syncRules,
+      hydratedSyncRules: () => {
+        return syncRules.config.hydrate({ hydrationState });
+      }
+    };
+  }
 
-  parsed(options: ParseSyncRulesOptions): PersistedSyncRules;
+  asUpdateOptions(options?: Omit<UpdateSyncRulesOptions, 'config'>): UpdateSyncRulesOptions {
+    return {
+      config: { yaml: this.sync_rules_content },
+      ...options
+    };
+  }
 
-  lock(): Promise<ReplicationLock>;
+  abstract lock(): Promise<ReplicationLock>;
 }
 
 export interface PersistedSyncRules {
   readonly id: number;
-  readonly sync_rules: SqlSyncRules;
+  readonly sync_rules: SyncConfigWithErrors;
   readonly slot_name: string;
 
   hydratedSyncRules(): HydratedSyncRules;

package/src/storage/ReportStorage.ts

@@ -28,7 +28,9 @@ export interface ReportStorage extends AsyncDisposable {
    * Usually this is call on the start of the new day, week or month. It will return all unique completed connections
    * as well as uniques currently connected clients.
    */
-  getClientConnectionReports(data: event_types.DateRange): Promise<event_types.ClientConnectionReportResponse>;
+  getClientConnectionReports(
+    data: event_types.ClientConnectionReportRequest
+  ): Promise<event_types.ClientConnectionReportResponse>;
   /**
    * Get a paginated list of client connection events
    * This will return a paginated list of connections for a client/ user ID or all if neither is provided, within a date range if provided
@@ -41,12 +43,4 @@ export interface ReportStorage extends AsyncDisposable {
    * This is used to clean up old connection data that is no longer needed.
    */
   deleteOldConnectionData(data: event_types.DeleteOldConnectionData): Promise<void>;
-
-  /**
-   * Report a sync analytics.
-   */
-  reportSyncAnalyticsEvent(data: event_types.SyncAnalyticsEventData): Promise<void>;
-  getSyncCheckpoint(data: event_types.SyncCheckpointRequest): Promise<event_types.PaginatedResponse<any>>;
-  getSyncBucketStats(data: event_types.SyncBucketStatsRequest): Promise<any>;
-  getLastSyncReport(data: event_types.LastSyncRequest): Promise<any>;
 }

package/src/storage/StorageVersionConfig.ts

@@ -0,0 +1,30 @@
+export interface StorageVersionConfig {
+  /**
+   * Whether versioned bucket names are automatically enabled.
+   *
+   * If this is false, bucket names may still be versioned depending on the sync config.
+   */
+  versionedBuckets: boolean;
+}
+
+/**
+ * Oldest supported storage version.
+ */
+export const LEGACY_STORAGE_VERSION = 1;
+
+/**
+ * Default storage version for newly persisted sync rules.
+ */
+export const CURRENT_STORAGE_VERSION = 2;
+
+/**
+ * Shared storage-version behavior across storage implementations.
+ */
+export const STORAGE_VERSION_CONFIG: Record<number, StorageVersionConfig | undefined> = {
+  [LEGACY_STORAGE_VERSION]: {
+    versionedBuckets: false
+  },
+  [CURRENT_STORAGE_VERSION]: {
+    versionedBuckets: true
+  }
+};

package/src/storage/SyncRulesBucketStorage.ts

@@ -218,10 +218,19 @@ export interface CompactOptions {
   moveBatchQueryLimit?: number;
 
   /**
+   * Minimum number new operations in a bucket to trigger compaction of that bucket.
+   *
    * Minimum of 1, default of 10.
    */
   minBucketChanges?: number;
 
+  /**
+   * Minimum ratio of new operations to existing operations in a bucket to trigger compaction of that bucket.
+   *
+   * Number between 0 and 1, default of 0.1.
+   */
+  minChangeRatio?: number;
+
   /**
    * Internal/testing use: Cache size for compacting parameters.
    */

package/src/storage/storage-index.ts

@@ -14,3 +14,4 @@ export * from './SyncRulesBucketStorage.js';
 export * from './PersistedSyncRulesContent.js';
 export * from './ReplicationLock.js';
 export * from './ReportStorage.js';
+export * from './StorageVersionConfig.js';