@syncular/server 0.0.6-96 → 0.1.1

package/src/push.ts

@@ -7,24 +7,33 @@ 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 type { ServerSyncDialect } from './dialect/types';
+import { finalizeCommitIntegrity } from './commit-integrity';
 import {
-  getServerHandlerOrThrow,
-  type ServerHandlerCollection,
-} from './handlers/collection';
+  coerceNumber,
+  parseJsonValue,
+  toDialectJsonValue,
+} from './dialect/helpers';
+import type { DbExecutor, ServerSyncDialect } from './dialect/types';
+import type { ServerHandlerCollection } from './handlers/collection';
 import type { SyncServerAuth } from './handlers/types';
+import {
+  createScopeCommitIndexEntries,
+  scopeKeysFromScopeValues,
+} from './helpers/scope-commit-index';
+import {
+  type SyncServerPushPlugin,
+  sortServerPushPlugins,
+} from './plugins/types';
 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;
@@ -44,8 +53,41 @@ export interface PushCommitResult {
    * Empty for rejected/cached commits.
    */
   emittedChanges: SyncChange[];
+  /**
+   * Commit actor metadata for downstream notifications.
+   * Null when no commit row was persisted.
+   */
+  commitActorId: string | null;
+  /**
+   * Commit timestamp metadata for downstream notifications.
+   * Null when no commit row was persisted.
+   */
+  commitCreatedAt: string | null;
+}
+
+export interface PushCommitValidationContext<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncServerAuth = SyncServerAuth,
+> {
+  trx: DbExecutor<DB>;
+  dialect: ServerSyncDialect;
+  auth: Auth;
+  request: SyncPushRequest;
+  partitionId: string;
+  actorId: string;
+  commitSeq: number;
 }
 
+export type PushCommitValidator<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncServerAuth = SyncServerAuth,
+> = (
+  ctx: PushCommitValidationContext<DB, Auth>
+) =>
+  | Promise<SyncPushResponse['results'][number] | null>
+  | SyncPushResponse['results'][number]
+  | null;
+
 class RejectCommitError extends Error {
   constructor(public readonly response: SyncPushResponse) {
     super('REJECT_COMMIT');
@@ -53,40 +95,6 @@ class RejectCommitError extends Error {
   }
 }
 
-function toDialectJsonValue(
-  dialect: ServerSyncDialect,
-  value: unknown
-): unknown {
-  if (value === null || value === undefined) return null;
-  if (dialect.family === 'sqlite') return JSON.stringify(value);
-  return value;
-}
-
-function parseJsonValue(value: unknown): unknown {
-  if (typeof value !== 'string') return value;
-  try {
-    return JSON.parse(value);
-  } catch {
-    return value;
-  }
-}
-
-function coerceNumber(value: unknown): number | null {
-  if (value === null || value === undefined) return null;
-  if (typeof value === 'number') {
-    return Number.isFinite(value) ? value : null;
-  }
-  if (typeof value === 'bigint') {
-    const coerced = Number(value);
-    return Number.isFinite(coerced) ? coerced : null;
-  }
-  if (typeof value === 'string') {
-    const coerced = Number(value);
-    return Number.isFinite(coerced) ? coerced : null;
-  }
-  return null;
-}
-
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null;
 }
@@ -97,8 +105,30 @@ function isSyncPushResponse(value: unknown): value is SyncPushResponse {
   );
 }
 
+function assertOperationIdentityUnchanged(
+  pluginName: string,
+  before: SyncPushRequest['operations'][number],
+  after: SyncPushRequest['operations'][number]
+): void {
+  if (before.table !== after.table) {
+    throw new Error(
+      `Server push plugin "${pluginName}" cannot change op.table (${before.table} -> ${after.table})`
+    );
+  }
+  if (before.row_id !== after.row_id) {
+    throw new Error(
+      `Server push plugin "${pluginName}" cannot change op.row_id (${before.row_id} -> ${after.row_id})`
+    );
+  }
+  if (before.op !== after.op) {
+    throw new Error(
+      `Server push plugin "${pluginName}" cannot change op.op (${before.op} -> ${after.op})`
+    );
+  }
+}
+
 async function readCommitAffectedTables<DB extends SyncCoreDb>(
-  db: Kysely<DB>,
+  db: DbExecutor<DB>,
   dialect: ServerSyncDialect,
   commitSeq: number,
   partitionId: string
@@ -131,10 +161,8 @@ function scopeKeysFromEmitted(
 ): string[] {
   const keys = new Set<string>();
   for (const c of emitted) {
-    for (const [key, value] of Object.entries(c.scopes)) {
-      if (!value) continue;
-      const prefix = key.replace(/_id$/, '');
-      keys.add(`${prefix}:${value}`);
+    for (const scopeKey of scopeKeysFromScopeValues(c.scopes)) {
+      keys.add(scopeKey);
     }
   }
   return Array.from(keys);
@@ -181,6 +209,650 @@ 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 push request',
+      code: 'sync.invalid_request',
+      retriable: false,
+    };
+  }
+
+  const ops = request.operations ?? [];
+  if (!Array.isArray(ops) || ops.length === 0) {
+    return {
+      opIndex: 0,
+      status: 'error',
+      error: 'Empty commit',
+      code: 'sync.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();
+
+  const scopeEntries = createScopeCommitIndexEntries(args.emittedChanges);
+  if (scopeEntries.length > 0) {
+    await syncTrx
+      .insertInto('sync_scope_commits')
+      .values(
+        scopeEntries.map((entry) => ({
+          partition_id: args.partitionId,
+          table: entry.table,
+          scope_key: entry.scopeKey,
+          commit_seq: args.commitSeq,
+        }))
+      )
+      .onConflict((oc) =>
+        oc
+          .columns(['partition_id', 'table', 'scope_key', 'commit_seq'])
+          .doNothing()
+      )
+      .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) {
+    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();
+  }
+
+  await finalizeCommitIntegrity({
+    db: args.trx,
+    dialect: args.dialect,
+    partitionId: args.partitionId,
+    commitSeq: args.commitSeq,
+  });
+}
+
+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: 'sync.idempotency_cache_miss',
+      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,
+      authLease: args.request.authLease,
+    };
+
+    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: 'sync.missing_scopes',
+            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;
+  validateCommit?: PushCommitValidator<DB, Auth>;
+}): 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: request.authLease
+      ? toDialectJsonValue(dialect, {
+          authLease: request.authLease,
+        })
+      : 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 validationResult = await args.validateCommit?.({
+    trx,
+    dialect,
+    auth: args.auth,
+    request,
+    partitionId,
+    actorId,
+    commitSeq,
+  });
+  if (validationResult) {
+    const response = createRejectedPushResponse(validationResult, commitSeq);
+    await persistCommitOutcome({
+      trx,
+      dialect,
+      partitionId,
+      commitSeq,
+      response,
+      affectedTables: [],
+      emittedChangeCount: 0,
+    });
+
+    return {
+      response,
+      affectedTables: [],
+      scopeKeys: [],
+      emittedChanges: [],
+      commitActorId: actorId,
+      commitCreatedAt,
+    };
+  }
+
+  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,
@@ -188,17 +860,20 @@ export async function pushCommit<
   db: Kysely<DB>;
   dialect: ServerSyncDialect;
   handlers: ServerHandlerCollection<DB, Auth>;
