improvement(mothership): table speed parity — keyset reads, limit bounds, background import/delete jobs

[TheodoreSpeaks]

Context

Audit of Mothership's table operations against the tables feature's recent perf work (tenant-scoped queries, keyset pagination, background table_jobs). The core user_table row CRUD was already on the fast paths; these were the gaps.

Changes

function_execute table mounts were silently truncated to 100 rows. inputTables mounted via queryRows(table, {}, …) — default limit 100, plus a COUNT(*) and an executions load the CSV never used. Sandbox code computed over truncated data. Mounts now drain selectExportRowPage (keyset, tenant-bounded, delete-mask-aware) in 5k pages, remap stored column-id keys back to display names (previously headers were names but cells were id-keyed, producing empty columns on id-keyed tables), run per-table mounts in parallel, and count toward the 50MB mount budget.

query_rows gets contract-parity limits and keyset paging. limit was passed through unclamped (the model could pull an entire table into one tool result) and only offset paging existed. Now: limit ≤ MAX_QUERY_LIMIT (1000) rejected with the contract's message, withExecutions: false, after: {orderKey, id} accepted (rejected with sort, like the HTTP contract), and nextCursor returned when a default-order page fills.

Imports and unbounded filter-deletes get full async-job parity with the UI routes.

• import_file / create_from_file: CSV/TSV ≥ CSV_ASYNC_IMPORT_THRESHOLD_BYTES (8MB) dispatch tableImportTask (claim slot → dispatch → release-on-failure, mirroring the import-async routes; create mode uses the placeholder-table pattern from the workspace-level route). Smaller/other-format files stay inline but now claim and release the table's one-write-job slot, so a Mothership import can no longer interleave with a running background import/delete.
• delete_rows_by_filter: explicit limit ≤ 1000 stays inline; with no limit, the match count is measured first (tenant-bounded count) and >1000 matches dispatch tableDeleteTask with the standard {filter, cutoff, doomedCount} payload — doomed rows hidden immediately via the existing pendingDeleteMask.
• New get_job operation returns the table's derived job state ({id, type, status, error, rowsProcessed}) for polling.

TableImportPayload.deleteSourceFile (default true). The import worker deletes its source object when terminal — correct for the UI's single-use direct uploads, destructive for the persistent workspace files Mothership imports from. Mothership passes false.

Generated artifacts (tool-catalog-v1.ts, tool-schemas-v1.ts) regenerated from the companion contract PR simstudioai/copilot#289 (get_job, after param, limit maximums, background-behavior docs). Sim-side behavior is live regardless; the model sees the new schema once the copilot PR deploys.

Tests

• user-table.test.ts: limit clamps, keyset after/nextCursor (+ after+sort rejection), inline slot claim/release, slot-held rejection, background import/delete dispatch payloads, get_job (33 passing)
• function-execute.test.ts (new): full keyset drain across pages (5002-row table), id→name header mapping, cross-workspace rejection
• import-runner.test.ts (new): source-file cleanup default vs deleteSourceFile: false
• bunx vitest run lib/copilot lib/table (78 files, 721 tests), bun run lint:check, bun run check:api-validation, tsc --noEmit all green

Related: #5011 (cross-tenant outputTable fix, split out), simstudioai/copilot#289 (contract).

🤖 Generated with Claude Code

[TheodoreSpeaks]

@greptile review

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Jun 12, 2026 11:28pm

[cursor]

PR Summary

High Risk
Introduces background delete/export paths, job-slot concurrency, and schema/API field renames on core table data; mistakes could cause wrong-row deletes, ghost jobs, or client/server drift.

Overview
Replaces per-table import fields and routes with a shared table_jobs model (jobStatus, jobId, jobType, …) and generic job cancel at /job/cancel. Import, filter-based delete, and large exports are kicked off through new async APIs (optional Trigger.dev dispatch with releaseJobClaim on failed triggers), with the stale-execution cron failing stuck jobs, pruning old terminal rows, and deleting orphaned export files.

