fix(api): normalize folder paths and unblock resource mutations

Author: TheodoreSpeaks

apps/sim/app/api/v2/knowledge/[id]/route.ts

@@ -9,7 +9,6 @@ import {
 import { parseRequest } from '@/lib/api/server'
 import { generateRequestId } from '@/lib/core/utils/request'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
-import { withFolderTreeLock } from '@/lib/folders/locks'
 import { loadActiveFolderPathIndex } from '@/lib/folders/queries'
 import {
   performDeleteKnowledgeBase,
@@ -18,7 +17,7 @@ import {
 import type { KnowledgeBaseWithCounts } from '@/lib/knowledge/types'
 import { formatKnowledgeBase, resolveKnowledgeBase } from '@/app/api/v1/knowledge/utils'
 import { checkRateLimit, type RateLimitResult } from '@/app/api/v1/middleware'
-import { folderPathForId, resolveFolderPathId } from '@/app/api/v2/lib/folders'
+import { folderPathForId, resolveFolderPathIdentity } from '@/app/api/v2/lib/folders'
 import { v2ApiGateError } from '@/app/api/v2/lib/gate'
 import {
   v2Data,
@@ -134,30 +133,32 @@ export const PUT = withRouteHandler(async (request: NextRequest, context: Knowle
     const result = await resolveKnowledgeBaseScoped(id, workspaceId, userId, rateLimit, 'write')
     if (result instanceof NextResponse) return result
 
-    const mutation = await withFolderTreeLock(workspaceId, 'knowledge_base', async (tx) => {
-      const index = await loadActiveFolderPathIndex(workspaceId, 'knowledge_base', tx)
-      const folderId = folderPath === undefined ? undefined : resolveFolderPathId(index, folderPath)
-      if (folderPath !== undefined && folderId === undefined) return { found: false as const }
-
-      const outcome = await performUpdateKnowledgeBase({
-        knowledgeBaseId: id,
-        workspaceId,
-        userId,
-        source: 'api',
-        updates: { name, description, chunkingConfig, folderId },
-        requestId,
-        request,
-      })
-      return { found: true as const, index, outcome }
-    })
-    if (!mutation.found) {
+    const resolution =
+      folderPath === undefined
+        ? undefined
+        : await resolveFolderPathIdentity({
+            workspaceId,
+            resourceType: 'knowledge_base',
+            path: folderPath,
+          })
+    if (resolution && !resolution.found) {
       return v2Error('NOT_FOUND', 'Folder not found')
     }
-    const { index: folderIndex, outcome } = mutation
+
+    const outcome = await performUpdateKnowledgeBase({
+      knowledgeBaseId: id,
+      workspaceId,
+      userId,
+      source: 'api',
+      updates: { name, description, chunkingConfig, folderId: resolution?.folderId },
+      requestId,
+      request,
+    })
     if (!outcome.success) {
       return v2ErrorForOrchestration(outcome.errorCode, outcome.error)
     }
 
+    const folderIndex = await loadActiveFolderPathIndex(workspaceId, 'knowledge_base')
     return v2Data(
       {
         knowledgeBase: {

apps/sim/app/api/v2/knowledge/route.ts

@@ -16,7 +16,7 @@ import { checkRateLimit, resolveWorkspaceAccess } from '@/app/api/v1/middleware'
 import {
   folderPathForId,
   resolveFolderPathId,
-  withResolvedFolderPathMutation,
+  resolveFolderPathIdentity,
 } from '@/app/api/v2/lib/folders'
 import { v2ApiGateError } from '@/app/api/v2/lib/gate'
 import {
@@ -118,25 +118,24 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
     const access = await resolveWorkspaceAccess(rateLimit, userId, workspaceId, 'write')
     if (access) return v2WorkspaceAccessError(access)
 
-    const mutation = await withResolvedFolderPathMutation({
+    const resolution = await resolveFolderPathIdentity({
       workspaceId,
       resourceType: 'knowledge_base',
       path: folderPath ?? '/',
-      mutate: (folderId) =>
-        performCreateKnowledgeBase({
-          userId,
-          source: 'api',
-          workspaceId,
-          name,
-          description,
-          chunkingConfig,
-          folderId,
-          requestId,
-          request,
-        }),
     })
-    if (!mutation.found) return v2Error('NOT_FOUND', 'Folder not found')
-    const outcome = mutation.value
+    if (!resolution.found) return v2Error('NOT_FOUND', 'Folder not found')
+
+    const outcome = await performCreateKnowledgeBase({
+      userId,
+      source: 'api',
+      workspaceId,
+      name,
+      description,
+      chunkingConfig,
+      folderId: resolution.folderId,
+      requestId,
+      request,
+    })
     if (!outcome.success) {
       return v2ErrorForOrchestration(outcome.errorCode, outcome.error)
     }
@@ -145,7 +144,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       {
         knowledgeBase: {
           ...formatKnowledgeBase(outcome.knowledgeBase),
-          folderPath: folderPathForId(mutation.index, outcome.knowledgeBase.folderId),
+          folderPath: folderPathForId(resolution.index, outcome.knowledgeBase.folderId),
         },
       },
       { rateLimit, status: 201 }

apps/sim/app/api/v2/lib/folders.ts

@@ -21,13 +21,11 @@ export function resolveFolderPathId(
   return path === ROOT_FOLDER_PATH ? null : index.idByPath.get(path)
 }
 
-export type ResolvedFolderPathMutation<T> =
+export type ResolvedFolderPathIdentity =
   | { found: false }
-  | { found: true; folderId: string | null; index: FolderPathIndex<FolderRow>; value: T }
+  | { found: true; folderId: string | null; index: FolderPathIndex<FolderRow> }
 
-export type ResolvedFolderPathIdentity = { found: false } | { found: true; folderId: string | null }
-
-/** Resolves a canonical path to its stable internal identity under the folder tree lock. */
+/** Resolves a path to its stable internal identity under a short-lived folder tree lock. */
 export async function resolveFolderPathIdentity(params: {
   workspaceId: string
   resourceType: FolderResourceType
@@ -36,23 +34,7 @@ export async function resolveFolderPathIdentity(params: {
   return withFolderTreeLock(params.workspaceId, params.resourceType, async (tx) => {
     const index = await loadActiveFolderPathIndex(params.workspaceId, params.resourceType, tx)
     const folderId = resolveFolderPathId(index, params.path)
-    return folderId === undefined ? { found: false } : { found: true, folderId }
-  })
-}
-
-/** Resolves a canonical path and keeps that folder tree stable through a resource mutation. */
-export async function withResolvedFolderPathMutation<T>(params: {
-  workspaceId: string
-  resourceType: FolderResourceType
-  path: string
-  mutate: (folderId: string | null) => Promise<T>
-}): Promise<ResolvedFolderPathMutation<T>> {
-  return withFolderTreeLock(params.workspaceId, params.resourceType, async (tx) => {
-    const index = await loadActiveFolderPathIndex(params.workspaceId, params.resourceType, tx)
-    const folderId = resolveFolderPathId(index, params.path)
-    if (folderId === undefined) return { found: false }
-    const value = await params.mutate(folderId)
-    return { found: true, folderId, index, value }
+    return folderId === undefined ? { found: false } : { found: true, folderId, index }
   })
 }
 

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

@@ -10,7 +10,6 @@ import { parseRequest } from '@/lib/api/server'
 import { asOrchestrationError } from '@/lib/core/orchestration/types'
 import { generateRequestId } from '@/lib/core/utils/request'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
-import { withFolderTreeLock } from '@/lib/folders/locks'
 import { loadActiveFolderPathIndex } from '@/lib/folders/queries'
 import { getTableById } from '@/lib/table'
 import { signalTableSchemaChanged } from '@/lib/table/events'
@@ -21,7 +20,7 @@ import {
 } from '@/lib/table/orchestration'
 import { checkAccess } from '@/app/api/table/utils'
 import { checkRateLimit, resolveWorkspaceScope } from '@/app/api/v1/middleware'
-import { folderPathForId, resolveFolderPathId } from '@/app/api/v2/lib/folders'
+import { folderPathForId, resolveFolderPathIdentity } from '@/app/api/v2/lib/folders'
 import { v2ApiGateError } from '@/app/api/v2/lib/gate'
 import {
   v2Data,
@@ -155,75 +154,66 @@ export const PATCH = withRouteHandler(async (request: NextRequest, context: Tabl
       return v2Error('NOT_FOUND', 'Table not found')
     }
 
-    return await withFolderTreeLock(table.workspaceId, 'table', async (tx) => {
-      const folderIndex = await loadActiveFolderPathIndex(table.workspaceId, 'table', tx)
-      const folderId =
-        validated.folderPath === undefined
-          ? undefined
-          : resolveFolderPathId(folderIndex, validated.folderPath)
-      if (validated.folderPath !== undefined && folderId === undefined) {
-        return v2Error('NOT_FOUND', 'Folder not found in this workspace')
-      }
+    const resolution =
+      validated.folderPath === undefined
+        ? undefined
+        : await resolveFolderPathIdentity({
+            workspaceId: table.workspaceId,
+            resourceType: 'table',
+            path: validated.folderPath,
+          })
+    if (resolution && !resolution.found) {
+      return v2Error('NOT_FOUND', 'Folder not found in this workspace')
+    }
 
-      // Rename and move retain their shared services' independent transactions and audits.
-      // Validate deterministic failures first and report `applied` so callers can reconcile
-      // if a later fault lands after an earlier operation commits.
-      let failure: { outcome: OrchestrationOutcome; fallback: string } | null = null
-
-      if (validated.name !== undefined) {
-        const outcome = await performRenameTable({
-          table,
-          newName: validated.name,
-          userId,
-          requestId,
-          request,
-        })
-        if (outcome.success) applied.push('name')
-        else failure = { outcome, fallback: 'Failed to rename table' }
-      }
+    let failure: { outcome: OrchestrationOutcome; fallback: string } | null = null
+
+    if (validated.name !== undefined) {
+      const outcome = await performRenameTable({
+        table,
+        newName: validated.name,
+        userId,
+        requestId,
+        request,
+      })
+      if (outcome.success) applied.push('name')
+      else failure = { outcome, fallback: 'Failed to rename table' }
+    }
 
-      if (!failure && validated.folderPath !== undefined) {
-        const outcome = await performMoveTableToFolder({
-          table,
-          folderId: folderId ?? null,
-          userId,
-          requestId,
-          request,
-        })
-        if (outcome.success) {
-          applied.push('folderPath')
-        } else {
-          // The move re-asserts workspace and active state, so a miss means the
-          // table was archived between `checkAccess` and the write.
-          failure = {
-            outcome:
-              outcome.errorCode === 'not_found'
-                ? { ...outcome, error: 'Table not found' }
-                : outcome,
-            fallback: 'Failed to move table',
-          }
+    if (!failure && validated.folderPath !== undefined) {
+      const outcome = await performMoveTableToFolder({
+        table,
+        folderId: resolution?.folderId ?? null,
+        userId,
+        requestId,
+        request,
+      })
+      if (outcome.success) {
+        applied.push('folderPath')
+      } else {
+        failure = {
+          outcome:
+            outcome.errorCode === 'not_found' ? { ...outcome, error: 'Table not found' } : outcome,
+          fallback: 'Failed to move table',
         }
       }
+    }
 
-      // Live-collab: tell open viewers the definition changed so they refetch.
-      if (applied.length > 0) signalTableSchemaChanged(tableId)
-      if (failure) {
-        return v2TableOrchestrationError(failure.outcome, failure.fallback, appliedDetails(applied))
-      }
+    if (applied.length > 0) signalTableSchemaChanged(tableId)
+    if (failure) {
+      return v2TableOrchestrationError(failure.outcome, failure.fallback, appliedDetails(applied))
+    }
 
-      // Re-read so the response reflects every applied change at once. A miss
-      // means the table was archived after the writes committed, so the caller
-      // still has to be told what landed.
-      const updated = await getTableById(tableId)
-      if (!updated) {
-        return v2Error('NOT_FOUND', 'Table not found', { details: appliedDetails(applied) })
-      }
+    const updated = await getTableById(tableId)
+    if (!updated) {
+      return v2Error('NOT_FOUND', 'Table not found', { details: appliedDetails(applied) })
+    }
 
-      return v2Data(
-        { table: toApiTable(updated, folderPathForId(folderIndex, updated.folderId)) },
-        { rateLimit }
-      )
-    })
+    const folderIndex = await loadActiveFolderPathIndex(table.workspaceId, 'table')
+    return v2Data(
+      { table: toApiTable(updated, folderPathForId(folderIndex, updated.folderId)) },
+      { rateLimit }
+    )
   } catch (error) {
     const details = appliedDetails(applied)
 

apps/sim/app/api/v2/tables/imports/route.ts

@@ -9,7 +9,7 @@ import {
   toV2CreateTableImport,
 } from '@/lib/table/orchestration/import-resource'
 import { checkRateLimit, resolveWorkspaceScope } from '@/app/api/v1/middleware'
-import { withResolvedFolderPathMutation } from '@/app/api/v2/lib/folders'
+import { resolveFolderPathIdentity } from '@/app/api/v2/lib/folders'
 import { v2ApiGateError } from '@/app/api/v2/lib/gate'
 import {
   v2CaughtOrchestrationError,
@@ -43,15 +43,18 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
     if (scopeError) return v2WorkspaceAccessError(scopeError)
     let created: Awaited<ReturnType<typeof createTableImportResource>>
     if (parsed.data.body.target.type === 'new') {
-      const mutation = await withResolvedFolderPathMutation({
+      const resolution = await resolveFolderPathIdentity({
         workspaceId: parsed.data.body.workspaceId,
         resourceType: 'table',
         path: parsed.data.body.target.folderPath ?? '/',
-        mutate: (folderId) =>
-          createTableImportResource(parsed.data.body, userId, request.nextUrl.origin, folderId),
       })
-      if (!mutation.found) return v2Error('NOT_FOUND', 'Folder not found')
-      created = mutation.value
+      if (!resolution.found) return v2Error('NOT_FOUND', 'Folder not found')
+      created = await createTableImportResource(
+        parsed.data.body,
+        userId,
+        request.nextUrl.origin,
+        resolution.folderId
+      )
     } else {
       created = await createTableImportResource(parsed.data.body, userId, request.nextUrl.origin)
     }