@syncular/server 0.0.6-95 → 0.1.0

package/src/handlers/create-handler.ts

@@ -3,7 +3,8 @@
  */
 
 import type {
-  ScopePattern,
+  BinarySnapshotColumn,
+  BinarySnapshotRowsEncoder,
   ScopeValues,
   ScopeValuesFromPatterns,
   ScopeDefinition as SimpleScopeDefinition,
@@ -15,8 +16,9 @@ import {
   applyCodecsToDbRow,
   type ColumnCodecDialect,
   type ColumnCodecSource,
-  extractScopeVars,
-  normalizeScopes,
+  createSingleVariableScopeMetadata,
+  createTableColumnCodecsResolver,
+  type SyncularErrorCode,
   toTableColumnCodecs,
 } from '@syncular/core';
 import type {
@@ -32,9 +34,12 @@ import type {
   UpdateResult,
 } from 'kysely';
 import { sql } from 'kysely';
+import { coerceNumber } from '../dialect/helpers';
+import { rowScopesAllowed } from '../helpers/scope-authorization';
 import type { SyncCoreDb } from '../schema';
 import type {
   ApplyOperationResult,
+  BatchApplyOperationInput,
   EmittedChange,
   ServerApplyOperationContext,
   ServerContext,
@@ -48,14 +53,10 @@ import type {
  */
 type AuthorizeResult =
   | true
-  | { error: string; code: string; retriable?: boolean };
+  | { error: string; code: SyncularErrorCode; retriable?: boolean };
 
-function classifyConstraintViolationCode(message: string): string {
-  const normalized = message.toLowerCase();
-  if (normalized.includes('not null')) return 'NOT_NULL_CONSTRAINT';
-  if (normalized.includes('unique')) return 'UNIQUE_CONSTRAINT';
-  if (normalized.includes('foreign key')) return 'FOREIGN_KEY_CONSTRAINT';
-  return 'CONSTRAINT_VIOLATION';
+function classifyConstraintViolationCode(_message: string): SyncularErrorCode {
+  return 'sync.constraint_violation';
 }
 
 function isConstraintViolationError(message: string): boolean {
@@ -76,10 +77,36 @@ function isMissingColumnReferenceError(message: string): boolean {
   );
 }
 
-/**
- * Scope definition for a column - maps scope variable to column name.
- */
-export type ScopeColumnMap = Record<string, string>;
+function readSafeVersionColumn(
+  row: Record<string, unknown>,
+  versionColumn: string,
+  defaultValue: number
+): number {
+  const value = row[versionColumn];
+  if (value === null || value === undefined) return defaultValue;
+  const version = coerceNumber(value);
+  if (version === null || !Number.isSafeInteger(version)) {
+    throw new Error(`Version column "${versionColumn}" must be a safe integer`);
+  }
+  return version;
+}
+
+function normalizeOutboundVersionColumn<Row>(
+  row: Row,
+  versionColumn: string,
+  version: number
+): Row {
+  if (row === null || typeof row !== 'object' || Array.isArray(row)) {
+    return row;
+  }
+  if (!Object.hasOwn(row, versionColumn)) {
+    return row;
+  }
+  return {
+    ...(row as Record<string, unknown>),
+    [versionColumn]: version,
+  } as Row;
+}
 
 /**
  * Options for creating a declarative server handler.
@@ -124,6 +151,37 @@ export interface CreateServerHandlerOptions<
   /** TTL for cached snapshot chunks in ms */
   snapshotChunkTtlMs?: number;
 
+  /**
+   * Stable binary snapshot column metadata used by binary bootstrap chunks.
+   */
+  snapshotBinaryColumns?: readonly BinarySnapshotColumn[];
+
+  /**
+   * Version-aware binary snapshot column metadata. Returning null intentionally
+   * disables fallback to current metadata.
+   */
+  snapshotBinaryColumnsForVersion?: (
+    schemaVersion: number
+  ) => readonly BinarySnapshotColumn[] | null | undefined;
+
+  /**
+   * Optional generated binary snapshot encoder used by binary bootstrap chunks.
+   */
+  snapshotBinaryEncoder?: BinarySnapshotRowsEncoder<
+    Selectable<ClientDB[TableName]>
+  >;
+
+  /**
+   * Version-aware generated binary snapshot encoder. Returning null
+   * intentionally disables fallback to the current encoder.
+   */
+  snapshotBinaryEncoderForVersion?: (
+    schemaVersion: number
+  ) =>
+    | BinarySnapshotRowsEncoder<Selectable<ClientDB[TableName]>>
+    | null
+    | undefined;
+
   /**
    * Resolve allowed scope values for the current actor.
    * Called per request to determine what the actor can access.
@@ -187,6 +245,17 @@ export interface CreateServerHandlerOptions<
    */
   applyOperation?: ServerTableHandler<ServerDB, Auth>['applyOperation'];
 
+  /**
+   * Hint for savepoint optimization on single-op commits.
+   *
+   * `true` means a rejected single operation never leaves durable writes
+   * before returning the rejection result.
+   *
+   * Defaults to `true` for the built-in applyOperation implementation and
+   * `false` when a custom applyOperation is provided.
+   */
+  canRejectSingleOperationWithoutSavepoint?: boolean;
+
   /**
    * Custom scope extraction from row (for complex scope logic).
    */
@@ -254,6 +323,10 @@ export function createServerHandler<
     versionColumn = 'server_version',
     dependsOn,
     snapshotChunkTtlMs,
+    snapshotBinaryColumns,
+    snapshotBinaryColumnsForVersion,
+    snapshotBinaryEncoder,
+    snapshotBinaryEncoderForVersion,
     resolveScopes,
     transformInbound,
     transformOutbound,
@@ -262,42 +335,19 @@ export function createServerHandler<
     authorize,
     extractScopes: customExtractScopes,
   } = options;
-  const codecCache = new Map<string, ReturnType<typeof toTableColumnCodecs>>();
-  const resolveTableCodecs = (row: Record<string, unknown>) => {
-    if (!codecs) return {};
-    const columns = Object.keys(row);
-    if (columns.length === 0) return {};
-    const cacheKey = columns.slice().sort().join('\u0000');
-    const cached = codecCache.get(cacheKey);
-    if (cached) return cached;
-    const resolved = toTableColumnCodecs(table, codecs, columns, {
-      dialect: codecDialect,
-    });
-    codecCache.set(cacheKey, resolved);
-    return resolved;
-  };
-
-  // Normalize scopes to pattern map and extract patterns/columns
-  const scopeColumnMap = normalizeScopes(scopeDefs);
-  const scopePatterns = Object.keys(scopeColumnMap) as ScopePattern[];
-  const scopeColumns: ScopeColumnMap = {};
-
-  for (const [pattern, columnName] of Object.entries(scopeColumnMap)) {
-    const vars = extractScopeVars(pattern);
-    if (vars.length !== 1) {
-      throw new Error(
-        `Scope pattern "${pattern}" must contain exactly one placeholder (got ${vars.length}).`
-      );
-    }
-    const varName = vars[0]!;
-    const existing = scopeColumns[varName];
-    if (existing && existing !== columnName) {
-      throw new Error(
-        `Scope variable "${varName}" is mapped to multiple columns: "${existing}" and "${columnName}".`
-      );
-    }
-    scopeColumns[varName] = columnName;
-  }
+  const resolveRowCodecs = createTableColumnCodecsResolver(codecs, {
+    dialect: codecDialect,
+  });
+  const primaryKeyColumn = primaryKey as keyof ServerDB[TableName] & string;
+  const qualifiedVersionRef = `${table}.${versionColumn}`;
+  const resolveTableCodecs = (row: Record<string, unknown>) =>
+    resolveRowCodecs(table, row);
+  const usePassthroughInbound = !transformInbound && codecs == null;
+
+  const { scopePatterns, scopeColumnsByVariable: scopeColumns } =
+    createSingleVariableScopeMetadata(scopeDefs);
+  const scopeColumnEntries = Object.entries(scopeColumns);
+  const requiredScopeKeys = Object.keys(scopeColumns);
 
   // Default extractScopes from scope columns
   const defaultExtractScopes = (row: Record<string, unknown>): StoredScopes => {
@@ -321,12 +371,101 @@ export function createServerHandler<
     const resolved = await resolveScopes(ctx);
     const normalized: ScopeValues = {};
     for (const [scopeKey, scopeValue] of Object.entries(resolved)) {
-      if (typeof scopeValue === 'string' || Array.isArray(scopeValue)) {
+      // null/undefined means "no access for this scope" and is skipped.
+      if (scopeValue === null || scopeValue === undefined) continue;
+      if (typeof scopeValue === 'string') {
+        normalized[scopeKey] = scopeValue;
+        continue;
+      }
+      if (Array.isArray(scopeValue)) {
+        const invalidIndex = scopeValue.findIndex(
+          (entry) => typeof entry !== 'string'
+        );
+        if (invalidIndex !== -1) {
+          throw new Error(
+            `resolveScopes() for table "${table}" returned a non-string entry ` +
+              `(${typeof scopeValue[invalidIndex]}) at index ${invalidIndex} of scope "${scopeKey}". ` +
+              'Scope values must be strings or string arrays.'
+          );
+        }
         normalized[scopeKey] = scopeValue;
+        continue;
       }
+      throw new Error(
+        `resolveScopes() for table "${table}" returned an invalid value ` +
+          `(${typeof scopeValue}) for scope "${scopeKey}". ` +
+          'Scope values must be strings or string arrays.'
+      );
     }
     return normalized;
   };
+  const writeScopeCache = new WeakMap<
+    ServerApplyOperationContext<ServerDB, Auth>,
+    Promise<ScopeValues>
+  >();
+
+  const resolveWriteScopes = (
+    ctx: ServerApplyOperationContext<ServerDB, Auth>
+  ): Promise<ScopeValues> => {
+    const cached = writeScopeCache.get(ctx);
+    if (cached) return cached;
+    const loaded = resolveScopesImpl(ctx);
+    writeScopeCache.set(ctx, loaded);
+    return loaded;
+  };
+
+  const authorizeRowScopes = async (
+    ctx: ServerApplyOperationContext<ServerDB, Auth>,
+    row: Record<string, unknown>
+  ): Promise<AuthorizeResult> => {
+    if (requiredScopeKeys.length === 0) return true;
+
+    let allowedScopes: ScopeValues;
+    try {
+      allowedScopes = await resolveWriteScopes(ctx);
+    } catch (resolveErr) {
+      console.error(
+        `[resolveScopes] Failed for table ${table} during write authorization:`,
+        resolveErr
+      );
+      return {
+        error: 'Forbidden',
+        code: 'sync.forbidden',
+        retriable: false,
+      };
+    }
+
+    const rowScopes = extractScopesImpl(row);
+    if (
+      rowScopesAllowed({
+        rowScopes,
+        allowedScopes,
+        requiredScopeKeys,
+      })
+    ) {
+      return true;
+    }
+
+    return {
+      error: 'Forbidden',
+      code: 'sync.forbidden',
+      retriable: false,
+    };
+  };
+
+  const rejectionResult = (
+    opIndex: number,
+    rejection: Exclude<AuthorizeResult, true>
+  ): ApplyOperationResult => ({
+    result: {
+      opIndex,
+      status: 'error',
+      error: rejection.error,
+      code: rejection.code,
+      retriable: rejection.retriable ?? false,
+    },
+    emittedChanges: [],
+  });
 
   const applyOutboundTransform = (
     row: Selectable<ServerDB[TableName]>
@@ -348,6 +487,10 @@ export function createServerHandler<
     row: Record<string, unknown>,
     schemaVersion: number | undefined
   ): Updateable<ServerDB[TableName]> => {
+    if (usePassthroughInbound) {
+      return row as Updateable<ServerDB[TableName]>;
+    }
+
     if (transformInbound) {
       return transformInbound(row as Selectable<ClientDB[TableName]>, {
         schemaVersion,
@@ -371,29 +514,29 @@ export function createServerHandler<
     const { ref } = trx.dynamic;
     const scopeValues = ctx.scopeValues;
 
-    const pageSize = Math.max(1, Math.min(10_000, ctx.limit));
+    const pageSize = Math.max(1, ctx.limit);
 
-    // Build dynamic WHERE conditions
-    const whereConditions: Array<{ column: string; values: string[] }> = [];
-    for (const [varName, columnName] of Object.entries(scopeColumns)) {
-      const values = scopeValues[varName];
-      if (values === undefined) continue;
-      const normalized = Array.isArray(values) ? values : [values];
-      if (normalized.length === 0) continue;
-      whereConditions.push({ column: columnName, values: normalized });
-    }
+    let q = trx.selectFrom(table) as SelectQueryBuilder<
+      ServerDB,
+      keyof ServerDB & string,
+      Record<string, unknown>
+    >;
 
-    let q = trx.selectFrom(table).selectAll() as SelectQueryBuilder<
+    q = q.selectAll() as SelectQueryBuilder<
       ServerDB,
       keyof ServerDB & string,
       Record<string, unknown>
     >;
 
-    for (const cond of whereConditions) {
-      if (cond.values.length === 1) {
-        q = q.where(ref<string>(cond.column), '=', cond.values[0]);
+    for (const [varName, columnName] of scopeColumnEntries) {
+      const values = scopeValues[varName];
+      if (values === undefined) continue;
+      const normalized = Array.isArray(values) ? values : [values];
+      if (normalized.length === 0) continue;
+      if (normalized.length === 1) {
+        q = q.where(ref<string>(columnName), '=', normalized[0]);
       } else {
-        q = q.where(ref<string>(cond.column), 'in', cond.values);
+        q = q.where(ref<string>(columnName), 'in', normalized);
       }
     }
 
@@ -417,10 +560,30 @@ export function createServerHandler<
           | undefined)
       : null;
 
-    // Transform outbound if provided
-    const outputRows = pageRows.map((r) =>
-      applyOutboundTransform(r as Selectable<ServerDB[TableName]>)
-    );
+    let outputRows: unknown[];
+    if (transformOutbound) {
+      outputRows = pageRows.map((r) =>
+        applyOutboundTransform(r as Selectable<ServerDB[TableName]>)
+      );
+    } else {
+      const firstRow = pageRows[0] as Record<string, unknown> | undefined;
+      const tableCodecs = firstRow
+        ? toTableColumnCodecs(table, codecs, Object.keys(firstRow), {
+            dialect: codecDialect,
+          })
+        : {};
+      if (Object.keys(tableCodecs).length === 0) {
+        outputRows = pageRows;
+      } else {
+        outputRows = pageRows.map((r) =>
+          applyCodecsFromDbRow(
+            r as Record<string, unknown>,
+            tableCodecs,
+            codecDialect
+          )
+        );
+      }
+    }
 
     return {
       rows: outputRows,
@@ -445,8 +608,8 @@ export function createServerHandler<
         result: {
           opIndex,
           status: 'error',
-          error: `UNKNOWN_TABLE:${op.table}`,
-          code: 'UNKNOWN_TABLE',
+          error: `Unknown table: ${op.table}`,
+          code: 'sync.unknown_table',
           retriable: false,
         },
         emittedChanges: [],
@@ -472,6 +635,25 @@ export function createServerHandler<
 
     // Handle delete
     if (op.op === 'delete') {
+      const existingRow = (await (
+        trx.selectFrom(table).selectAll() as SelectQueryBuilder<
+          ServerDB,
+          keyof ServerDB & string,
+          Record<string, unknown>
+        >
+      )
+        .where(ref<string>(primaryKey), '=', op.row_id)
+        .executeTakeFirst()) as Record<string, unknown> | undefined;
+
+      if (!existingRow) {
+        return { result: { opIndex, status: 'applied' }, emittedChanges: [] };
+      }
+
+      const scopeAuth = await authorizeRowScopes(ctx, existingRow);
+      if (scopeAuth !== true) {
+        return rejectionResult(opIndex, scopeAuth);
+      }
+
       const deleted = await (
         trx.deleteFrom(table) as DeleteQueryBuilder<
           ServerDB,
@@ -484,9 +666,8 @@ export function createServerHandler<
         .executeTakeFirst();
 
       const deletedRow = deleted as Record<string, unknown> | undefined;
-      if (!deletedRow) {
+      if (!deletedRow)
         return { result: { opIndex, status: 'applied' }, emittedChanges: [] };
-      }
 
       // Extract scopes from existing row for the delete emission
       const scopes = extractScopesImpl(deletedRow);
@@ -513,6 +694,29 @@ export function createServerHandler<
         ? (rawPayload as Record<string, unknown>)
         : {};
     const payload = applyInboundTransform(payloadRecord, ctx.schemaVersion);
+    const rowForInsertScopeCheck: Record<string, unknown> = {
+      ...payload,
+      [primaryKey]: op.row_id,
+      [versionColumn]: 1,
+    };
+
+    const existingRowBeforeWrite = (await (
+      trx.selectFrom(table).selectAll() as SelectQueryBuilder<
+        ServerDB,
+        keyof ServerDB & string,
+        Record<string, unknown>
+      >
+    )
+      .where(ref<string>(primaryKey), '=', op.row_id)
+      .executeTakeFirst()) as Record<string, unknown> | undefined;
+
+    const rowScopeAuth = await authorizeRowScopes(
+      ctx,
+      existingRowBeforeWrite ?? rowForInsertScopeCheck
+    );
+    if (rowScopeAuth !== true) {
+      return rejectionResult(opIndex, rowScopeAuth);
+    }
 
     let updated: Record<string, unknown> | undefined;
     let constraintError: { message: string; code: string } | null = null;
@@ -544,7 +748,7 @@ export function createServerHandler<
           .executeTakeFirst()) as Record<string, unknown> | undefined;
 
         if (!updated) {
-          const conflictRow = await (
+          let conflictRow = await (
             trx.selectFrom(table).selectAll() as SelectQueryBuilder<
               ServerDB,
               keyof ServerDB & string,
@@ -554,100 +758,118 @@ export function createServerHandler<
             .where(ref<string>(primaryKey), '=', op.row_id)
             .executeTakeFirst();
 
-          if (!conflictRow) {
+          if (!conflictRow && expectedVersion === 0) {
+            const insertValues: Record<string, unknown> = {
+              ...payload,
+              [primaryKey]: op.row_id,
+              [versionColumn]: 1,
+            };
+
+            try {
+              updated = (await (
+                trx.insertInto(table) as InsertQueryBuilder<
+                  ServerDB,
+                  TableName,
+                  InsertResult
+                >
+              )
+                .values(insertValues as Insertable<ServerDB[TableName]>)
+                .returningAll()
+                .executeTakeFirst()) as Record<string, unknown> | undefined;
+            } catch (err) {
+              const message = err instanceof Error ? err.message : String(err);
+              if (!isConstraintViolationError(message)) {
+                throw err;
+              }
+              conflictRow = await (
+                trx.selectFrom(table).selectAll() as SelectQueryBuilder<
+                  ServerDB,
+                  keyof ServerDB & string,
+                  Record<string, unknown>
+                >
+              )
+                .where(ref<string>(primaryKey), '=', op.row_id)
+                .executeTakeFirst();
+            }
+          }
+
+          if (!updated && !conflictRow) {
             return {
               result: {
                 opIndex,
                 status: 'error',
-                error: 'ROW_NOT_FOUND_FOR_BASE_VERSION',
-                code: 'ROW_MISSING',
+                error: 'Row not found for base version',
+                code: 'sync.row_missing',
                 retriable: false,
               },
               emittedChanges: [],
             };
           }
 
-          const existingVersion =
-            (conflictRow[versionColumn] as number | undefined) ?? 0;
-          return {
-            result: {
-              opIndex,
-              status: 'conflict',
-              message: `Version conflict: server=${existingVersion}, base=${expectedVersion}`,
-              server_version: existingVersion,
-              server_row: applyOutboundTransform(
-                conflictRow as Selectable<ServerDB[TableName]>
-              ),
-            },
-            emittedChanges: [],
-          };
+          if (!updated && conflictRow) {
+            const conflictScopeAuth = await authorizeRowScopes(
+              ctx,
+              conflictRow
+            );
+            if (conflictScopeAuth !== true) {
+              return rejectionResult(opIndex, conflictScopeAuth);
+            }
+
+            const existingVersion = readSafeVersionColumn(
+              conflictRow,
+              versionColumn,
+              0
+            );
+            return {
+              result: {
+                opIndex,
+                status: 'conflict',
+                message: `Version conflict: server=${existingVersion}, base=${expectedVersion}`,
+                code: 'sync.version_conflict',
+                server_version: existingVersion,
+                server_row: normalizeOutboundVersionColumn(
+                  applyOutboundTransform(
+                    conflictRow as Selectable<ServerDB[TableName]>
+                  ),
+                  versionColumn,
+                  existingVersion
+                ),
+              },
+              emittedChanges: [],
+            };
+          }
         }
       } else {
         const updateSet: Record<string, unknown> = {
           ...payload,
-          [versionColumn]: sql`${sql.ref(versionColumn)} + 1`,
+          [versionColumn]: sql`${sql.ref(qualifiedVersionRef)} + 1`,
         };
         delete updateSet[primaryKey];
         for (const col of Object.values(scopeColumns)) {
           delete updateSet[col];
         }
 
+        const insertValues: Record<string, unknown> = {
+          ...payload,
+          [primaryKey]: op.row_id,
+          [versionColumn]: 1,
+        };
+
         updated = (await (
-          trx.updateTable(table) as UpdateQueryBuilder<
+          trx.insertInto(table) as InsertQueryBuilder<
             ServerDB,
             TableName,
-            TableName,
-            UpdateResult
+            InsertResult
           >
         )
-          .set(updateSet as UpdateSetObject)
-          .where(ref<string>(primaryKey), '=', op.row_id)
+          .values(insertValues as Insertable<ServerDB[TableName]>)
+          .onConflict((oc) =>
+            oc
+              .column(primaryKeyColumn)
+              .doUpdateSet(updateSet as UpdateSetObject)
+          )
           .returningAll()
           .executeTakeFirst()) as Record<string, unknown> | undefined;
-
-        if (!updated) {
-          const insertValues: Record<string, unknown> = {
-            ...payload,
-            [primaryKey]: op.row_id,
-            [versionColumn]: 1,
-          };
-
-          try {
-            updated = (await (
-              trx.insertInto(table) as InsertQueryBuilder<
-                ServerDB,
-                TableName,
-                InsertResult
-              >
-            )
-              .values(insertValues as Insertable<ServerDB[TableName]>)
-              .returningAll()
-              .executeTakeFirst()) as Record<string, unknown> | undefined;
-          } catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            if (!isConstraintViolationError(message)) {
-              throw err;
-            }
-            updated = (await (
-              trx.updateTable(table) as UpdateQueryBuilder<
-                ServerDB,
-                TableName,
-                TableName,
-                UpdateResult
-              >
-            )
-              .set(updateSet as UpdateSetObject)
-              .where(ref<string>(primaryKey), '=', op.row_id)
-              .returningAll()
-              .executeTakeFirst()) as Record<string, unknown> | undefined;
-            if (!updated) {
-              constraintError = {
-                message,
-                code: classifyConstraintViolationCode(message),
-              };
-            }
-          }
-        }
       }
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -666,8 +888,8 @@ export function createServerHandler<
             result: {
               opIndex,
               status: 'error',
-              error: 'ROW_NOT_FOUND_FOR_BASE_VERSION',
-              code: 'ROW_MISSING',
+              error: 'Row not found for base version',
+              code: 'sync.row_missing',
               retriable: false,
             },
             emittedChanges: [],
@@ -703,14 +925,16 @@ export function createServerHandler<
     }
 
     const updatedRow = updated;
-    const rowVersion = (updatedRow[versionColumn] as number) ?? 1;
+    const rowVersion = readSafeVersionColumn(updatedRow, versionColumn, 1);
 
     // Extract scopes from updated row
     const scopes = extractScopesImpl(updatedRow);
 
     // Transform outbound for emitted change
-    const rowJson = applyOutboundTransform(
-      updated as Selectable<ServerDB[TableName]>
+    const rowJson = normalizeOutboundVersionColumn(
+      applyOutboundTransform(updated as Selectable<ServerDB[TableName]>),
+      versionColumn,
+      rowVersion
     );
 
     const emitted: EmittedChange = {
@@ -728,14 +952,183 @@ export function createServerHandler<
     };
   };
 
+  const defaultApplyOperationBatch = async (
+    ctx: ServerApplyOperationContext<ServerDB, Auth>,
+    operations: BatchApplyOperationInput[]
+  ): Promise<ApplyOperationResult[]> => {
+    if (operations.length === 0) return [];
+
+    const runSequentialFallback = async (): Promise<ApplyOperationResult[]> => {
+      const sequential: ApplyOperationResult[] = [];
+      for (const entry of operations) {
+        const applied = await defaultApplyOperation(
+          ctx,
+          entry.op,
+          entry.opIndex
+        );
+        sequential.push(applied);
+        if (applied.result.status !== 'applied') {
+          break;
+        }
+      }
+      return sequential;
+    };
+
+    if (operations.length === 1 || authorize || requiredScopeKeys.length > 0) {
+      return runSequentialFallback();
+    }
+
+    const trx = ctx.trx;
+    const prepared: Array<{
+      entry: BatchApplyOperationInput;
+      payload: Record<string, unknown>;
+      insertValues: Record<string, unknown>;
+    }> = [];
+    const seenRowIds = new Set<string>();
+    const payloadKeySignatures = new Set<string>();
+
+    for (const entry of operations) {
+      const op = entry.op;
+      if (op.table !== table || op.op !== 'upsert' || op.base_version != null) {
+        return runSequentialFallback();
+      }
+      if (seenRowIds.has(op.row_id)) {
+        return runSequentialFallback();
+      }
+      seenRowIds.add(op.row_id);
+
+      const rawPayload = op.payload ?? {};
+      const payloadRecord =
+        rawPayload !== null && typeof rawPayload === 'object'
+          ? (rawPayload as Record<string, unknown>)
+          : {};
+      const payload = applyInboundTransform(
+        payloadRecord,
+        ctx.schemaVersion
+      ) as Record<string, unknown>;
+
+      payloadKeySignatures.add(Object.keys(payload).sort().join('\u0000'));
+
+      const insertValues: Record<string, unknown> = {
+        ...payload,
+        [primaryKey]: op.row_id,
+        [versionColumn]: 1,
+      };
+
+      prepared.push({
+        entry,
+        payload,
+        insertValues,
+      });
+    }
+
+    if (prepared.length <= 1 || payloadKeySignatures.size !== 1) {
+      return runSequentialFallback();
+    }
+
+    const basePayload = prepared[0]!.payload;
+    const updateSet: Record<string, unknown> = {
+      ...basePayload,
+      [versionColumn]: sql`${sql.ref(qualifiedVersionRef)} + 1`,
+    };
+    delete updateSet[primaryKey];
+    for (const col of Object.values(scopeColumns)) {
+      delete updateSet[col];
+    }
+
+    try {
+      const updatedRows = (await (
+        trx.insertInto(table) as InsertQueryBuilder<
+          ServerDB,
+          TableName,
+          InsertResult
+        >
+      )
+        .values(
+          prepared.map(
+            (item) => item.insertValues as Insertable<ServerDB[TableName]>
+          )
+        )
+        .onConflict((oc) =>
+          oc.column(primaryKeyColumn).doUpdateSet(updateSet as UpdateSetObject)
+        )
+        .returningAll()
+        .execute()) as Record<string, unknown>[];
+
+      const updatedById = new Map<string, Record<string, unknown>>();
+      for (const row of updatedRows) {
+        const rowIdValue = row[primaryKey];
+        if (rowIdValue === null || rowIdValue === undefined) continue;
+        updatedById.set(String(rowIdValue), row);
+      }
+
+      const results: ApplyOperationResult[] = [];
+      for (const item of prepared) {
+        const rowId = item.entry.op.row_id;
+        const updated = updatedById.get(rowId);
+        if (!updated) {
+          return runSequentialFallback();
+        }
+
+        const rowVersion = readSafeVersionColumn(updated, versionColumn, 1);
+        const scopes = extractScopesImpl(updated);
+        const rowJson = normalizeOutboundVersionColumn(
+          applyOutboundTransform(updated as Selectable<ServerDB[TableName]>),
+          versionColumn,
+          rowVersion
+        );
+
+        results.push({
+          result: { opIndex: item.entry.opIndex, status: 'applied' },
+          emittedChanges: [
+            {
+              table,
+              row_id: rowId,
+              op: 'upsert',
+              row_json: rowJson,
+              row_version: rowVersion,
+              scopes,
+            },
+          ],
+        });
+      }
+
+      return results;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (isConstraintViolationError(message)) {
+        return runSequentialFallback();
+      }
+      throw err;
+    }
+  };
+
   return {
     table,
+    primaryKeyColumn,
     scopePatterns,
     dependsOn,
     snapshotChunkTtlMs,
+    snapshotBinaryColumns,
+    snapshotBinaryColumnsForVersion,
+    snapshotBinaryEncoder: snapshotBinaryEncoder as
+      | BinarySnapshotRowsEncoder
+      | undefined,
+    snapshotBinaryEncoderForVersion: snapshotBinaryEncoderForVersion as
+      | ((
+          schemaVersion: number
+        ) => BinarySnapshotRowsEncoder | null | undefined)
+      | undefined,
+    canRejectSingleOperationWithoutSavepoint:
+      options.canRejectSingleOperationWithoutSavepoint ??
+      options.applyOperation === undefined,
     resolveScopes: resolveScopesImpl,
     extractScopes: extractScopesImpl,
     snapshot: options.snapshot ?? defaultSnapshot,
     applyOperation: options.applyOperation ?? defaultApplyOperation,
+    applyOperationBatch:
+      options.applyOperation === undefined
+        ? defaultApplyOperationBatch
+        : undefined,
   };
 }