@syncular/server-hono 0.0.1 → 0.0.2-126

package/src/routes.ts

@@ -2,20 +2,19 @@
  * @syncular/server-hono - Sync routes for Hono
  *
  * Provides:
- * - POST /pull  (commit stream + optional bootstrap snapshots)
- * - POST /push  (commit ingestion)
+ * - POST /      (combined push + pull in one round-trip)
  * - GET  /snapshot-chunks/:chunkId (download encoded snapshot chunks)
  * - GET  /realtime (optional WebSocket "wake up" notifications)
  */
 
 import {
+  captureSyncException,
   createSyncTimer,
   ErrorResponseSchema,
   logSyncEvent,
-  SyncPullRequestSchema,
-  SyncPullResponseSchema,
+  SyncCombinedRequestSchema,
+  SyncCombinedResponseSchema,
   SyncPushRequestSchema,
-  SyncPushResponseSchema,
 } from '@syncular/core';
 import type {
   ServerSyncDialect,
@@ -28,8 +27,6 @@ import type {
 import {
   type CompactOptions,
   InvalidSubscriptionScopeError,
-  maybeCompactChanges,
-  maybePruneSync,
   type PruneOptions,
   type PullResult,
   pull,
@@ -38,8 +35,9 @@ import {
   recordClientCursor,
   TableRegistry,
 } from '@syncular/server';
-import type { Context } from 'hono';
+import type { Context, MiddlewareHandler } from 'hono';
 import { Hono } from 'hono';
+
 import type { UpgradeWebSocket } from 'hono/ws';
 import { describeRoute, resolver, validator as zValidator } from 'hono-openapi';
 import {
@@ -54,7 +52,11 @@ import {
   DEFAULT_SYNC_RATE_LIMITS,
   type SyncRateLimitConfig,
 } from './rate-limit';
-import { createWebSocketConnection, WebSocketConnectionManager } from './ws';
+import {
+  createWebSocketConnection,
+  type WebSocketConnection,
+  WebSocketConnectionManager,
+} from './ws';
 
 /**
  * WeakMaps for storing Hono-instance-specific data without augmenting the type.
@@ -64,6 +66,7 @@ const realtimeUnsubscribeMap = new WeakMap<Hono, () => void>();
 
 export interface SyncAuthResult {
   actorId: string;
+  partitionId?: string;
 }
 
 /**
@@ -186,6 +189,14 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
   options: CreateSyncRoutesOptions<DB>
 ): Hono {
   const routes = new Hono();
+  routes.onError((error, c) => {
+    captureSyncException(error, {
+      event: 'sync.route.unhandled',
+      method: c.req.method,
+      path: c.req.path,
+    });
+    return c.text('Internal Server Error', 500);
+  });
   const handlerRegistry = new TableRegistry<DB>();
   for (const handler of options.handlers) {
     handlerRegistry.register(handler);
@@ -229,11 +240,30 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
     (typeof crypto !== 'undefined' && 'randomUUID' in crypto
       ? crypto.randomUUID()
       : `${Date.now()}-${Math.random().toString(16).slice(2)}`);
+  const loggedAsyncFailureKeys = new Set<string>();
+  const logAsyncFailureOnce = (
+    key: string,
+    event: {
+      event: string;
+      error: string;
+      [key: string]: unknown;
+    }
+  ) => {
+    if (loggedAsyncFailureKeys.has(key)) return;
+    loggedAsyncFailureKeys.add(key);
+    logSyncEvent(event);
+  };
 
   if (wsConnectionManager && realtimeBroadcaster) {
     const unsubscribe = realtimeBroadcaster.subscribe(
       (event: SyncRealtimeEvent) => {
-        void handleRealtimeEvent(event).catch(() => {});
+        void handleRealtimeEvent(event).catch((error) => {
+          logAsyncFailureOnce('sync.realtime.broadcast_delivery_failed', {
+            event: 'sync.realtime.broadcast_delivery_failed',
+            error: error instanceof Error ? error.message : String(error),
+            sourceEventType: event.type,
+          });
+        });
       }
     );
 
@@ -244,7 +274,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
   // Request event recording (for console inspector)
   // -------------------------------------------------------------------------
 
-  const recordRequestEvent = async (event: {
+  type RequestEvent = {
     eventType: 'push' | 'pull';
     actorId: string;
     clientId: string;
@@ -257,25 +287,44 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
     rowCount?: number | null;
     tables?: string[];
     errorMessage?: string | null;
-  }) => {
-    try {
-      const tablesValue = options.dialect.arrayToDb(event.tables ?? []);
-      await sql`
-        INSERT INTO sync_request_events (
-          event_type, actor_id, client_id, status_code, outcome,
-          duration_ms, commit_seq, operation_count, row_count,
-          tables, error_message, transport_path
-        ) VALUES (
-          ${event.eventType}, ${event.actorId}, ${event.clientId},
-          ${event.statusCode}, ${event.outcome}, ${event.durationMs},
-          ${event.commitSeq ?? null}, ${event.operationCount ?? null},
-          ${event.rowCount ?? null}, ${tablesValue}, ${event.errorMessage ?? null},
-          ${event.transportPath}
-        )
-      `.execute(options.db);
-    } catch {
-      // Silently ignore - event recording should not block sync
-    }
+  };
+
+  const recordRequestEvent = async (event: RequestEvent) => {
+    const tablesValue = options.dialect.arrayToDb(event.tables ?? []);
+    await sql`
+      INSERT INTO sync_request_events (
+        event_type, actor_id, client_id, status_code, outcome,
+        duration_ms, commit_seq, operation_count, row_count,
+        tables, error_message, transport_path
+      ) VALUES (
+        ${event.eventType}, ${event.actorId}, ${event.clientId},
+        ${event.statusCode}, ${event.outcome}, ${event.durationMs},
+        ${event.commitSeq ?? null}, ${event.operationCount ?? null},
+        ${event.rowCount ?? null}, ${tablesValue}, ${event.errorMessage ?? null},
+        ${event.transportPath}
+      )
+    `.execute(options.db);
+  };
+
+  const recordRequestEventInBackground = (event: RequestEvent): void => {
+    void recordRequestEvent(event).catch((error) => {
+      logAsyncFailureOnce('sync.request_event_record_failed', {
+        event: 'sync.request_event_record_failed',
+        userId: event.actorId,
+        clientId: event.clientId,
+        requestEventType: event.eventType,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    });
+  };
+
+  const authCache = new WeakMap<Context, Promise<SyncAuthResult | null>>();
+  const getAuth = (c: Context): Promise<SyncAuthResult | null> => {
+    const cached = authCache.get(c);
+    if (cached) return cached;
+    const pending = options.authenticate(c);
+    authCache.set(c, pending);
+    return pending;
   };
 
   // -------------------------------------------------------------------------
@@ -296,17 +345,52 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
       return createRateLimiter({
         ...limitConfig,
         keyGenerator: async (c) => {
-          const auth = await options.authenticate(c);
+          const auth = await getAuth(c);
           return auth?.actorId ?? null;
         },
       });
     };
 
     const pullLimiter = createAuthBasedRateLimiter(pullRateLimit);
-    if (pullLimiter) routes.use('/pull', pullLimiter);
-
     const pushLimiter = createAuthBasedRateLimiter(pushRateLimit);
-    if (pushLimiter) routes.use('/push', pushLimiter);
+
+    const syncRateLimiter: MiddlewareHandler = async (c, next) => {
+      if (!pullLimiter && !pushLimiter) return next();
+
+      let shouldApplyPull = pullLimiter !== null;
+      let shouldApplyPush = pushLimiter !== null;
+
+      if (pullLimiter && pushLimiter && c.req.method === 'POST') {
+        try {
+          const parsed = await c.req.raw.clone().json();
+          if (parsed !== null && typeof parsed === 'object') {
+            shouldApplyPull = Reflect.get(parsed, 'pull') !== undefined;
+            shouldApplyPush = Reflect.get(parsed, 'push') !== undefined;
+          }
+        } catch {
+          // Keep default behavior and apply both limiters when payload parsing fails.
+        }
+      }
+
+      if (pullLimiter && shouldApplyPull && pushLimiter && shouldApplyPush) {
+        return pullLimiter(c, async () => {
+          const pushResult = await pushLimiter(c, next);
+          if (pushResult instanceof Response) {
+            c.res = pushResult;
+          }
+        });
+      }
+      if (pullLimiter && shouldApplyPull) {
+        return pullLimiter(c, next);
+      }
+      if (pushLimiter && shouldApplyPush) {
+        return pushLimiter(c, next);
+      }
+
+      return next();
+    };
+
+    routes.use('/', syncRateLimiter);
   }
 
   // -------------------------------------------------------------------------
@@ -321,21 +405,23 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
   });
 
   // -------------------------------------------------------------------------
-  // POST /pull
+  // POST /  (combined push + pull in one round-trip)
   // -------------------------------------------------------------------------
 
   routes.post(
-    '/pull',
+    '/',
     describeRoute({
       tags: ['sync'],
-      summary: 'Pull commits and snapshots',
+      summary: 'Combined push and pull',
       description:
-        'Pull commits and optional bootstrap snapshots for subscriptions',
+        'Perform push and/or pull in a single request to reduce round-trips',
       responses: {
         200: {
-          description: 'Successful pull response',
+          description: 'Combined sync response',
           content: {
-            'application/json': { schema: resolver(SyncPullResponseSchema) },
+            'application/json': {
+              schema: resolver(SyncCombinedResponseSchema),
+            },
           },
         },
         400: {
@@ -352,190 +438,255 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
         },
       },
     }),
-    zValidator('json', SyncPullRequestSchema),
+    zValidator('json', SyncCombinedRequestSchema),
     async (c) => {
-      const auth = await options.authenticate(c);
+      const auth = await getAuth(c);
       if (!auth) return c.json({ error: 'UNAUTHENTICATED' }, 401);
+      const partitionId = auth.partitionId ?? 'default';
 
       const body = c.req.valid('json');
+      const clientId = body.clientId;
 
-      const timer = createSyncTimer();
+      let pushResponse:
+        | undefined
+        | Awaited<ReturnType<typeof pushCommit>>['response'];
+      let pullResponse: undefined | PullResult['response'];
 
-      if (body.subscriptions.length > maxSubscriptionsPerPull) {
-        return c.json(
-          {
-            error: 'INVALID_REQUEST',
-            message: `Too many subscriptions (max ${maxSubscriptionsPerPull})`,
-          },
-          400
-        );
-      }
-
-      // Guardrail: unique subscription ids in a single request.
-      const seenSubscriptionIds = new Set<string>();
-      for (const sub of body.subscriptions) {
-        const id = sub.id;
-        if (seenSubscriptionIds.has(id)) {
+      // --- Push phase ---
+      if (body.push) {
+        const pushOps = body.push.operations ?? [];
+        if (pushOps.length > maxOperationsPerPush) {
           return c.json(
             {
-              error: 'INVALID_REQUEST',
-              message: `Duplicate subscription id: ${id}`,
+              error: 'TOO_MANY_OPERATIONS',
+              message: `Maximum ${maxOperationsPerPush} operations per push`,
             },
             400
           );
         }
-        seenSubscriptionIds.add(id);
-      }
 
-      const request = {
-        clientId: body.clientId,
-        limitCommits: clampInt(body.limitCommits ?? 50, 1, maxPullLimitCommits),
-        limitSnapshotRows: clampInt(
-          body.limitSnapshotRows ?? 1000,
-          1,
-          maxPullLimitSnapshotRows
-        ),
-        maxSnapshotPages: clampInt(
-          body.maxSnapshotPages ?? 1,
-          1,
-          maxPullMaxSnapshotPages
-        ),
-        dedupeRows: body.dedupeRows === true,
-        subscriptions: body.subscriptions.map((sub) => ({
-          id: sub.id,
-          shape: sub.shape,
-          scopes: (sub.scopes ?? {}) as Record<string, string | string[]>,
-          params: sub.params as Record<string, unknown>,
-          cursor: Math.max(-1, sub.cursor),
-          bootstrapState: sub.bootstrapState ?? null,
-        })),
-      };
-
-      let pullResult: PullResult;
-      try {
-        pullResult = await pull({
+        const timer = createSyncTimer();
+
+        const pushed = await pushCommit({
           db: options.db,
           dialect: options.dialect,
-          shapes: handlerRegistry,
+          handlers: handlerRegistry,
           actorId: auth.actorId,
-          request,
-          chunkStorage: options.chunkStorage,
+          partitionId,
+          request: {
+            clientId,
+            clientCommitId: body.push.clientCommitId,
+            operations: body.push.operations,
+            schemaVersion: body.push.schemaVersion,
+          },
         });
-      } catch (err) {
-        if (err instanceof InvalidSubscriptionScopeError) {
-          return c.json(
-            { error: 'INVALID_SUBSCRIPTION', message: err.message },
-            400
+
+        const pushDurationMs = timer();
+
+        logSyncEvent({
+          event: 'sync.push',
+          userId: auth.actorId,
+          durationMs: pushDurationMs,
+          operationCount: pushOps.length,
+          status: pushed.response.status,
+          commitSeq: pushed.response.commitSeq,
+        });
+
+        recordRequestEventInBackground({
+          eventType: 'push',
+          actorId: auth.actorId,
+          clientId,
+          transportPath: readTransportPath(c),
+          statusCode: 200,
+          outcome: pushed.response.status,
+          durationMs: pushDurationMs,
+          commitSeq: pushed.response.commitSeq,
+          operationCount: pushOps.length,
+          tables: pushed.affectedTables,
+        });
+
+        // WS notifications
+        if (
+          wsConnectionManager &&
+          pushed.response.ok === true &&
+          pushed.response.status === 'applied' &&
+          typeof pushed.response.commitSeq === 'number'
+        ) {
+          const scopeKeys = applyPartitionToScopeKeys(
+            partitionId,
+            pushed.scopeKeys
           );
+          if (scopeKeys.length > 0) {
+            wsConnectionManager.notifyScopeKeys(
+              scopeKeys,
+              pushed.response.commitSeq,
+              {
+                excludeClientIds: [clientId],
+                changes: pushed.emittedChanges,
+              }
+            );
+
+            if (realtimeBroadcaster) {
+              realtimeBroadcaster
+                .publish({
+                  type: 'commit',
+                  commitSeq: pushed.response.commitSeq,
+                  partitionId,
+                  scopeKeys,
+                  sourceInstanceId: instanceId,
+                })
+                .catch((error) => {
+                  logAsyncFailureOnce(
+                    'sync.realtime.broadcast_publish_failed',
+                    {
+                      event: 'sync.realtime.broadcast_publish_failed',
+                      userId: auth.actorId,
+                      clientId,
+                      error:
+                        error instanceof Error ? error.message : String(error),
+                    }
+                  );
+                });
+            }
+          }
         }
-        throw err;
+
+        pushResponse = pushed.response;
       }
 
-      await recordClientCursor(options.db, options.dialect, {
-        clientId: request.clientId,
-        actorId: auth.actorId,
-        cursor: pullResult.clientCursor,
-        effectiveScopes: pullResult.effectiveScopes,
-      });
+      // --- Pull phase ---
+      if (body.pull) {
+        if (body.pull.subscriptions.length > maxSubscriptionsPerPull) {
+          return c.json(
+            {
+              error: 'INVALID_REQUEST',
+              message: `Too many subscriptions (max ${maxSubscriptionsPerPull})`,
+            },
+            400
+          );
+        }
 
-      // Update WebSocket manager with effective scopes for this client.
-      // Realtime wake-ups are best-effort; correctness always comes from pull+cursors.
-      wsConnectionManager?.updateClientScopeKeys(
-        request.clientId,
-        scopeValuesToScopeKeys(pullResult.effectiveScopes)
-      );
+        const seenSubscriptionIds = new Set<string>();
+        for (const sub of body.pull.subscriptions) {
+          const id = sub.id;
+          if (seenSubscriptionIds.has(id)) {
+            return c.json(
+              {
+                error: 'INVALID_REQUEST',
+                message: `Duplicate subscription id: ${id}`,
+              },
+              400
+            );
+          }
+          seenSubscriptionIds.add(id);
+        }
 
-      const pruneCfg = config.prune;
-      if (pruneCfg) {
-        const deletedCommits = await maybePruneSync(options.db, {
-          minIntervalMs: pruneCfg.minIntervalMs ?? 5 * 60 * 1000,
-          options: pruneCfg.options,
-        });
-        if (deletedCommits > 0) {
-          logSyncEvent({
-            event: 'sync.prune',
-            userId: auth.actorId,
-            deletedCommits,
+        const request = {
+          clientId,
+          limitCommits: clampInt(
+            body.pull.limitCommits ?? 50,
+            1,
+            maxPullLimitCommits
+          ),
+          limitSnapshotRows: clampInt(
+            body.pull.limitSnapshotRows ?? 1000,
+            1,
+            maxPullLimitSnapshotRows
+          ),
+          maxSnapshotPages: clampInt(
+            body.pull.maxSnapshotPages ?? 1,
+            1,
+            maxPullMaxSnapshotPages
+          ),
+          dedupeRows: body.pull.dedupeRows === true,
+          subscriptions: body.pull.subscriptions.map((sub) => ({
+            id: sub.id,
+            table: sub.table,
+            scopes: (sub.scopes ?? {}) as Record<string, string | string[]>,
+            params: sub.params as Record<string, unknown>,
+            cursor: Math.max(-1, sub.cursor),
+            bootstrapState: sub.bootstrapState ?? null,
+          })),
+        };
+
+        const timer = createSyncTimer();
+
+        let pullResult: PullResult;
+        try {
+          pullResult = await pull({
+            db: options.db,
+            dialect: options.dialect,
+            handlers: handlerRegistry,
+            actorId: auth.actorId,
+            partitionId,
+            request,
+            chunkStorage: options.chunkStorage,
           });
+        } catch (err) {
+          if (err instanceof InvalidSubscriptionScopeError) {
+            return c.json(
+              { error: 'INVALID_SUBSCRIPTION', message: err.message },
+              400
+            );
+          }
+          throw err;
         }
-      }
 
-      const compactCfg = config.compact;
-      if (compactCfg) {
-        const deletedChanges = await maybeCompactChanges(options.db, {
-          dialect: options.dialect,
-          minIntervalMs: compactCfg.minIntervalMs ?? 30 * 60 * 1000,
-          options: {
-            fullHistoryHours: compactCfg.options?.fullHistoryHours ?? 24 * 7,
-          },
-        });
-        if (deletedChanges > 0) {
-          logSyncEvent({
-            event: 'sync.compact',
+        // Fire-and-forget bookkeeping
+        void recordClientCursor(options.db, options.dialect, {
+          partitionId,
+          clientId,
+          actorId: auth.actorId,
+          cursor: pullResult.clientCursor,
+          effectiveScopes: pullResult.effectiveScopes,
+        }).catch((error) => {
+          logAsyncFailureOnce('sync.client_cursor_record_failed', {
+            event: 'sync.client_cursor_record_failed',
             userId: auth.actorId,
-            deletedChanges,
+            clientId,
+            error: error instanceof Error ? error.message : String(error),
           });
-        }
-      }
+        });
 
-      const rowCount = pullResult.response.subscriptions.reduce(
-        (sum: number, s) => {
-          if (s.bootstrap) {
-            return (
-              sum +
-              (s.snapshots ?? []).reduce(
-                (ss: number, snap) => ss + (snap.rows?.length ?? 0),
-                0
-              )
-            );
-          }
-          return (
-            sum +
-            s.commits.reduce(
-              (cs: number, commit) => cs + commit.changes.length,
-              0
-            )
-          );
-        },
-        0
-      );
+        wsConnectionManager?.updateClientScopeKeys(
+          clientId,
+          applyPartitionToScopeKeys(
+            partitionId,
+            scopeValuesToScopeKeys(pullResult.effectiveScopes)
+          )
+        );
 
-      const bootstrapCount = pullResult.response.subscriptions.filter(
-        (s) => s.bootstrap
-      ).length;
-      const activeCount = pullResult.response.subscriptions.filter(
-        (s) => s.status === 'active'
-      ).length;
+        const pullDurationMs = timer();
 
-      const pullDurationMs = timer();
+        logSyncEvent({
+          event: 'sync.pull',
+          userId: auth.actorId,
+          durationMs: pullDurationMs,
+          subscriptionCount: pullResult.response.subscriptions.length,
+          clientCursor: pullResult.clientCursor,
+        });
 
-      logSyncEvent({
-        event: 'sync.pull',
-        userId: auth.actorId,
-        durationMs: pullDurationMs,
-        rowCount,
-        subscriptionCount: pullResult.response.subscriptions.length,
-        activeSubscriptionCount: activeCount,
-        bootstrapCount,
-        effectiveTableCount: Object.keys(pullResult.effectiveScopes).length,
-        clientCursor: pullResult.clientCursor,
-      });
+        recordRequestEventInBackground({
+          eventType: 'pull',
+          actorId: auth.actorId,
+          clientId,
+          transportPath: readTransportPath(c),
+          statusCode: 200,
+          outcome: 'applied',
+          durationMs: pullDurationMs,
+        });
 
-      // Record event for console inspector (non-blocking)
-      recordRequestEvent({
-        eventType: 'pull',
-        actorId: auth.actorId,
-        clientId: request.clientId,
-        transportPath: readTransportPath(c),
-        statusCode: 200,
-        outcome:
-          bootstrapCount > 0 ? 'applied' : rowCount > 0 ? 'applied' : 'cached',
-        durationMs: pullDurationMs,
-        rowCount,
-        tables: Object.keys(pullResult.effectiveScopes),
-      });
+        pullResponse = pullResult.response;
+      }
 
-      return c.json(pullResult.response, 200);
+      return c.json(
+        {
+          ok: true as const,
+          ...(pushResponse ? { push: pushResponse } : {}),
+          ...(pullResponse ? { pull: pullResponse } : {}),
+        },
+        200
+      );
     }
   );
 
@@ -551,7 +702,12 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
       description: 'Download an encoded bootstrap snapshot chunk',
       responses: {
         200: {
-          description: 'Snapshot chunk data (gzip-compressed NDJSON)',
+          description: 'Snapshot chunk data (gzip-compressed framed JSON rows)',
+          content: {
+            'application/octet-stream': {
+              schema: resolver(z.string()),
+            },
+          },
         },
         304: {
           description: 'Not modified (cached)',
@@ -578,8 +734,9 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
     }),
     zValidator('param', snapshotChunkParamsSchema),
     async (c) => {
-      const auth = await options.authenticate(c);
+      const auth = await getAuth(c);
       if (!auth) return c.json({ error: 'UNAUTHENTICATED' }, 401);
+      const partitionId = auth.partitionId ?? 'default';
 
       const { chunkId } = c.req.valid('param');
 
@@ -587,6 +744,9 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
         chunkStorage: options.chunkStorage,
       });
       if (!chunk) return c.json({ error: 'NOT_FOUND' }, 404);
+      if (chunk.partitionId !== partitionId) {
+        return c.json({ error: 'FORBIDDEN' }, 403);
+      }
 
       const nowIso = new Date().toISOString();
       if (chunk.expiresAt <= nowIso) {
@@ -595,7 +755,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
 
       // Note: Snapshot chunks are created during authorized pull requests
       // and have opaque IDs that expire. Additional authorization is handled
-      // at the pull layer via shape-level resolveScopes.
+      // at the pull layer via table-level resolveScopes.
 
       const etag = `"sha256:${chunk.sha256}"`;
       const ifNoneMatch = c.req.header('if-none-match');
@@ -613,9 +773,9 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
       return new Response(chunk.body as BodyInit, {
         status: 200,
         headers: {
-          'Content-Type': 'application/x-ndjson; charset=utf-8',
+          'Content-Type': 'application/octet-stream',
           'Content-Encoding': 'gzip',
-          'Content-Length': String(chunk.body.length),
+          'Content-Length': String(chunk.byteLength),
           ETag: etag,
           'Cache-Control': 'private, max-age=0',
           Vary: 'Authorization',
@@ -628,134 +788,15 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
     }
   );
 
-  // -------------------------------------------------------------------------
-  // POST /push
-  // -------------------------------------------------------------------------
-
-  routes.post(
-    '/push',
-    describeRoute({
-      tags: ['sync'],
-      summary: 'Push a commit',
-      description: 'Push a client commit with operations to the server',
-      responses: {
-        200: {
-          description: 'Successful push response',
-          content: {
-            'application/json': { schema: resolver(SyncPushResponseSchema) },
-          },
-        },
-        400: {
-          description: 'Invalid request',
-          content: {
-            'application/json': { schema: resolver(ErrorResponseSchema) },
-          },
-        },
-        401: {
-          description: 'Unauthenticated',
-          content: {
-            'application/json': { schema: resolver(ErrorResponseSchema) },
-          },
-        },
-      },
-    }),
-    zValidator('json', SyncPushRequestSchema),
-    async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) return c.json({ error: 'UNAUTHENTICATED' }, 401);
-
-      const body = c.req.valid('json');
-
-      if (body.operations.length > maxOperationsPerPush) {
-        return c.json(
-          {
-            error: 'TOO_MANY_OPERATIONS',
-            message: `Maximum ${maxOperationsPerPush} operations per push`,
-          },
-          400
-        );
-      }
-
-      const timer = createSyncTimer();
-
-      const pushed = await pushCommit({
-        db: options.db,
-        dialect: options.dialect,
-        shapes: handlerRegistry,
-        actorId: auth.actorId,
-        request: body,
-      });
-
-      const pushDurationMs = timer();
-
-      logSyncEvent({
-        event: 'sync.push',
-        userId: auth.actorId,
-        durationMs: pushDurationMs,
-        operationCount: body.operations.length,
-        status: pushed.response.status,
-        commitSeq: pushed.response.commitSeq,
-      });
-
-      // Record event for console inspector (non-blocking)
-      recordRequestEvent({
-        eventType: 'push',
-        actorId: auth.actorId,
-        clientId: body.clientId,
-        transportPath: readTransportPath(c),
-        statusCode: 200,
-        outcome: pushed.response.status,
-        durationMs: pushDurationMs,
-        commitSeq: pushed.response.commitSeq,
-        operationCount: body.operations.length,
-        tables: pushed.affectedTables,
-      });
-
-      if (
-        wsConnectionManager &&
-        pushed.response.ok === true &&
-        pushed.response.status === 'applied' &&
-        typeof pushed.response.commitSeq === 'number'
-      ) {
-        const scopeKeys = await readCommitScopeKeys(
-          options.db,
-          pushed.response.commitSeq
-        );
-
-        if (scopeKeys.length > 0) {
-          wsConnectionManager.notifyScopeKeys(
-            scopeKeys,
-            pushed.response.commitSeq,
-            {
-              excludeClientIds: [body.clientId],
-            }
-          );
-
-          if (realtimeBroadcaster) {
-            realtimeBroadcaster
-              .publish({
-                type: 'commit',
-                commitSeq: pushed.response.commitSeq,
-                scopeKeys,
-                sourceInstanceId: instanceId,
-              })
-              .catch(() => {});
-          }
-        }
-      }
-
-      return c.json(pushed.response, 200);
-    }
-  );
-
   // -------------------------------------------------------------------------
   // GET /realtime (optional WebSocket wake-ups)
   // -------------------------------------------------------------------------
 
   if (wsConnectionManager && websocketConfig?.enabled) {
     routes.get('/realtime', async (c) => {
-      const auth = await options.authenticate(c);
+      const auth = await getAuth(c);
       if (!auth) return c.json({ error: 'UNAUTHENTICATED' }, 401);
+      const partitionId = auth.partitionId ?? 'default';
 
       const clientId = c.req.query('clientId');
       if (!clientId || typeof clientId !== 'string') {
@@ -787,6 +828,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
 
         const row = await cursorsQ
           .selectAll()
+          .where(sql<SqlBool>`partition_id = ${partitionId}`)
           .where(sql<SqlBool>`client_id = ${clientId}`)
           .executeTakeFirst();
 
@@ -804,7 +846,10 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
           }
         }
 
-        initialScopeKeys = scopeValuesToScopeKeys(parsed);
+        initialScopeKeys = applyPartitionToScopeKeys(
+          partitionId,
+          scopeValuesToScopeKeys(parsed)
+        );
       } catch {
         // ignore; realtime is best-effort
       }
@@ -884,15 +929,26 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
             const raw =
               typeof evt.data === 'string' ? evt.data : String(evt.data);
             const msg = JSON.parse(raw);
-            if (
-              !msg ||
-              typeof msg !== 'object' ||
-              msg.type !== 'presence' ||
-              !msg.scopeKey
-            )
+            if (!msg || typeof msg !== 'object') return;
+
+            if (msg.type === 'push') {
+              void handleWsPush(
+                msg,
+                connRef,
+                auth.actorId,
+                partitionId,
+                clientId
+              );
               return;
+            }
 
-            const scopeKey = String(msg.scopeKey);
+            if (msg.type !== 'presence' || !msg.scopeKey) return;
+
+            const scopeKey = normalizeScopeKeyForPartition(
+              partitionId,
+              String(msg.scopeKey)
+            );
+            if (!scopeKey) return;
 
             switch (msg.action) {
               case 'join':
@@ -961,14 +1017,167 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
     if (event.sourceInstanceId && event.sourceInstanceId === instanceId) return;
 
     const commitSeq = event.commitSeq;
+    const partitionId = event.partitionId ?? 'default';
     const scopeKeys =
       event.scopeKeys && event.scopeKeys.length > 0
         ? event.scopeKeys
-        : await readCommitScopeKeys(options.db, commitSeq);
+        : await readCommitScopeKeys(options.db, commitSeq, partitionId);
 
     if (scopeKeys.length === 0) return;
     wsConnectionManager.notifyScopeKeys(scopeKeys, commitSeq);
   }
+
+  async function handleWsPush(
+    msg: Record<string, unknown>,
+    conn: WebSocketConnection,
+    actorId: string,
+    partitionId: string,
+    clientId: string
+  ): Promise<void> {
+    const requestId = typeof msg.requestId === 'string' ? msg.requestId : '';
+    if (!requestId) return;
+
+    try {
+      // Validate the push payload
+      const parsed = SyncPushRequestSchema.omit({ clientId: true }).safeParse(
+        msg
+      );
+      if (!parsed.success) {
+        conn.sendPushResponse({
+          requestId,
+          ok: false,
+          status: 'rejected',
+          results: [
+            { opIndex: 0, status: 'error', error: 'Invalid push payload' },
+          ],
+        });
+        return;
+      }
+
+      const pushOps = parsed.data.operations ?? [];
+      if (pushOps.length > maxOperationsPerPush) {
+        conn.sendPushResponse({
+          requestId,
+          ok: false,
+          status: 'rejected',
+          results: [
+            {
+              opIndex: 0,
+              status: 'error',
+              error: `Maximum ${maxOperationsPerPush} operations per push`,
+            },
+          ],
+        });
+        return;
+      }
+
+      const timer = createSyncTimer();
+
+      const pushed = await pushCommit({
+        db: options.db,
+        dialect: options.dialect,
+        handlers: handlerRegistry,
+        actorId,
+        partitionId,
+        request: {
+          clientId,
+          clientCommitId: parsed.data.clientCommitId,
+          operations: parsed.data.operations,
+          schemaVersion: parsed.data.schemaVersion,
+        },
+      });
+
+      const pushDurationMs = timer();
+
+      logSyncEvent({
+        event: 'sync.push',
+        userId: actorId,
+        durationMs: pushDurationMs,
+        operationCount: pushOps.length,
+        status: pushed.response.status,
+        commitSeq: pushed.response.commitSeq,
+      });
+
+      recordRequestEventInBackground({
+        eventType: 'push',
+        actorId,
+        clientId,
+        transportPath: conn.transportPath,
+        statusCode: 200,
+        outcome: pushed.response.status,
+        durationMs: pushDurationMs,
+        commitSeq: pushed.response.commitSeq,
+        operationCount: pushOps.length,
+        tables: pushed.affectedTables,
+      });
+
+      // WS notifications to other clients
+      if (
+        wsConnectionManager &&
+        pushed.response.ok === true &&
+        pushed.response.status === 'applied' &&
+        typeof pushed.response.commitSeq === 'number'
+      ) {
+        const scopeKeys = applyPartitionToScopeKeys(
+          partitionId,
+          pushed.scopeKeys
+        );
+        if (scopeKeys.length > 0) {
+          wsConnectionManager.notifyScopeKeys(
+            scopeKeys,
+            pushed.response.commitSeq,
+            {
+              excludeClientIds: [clientId],
+              changes: pushed.emittedChanges,
+            }
+          );
+
+          if (realtimeBroadcaster) {
+            realtimeBroadcaster
+              .publish({
+                type: 'commit',
+                commitSeq: pushed.response.commitSeq,
+                partitionId,
+                scopeKeys,
+                sourceInstanceId: instanceId,
+              })
+              .catch((error) => {
+                logAsyncFailureOnce('sync.realtime.broadcast_publish_failed', {
+                  event: 'sync.realtime.broadcast_publish_failed',
+                  userId: actorId,
+                  clientId,
+                  error: error instanceof Error ? error.message : String(error),
+                });
+              });
+          }
+        }
+      }
+
+      conn.sendPushResponse({
+        requestId,
+        ok: pushed.response.ok,
+        status: pushed.response.status,
+        commitSeq: pushed.response.commitSeq,
+        results: pushed.response.results,
+      });
+    } catch (err) {
+      captureSyncException(err, {
+        event: 'sync.realtime.push_failed',
+        requestId,
+        clientId,
+        actorId,
+        partitionId,
+      });
+      const message =
+        err instanceof Error ? err.message : 'Internal server error';
+      conn.sendPushResponse({
+        requestId,
+        ok: false,
+        status: 'rejected',
+        results: [{ opIndex: 0, status: 'error', error: message }],
+      });
+    }
+  }
 }
 
 export function getSyncWebSocketConnectionManager(
@@ -1035,15 +1244,46 @@ function scopeValuesToScopeKeys(scopes: unknown): string[] {
   return Array.from(scopeKeys);
 }
 
+function partitionScopeKey(partitionId: string, scopeKey: string): string {
+  return `${partitionId}::${scopeKey}`;
+}
+
+function applyPartitionToScopeKeys(
+  partitionId: string,
+  scopeKeys: readonly string[]
+): string[] {
+  const prefixed = new Set<string>();
+  for (const scopeKey of scopeKeys) {
+    if (!scopeKey) continue;
+    if (scopeKey.startsWith(`${partitionId}::`)) {
+      prefixed.add(scopeKey);
+      continue;
+    }
+    prefixed.add(partitionScopeKey(partitionId, scopeKey));
+  }
+  return Array.from(prefixed);
+}
+
+function normalizeScopeKeyForPartition(
+  partitionId: string,
+  scopeKey: string
+): string {
+  if (scopeKey.startsWith(`${partitionId}::`)) return scopeKey;
+  if (scopeKey.includes('::')) return '';
+  return partitionScopeKey(partitionId, scopeKey);
+}
+
 async function readCommitScopeKeys<DB extends SyncCoreDb>(
   db: Kysely<DB>,
-  commitSeq: number
+  commitSeq: number,
+  partitionId: string
 ): Promise<string[]> {
   // Read scopes from the JSONB column and convert to scope strings
   const rowsResult = await sql<{ scopes: unknown }>`
     select scopes
     from ${sql.table('sync_changes')}
     where commit_seq = ${commitSeq}
+      and partition_id = ${partitionId}
   `.execute(db);
   const rows = rowsResult.rows;
 
@@ -1053,7 +1293,10 @@ async function readCommitScopeKeys<DB extends SyncCoreDb>(
     const scopes =
       typeof row.scopes === 'string' ? JSON.parse(row.scopes) : row.scopes;
 
-    for (const k of scopeValuesToScopeKeys(scopes)) {
+    for (const k of applyPartitionToScopeKeys(
+      partitionId,
+      scopeValuesToScopeKeys(scopes)
+    )) {
       scopeKeys.add(k);
     }
   }