fix(tables): resolve reference review findings

Author: j15z

apps/sim/app/workspace/[workspaceId]/tables/[tableId]/hooks/use-table-event-stream.ts

@@ -475,12 +475,16 @@ export function useTableEventStream({
           // invalidateTableSchema set — the definition (exact, so rows stay on the
           // debounce), the run-state + enrichment sibling queries under detail (a group
           // delete/restructure can otherwise leave a stale running badge or enrichment
-          // panel), the tables list (column/row counts), and the debounced rows.
+          // panel), the tables list (column/row counts), open reference previews, and the
+          // debounced rows.
           else if (entry.event?.kind === 'schema') {
             void queryClient.invalidateQueries({ queryKey: tableKeys.detail(tableId), exact: true })
             void queryClient.invalidateQueries({ queryKey: tableKeys.activeDispatches(tableId) })
             void queryClient.invalidateQueries({ queryKey: tableKeys.enrichmentDetails(tableId) })
             void queryClient.invalidateQueries({ queryKey: tableKeys.lists() })
+            void queryClient.invalidateQueries({
+              queryKey: tableKeys.referencePreviewsForTable(tableId),
+            })
             scheduleRowsInvalidate()
           }
           // A collaborator changed the column layout (width/pin/order): refetch the

apps/sim/app/workspace/[workspaceId]/tables/hooks/use-workspace-tables-room.ts

@@ -8,8 +8,9 @@ import { tableKeys } from '@/hooks/queries/utils/table-keys'
 
 /**
  * Keeps the tables browser live: joins the workspace-tables room so a `workspace-tables-changed`
- * broadcast (fanned out by the table + table-folder mutation services) invalidates the tables list
- * AND the table folders so every viewer refetches without waiting for staleness. A created/renamed/
+ * broadcast (fanned out by the table + table-folder mutation services) invalidates table lists,
+ * names, reference previews, AND table folders so every viewer refetches without waiting for
+ * staleness. A created/renamed/
  * moved/deleted/restored table changes the list result (including folder placement); a folder
  * create/rename/delete/restore changes the folder tree — the page renders both, so both are
  * invalidated. Thin binding over {@link useWorkspaceInvalidationRoom}.
@@ -18,6 +19,8 @@ export function useWorkspaceTablesRoom(workspaceId: string): void {
   const queryClient = useQueryClient()
   useWorkspaceInvalidationRoom(workspaceId, ROOM_TYPES.WORKSPACE_TABLES, () => {
     queryClient.invalidateQueries({ queryKey: tableKeys.lists() })
+    queryClient.invalidateQueries({ queryKey: tableKeys.namesRoot() })
+    queryClient.invalidateQueries({ queryKey: tableKeys.referencePreviews() })
     queryClient.invalidateQueries({ queryKey: folderKeys.resource('table') })
   })
 }

apps/sim/hooks/queries/folders.ts

@@ -128,7 +128,11 @@ function invalidateCascadedResourceLists(
     case 'workflow':
       return invalidateWorkflowLists(queryClient, workspaceId, ['active', 'archived'])
     case 'table':
-      return queryClient.invalidateQueries({ queryKey: tableKeys.lists() })
+      return Promise.all([
+        queryClient.invalidateQueries({ queryKey: tableKeys.lists() }),
+        queryClient.invalidateQueries({ queryKey: tableKeys.namesRoot() }),
+        queryClient.invalidateQueries({ queryKey: tableKeys.referencePreviews() }),
+      ]).then(() => undefined)
     case 'knowledge_base':
       return queryClient.invalidateQueries({ queryKey: knowledgeKeys.lists() })
     /**

apps/sim/hooks/queries/tables.test.ts

@@ -127,6 +127,8 @@ describe('useTableNames', () => {
       enabled: true,
       queryKey: tableKeys.names(WORKSPACE_ID, [TABLE_ID, 'tbl-2']),
     })
+    expect(options.queryKey.slice(0, tableKeys.namesRoot().length)).toEqual(tableKeys.namesRoot())
+    expect(options.queryKey.slice(0, tableKeys.lists().length)).not.toEqual(tableKeys.lists())
     expect(requestJson).toHaveBeenCalledWith(listTableNamesContract, {
       body: { workspaceId: WORKSPACE_ID, tableIds: [TABLE_ID, 'tbl-2'] },
       signal,
@@ -580,7 +582,7 @@ describe('useDeleteColumn optimistic update', () => {
     expect(getCache(ROWS_KEY)).toEqual(originalRows)
   })
 
-  it('invalidates schema, rows, and lists in onSettled', () => {
+  it('invalidates schema, rows, lists, and mounted reference previews in onSettled', () => {
     const hook = useDeleteColumn({ workspaceId: WORKSPACE_ID, tableId: TABLE_ID })
     hook.onSettled?.(undefined, null, 'age', undefined)
 
@@ -590,6 +592,7 @@ describe('useDeleteColumn optimistic update', () => {
         tableKeys.detail(TABLE_ID),
         tableKeys.rowsRoot(TABLE_ID),
         tableKeys.lists(),
+        tableKeys.referencePreviewsForTable(TABLE_ID),
       ])
     )
   })
@@ -648,6 +651,15 @@ describe('useUpdateColumn optimistic update', () => {
     )
     expect(detail?.schema.columns[0]).toMatchObject({ id: 'age', name: 'years' })
   })
+
+  it('invalidates mounted previews when the referenced table schema changes', () => {
+    const hook = useUpdateColumn({ workspaceId: WORKSPACE_ID, tableId: TABLE_ID })
+    hook.onSettled?.(undefined, null, { columnName: 'age', updates: { name: 'years' } }, undefined)
+
+    expect(queryClient.invalidateQueries).toHaveBeenCalledWith({
+      queryKey: tableKeys.referencePreviewsForTable(TABLE_ID),
+    })
+  })
 })
 
 describe('useRestoreTable cache invalidation', () => {
@@ -674,16 +686,18 @@ describe('useRestoreTable cache invalidation', () => {
     })
   })
 
-  it('invalidates lists, table detail, and row data for the restored table', () => {
+  it('invalidates names, previews, lists, table detail, and row data for the restored table', () => {
     const hook = useRestoreTable()
     hook.onSettled?.(undefined, null, TABLE_ID, undefined)
 
     const calls = queryClient.invalidateQueries.mock.calls.map((c) => c[0]?.queryKey)
     expect(calls).toEqual(
       expect.arrayContaining([
         tableKeys.lists(),
+        tableKeys.namesRoot(),
         tableKeys.detail(TABLE_ID),
         tableKeys.rowsRoot(TABLE_ID),
+        tableKeys.referencePreviewsForTable(TABLE_ID),
       ])
     )
   })

apps/sim/hooks/queries/tables.ts

@@ -280,6 +280,17 @@ function invalidateReferencePreviews(
   })
 }
 
+function invalidateTableNames(queryClient: ReturnType<typeof useQueryClient>) {
+  queryClient.invalidateQueries({ queryKey: tableKeys.namesRoot() })
+}
+
+function invalidateReferenceTablePreviews(
+  queryClient: ReturnType<typeof useQueryClient>,
+  tableId: string
+) {
+  queryClient.invalidateQueries({ queryKey: tableKeys.referencePreviewsForTable(tableId) })
+}
+
 /**
  * Invalidate only the row-count surfaces — the table detail and the tables
  * list, both of which carry the unfiltered `rowCount`. Deliberately leaves
@@ -304,6 +315,7 @@ function invalidateTableSchema(queryClient: ReturnType<typeof useQueryClient>, t
   queryClient.invalidateQueries({ queryKey: tableKeys.detail(tableId) })
   queryClient.invalidateQueries({ queryKey: tableKeys.rowsRoot(tableId) })
   queryClient.invalidateQueries({ queryKey: tableKeys.lists() })
+  invalidateReferenceTablePreviews(queryClient, tableId)
 }
 
 /**
@@ -321,6 +333,7 @@ function invalidateTableSchemaOnly(
 ) {
   queryClient.invalidateQueries({ queryKey: tableKeys.detail(tableId) })
   queryClient.invalidateQueries({ queryKey: tableKeys.lists() })
+  invalidateReferenceTablePreviews(queryClient, tableId)
 }
 
 /**
@@ -730,6 +743,7 @@ export function useCreateTable(workspaceId: string) {
     },
     onSettled: () => {
       queryClient.invalidateQueries({ queryKey: tableKeys.lists() })
+      invalidateTableNames(queryClient)
     },
   })
 }
@@ -779,6 +793,8 @@ export function useRenameTable(workspaceId: string) {
     onSettled: (_data, _error, variables) => {
       queryClient.invalidateQueries({ queryKey: tableKeys.detail(variables.tableId) })
       queryClient.invalidateQueries({ queryKey: tableKeys.lists() })
+      invalidateTableNames(queryClient)
+      invalidateReferenceTablePreviews(queryClient, variables.tableId)
     },
   })
 }
@@ -889,6 +905,8 @@ export function useDeleteTable(workspaceId: string) {
     },
     onSettled: (_data, _error, tableId) => {
       queryClient.invalidateQueries({ queryKey: tableKeys.lists() })
+      invalidateTableNames(queryClient)
+      invalidateReferenceTablePreviews(queryClient, tableId)
       queryClient.removeQueries({ queryKey: tableKeys.detail(tableId) })
       queryClient.removeQueries({ queryKey: tableKeys.rowsRoot(tableId) })
     },
@@ -1954,8 +1972,12 @@ export function useRestoreTable() {
     onSettled: (_data, _error, tableId) => {
       return Promise.all([
         queryClient.invalidateQueries({ queryKey: tableKeys.lists() }),
+        queryClient.invalidateQueries({ queryKey: tableKeys.namesRoot() }),
         queryClient.invalidateQueries({ queryKey: tableKeys.detail(tableId) }),
         queryClient.invalidateQueries({ queryKey: tableKeys.rowsRoot(tableId) }),
+        queryClient.invalidateQueries({
+          queryKey: tableKeys.referencePreviewsForTable(tableId),
+        }),
       ])
     },
   })
@@ -2073,6 +2095,7 @@ export function useImportCsv() {
     },
     onSettled: () => {
       queryClient.invalidateQueries({ queryKey: tableKeys.lists() })
+      invalidateTableNames(queryClient)
     },
   })
 }
@@ -2117,6 +2140,7 @@ export function useImportFileAsTable() {
     },
     onSettled: () => {
       queryClient.invalidateQueries({ queryKey: tableKeys.lists() })
+      invalidateTableNames(queryClient)
     },
   })
 }
@@ -2784,6 +2808,8 @@ export function useBulkDeleteTables(workspaceId: string) {
     },
     onSettled: (_data, _error, { tableIds = [] }) => {
       queryClient.invalidateQueries({ queryKey: tableKeys.lists() })
+      invalidateTableNames(queryClient)
+      queryClient.invalidateQueries({ queryKey: tableKeys.referencePreviews() })
       queryClient.invalidateQueries({ queryKey: folderKeys.resource('table') })
       for (const tableId of tableIds) {
         queryClient.removeQueries({ queryKey: tableKeys.detail(tableId) })

apps/sim/hooks/queries/utils/table-keys.ts

@@ -20,16 +20,19 @@ export const tableKeys = {
   lists: () => [...tableKeys.all, 'list'] as const,
   list: (workspaceId?: string, scope: TableQueryScope = 'active') =>
     [...tableKeys.lists(), workspaceId ?? '', scope] as const,
+  namesRoot: () => [...tableKeys.all, 'names'] as const,
   names: (workspaceId: string | undefined, tableIds: readonly string[]) =>
-    [...tableKeys.lists(), 'names', workspaceId ?? '', tableIds] as const,
+    [...tableKeys.namesRoot(), workspaceId ?? '', tableIds] as const,
   details: () => [...tableKeys.all, 'detail'] as const,
   detail: (tableId: string) => [...tableKeys.details(), tableId] as const,
   exportJobs: (workspaceId?: string) =>
     [...tableKeys.all, 'export-jobs', workspaceId ?? ''] as const,
   rowsRoot: (tableId: string) => [...tableKeys.detail(tableId), 'rows'] as const,
   referencePreviews: () => [...tableKeys.all, 'reference-preview'] as const,
+  referencePreviewsForTable: (tableId: string) =>
+    [...tableKeys.referencePreviews(), tableId] as const,
   referencePreview: (tableId: string, rowId: string, sourceRowId = '', sourceColumnKey = '') =>
-    [...tableKeys.referencePreviews(), tableId, rowId, sourceRowId, sourceColumnKey] as const,
+    [...tableKeys.referencePreviewsForTable(tableId), rowId, sourceRowId, sourceColumnKey] as const,
   /**
    * Prefix covering only the paged row lists. `rowsRoot` is a shared parent — `find`
    * hangs off it holding a different shape — so anything walking the cache for row

apps/sim/lib/folders/cascade.test.ts

@@ -23,6 +23,14 @@ import { FolderCollectionLimitExceededError } from '@/lib/folders/errors'
 import { folderResourceSupportsLocking } from '@/lib/folders/resource-traits'
 import { folderMutationStatus } from '@/lib/folders/status'
 
+const tableServiceMocks = vi.hoisted(() => ({
+  deleteTables: vi.fn(),
+}))
+
+vi.mock('@/lib/table/service', () => ({
+  deleteTables: tableServiceMocks.deleteTables,
+}))
+
 interface SelectCall {
   where: unknown
 }
@@ -545,6 +553,41 @@ describe('knowledge_base and table folder resources', () => {
     expect(knowledgeConfig.sortOrderColumn).toBeUndefined()
     expect(tableConfig.sortOrderColumn).toBeUndefined()
   })
+
+  it('archives table children as one restorable cohort', async () => {
+    resetDbChainMock()
+    queueTableRows(schemaMock.userTableDefinitions, [
+      { id: 'tbl_accounts' },
+      { id: 'tbl_contacts' },
+    ])
+    tableServiceMocks.deleteTables.mockResolvedValueOnce({
+      archived: [
+        { id: 'tbl_accounts', name: 'Accounts', workspaceId: 'ws-1' },
+        { id: 'tbl_contacts', name: 'Contacts', workspaceId: 'ws-1' },
+      ],
+      failed: [],
+      notFound: [],
+    })
+
+    await expect(
+      tableConfig.archiveChildren?.({
+        workspaceId: 'ws-1',
+        folderIds: ['folder-1'],
+        timestamp: TIMESTAMP,
+      })
+    ).resolves.toBe(2)
+
+    expect(tableServiceMocks.deleteTables).toHaveBeenCalledWith(
+      ['tbl_accounts', 'tbl_contacts'],
+      'folder-cascade-folder-1',
+      {
+        expectedWorkspaceId: 'ws-1',
+        archivedAt: TIMESTAMP,
+        skipNotify: true,
+        archiveAsCohort: true,
+      }
+    )
+  })
 })
 
 describe('table folder deletion guard', () => {

apps/sim/lib/folders/cascade.ts

@@ -99,8 +99,8 @@ function childFilter(config: FolderResourceConfig, workspaceId: string, folderId
  * also reviving siblings that were deleted independently.
  *
  * Folders are stamped BEFORE their children, which is what makes a failed cascade
- * recoverable. `archiveChildren` hooks walk resources one at a time through their canonical
- * delete, so a mid-loop failure can leave some children archived and some not. With the
+ * recoverable. `archiveChildren` hooks may walk resources through their canonical deletes, so
+ * a mid-cascade failure can leave some children archived and some not. With the
  * folder already stamped, `deleteFolder` reuses that same `deletedAt` on the retry and the
  * stragglers join the original snapshot. Stamping children first would leave the folder
  * active, so a retry would mint a fresh timestamp and the partially-archived children could

apps/sim/lib/folders/config.ts

@@ -11,6 +11,7 @@ import {
 import { eq, type SQL } from 'drizzle-orm'
 import type { PgColumn, PgTable } from 'drizzle-orm/pg-core'
 import type { FolderResourceType } from '@/lib/api/contracts/folders'
+import { OrchestrationError } from '@/lib/core/orchestration/types'
 import {
   FOLDER_RESOURCE_LABELS,
   FOLDER_RESOURCE_SUPPORTS_LOCKING,
@@ -310,18 +311,21 @@ async function restoreKnowledgeBaseChildren(context: CascadeChildrenContext): Pr
  * encounter a partial cascade.
  */
 async function archiveTableChildren(context: CascadeChildrenContext): Promise<number> {
-  const { deleteTable } = await import('@/lib/table/service')
+  const { deleteTables } = await import('@/lib/table/service')
   const ids = await selectChildIds(FOLDER_RESOURCES.table, context, 'active')
-
-  for (const id of ids) {
-    await deleteTable(id, `folder-cascade-${context.folderIds[0]}`, {
-      archivedAt: context.timestamp,
-      // deleteFolder fires one folder-level live-list notify for the whole subtree.
-      skipNotify: true,
-    })
+  const result = await deleteTables(ids, `folder-cascade-${context.folderIds[0]}`, {
+    expectedWorkspaceId: context.workspaceId,
+    archivedAt: context.timestamp,
+    // deleteFolder fires one folder-level live-list notify for the whole subtree.
+    skipNotify: true,
+    archiveAsCohort: true,
+  })
+  if (result.terminalError) throw result.terminalError
+  if (result.failed[0]) {
+    throw new OrchestrationError('conflict', result.failed[0].reason)
   }
 
-  return ids.length
+  return result.archived.length
 }
 
 /**

apps/sim/lib/table/service.test.ts

@@ -746,6 +746,35 @@ describe('deleteTables reference guard', () => {
     expect(dbChainMockFns.update).toHaveBeenCalledOnce()
   })
 
+  it('archives a reference cycle atomically when it will be restored as one cohort', async () => {
+    queueTableRows(schemaMock.userTableDefinitions, [
+      batchTable('tbl_accounts', 'Accounts', ['tbl_contacts']),
+      batchTable('tbl_contacts', 'Contacts', ['tbl_accounts']),
+    ])
+    dbChainMockFns.returning.mockResolvedValueOnce([
+      { id: 'tbl_accounts', name: 'Accounts', workspaceId: WORKSPACE_ID },
+      { id: 'tbl_contacts', name: 'Contacts', workspaceId: WORKSPACE_ID },
+    ])
+
+    await expect(
+      deleteTables(['tbl_accounts', 'tbl_contacts'], 'folder-cascade-folder-1', {
+        expectedWorkspaceId: WORKSPACE_ID,
+        skipNotify: true,
+        archiveAsCohort: true,
+      })
+    ).resolves.toEqual({
+      archived: [
+        { id: 'tbl_accounts', name: 'Accounts', workspaceId: WORKSPACE_ID },
+        { id: 'tbl_contacts', name: 'Contacts', workspaceId: WORKSPACE_ID },
+      ],
+      failed: [],
+      notFound: [],
+    })
+
+    expect(dbChainMockFns.update).toHaveBeenCalledOnce()
+    expect(dbChainMockFns.transaction).toHaveBeenCalledOnce()
+  })
+
   it('allows a self-referencing table to archive', async () => {
     queueTableRows(schemaMock.userTableDefinitions, [
       batchTable('tbl_categories', 'Categories', ['tbl_categories']),