@syncular/server 0.1.3 → 0.2.1

package/src/handlers/create-handler.ts

@@ -1,1134 +0,0 @@
-/**
- * @syncular/server - Declarative server handler helper
- */
-
-import type {
-  BinarySnapshotColumn,
-  BinarySnapshotRowsEncoder,
-  ScopeValues,
-  ScopeValuesFromPatterns,
-  ScopeDefinition as SimpleScopeDefinition,
-  StoredScopes,
-  SyncOperation,
-} from '@syncular/core';
-import {
-  applyCodecsFromDbRow,
-  applyCodecsToDbRow,
-  type ColumnCodecDialect,
-  type ColumnCodecSource,
-  createSingleVariableScopeMetadata,
-  createTableColumnCodecsResolver,
-  type SyncularErrorCode,
-  toTableColumnCodecs,
-} from '@syncular/core';
-import type {
-  DeleteQueryBuilder,
-  DeleteResult,
-  Insertable,
-  InsertQueryBuilder,
-  InsertResult,
-  Selectable,
-  SelectQueryBuilder,
-  Updateable,
-  UpdateQueryBuilder,
-  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,
-  ServerSnapshotContext,
-  ServerTableHandler,
-  SyncServerAuth,
-} from './types';
-
-/**
- * Authorization result from authorize callback.
- */
-type AuthorizeResult =
-  | true
-  | { error: string; code: SyncularErrorCode; retriable?: boolean };
-
-function classifyConstraintViolationCode(_message: string): SyncularErrorCode {
-  return 'sync.constraint_violation';
-}
-
-function isConstraintViolationError(message: string): boolean {
-  const normalized = message.toLowerCase();
-  return (
-    normalized.includes('constraint') ||
-    normalized.includes('not null') ||
-    normalized.includes('foreign key') ||
-    normalized.includes('unique')
-  );
-}
-
-function isMissingColumnReferenceError(message: string): boolean {
-  const normalized = message.toLowerCase();
-  return (
-    normalized.includes('no such column') ||
-    (normalized.includes('column') && normalized.includes('does not exist'))
-  );
-}
-
-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.
- */
-export interface CreateServerHandlerOptions<
-  ServerDB extends SyncCoreDb,
-  ClientDB,
-  TableName extends keyof ServerDB & keyof ClientDB & string,
-  Auth extends SyncServerAuth = SyncServerAuth,
-  ScopeDefs extends
-    readonly SimpleScopeDefinition[] = readonly SimpleScopeDefinition[],
-> {
-  /** Table name in the database */
-  table: TableName;
-
-  /**
-   * Scope definitions for this table.
-   * Can be simple strings (column auto-derived) or objects with explicit mapping.
-   *
-   * @example
-   * ```typescript
-   * // Simple: column auto-derived from placeholder
-   * scopes: ['user:{user_id}', 'org:{org_id}']
-   *
-   * // Explicit: when column differs from pattern variable
-   * scopes: [
-   *   { pattern: 'user:{user_id}', column: 'owner_id' }
-   * ]
-   * ```
-   */
-  scopes: ScopeDefs;
-
-  /** Primary key column name (default: 'id') */
-  primaryKey?: string;
-
-  /** Version column name (default: 'server_version') */
-  versionColumn?: string;
-
-  /** Tables this handler depends on (for bootstrap ordering) */
-  dependsOn?: string[];
-
-  /** 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.
-   *
-   * @example
-   * resolveScopes: async (ctx) => ({
-   *   user_id: [ctx.actorId],
-   *   project_id: await getProjectsForUser(ctx.db, ctx.actorId),
-   * })
-   */
-  resolveScopes: (
-    ctx: ServerContext<ServerDB, Auth>
-  ) => Promise<ScopeValuesFromPatterns<ScopeDefs>>;
-
-  /**
-   * Transform inbound row from client to server format.
-   * Use ctx.schemaVersion to handle older client versions.
-   */
-  transformInbound?: (
-    row: Selectable<ClientDB[TableName]>,
-    ctx: { schemaVersion?: number }
-  ) => Updateable<ServerDB[TableName]>;
-
-  /**
-   * Transform outbound row from server to client format.
-   */
-  transformOutbound?: (
-    row: Selectable<ServerDB[TableName]>
-  ) => Selectable<ClientDB[TableName]>;
-
-  /**
-   * Optional column codec resolver.
-   * Receives `{ table, column, sqlType?, dialect? }` and returns a codec.
-   * Only used by default snapshot/apply paths when the corresponding
-   * transform hook is not provided.
-   */
-  codecs?: ColumnCodecSource;
-
-  /**
-   * Dialect used for codec dialect overrides.
-   * Default: 'sqlite'
-   */
-  codecDialect?: ColumnCodecDialect;
-
-  /**
-   * Authorize an operation before applying.
-   * Return true to allow, or an error object to reject.
-   */
-  authorize?: (
-    ctx: ServerApplyOperationContext<ServerDB, Auth>,
-    op: SyncOperation
-  ) => Promise<AuthorizeResult>;
-
-  /**
-   * Override: Build snapshot query.
-   */
-  snapshot?: ServerTableHandler<ServerDB, Auth>['snapshot'];
-
-  /**
-   * Override: Apply operation.
-   */
-  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).
-   */
-  extractScopes?: (row: Record<string, unknown>) => StoredScopes;
-}
-
-/**
- * Create a declarative server table handler with sensible defaults.
- *
- * @example
- * ```typescript
- * import { createServerHandler } from '@syncular/server';
- * import type { ServerDb } from '../db';
- * import type { ClientDb } from '../../shared/client-db.generated';
- *
- * export const tasksHandler = createServerHandler<ServerDb, ClientDb, 'tasks'>({
- *   table: 'tasks',
- *   scopes: ['user:{user_id}'],  // column auto-derived from placeholder
- *   resolveScopes: async (ctx) => ({
- *     user_id: [ctx.actorId],
- *   }),
- * });
- *
- * // With custom column mapping:
- * export const tasksHandler = createServerHandler<ServerDb, ClientDb, 'tasks'>({
- *   table: 'tasks',
- *   scopes: [{ pattern: 'user:{user_id}', column: 'owner_id' }],
- *   resolveScopes: async (ctx) => ({
- *     user_id: [ctx.actorId],
- *   }),
- * });
- * ```
- */
-export function createServerHandler<
-  ServerDB extends SyncCoreDb,
-  ClientDB,
-  TableName extends keyof ServerDB & keyof ClientDB & string,
-  Auth extends SyncServerAuth = SyncServerAuth,
-  ScopeDefs extends
-    readonly SimpleScopeDefinition[] = readonly SimpleScopeDefinition[],
->(
-  options: CreateServerHandlerOptions<
-    ServerDB,
-    ClientDB,
-    TableName,
-    Auth,
-    ScopeDefs
-  >
-): ServerTableHandler<ServerDB, Auth> {
-  type OverloadParameters<T> = T extends (...args: infer A) => unknown
-    ? A
-    : never;
-
-  type UpdateSetObject = Extract<
-    OverloadParameters<
-      UpdateQueryBuilder<ServerDB, TableName, TableName, UpdateResult>['set']
-    >,
-    [unknown]
-  >[0];
-
-  const {
-    table,
-    scopes: scopeDefs,
-    primaryKey = 'id',
-    versionColumn = 'server_version',
-    dependsOn,
-    snapshotChunkTtlMs,
-    snapshotBinaryColumns,
-    snapshotBinaryColumnsForVersion,
-    snapshotBinaryEncoder,
-    snapshotBinaryEncoderForVersion,
-    resolveScopes,
-    transformInbound,
-    transformOutbound,
-    codecs,
-    codecDialect = 'sqlite',
-    authorize,
-    extractScopes: customExtractScopes,
-  } = options;
-  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 => {
-    const scopes: StoredScopes = {};
-    for (const [varName, columnName] of Object.entries(scopeColumns)) {
-      const raw = row[columnName];
-      if (raw === null || raw === undefined) continue;
-      const value = String(raw);
-      if (value.length > 0) {
-        scopes[varName] = value;
-      }
-    }
-    return scopes;
-  };
-
-  const extractScopesImpl = customExtractScopes ?? defaultExtractScopes;
-
-  const resolveScopesImpl = async (
-    ctx: ServerContext<ServerDB, Auth>
-  ): Promise<ScopeValues> => {
-    const resolved = await resolveScopes(ctx);
-    const normalized: ScopeValues = {};
-    for (const [scopeKey, scopeValue] of Object.entries(resolved)) {
-      // 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]>
-  ): Selectable<ClientDB[TableName]> => {
-    if (transformOutbound) {
-      return transformOutbound(row);
-    }
-
-    const recordRow = row as Record<string, unknown>;
-    const transformed = applyCodecsFromDbRow(
-      recordRow,
-      resolveTableCodecs(recordRow),
-      codecDialect
-    );
-    return transformed as Selectable<ClientDB[TableName]>;
-  };
-
-  const applyInboundTransform = (
-    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,
-      });
-    }
-
-    const transformed = applyCodecsToDbRow(
-      row,
-      resolveTableCodecs(row),
-      codecDialect
-    );
-    return transformed as Updateable<ServerDB[TableName]>;
-  };
-
-  // Default snapshot implementation
-  const defaultSnapshot = async (
-    ctx: ServerSnapshotContext<ServerDB, string, Auth>,
-    _params: Record<string, unknown> | undefined
-  ): Promise<{ rows: unknown[]; nextCursor: string | null }> => {
-    const trx = ctx.db;
-    const { ref } = trx.dynamic;
-    const scopeValues = ctx.scopeValues;
-
-    const pageSize = Math.max(1, ctx.limit);
-
-    let q = trx.selectFrom(table) as SelectQueryBuilder<
-      ServerDB,
-      keyof ServerDB & string,
-      Record<string, unknown>
-    >;
-
-    q = q.selectAll() as SelectQueryBuilder<
-      ServerDB,
-      keyof ServerDB & string,
-      Record<string, unknown>
-    >;
-
-    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>(columnName), 'in', normalized);
-      }
-    }
-
-    if (ctx.cursor !== null) {
-      q = q.where(ref<string>(primaryKey), '>', ctx.cursor);
-    }
-
-    const rows = await q
-      .orderBy(ref<string>(primaryKey), 'asc')
-      .limit(pageSize + 1)
-      .execute();
-
-    const hasMore = rows.length > pageSize;
-    const pageRows = hasMore ? rows.slice(0, pageSize) : rows;
-    const lastRow = pageRows[pageRows.length - 1] as
-      | (typeof rows)[number]
-      | undefined;
-    const nextCursor = hasMore
-      ? ((lastRow as Record<string, unknown> | undefined)?.[primaryKey] as
-          | string
-          | undefined)
-      : null;
-
-    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,
-      nextCursor:
-        typeof nextCursor === 'string' && nextCursor.length > 0
-          ? nextCursor
-          : null,
-    };
-  };
-
-  // Default applyOperation implementation
-  const defaultApplyOperation = async (
-    ctx: ServerApplyOperationContext<ServerDB, Auth>,
-    op: SyncOperation,
-    opIndex: number
-  ): Promise<ApplyOperationResult> => {
-    const trx = ctx.trx;
-    const { ref } = trx.dynamic;
-
-    if (op.table !== table) {
-      return {
-        result: {
-          opIndex,
-          status: 'error',
-          error: `Unknown table: ${op.table}`,
-          code: 'sync.unknown_table',
-          retriable: false,
-        },
-        emittedChanges: [],
-      };
-    }
-
-    // Run authorization if provided
-    if (authorize) {
-      const authResult = await authorize(ctx, op);
-      if (authResult !== true) {
-        return {
-          result: {
-            opIndex,
-            status: 'error',
-            error: authResult.error,
-            code: authResult.code,
-            retriable: authResult.retriable ?? false,
-          },
-          emittedChanges: [],
-        };
-      }
-    }
-
-    // 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,
-          keyof ServerDB & string,
-          DeleteResult
-        >
-      )
-        .where(ref<string>(primaryKey), '=', op.row_id)
-        .returningAll()
-        .executeTakeFirst();
-
-      const deletedRow = deleted as Record<string, unknown> | undefined;
-      if (!deletedRow)
-        return { result: { opIndex, status: 'applied' }, emittedChanges: [] };
-
-      // Extract scopes from existing row for the delete emission
-      const scopes = extractScopesImpl(deletedRow);
-
-      const emitted: EmittedChange = {
-        table,
-        row_id: op.row_id,
-        op: 'delete',
-        row_json: null,
-        row_version: null,
-        scopes,
-      };
-
-      return {
-        result: { opIndex, status: 'applied' },
-        emittedChanges: [emitted],
-      };
-    }
-
-    // Handle upsert
-    const rawPayload = op.payload ?? {};
-    const payloadRecord =
-      rawPayload !== null && typeof rawPayload === 'object'
-        ? (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;
-
-    try {
-      if (op.base_version != null) {
-        const expectedVersion = op.base_version;
-        const conditionalUpdateSet: Record<string, unknown> = {
-          ...payload,
-          [versionColumn]: expectedVersion + 1,
-        };
-        delete conditionalUpdateSet[primaryKey];
-        for (const col of Object.values(scopeColumns)) {
-          delete conditionalUpdateSet[col];
-        }
-
-        updated = (await (
-          trx.updateTable(table) as UpdateQueryBuilder<
-            ServerDB,
-            TableName,
-            TableName,
-            UpdateResult
-          >
-        )
-          .set(conditionalUpdateSet as UpdateSetObject)
-          .where(ref<string>(primaryKey), '=', op.row_id)
-          .where(ref<string>(versionColumn), '=', expectedVersion)
-          .returningAll()
-          .executeTakeFirst()) as Record<string, unknown> | undefined;
-
-        if (!updated) {
-          let conflictRow = await (
-            trx.selectFrom(table).selectAll() as SelectQueryBuilder<
-              ServerDB,
-              keyof ServerDB & string,
-              Record<string, unknown>
-            >
-          )
-            .where(ref<string>(primaryKey), '=', op.row_id)
-            .executeTakeFirst();
-
-          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: 'sync.row_missing',
-                retriable: false,
-              },
-              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(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.insertInto(table) as InsertQueryBuilder<
-            ServerDB,
-            TableName,
-            InsertResult
-          >
-        )
-          .values(insertValues as Insertable<ServerDB[TableName]>)
-          .onConflict((oc) =>
-            oc
-              .column(primaryKeyColumn)
-              .doUpdateSet(updateSet as UpdateSetObject)
-          )
-          .returningAll()
-          .executeTakeFirst()) as Record<string, unknown> | undefined;
-      }
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      if (op.base_version != null && isMissingColumnReferenceError(message)) {
-        const row = await (
-          trx.selectFrom(table).selectAll() as SelectQueryBuilder<
-            ServerDB,
-            keyof ServerDB & string,
-            Record<string, unknown>
-          >
-        )
-          .where(ref<string>(primaryKey), '=', op.row_id)
-          .executeTakeFirst();
-        if (!row) {
-          return {
-            result: {
-              opIndex,
-              status: 'error',
-              error: 'Row not found for base version',
-              code: 'sync.row_missing',
-              retriable: false,
-            },
-            emittedChanges: [],
-          };
-        }
-      }
-
-      if (!isConstraintViolationError(message)) {
-        throw err;
-      }
-
-      constraintError = {
-        message,
-        code: classifyConstraintViolationCode(message),
-      };
-    }
-
-    if (constraintError) {
-      return {
-        result: {
-          opIndex,
-          status: 'error',
-          error: constraintError.message,
-          code: constraintError.code,
-          retriable: false,
-        },
-        emittedChanges: [],
-      };
-    }
-
-    if (!updated) {
-      throw new Error('Updated row is missing after applyOperation');
-    }
-
-    const updatedRow = updated;
-    const rowVersion = readSafeVersionColumn(updatedRow, versionColumn, 1);
-
-    // Extract scopes from updated row
-    const scopes = extractScopesImpl(updatedRow);
-
-    // Transform outbound for emitted change
-    const rowJson = normalizeOutboundVersionColumn(
-      applyOutboundTransform(updated as Selectable<ServerDB[TableName]>),
-      versionColumn,
-      rowVersion
-    );
-
-    const emitted: EmittedChange = {
-      table,
-      row_id: op.row_id,
-      op: 'upsert',
-      row_json: rowJson,
-      row_version: rowVersion,
-      scopes,
-    };
-
-    return {
-      result: { opIndex, status: 'applied' },
-      emittedChanges: [emitted],
-    };
-  };
-
-  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,
-  };
-}