Function resolveInsertByNeighbor

apps/sim/lib/table/rows/ordering.ts:232–296

(
  trx: DbTransaction,
  tableId: string,
  afterRowId?: string,
  beforeRowId?: string
)

 * row-order lock.
 */
export async function resolveInsertByNeighbor(
  trx: DbTransaction,
  tableId: string,
  afterRowId?: string,
  beforeRowId?: string
): Promise<{ orderKey: string; position: number }> {
  const anchorId = afterRowId ?? beforeRowId!
  const [anchor] = await trx
    .select({ orderKey: userTableRows.orderKey, position: userTableRows.position })
    .from(userTableRows)
    .where(and(eq(userTableRows.tableId, tableId), eq(userTableRows.id, anchorId)))
    .limit(1)
  // The client targets a specific neighbor; a missing one (concurrent delete /
  // stale view) is an error, not a silent insert at the front.
  if (!anchor) throw new Error(`Row not found: ${anchorId}`)
  const anchorKey = anchor.orderKey ?? null
  // A null key on the anchor means the table isn't backfilled. With the flag on
  // (key is authoritative) the adjacent-key lookup below can't work — fail
  // loudly rather than mint a wrong key. Flag off keeps `position` authoritative,
  // so a best-effort key here is fine (the backfill re-keys before the flip).
  const fractionalOrdering = await isFeatureEnabled('tables-fractional-ordering')
  if (anchorKey === null && fractionalOrdering) {
    throw new Error(`Row ${anchorId} has no order_key yet (table not backfilled)`)
  }

  if (afterRowId) {
    // hi = the smallest key strictly GREATER than the anchor key. Comparing keys
    // (not the `(order_key, id)` row tuple) skips past any sibling that shares the
    // anchor's key, so `keyBetween` always gets strictly-ordered bounds and can't
    // throw on a stray duplicate. Identical to the row tuple when keys are distinct.
    // A null anchorKey (flag off, un-backfilled) has no key to compare — leave the
    // upper bound open, matching the prior best-effort behavior.
    let nextKey: string | null = null
    if (anchorKey !== null) {
      const [next] = await trx
        .select({ orderKey: userTableRows.orderKey })
        .from(userTableRows)
        .where(and(eq(userTableRows.tableId, tableId), gt(userTableRows.orderKey, anchorKey)))
        .orderBy(asc(userTableRows.orderKey))
        .limit(1)
      nextKey = next?.orderKey ?? null
    }
    return {
      orderKey: keyBetween(anchorKey, nextKey),
      position: anchor.position + 1,
    }
  }

  // beforeRowId: lo = the largest key strictly LESS than the anchor key (distinct,
  // same rationale as the afterRowId branch above).
  let prevKey: string | null = null
  if (anchorKey !== null) {
    const [prev] = await trx
      .select({ orderKey: userTableRows.orderKey })
      .from(userTableRows)
      .where(and(eq(userTableRows.tableId, tableId), lt(userTableRows.orderKey, anchorKey)))
      .orderBy(desc(userTableRows.orderKey))
      .limit(1)