fix(table): reject empty filter groups and bind cursors to their sort

Bugbot round 2 on PR #6067, both verified:

Empty groups (High). `{all: []}` fails the strict predicate branch (.min(1))
but slips the dual union via the legacy branch — an empty ARRAY inside a
non-empty OBJECT — then downgraded to `{$and: []}`, which compiles to no WHERE
clause: a run/cancel/delete scope silently widened to every row.
validatePredicateShape now mirrors the contract's .min(1), which closes it at
every dual-grammar boundary at once (toLegacyFilter, resolveBulkFilter, the
GET native path).

Cursor↔sort binding (Medium). CURSOR_SORT_CONFLICT only fired for keyset
cursors; offset cursors — the shape sorted views actually emit — carried no
record of their ordering, so one minted under sort A replayed under sort B (or
none) silently paged the wrong sequence. Offset cursors are now stamped with a
canonical fingerprint of their sort at mint (queryRows), and a shared
assertCursorSortBinding enforces the match at all three consumers (both query
routes and the copilot executor), replacing the three hand-rolled keyset-only
checks. Keyset/compound cursors stay default-order-only by construction. The
OpenAPI cursor wording now states the binding rather than overclaiming.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011M563cbFy2S74GvSDf2C3R

Author: TheodoreSpeaks

apps/docs/openapi-v2-tables.json