Bulk operations now accept filter and excludeRowIds on run, cancel-runs, and delete-async (with upfront tableFilterError validation). Row listing adds after keyset paging; table APIs centralize client-facing write errors via rootErrorMessage / rowWriteErrorResponse.

The workspace grid treats select-all as filter-scoped totals (including unloaded rows): exclusions survive toggles, Cmd+A toggles whole-table selection, delete-all goes through a background job instead of loading every id, and run/stop/copy counts use the filter-scoped total. SSE handles job events (including auto-download for exports). Smaller UI passes swap sidebars/filters to Chip components and shared sidebar field helpers.

Dev CI db:push now surfaces a clear workflow error when Drizzle hits interactive rename/drop prompts without a TTY.

^{Reviewed by Cursor Bugbot for commit 7310c06. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 7310c06. Configure here.}

[cursor]

HTTP rows missing next cursor

Medium Severity

The GET rows handler now accepts an after keyset cursor and passes it to queryRows, but the JSON response never includes a nextCursor when a full page is returned. REST clients cannot advance past the first default-order page without guessing offsets or reusing Mothership-only tooling.

 

^{Reviewed by Cursor Bugbot for commit 7310c06. Configure here.}

[greptile-apps]

Greptile Summary

This PR brings Mothership's table operations to parity with the UI's recent performance work: full-table keyset CSV mounts replacing the silently-truncated 100-row queryRows path, query_rows limit enforcement and after/nextCursor cursor support, and background import/delete job dispatch for large CSV imports and unbounded filter deletes.

• Schema migration (0233) introduces a table_jobs table with a partial unique index enforcing one active write-job per table, migrates existing import state, replaces the cross-tenant GIN index with a tenant-scoped one, and adds a keyset index on (table_id, id).
• function-execute now drains the full table via selectExportRowPage in 5k-row pages, remaps column-id keys to display names, and runs per-table mounts in parallel against the 50MB budget — however the entire CSV for every table is built before the budget is checked, so the budget cap is not enforced pre-load.
• user-table (Mothership tool) adds get_job for polling, enforces MAX_QUERY_LIMIT (1000) on query_rows, dispatches large CSV imports and unbounded filter deletes to background workers, and passes deleteSourceFile: false to preserve persistent workspace files.

Confidence Score: 3/5

The job infrastructure, migration, and background worker paths are solid, but the sandbox table mount builds every table CSV fully in memory before the budget check can reject it — for large enterprise tables this can spike the web container's heap before the error is thrown.

The core job-slot enforcement (partial unique index, markTableJobRunning/releaseJobClaim, stale-job janitor) is well-structured and the import/delete runner paths handle failure and supersession correctly. The one concrete defect is in buildTableCsvForMount: tables are drained in parallel via Promise.all before the 50MB budget loop runs, so all CSVs land in memory simultaneously regardless of size — the budget check comes too late to prevent the allocation. Everything else in the PR (keyset pagination, limit clamping, deleteSourceFile flag, migration) looks correct and tested.

apps/sim/lib/copilot/tools/handlers/function-execute.ts — the parallel CSV build before budget enforcement is the main concern; the rest of the changed files look safe to merge.

Important Files Changed

