@powersync/service-core 1.25.0 → 1.26.1

package/src/sync/sync.ts

@@ -119,9 +119,14 @@ async function* streamResponseInner(
     syncRequest: params,
     logger: logger
   });
+  // The checkpoint iterator can have a pending next() while a data batch fails.
+  // Aborting this on cleanup makes that pending next() settle, so the watcher subscription
+  // is released instead of staying open until another checkpoint arrives. See the cleanup
+  // in the finally block below.
+  const checkpointWatchController = new AbortController();
   const stream = bucketStorage.watchCheckpointChanges({
     user_id: checkpointUserId,
-    signal
+    signal: AbortSignal.any([signal, checkpointWatchController.signal])
   });
   const newCheckpoints = stream[Symbol.asyncIterator]();
 
@@ -170,6 +175,16 @@ async function* streamResponseInner(
     }
   }
 
+  function checkpointLogDetails(cp: storage.ReplicationCheckpoint) {
+    return {
+      checkpoint: cp.checkpoint,
+      user_id: tokenPayload.userIdJson,
+      ...tracker.getIncrementalCheckpointStats()
+    };
+  }
+
+  let activeCheckpoint: { checkpoint: storage.ReplicationCheckpoint; trace: ActiveCheckpointTrace } | null = null;
+
   try {
     let nextCheckpointPromise: Promise<PromiseSettledResult<IteratorResult<CheckpointAndLine>>> | undefined;
 
@@ -195,6 +210,7 @@ async function* streamResponseInner(
       const trace = next.value.value.trace!;
       const checkpoint = next.value.value.checkpoint;
       const tracer = trace.tracer;
+      activeCheckpoint = { checkpoint, trace };
 
       const { checkpointLine, bucketsToFetch, bucketDataRequestHint } = line;
 
@@ -266,14 +282,6 @@ async function* streamResponseInner(
         maybeRaceForNewCheckpoint();
       }
 
-      function checkpointLogDetails(cp: storage.ReplicationCheckpoint) {
-        return {
-          checkpoint: cp.checkpoint,
-          user_id: tokenPayload.userIdJson,
-          ...tracker.getIncrementalCheckpointStats()
-        };
-      }
-
       // This incrementally updates dataBuckets with each individual bucket position.
       // At the end of this, we can be sure that all buckets have data up to the checkpoint.
       for (const [priority, buckets] of priorityBatches) {
@@ -328,13 +336,34 @@ async function* streamResponseInner(
           ms: getCheckpointTraceTimings(trace.span)
         });
       }
+      if (checkpointResult != null) {
+        activeCheckpoint = null;
+      }
 
       if (!abortCheckpointSignal.aborted) {
         await new Promise((resolve) => setTimeout(resolve, 10));
       }
     } while (!signal.aborted);
   } finally {
-    await newCheckpoints.return?.();
+    if (activeCheckpoint != null) {
+      const { checkpoint, trace } = activeCheckpoint;
+      logger.info(`checkpoint_interrupted: ${checkpoint.checkpoint}`, {
+        ...checkpointLogDetails(checkpoint),
+        ms: getCheckpointTraceTimings(trace.span)
+      });
+    }
+
+    // The abort makes a pending next() settle as soon as the storage watcher observes it,
+    // releasing the subscription. return() is still needed for the case where there is no
+    // pending next(): the watcher is then suspended at a yield and never observes the abort.
+    // Neither is awaited: async generators queue return() behind a pending next(), so
+    // awaiting it here would keep the connection open until the next checkpoint arrives.
+    checkpointWatchController.abort();
+    newCheckpoints.return?.().catch((e) => {
+      if (!isAbortError(e)) {
+        logger.warn('Error while closing the checkpoint watcher', e);
+      }
+    });
   }
 }
 
@@ -437,7 +466,6 @@ async function* bucketDataBatch(
   } = request;
 
   const tracer = request.tracer;
