@syncular/server 0.0.6-185 → 0.0.6-201

package/src/push.ts

@@ -7,20 +7,14 @@ import {
   type SyncPushResponse,
   startSyncSpan,
 } from '@syncular/core';
-import type {
-  Insertable,
-  Kysely,
-  SelectQueryBuilder,
-  SqlBool,
-  Updateable,
-} from 'kysely';
+import type { Insertable, Kysely, SelectQueryBuilder, SqlBool } from 'kysely';
 import { sql } from 'kysely';
 import {
   coerceNumber,
   parseJsonValue,
   toDialectJsonValue,
 } from './dialect/helpers';
-import type { ServerSyncDialect } from './dialect/types';
+import type { DbExecutor, ServerSyncDialect } from './dialect/types';
 import type { ServerHandlerCollection } from './handlers/collection';
 import type { SyncServerAuth } from './handlers/types';
 import {
@@ -31,6 +25,10 @@ import type { SyncCoreDb } from './schema';
 
 // biome-ignore lint/complexity/noBannedTypes: Kysely uses `{}` as the initial "no selected columns yet" marker.
 type EmptySelection = {};
+type SyncMetadataTrx = Pick<
+  Kysely<SyncCoreDb>,
+  'selectFrom' | 'insertInto' | 'updateTable' | 'deleteFrom'
+>;
 
 export interface PushCommitResult {
   response: SyncPushResponse;
@@ -102,7 +100,7 @@ function assertOperationIdentityUnchanged(
 }
 
 async function readCommitAffectedTables<DB extends SyncCoreDb>(
-  db: Kysely<DB>,
+  db: DbExecutor<DB>,
   dialect: ServerSyncDialect,
   commitSeq: number,
   partitionId: string
@@ -185,6 +183,588 @@ function recordPushMetrics(args: {
   );
 }
 
+function createRejectedPushResult(
+  error: SyncPushResponse['results'][number]
+): PushCommitResult {
+  return {
+    response: {
+      ok: true,
+      status: 'rejected',
+      results: [error],
+    },
+    affectedTables: [],
+    scopeKeys: [],
+    emittedChanges: [],
+    commitActorId: null,
+    commitCreatedAt: null,
+  };
+}
+
+function createRejectedPushResponse(
+  error: SyncPushResponse['results'][number],
+  commitSeq?: number
+): SyncPushResponse {
+  return {
+    ok: true,
+    status: 'rejected',
+    ...(commitSeq !== undefined ? { commitSeq } : {}),
+    results: [error],
+  };
+}
+
+function validatePushRequest(
+  request: SyncPushRequest
+): SyncPushResponse['results'][number] | null {
+  if (!request.clientId || !request.clientCommitId) {
+    return {
+      opIndex: 0,
+      status: 'error',
+      error: 'INVALID_REQUEST',
+      code: 'INVALID_REQUEST',
+      retriable: false,
+    };
+  }
+
+  const ops = request.operations ?? [];
+  if (!Array.isArray(ops) || ops.length === 0) {
+    return {
+      opIndex: 0,
+      status: 'error',
+      error: 'EMPTY_COMMIT',
+      code: 'EMPTY_COMMIT',
+      retriable: false,
+    };
+  }
+
+  return null;
+}
+
+function shouldUseSavepoints<
+  DB extends SyncCoreDb,
+  Auth extends SyncServerAuth,
+>(args: {
+  dialect: ServerSyncDialect;
+  handlers: ServerHandlerCollection<DB, Auth>;
+  operations: SyncPushRequest['operations'];
+}): boolean {
+  if (!args.dialect.supportsSavepoints) {
+    return false;
+  }
+
+  if ((args.operations?.length ?? 0) !== 1) {
+    return true;
+  }
+
+  const singleOp = args.operations?.[0];
+  if (!singleOp) {
+    return true;
+  }
+
+  const singleOpHandler = args.handlers.byTable.get(singleOp.table);
+  if (!singleOpHandler) {
+    throw new Error(`Unknown table: ${singleOp.table}`);
+  }
+
+  return !singleOpHandler.canRejectSingleOperationWithoutSavepoint;
+}
+
+async function persistEmittedChanges<DB extends SyncCoreDb>(args: {
+  trx: DbExecutor<DB>;
+  dialect: ServerSyncDialect;
+  partitionId: string;
+  commitSeq: number;
+  emittedChanges: PushCommitResult['emittedChanges'];
+}): Promise<void> {
+  if (args.emittedChanges.length === 0) {
+    return;
+  }
+
+  const syncTrx = args.trx as Pick<Kysely<SyncCoreDb>, 'insertInto'>;
+  const changeRows: Array<Insertable<SyncCoreDb['sync_changes']>> =
+    args.emittedChanges.map((change) => ({
+      partition_id: args.partitionId,
+      commit_seq: args.commitSeq,
+      table: change.table,
+      row_id: change.row_id,
+      op: change.op,
+      row_json: toDialectJsonValue(args.dialect, change.row_json),
+      row_version: change.row_version,
+      scopes: args.dialect.scopesToDb(change.scopes),
+    }));
+
+  await syncTrx.insertInto('sync_changes').values(changeRows).execute();
+}
+
+async function persistCommitOutcome<DB extends SyncCoreDb>(args: {
+  trx: DbExecutor<DB>;
+  dialect: ServerSyncDialect;
+  partitionId: string;
+  commitSeq: number;
+  response: SyncPushResponse;
+  affectedTables: string[];
+  emittedChangeCount: number;
+}): Promise<void> {
+  const syncTrx = args.trx as Pick<
+    Kysely<SyncCoreDb>,
+    'insertInto' | 'updateTable'
+  >;
+
+  await syncTrx
+    .updateTable('sync_commits')
+    .set({
+      result_json: toDialectJsonValue(args.dialect, args.response),
+      change_count: args.emittedChangeCount,
+      affected_tables: args.dialect.arrayToDb(args.affectedTables) as string[],
+    })
+    .where('commit_seq', '=', args.commitSeq)
+    .execute();
+
+  if (args.affectedTables.length === 0) {
+    return;
+  }
+
+  await syncTrx
+    .insertInto('sync_table_commits')
+    .values(
+      args.affectedTables.map((table) => ({
+        partition_id: args.partitionId,
+        table,
+        commit_seq: args.commitSeq,
+      }))
+    )
+    .onConflict((oc) =>
+      oc.columns(['partition_id', 'table', 'commit_seq']).doNothing()
+    )
+    .execute();
+}
+
+async function loadExistingCommitResult<DB extends SyncCoreDb>(args: {
+  trx: DbExecutor<DB>;
+  syncTrx: SyncMetadataTrx;
+  dialect: ServerSyncDialect;
+  request: SyncPushRequest;
+  partitionId: string;
+}): Promise<PushCommitResult> {
+  let query = (
+    args.syncTrx.selectFrom('sync_commits') as SelectQueryBuilder<
+      SyncCoreDb,
+      'sync_commits',
+      EmptySelection
+    >
+  )
+    .selectAll()
+    .where('partition_id', '=', args.partitionId)
+    .where('client_id', '=', args.request.clientId)
+    .where('client_commit_id', '=', args.request.clientCommitId);
+
+  if (args.dialect.supportsForUpdate) {
+    query = query.forUpdate();
+  }
+
+  const existing = await query.executeTakeFirstOrThrow();
+  const parsedCached = parseJsonValue(existing.result_json);
+
+  if (!isSyncPushResponse(parsedCached)) {
+    return createRejectedPushResult({
+      opIndex: 0,
+      status: 'error',
+      error: 'IDEMPOTENCY_CACHE_MISS',
+      code: 'INTERNAL',
+      retriable: true,
+    });
+  }
+
+  const base: SyncPushResponse = {
+    ...parsedCached,
+    commitSeq: Number(existing.commit_seq),
+  };
+
+  if (parsedCached.status === 'applied') {
+    const tablesFromDb = args.dialect.dbToArray(existing.affected_tables);
+    return {
+      response: { ...base, status: 'cached' },
+      affectedTables:
+        tablesFromDb.length > 0
+          ? tablesFromDb
+          : await readCommitAffectedTables(
+              args.trx,
+              args.dialect,
+              Number(existing.commit_seq),
+              args.partitionId
+            ),
+      scopeKeys: [],
+      emittedChanges: [],
+      commitActorId:
+        typeof existing.actor_id === 'string' ? existing.actor_id : null,
+      commitCreatedAt:
+        typeof existing.created_at === 'string' ? existing.created_at : null,
+    };
+  }
+
+  return {
+    response: base,
+    affectedTables: [],
+    scopeKeys: [],
+    emittedChanges: [],
+    commitActorId:
+      typeof existing.actor_id === 'string' ? existing.actor_id : null,
+    commitCreatedAt:
+      typeof existing.created_at === 'string' ? existing.created_at : null,
+  };
+}
+
+async function insertPendingCommit(args: {
+  syncTrx: SyncMetadataTrx;
+  dialect: ServerSyncDialect;
+  commitRow: Insertable<SyncCoreDb['sync_commits']>;
+}): Promise<number | null> {
+  if (args.dialect.supportsInsertReturning) {
+    const insertedCommit = await args.syncTrx
+      .insertInto('sync_commits')
+      .values(args.commitRow)
+      .onConflict((oc) =>
+        oc
+          .columns(['partition_id', 'client_id', 'client_commit_id'])
+          .doNothing()
+      )
+      .returning(['commit_seq'])
+      .executeTakeFirst();
+
+    if (!insertedCommit) {
+      return null;
+    }
+
+    return coerceNumber(insertedCommit.commit_seq) ?? 0;
+  }
+
+  const insertResult = await args.syncTrx
+    .insertInto('sync_commits')
+    .values(args.commitRow)
+    .onConflict((oc) =>
+      oc.columns(['partition_id', 'client_id', 'client_commit_id']).doNothing()
+    )
+    .executeTakeFirstOrThrow();
+
+  const insertedRows = Number(insertResult.numInsertedOrUpdatedRows ?? 0);
+  if (insertedRows === 0) {
+    return null;
+  }
+
+  return coerceNumber(insertResult.insertId) ?? 0;
+}
+
+async function applyCommitOperations<
+  DB extends SyncCoreDb,
+  Auth extends SyncServerAuth,
+>(args: {
+  trx: DbExecutor<DB>;
+  handlers: ServerHandlerCollection<DB, Auth>;
+  pushPlugins: readonly SyncServerPushPlugin<DB, Auth>[];
+  auth: Auth;
+  request: SyncPushRequest;
+  actorId: string;
+  commitId: string;
+  commitSeq: number;
+}): Promise<{
+  results: SyncPushResponse['results'];
+  emittedChanges: PushCommitResult['emittedChanges'];
+  affectedTables: string[];
+}> {
+  const ops = args.request.operations ?? [];
+  const allEmitted: PushCommitResult['emittedChanges'] = [];
+  const results: SyncPushResponse['results'] = [];
+  const affectedTablesSet = new Set<string>();
+
+  for (let i = 0; i < ops.length; ) {
+    const op = ops[i]!;
+    const handler = args.handlers.byTable.get(op.table);
+    if (!handler) {
+      throw new Error(`Unknown table: ${op.table}`);
+    }
+
+    const operationCtx = {
+      db: args.trx,
+      trx: args.trx,
+      actorId: args.actorId,
+      auth: args.auth,
+      clientId: args.request.clientId,
+      commitId: args.commitId,
+      schemaVersion: args.request.schemaVersion,
+    };
+
+    let transformedOp = op;
+    for (const plugin of args.pushPlugins) {
+      if (!plugin.beforeApplyOperation) continue;
+      const nextOp = await plugin.beforeApplyOperation({
+        ctx: operationCtx,
+        tableHandler: handler,
+        op: transformedOp,
+        opIndex: i,
+      });
+      assertOperationIdentityUnchanged(plugin.name, op, nextOp);
+      transformedOp = nextOp;
+    }
+
+    let appliedBatch:
+      | Awaited<ReturnType<typeof handler.applyOperation>>[]
+      | null = null;
+    let consumed = 1;
+
+    if (args.pushPlugins.length === 0 && handler.applyOperationBatch) {
+      const batchInput = [];
+      for (let j = i; j < ops.length; j++) {
+        const nextOp = ops[j]!;
+        if (nextOp.table !== op.table) break;
+        batchInput.push({ op: nextOp, opIndex: j });
+      }
+
+      if (batchInput.length > 1) {
+        appliedBatch = await handler.applyOperationBatch(
+          operationCtx,
+          batchInput
+        );
+        consumed = Math.max(1, appliedBatch.length);
+      }
+    }
+
+    if (!appliedBatch) {
+      let appliedSingle = await handler.applyOperation(
+        operationCtx,
+        transformedOp,
+        i
+      );
+
+      for (const plugin of args.pushPlugins) {
+        if (!plugin.afterApplyOperation) continue;
+        appliedSingle = await plugin.afterApplyOperation({
+          ctx: operationCtx,
+          tableHandler: handler,
+          op: transformedOp,
+          opIndex: i,
+          applied: appliedSingle,
+        });
+      }
+
+      appliedBatch = [appliedSingle];
+    }
+
+    if (appliedBatch.length === 0) {
+      throw new Error(
+        `Handler "${op.table}" returned no results from applyOperationBatch`
+      );
+    }
+
+    for (const applied of appliedBatch) {
+      if (applied.result.status !== 'applied') {
+        results.push(applied.result);
+        throw new RejectCommitError(
+          createRejectedPushResponse(applied.result, args.commitSeq)
+        );
+      }
+
+      for (const change of applied.emittedChanges ?? []) {
+        const scopes = change?.scopes;
+        if (!scopes || typeof scopes !== 'object') {
+          const error: SyncPushResponse['results'][number] = {
+            opIndex: applied.result.opIndex,
+            status: 'error',
+            error: 'MISSING_SCOPES',
+            code: 'INVALID_SCOPE',
+            retriable: false,
+          };
+          results.push(error);
+          throw new RejectCommitError(
+            createRejectedPushResponse(error, args.commitSeq)
+          );
+        }
+      }
+
+      results.push(applied.result);
+      allEmitted.push(...applied.emittedChanges);
+      for (const change of applied.emittedChanges) {
+        affectedTablesSet.add(change.table);
+      }
+    }
+
+    i += consumed;
+  }
+
+  return {
+    results,
+    emittedChanges: allEmitted,
+    affectedTables: Array.from(affectedTablesSet).sort(),
+  };
+}
+
+async function executePushCommitInExecutor<
+  DB extends SyncCoreDb,
+  Auth extends SyncServerAuth,
+>(args: {
+  trx: DbExecutor<DB>;
+  dialect: ServerSyncDialect;
+  handlers: ServerHandlerCollection<DB, Auth>;
+  pushPlugins: readonly SyncServerPushPlugin<DB, Auth>[];
+  auth: Auth;
+  request: SyncPushRequest;
+}): Promise<PushCommitResult> {
+  const { trx, dialect, handlers, request, pushPlugins } = args;
+  const actorId = args.auth.actorId;
+  const partitionId = args.auth.partitionId ?? 'default';
+  const ops = request.operations ?? [];
+  const syncTrx = trx as SyncMetadataTrx;
+
+  if (!dialect.supportsSavepoints) {
+    await syncTrx
+      .deleteFrom('sync_commits')
+      .where('partition_id', '=', partitionId)
+      .where('client_id', '=', request.clientId)
+      .where('client_commit_id', '=', request.clientCommitId)
+      .where('result_json', 'is', null)
+      .execute();
+  }
+
+  const commitCreatedAt = new Date().toISOString();
+  const commitRow: Insertable<SyncCoreDb['sync_commits']> = {
+    partition_id: partitionId,
+    actor_id: actorId,
+    client_id: request.clientId,
+    client_commit_id: request.clientCommitId,
+    created_at: commitCreatedAt,
+    meta: null,
+    result_json: null,
+  };
+  let commitSeq =
+    (await insertPendingCommit({
+      syncTrx,
+      dialect,
+      commitRow,
+    })) ?? 0;
+  if (commitSeq === 0) {
+    return loadExistingCommitResult({
+      trx,
+      syncTrx,
+      dialect,
+      request,
+      partitionId,
+    });
+  }
+
+  if (commitSeq <= 0) {
+    const insertedCommitRow = await (
+      syncTrx.selectFrom('sync_commits') as SelectQueryBuilder<
+        SyncCoreDb,
+        'sync_commits',
+        EmptySelection
+      >
+    )
+      .selectAll()
+      .where('partition_id', '=', partitionId)
+      .where('client_id', '=', request.clientId)
+      .where('client_commit_id', '=', request.clientCommitId)
+      .executeTakeFirstOrThrow();
+    commitSeq = Number(insertedCommitRow.commit_seq);
+  }
+
+  const commitId = `${request.clientId}:${request.clientCommitId}`;
+  const savepointName = `sync_apply_${commitSeq}`;
+  const useSavepoints = shouldUseSavepoints({
+    dialect,
+    handlers,
+    operations: ops,
+  });
+  let savepointCreated = false;
+
+  try {
+    if (useSavepoints) {
+      await sql.raw(`SAVEPOINT ${savepointName}`).execute(trx);
+      savepointCreated = true;
+    }
+
+    const applied = await applyCommitOperations({
+      trx,
+      handlers,
+      pushPlugins,
+      auth: args.auth,
+      request,
+      actorId,
+      commitId,
+      commitSeq,
+    });
+
+    const appliedResponse: SyncPushResponse = {
+      ok: true,
+      status: 'applied',
+      commitSeq,
+      results: applied.results,
+    };
+    await persistEmittedChanges({
+      trx,
+      dialect,
+      partitionId,
+      commitSeq,
+      emittedChanges: applied.emittedChanges,
+    });
+    await persistCommitOutcome({
+      trx,
+      dialect,
+      partitionId,
+      commitSeq,
+      response: appliedResponse,
+      affectedTables: applied.affectedTables,
+      emittedChangeCount: applied.emittedChanges.length,
+    });
+
+    if (useSavepoints) {
+      await sql.raw(`RELEASE SAVEPOINT ${savepointName}`).execute(trx);
+    }
+
+    return {
+      response: appliedResponse,
+      affectedTables: applied.affectedTables,
+      scopeKeys: scopeKeysFromEmitted(applied.emittedChanges),
+      emittedChanges: applied.emittedChanges,
+      commitActorId: actorId,
+      commitCreatedAt,
+    };
+  } catch (error) {
+    if (savepointCreated) {
+      try {
+        await sql.raw(`ROLLBACK TO SAVEPOINT ${savepointName}`).execute(trx);
+        await sql.raw(`RELEASE SAVEPOINT ${savepointName}`).execute(trx);
+      } catch (savepointError) {
+        console.error(
+          '[pushCommit] Savepoint rollback failed:',
+          savepointError
+        );
+        throw savepointError;
+      }
+    }
+
+    if (!(error instanceof RejectCommitError)) {
+      throw error;
+    }
+
+    await persistCommitOutcome({
+      trx,
+      dialect,
+      partitionId,
+      commitSeq,
+      response: error.response,
+      affectedTables: [],
+      emittedChangeCount: 0,
+    });
+
+    return {
+      response: error.response,
+      affectedTables: [],
+      scopeKeys: [],
+      emittedChanges: [],
+      commitActorId: actorId,
+      commitCreatedAt,
+    };
+  }
+}
+
 export async function pushCommit<
   DB extends SyncCoreDb,
   Auth extends SyncServerAuth,
@@ -195,16 +775,16 @@ export async function pushCommit<
   plugins?: readonly SyncServerPushPlugin<DB, Auth>[];
   auth: Auth;
   request: SyncPushRequest;
+  suppressTelemetry?: boolean;
 }): Promise<PushCommitResult> {
   const { db, dialect, handlers, request } = args;
   const pushPlugins = sortServerPushPlugins(args.plugins);
-  const actorId = args.auth.actorId;
-  const partitionId = args.auth.partitionId ?? 'default';
   const requestedOps = Array.isArray(request.operations)
     ? request.operations
     : [];
   const operationCount = requestedOps.length;
   const startedAtMs = Date.now();
+  const suppressTelemetry = args.suppressTelemetry === true;
 
   return startSyncSpan(
     {
@@ -225,587 +805,178 @@ export async function pushCommit<
         span.setAttribute('affected_table_count', result.affectedTables.length);
         span.setStatus('ok');
 
-        recordPushMetrics({
-          status,
-          durationMs,
-          operationCount,
-          emittedChangeCount: result.emittedChanges.length,
-          affectedTableCount: result.affectedTables.length,
-        });
+        if (!suppressTelemetry) {
+          recordPushMetrics({
+            status,
+            durationMs,
+            operationCount,
+            emittedChangeCount: result.emittedChanges.length,
+            affectedTableCount: result.affectedTables.length,
+          });
+        }
 
         return result;
       };
 
       try {
-        if (!request.clientId || !request.clientCommitId) {
-          return finalizeResult({
-            response: {
-              ok: true,
-              status: 'rejected',
-              results: [
-                {
-                  opIndex: 0,
-                  status: 'error',
-                  error: 'INVALID_REQUEST',
-                  code: 'INVALID_REQUEST',
-                  retriable: false,
-                },
-              ],
-            },
-            affectedTables: [],
-            scopeKeys: [],
-            emittedChanges: [],
-            commitActorId: null,
-            commitCreatedAt: null,
-          });
+        const validationError = validatePushRequest(request);
+        if (validationError) {
+          return finalizeResult(createRejectedPushResult(validationError));
         }
 
-        const ops = request.operations ?? [];
-        if (!Array.isArray(ops) || ops.length === 0) {
-          return finalizeResult({
-            response: {
-              ok: true,
-              status: 'rejected',
-              results: [
-                {
-                  opIndex: 0,
-                  status: 'error',
-                  error: 'EMPTY_COMMIT',
-                  code: 'EMPTY_COMMIT',
-                  retriable: false,
-                },
-              ],
-            },
-            affectedTables: [],
-            scopeKeys: [],
-            emittedChanges: [],
-            commitActorId: null,
-            commitCreatedAt: null,
+        return finalizeResult(
+          await dialect.executeInTransaction(db, async (trx) =>
+            executePushCommitInExecutor({
+              trx,
+              dialect,
+              handlers,
+              pushPlugins,
+              auth: args.auth,
+              request,
+            })
+          )
+        );
+      } catch (error) {
+        const durationMs = Math.max(0, Date.now() - startedAtMs);
+        span.setAttribute('status', 'error');
+        span.setAttribute('duration_ms', durationMs);
+        span.setStatus('error');
+
+        if (!suppressTelemetry) {
+          recordPushMetrics({
+            status: 'error',
+            durationMs,
+            operationCount,
+            emittedChangeCount: 0,
+            affectedTableCount: 0,
+          });
+          captureSyncException(error, {
+            event: 'sync.server.push',
+            operationCount,
           });
         }
+        throw error;
+      }
+    }
+  );
+}
 
-        return finalizeResult(
-          await dialect.executeInTransaction(db, async (trx) => {
-            type SyncTrx = Pick<
-              Kysely<SyncCoreDb>,
-              'selectFrom' | 'insertInto' | 'updateTable' | 'deleteFrom'
-            >;
-
-            const syncTrx = trx as SyncTrx;
-
-            // Clean up any stale commit row with null result_json.
-            // This can happen when a previous push inserted the commit row but crashed
-            // before writing the result (e.g., on D1 without transaction support).
-            if (!dialect.supportsSavepoints) {
-              await syncTrx
-                .deleteFrom('sync_commits')
-                .where('partition_id', '=', partitionId)
-                .where('client_id', '=', request.clientId)
-                .where('client_commit_id', '=', request.clientCommitId)
-                .where('result_json', 'is', null)
-                .execute();
-            }
+export async function pushCommitBatch<
+  DB extends SyncCoreDb,
+  Auth extends SyncServerAuth,
+>(args: {
+  db: Kysely<DB>;
+  dialect: ServerSyncDialect;
+  handlers: ServerHandlerCollection<DB, Auth>;
+  plugins?: readonly SyncServerPushPlugin<DB, Auth>[];
+  auth: Auth;
+  requests: SyncPushRequest[];
+  suppressTelemetry?: boolean;
+}): Promise<PushCommitResult[]> {
+  const { db, dialect, handlers, requests } = args;
+  const pushPlugins = sortServerPushPlugins(args.plugins);
+  const startedAtMs = Date.now();
+  const suppressTelemetry = args.suppressTelemetry === true;
+  const totalOperationCount = requests.reduce((count, request) => {
+    const operations = Array.isArray(request.operations)
+      ? request.operations
+      : [];
+    return count + operations.length;
+  }, 0);
 
-            // Insert commit row (idempotency key)
-            const commitRow: Insertable<SyncCoreDb['sync_commits']> = {
-              partition_id: partitionId,
-              actor_id: actorId,
-              client_id: request.clientId,
-              client_commit_id: request.clientCommitId,
-              meta: null,
-              result_json: null,
-            };
-
-            const loadExistingCommit = async (): Promise<PushCommitResult> => {
-              // Existing commit: return cached response (applied or rejected)
-              // Use forUpdate() for row locking on databases that support it
-              let query = (
-                syncTrx.selectFrom('sync_commits') as SelectQueryBuilder<
-                  SyncCoreDb,
-                  'sync_commits',
-                  EmptySelection
-                >
-              )
-                .selectAll()
-                .where('partition_id', '=', partitionId)
-                .where('client_id', '=', request.clientId)
-                .where('client_commit_id', '=', request.clientCommitId);
-
-              if (dialect.supportsForUpdate) {
-                query = query.forUpdate();
-              }
-
-              const existing = await query.executeTakeFirstOrThrow();
-
-              const parsedCached = parseJsonValue(existing.result_json);
-              if (!isSyncPushResponse(parsedCached)) {
-                return {
-                  response: {
-                    ok: true,
-                    status: 'rejected',
-                    results: [
-                      {
-                        opIndex: 0,
-                        status: 'error',
-                        error: 'IDEMPOTENCY_CACHE_MISS',
-                        code: 'INTERNAL',
-                        retriable: true,
-                      },
-                    ],
-                  },
-                  affectedTables: [],
-                  scopeKeys: [],
-                  emittedChanges: [],
-                  commitActorId:
-                    typeof existing.actor_id === 'string'
-                      ? existing.actor_id
-                      : null,
-                  commitCreatedAt:
-                    typeof existing.created_at === 'string'
-                      ? existing.created_at
-                      : null,
-                };
-              }
-
-              const base: SyncPushResponse = {
-                ...parsedCached,
-                commitSeq: Number(existing.commit_seq),
-              };
-
-              if (parsedCached.status === 'applied') {
-                const tablesFromDb = dialect.dbToArray(
-                  existing.affected_tables
-                );
-                return {
-                  response: { ...base, status: 'cached' },
-                  affectedTables:
-                    tablesFromDb.length > 0
-                      ? tablesFromDb
-                      : await readCommitAffectedTables(
-                          trx,
-                          dialect,
-                          Number(existing.commit_seq),
-                          partitionId
-                        ),
-                  scopeKeys: [],
-                  emittedChanges: [],
-                  commitActorId:
-                    typeof existing.actor_id === 'string'
-                      ? existing.actor_id
-                      : null,
-                  commitCreatedAt:
-                    typeof existing.created_at === 'string'
-                      ? existing.created_at
-                      : null,
-                };
-              }
-
-              return {
-                response: base,
-                affectedTables: [],
-                scopeKeys: [],
-                emittedChanges: [],
-                commitActorId:
-                  typeof existing.actor_id === 'string'
-                    ? existing.actor_id
-                    : null,
-                commitCreatedAt:
-                  typeof existing.created_at === 'string'
-                    ? existing.created_at
-                    : null,
-              };
-            };
-
-            const loadPersistedCommitMetadata = async (
-              seq: number
-            ): Promise<{
-              commitActorId: string | null;
-              commitCreatedAt: string | null;
-            }> => {
-              const persisted = await (
-                syncTrx.selectFrom('sync_commits') as SelectQueryBuilder<
-                  SyncCoreDb,
-                  'sync_commits',
-                  EmptySelection
-                >
-              )
-                .selectAll()
-                .where('commit_seq', '=', seq)
-                .where('partition_id', '=', partitionId)
-                .executeTakeFirst();
-
-              return {
-                commitActorId:
-                  typeof persisted?.actor_id === 'string'
-                    ? persisted.actor_id
-                    : null,
-                commitCreatedAt:
-                  typeof persisted?.created_at === 'string'
-                    ? persisted.created_at
-                    : null,
-              };
-            };
-
-            let commitSeq = 0;
-            if (dialect.supportsInsertReturning) {
-              const insertedCommit = await syncTrx
-                .insertInto('sync_commits')
-                .values(commitRow)
-                .onConflict((oc) =>
-                  oc
-                    .columns(['partition_id', 'client_id', 'client_commit_id'])
-                    .doNothing()
-                )
-                .returning(['commit_seq'])
-                .executeTakeFirst();
-
-              if (!insertedCommit) {
-                return loadExistingCommit();
-              }
-
-              commitSeq = coerceNumber(insertedCommit.commit_seq) ?? 0;
-            } else {
-              const insertResult = await syncTrx
-                .insertInto('sync_commits')
-                .values(commitRow)
-                .onConflict((oc) =>
-                  oc
-                    .columns(['partition_id', 'client_id', 'client_commit_id'])
-                    .doNothing()
-                )
-                .executeTakeFirstOrThrow();
-
-              const insertedRows = Number(
-                insertResult.numInsertedOrUpdatedRows ?? 0
-              );
-              if (insertedRows === 0) {
-                return loadExistingCommit();
-              }
-
-              commitSeq = coerceNumber(insertResult.insertId) ?? 0;
+  return startSyncSpan(
+    {
+      name: 'sync.server.push_batch',
+      op: 'sync.push.batch',
+      attributes: {
+        commit_count: requests.length,
+        operation_count: totalOperationCount,
+      },
+    },
+    async (span) => {
+      try {
+        const results = await dialect.executeInTransaction(db, async (trx) => {
+          const executed: PushCommitResult[] = [];
+          for (const request of requests) {
+            const validationError = validatePushRequest(request);
+            if (validationError) {
+              executed.push(createRejectedPushResult(validationError));
+              continue;
             }
 
-            if (commitSeq <= 0) {
-              const insertedCommitRow = await (
-                syncTrx.selectFrom('sync_commits') as SelectQueryBuilder<
-                  SyncCoreDb,
-                  'sync_commits',
-                  EmptySelection
-                >
-              )
-                .selectAll()
-                .where('partition_id', '=', partitionId)
-                .where('client_id', '=', request.clientId)
-                .where('client_commit_id', '=', request.clientCommitId)
-                .executeTakeFirstOrThrow();
-              commitSeq = Number(insertedCommitRow.commit_seq);
-            }
-            const commitId = `${request.clientId}:${request.clientCommitId}`;
-
-            const savepointName = 'sync_apply';
-            let useSavepoints = dialect.supportsSavepoints;
-            if (useSavepoints && ops.length === 1) {
-              const singleOpHandler = handlers.byTable.get(ops[0]!.table);
-              if (!singleOpHandler) {
-                throw new Error(`Unknown table: ${ops[0]!.table}`);
-              }
-              if (singleOpHandler.canRejectSingleOperationWithoutSavepoint) {
-                useSavepoints = false;
-              }
-            }
-            let savepointCreated = false;
-
-            try {
-              // Apply the commit under a savepoint so we can roll back app writes on conflict
-              // while still persisting the commit-level cached response.
-              if (useSavepoints) {
-                await sql.raw(`SAVEPOINT ${savepointName}`).execute(trx);
-                savepointCreated = true;
-              }
-
-              const allEmitted = [];
-              const results = [];
-              const affectedTablesSet = new Set<string>();
-
-              for (let i = 0; i < ops.length; ) {
-                const op = ops[i]!;
-                const handler = handlers.byTable.get(op.table);
-                if (!handler) {
-                  throw new Error(`Unknown table: ${op.table}`);
-                }
-
-                const operationCtx = {
-                  db: trx,
-                  trx,
-                  actorId,
-                  auth: args.auth,
-                  clientId: request.clientId,
-                  commitId,
-                  schemaVersion: request.schemaVersion,
-                };
-
-                let transformedOp = op;
-                for (const plugin of pushPlugins) {
-                  if (!plugin.beforeApplyOperation) continue;
-                  const nextOp = await plugin.beforeApplyOperation({
-                    ctx: operationCtx,
-                    tableHandler: handler,
-                    op: transformedOp,
-                    opIndex: i,
-                  });
-                  assertOperationIdentityUnchanged(plugin.name, op, nextOp);
-                  transformedOp = nextOp;
-                }
-
-                let appliedBatch:
-                  | Awaited<ReturnType<typeof handler.applyOperation>>[]
-                  | null = null;
-                let consumed = 1;
-
-                if (
-                  pushPlugins.length === 0 &&
-                  handler.applyOperationBatch &&
-                  dialect.supportsInsertReturning
-                ) {
-                  const batchInput = [];
-                  for (let j = i; j < ops.length; j++) {
-                    const nextOp = ops[j]!;
-                    if (nextOp.table !== op.table) break;
-                    batchInput.push({ op: nextOp, opIndex: j });
-                  }
-
-                  if (batchInput.length > 1) {
-                    appliedBatch = await handler.applyOperationBatch(
-                      operationCtx,
-                      batchInput
-                    );
-                    consumed = Math.max(1, appliedBatch.length);
-                  }
-                }
-
-                if (!appliedBatch) {
-                  let appliedSingle = await handler.applyOperation(
-                    operationCtx,
-                    transformedOp,
-                    i
-                  );
-
-                  for (const plugin of pushPlugins) {
-                    if (!plugin.afterApplyOperation) continue;
-                    appliedSingle = await plugin.afterApplyOperation({
-                      ctx: operationCtx,
-                      tableHandler: handler,
-                      op: transformedOp,
-                      opIndex: i,
-                      applied: appliedSingle,
-                    });
-                  }
-
-                  appliedBatch = [appliedSingle];
-                }
-                if (appliedBatch.length === 0) {
-                  throw new Error(
-                    `Handler "${op.table}" returned no results from applyOperationBatch`
-                  );
-                }
-
-                for (const applied of appliedBatch) {
-                  if (applied.result.status !== 'applied') {
-                    results.push(applied.result);
-                    throw new RejectCommitError({
-                      ok: true,
-                      status: 'rejected',
-                      commitSeq,
-                      results,
-                    });
-                  }
-
-                  // Framework-level enforcement: emitted changes must have scopes
-                  for (const c of applied.emittedChanges ?? []) {
-                    const scopes = c?.scopes;
-                    if (!scopes || typeof scopes !== 'object') {
-                      results.push({
-                        opIndex: applied.result.opIndex,
-                        status: 'error' as const,
-                        error: 'MISSING_SCOPES',
-                        code: 'INVALID_SCOPE',
-                        retriable: false,
-                      });
-                      throw new RejectCommitError({
-                        ok: true,
-                        status: 'rejected',
-                        commitSeq,
-                        results,
-                      });
-                    }
-                  }
-
-                  results.push(applied.result);
-                  allEmitted.push(...applied.emittedChanges);
-                  for (const c of applied.emittedChanges) {
-                    affectedTablesSet.add(c.table);
-                  }
-                }
-
-                i += consumed;
-              }
-
-              if (allEmitted.length > 0) {
-                const changeRows: Array<
-                  Insertable<SyncCoreDb['sync_changes']>
-                > = allEmitted.map((c) => ({
-                  partition_id: partitionId,
-                  commit_seq: commitSeq,
-                  table: c.table,
-                  row_id: c.row_id,
-                  op: c.op,
-                  row_json: toDialectJsonValue(dialect, c.row_json),
-                  row_version: c.row_version,
-                  scopes: dialect.scopesToDb(c.scopes),
-                }));
-
-                await syncTrx
-                  .insertInto('sync_changes')
-                  .values(changeRows)
-                  .execute();
-              }
-
-              const appliedResponse: SyncPushResponse = {
-                ok: true,
-                status: 'applied',
-                commitSeq,
-                results,
-              };
-
-              const affectedTables = Array.from(affectedTablesSet).sort();
-
-              const appliedCommitUpdate: Updateable<
-                SyncCoreDb['sync_commits']
-              > = {
-                result_json: toDialectJsonValue(dialect, appliedResponse),
-                change_count: allEmitted.length,
-                affected_tables: dialect.arrayToDb(affectedTables) as string[],
-              };
-
-              await syncTrx
-                .updateTable('sync_commits')
-                .set(appliedCommitUpdate)
-                .where('commit_seq', '=', commitSeq)
-                .execute();
-
-              // Insert table commits for subscription filtering
-              if (affectedTables.length > 0) {
-                const tableCommits: Array<
-                  Insertable<SyncCoreDb['sync_table_commits']>
-                > = affectedTables.map((table) => ({
-                  partition_id: partitionId,
-                  table,
-                  commit_seq: commitSeq,
-                }));
-
-                await syncTrx
-                  .insertInto('sync_table_commits')
-                  .values(tableCommits)
-                  .onConflict((oc) =>
-                    oc
-                      .columns(['partition_id', 'table', 'commit_seq'])
-                      .doNothing()
-                  )
-                  .execute();
-              }
-
-              if (useSavepoints) {
-                await sql
-                  .raw(`RELEASE SAVEPOINT ${savepointName}`)
-                  .execute(trx);
-              }
-
-              const commitMetadata =
-                await loadPersistedCommitMetadata(commitSeq);
-
-              return {
-                response: appliedResponse,
-                affectedTables,
-                scopeKeys: scopeKeysFromEmitted(allEmitted),
-                emittedChanges: allEmitted.map((c) => ({
-                  table: c.table,
-                  row_id: c.row_id,
-                  op: c.op,
-                  row_json: c.row_json,
-                  row_version: c.row_version,
-                  scopes: c.scopes,
-                })),
-                ...commitMetadata,
-              };
-            } catch (err) {
-              // Roll back app writes but keep the commit row.
-              if (savepointCreated) {
-                try {
-                  await sql
-                    .raw(`ROLLBACK TO SAVEPOINT ${savepointName}`)
-                    .execute(trx);
-                  await sql
-                    .raw(`RELEASE SAVEPOINT ${savepointName}`)
-                    .execute(trx);
-                } catch (savepointErr) {
-                  // If savepoint rollback fails, the transaction may be in an
-                  // inconsistent state. Log and rethrow to fail the entire commit
-                  // rather than risk data corruption.
-                  console.error(
-                    '[pushCommit] Savepoint rollback failed:',
-                    savepointErr
-                  );
-                  throw savepointErr;
-                }
-              }
-
-              if (!(err instanceof RejectCommitError)) throw err;
-
-              const rejectedCommitUpdate: Updateable<
-                SyncCoreDb['sync_commits']
-              > = {
-                result_json: toDialectJsonValue(dialect, err.response),
-                change_count: 0,
-                affected_tables: dialect.arrayToDb([]) as string[],
-              };
-
-              // Persist the rejected response for commit-level idempotency.
-              await syncTrx
-                .updateTable('sync_commits')
-                .set(rejectedCommitUpdate)
-                .where('commit_seq', '=', commitSeq)
-                .execute();
-
-              const commitMetadata =
-                await loadPersistedCommitMetadata(commitSeq);
-
-              return {
-                response: err.response,
-                affectedTables: [],
-                scopeKeys: [],
-                emittedChanges: [],
-                ...commitMetadata,
-              };
-            }
-          })
+            executed.push(
+              await executePushCommitInExecutor({
+                trx,
+                dialect,
+                handlers,
+                pushPlugins,
+                auth: args.auth,
+                request,
+              })
+            );
+          }
+          return executed;
+        });
+
+        const durationMs = Math.max(0, Date.now() - startedAtMs);
+        const emittedChangeCount = results.reduce(
+          (count, result) => count + result.emittedChanges.length,
+          0
         );
+        const affectedTableCount = results.reduce(
+          (count, result) => count + result.affectedTables.length,
+          0
+        );
+        const status = results.every(
+          (result) => result.response.status === 'cached'
+        )
+          ? 'cached'
+          : results.every(
+                (result) =>
+                  result.response.status === 'applied' ||
+                  result.response.status === 'cached'
+              )
+            ? 'applied'
+            : 'rejected';
+
+        span.setAttribute('status', status);
+        span.setAttribute('duration_ms', durationMs);
+        span.setAttribute('commit_count', results.length);
+        span.setAttribute('emitted_change_count', emittedChangeCount);
+        span.setAttribute('affected_table_count', affectedTableCount);
+        span.setStatus('ok');
+
+        if (!suppressTelemetry) {
+          recordPushMetrics({
+            status,
+            durationMs,
+            operationCount: totalOperationCount,
+            emittedChangeCount,
+            affectedTableCount,
+          });
+        }
+
+        return results;
       } catch (error) {
         const durationMs = Math.max(0, Date.now() - startedAtMs);
         span.setAttribute('status', 'error');
         span.setAttribute('duration_ms', durationMs);
         span.setStatus('error');
 
-        recordPushMetrics({
-          status: 'error',
-          durationMs,
-          operationCount,
-          emittedChangeCount: 0,
-          affectedTableCount: 0,
-        });
-        captureSyncException(error, {
-          event: 'sync.server.push',
-          operationCount,
-        });
+        if (!suppressTelemetry) {
+          recordPushMetrics({
+            status: 'error',
+            durationMs,
+            operationCount: totalOperationCount,
+            emittedChangeCount: 0,
+            affectedTableCount: 0,
+          });
+          captureSyncException(error, {
+            event: 'sync.server.push_batch',
+            commitCount: requests.length,
+            operationCount: totalOperationCount,
+          });
+        }
         throw error;
       }
     }