feat(tables): insert-by-neighbor-id + orderKey on wire + client order-by-key

Inserts express intent as afterRowId/beforeRowId (O(1) key mint via the
(table_id,order_key,id) index); orderKey is returned on every row; client
reconcile/undo place by orderKey (no neighbor bump) with position fallback.
Flag off = unchanged. 205 table tests pass.

Author: TheodoreSpeaks

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

@@ -71,6 +71,7 @@ async function handleBatchInsert(
         workspaceId: validated.workspaceId,
         userId,
         positions: validated.positions,
+        orderKeys: validated.orderKeys,
       },
       table,
       requestId
@@ -162,6 +163,8 @@ export const POST = withRouteHandler(
           workspaceId: validated.workspaceId,
           userId: authResult.userId,
           position: validated.position,
+          afterRowId: validated.afterRowId,
+          beforeRowId: validated.beforeRowId,
         },
         table,
         requestId

apps/sim/app/workspace/[workspaceId]/tables/[tableId]/components/table-grid/table-grid.tsx

@@ -837,9 +837,12 @@ export function TableGrid({
 
   function handleInsertRow(offset: 0 | 1) {
     if (!contextMenu.row) return
+    const anchorId = contextMenu.row.id
+    // Fractional ordering: express intent by neighbor id, not integer position.
+    const intent = offset === 0 ? { beforeRowId: anchorId } : { afterRowId: anchorId }
     const position = contextMenu.row.position + offset
     createRef.current(
-      { data: {}, position },
+      { data: {}, ...intent },
       {
         onSuccess: (response: Record<string, unknown>) => {
           const newRowId = extractCreatedRowId(response)
@@ -904,7 +907,7 @@ export function TableGrid({
     const sourceArrayIndex = rowsRef.current.findIndex((r) => r.id === contextRow.id)
     closeContextMenu()
     createRef.current(
-      { data: rowData, position },
+      { data: rowData, afterRowId: contextRow.id },
       {
         onSuccess: (response: Record<string, unknown>) => {
           const newRowId = extractCreatedRowId(response)

apps/sim/app/workspace/[workspaceId]/tables/[tableId]/components/table-grid/utils.ts

@@ -302,7 +302,12 @@ export function computeNormalizedSelection(
 export function collectRowSnapshots(rows: Iterable<TableRowType>): DeletedRowSnapshot[] {
   const snapshots: DeletedRowSnapshot[] = []
   for (const row of rows) {
-    snapshots.push({ rowId: row.id, data: { ...row.data }, position: row.position })
+    snapshots.push({
+      rowId: row.id,
+      data: { ...row.data },
+      position: row.position,
+      orderKey: row.orderKey,
+    })
   }
   return snapshots
 }

apps/sim/hooks/queries/tables.ts

@@ -512,7 +512,13 @@ export function useCreateTableRow({ workspaceId, tableId }: RowMutationContext)
     ) => {
       return requestJson(createTableRowContract, {
         params: { tableId },
-        body: { workspaceId, data: variables.data as RowData, position: variables.position },
+        body: {
+          workspaceId,
+          data: variables.data as RowData,
+          position: variables.position,
+          afterRowId: variables.afterRowId,
+          beforeRowId: variables.beforeRowId,
+        },
       })
     },
     onSuccess: (response) => {
@@ -586,41 +592,49 @@ function reconcileCreatedRow(
   tableId: string,
   row: TableRow
 ) {
+  // Fractional ordering: the new row carries an `orderKey` and no other row's
+  // key changes, so we splice it in by key with no neighbor bump. Falls back to
+  // the legacy `position` path (bump + sort) for rows without a key.
+  const byKey = row.orderKey != null
+  const sortRows = (rows: TableRow[]) =>
+    byKey
+      ? [...rows].sort((a, b) => (a.orderKey ?? '').localeCompare(b.orderKey ?? ''))
+      : [...rows].sort((a, b) => a.position - b.position)
+  const fitsAfter = (last: TableRow | undefined) =>
+    last === undefined ||
+    (byKey ? (last.orderKey ?? '') >= row.orderKey! : last.position >= row.position)
+
   queryClient.setQueriesData<InfiniteData<TableRowsResponse, number>>(
     { queryKey: tableKeys.rowsRoot(tableId), exact: false },
     (old) => {
       if (!old) return old
       if (old.pages.some((p) => p.rows.some((r) => r.id === row.id))) return old
 
-      const pages = old.pages.map((page) =>
-        page.rows.some((r) => r.position >= row.position)
-          ? {
-              ...page,
-              rows: page.rows.map((r) =>
-                r.position >= row.position ? { ...r, position: r.position + 1 } : r
-              ),
-            }
-          : page
-      )
+      const pages = byKey
+        ? old.pages
+        : old.pages.map((page) =>
+            page.rows.some((r) => r.position >= row.position)
+              ? {
+                  ...page,
+                  rows: page.rows.map((r) =>
+                    r.position >= row.position ? { ...r, position: r.position + 1 } : r
+                  ),
+                }
+              : page
+          )
 
       let inserted = false
       const nextPages = pages.map((page) => {
         if (inserted) return page
-        const last = page.rows[page.rows.length - 1]
-        const fits = last === undefined || last.position >= row.position
-        if (!fits) return page
+        if (!fitsAfter(page.rows[page.rows.length - 1])) return page
         inserted = true
-        const merged = [...page.rows, row].sort((a, b) => a.position - b.position)
-        return { ...page, rows: merged }
+        return { ...page, rows: sortRows([...page.rows, row]) }
       })
 
       if (!inserted && nextPages.length > 0) {
         const lastIdx = nextPages.length - 1
         const lastPage = nextPages[lastIdx]
-        nextPages[lastIdx] = {
-          ...lastPage,
-          rows: [...lastPage.rows, row].sort((a, b) => a.position - b.position),
-        }
+        nextPages[lastIdx] = { ...lastPage, rows: sortRows([...lastPage.rows, row]) }
       }
 
       const firstPage = nextPages[0]
@@ -655,6 +669,7 @@ export function useBatchCreateTableRows({ workspaceId, tableId }: RowMutationCon
           workspaceId,
           rows: variables.rows as RowData[],
           positions: variables.positions,
+          orderKeys: variables.orderKeys,
         },
       })
     },

apps/sim/hooks/use-table-undo.ts

@@ -165,6 +165,9 @@ export function useTableUndo({
                 {
                   rows: action.rows.map((r) => r.data),
                   positions: action.rows.map((r) => r.position),
+                  orderKeys: action.rows.every((r) => r.orderKey)
+                    ? action.rows.map((r) => r.orderKey as string)
+                    : undefined,
                 },
                 {
                   onSuccess: (response) => {
@@ -187,6 +190,9 @@ export function useTableUndo({
                 {
                   rows: action.rows.map((row) => row.data),
                   positions: action.rows.map((row) => row.position),
+                  orderKeys: action.rows.every((row) => row.orderKey)
+                    ? action.rows.map((row) => row.orderKey as string)
+                    : undefined,
                 },
                 {
                   onSuccess: (response) => {

apps/sim/lib/api/contracts/tables.ts

@@ -151,6 +151,10 @@ export const insertTableRowBodySchema = z.object({
   workspaceId: z.string().min(1, 'Workspace ID is required'),
   data: rowDataSchema,
   position: z.number().int().min(0).optional(),
+  /** Fractional ordering: insert directly after this row id. Takes precedence over `position`. */
+  afterRowId: z.string().min(1).optional(),
+  /** Fractional ordering: insert directly before this row id. Takes precedence over `position`. */
+  beforeRowId: z.string().min(1).optional(),
 })
 
 /**
@@ -175,13 +179,18 @@ export const batchInsertTableRowsBodySchema = z
         `Cannot insert more than ${TABLE_LIMITS.MAX_BATCH_INSERT_SIZE} rows per batch`
       ),
     positions: z.array(z.number().int().min(0)).max(TABLE_LIMITS.MAX_BATCH_INSERT_SIZE).optional(),
+    /** Fractional ordering: exact per-row order keys (undo restore). Takes precedence over `positions`. */
+    orderKeys: z.array(z.string().min(1)).max(TABLE_LIMITS.MAX_BATCH_INSERT_SIZE).optional(),
   })
   .refine((data) => !data.positions || data.positions.length === data.rows.length, {
     message: 'positions array length must match rows array length',
   })
   .refine((data) => !data.positions || new Set(data.positions).size === data.positions.length, {
     message: 'positions must not contain duplicates',
   })
+  .refine((data) => !data.orderKeys || data.orderKeys.length === data.rows.length, {
+    message: 'orderKeys array length must match rows array length',
+  })
 
 /**
  * POST `/api/table/[tableId]/rows` body — accepts either a batch payload