refactor(tables): make lib/table/orchestration the single implementation

Column update was implemented four times — the UI route, v1, v2, and the
copilot table tool — each calling the same column services but owning its own
guards, error mapping, and audit. The copies had drifted, and the drift was the
bug: v2 was missing both guards, only the copilot copy minted stable option
ids, and only v1/v2 audited.

performUpdateTableColumn, performDeleteTable, and performDeleteTableRow now own
that logic; all ten call sites reduce to auth, parse, call, render. The guards
are asserted once in lib/table/orchestration rather than four times against
four routes.

Behavior this consolidates, previously true on only some paths:

- The typeChanging guard. updateColumnType early-returns on an unchanged type
  and drops any options sent with it, so restating the current type alongside
  new options silently discarded them. v2 had no guard at all and, since its
  contract shares v1's body schema, accepted options and ignored them.
- The select-unique guard. Each write is its own locked transaction, so a
  rename or type change paired with a constraint write that is going to fail
  commits first and then throws, half-applying the schema change.
- Stable select-option ids. Cells reference the option id, so an edit that
  re-sends an option by name has to reuse it or every cell holding it is
  orphaned. Only the copilot path did this; normalizeSelectOptionsInput moves to
  lib/table/select-options and now covers every caller. It preserves a supplied
  id, so it is a no-op for the fully-formed options the HTTP contracts accept.
- required forwarded into the type and options writes, so a conversion
  validates against the constraint the same request is setting.
- An audit on every successful update. The UI route and the copilot tool
  emitted none.
- Single-row delete through the row service. v2 did a raw db.delete, skipping
  assertRowDelete and deleteOrderedRow, so a delete-locked table returned 200
  and the row-count bookkeeping never ran.
- The delete actor handed to deleteTable, which audits only when a row was
  actually archived. v1 and v2 omitted it and audited themselves outside that
  check, emitting TABLE_DELETED for a no-op delete of an archived table.

Failure classes come back as OrchestrationErrorCode; v2 renders them through a
new v2ErrorForOrchestration, mirroring statusForOrchestrationError on the v1
and UI surfaces, so a given failure maps to the same status everywhere.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: TheodoreSpeaks

apps/sim/app/api/table/[tableId]/columns/route.ts

