@@ -332,7 +332,7 @@ describe('POST /api/v2/files', () => {
       userId: 'user-1',
       name: 'untitled.md',
       contentType: 'text/markdown',
-      folderId: null,
+      folderPath: '/',
       content: Buffer.alloc(0),
       exactName: true,
       request,
@@ -367,7 +367,7 @@ describe('POST /api/v2/files', () => {
         workspaceId: WS,
         name: 'seed.bin',
         contentType: 'application/octet-stream',
-        folderId: FOLDER_ID,
+        folderPath: '/Fixtures',
         content: Buffer.from([1, 2, 3]),
         exactName: true,
       })
 
@@ -137,16 +137,12 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
     const access = await resolveWorkspaceAccess(rateLimit, userId, workspaceId, 'write')
     if (access) return v2WorkspaceAccessError(access)
 
-    const folderIndex = await loadActiveFolderPathIndex(workspaceId, 'file')
-    const folderId = resolveFolderPathId(folderIndex, folderPath ?? '/')
-    if (folderId === undefined) return v2Error('NOT_FOUND', 'Folder not found')
-
     const result = await performCreateWorkspaceFile({
       workspaceId,
       userId,
       name,
       contentType: contentType ?? getMimeTypeFromExtension(getFileExtension(name)),
-      folderId,
+      folderPath: folderPath ?? '/',
       content: Buffer.from(content, encoding),
       exactName: true,
       request,
 
@@ -7,13 +7,13 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
 const {
   mockCheckRateLimit,
   mockResolveWorkspaceAccess,
-  mockAssertFolder,
   mockCreateUploadSession,
+  mockLoadActiveFolderPathIndex,
 } = vi.hoisted(() => ({
   mockCheckRateLimit: vi.fn(),
   mockResolveWorkspaceAccess: vi.fn(),
-  mockAssertFolder: vi.fn(),
   mockCreateUploadSession: vi.fn(),
+  mockLoadActiveFolderPathIndex: vi.fn(),
 }))
 
 vi.mock('@/app/api/v1/middleware', () => ({
@@ -25,8 +25,8 @@ vi.mock('@/app/api/v2/lib/gate', () => ({
   v2ApiGateError: vi.fn().mockResolvedValue(null),
 }))
 
-vi.mock('@/lib/uploads/contexts/workspace', () => ({
-  assertWorkspaceFileFolderTarget: mockAssertFolder,
+vi.mock('@/lib/folders/queries', () => ({
+  loadActiveFolderPathIndex: mockLoadActiveFolderPathIndex,
 }))
 
 vi.mock('@/lib/uploads/upload-session/service', () => ({
@@ -60,7 +60,11 @@ describe('POST /api/v2/files/uploads', () => {
     vi.clearAllMocks()
     mockCheckRateLimit.mockResolvedValue(RATE_LIMIT)
     mockResolveWorkspaceAccess.mockResolvedValue(null)
-    mockAssertFolder.mockResolvedValue(null)
+    mockLoadActiveFolderPathIndex.mockResolvedValue({
+      rowById: new Map(),
+      pathById: new Map(),
+      idByPath: new Map([['/Reports', 'folder-reports']]),
+    })
     mockCreateUploadSession.mockResolvedValue({
       id: 'upload-1',
       workspaceId: WORKSPACE_ID,
@@ -144,7 +148,7 @@ describe('POST /api/v2/files/uploads', () => {
     })
 
     expect(response.status).toBe(403)
-    expect(mockAssertFolder).not.toHaveBeenCalled()
+    expect(mockLoadActiveFolderPathIndex).not.toHaveBeenCalled()
     expect(mockCreateUploadSession).not.toHaveBeenCalled()
   })
 
@@ -161,4 +165,24 @@ describe('POST /api/v2/files/uploads', () => {
       expect.objectContaining({ purpose: 'workspace_file', fileSize: 0 })
     )
   })
+
+  it('resolves a canonical folder path while the upload session is created', async () => {
+    const response = await request({
+      workspaceId: WORKSPACE_ID,
+      name: 'file.csv',
+      contentType: 'text/csv',
+      size: 10,
+      folderPath: '/Reports',
+    })
+
+    expect(response.status).toBe(201)
+    expect(mockLoadActiveFolderPathIndex).toHaveBeenCalledWith(
+      WORKSPACE_ID,
+      'file',
+      expect.any(Object)
+    )
+    expect(mockCreateUploadSession).toHaveBeenCalledWith(
+      expect.objectContaining({ metadata: { folderId: 'folder-reports' } })
+    )
+  })
 })
@@ -4,11 +4,10 @@ import type { NextRequest } from 'next/server'
 import { v2CreateFileUploadContract } from '@/lib/api/contracts/v2/files'
 import { parseRequest } from '@/lib/api/server'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
-import { loadActiveFolderPathIndex } from '@/lib/folders/queries'
 import { createUploadSession } from '@/lib/uploads/upload-session/service'
 import { checkRateLimit, resolveWorkspaceAccess } from '@/app/api/v1/middleware'
 import { toV2FileUpload } from '@/app/api/v2/files/uploads/utils'
-import { resolveFolderPathId } from '@/app/api/v2/lib/folders'
+import { withResolvedFolderPathMutation } from '@/app/api/v2/lib/folders'
 import { v2ApiGateError } from '@/app/api/v2/lib/gate'
 import {
   v2CaughtOrchestrationError,
@@ -41,20 +40,24 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
     const { workspaceId, name, contentType, size, folderPath } = parsed.data.body
     const access = await resolveWorkspaceAccess(rateLimit, userId, workspaceId, 'write')
     if (access) return v2WorkspaceAccessError(access)
-    const folderIndex = await loadActiveFolderPathIndex(workspaceId, 'file')
-    const normalizedFolderId = resolveFolderPathId(folderIndex, folderPath ?? '/')
-    if (normalizedFolderId === undefined) return v2Error('NOT_FOUND', 'Folder not found')
-
-    const session = await createUploadSession({
+    const mutation = await withResolvedFolderPathMutation({
       workspaceId,
-      userId,
-      purpose: 'workspace_file',
-      fileName: name,
-      contentType,
-      fileSize: size,
-      metadata: { folderId: normalizedFolderId },
-      localOrigin: request.nextUrl.origin,
+      resourceType: 'file',
+      path: folderPath ?? '/',
+      mutate: (folderId) =>
+        createUploadSession({
+          workspaceId,
+          userId,
+          purpose: 'workspace_file',
+          fileName: name,
+          contentType,
+          fileSize: size,
+          metadata: { folderId },
+          localOrigin: request.nextUrl.origin,
+        }),
     })
+    if (!mutation.found) return v2Error('NOT_FOUND', 'Folder not found')
+    const session = mutation.value
     return v2Data(
       {
         session: toV2FileUpload(session, null),
 
@@ -345,10 +345,26 @@ export async function resolveWorkspaceFileFolderTarget(
 
 export async function assertWorkspaceFileFolderTarget(
   workspaceId: string,
-  folderId?: string | null
+  folderId?: string | null,
+  executor: DbOrTx = db
 ): Promise<string | null> {
-  const folder = await resolveWorkspaceFileFolderTarget(workspaceId, folderId)
-  return folder?.id ?? null
+  const normalized = normalizeParentId(folderId)
+  if (!normalized) return null
+
+  const [folder] = await executor
+    .select({ id: folderTable.id })
+    .from(folderTable)
+    .where(
+      and(
+        eq(folderTable.id, normalized),
+        eq(folderTable.workspaceId, workspaceId),
+        isFileFolder,
+        isNull(folderTable.deletedAt)
+      )
+    )
+    .limit(1)
+  if (!folder) throw new OrchestrationError('not_found', 'Target folder not found')
+  return folder.id
 }
 
 export async function createWorkspaceFileFolder(params: {
 
@@ -38,6 +38,9 @@ import { asOrchestrationError, OrchestrationError } from '@/lib/core/orchestrati
 import { generateRequestId } from '@/lib/core/utils/request'
 import { generateRestoreName } from '@/lib/core/utils/restore-name'
 import type { DbOrTx } from '@/lib/db/types'
+import { acquireFolderMutationLock } from '@/lib/folders/locks'
+import { parseFolderPath } from '@/lib/folders/paths'
+import { loadActiveFolderPathIndex, resolveFolderPathFromIndex } from '@/lib/folders/queries'
 import { mergeEditIntoLiveFileDoc, notifyWorkspaceFilesChanged } from '@/lib/realtime/notify'
 import { getServePathPrefix } from '@/lib/uploads'
 import {
@@ -338,13 +341,30 @@ export async function uploadWorkspaceFile(
   fileBuffer: Buffer,
   fileName: string,
   contentType: string,
-  options?: { folderId?: string | null; exactName?: boolean }
+  options?: { folderId?: string | null; folderPath?: string; exactName?: boolean }
 ): Promise<UploadedWorkspaceFileRecord> {
   logger.info(`Uploading workspace file: ${fileName} for workspace ${workspaceId}`)
 
-  const folderTarget = await resolveWorkspaceFileFolderTarget(workspaceId, options?.folderId)
-  const folderId = folderTarget?.id ?? null
-  const folderPath = folderTarget?.path ?? null
+  if (options?.folderId !== undefined && options.folderPath !== undefined) {
+    throw new OrchestrationError('validation', 'Specify either folderId or folderPath, not both')
+  }
+
+  let folderId: string | null
+  let folderPath: string | null
+  if (options?.folderPath !== undefined) {
+    const folderPathSegments = parseFolderPath(options.folderPath)
+    const folderIndex = await loadActiveFolderPathIndex(workspaceId, 'file')
+    const resolvedFolderId = resolveFolderPathFromIndex(folderIndex, options.folderPath)
+    if (resolvedFolderId === undefined) {
+      throw new OrchestrationError('not_found', 'Target folder not found')
+    }
+    folderId = resolvedFolderId
+    folderPath = resolvedFolderId ? folderPathSegments.join('/') : null
+  } else {
+    const folderTarget = await resolveWorkspaceFileFolderTarget(workspaceId, options?.folderId)
+    folderId = folderTarget?.id ?? null
+    folderPath = folderTarget?.path ?? null
+  }
   const normalizedFileName = normalizeWorkspaceFileItemName(fileName, 'File')
   const exactName = options?.exactName ?? false
   const storageBillingContext = await resolveStorageBillingContext(workspaceId)
@@ -370,7 +390,7 @@ export async function uploadWorkspaceFile(
         purpose: 'workspace',
         userId: userId,
         workspaceId: workspaceId,
-        ...(folderId ? { folderId } : {}),
+        ...(folderId && options?.folderPath === undefined ? { folderId } : {}),
       }
 
       const uploadResult = await uploadFile({
@@ -392,12 +412,24 @@ export async function uploadWorkspaceFile(
       }
       try {
         finalized = await db.transaction(async (tx) => {
+          await acquireFolderMutationLock(tx, workspaceId, 'file')
+          let activeFolderId: string | null
+          if (options?.folderPath !== undefined) {
+            const folderIndex = await loadActiveFolderPathIndex(workspaceId, 'file', tx)
+            const resolvedFolderId = resolveFolderPathFromIndex(folderIndex, options.folderPath)
+            if (resolvedFolderId === undefined) {
+              throw new OrchestrationError('not_found', 'Target folder not found')
+            }
+            activeFolderId = resolvedFolderId
+          } else {
+            activeFolderId = await assertWorkspaceFileFolderTarget(workspaceId, folderId, tx)
+          }
           const inserted = await insertWorkspaceFileMetadataInTx(tx, {
             id: fileId,
             key: uploadResult.key,
             userId,
             workspaceId,
-            folderId,
+            folderId: activeFolderId,
             originalName: uniqueName,
             contentType,
             size: fileBuffer.length,
@@ -537,7 +569,7 @@ export async function registerUploadedWorkspaceFile(params: {
     }
   }
 
-  const folderId = await assertWorkspaceFileFolderTarget(workspaceId, params.folderId)
+  const folderId = params.folderId ?? null
 
   const storageBillingContext = await resolveStorageBillingContext(workspaceId)
   for (let attempt = 0; attempt < MAX_UPLOAD_UNIQUE_RETRIES; attempt++) {
@@ -549,12 +581,14 @@ export async function registerUploadedWorkspaceFile(params: {
     )
 
     const finalized = await db.transaction(async (tx) => {
+      await acquireFolderMutationLock(tx, workspaceId, 'file')
+      const activeFolderId = await assertWorkspaceFileFolderTarget(workspaceId, folderId, tx)
       const inserted = await insertWorkspaceFileMetadataInTx(tx, {
         id: fileId,
         key,
         userId,
         workspaceId,
-        folderId,
+        folderId: activeFolderId,
         originalName: displayName,
         contentType,
         size: verifiedSize,