Filename	Overview
apps/sim/lib/copilot/tools/handlers/function-execute.ts	Replaces truncated 100-row queryRows mount with full keyset drain via selectExportRowPage; all table CSVs are built in parallel before the 50MB budget check runs, risking OOM for large tables.
apps/sim/lib/copilot/tools/server/table/user-table.ts	Adds keyset pagination, limit enforcement, background import/delete dispatch, and get_job operation; doomedCount in delete_rows_by_filter can overestimate if rows are inserted between count and dispatch.
apps/sim/lib/table/import-runner.ts	Adds deleteSourceFile flag (defaults true) to skip deletion of persistent workspace files; existing streaming import logic unchanged.
apps/sim/lib/table/delete-runner.ts	New background delete worker using keyset pagination on id; ownership-gated per page; correctly calls markTableDeleteFailed on unexpected errors.
apps/sim/lib/table/service.ts	Migrates import-status columns to table_jobs table; adds markTableJobRunning, releaseJobClaim, selectExportRowPage, and latestJobForTable helpers; rowCount now subtracts pendingDeleteRemaining for mid-delete accuracy.
packages/db/migrations/0233_table_jobs_and_keyset.sql	Creates table_jobs with partial unique index for one active write-job per table; migrates existing import_status data; adds tenant-scoped GIN index and drops old cross-tenant one; all DDL is idempotent.
packages/db/migrations/0234_analyze_user_table_rows.sql	Runs ANALYZE on user_table_rows to fix reltuples=Infinity corruption from concurrent index builds; idempotent and safe.
apps/sim/app/api/cron/cleanup-stale-executions/route.ts	Updated stale-job janitor to operate on table_jobs instead of import columns; adds pruning of terminal jobs older than 24h and cleans up orphaned export storage objects.
apps/sim/app/api/table/[tableId]/import-async/route.ts	Switches from markTableImporting to markTableJobRunning; adds trigger.dev dispatch path with proper releaseJobClaim on dispatch failure.

Sequence Diagram

sequenceDiagram
    participant MB as Mothership Tool
    participant SVC as table/service
    participant JOB as table_jobs DB
    participant WRK as Background Worker
    participant SSE as SSE / get_job

    Note over MB,SSE: import_file (large CSV / trigger.dev path)
    MB->>SVC: markTableJobRunning(tableId, importId, 'import')
    SVC->>JOB: INSERT table_jobs ON CONFLICT DO NOTHING
    JOB-->>SVC: "claimed=true"
    MB->>WRK: tasks.trigger('table-import', payload)
    WRK-->>MB: dispatched
    MB-->>MB: return jobId

    Note over MB,SSE: delete_rows_by_filter (unbounded >1000 matches)
    MB->>SVC: queryRows(filter, limit:1) totalCount
    MB->>SVC: markTableJobRunning(tableId, jobId, 'delete', payload)
    SVC->>JOB: "INSERT status=running payload={filter,cutoff,doomedCount}"
    MB->>WRK: tasks.trigger('table-delete')
    WRK->>SVC: selectRowIdPage + deletePageByIds keyset loop
    WRK->>SVC: updateJobProgress / markJobReady
    SVC->>JOB: "UPDATE status=ready"
    WRK->>SSE: "appendTableEvent status=ready"

    Note over MB,SSE: get_job polling
    MB->>SVC: getTableById(tableId)
    SVC->>JOB: SELECT latest non-export job
    JOB-->>SVC: status rowsProcessed error
    SVC-->>MB: jobStatus jobRowsProcessed

Loading

_{Reviews (1): Last reviewed commit: "improvement(mothership): table speed par..." | Re-trigger Greptile}

[greptile-apps]

Full table CSVs built before budget enforcement

All input tables are serialized in parallel via Promise.all before any size check runs. For each table the buildTableCsvForMount loop fetches every row page-by-page and accumulates the entire CSV in memory — no size gate inside the loop. The outer budget check (totalSize + mount.content.length > MAX_TOTAL_SIZE) only fires after every table has been fully loaded.

Concrete failure: a user mounts two enterprise-plan tables each at ~40MB of rows. Both CSVs are built (80MB in memory) before the loop sees that the second one exceeds the 50MB cap and throws. File and directory mounts check record.size before fetching; tables lack that pre-flight guard. Under traffic, several concurrent requests doing this can exhaust the web container's heap.

[greptile-apps]

doomedCount can overestimate when rows are inserted between count and dispatch

matchCount comes from queryRows(..., { limit: 1, withExecutions: false }) and reflects the delete-mask-filtered row count. Between that count query and markTableJobRunning, rows inserted after the cutoff timestamp could match the filter, making matchCount stale. The cutoff passed to the background worker correctly caps new-row inclusion, but doomedCount stored in the job payload — and surfaced in the get_job response message — would over-report the number of rows being removed. Not a correctness issue for the worker, but the user-visible estimate is an upper bound, not an exact figure.