-
   let checkpointInvalidated = false;
 
   const acquired = await tracer.span('acquiring_lock').with(async () => {
@@ -456,6 +484,7 @@ async function* bucketDataBatch(
     const filteredBuckets = checkpointLine.getFilteredBucketPositions(bucketsToFetch);
     const dataBatches = storage.getBucketDataBatch(checkpoint, filteredBuckets, {
       requestHint,
+      tracer,
       // Checkpoint supersession is a cooperative batch handoff. Only abort
       // in-flight storage work when the connection itself is closed.
       signal: abort_connection

package/src/sync/util.ts

@@ -144,9 +144,19 @@ 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.
+    if (abort.aborted) {
+      resolve('aborted');
+      return;
+    }
+
     let aborted = false;
     let hasSemaphore = false;
 
@@ -159,16 +169,22 @@ export function acquireSemaphoreAbortable(
     };
     abort.addEventListener('abort', listener);
 
-    semaphone.acquire().then((acquired) => {
-      hasSemaphore = true;
-      if (aborted) {
-        // Release semaphore, already aborted
-        acquired[1]();
-      } else {
+    semaphone.acquire().then(
+      (acquired) => {
+        hasSemaphore = true;
+        if (aborted) {
+          // Release semaphore, already aborted
+          acquired[1]();
+        } else {
+          abort.removeEventListener('abort', listener);
+          resolve(acquired);
+        }
+      },
+      (error) => {
         abort.removeEventListener('abort', listener);
-        resolve(acquired);
+        reject(error);
       }
-    }, reject);
+    );
   });
 }
 

package/src/util/config/compound-config-collector.ts

@@ -1,4 +1,5 @@
 import { logger, LookupOptions } from '@powersync/lib-services-framework';
+import { validateStorageVersion } from '@powersync/service-sync-rules';
 import { configFile } from '@powersync/service-types';
 import * as auth from '../../auth/auth-index.js';
 import { ConfigCollector } from './collectors/config-collector.js';
@@ -62,6 +63,11 @@ export class CompoundConfigCollector {
   async collectConfig(runnerConfig: RunnerConfig = {}): Promise<ResolvedPowerSyncConfig> {
     const baseConfig = await this.collectBaseConfig(runnerConfig);
 
+    const defaultStorageVersion = baseConfig.storage?.default_storage_version;
+    if (defaultStorageVersion != null && validateStorageVersion(defaultStorageVersion) == null) {
+      throw new Error(`Storage version ${defaultStorageVersion} is not supported`);
+    }
+
     const dataSources = baseConfig.replication?.connections ?? [];
     if (dataSources.length > 1) {
       throw new Error('Only a single replication data source is supported currently');

package/src/util/config/sync-rules/impl/base64-sync-rules-collector.ts

@@ -15,6 +15,7 @@ export class Base64SyncRulesCollector extends SyncRulesCollector {
 
     return {
       present: true,
+      version_label: baseConfig.sync_config?.version_label,
       exit_on_error: baseConfig.sync_config?.exit_on_error ?? true,
       content: Buffer.from(sync_config_base64, 'base64').toString()
     };

package/src/util/config/sync-rules/impl/filesystem-sync-rules-collector.ts

@@ -20,6 +20,7 @@ export class FileSystemSyncRulesCollector extends SyncRulesCollector {
     // Only persist the path here, and load on demand using `loadSyncRules()`.
     return {
       present: true,
+      version_label: baseConfig.sync_config?.version_label,
       exit_on_error: baseConfig.sync_config?.exit_on_error ?? true,
       path: config_path ? path.resolve(path.dirname(config_path), sync_path) : sync_path
     };

package/src/util/config/sync-rules/sync-rules-provider.ts

@@ -5,6 +5,7 @@ export interface SyncRulesProvider {
   get(): Promise<string | undefined>;
 
   readonly exitOnError: boolean;
+  readonly versionLabel: string | undefined;
 }
 
 export class ConfigurationFileSyncRulesProvider implements SyncRulesProvider {
@@ -21,4 +22,8 @@ export class ConfigurationFileSyncRulesProvider implements SyncRulesProvider {
   get exitOnError() {
     return this.config.exit_on_error;
   }
+
+  get versionLabel() {
+    return this.config.version_label;
+  }
 }

package/src/util/config/types.ts

@@ -22,6 +22,7 @@ export type Runner = (config: RunnerConfig) => Promise<void>;
 
 export type SyncRulesConfig = {
   present: boolean;
+  version_label?: string;
   content?: string;
   path?: string;
   exit_on_error: boolean;

package/src/util/protocol-types.ts

@@ -1,5 +1,6 @@
 import { JsonContainer } from '@powersync/service-jsonbig';
 import { BucketPriority, SqliteJsonRow } from '@powersync/service-sync-rules';
+import { orNull } from '@powersync/service-types';
 import * as t from 'ts-codec';
 
 export const BucketRequest = t.object({
@@ -24,14 +25,14 @@ export const RequestedStreamSubscription = t.object({
   /**
    * An optional dictionary of parameters to pass to this specific stream.
    */
-  parameters: t.union(t.record(t.any), t.Null),
+  parameters: orNull(t.record(t.any)),
   /**
    * 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
    * useful when the priority for partial syncs depends on e.g. the current page opened in a client.
    */
-  override_priority: t.union(t.number, t.Null)
+  override_priority: orNull(t.number)
 });
 
 export type RequestedStreamSubscription = t.Decoded<typeof RequestedStreamSubscription>;

package/src/util/utils.ts

@@ -309,3 +309,17 @@ export function estimateRowSize(record: sync_rules.ToastableSqliteRow | undefine
   }
   return size;
 }
+
+export function formatBytes(bytes: number | bigint): string {
+  if (typeof bytes == 'bigint') {
+    bytes = Number(bytes); // We round either way
+  }
+  if (bytes >= 1024 * 1024 * 1024) {
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)}GB`;
+  } else if (bytes >= 1024 * 1024) {
+    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+  } else if (bytes >= 1024) {
+    return `${(bytes / 1024).toFixed(1)}KB`;
+  }
+  return `${bytes}B`;
+}

package/test/src/AbstractReplicator.test.ts

@@ -44,6 +44,14 @@ class TestReplicator extends AbstractReplicator {
   get heartbeatIntervalNanosForTest(): bigint | null {
     return (this as any).heartbeatIntervalNanos;
   }
+
+  shouldHandleStreamForTest(
+    replicationStream: PersistedReplicationStream,
+    loadedSyncRules: string | undefined,
+    loadedVersionLabel: string | undefined
+  ): boolean {
+    return (this as any).shouldHandleReplicationStream(replicationStream, loadedSyncRules, loadedVersionLabel);
+  }
 }
 
 describe('AbstractReplicator heartbeat interval', () => {
@@ -145,3 +153,25 @@ describe('AbstractReplicator stopped stream cleanup', () => {
     expect(stopped).toBe(true);
   });
 });
+
+describe('AbstractReplicator rolling deployment config matching', () => {
+  const processingStream = (version_label: string | undefined): PersistedReplicationStream =>
+    ({
+      syncConfigContent: [
+        {
+          syncConfigState: 'PROCESSING',
+          sync_rules_content: 'bucket_definitions: {}',
+          version_label
+        }
+      ]
+    }) as unknown as PersistedReplicationStream;
+
+  it('requires both YAML and version label to match a processing config', () => {
+    const replicator = new TestReplicator(async () => {});
+    const stream = processingStream('v2');
+
+    expect(replicator.shouldHandleStreamForTest(stream, 'bucket_definitions: {}', 'v2')).toBe(true);
+    expect(replicator.shouldHandleStreamForTest(stream, 'bucket_definitions: {}', 'v1')).toBe(false);
+    expect(replicator.shouldHandleStreamForTest(stream, 'bucket_definitions: {}', undefined)).toBe(false);
+  });
+});

package/test/src/MetricAttributeFilteringExporter.test.ts

@@ -0,0 +1,96 @@
+import { MetricAttributeFilteringExporter } from '@/metrics/open-telemetry/MetricAttributeFilteringExporter.js';
+import { Attributes } from '@opentelemetry/api';
+import { ExportResult } from '@opentelemetry/core';
+import { DataPointType, PushMetricExporter, ResourceMetrics } from '@opentelemetry/sdk-metrics';
+import { describe, expect, it, vi } from 'vitest';
+
+type ExportMetrics = (metrics: ResourceMetrics, resultCallback: (result: ExportResult) => void) => void;
+
+describe('MetricAttributeFilteringExporter', () => {
+  it('filters configured attributes without changing the collected metrics', () => {
+    const exportMetrics = vi.fn<ExportMetrics>();
+    const delegate = {
+      export: exportMetrics,
+      forceFlush: vi.fn(async () => {}),
+      shutdown: vi.fn(async () => {})
+    } satisfies PushMetricExporter;
+    const exporter = new MetricAttributeFilteringExporter(delegate, new Set(['version_label']));
+    const attributes: Attributes = {
+      sync_config_id: 'config-a',
+      sync_config_state: 'ACTIVE',
+      version_label: 'customer-version'
+    };
+    const metrics = {
+      resource: {},
+      scopeMetrics: [
+        {
+          scope: {},
+          metrics: [
+            {
+              dataPointType: DataPointType.GAUGE,
+              dataPoints: [{ attributes, value: 100 }]
+            }
+          ]
+        }
+      ]
+    } as unknown as ResourceMetrics;
+    const callback = vi.fn();
+
+    exporter.export(metrics, callback);
+
+    expect(exportMetrics).toHaveBeenCalledWith(
+      expect.objectContaining({
+        scopeMetrics: [
+          expect.objectContaining({
+            metrics: [
+              expect.objectContaining({
+                dataPoints: [
+                  expect.objectContaining({
+                    attributes: { sync_config_id: 'config-a', sync_config_state: 'ACTIVE' }
+                  })
+                ]
+              })
+            ]
+          })
+        ]
+      }),
+      callback
+    );
+    expect(metrics.scopeMetrics[0].metrics[0].dataPoints[0].attributes).toBe(attributes);
+  });
+
+  it('forwards rather than merges data points whose attributes become identical', () => {
+    const exportMetrics = vi.fn<ExportMetrics>();
+    const delegate = {
+      export: exportMetrics,
+      forceFlush: vi.fn(async () => {}),
+      shutdown: vi.fn(async () => {})
+    } satisfies PushMetricExporter;
+    const exporter = new MetricAttributeFilteringExporter(delegate, new Set(['filtered']));
+    const metrics = {
+      resource: {},
+      scopeMetrics: [
+        {
+          scope: {},
+          metrics: [
+            {
+              dataPointType: DataPointType.GAUGE,
+              dataPoints: [
+                { attributes: { retained: 'same', filtered: 'a' }, value: 10 },
+                { attributes: { retained: 'same', filtered: 'b' }, value: 20 }
+              ]
+            }
+          ]
+        }
+      ]
+    } as unknown as ResourceMetrics;
+
+    exporter.export(metrics, vi.fn());
+
+    const exported = exportMetrics.mock.calls[0][0];
+    expect(exported.scopeMetrics[0].metrics[0].dataPoints).toMatchObject([
+      { attributes: { retained: 'same' }, value: 10 },
+      { attributes: { retained: 'same' }, value: 20 }
+    ]);
+  });
+});

package/test/src/PersistedSyncConfigContent.test.ts

@@ -0,0 +1,152 @@
+import {
+  DEFAULT_HYDRATION_STATE,
+  DEFAULT_TAG,
+  nodeSqlite,
+  PrecompiledSyncConfig,
+  serializeSyncPlan,
+  SqlSyncRules
+} from '@powersync/service-sync-rules';
+import * as sqlite from 'node:sqlite';
+import { describe, expect, test } from 'vitest';
+import {
+  parsePersistedSyncConfigContent,
+  SerializedSyncPlan,
+  updateSyncRulesFromConfig
+} from '../../src/storage/storage-index.js';
+
+const EVENT_QUERY = 'SELECT user_id, checkpoint FROM checkpoints WHERE active = true';
+const yamlWithoutEvents = `
+config:
+  edition: 3
+
+streams:
+  checkpoints:
+    query: SELECT * FROM checkpoints
+`;
+const yamlWithEvents = `${yamlWithoutEvents}
+event_definitions:
+  write_checkpoints:
+    payloads:
+      - ${EVENT_QUERY}
+`;
+
+describe('persisted compiled replication events', () => {
+  test('dual-writes additive compiled events and restores the compiled evaluator', () => {
+    const parsed = SqlSyncRules.fromYaml(yamlWithEvents, { defaultSchema: 'test_schema' });
+    const update = updateSyncRulesFromConfig(parsed);
+    const compiled = update.config.plan!;
+    const originalEvent = compiled.plan.events![0];
+
+    expect(compiled.plan.version).toBeLessThanOrEqual(2);
+    expect(compiled.plan.events).toHaveLength(1);
+    expect(originalEvent.name).toBe('write_checkpoints');
+    expect(compiled.eventDescriptors).toEqual({ write_checkpoints: [EVENT_QUERY] });
+
+    const restored = restore(compiled);
+    expect(restored.config).toBeInstanceOf(PrecompiledSyncConfig);
+    expect(restored.config).not.toHaveProperty('eventDescriptors');
+    expect(restored.config.eventDefinitions).toHaveLength(1);
+    expect(restored.config.eventDefinitions[0].name).toBe('write_checkpoints');
+
+    const hydrated = restored.config.hydrate({
+      hydrationState: DEFAULT_HYDRATION_STATE,
+      sqlite: nodeSqlite(sqlite)
+    });
+    expect(
+      hydrated.eventDescriptors[0].evaluateRowWithErrors({
+        sourceTable: { connectionTag: DEFAULT_TAG, schema: 'test_schema', name: 'checkpoints' },
+        record: { user_id: 'user-1', checkpoint: 4n, active: 1 }
+      })
+    ).toEqual({ results: [{ data: { user_id: 'user-1', checkpoint: 4n } }], errors: [] });
+
+    // This represents what an older compiler sees after ignoring the additive plan.events field. The raw descriptor
+    // mirror is normalized into the compiled representation by the new loading boundary, retaining the legacy behavior
+    // of ignoring payload filters until the sync config is redeployed.
+    const { events: _ignored, ...planWithoutCompiledEvents } = compiled.plan;
+    const legacyView = restore({ ...compiled, plan: planWithoutCompiledEvents });
+    expect(legacyView.config).not.toHaveProperty('eventDescriptors');
+    expect(legacyView.config.eventDefinitions).toHaveLength(1);
+    expect(legacyView.config.eventDefinitions[0].name).toBe('write_checkpoints');
+    expect(legacyView.errors).toHaveLength(1);
+    expect(legacyView.errors[0]).toMatchObject({ type: 'warning' });
+
+    const legacyEvent = serializeSyncPlan((legacyView.config as PrecompiledSyncConfig).plan).events![0];
+    expect(legacyEvent.sourceQueries[0].variants[0].filters).toEqual([]);
+    expect(originalEvent.sourceQueries[0].variants[0].filters).not.toEqual([]);
+
+    const legacyHydrated = legacyView.config.hydrate({
+      hydrationState: DEFAULT_HYDRATION_STATE,
+      sqlite: nodeSqlite(sqlite)
+    });
+    expect(
+      legacyHydrated.eventDescriptors[0].evaluateRowWithErrors({
+        sourceTable: { connectionTag: DEFAULT_TAG, schema: 'test_schema', name: 'checkpoints' },
+        record: { user_id: 'user-1', checkpoint: 4n, active: 0 }
+      })
+    ).toEqual({ results: [{ data: { user_id: 'user-1', checkpoint: 4n } }], errors: [] });
+  });
+
+  test('restores raw event descriptors attached to version 1 and 2 plans', () => {
+    const parsed = SqlSyncRules.fromYaml(yamlWithoutEvents, { defaultSchema: 'test_schema' });
+    const update = updateSyncRulesFromConfig(parsed);
+    const legacy: SerializedSyncPlan = {
+      ...update.config.plan!,
+      eventDescriptors: { write_checkpoints: [EVENT_QUERY] }
+    };
+
+    expect(legacy.plan.version).toBeLessThanOrEqual(2);
+    const restored = restore(legacy);
+    expect(restored.config).not.toHaveProperty('eventDescriptors');
+    expect(restored.config.eventDefinitions).toHaveLength(1);
+    expect((restored.config as PrecompiledSyncConfig).plan.events).toMatchObject([
+      { name: 'write_checkpoints', sourceQueries: [{ sql: EVENT_QUERY }] }
+    ]);
+    expect(restored.errors).toHaveLength(1);
+    expect(restored.errors[0]).toMatchObject({ type: 'warning' });
+    expect(
+      serializeSyncPlan((restored.config as PrecompiledSyncConfig).plan).events![0].sourceQueries[0].variants[0].filters
+    ).toEqual([]);
+  });
+
+  /**
+   * Event SQL accepted by the legacy evaluator must remain loadable after an upgrade, even when its ignored filter uses
+   * expressions that the compiled event evaluator intentionally rejects for new deployments.
+   */
+  test.each([
+    ['request parameters', 'SELECT user_id FROM checkpoints WHERE user_id = request.user_id()'],
+    ['unsupported expressions', 'SELECT user_id FROM checkpoints WHERE active IN (1, 2)']
+  ])('loads legacy event descriptors without validating ignored %s', (_description, eventQuery) => {
+    const parsed = SqlSyncRules.fromYaml(yamlWithoutEvents, { defaultSchema: 'test_schema' });
+    const update = updateSyncRulesFromConfig(parsed);
+    const legacy: SerializedSyncPlan = {
+      ...update.config.plan!,
+      eventDescriptors: {
+        write_checkpoints: [eventQuery]
+      }
+    };
+
+    const restored = restore(legacy);
+    expect(restored.errors).toHaveLength(1);
+    expect(restored.errors[0]).toMatchObject({ type: 'warning' });
+
+    const event = restored.config.hydrate({
+      hydrationState: DEFAULT_HYDRATION_STATE,
+      sqlite: nodeSqlite(sqlite)
+    }).eventDescriptors[0];
+    expect(
+      event.evaluateRowWithErrors({
+        sourceTable: { connectionTag: DEFAULT_TAG, schema: 'test_schema', name: 'checkpoints' },
+        record: { user_id: 'user-1' }
+      })
+    ).toEqual({ results: [{ data: { user_id: 'user-1' } }], errors: [] });
+  });
+});
+
+function restore(compiledPlan: SerializedSyncPlan) {
+  return parsePersistedSyncConfigContent({
+    content: yamlWithEvents,
+    compiledPlan,
+    storageVersion: 1,
+    parseOptions: { defaultSchema: 'test_schema' }
+  });
+}

package/test/src/config.test.ts

@@ -70,6 +70,44 @@ describe('Config', () => {
     expect(config.api_parameters.max_buckets_per_connection).toBe(1);
   });
 
+  it('should resolve the storage default version', {}, async () => {
+    const yamlConfig = /* yaml */ `
+      # PowerSync config
+      replication:
+        connections: []
+      storage:
+        type: mongodb
+        default_storage_version: 4
+    `;
+
+    const collector = new CompoundConfigCollector();
+
+    const config = await collector.collectConfig({
+      config_base64: Buffer.from(yamlConfig, 'utf-8').toString('base64')
+    });
+
+    expect(config.storage.default_storage_version).toBe(4);
+  });
+
+  it.each([1, 1.5, 5])('should reject unsupported storage default version %s', async (defaultStorageVersion) => {
+    const yamlConfig = /* yaml */ `
+      # PowerSync config
+      replication:
+        connections: []
+      storage:
+        type: mongodb
+        default_storage_version: ${defaultStorageVersion}
+    `;
+
+    const collector = new CompoundConfigCollector();
+
+    await expect(
+      collector.collectConfig({
+        config_base64: Buffer.from(yamlConfig, 'utf-8').toString('base64')
+      })
+    ).rejects.toThrow(`Storage version ${defaultStorageVersion} is not supported`);
+  });
+
   it('should resolve checkpoint request retention config', {}, async () => {
     const yamlConfig = /* yaml */ `
       # PowerSync config
@@ -198,6 +236,7 @@ describe('Config', () => {
       storage:
         type: mongodb
       sync_config:
+        version_label: v6
         content: |
           config:
             edition: 2
@@ -214,6 +253,7 @@ describe('Config', () => {
 
     expect(result.sync_rules).toEqual({
       present: true,
+      version_label: 'v6',
       exit_on_error: true,
       content: expect.stringContaining('edition: 2')
     });

package/test/src/diagnostics.test.ts

@@ -15,6 +15,7 @@ bucket_definitions:
 
 function makeSyncRulesContent(overrides?: {
   slot_name?: string;
+  version_label?: string;
   status?: storage.PersistedSyncConfigStatus;
 }): storage.PersistedSyncConfigContent {
   // We don't implement the entire interface correctly here - just enough to test the diagnostics logic.
@@ -37,6 +38,7 @@ function makeSyncRulesContent(overrides?: {
     compiled_plan: null,
     storageVersion: 1,
     syncConfigState: status.state,
+    version_label: overrides?.version_label,
     parsed(options?: any) {
       const syncRules = SqlSyncRules.fromYaml(MINIMAL_SYNC_RULES, {
         ...options,
@@ -180,4 +182,27 @@ describe('getSyncRulesStatus WAL budget warnings', () => {
     expect(result!.connections[0].last_keepalive_ts).toBe('2026-01-01T00:01:00.000Z');
     expect(result!.errors.some((error) => error.message == 'config failed')).toBe(true);
   });
+
+  test('includes the sync config version label', async () => {
+    const result = await getSyncRulesStatus(
+      makeRouteAPI(),
+      makeSyncRulesContent({ version_label: 'v6' }),
+      OPTIONS,
+      makeSystemStorage()
+    );
+
+    expect(result!.version_label).toBe('v6');
+  });
+
+  test('includes the sync config version label when parsing fails', async () => {
+    const content = makeSyncRulesContent({ version_label: 'v6' });
+    content.parsed = () => {
+      throw new Error('Invalid sync config');
+    };
+
+    const result = await getSyncRulesStatus(makeRouteAPI(), content, OPTIONS, makeSystemStorage());
+
+    expect(result!.version_label).toBe('v6');
+    expect(result!.errors).toEqual([expect.objectContaining({ level: 'fatal', message: 'Invalid sync config' })]);
+  });
 });