@powersync/service-core 1.27.1 → 1.28.0

package/test/src/module-loader.test.ts

@@ -99,7 +99,20 @@ describe('module loader', () => {
       storage: { type: 'postgresql' }
     };
 
-    await expect(loadModules(config as any, mockLoaders)).rejects.toThrowError();
+    await expect(loadModules(config as any, mockLoaders)).rejects.toThrowError(
+      'Invalid connection types: "redis". Supported types: "mysql", "postgresql".'
+    );
+  });
+
+  it('should throw an error with supported storage types if storage type is invalid', async () => {
+    const config: MockConfig = {
+      connections: [{ type: 'mysql' }],
+      storage: { type: 'redis' }
+    };
+
+    await expect(loadModules(config as any, mockLoaders)).rejects.toThrowError(
+      'Invalid storage type: "redis". Supported types: "postgresql".'
+    );
   });
 
   it('should throw an error if one dynamic connection module import fails', async () => {

package/test/src/recording-metrics.ts

@@ -0,0 +1,36 @@
+import {
+  AggregationTemporality,
+  InMemoryMetricExporter,
+  MeterProvider,
+  PeriodicExportingMetricReader
+} from '@opentelemetry/sdk-metrics';
+
+import { createCoreAPIMetrics, initializeCoreAPIMetrics, MetricsEngine, OpenTelemetryMetricsFactory } from '@/index.js';
+
+/** Collects real metrics and sums series matching the supplied labels. */
+export function recordingMetricsEngine(name = 'route-test') {
+  const exporter = new InMemoryMetricExporter(AggregationTemporality.CUMULATIVE);
+  const reader = new PeriodicExportingMetricReader({ exporter, exportIntervalMillis: 60_000 });
+  const provider = new MeterProvider({ readers: [reader] });
+  const engine = new MetricsEngine({
+    factory: new OpenTelemetryMetricsFactory(provider.getMeter(name)),
+    disable_telemetry_sharing: true
+  });
+  createCoreAPIMetrics(engine);
+  initializeCoreAPIMetrics(engine);
+
+  return {
+    engine,
+    shutdown: () => provider.shutdown(),
+    async seriesValue(metricName: string, attributes: Record<string, string>): Promise<number | undefined> {
+      await reader.forceFlush();
+      const metrics = exporter.getMetrics();
+      const scoped = metrics[metrics.length - 1]?.scopeMetrics?.[0]?.metrics;
+      const metric = scoped?.find((m) => m.descriptor.name === metricName);
+      const points = metric?.dataPoints.filter((p) =>
+        Object.entries(attributes).every(([k, v]) => p.attributes[k] === v)
+      );
+      return points?.length ? points.reduce((sum, point) => sum + (point.value as number), 0) : undefined;
+    }
+  };
+}

package/test/src/routes/admin.test.ts

@@ -1,6 +1,6 @@
 import { BasicRouterRequest, Context, JwtPayload, ParsedSyncConfigSet, storage } from '@/index.js';
 import { ErrorCode, logger } from '@powersync/lib-services-framework';
-import { PrecompiledSyncConfig, SqlSyncRules } from '@powersync/service-sync-rules';
+import { PrecompiledSyncConfig, parseSyncConfig } from '@powersync/service-sync-rules';
 import { describe, expect, it, vi } from 'vitest';
 import { diagnostics, reprocess, validate } from '../../../src/routes/endpoints/admin.js';
 import { deploySyncRules, reprocessSyncRules, validateSyncRules } from '../../../src/routes/endpoints/sync-rules.js';
@@ -70,7 +70,7 @@ bucket_definitions:
       syncConfigState: syncConfigStatus.state,
       version_label: options.version_label,
       parsed(options?: any) {
-        const syncRules = SqlSyncRules.fromYaml(content.sync_rules_content, {
+        const syncRules = parseSyncConfig(content.sync_rules_content, {
           ...options,
           defaultSchema: 'public'
         });

package/test/src/routes/concurrency-limit.test.ts

@@ -0,0 +1,108 @@
+import { JwtPayload, routeDefinition } from '@/index.js';
+import { router } from '@powersync/lib-services-framework';
+import { APIMetric } from '@powersync/service-types';
+import Fastify from 'fastify';
+import { describe, expect, it, onTestFinished, vi } from 'vitest';
+import { configureFastifyServer } from '../../../src/routes/configure-fastify.js';
+import { syncStreamed } from '../../../src/routes/endpoints/sync-stream.js';
+import { recordingMetricsEngine } from '../recording-metrics.js';
+import { mockServiceContext } from './mocks.js';
+
+describe('HTTP concurrency limit metrics', () => {
+  it('counts each rejected sync request without changing the HTTP 429 response', async () => {
+    const recorder = recordingMetricsEngine();
+    onTestFinished(() => recorder.shutdown());
+    const service = mockServiceContext(null, recorder.engine);
+    const entered = Promise.withResolvers<void>();
+    const release = Promise.withResolvers<void>();
+    vi.spyOn(service.storageEngine.activeBucketStorage, 'getActiveSyncConfig').mockImplementation(async () => {
+      entered.resolve();
+      await release.promise;
+      return null;
+    });
+    const app = Fastify();
+    configureFastifyServer(app, {
+      service_context: service,
+      routes: {
+        api: { routes: [] },
+        checkpointing: { routes: [] },
+        sync_stream: {
+          queue_options: { concurrency: 1, max_queue_depth: 0 },
+          routes: [
+            {
+              ...syncStreamed,
+              authorize: async ({ context }) => {
+                context.token_payload = new JwtPayload({ sub: 'test-user', exp: Date.now() / 1000 + 10_000 });
+                return { authorized: true };
+              }
+            }
+          ]
+        }
+      }
+    });
+    const first = app.inject({ method: 'POST', url: '/sync/stream', payload: {} });
+    try {
+      await entered.promise;
+      for (let i = 0; i < 3; i++) {
+        const response = await app.inject({ method: 'POST', url: '/sync/stream', payload: {} });
+        expect(response.statusCode).toBe(429);
+        expect(response.body).toBe('');
+      }
+      expect(
+        await recorder.seriesValue(APIMetric.SYNC_CONNECTIONS, {
+          outcome: 'rejected',
+          close_reason: 'concurrency_limit',
+          error_code: 'other',
+          transport: 'http_stream'
+        })
+      ).toBe(3);
+      expect(await recorder.seriesValue(APIMetric.SYNC_CONNECTIONS, {})).toBe(3);
+      expect(await recorder.seriesValue(APIMetric.CONCURRENT_CONNECTIONS, {})).toBe(0);
+    } finally {
+      release.resolve();
+      await first;
+      await app.close();
+    }
+  });
+
+  it.each(['api', 'checkpointing'] as const)('does not count %s queue rejections as sync attempts', async (group) => {
+    const recorder = recordingMetricsEngine();
+    onTestFinished(() => recorder.shutdown());
+    const entered = Promise.withResolvers<void>();
+    const release = Promise.withResolvers<void>();
+    const app = Fastify();
+    configureFastifyServer(app, {
+      service_context: mockServiceContext(null, recorder.engine),
+      routes: {
+        api: { routes: [] },
+        checkpointing: { routes: [] },
+        sync_stream: { routes: [] },
+        [group]: {
+          queue_options: { concurrency: 1, max_queue_depth: 0 },
+          routes: [
+            routeDefinition({
+              path: '/test',
+              method: router.HTTPMethod.GET,
+              handler: async () => {
+                entered.resolve();
+                await release.promise;
+                return {};
+              }
+            })
+          ]
+        }
+      }
+    });
+    const first = app.inject({ method: 'GET', url: '/test' });
+    try {
+      await entered.promise;
+      const response = await app.inject({ method: 'GET', url: '/test' });
+      expect(response.statusCode).toBe(429);
+      expect((await recorder.seriesValue(APIMetric.SYNC_CONNECTIONS, {})) ?? 0).toBe(0);
+    } finally {
+      release.resolve();
+      await first;
+      await app.close();
+    }
+  });
+});

package/test/src/routes/connection-metrics.test.ts

@@ -0,0 +1,269 @@
+import { Context, JwtPayload, RouterEngine, SyncRulesBucketStorage, SyncTransport } from '@/index.js';
+import { ErrorCode, logger, RouterResponse, ServiceError } from '@powersync/lib-services-framework';
+import {
+  handleReactiveStream,
+  ReactiveSocketRouter,
+  ReactiveStreamRequest,
+  SocketRouterObserver
+} from '@powersync/service-rsocket-router';
+import { DEFAULT_HYDRATION_STATE, nodeSqlite, parseSyncConfig } from '@powersync/service-sync-rules';
+import { APIMetric } from '@powersync/service-types';
+import * as sqlite from 'node:sqlite';
+import { Readable } from 'node:stream';
+import { describe, expect, it, onTestFinished, vi } from 'vitest';
+import { syncStreamReactive } from '../../../src/routes/endpoints/socket-route.js';
+import { syncStreamed } from '../../../src/routes/endpoints/sync-stream.js';
+import { recordingMetricsEngine } from '../recording-metrics.js';
+import { mockServiceContext } from './mocks.js';
+
+function testContext(storage: Partial<SyncRulesBucketStorage> | null) {
+  const recorder = recordingMetricsEngine();
+  onTestFinished(() => recorder.shutdown());
+  const service = mockServiceContext(storage, recorder.engine);
+  const api = service.routerEngine.getAPI();
+  service.routerEngine = new RouterEngine();
+  service.routerEngine.registerAPI({ ...api, shutdown: async () => {} });
+  const context: Context = {
+    service_context: service,
+    logger: logger.child({}),
+    token_payload: new JwtPayload({ sub: 'test-user', exp: Date.now() / 1000 + 10_000 })
+  };
+  return { recorder, context, service };
+}
+
+function startConnection(transport: SyncTransport, context: Context) {
+  const controller = new AbortController();
+  const disconnected = Promise.withResolvers<void>();
+  const errors: unknown[] = [];
+  let response: RouterResponse | undefined;
+  let clientClosed = false;
+  const disconnect = () => {
+    clientClosed = true;
+    controller.abort();
+    (response?.data as Readable | undefined)?.destroy();
+    disconnected.resolve();
+  };
+
+  const finished =
+    transport === SyncTransport.HttpStream
+      ? (async () => {
+          try {
+            response = (await syncStreamed.handler({
+              context,
+              params: {},
+              request: { headers: {}, hostname: '', protocol: 'http' }
+            })) as RouterResponse;
+            const drained = (async () => {
+              try {
+                for await (const _chunk of response!.data as Readable) {
+                  // Consume the response as the HTTP router would.
+                }
+              } catch (error) {
+                errors.push(error);
+                disconnect();
+              }
+            })();
+            // Fastify runs afterSend on socket close, without waiting for the iterator to finish.
+            await Promise.race([drained, disconnected.promise]);
+            await response.afterSend({ clientClosed });
+            await drained;
+          } catch (error) {
+            errors.push(error);
+          }
+        })()
+      : handleReactiveStream(
+          context,
+          {
+            payload: { data: Buffer.from('{}'), metadata: Buffer.from(JSON.stringify({ path: '/sync/stream' })) },
+            metadataMimeType: 'application/json',
+            dataMimeType: 'application/json',
+            initialN: 10,
+            responder: {
+              onNext() {},
+              onComplete() {},
+              onExtension() {},
+              onError(error) {
+                errors.push(error);
+                disconnect();
+              }
+            },
+            connection: { tracker: {} } as ReactiveStreamRequest['connection']
+          },
+          new SocketRouterObserver(),
+          controller,
+          {
+            contextProvider: async () => context,
+            endpoints: [syncStreamReactive(new ReactiveSocketRouter())],
+            metaDecoder: async (buffer) => JSON.parse(buffer.contents.toString()),
+            payloadDecoder: async (buffer) => buffer && JSON.parse(buffer.contents.toString())
+          }
+        );
+  onTestFinished(async () => {
+    disconnect();
+    await finished;
+  });
+  return { finished, disconnect, errors };
+}
+
+function idleStorage() {
+  const ready = Promise.withResolvers<void>();
+  const ending = Promise.withResolvers<void>();
+  const storage: Partial<SyncRulesBucketStorage> = {
+    getParsedSyncRules: () =>
+      parseSyncConfig('config:\n  edition: 3\nstreams: {}', {
+        defaultSchema: 'public'
+      }).config.hydrate({
+        hydrationState: DEFAULT_HYDRATION_STATE,
+        sqlite: nodeSqlite(sqlite)
+      }),
+    async *watchCheckpointChanges({ signal }) {
+      const onAbort = () => ending.resolve();
+      signal.addEventListener('abort', onAbort, { once: true });
+      if (signal.aborted) onAbort();
+      ready.resolve();
+      try {
+        await ending.promise;
+      } finally {
+        signal.removeEventListener('abort', onAbort);
+      }
+    }
+  };
+  return { storage, ready: ready.promise, finish: () => ending.resolve(), fail: ending.reject };
+}
+
+describe.each([SyncTransport.HttpStream, SyncTransport.RSocket])('%s connection metrics', (transport) => {
+  it.each([
+    ['service_unavailable', 'PSYNC_S2003'],
+    ['no_sync_config', 'PSYNC_S2302'],
+    ['storage_error', 'PSYNC_S2403'],
+    ['storage_error', 'other']
+  ])('counts %s / %s once without accepting a stream', async (closeReason, errorCode) => {
+    const { recorder, context, service } = testContext(null);
+    if (closeReason === 'service_unavailable') {
+      await service.routerEngine.shutDown();
+    } else if (closeReason === 'storage_error') {
+      const error =
+        errorCode === 'other'
+          ? new Error('Storage lookup failed')
+          : new ServiceError(ErrorCode.PSYNC_S2403, 'Storage query timed out');
+      vi.spyOn(service.storageEngine.activeBucketStorage, 'getActiveSyncConfig').mockRejectedValue(error);
+    }
+
+    const connection = startConnection(transport, context);
+    await connection.finished;
+    expect(connection.errors).toHaveLength(1);
+    if (errorCode !== 'other') {
+      expect(connection.errors[0]).toMatchObject({ errorData: { code: errorCode } });
+    }
+    expect(
+      await recorder.seriesValue(APIMetric.SYNC_CONNECTIONS, {
+        transport,
+        outcome: 'rejected',
+        close_reason: closeReason,
+        error_code: errorCode
+      })
+    ).toBe(1);
+    expect(await recorder.seriesValue(APIMetric.SYNC_CONNECTIONS, {})).toBe(1);
+    expect(await recorder.seriesValue(APIMetric.CONCURRENT_CONNECTIONS, {})).toBe(0);
+  });
+
+  it.each(['client_closed', 'service_closed', 'process_shutdown'])(
+    'counts %s once and restores the active gauge',
+    async (closeReason) => {
+      const source = idleStorage();
+      const { recorder, context, service } = testContext(source.storage);
+      const connection = startConnection(transport, context);
+      await source.ready;
+      expect(await recorder.seriesValue(APIMetric.CONCURRENT_CONNECTIONS, {})).toBe(1);
+      expect(await recorder.seriesValue(APIMetric.SYNC_CONNECTIONS, {})).toBeUndefined();
+
+      if (closeReason === 'client_closed') {
+        connection.disconnect();
+      } else if (closeReason === 'process_shutdown') {
+        await service.routerEngine.shutDown();
+      } else {
+        source.finish();
+      }
+      await connection.finished;
+      connection.disconnect();
+      await service.routerEngine.shutDown();
+
+      expect(
+        await recorder.seriesValue(APIMetric.SYNC_CONNECTIONS, {
+          transport,
+          outcome: 'ok',
+          close_reason: closeReason
+        })
+      ).toBe(1);
+      expect(await recorder.seriesValue(APIMetric.SYNC_CONNECTIONS, {})).toBe(1);
+      expect(await recorder.seriesValue(APIMetric.CONCURRENT_CONNECTIONS, {})).toBe(0);
+    }
+  );
+
+  it('counts token expiry as an ok server close', async () => {
+    const source = idleStorage();
+    const { recorder, context } = testContext(source.storage);
+    context.token_payload = new JwtPayload({ sub: 'test-user', exp: 0 });
+    const connection = startConnection(transport, context);
+    await connection.finished;
+
+    expect(connection.errors).toEqual([]);
+    expect(
+      await recorder.seriesValue(APIMetric.SYNC_CONNECTIONS, {
+        transport,
+        outcome: 'ok',
+        close_reason: 'service_closed'
+      })
+    ).toBe(1);
+    expect(await recorder.seriesValue(APIMetric.SYNC_CONNECTIONS, {})).toBe(1);
+    expect(await recorder.seriesValue(APIMetric.CONCURRENT_CONNECTIONS, {})).toBe(0);
+  });
+
+  it.each([
+    [new ServiceError(ErrorCode.PSYNC_S2305, 'Too many buckets'), 'PSYNC_S2305'],
+    [new Error('Storage read failed'), 'other']
+  ] as const)('preserves an accepted stream failure through client disconnect: %s', async (error, errorCode) => {
+    const source = idleStorage();
+    const { recorder, context } = testContext(source.storage);
+    const connection = startConnection(transport, context);
+    await source.ready;
+    expect(await recorder.seriesValue(APIMetric.CONCURRENT_CONNECTIONS, {})).toBe(1);
+    source.fail(error);
+    await connection.finished;
+
+    expect(connection.errors).toHaveLength(1);
+    expect(
+      await recorder.seriesValue(APIMetric.SYNC_CONNECTIONS, {
+        transport,
+        outcome: 'error',
+        close_reason: 'stream_error',
+        error_code: errorCode
+      })
+    ).toBe(1);
+    expect(await recorder.seriesValue(APIMetric.SYNC_CONNECTIONS, {})).toBe(1);
+    expect(await recorder.seriesValue(APIMetric.CONCURRENT_CONNECTIONS, {})).toBe(0);
+  });
+
+  it('counts a sync config hydration failure as one rejection without accepting a stream', async () => {
+    const failure = new Error('Persisted sync config could not be hydrated');
+    const { recorder, context } = testContext({
+      getParsedSyncRules() {
+        throw failure;
+      }
+    });
+    const connection = startConnection(transport, context);
+    await connection.finished;
+
+    expect(connection.errors).toEqual([failure]);
+    expect(
+      await recorder.seriesValue(APIMetric.SYNC_CONNECTIONS, {
+        transport,
+        outcome: 'rejected',
+        close_reason: 'sync_config_error',
+        error_code: 'other'
+      })
+    ).toBe(1);
+    expect(await recorder.seriesValue(APIMetric.SYNC_CONNECTIONS, {})).toBe(1);
+    expect(await recorder.seriesValue(APIMetric.CONCURRENT_CONNECTIONS, {})).toBe(0);
+  });
+});

package/test/src/routes/invalid-config.test.ts

@@ -0,0 +1,184 @@
+import { BasicRouterRequest, Context, RouterEngine, storage, updateSyncRulesFromYaml } from '@/index.js';
+import { diagnostics, reprocess } from '@/routes/endpoints/admin.js';
+import { reprocessSyncRules } from '@/routes/endpoints/sync-rules.js';
+import { SyncConfigEngine } from '@/system/SyncConfigEngine.js';
+import { describe, expect, it, vi } from 'vitest';
+import { mockServiceContext } from './mocks.js';
+
+const VALID_CONFIG = /* yaml */ `
+  # Stored config.
+  config:
+    edition: 3
+  streams:
+    todos:
+      query: SELECT id FROM todos
+`;
+const INVALID_CONFIG = /* yaml */ `
+  # Local rejected config.
+  config:
+    edition: 3
+  streams:
+    broken:
+      query: SELECT FROM
+`;
+const REQUEST = { headers: {}, hostname: '', protocol: 'http' } as BasicRouterRequest;
+
+function makeStoredConfig() {
+  return {
+    content: {
+      replicationStreamName: 'stored_slot',
+      version_label: 'stored',
+      sync_rules_content: VALID_CONFIG,
+      parsed: () => ({ syncConfigs: [updateSyncRulesFromYaml(VALID_CONFIG).config.parsed] }),
+      getSyncConfigStatus: async () => null
+    },
+    storage: { getStatus: vi.fn(async () => ({ snapshotDone: true })) }
+  } as unknown as storage.ResolvedSyncConfig;
+}
+
+async function makeContext(content: string, active = true, connected = true) {
+  const service = mockServiceContext(null);
+  service.configuration = {
+    sync_rules: { present: true, content, version_label: 'local', exit_on_error: false }
+  } as typeof service.configuration;
+  const persisted = makeStoredConfig();
+  (service.storageEngine as any).activeBucketStorage = {
+    getActiveSyncConfig: async () => (active ? persisted : null),
+    getDeployingSyncConfig: async () => persisted
+  };
+  const api = service.routerEngine.getAPI();
+  service.routerEngine = new RouterEngine();
+  service.routerEngine.registerAPI(api);
+  service.syncConfigEngine = new SyncConfigEngine(service.configuration.sync_rules, () =>
+    service.routerEngine.getAPI()
+  );
+  vi.spyOn(api, 'getConnectionStatus').mockResolvedValue({ connected, errors: [], id: 'test_id', uri: 'test' });
+  return { context: { service_context: service } as Context, api, persisted };
+}
+
+describe('local invalid config diagnostics', () => {
+  it.each([{ connected: true }, { connected: false }])(
+    'overlays rejected config and preserves active diagnostics (connected=$connected)',
+    async ({ connected }) => {
+      const { context } = await makeContext(INVALID_CONFIG, true, connected);
+      const result = await diagnostics.handler({ context, request: REQUEST, params: { sync_rules_content: true } });
+      // Rejected configured YAML appears under deploying_sync_rules without hiding the active deployment.
+      expect(result.active_sync_rules?.content).toBe(VALID_CONFIG);
+      expect(result.active_sync_rules?.connections[0].slot_name).toBe('stored_slot');
+      expect(result.deploying_sync_rules?.content).toBe(INVALID_CONFIG);
+      expect(result.deploying_sync_rules?.version_label).toBe('local');
+      expect(result.deploying_sync_rules?.connections).toEqual([]);
+      expect(result.deploying_sync_rules?.errors.some((error) => error.level == 'fatal')).toBe(true);
+    }
+  );
+
+  it('reports a rejected first config without content when not requested', async () => {
+    const { context } = await makeContext(INVALID_CONFIG, false);
+    const result = await diagnostics.handler({ context, request: REQUEST, params: {} });
+    expect(result.active_sync_rules).toBeUndefined();
+    expect(result.deploying_sync_rules?.content).toBeUndefined();
+    expect(result.deploying_sync_rules?.errors.some((error) => error.level == 'fatal')).toBe(true);
+  });
+
+  it('reports local errors even when no source connection is configured', async () => {
+    const { context, api } = await makeContext(INVALID_CONFIG, false);
+    // Exercise the route's existing defensive fallback for a missing source adapter status.
+    vi.mocked(api.getConnectionStatus).mockResolvedValue(
+      undefined as unknown as Awaited<ReturnType<typeof api.getConnectionStatus>>
+    );
+    const result = await diagnostics.handler({ context, request: REQUEST, params: {} });
+    expect(result.connections).toEqual([]);
+    expect(result.deploying_sync_rules?.errors.some((error) => error.level == 'fatal')).toBe(true);
+  });
+
+  it('keeps stored pending diagnostics when the local config is valid', async () => {
+    const { context } = await makeContext(VALID_CONFIG);
+    const result = await diagnostics.handler({ context, request: REQUEST, params: { sync_rules_content: true } });
+    expect(result.deploying_sync_rules?.content).toBe(VALID_CONFIG);
+    expect(result.deploying_sync_rules?.connections[0].slot_name).toBe('stored_slot');
+  });
+
+  it.each([{ connected: true }, { connected: false }])(
+    'reports rejected source capabilities on an API instance (connected=$connected)',
+    async ({ connected }) => {
+      const content = /* yaml */ `
+        # Rejected local MongoDB deployment.
+        config:
+          edition: 3
+          source_table_options:
+            orders:
+              mongodb_filter_expression: { $eq: ['$$doc.active', true] }
+        streams:
+          orders:
+            query: SELECT * FROM orders
+      `;
+      const { context, api } = await makeContext(content, true, connected);
+      // Only the API is running: no replicator has validated or persisted the local config.
+      const fatal = {
+        level: 'fatal' as const,
+        message: 'MongoDB pre-filtering is not supported',
+        location: { start_offset: 1, end_offset: 10 }
+      };
+      api.validateSourceCapabilities = vi.fn(async (config) => {
+        return config.content === content ? [fatal] : [];
+      });
+      const result = await diagnostics.handler({ context, request: REQUEST, params: { sync_rules_content: true } });
+      expect(result.active_sync_rules?.content).toBe(VALID_CONFIG);
+      expect(result.deploying_sync_rules).toMatchObject({
+        content,
+        version_label: 'local',
+        connections: [],
+        errors: expect.arrayContaining([expect.objectContaining(fatal)])
+      });
+    }
+  );
+
+  it('reports unexpected source capability failures without persisted status or requested content', async () => {
+    const { context, api } = await makeContext(VALID_CONFIG, false);
+    api.validateSourceCapabilities = vi.fn(async () => {
+      throw new Error('Capability validation failed');
+    });
+    const result = await diagnostics.handler({ context, request: REQUEST, params: {} });
+    expect(result.deploying_sync_rules?.content).toBeUndefined();
+    expect(result.deploying_sync_rules?.connections).toEqual([]);
+    expect(result.deploying_sync_rules?.errors).toEqual([
+      expect.objectContaining({ level: 'fatal', message: 'Capability validation failed' })
+    ]);
+  });
+
+  it('keeps stored pending diagnostics when local source capabilities only report warnings', async () => {
+    const { context, api } = await makeContext(VALID_CONFIG);
+    api.validateSourceCapabilities = vi.fn(async () => [{ level: 'warning' as const, message: 'Advisory warning' }]);
+    const result = await diagnostics.handler({ context, request: REQUEST, params: { sync_rules_content: true } });
+    expect(result.deploying_sync_rules?.connections[0].slot_name).toBe('stored_slot');
+  });
+});
+
+describe('manual reprocessing with rejected local config', () => {
+  it.each(
+    [reprocess, reprocessSyncRules].flatMap((route) =>
+      [false, true].map((capabilityFailure) => ({ route, capabilityFailure }))
+    )
+  )(
+    'blocks $route.path for local fatal errors (capability=$capabilityFailure)',
+    async ({ route, capabilityFailure }) => {
+      const { context, api } = await makeContext(capabilityFailure ? VALID_CONFIG : INVALID_CONFIG);
+      const backend = context.service_context.storageEngine.activeBucketStorage;
+      // Ensure no pending deployment exists, so invalid configured YAML is what blocks reprocessing.
+      vi.spyOn(backend, 'getDeployingSyncConfig').mockResolvedValue(null);
+      if (capabilityFailure) {
+        api.validateSourceCapabilities = async () => [{ level: 'fatal', message: 'Unsupported executor' }];
+      }
+      const update = vi.fn();
+      backend.updateSyncRules = update;
+      await expect(route.handler({ context, request: REQUEST, params: {} })).rejects.toMatchObject({
+        errorData: {
+          status: 409,
+          code: 'PSYNC_S4106',
+          description: 'Cannot reprocess while the configured sync config is invalid'
+        }
+      });
+      expect(update).not.toHaveBeenCalled();
+    }
+  );
+});