@powersync/service-core 1.24.0 → 1.26.0

package/package.json

@@ -4,13 +4,14 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.24.0",
+  "version": "1.26.0",
   "license": "FSL-1.1-ALv2",
   "type": "module",
   "exports": "./dist/index.js",
   "dependencies": {
     "@js-sdsl/ordered-set": "^4.4.2",
     "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "^2.0.1",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.203.0",
     "@opentelemetry/exporter-prometheus": "^0.203.0",
     "@opentelemetry/resources": "^2.0.1",
@@ -32,11 +33,11 @@
     "uuid": "^14.0.0",
     "winston": "^3.13.0",
     "yaml": "^2.8.3",
-    "@powersync/lib-services-framework": "0.10.0",
     "@powersync/service-jsonbig": "0.17.13",
-    "@powersync/service-rsocket-router": "0.2.25",
-    "@powersync/service-sync-rules": "0.40.0",
-    "@powersync/service-types": "0.17.0"
+    "@powersync/service-rsocket-router": "0.2.26",
+    "@powersync/service-sync-rules": "0.41.0",
+    "@powersync/lib-services-framework": "0.10.1",
+    "@powersync/service-types": "0.18.0"
   },
   "devDependencies": {
     "@types/async": "^3.2.24",

package/src/api/diagnostics.ts

@@ -65,6 +65,7 @@ export async function getSyncRulesStatus(
     parsed = singleConfig;
   } catch (e) {
     return {
+      version_label: syncConfig.version_label,
       content: include_content ? syncConfig.sync_rules_content : undefined,
       connections: [],
       errors: [{ level: 'fatal', message: e.message, ts: now }]
@@ -221,6 +222,7 @@ export async function getSyncRulesStatus(
   }
 
   return {
+    version_label: syncConfig.version_label,
     content: include_content ? syncConfig.sync_rules_content : undefined,
     connections: [
       {

package/src/entry/commands/compact-action.ts

@@ -28,7 +28,11 @@ export function registerCompactAction(program: Command) {
     .command(COMMAND_NAME)
     .option(`-b, --buckets [buckets]`, 'Full bucket names, comma-separated (e.g., "global[],mybucket[\\"user1\\"]")')
     .option('-p, --parameter-indexes', 'Compacting parameter indexes. Defaults to set unless --buckets is provided.')
-    .option('--no-parameter-indexes', 'Disabling compacting parameter indexes.');
+    .option('--no-parameter-indexes', 'Disabling compacting parameter indexes.')
+    .option(
+      '--incremental-only',
+      '[EXPERIMENTAL] Perform incremental compacting only. Parameter compaction runs on supported storage versions.'
+    );
 
   wrapConfigCommand(compactCommand);
 
@@ -48,8 +52,9 @@ export function registerCompactAction(program: Command) {
       }
     }
 
-    let compactParameters: boolean | null = options.parameterIndexes;
+    const incremental: boolean = options.incrementalOnly ?? false;
 
+    let compactParameters: boolean | null = options.parameterIndexes;
     if (buckets == null) {
       logger.info('Compacting storage for all buckets...');
     } else if (buckets.length == 0) {
@@ -87,29 +92,32 @@ export function registerCompactAction(program: Command) {
         Date.now() - config.api_parameters.checkpoint_request_retention_minutes * MINUTE_MS
       );
 
-      const active = (await bucketStorage.getActiveSyncConfig())?.storage;
-      if (active == null) {
-        logger.info('No active instance to compact');
-        return;
-      }
-      if (buckets != null) {
-        logger.info('Performing compaction...');
-        await active.compact({
-          memoryLimitMB: COMPACT_MEMORY_LIMIT_MB,
-          compactBuckets: buckets,
-          compactParameterData: compactParameters ?? false,
-          deleteCheckpointRequestsBefore,
-          signal: abortController.signal
-        });
-      } else {
-        await active.compact({
-          memoryLimitMB: COMPACT_MEMORY_LIMIT_MB,
-          compactParameterData: compactParameters ?? true,
-          deleteCheckpointRequestsBefore,
-          signal: abortController.signal
-        });
+      const streams = await bucketStorage.getReplicatingReplicationStreams();
+      for (let stream of streams) {
+        const storage = bucketStorage.getInstance(stream);
+        const compactParameterData =
+          (compactParameters ?? buckets == null) && (!incremental || storage.supportsIncrementalParameterCompaction());
+        logger.info(`[${stream.replicationStreamName}] Performing compaction...`);
+        if (buckets != null) {
+          await storage.compact({
+            memoryLimitMB: COMPACT_MEMORY_LIMIT_MB,
+            compactBuckets: buckets,
+            compactParameterData,
+            incrementalOnly: incremental,
+            deleteCheckpointRequestsBefore,
+            signal: abortController.signal
+          });
+        } else {
+          await storage.compact({
+            memoryLimitMB: COMPACT_MEMORY_LIMIT_MB,
+            compactParameterData,
+            incrementalOnly: incremental,
+            deleteCheckpointRequestsBefore,
+            signal: abortController.signal
+          });
+        }
+        logger.info(`[${stream.replicationStreamName}] Successfully compacted storage.`);
       }
-      logger.info('Successfully compacted storage.');
     } catch (e) {
       logger.error(`Failed to compact:`, e);
       // Indirectly triggers lifeCycleEngine.stop

package/src/metrics/metrics-interfaces.ts

@@ -19,7 +19,12 @@ export interface ObservableGauge {
    *  Set a value provider that provides the value for the gauge at the time of observation.
    *  @param valueProvider
    */
-  setValueProvider(valueProvider: () => Promise<number | undefined>): void;
+  setValueProvider(valueProvider: () => Promise<number | ObservableGaugeObservation[] | undefined>): void;
+}
+
+export interface ObservableGaugeObservation {
+  value: number;
+  attributes?: Record<string, string>;
 }
 
 export enum Precision {

package/src/metrics/open-telemetry/MetricAttributeFilteringExporter.ts

@@ -0,0 +1,85 @@
+import { Attributes } from '@opentelemetry/api';
+import { ExportResult } from '@opentelemetry/core';
+import {
+  AggregationSelector,
+  AggregationTemporalitySelector,
+  DataPoint,
+  DataPointType,
+  MetricData,
+  PushMetricExporter,
+  ResourceMetrics
+} from '@opentelemetry/sdk-metrics';
+
+/**
+ * Decorates a push exporter and removes selected attributes from every metric data point before
+ * delegating the export. The input metrics are not mutated, so another reader can export the
+ * original attributes.
+ *
+ * This exporter deliberately does not merge data points when filtering makes their attribute sets
+ * identical. Both points are forwarded with the same attributes. There is no generally correct
+ * merge operation at this layer: gauges, counters, and histograms have different aggregation
+ * semantics. Callers must therefore ensure that an excluded attribute does not distinguish data
+ * points for the same metric, resource, and instrumentation scope. Otherwise, the resulting
+ * duplicate series identity may be rejected or interpreted unpredictably downstream.
+ *
+ * Lifecycle methods and aggregation selection are delegated unchanged to the wrapped exporter.
+ */
+export class MetricAttributeFilteringExporter implements PushMetricExporter {
+  readonly selectAggregation?: AggregationSelector;
+  readonly selectAggregationTemporality?: AggregationTemporalitySelector;
+
+  constructor(
+    /** The exporter that receives the filtered copy of the metrics. */
+    private readonly delegate: PushMetricExporter,
+    /** Attribute names to remove from every exported data point. */
+    private readonly excludedAttributes: ReadonlySet<string>
+  ) {
+    this.selectAggregation = delegate.selectAggregation?.bind(delegate);
+    this.selectAggregationTemporality = delegate.selectAggregationTemporality?.bind(delegate);
+  }
+
+  export(metrics: ResourceMetrics, resultCallback: (result: ExportResult) => void): void {
+    this.delegate.export(this.filterAttributes(metrics), resultCallback);
+  }
+
+  forceFlush(): Promise<void> {
+    return this.delegate.forceFlush();
+  }
+
+  shutdown(): Promise<void> {
+    return this.delegate.shutdown();
+  }
+
+  private filterAttributes(metrics: ResourceMetrics): ResourceMetrics {
+    return {
+      ...metrics,
+      scopeMetrics: metrics.scopeMetrics.map((scopeMetrics) => ({
+        ...scopeMetrics,
+        metrics: scopeMetrics.metrics.map((metric) => this.filterMetricAttributes(metric))
+      }))
+    };
+  }
+
+  private filterMetricAttributes(metric: MetricData): MetricData {
+    switch (metric.dataPointType) {
+      case DataPointType.SUM:
+      case DataPointType.GAUGE:
+        return { ...metric, dataPoints: metric.dataPoints.map((dataPoint) => this.filterDataPoint(dataPoint)) };
+      case DataPointType.HISTOGRAM:
+        return { ...metric, dataPoints: metric.dataPoints.map((dataPoint) => this.filterDataPoint(dataPoint)) };
+      case DataPointType.EXPONENTIAL_HISTOGRAM:
+        return { ...metric, dataPoints: metric.dataPoints.map((dataPoint) => this.filterDataPoint(dataPoint)) };
+    }
+  }
+
+  private filterDataPoint<T>(dataPoint: DataPoint<T>): DataPoint<T> {
+    return {
+      ...dataPoint,
+      attributes: this.filterDataPointAttributes(dataPoint.attributes)
+    };
+  }
+
+  private filterDataPointAttributes(attributes: Attributes): Attributes {
+    return Object.fromEntries(Object.entries(attributes).filter(([name]) => !this.excludedAttributes.has(name)));
+  }
+}

package/src/metrics/open-telemetry/OpenTelemetryMetricsFactory.ts

@@ -4,6 +4,7 @@ import {
   MetricMetadata,
   MetricsFactory,
   ObservableGauge,
+  ObservableGaugeObservation,
   Precision,
   UpDownCounter
 } from '../metrics-interfaces.js';
@@ -31,12 +32,16 @@ export class OpenTelemetryMetricsFactory implements MetricsFactory {
     });
 
     return {
-      setValueProvider(valueProvider: () => Promise<number | undefined>) {
+      setValueProvider(valueProvider: () => Promise<number | ObservableGaugeObservation[] | undefined>) {
         gauge.addCallback(async (result) => {
           const value = await valueProvider();
 
-          if (value != undefined) {
+          if (typeof value === 'number') {
             result.observe(value);
+          } else if (value != undefined) {
+            for (const observation of value) {
+              result.observe(observation.value, observation.attributes);
+            }
           }
         });
       }

package/src/metrics/open-telemetry/util.ts

@@ -4,6 +4,7 @@ import { MeterProvider, MetricReader, PeriodicExportingMetricReader } from '@ope
 import { logger } from '@powersync/lib-services-framework';
 import { ServiceContext } from '../../system/ServiceContext.js';
 import { MetricsFactory } from '../metrics-interfaces.js';
+import { MetricAttributeFilteringExporter } from './MetricAttributeFilteringExporter.js';
 import { OpenTelemetryMetricsFactory } from './OpenTelemetryMetricsFactory.js';
 
 import { resourceFromAttributes } from '@opentelemetry/resources';
@@ -29,10 +30,13 @@ export function createOpenTelemetryMetricsFactory(context: ServiceContext): Metr
   }
 
   if (!configuration.telemetry.disable_telemetry_sharing) {
+    const otlpExporter = new OTLPMetricExporter({
+      url: configuration.telemetry.internal_service_endpoint
+    });
     const periodicExporter = new PeriodicExportingMetricReader({
-      exporter: new OTLPMetricExporter({
-        url: configuration.telemetry.internal_service_endpoint
-      }),
+      // sync_config_id uniquely identifies these metric series after version_label is removed,
+      // so filtering cannot create duplicate data points.
+      exporter: new MetricAttributeFilteringExporter(otlpExporter, new Set(['version_label'])),
       exportIntervalMillis: 1000 * 60 * 5 // 5 minutes
     });
 

package/src/replication/AbstractReplicator.ts

@@ -156,7 +156,8 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
 
     let configuredLock: storage.ReplicationLock | undefined = undefined;
     if (loadedSyncConfig != null) {
-      this.logger.info('Loaded sync config');
+      const versionLabel = this.syncRuleProvider.versionLabel;
+      this.logger.info(`Loaded sync config${versionLabel == null ? '' : ` ${versionLabel}`}`);
       try {
         // Configure new sync config, if they have changed.
         // In that case, also immediately take out a lock, so that another process doesn't start replication on it.
@@ -165,7 +166,11 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
         // the same time.
 
         const { lock } = await this.storage.configureSyncRules(
-          storage.updateSyncRulesFromYaml(loadedSyncConfig, { lock: true, validate: this.syncRuleProvider.exitOnError })
+          storage.updateSyncRulesFromYaml(loadedSyncConfig, {
+            lock: true,
+            validate: this.syncRuleProvider.exitOnError,
+            version_label: versionLabel
+          })
         );
         if (lock) {
           configuredLock = lock;
@@ -184,7 +189,11 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
     while (!this.stopped) {
       await container.probes.touch();
       try {
-        const refreshResult = await this.refresh({ configuredLock, loadedSyncConfig });
+        const refreshResult = await this.refresh({
+          configuredLock,
+          loadedSyncConfig,
+          loadedVersionLabel: this.syncRuleProvider.versionLabel
+        });
         if (refreshResult.replicationJobStarted || Date.now() >= fastRefreshDeadline) {
           useFastRefresh = false;
         }
@@ -216,6 +225,7 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
   private async refresh(options?: {
     configuredLock?: storage.ReplicationLock;
     loadedSyncConfig?: string;
+    loadedVersionLabel?: string;
   }): Promise<{ replicationJobStarted: boolean }> {
     if (this.stopped) {
       return { replicationJobStarted: false };
@@ -233,7 +243,9 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
       const jobId = replicationStream.replicationJobId;
       const existingJob = existingJobs.get(jobId);
       const syncConfigMismatchMessage = 'Ignoring replication stream for sync config not loaded by this process';
-      if (!this.shouldHandleReplicationStream(replicationStream, options?.loadedSyncConfig)) {
+      if (
+        !this.shouldHandleReplicationStream(replicationStream, options?.loadedSyncConfig, options?.loadedVersionLabel)
+      ) {
         this.logReplicationStreamInfoOnce(replicationStream, 'sync-config-mismatch', () => {
           replicationStream.logger.info(syncConfigMismatchMessage);
         });
@@ -371,7 +383,8 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
    */
   private shouldHandleReplicationStream(
     replicationStream: storage.PersistedReplicationStream,
-    loadedSyncRules: string | undefined
+    loadedSyncRules: string | undefined,
+    loadedVersionLabel: string | undefined
   ) {
     if (loadedSyncRules == null) {
       return true;
@@ -380,7 +393,10 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
     const processingConfig = replicationStream.syncConfigContent.find(
       (syncConfig) => syncConfig.syncConfigState == storage.SyncRuleState.PROCESSING
     );
-    return processingConfig == null || processingConfig.sync_rules_content == loadedSyncRules;
+    return (
+      processingConfig == null ||
+      (processingConfig.sync_rules_content == loadedSyncRules && processingConfig.version_label == loadedVersionLabel)
+    );
   }
 
   protected createJobId(syncRuleId: number) {

package/src/routes/endpoints/admin.ts

@@ -165,7 +165,9 @@ export const reprocess = routeDefinition({
       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
+        validate: true,
+        version_label: active.content.version_label,
+        forceNewReplicationStream: true
       })
     );
 

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

@@ -180,7 +180,9 @@ export const reprocessSyncRules = routeDefinition({
       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
+        validate: true,
+        version_label: sync_rules.version_label,
+        forceNewReplicationStream: true
       })
     );
     return {

package/src/storage/BucketStorageBatch.ts

@@ -176,7 +176,8 @@ export interface BucketStorageBatch extends ObserverClient<BucketBatchStorageLis
    * Queue a custom checkpoint request to be persisted after operations are
    * flushed. Set `checkpoint_requested_at` when the custom checkpoint came from
    * a client checkpoint request and should be cleaned up by request-retention
-   * compaction; omit it for persistent source-owned checkpoints.
+   * compaction; omit it for persistent source-owned checkpoints. Incremental
+   * event handlers should copy `event_id` from their {@link ReplicationEventPayload}.
    */
   addCustomWriteCheckpoint(checkpoint: BatchedCustomWriteCheckpointOptions): void;
 }

package/src/storage/BucketStorageFactory.ts

@@ -37,10 +37,17 @@ export abstract class BucketStorageFactory
     const deploying = await this.getDeployingSyncConfig();
     const active = await this.getActiveSyncConfig();
 
-    if (deploying?.content.sync_rules_content == options.config.yaml) {
+    if (
+      deploying?.content.sync_rules_content == options.config.yaml &&
+      deploying.content.version_label == options.version_label
+    ) {
       logger.info('Sync config unchanged');
       return { updated: false };
-    } else if (deploying == null && active?.content.sync_rules_content == options.config.yaml) {
+    } else if (
+      deploying == null &&
+      active?.content.sync_rules_content == options.config.yaml &&
+      active.content.version_label == options.version_label
+    ) {
       logger.info('Sync config unchanged');
       return { updated: false };
     } else {
@@ -141,9 +148,32 @@ export interface StorageMetrics {
    * Size of current_data.
    */
   replication_size_bytes: number;
+
+  /**
+   * Size of active object-storage references, such as S3 bucket-data objects.
+   */
+  object_storage_size_bytes?: number;
+
+  /**
+   * Per-sync-config storage sizes, when the storage backend can provide them.
+   */
+  sync_config_metrics?: StorageSyncConfigMetrics[];
+}
+
+export interface StorageSyncConfigMetrics {
+  sync_config_id: string;
+  sync_config_state: string;
+  /** Optional operator-supplied label identifying this sync config version. */
+  version_label?: string;
+  attributed_bucket_data_bytes: number;
+  attributed_parameter_indexes_bytes: number;
+  attributed_source_records_bytes: number;
+  attributed_object_storage_bytes: number;
 }
 
 export interface UpdateSyncRulesOptions {
+  /** Optional operator-supplied label identifying this deployed sync config version. */
+  version_label?: string;
   config: {
     yaml: string;
     /**
@@ -161,6 +191,12 @@ export interface UpdateSyncRulesOptions {
   lock?: boolean;
   storageVersion?: number;
 
+  /**
+   * Start a replacement replication stream instead of incrementally reprocessing a
+   * compatible active stream. Used when the current stream needs a full reprocess.
+   */
+  forceNewReplicationStream?: boolean;
+
   /**
    * Only relevant if the result is used. This does not affect the persisted config.
    */
@@ -174,11 +210,10 @@ export interface SerializedSyncPlan {
   plan: RawSerializedSyncPlan;
   compatibility: SerializedCompatibilityContext;
   /**
-   * Event descriptors are not currently represented in the sync plan because they don't use the sync streams compiler
-   * yet.
+   * Raw event SQL persisted as a compatibility mirror for compiled {@link plan} events.
    *
-   * We might revisit that in the future, but for now we store SQL text of their definitions here to be able to restore
-   * them.
+   * Compiled events are an additive plan field. Older services ignore that field and restore these descriptors through
+   * the legacy evaluator. Keep dual-writing this field until a future plan version explicitly removes that support.
    */
   eventDescriptors: Record<string, string[]>;
   errors?: ReplicationError[];
@@ -206,13 +241,14 @@ export function updateSyncRulesFromConfig(
   const { config, errors } = parsed;
   if (config instanceof PrecompiledSyncConfig) {
     const eventDescriptors: Record<string, string[]> = {};
-    for (const event of config.eventDescriptors) {
-      eventDescriptors[event.name] = event.sourceQueries.map((q) => q.sql);
+    for (const event of config.plan.events) {
+      eventDescriptors[event.name] = event.sourceQueries.map((query) => query.sql);
     }
 
     plan = {
       compatibility: config.compatibility.serialize(),
       plan: serializeSyncPlan(config.plan),
+      // Dual-write raw SQL so older services can ignore additive compiled plan events without losing event behavior.
       eventDescriptors,
       errors: errors.map((e) => syncConfigYamlErrorToReplicationError(e))
     };

package/src/storage/PersistedSyncConfigContent.ts

@@ -2,6 +2,7 @@ import { logger as defaultLogger, ErrorCode, ServiceError } from '@powersync/lib
 import {
   CompatibilityContext,
   CompatibilityOption,
+  compileEventDefinitions,
   DEFAULT_HYDRATION_STATE,
   deserializeSyncPlan,
   ErrorLocation,
@@ -9,7 +10,6 @@ import {
   HydrationState,
   nodeSqlite,
   PrecompiledSyncConfig,
-  SqlEventDescriptor,
   SqlSyncRules,
   SyncConfigWithErrors,
   versionedHydrationState,
@@ -40,17 +40,28 @@ export function parsePersistedSyncConfigContent(options: ParsePersistedSyncConfi
 
   const plan = deserializeSyncPlan(compiledPlan.plan);
   const compatibility = CompatibilityContext.deserialize(compiledPlan.compatibility);
-  const eventDefinitions: SqlEventDescriptor[] = [];
-  for (const [name, queries] of Object.entries(compiledPlan.eventDescriptors)) {
-    const descriptor = new SqlEventDescriptor(name, compatibility);
-    for (const query of queries) {
-      descriptor.addSourceQuery(query, parseOptions);
+  const errors: YamlError[] = [];
+  // Compiled events are additive to plan versions 1 and 2. New readers prefer them when present; when an older plan
+  // does not contain them, normalize the dual-written raw SQL at this loading boundary. This keeps legacy event
+  // evaluators out of PrecompiledSyncConfig while older binaries can continue reading the same persisted config.
+  if (compiledPlan.plan.events == null) {
+    const normalized = compileEventDefinitions(compiledPlan.eventDescriptors, {
+      ...parseOptions,
+      // The legacy evaluator ignored event payload filters. Preserve that behavior for plans deployed before compiled
+      // events existed; a redeploy compiles and validates those filters before the replacement config is activated.
+      compileEventPayloadFilters: false
+    });
+    const fatalErrors = normalized.errors.filter((error) => error.type == 'fatal');
+    if (fatalErrors.length != 0) {
+      throw new Error(
+        `Failed to compile persisted replication events: ${fatalErrors.map((error) => error.message).join(', ')}`
+      );
     }
-
-    eventDefinitions.push(descriptor);
+    plan.events = normalized.events;
+    errors.push(...normalized.errors.map((error) => new YamlError(error)));
   }
 
-  const precompiled = new PrecompiledSyncConfig(plan, compatibility, eventDefinitions, {
+  const precompiled = new PrecompiledSyncConfig(plan, compatibility, {
     defaultSchema: parseOptions.defaultSchema,
     sourceText: content
   });
@@ -59,7 +70,6 @@ export function parsePersistedSyncConfigContent(options: ParsePersistedSyncConfi
   // This means asUpdateOptions will not change the storage version, even if the default changes.
   precompiled.storageVersion = storageVersion;
 
-  const errors: YamlError[] = [];
   if (compiledPlan.errors) {
     for (const error of compiledPlan.errors) {
       const location: ErrorLocation | undefined = error.location && {
@@ -93,6 +103,7 @@ export abstract class PersistedSyncConfigContent implements PersistedSyncConfigC
   readonly logger: Logger;
   readonly syncConfigId: PersistedSyncConfigId | null;
   readonly syncConfigState: SyncRuleState;
+  readonly version_label: string | undefined;
 
   constructor(data: PersistedSyncConfigContentData) {
     this.replicationStreamId = data.replicationStreamId;
@@ -102,7 +113,9 @@ export abstract class PersistedSyncConfigContent implements PersistedSyncConfigC
     this.storageVersion = data.storageVersion;
     this.syncConfigId = data.syncConfigId ?? null;
     this.syncConfigState = data.syncConfigState;
-    this.logger = defaultLogger.child({ prefix: `[${this.replicationStreamName}] ` });
+    this.version_label = data.version_label;
+    const versionPrefix = this.version_label == null ? '' : `[${this.version_label}]`;
+    this.logger = defaultLogger.child({ prefix: `[${this.replicationStreamName}]${versionPrefix} ` });
   }
 
   /**
@@ -167,6 +180,7 @@ export abstract class PersistedSyncConfigContent implements PersistedSyncConfigC
     const parsed = this.parseSingleConfig({ defaultSchema: 'not_applicable' });
     return {
       config: { yaml: this.sync_rules_content, plan: this.compiled_plan, parsed },
+      version_label: this.version_label,
       ...options
     };
   }
@@ -185,6 +199,7 @@ export interface PersistedSyncConfigContentData {
 
   readonly syncConfigId?: PersistedSyncConfigId | null;
   readonly syncConfigState: SyncRuleState;
+  readonly version_label?: string;
 }
 export type PersistedSyncConfigId = string;
 export interface ParseSyncConfigOptions {

package/src/storage/ReplicationEventPayload.ts

@@ -11,6 +11,11 @@ export type EventData = {
 export type ReplicationEventPayload = {
   batch: BucketStorageBatch;
   data: EventData;
-  event: sync_rules.SqlEventDescriptor;
+  event: sync_rules.HydratedEventDescriptor;
+  /**
+   * Storage-assigned id for this event definition. Present when storage uses persisted event mappings, allowing event
+   * handlers to route custom checkpoints without deriving an id from compiled event content.
+   */
+  event_id?: sync_rules.EventDefinitionId;
   table: SourceTable;
 };

package/src/storage/SourceEntity.ts

@@ -1,5 +1,11 @@
 import { SourceTableRef } from '@powersync/service-sync-rules';
 
+/**
+ * Source-specific JSON metadata. Storage does not interpret it. Source-table APIs use null to
+ * represent the absence of metadata.
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
 export interface ColumnDescriptor {
   name: string;
   /**
@@ -19,8 +25,6 @@ export interface SourceEntityDescriptor extends SourceTableRef {
    * If specified, this is specifically used to detect renames.
    */
   objectId: number | string | undefined;
-  schema: string;
-  name: string;
   /**
    *  The columns that are used to uniquely identify a record in the source entity.
    */