[greptile-apps]

Greptile Summary

This PR closes three performance gaps in Mothership's table operations: sandbox table mounts now drain all rows via keyset pagination instead of silently truncating to 100, query_rows gains a 1000-row limit cap and keyset cursor support, and large CSV/TSV imports plus unbounded filter-deletes are handed off to the existing background-job infrastructure (with a new get_job poll operation). The underlying data model also migrates: per-import state columns on user_table_definitions are replaced by a new table_jobs table with a partial-unique index enforcing one running write-job per table.

• function-execute mounts: buildTableCsvForMount pages through selectExportRowPage in 5k-row chunks, remaps column-id keys to display names, and counts toward the 50 MB budget — fixing empty-column mounts on id-keyed tables and the silent 100-row truncation.
• query_rows contract parity: limit now rejected above 1000, withExecutions: false, and keyset after/nextCursor accepted (rejected alongside sort); inline imports/deletes claim the one-write-job slot to block interleaving.
• Background import/delete in Mothership: CSV/TSV ≥ 8 MB dispatches tableImportTask; unbounded filter-deletes above 1000 rows dispatch tableDeleteTask with a pendingDeleteMask that hides doomed rows immediately from all read paths.

Confidence Score: 3/5

Safe to merge for most workloads; enterprise tables with hundreds of thousands of rows could exhaust Vercel function memory during a sandbox mount before the 50 MB budget check fires.

The core job-slot migration, keyset pagination, background import/delete dispatch, and schema change are all well-structured and tested. The one concern worth resolving before a wide enterprise rollout is buildTableCsvForMount: all table CSVs are fully assembled in parallel memory before the budget check, so a user who mounts a 500k-row enterprise table gets a function OOM rather than a clean rejection.

apps/sim/lib/copilot/tools/handlers/function-execute.ts — the buildTableCsvForMount loop and the parallel Promise.all mount assembly need a per-page budget check to avoid OOM on large enterprise tables.

Important Files Changed