+  plugins?: readonly SyncServerPushPlugin<DB, Auth>[];
   auth: Auth;
   request: SyncPushRequest;
+  validateCommit?: PushCommitValidator<DB, Auth>;
+  suppressTelemetry?: boolean;
 }): Promise<PushCommitResult> {
   const { db, dialect, handlers, request } = args;
-  const actorId = args.auth.actorId;
-  const partitionId = args.auth.partitionId ?? 'default';
+  const pushPlugins = sortServerPushPlugins(args.plugins);
   const requestedOps = Array.isArray(request.operations)
     ? request.operations
     : [];
   const operationCount = requestedOps.length;
   const startedAtMs = Date.now();
+  const suppressTelemetry = args.suppressTelemetry === true;
 
   return startSyncSpan(
     {
@@ -219,418 +894,181 @@ 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: [],
-          });
+        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: [],
+        return finalizeResult(
+          await dialect.executeInTransaction(db, async (trx) =>
+            executePushCommitInExecutor({
+              trx,
+              dialect,
+              handlers,
+              pushPlugins,
+              auth: args.auth,
+              request,
+              validateCommit: args.validateCommit,
+            })
+          )
+        );
+      } 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[];
+  validateCommit?: PushCommitValidator<DB, Auth>;
+  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 insertResult = await syncTrx
-              .insertInto('sync_commits')
-              .values(commitRow)
-              .onConflict((oc) =>
-                oc
-                  .columns(['partition_id', 'client_id', 'client_commit_id'])
-                  .doNothing()
-              )
-              .executeTakeFirstOrThrow();
+  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;
+            }
 
-            const insertedRows = Number(
-              insertResult.numInsertedOrUpdatedRows ?? 0
+            executed.push(
+              await executePushCommitInExecutor({
+                trx,
+                dialect,
+                handlers,
+                pushPlugins,
+                auth: args.auth,
+                request,
+                validateCommit: args.validateCommit,
+              })
             );
-            if (insertedRows === 0) {
-              // 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: [],
-                };
-              }
-
-              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: [],
-                };
-              }
-
-              return {
-                response: base,
-                affectedTables: [],
-                scopeKeys: [],
-                emittedChanges: [],
-              };
-            }
+          }
+          return executed;
+        });
 
-            let commitSeq = coerceNumber(insertResult.insertId) ?? 0;
-            if (commitSeq <= 0) {
-              const insertedCommit = 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(insertedCommit.commit_seq);
-            }
-            const commitId = `${request.clientId}:${request.clientCommitId}`;
-
-            const savepointName = 'sync_apply';
-            const useSavepoints = dialect.supportsSavepoints;
-            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; i++) {
-                const op = ops[i]!;
-                const handler = getServerHandlerOrThrow(handlers, op.table);
-                const applied = await handler.applyOperation(
-                  {
-                    db: trx,
-                    trx,
-                    actorId,
-                    auth: args.auth,
-                    clientId: request.clientId,
-                    commitId,
-                    schemaVersion: request.schemaVersion,
-                  },
-                  op,
-                  i
-                );
-
-                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: i,
-                      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);
-                }
-              }
-
-              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);
-              }
-
-              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,
-                })),
-              };
-            } 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();
-
-              return {
-                response: err.response,
-                affectedTables: [],
-                scopeKeys: [],
-                emittedChanges: [],
-              };
-            }
-          })
+        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;
       }
     }