@syncular/server-hono 0.0.1 → 0.0.2-126

package/dist/routes.js

@@ -2,19 +2,18 @@
  * @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 { createSyncTimer, ErrorResponseSchema, logSyncEvent, SyncPullRequestSchema, SyncPullResponseSchema, SyncPushRequestSchema, SyncPushResponseSchema, } from '@syncular/core';
-import { InvalidSubscriptionScopeError, maybeCompactChanges, maybePruneSync, pull, pushCommit, readSnapshotChunk, recordClientCursor, TableRegistry, } from '@syncular/server';
+import { captureSyncException, createSyncTimer, ErrorResponseSchema, logSyncEvent, SyncCombinedRequestSchema, SyncCombinedResponseSchema, SyncPushRequestSchema, } from '@syncular/core';
+import { InvalidSubscriptionScopeError, pull, pushCommit, readSnapshotChunk, recordClientCursor, TableRegistry, } from '@syncular/server';
 import { Hono } from 'hono';
 import { describeRoute, resolver, validator as zValidator } from 'hono-openapi';
 import { sql, } from 'kysely';
 import { z } from 'zod';
-import { createRateLimiter, DEFAULT_SYNC_RATE_LIMITS, } from './rate-limit';
-import { createWebSocketConnection, WebSocketConnectionManager } from './ws';
+import { createRateLimiter, DEFAULT_SYNC_RATE_LIMITS, } from './rate-limit.js';
+import { createWebSocketConnection, WebSocketConnectionManager, } from './ws.js';
 /**
  * WeakMaps for storing Hono-instance-specific data without augmenting the type.
  */
@@ -28,6 +27,14 @@ const snapshotChunkParamsSchema = z.object({
 });
 export function createSyncRoutes(options) {
     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();
     for (const handler of options.handlers) {
         handlerRegistry.register(handler);
@@ -62,35 +69,60 @@ export function createSyncRoutes(options) {
         (typeof crypto !== 'undefined' && 'randomUUID' in crypto
             ? crypto.randomUUID()
             : `${Date.now()}-${Math.random().toString(16).slice(2)}`);
+    const loggedAsyncFailureKeys = new Set();
+    const logAsyncFailureOnce = (key, event) => {
+        if (loggedAsyncFailureKeys.has(key))
+            return;
+        loggedAsyncFailureKeys.add(key);
+        logSyncEvent(event);
+    };
     if (wsConnectionManager && realtimeBroadcaster) {
         const unsubscribe = realtimeBroadcaster.subscribe((event) => {
-            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,
+                });
+            });
         });
         realtimeUnsubscribeMap.set(routes, unsubscribe);
     }
-    // -------------------------------------------------------------------------
-    // Request event recording (for console inspector)
-    // -------------------------------------------------------------------------
     const recordRequestEvent = async (event) => {
-        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 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) => {
+        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();
+    const getAuth = (c) => {
+        const cached = authCache.get(c);
+        if (cached)
+            return cached;
+        const pending = options.authenticate(c);
+        authCache.set(c, pending);
+        return pending;
     };
     // -------------------------------------------------------------------------
     // Rate limiting (optional)
@@ -105,17 +137,47 @@ export function createSyncRoutes(options) {
             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 = 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);
     }
     // -------------------------------------------------------------------------
     // GET /health
@@ -127,17 +189,19 @@ export function createSyncRoutes(options) {
         });
     });
     // -------------------------------------------------------------------------
-    // POST /pull
+    // POST /  (combined push + pull in one round-trip)
     // -------------------------------------------------------------------------
-    routes.post('/pull', describeRoute({
+    routes.post('/', describeRoute({
         tags: ['sync'],
-        summary: 'Pull commits and snapshots',
-        description: 'Pull commits and optional bootstrap snapshots for subscriptions',
+        summary: 'Combined push and pull',
+        description: '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: {
@@ -153,137 +217,185 @@ export function createSyncRoutes(options) {
                 },
             },
         },
-    }), zValidator('json', SyncPullRequestSchema), async (c) => {
-        const auth = await options.authenticate(c);
+    }), zValidator('json', SyncCombinedRequestSchema), async (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 timer = createSyncTimer();
-        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();
-        for (const sub of body.subscriptions) {
-            const id = sub.id;
-            if (seenSubscriptionIds.has(id)) {
+        const clientId = body.clientId;
+        let pushResponse;
+        let pullResponse;
+        // --- 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 ?? {}),
-                params: sub.params,
-                cursor: Math.max(-1, sub.cursor),
-                bootstrapState: sub.bootstrapState ?? null,
-            })),
-        };
-        let 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,
-        });
-        // 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 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,
+        // --- Pull phase ---
+        if (body.pull) {
+            if (body.pull.subscriptions.length > maxSubscriptionsPerPull) {
+                return c.json({
+                    error: 'INVALID_REQUEST',
+                    message: `Too many subscriptions (max ${maxSubscriptionsPerPull})`,
+                }, 400);
+            }
+            const seenSubscriptionIds = new Set();
+            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 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 ?? {}),
+                    params: sub.params,
+                    cursor: Math.max(-1, sub.cursor),
+                    bootstrapState: sub.bootstrapState ?? null,
+                })),
+            };
+            const timer = createSyncTimer();
+            let pullResult;
+            try {
+                pullResult = await pull({
+                    db: options.db,
+                    dialect: options.dialect,
+                    handlers: handlerRegistry,
+                    actorId: auth.actorId,
+                    partitionId,
+                    request,
+                    chunkStorage: options.chunkStorage,
                 });
             }