Filename	Overview
apps/sim/lib/copilot/tools/handlers/function-execute.ts	Replaces the truncated 100-row queryRows mount with a keyset-draining buildTableCsvForMount that reads all rows and remaps id-keyed cells back to display names. Has a memory safety issue: the full CSV is materialized in memory before the 50 MB budget check runs, and pendingDeleteMask is called once per page (N+1 pattern).
apps/sim/lib/table/service.ts	Major overhaul: migrates import-status fields from user_table_definitions to table_jobs, adds selectExportRowPage (position-keyset export drain), pendingDeleteMask for delete-job visibility, selectRowIdPage/deletePageByIds for async delete workers, and latestJobForTable/latestJobsForTables for the new job fields. pendingDeleteMask now runs on every queryRows call regardless of table state.
apps/sim/lib/copilot/tools/server/table/user-table.ts	Adds query_rows limit clamping, keyset cursor (after/nextCursor), background delete dispatch for unbounded deletes, background import dispatch for large CSV/TSV files, get_job polling operation, and job-slot claim/release for inline imports. Logic is well-structured with proper guards and rollback paths.
apps/sim/lib/table/import-runner.ts	Renames import-specific service calls to generic job variants (markImportFailed→markJobFailed, etc.), adds deleteSourceFile flag (defaults true for UI single-use uploads; pass false for Mothership persistent workspace files), and updates SSE events to the new job event kind.
packages/db/migrations/0233_table_jobs_and_keyset.sql	Creates table_jobs with partial unique index (one running write-job per table), migrates existing import_status rows idempotently via ON CONFLICT DO NOTHING, tunes autovacuum on user_table_rows, and adds two CONCURRENT indexes (table_id+id keyset, tenant-scoped btree_gin) while dropping the old cross-tenant GIN index.
apps/sim/lib/table/delete-runner.ts	New async delete worker: walks rows in keyset pages (selectRowIdPage → deletePageByIds), checks job ownership on each page, applies cutoff/filter/exclusion scope, emits SSE events, and marks the job terminal or failed.
packages/db/schema.ts	Adds tableJobs table with unique partial index, replaces the old cross-tenant GIN index on user_table_rows with a tenant-scoped btree_gin index, adds table_id+id keyset index, and removes import_* columns from userTableDefinitions.
apps/sim/lib/table/dispatcher.ts	Extends DispatchScope with filter/excludeRowIds for select-all-under-filter and select-all-minus-deselections, wraps the dispatcherStep page query in withSeqscanOff for jsonb-filtered scopes, and adds scope-aware markActiveDispatchesCancelled with JSONB scope comparison.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Mothership: import_file / create_from_file] --> B{CSV/TSV 8 MB?}
    B -- No --> C[markTableJobRunning claim slot]
    C --> D[Inline import parseFileRows + batchInsert]
    D --> E[releaseJobClaim]
    B -- Yes --> F[createTable with jobStatus=running or markTableJobRunning]
    F --> G{isTriggerDevEnabled?}
    G -- Yes --> H[tasks.trigger tableImportTask]
    G -- No --> I[runDetached runTableImport]
    H -- dispatch error --> J[releaseJobClaim / deleteTable]
    I --> K[runTableImport streaming keyset import]
    H --> K

    L[Mothership: delete_rows_by_filter] --> M{limit === undefined?}
    M -- Yes --> N[queryRows count with pendingDeleteMask]
    N --> O{matchCount > 1000?}
    O -- No --> P[deleteRowsByFilter inline]
    O -- Yes --> Q[markTableJobRunning claim]
    Q --> R[dispatchDeleteJob]
    R --> S[runTableDelete keyset page walk]
    M -- No --> P

    T[Mothership: query_rows] --> U{limit > 1000?}
    U -- Yes --> V[return error]
    U -- No --> W[queryRows with pendingDeleteMask + after cursor]
    W --> X[return rows + nextCursor]

    Y[Mothership: get_job] --> Z[getTableById latestJobForTable]
    Z --> AA[return job status / rowCount]

Loading

_{Reviews (2): Last reviewed commit: "improvement(mothership): table speed par..." | Re-trigger Greptile}

[greptile-apps]

Full CSV materialized in memory before the 50 MB budget check

buildTableCsvForMount drains every row into a lines[] array and only returns after the full table is assembled. The budget check in the caller happens after all table CSVs are built via Promise.all. For an enterprise table with 100k+ rows, the CSV string can be hundreds of megabytes or more before the check ever fires — the budget guard prevents the file from reaching the sandbox, but the memory damage is already done (and in the parallel case, all tables are materialized simultaneously).

The old queryRows path implicitly bounded this to 100 rows. A straightforward fix is to track a running byte count inside the drain loop and throw early once the caller's budget would be exceeded — or pass maxBytes as a parameter and abort the page walk.

[greptile-apps]

pendingDeleteMask fetched on every page — N+1 DB round-trips during drain

selectExportRowPage calls pendingDeleteMask(table) unconditionally, so a 100k-row table drained in 20 pages makes 20 extra DB round-trips just to check whether a delete job is running. The mask is derived from table.id which is constant, and the delete job status won't change meaningfully mid-drain. Fetching it once before the loop and threading it through would eliminate the repeated queries.

[greptile-apps]

pendingDeleteMask adds an extra DB query to every queryRows call

pendingDeleteMask is now called at the top of queryRows on every invocation — adding a round-trip to every read path (grid page loads, Mothership query_rows, count refreshes, etc.). The vast majority of tables will never have a running delete job, so this query returns nothing almost all the time. A lightweight fast-path could skip the query if the table's derived jobStatus (already available on TableDefinition) isn't 'running'/'delete', or the mask could be pre-fetched where the caller already holds a recent TableDefinition.