@@ -8,17 +8,11 @@ import {
 import { parseRequest } from '@/lib/api/server'
 import { isZodError, validationErrorResponse } from '@/lib/api/server/validation'
 import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
+import { statusForOrchestrationError } from '@/lib/core/orchestration/types'
 import { generateRequestId } from '@/lib/core/utils/request'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
-import {
-  addTableColumn,
-  deleteColumn,
-  renameColumn,
-  updateColumnConstraints,
-  updateColumnOptions,
-  updateColumnType,
-} from '@/lib/table'
-import { columnMatchesRef } from '@/lib/table/column-keys'
+import { addTableColumn, deleteColumn } from '@/lib/table'
+import { performUpdateTableColumn } from '@/lib/table/orchestration'
 import {
   accessError,
   checkAccess,
@@ -117,111 +111,31 @@ export const PATCH = withRouteHandler(async (request: NextRequest, context: Colu
       return NextResponse.json({ error: 'Invalid workspace ID' }, { status: 400 })
     }
 
-    const { updates } = validated
-    let updatedTable = null
-
-    if (updates.name) {
-      updatedTable = await renameColumn(
-        { tableId, oldName: validated.columnName, newName: updates.name },
-        requestId
-      )
-    }
-
-    // A payload that repeats the current type must not go through
-    // `updateColumnType` — it early-returns on an unchanged type and would drop
-    // any `options` alongside it. Only a real type change routes there; an
-    // unchanged type with options routes to the options-only update.
-    const currentColumn = table.schema.columns.find((c) =>
-      columnMatchesRef(c, validated.columnName)
-    )
-    const typeChanging = updates.type !== undefined && updates.type !== currentColumn?.type
-
-    // Every write below is its own locked transaction, so any of them paired
-    // with a constraint write that is going to fail commits and then errors.
-    // Gate on the type the column ENDS UP with, not on whether the type is
-    // changing: an options-only update on an existing select column carries the
-    // same hazard as a conversion does.
-    const resultingType = updates.type ?? currentColumn?.type
-    if (updates.unique === true && resultingType === 'select') {
-      return NextResponse.json({ error: 'Cannot set a select column as unique' }, { status: 400 })
-    }
-
-    if (typeChanging) {
-      updatedTable = await updateColumnType(
-        {
-          tableId,
-          columnName: updates.name ?? validated.columnName,
-          newType: updates.type as NonNullable<typeof updates.type>,
-          ...(updates.options !== undefined ? { options: updates.options } : {}),
-          ...(updates.multiple !== undefined ? { multiple: updates.multiple } : {}),
-          // Forwarded so the conversion validates against the constraint this
-          // same request is about to set, not the column's current one.
-          ...(updates.required !== undefined ? { required: updates.required } : {}),
-        },
-        requestId
-      )
-    } else if (updates.options !== undefined || updates.multiple !== undefined) {
-      updatedTable = await updateColumnOptions(
-        {
-          tableId,
-          columnName: updates.name ?? validated.columnName,
-          options: updates.options ?? currentColumn?.options ?? [],
-          ...(updates.multiple !== undefined ? { multiple: updates.multiple } : {}),
-          // Forwarded so the removal guard validates against the constraint this
-          // same request is about to set, not the column's current one.
-          ...(updates.required !== undefined ? { required: updates.required } : {}),
-        },
-        requestId
-      )
-    }
-
-    if (updates.required !== undefined || updates.unique !== undefined) {
-      updatedTable = await updateColumnConstraints(
-        {
-          tableId,
-          columnName: updates.name ?? validated.columnName,
-          ...(updates.required !== undefined ? { required: updates.required } : {}),
-          ...(updates.unique !== undefined ? { unique: updates.unique } : {}),
-        },
-        requestId
+    const outcome = await performUpdateTableColumn({
+      table,
+      columnName: validated.columnName,
+      userId: authResult.userId,
+      updates: validated.updates,
+      requestId,
+    })
+    if (!outcome.success || !outcome.table) {
+      return NextResponse.json(
+        { error: outcome.error ?? 'Failed to update column' },
+        { status: statusForOrchestrationError(outcome.errorCode) }
       )
     }
 
-    if (!updatedTable) {
-      return NextResponse.json({ error: 'No updates specified' }, { status: 400 })
-    }
-
     return NextResponse.json({
       success: true,
       data: {
-        columns: updatedTable.schema.columns.map(normalizeColumn),
+        columns: outcome.table.schema.columns.map(normalizeColumn),
       },
     })
   } catch (error) {
-    const lockError = tableLockErrorResponse(error)
-    if (lockError) return lockError
     if (isZodError(error)) {
       return validationErrorResponse(error, 'Invalid request data')
     }
 
-    const msg = rootErrorMessage(error)
-    if (msg.includes('not found') || msg.includes('Table not found')) {
-      return NextResponse.json({ error: msg }, { status: 404 })
-    }
-    if (
-      msg.includes('already exists') ||
-      msg.includes('Cannot delete the last column') ||
-      msg.includes('Cannot set column') ||
-      msg.includes('Cannot set unique column') ||
-      msg.includes('Invalid column') ||
-      msg.includes('exceeds maximum') ||
-      msg.includes('incompatible') ||
-      msg.includes('duplicate') ||
-      msg.includes('option')
-    ) {
-      return NextResponse.json({ error: msg }, { status: 400 })
-    }
-
     logger.error(`[${requestId}] Error updating column in table ${tableId}:`, error)
     return NextResponse.json({ error: 'Failed to update column' }, { status: 500 })
   }

apps/sim/app/api/table/[tableId]/route.ts

@@ -5,12 +5,11 @@ import { getTableQuerySchema, updateTableContract } from '@/lib/api/contracts/ta
 import { isZodError, parseRequest, validationErrorResponse } from '@/lib/api/server/validation'
 import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
 import { isFeatureEnabled } from '@/lib/core/config/feature-flags'
+import { statusForOrchestrationError } from '@/lib/core/orchestration/types'
 import { generateRequestId } from '@/lib/core/utils/request'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { findActiveFolder } from '@/lib/folders/queries'
-import { captureServerEvent } from '@/lib/posthog/server'
 import {
-  deleteTable,
   getTableById,
   moveTableToFolder,
   renameTable,
@@ -19,6 +18,7 @@ import {
   updateTableLocks,
 } from '@/lib/table'
 import { getWorkspaceTableLimits } from '@/lib/table/billing'
+import { performDeleteTable } from '@/lib/table/orchestration'
 import { TABLE_LOCK_FLAGS, TABLE_LOCK_KINDS } from '@/lib/table/types'
 import { getWorkspaceWithOwner } from '@/lib/workspaces/permissions/utils'
 import {
@@ -268,14 +268,13 @@ export const DELETE = withRouteHandler(
         return NextResponse.json({ error: 'Invalid workspace ID' }, { status: 400 })
       }
 
-      await deleteTable(tableId, requestId, authResult.userId)
-
-      captureServerEvent(
-        authResult.userId,
-        'table_deleted',
-        { table_id: tableId, workspace_id: table.workspaceId },
-        { groups: { workspace: table.workspaceId } }
-      )
+      const outcome = await performDeleteTable({ table, userId: authResult.userId, requestId })
+      if (!outcome.success) {
+        return NextResponse.json(
+          { error: outcome.error ?? 'Failed to delete table' },
+          { status: statusForOrchestrationError(outcome.errorCode) }
+        )
+      }
 
       return NextResponse.json({
         success: true,

apps/sim/app/api/table/[tableId]/rows/[rowId]/route.ts

@@ -11,10 +11,12 @@ import {
 } from '@/lib/api/contracts/tables'
 import { isZodError, parseRequest, validationErrorResponse } from '@/lib/api/server/validation'
 import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
+import { statusForOrchestrationError } from '@/lib/core/orchestration/types'
 import { generateRequestId } from '@/lib/core/utils/request'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import type { RowData, TableSchema } from '@/lib/table'
-import { deleteRow, updateRow } from '@/lib/table'
+import { updateRow } from '@/lib/table'
+import { performDeleteTableRow } from '@/lib/table/orchestration'
 import { rowWireTranslators } from '@/app/api/table/row-wire'
 import {
   accessError,
@@ -212,7 +214,13 @@ export const DELETE = withRouteHandler(async (request: NextRequest, context: Row
       return NextResponse.json({ error: 'Invalid workspace ID' }, { status: 400 })
     }
 
-    await deleteRow(table, rowId, requestId)
+    const outcome = await performDeleteTableRow({ table, rowId, requestId })
+    if (!outcome.success) {
+      return NextResponse.json(
+        { error: outcome.error ?? 'Failed to delete row' },
+        { status: statusForOrchestrationError(outcome.errorCode) }
+      )
+    }
 
     return NextResponse.json({
       success: true,

apps/sim/app/api/v1/tables/[tableId]/columns/route.ts

@@ -7,17 +7,11 @@ import {
   v1UpdateTableColumnContract,
 } from '@/lib/api/contracts/v1/tables'
 import { parseRequest } from '@/lib/api/server'
+import { statusForOrchestrationError } from '@/lib/core/orchestration/types'
 import { generateRequestId } from '@/lib/core/utils/request'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
-import {
-  addTableColumn,
-  deleteColumn,
-  renameColumn,
-  updateColumnConstraints,
-  updateColumnOptions,
-  updateColumnType,
-} from '@/lib/table'
-import { columnMatchesRef } from '@/lib/table/column-keys'
+import { addTableColumn, deleteColumn } from '@/lib/table'
+import { performUpdateTableColumn } from '@/lib/table/orchestration'
 import {
   accessError,
   checkAccess,
@@ -151,123 +145,30 @@ export const PATCH = withRouteHandler(async (request: NextRequest, context: Colu
       return NextResponse.json({ error: 'Invalid workspace ID' }, { status: 400 })
     }
 
-    const { updates } = validated
-    let updatedTable = null
-
-    if (updates.name) {
-      updatedTable = await renameColumn(
-        { tableId, oldName: validated.columnName, newName: updates.name },
-        requestId
-      )
-    }
-
-    // A payload that repeats the current type must not go through
-    // `updateColumnType` — it early-returns on an unchanged type and would drop
-    // any `options` alongside it. Only a real type change routes there; an
-    // unchanged type with options routes to the options-only update.
-    const currentColumn = table.schema.columns.find((c) =>
-      columnMatchesRef(c, validated.columnName)
-    )
-    const typeChanging = updates.type !== undefined && updates.type !== currentColumn?.type
-
-    // Every write below is its own locked transaction, so any of them paired
-    // with a constraint write that is going to fail commits and then errors.
-    // Gate on the type the column ENDS UP with, not on whether the type is
-    // changing: an options-only update on an existing select column carries the
-    // same hazard as a conversion does.
-    const resultingType = updates.type ?? currentColumn?.type
-    if (updates.unique === true && resultingType === 'select') {
-      return NextResponse.json({ error: 'Cannot set a select column as unique' }, { status: 400 })
-    }
-
-    if (typeChanging) {
-      updatedTable = await updateColumnType(
-        {
-          tableId,
-          columnName: updates.name ?? validated.columnName,
-          newType: updates.type as NonNullable<typeof updates.type>,
-          ...(updates.options !== undefined ? { options: updates.options } : {}),
-          ...(updates.multiple !== undefined ? { multiple: updates.multiple } : {}),
-          // Forwarded so the conversion validates against the constraint this
-          // same request is about to set, not the column's current one.
-          ...(updates.required !== undefined ? { required: updates.required } : {}),
-        },
-        requestId
-      )
-    } else if (updates.options !== undefined || updates.multiple !== undefined) {
-      updatedTable = await updateColumnOptions(
-        {
-          tableId,
-          columnName: updates.name ?? validated.columnName,
-          options: updates.options ?? currentColumn?.options ?? [],
-          ...(updates.multiple !== undefined ? { multiple: updates.multiple } : {}),
-          // Forwarded so the removal guard validates against the constraint this
-          // same request is about to set, not the column's current one.
-          ...(updates.required !== undefined ? { required: updates.required } : {}),
-        },
-        requestId
-      )
-    }
-
-    if (updates.required !== undefined || updates.unique !== undefined) {
-      updatedTable = await updateColumnConstraints(
-        {
-          tableId,
-          columnName: updates.name ?? validated.columnName,
-          ...(updates.required !== undefined ? { required: updates.required } : {}),
-          ...(updates.unique !== undefined ? { unique: updates.unique } : {}),
-        },
-        requestId
+    const outcome = await performUpdateTableColumn({
+      table,
+      columnName: validated.columnName,
+      userId,
+      updates: validated.updates,
+      requestId,
+    })
+    if (!outcome.success || !outcome.table) {
+      return NextResponse.json(
+        { error: outcome.error ?? 'Failed to update column' },
+        { status: statusForOrchestrationError(outcome.errorCode) }
       )
     }
 
-    if (!updatedTable) {
-      return NextResponse.json({ error: 'No updates specified' }, { status: 400 })
-    }
-
-    recordAudit({
-      workspaceId: validated.workspaceId,
-      actorId: userId,
-      action: AuditAction.TABLE_UPDATED,
-      resourceType: AuditResourceType.TABLE,
-      resourceId: tableId,
-      resourceName: table.name,
-      description: `Updated column "${validated.columnName}" in table "${table.name}"`,
-      metadata: { columnName: validated.columnName, updates },
-      request,
-    })
-
     return NextResponse.json({
       success: true,
       data: {
-        columns: updatedTable.schema.columns.map(normalizeColumn),
+        columns: outcome.table.schema.columns.map(normalizeColumn),
       },
     })
   } catch (error) {
-    const lockError = tableLockErrorResponse(error)
-    if (lockError) return lockError
     const validationResponse = v1ValidationErrorResponseFromError(error)
     if (validationResponse) return validationResponse
 
-    if (error instanceof Error) {
-      const msg = error.message
-      if (msg.includes('not found') || msg.includes('Table not found')) {
-        return NextResponse.json({ error: msg }, { status: 404 })
-      }
-      if (
-        msg.includes('already exists') ||
-        msg.includes('Cannot delete the last column') ||
-        msg.includes('Cannot set column') ||
-        msg.includes('Invalid column') ||
-        msg.includes('exceeds maximum') ||
-        msg.includes('incompatible') ||
-        msg.includes('duplicate') ||
-        msg.includes('option')
-      ) {
-        return NextResponse.json({ error: msg }, { status: 400 })
-      }
-    }
-
     logger.error(`[${requestId}] Error updating column in table:`, error)
     return NextResponse.json({ error: 'Failed to update column' }, { status: 500 })
   }