-        }
-        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',
+            catch (err) {
+                if (err instanceof InvalidSubscriptionScopeError) {
+                    return c.json({ error: 'INVALID_SUBSCRIPTION', message: err.message }, 400);
+                }
+                throw err;
+            }
+            // 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),
                 });
-            }
+            });
+            wsConnectionManager?.updateClientScopeKeys(clientId, applyPartitionToScopeKeys(partitionId, scopeValuesToScopeKeys(pullResult.effectiveScopes)));
+            const pullDurationMs = timer();
+            logSyncEvent({
+                event: 'sync.pull',
+                userId: auth.actorId,
+                durationMs: pullDurationMs,
+                subscriptionCount: pullResult.response.subscriptions.length,
+                clientCursor: pullResult.clientCursor,
+            });
+            recordRequestEventInBackground({
+                eventType: 'pull',
+                actorId: auth.actorId,
+                clientId,
+                transportPath: readTransportPath(c),
+                statusCode: 200,
+                outcome: 'applied',
+                durationMs: pullDurationMs,
+            });
+            pullResponse = pullResult.response;
         }
-        const rowCount = pullResult.response.subscriptions.reduce((sum, s) => {
-            if (s.bootstrap) {
-                return (sum +
-                    (s.snapshots ?? []).reduce((ss, snap) => ss + (snap.rows?.length ?? 0), 0));
-            }
-            return (sum +
-                s.commits.reduce((cs, commit) => cs + commit.changes.length, 0));
-        }, 0);
-        const bootstrapCount = pullResult.response.subscriptions.filter((s) => s.bootstrap).length;
-        const activeCount = pullResult.response.subscriptions.filter((s) => s.status === 'active').length;
-        const pullDurationMs = timer();
-        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,
-        });
-        // 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),
-        });
-        return c.json(pullResult.response, 200);
+        return c.json({
+            ok: true,
+            ...(pushResponse ? { push: pushResponse } : {}),
+            ...(pullResponse ? { pull: pullResponse } : {}),
+        }, 200);
     });
     // -------------------------------------------------------------------------
     // GET /snapshot-chunks/:chunkId
@@ -294,7 +406,12 @@ export function createSyncRoutes(options) {
         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)',
@@ -319,22 +436,26 @@ export function createSyncRoutes(options) {
             },
         },
     }), 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');
         const chunk = await readSnapshotChunk(options.db, chunkId, {
             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) {
             return c.json({ error: 'NOT_FOUND' }, 404);
         }
         // 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');
         if (ifNoneMatch && ifNoneMatch === etag) {
@@ -350,9 +471,9 @@ export function createSyncRoutes(options) {
         return new Response(chunk.body, {
             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',
@@ -364,104 +485,14 @@ export function createSyncRoutes(options) {
         });
     });
     // -------------------------------------------------------------------------
-    // 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') {
                 return c.json({
@@ -477,6 +508,7 @@ export function createSyncRoutes(options) {
                 const cursorsQ = options.db.selectFrom('sync_client_cursors');
                 const row = await cursorsQ
                     .selectAll()
+                    .where(sql `partition_id = ${partitionId}`)
                     .where(sql `client_id = ${clientId}`)
                     .executeTakeFirst();
                 if (row && row.actor_id !== auth.actorId) {
@@ -492,7 +524,7 @@ export function createSyncRoutes(options) {
                         parsed = null;
                     }
                 }
-                initialScopeKeys = scopeValuesToScopeKeys(parsed);
+                initialScopeKeys = applyPartitionToScopeKeys(partitionId, scopeValuesToScopeKeys(parsed));
             }
             catch {
                 // ignore; realtime is best-effort
@@ -560,12 +592,17 @@ export function createSyncRoutes(options) {
                     try {
                         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;
+                        }
+                        if (msg.type !== 'presence' || !msg.scopeKey)
+                            return;
+                        const scopeKey = normalizeScopeKeyForPartition(partitionId, String(msg.scopeKey));
+                        if (!scopeKey)
                             return;
-                        const scopeKey = String(msg.scopeKey);
                         switch (msg.action) {
                             case 'join':
                                 if (!wsConnectionManager.joinPresence(clientId, scopeKey, msg.metadata)) {
@@ -619,13 +656,139 @@ export function createSyncRoutes(options) {
         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, conn, actorId, partitionId, clientId) {
+        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(routes) {
     return wsConnectionManagerMap.get(routes);
@@ -677,18 +840,42 @@ function scopeValuesToScopeKeys(scopes) {
     }
     return Array.from(scopeKeys);
 }
-async function readCommitScopeKeys(db, commitSeq) {
+function partitionScopeKey(partitionId, scopeKey) {
+    return `${partitionId}::${scopeKey}`;
+}
+function applyPartitionToScopeKeys(partitionId, scopeKeys) {
+    const prefixed = new Set();
+    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, scopeKey) {
+    if (scopeKey.startsWith(`${partitionId}::`))
+        return scopeKey;
+    if (scopeKey.includes('::'))
+        return '';
+    return partitionScopeKey(partitionId, scopeKey);
+}
+async function readCommitScopeKeys(db, commitSeq, partitionId) {
     // Read scopes from the JSONB column and convert to scope strings
     const rowsResult = await sql `
     select scopes
     from ${sql.table('sync_changes')}
     where commit_seq = ${commitSeq}
+      and partition_id = ${partitionId}
   `.execute(db);
     const rows = rowsResult.rows;
     const scopeKeys = new Set();
     for (const row of rows) {
         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);
         }
     }