@@ -60,7 +60,7 @@
       "post": {
         "operationId": "v2QueryTableRows",
         "summary": "Query Rows",
-        "description": "Query rows with a typed predicate filter, an ordered sort spec, and opaque cursor pagination. Row `data` is keyed by column NAME; `select` cells return option names, and filter operands on select columns accept option names (resolved case-insensitively).\n\n**Pagination contract:** page by passing the previous response's `nextCursor` back as `cursor`, and stop only when it is `null` — a page may return fewer than `limit` rows and still have more behind it, so page fullness is never a termination signal. A cursor encodes a position in the default row order and cannot be combined with `sort` (400 `CURSOR_SORT_CONFLICT`). `totalCount` is computed on the first page only (requests with a `cursor` return `totalCount: null`).",
+        "description": "Query rows with a typed predicate filter, an ordered sort spec, and opaque cursor pagination. Row `data` is keyed by column NAME; `select` cells return option names, and filter operands on select columns accept option names (resolved case-insensitively).\n\n**Pagination contract:** page by passing the previous response's `nextCursor` back as `cursor`, and stop only when it is `null` — a page may return fewer than `limit` rows and still have more behind it, so page fullness is never a termination signal. A cursor is bound to the exact query shape it was minted under: keyset cursors to the default row order, offset cursors (sorted views) to that sort. Replaying one under a different `sort` returns 400 `CURSOR_SORT_CONFLICT`. `totalCount` is computed on the first page only (requests with a `cursor` return `totalCount: null`).",
         "tags": ["Tables v2"],
         "parameters": [
           {

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

@@ -10,7 +10,7 @@ import type { Sort, TableSchema } from '@/lib/table'
 import { buildIdByName, sortSpecNamesToIds } from '@/lib/table/column-keys'
 import { TableQueryValidationError } from '@/lib/table/errors'
 import { validatePredicate, validateSortSpec } from '@/lib/table/query-builder/validate'
-import { decodeCursor } from '@/lib/table/rows/cursor'
+import { assertCursorSortBinding, decodeCursor } from '@/lib/table/rows/cursor'
 import { queryRows } from '@/lib/table/rows/service'
 import { predicateToStorage } from '@/lib/table/select-values'
 import { rowWireTranslators } from '@/app/api/table/row-wire'
@@ -63,19 +63,6 @@ export const POST = withRouteHandler(async (request: NextRequest, context: RowQu
     const wire = rowWireTranslators(authResult.authType, schema)
     const cursor = body.cursor ? decodeCursor(body.cursor) : undefined
 
-    // A keyset cursor encodes a position on the DEFAULT `(order_key, id)`
-    // order; combining it with a custom order would silently return page 1
-    // of the sorted view relabeled as a next page.
-    if (cursor?.after && body.sort?.length) {
-      return NextResponse.json(
-        {
-          error: 'Cursor is not valid for a sorted query. Restart paging without the cursor.',
-          code: 'CURSOR_SORT_CONFLICT',
-        },
-        { status: 400 }
-      )
-    }
-
     // Predicate/sort fields are column-NAME-keyed by construction (the caller
     // authors names), so validate against the schema then translate names →
     // storage ids unconditionally — unlike row data, this is not authType-dependent.
@@ -94,6 +81,10 @@ export const POST = withRouteHandler(async (request: NextRequest, context: RowQu
       ? Object.fromEntries(sortSpec.map((s) => [s.field, s.direction]))
       : undefined
 
+    // Cursor↔sort binding: keyset cursors are default-order only; an offset
+    // cursor must be replayed under the exact sort it was minted with.
+    if (cursor) assertCursorSortBinding(cursor, sort)
+
     const result = await queryRows(
       table,
       {

apps/sim/app/api/v2/tables/[tableId]/query/route.ts

@@ -10,7 +10,7 @@ import { buildIdByName, sortSpecNamesToIds } from '@/lib/table'
 import { namedRowMapper } from '@/lib/table/cell-format'
 import { TableQueryValidationError } from '@/lib/table/errors'
 import { validatePredicate, validateSortSpec } from '@/lib/table/query-builder/validate'
-import { decodeCursor } from '@/lib/table/rows/cursor'
+import { assertCursorSortBinding, decodeCursor } from '@/lib/table/rows/cursor'
 import { queryRows } from '@/lib/table/rows/service'
 import { predicateToStorage } from '@/lib/table/select-values'
 import { accessError, checkAccess, tablesV2GateError } from '@/app/api/table/utils'
@@ -72,18 +72,6 @@ export const POST = withRouteHandler(async (request: NextRequest, context: Query
     const schema = table.schema as TableSchema
     const cursor = cursorToken ? decodeCursor(cursorToken) : undefined
 
-    // A keyset cursor is bound to the DEFAULT `(order_key, id)` order; combining
-    // it with a custom sort would relabel page 1 of the sorted view as a next page.
-    if (cursor?.after && sort?.length) {
-      return NextResponse.json(
-        {
-          error: 'Cursor is not valid for a sorted query. Restart paging without the cursor.',
-          code: 'CURSOR_SORT_CONFLICT',
-        },
-        { status: 400, headers: PRIVATE_NO_STORE }
-      )
-    }
-
     const idByName = buildIdByName(schema)
     // Fuses the id→name key remap with select-cell value formatting, so a select
     // cell surfaces its option NAME rather than the stored option id.
@@ -102,6 +90,11 @@ export const POST = withRouteHandler(async (request: NextRequest, context: Query
       ? Object.fromEntries(sortSpec.map((s) => [s.field, s.direction]))
       : undefined
 
+    // A cursor is only valid for the query shape it was minted under: keyset
+    // cursors bind to the default order, offset cursors to their sort. Runs on
+    // the STORAGE-keyed sort so the fingerprint matches what queryRows stamped.
+    if (cursor) assertCursorSortBinding(cursor, sortObj)
+
     // Public default is a bounded page (unlike the internal surface's unbounded
     // omit). `limit=0` is the explicit unbounded opt-in.
     const effectiveLimit =

apps/sim/lib/copilot/tools/server/table/user-table.ts

@@ -1,6 +1,6 @@
 import { AuditAction, AuditResourceType, recordAudit } from '@sim/audit'
 import { createLogger } from '@sim/logger'
-import { toError } from '@sim/utils/errors'
+import { getErrorMessage, toError } from '@sim/utils/errors'
 import { generateId, generateShortId } from '@sim/utils/id'
 import { UserTable } from '@/lib/copilot/generated/tool-catalog-v1'
 import {
@@ -49,7 +49,7 @@ import { markTableJobRunning, releaseJobClaim } from '@/lib/table/jobs/service'
 import { assertRowDelete, assertRowUpdate, patchColumnIds } from '@/lib/table/mutation-locks'
 import { predicateToFilter } from '@/lib/table/query-builder/converters'
 import { validatePredicate, validateSortSpec } from '@/lib/table/query-builder/validate'
-import { decodeCursor } from '@/lib/table/rows/cursor'
+import { assertCursorSortBinding, decodeCursor } from '@/lib/table/rows/cursor'
 import {
   batchInsertRows,
   batchUpdateRows,
@@ -700,11 +700,13 @@ export const userTableServerTool: BaseServerTool<UserTableArgs, UserTableResult>
           // physically can't page). A keyset cursor is bound to the default order,
           // so it can't be combined with a fresh sort.
           const cursor = args.cursor ? decodeCursor(args.cursor) : undefined
-          if (cursor?.after && sort) {
-            return {
-              success: false,
-              message:
-                'Cursor is not valid for a sorted query. Restart paging without the cursor (omit it on the first sorted page).',
+          if (cursor) {
+            try {
+              // Keyset cursors bind to the default order; offset cursors to the
+              // exact sort they were minted under.
+              assertCursorSortBinding(cursor, sort)
+            } catch (bindError) {
+              return { success: false, message: getErrorMessage(bindError, 'Invalid cursor') }
             }
           }
 

apps/sim/lib/table/__tests__/service-filter-threading.test.ts

@@ -403,7 +403,12 @@ describe('queryRows byte budget', () => {
 
     expect(dbChainMockFns.offset).toHaveBeenCalledWith(40)
     expect(result.rows).toHaveLength(1)
-    expect(decodeCursor(result.nextCursor as string)).toEqual({ offset: 41 })
+    // The offset cursor is stamped with the sort it was minted under, so a
+    // replay against a different ordering is rejected instead of paging wrong.
+    expect(decodeCursor(result.nextCursor as string)).toEqual({
+      offset: 41,
+      sortKey: JSON.stringify([['name', 'asc']]),
+    })
   })
 
   it('emits a compound cursor when rows past the inbound anchor are unkeyed', async () => {

apps/sim/lib/table/query-builder/__tests__/converters.test.ts

@@ -497,3 +497,7 @@ describe('isTablePredicate vs columns literally named all/any', () => {
     expect(isTablePredicate({ any: [{ field: 'a', op: 'eq', value: 1 }] })).toBe(true)
   })
 })
+
+it('toLegacyFilter rejects an empty group instead of downgrading it to no WHERE', () => {
+  expect(() => toLegacyFilter({ all: [] })).toThrow(/at least one condition/)
+})

apps/sim/lib/table/query-builder/__tests__/validate.test.ts

@@ -3,7 +3,11 @@
  */
 import { describe, expect, it } from 'vitest'
 import { TableQueryValidationError } from '@/lib/table/errors'
-import { validatePredicate, validateSortSpec } from '@/lib/table/query-builder/validate'
+import {
+  validatePredicate,
+  validatePredicateShape,
+  validateSortSpec,
+} from '@/lib/table/query-builder/validate'
 import type { ColumnDefinition } from '@/lib/table/types'
 
 const COLS: ColumnDefinition[] = [
@@ -175,3 +179,23 @@ describe('validatePredicate — legacy $-grammar diagnostics', () => {
     )
   })
 })
+
+/**
+ * Bugbot round 2: `{all: []}` passes the dual union via the non-empty-OBJECT
+ * legacy branch, then compiled to no WHERE clause — silently widening a run /
+ * cancel / delete scope to every row. The shape validator now mirrors the Zod
+ * contract's .min(1).
+ */
+describe('empty groups are rejected at every layer', () => {
+  it('validatePredicateShape rejects an empty group', () => {
+    expect(() => validatePredicateShape({ all: [] })).toThrow(/at least one condition/)
+    expect(() => validatePredicateShape({ any: [] })).toThrow(/at least one condition/)
+    expect(() => validatePredicateShape({ all: [{ any: [] }] } as never)).toThrow(
+      /at least one condition/
+    )
+  })
+
+  it('validatePredicate rejects it too', () => {
+    expect(() => validatePredicate({ all: [] }, COLS)).toThrow(/at least one condition/)
+  })
+})

apps/sim/lib/table/query-builder/validate.ts

@@ -145,6 +145,15 @@ function validateNode(node: PredicateNode, typeByName: Map<string, ColumnType> |
         'INVALID_FILTER'
       )
     }
+    // Mirrors the Zod contract's .min(1). An empty group slips the strict union
+    // (falling to the non-empty-OBJECT legacy branch) and compiles to no WHERE
+    // clause — which on the run/cancel/delete scopes silently means EVERY row.
+    if (members.length === 0) {
+      throw new TableQueryValidationError(
+        'A filter group must contain at least one condition.',
+        'INVALID_FILTER'
+      )
+    }
     for (const child of members) validateNode(child, typeByName)
     return
   }

apps/sim/lib/table/rows/cursor.test.ts

@@ -0,0 +1,78 @@
+/**
+ * @vitest-environment node
+ *
+ * Opaque cursor encode/decode and the cursor↔sort binding. A cursor encodes a
+ * position in one specific ordering; replaying it under any other ordering
+ * silently pages the wrong sequence, so binding violations must throw
+ * CURSOR_SORT_CONFLICT rather than return wrong rows.
+ */
+import { describe, expect, it } from 'vitest'
+import { TableQueryValidationError } from '@/lib/table/errors'
+import {
+  assertCursorSortBinding,
+  canonicalSortKey,
+  decodeCursor,
+  encodeCursor,
+} from '@/lib/table/rows/cursor'
+
+const ROW = { id: 'row_1', orderKey: 'a1' }
+
+describe('cursor↔sort binding (bugbot round 2)', () => {
+  it('stamps an offset cursor with the sort it was minted under', () => {
+    const token = encodeCursor({
+      lastRow: { id: 'row_1', orderKey: null },
+      keysetValid: false,
+      nextOffset: 100,
+      sort: { col_a: 'desc' },
+    })
+    const decoded = decodeCursor(token)
+    expect(decoded.offset).toBe(100)
+    expect(decoded.sortKey).toBe(canonicalSortKey({ col_a: 'desc' }))
+  })
+
+  it('accepts replay under the identical sort', () => {
+    const decoded = { offset: 100, sortKey: canonicalSortKey({ col_a: 'desc' }) }
+    expect(() => assertCursorSortBinding(decoded, { col_a: 'desc' })).not.toThrow()
+  })
+
+  it('rejects replay under a DIFFERENT sort', () => {
+    const decoded = { offset: 100, sortKey: canonicalSortKey({ col_a: 'desc' }) }
+    for (const sort of [{ col_a: 'asc' as const }, { col_b: 'desc' as const }, undefined]) {
+      expect(() => assertCursorSortBinding(decoded, sort)).toThrow(TableQueryValidationError)
+      try {
+        assertCursorSortBinding(decoded, sort)
+      } catch (e) {
+        expect((e as TableQueryValidationError).code).toBe('CURSOR_SORT_CONFLICT')
+      }
+    }
+  })
+
+  it('rejects adding a sort to an unsorted offset cursor', () => {
+    const token = encodeCursor({
+      lastRow: { id: 'row_1', orderKey: null },
+      keysetValid: false,
+      nextOffset: 50,
+    })
+    const decoded = decodeCursor(token)
+    expect(decoded.sortKey).toBeUndefined()
+    expect(() => assertCursorSortBinding(decoded, { col_a: 'asc' })).toThrow(
+      /different sort|sorted query/
+    )
+    expect(() => assertCursorSortBinding(decoded, undefined)).not.toThrow()
+  })
+
+  it('keyset cursors stay default-order only and never carry a sort stamp', () => {
+    const token = encodeCursor({ lastRow: ROW, keysetValid: true, nextOffset: 10 })
+    const decoded = decodeCursor(token)
+    expect(decoded.after).toEqual({ orderKey: 'a1', id: 'row_1' })
+    expect(decoded.sortKey).toBeUndefined()
+    expect(() => assertCursorSortBinding(decoded, { col_a: 'asc' })).toThrow(/sorted query/)
+    expect(() => assertCursorSortBinding(decoded, undefined)).not.toThrow()
+  })
+
+  it('sort key order is significant (priority is part of the identity)', () => {
+    expect(canonicalSortKey({ a: 'asc', b: 'desc' })).not.toBe(
+      canonicalSortKey({ b: 'desc', a: 'asc' })
+    )
+  })
+})

apps/sim/lib/table/rows/cursor.ts

@@ -16,7 +16,7 @@
  */
 
 import { TableQueryValidationError } from '@/lib/table/errors'
-import type { TableRow, TableRowsCursor } from '@/lib/table/types'
+import type { Sort, TableRow, TableRowsCursor } from '@/lib/table/types'
 
 /**
  * Cursor payload version. Every encoded token carries `v`; decode rejects any
@@ -26,7 +26,50 @@ import type { TableRow, TableRowsCursor } from '@/lib/table/types'
 const CURSOR_VERSION = 1
 
 type CursorBody = { k: string; i: string } | { o: number } | { k: string; i: string; o: number }
-type CursorPayload = CursorBody & { v: number }
+type SortBinding = { s?: string }
+type CursorPayload = CursorBody & SortBinding & { v: number }
+
+/**
+ * Canonical fingerprint of a sort for cursor binding. Entry order is the sort
+ * priority (built from the ordered spec upstream), so stringifying entries is
+ * deterministic for equal sorts and distinct for different ones.
+ */
+export function canonicalSortKey(sort: Sort | null | undefined): string | undefined {
+  if (!sort) return undefined
+  const entries = Object.entries(sort)
+  return entries.length > 0 ? JSON.stringify(entries) : undefined
+}
+
+/**
+ * A cursor is only valid for the exact query shape it was minted under:
+ * keyset/compound cursors encode a position in the DEFAULT `(order_key, id)`
+ * order, and an offset cursor from a sorted view encodes a position in THAT
+ * sort. Replaying either against a different ordering silently pages the wrong
+ * sequence — rows skipped or duplicated with no error. Throws
+ * `CURSOR_SORT_CONFLICT` so callers restart paging without the cursor.
+ */
+export function assertCursorSortBinding(
+  decoded: { after?: TableRowsCursor; offset?: number; sortKey?: string },
+  sort: Sort | null | undefined
+): void {
+  const requested = canonicalSortKey(sort)
+  if (decoded.after && requested !== undefined) {
+    throw new TableQueryValidationError(
+      'Cursor is not valid for a sorted query. Restart paging without the cursor.',
+      'CURSOR_SORT_CONFLICT'
+    )
+  }
+  if (
+    decoded.after === undefined &&
+    decoded.offset !== undefined &&
+    decoded.sortKey !== requested
+  ) {
+    throw new TableQueryValidationError(
+      'Cursor was created under a different sort. Restart paging without the cursor.',
+      'CURSOR_SORT_CONFLICT'
+    )
+  }
+}
 
 function invalidCursor(): never {
   throw new TableQueryValidationError('Invalid cursor', 'INVALID_CURSOR')
@@ -57,6 +100,8 @@ export function encodeCursor(args: {
   keysetValid: boolean
   nextOffset: number
   seekBase?: { anchor: TableRowsCursor; offsetFromAnchor: number }
+  /** The sort the page was produced under — stamps offset cursors so they can't be replayed against a different ordering. */
+  sort?: Sort | null
 }): string {
   let body: CursorBody
   if (args.keysetValid && args.lastRow.orderKey) {
@@ -74,12 +119,24 @@ export function encodeCursor(args: {
   } else {
     body = { o: args.nextOffset }
   }
-  const payload: CursorPayload = { ...body, v: CURSOR_VERSION }
+  const sortKey = canonicalSortKey(args.sort)
+  const payload: CursorPayload = {
+    ...body,
+    // Only the pure-offset shape can exist under a custom sort; keyset and
+    // compound shapes are default-order by construction and carry no binding.
+    ...('k' in body || sortKey === undefined ? {} : { s: sortKey }),
+    v: CURSOR_VERSION,
+  }
   return toBase64Url(JSON.stringify(payload))
 }
 
 /** Decodes an opaque cursor into the `queryRows` paging inputs it stands for. */
-export function decodeCursor(token: string): { after?: TableRowsCursor; offset?: number } {
+export function decodeCursor(token: string): {
+  after?: TableRowsCursor
+  offset?: number
+  /** Sort fingerprint an offset cursor was minted under; absent = default order. */
+  sortKey?: string
+} {
   let payload: unknown
   try {
     payload = JSON.parse(fromBase64Url(token))
@@ -105,7 +162,10 @@ export function decodeCursor(token: string): { after?: TableRowsCursor; offset?:
     return { after: { orderKey: record.k as string, id: record.i as string } }
   }
   if (hasOffset) {
-    return { offset: record.o as number }
+    return {
+      offset: record.o as number,
+      ...(typeof record.s === 'string' ? { sortKey: record.s } : {}),
+    }
   }
   invalidCursor()
 }