fix(folders): close the folder-engine audit findings

Data loss
- Migration 0274 catches up file folders created AFTER 0272. That backfill is guarded
  by `WHERE NOT EXISTS (… resource_type = 'file')`, so it fires once; every file folder
  created between it and this cutover exists only in `workspace_file_folders`. Without
  the catch-up they vanish from Files on deploy and their contents become unreachable

Authorization
- Archived folders were mutable, which bypassed the folder lock: the folder routes and
  `updateFolder` filtered id + resourceType but never `deletedAt`, while
  `getFolderLockStatus` does — so an archived-but-locked folder reported unlocked. Lock a
  subfolder, delete its parent, and any write-level member could rename and reparent it.
  PUT and the engine now require an active row; DELETE deliberately still does not, because
  it reuses an archived folder's own `deletedAt` to make a partial cascade retryable
- `v1/admin/workflows/import` wrote `folderId` with no validation at all. Migration 0272
  dropped the FK, so it accepted a knowledge-base folder, another workspace's folder, or
  garbage — and the workflow then rendered under no sidebar node while still executing,
  billing, and escaping the folder delete cascade. It now runs the same
  `assertFolderInWorkspace` + `assertFolderMutable` pair as `v1/workflows/import`

Restore no longer loses state
- A folder restore ran a bare `archivedAt = null` over its workflows, while the delete had
  routed through `archiveWorkflow` — which also disables schedules, webhooks, chats, and MCP
  tools. Restoring a folder reported success while every schedule stayed disabled forever
  and every chat 404'd. The workflow tree now restores through `restoreWorkflow`, like the
  knowledge-base and table trees already did. Deployment state is still deliberately not
  revived, matching the single-workflow restore
- Those canonical restores re-root a resource whose folder is archived — correct on its own,
  catastrophic inside a cascade, which restores children BEFORE the folder rows and would
  therefore dump every child at the workspace root. `resolveRestoredFolderId` takes the
  subtree being restored and exempts it. `restoreTable` gained the re-root check it lacked

Correctness
- `getFolderPath` in `lib/folders/tree.ts` walked `parentId` with no `visited` set, so a
  cycle in the client cache — reachable through `useReorderFolders`' unchecked optimistic
  write — hung the tab. Its twin already had one. Dead `buildFolderMap` deleted
- The sidebar's "New folder" inside a folder hardcoded the name, so the second one 409'd,
  was swallowed with only a log line, and the user got no folder and no message. It now
  names through the existing `generateSubfolderName` and surfaces failures
- `chunkedBatchDelete` deleted by id with no re-check, so a resource restored between the
  SELECT and the DELETE was hard-deleted anyway. Callers now re-assert their soft-delete
  predicate on the DELETE
- Recently Deleted and the `restore_resource` tool cover every folder tree, not just
  workflow folders, so deleted knowledge-base and table folders are recoverable

Cleanup
- The folder duplicate route stops steering control flow through `throw new Error('literal')`
  matched by string, reuses the engine's `nextFolderSortOrder` instead of recomputing it, and
  names its workflow scope once
- `servedFolderResourceTypeSchema` documents that its default applies only to an omitted
  value; a present-but-unrecognized one is rejected, never coerced to `workflow`
- The `workspace_file_folders` comment described the table as unread and unwritten and
  invited a DROP. It was live until this cutover, and it is now the rollback copy — the
  comment says so, and names what must be true before anyone drops it
- Pinned rows carry a small non-interactive pin glyph again; they sort to the top and had
  nothing explaining why since the inline pin button was removed

Tests
- New `lib/folders/lifecycle.test.ts` covers create/update/delete/restore, the re-root, and
  the 23505 mappings; `cleanup-soft-deletes.test.ts` now pins the folder target's
  resourceType predicate, which is what keeps the sweep off a not-yet-cut-over type

Author: waleedlatif1

apps/sim/app/api/folders/[id]/duplicate/route.ts

@@ -4,21 +4,46 @@ import { folder as folderTable, workflow } from '@sim/db/schema'
 import { createLogger } from '@sim/logger'
 import { FolderLockedError } from '@sim/platform-authz/workflow'
 import { generateId } from '@sim/utils/id'
-import { and, eq, isNull, min } from 'drizzle-orm'
+import { and, eq, isNull } from 'drizzle-orm'
 import { type NextRequest, NextResponse } from 'next/server'
 import { duplicateFolderContract } from '@/lib/api/contracts'
 import { parseRequest } from '@/lib/api/server'
 import { getSession } from '@/lib/auth'
 import { generateRequestId } from '@/lib/core/utils/request'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import type { DbOrTx } from '@/lib/db/types'
+import { nextFolderSortOrder } from '@/lib/folders/lifecycle'
 import { deduplicateFolderName } from '@/lib/folders/naming'
 import { toFolderApi } from '@/lib/folders/queries'
 import { duplicateWorkflow } from '@/lib/workflows/persistence/duplicate'
 import { getUserEntityPermissions } from '@/lib/workspaces/permissions/utils'
 
 const logger = createLogger('FolderDuplicateAPI')
 
+/**
+ * Duplication only ever copies workflow folders. Named once so the scope is stated rather
+ * than restated as a literal at every query — the engine reads its resourceType from config
+ * for exactly this reason.
+ */
+const FOLDER_RESOURCE_TYPE = 'workflow' as const
+
+/**
+ * Carries the HTTP status with the failure, so the handler maps errors by type instead of by
+ * comparing `error.message` to a literal — a coupling that breaks silently the moment
+ * someone rewords a message.
+ */
+class FolderDuplicationError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    /** Message returned to the caller when it must differ from the logged one. */
+    readonly publicMessage: string = message
+  ) {
+    super(message)
+    this.name = 'FolderDuplicationError'
+  }
+}
+
 // POST /api/folders/[id]/duplicate - Duplicate a folder with all its child folders and workflows
 export const POST = withRouteHandler(
   async (req: NextRequest, context: { params: Promise<{ id: string }> }) => {
@@ -46,13 +71,13 @@ export const POST = withRouteHandler(
           and(
             eq(folderTable.id, sourceFolderId),
             isNull(folderTable.deletedAt),
-            eq(folderTable.resourceType, 'workflow')
+            eq(folderTable.resourceType, FOLDER_RESOURCE_TYPE)
           )
         )
         .then((rows) => rows[0])
 
       if (!sourceFolder) {
-        throw new Error('Source folder not found')
+        throw new FolderDuplicationError('Source folder not found', 404)
       }
 
       const userPermission = await getUserEntityPermissions(
@@ -62,12 +87,16 @@ export const POST = withRouteHandler(
       )
 
       if (!userPermission || userPermission === 'read') {
-        throw new Error('Source folder not found or access denied')
+        throw new FolderDuplicationError(
+          'Source folder not found or access denied',
+          403,
+          'Access denied'
+        )
       }
 
       const targetWorkspaceId = workspaceId || sourceFolder.workspaceId
       if (targetWorkspaceId !== sourceFolder.workspaceId) {
-        throw new Error('Cross-workspace folder duplication is not supported')
+        throw new FolderDuplicationError('Cross-workspace folder duplication is not supported', 400)
       }
 
       const { newFolderId, folderMapping, workflowStats } = await db.transaction(async (tx) => {
@@ -76,49 +105,26 @@ export const POST = withRouteHandler(
         const targetParentId = parentId ?? sourceFolder.parentId
         await assertTargetParentFolderMutable(tx, targetParentId, targetWorkspaceId, sourceFolderId)
 
-        const folderParentCondition = targetParentId
-          ? eq(folderTable.parentId, targetParentId)
-          : isNull(folderTable.parentId)
-        const workflowParentCondition = targetParentId
-          ? eq(workflow.folderId, targetParentId)
-          : isNull(workflow.folderId)
-
-        const [[folderResult], [workflowResult]] = await Promise.all([
-          tx
-            .select({ minSortOrder: min(folderTable.sortOrder) })
-            .from(folderTable)
-            .where(
-              and(
-                eq(folderTable.workspaceId, targetWorkspaceId),
-                eq(folderTable.resourceType, 'workflow'),
-                folderParentCondition
-              )
-            ),
+        // Placement is the engine's rule (folders and workflows share one ordering space),
+        // so it is read from there rather than recomputed here.
+        const sortOrder = await nextFolderSortOrder(
+          FOLDER_RESOURCE_TYPE,
+          targetWorkspaceId,
+          targetParentId,
           tx
-            .select({ minSortOrder: min(workflow.sortOrder) })
-            .from(workflow)
-            .where(and(eq(workflow.workspaceId, targetWorkspaceId), workflowParentCondition)),
-        ])
-
-        const minSortOrder = [folderResult?.minSortOrder, workflowResult?.minSortOrder].reduce<
-          number | null
-        >((currentMin, candidate) => {
-          if (candidate == null) return currentMin
-          if (currentMin == null) return candidate
-          return Math.min(currentMin, candidate)
-        }, null)
-        const sortOrder = minSortOrder != null ? minSortOrder - 1 : 0
+        )
+
         const deduplicatedName = await deduplicateFolderName(
           tx,
           targetWorkspaceId,
           targetParentId,
           name,
-          'workflow'
+          FOLDER_RESOURCE_TYPE
         )
 
         await tx.insert(folderTable).values({
           id: newFolderId,
-          resourceType: 'workflow',
+          resourceType: FOLDER_RESOURCE_TYPE,
           userId: session.user.id,
           workspaceId: targetWorkspaceId,
           name: deduplicatedName,
@@ -183,41 +189,23 @@ export const POST = withRouteHandler(
       const duplicatedFolder = await db
         .select()
         .from(folderTable)
-        .where(and(eq(folderTable.id, newFolderId), eq(folderTable.resourceType, 'workflow')))
+        .where(
+          and(eq(folderTable.id, newFolderId), eq(folderTable.resourceType, FOLDER_RESOURCE_TYPE))
+        )
         .then((rows) => rows[0])
 
       return NextResponse.json({ folder: toFolderApi(duplicatedFolder) }, { status: 201 })
     } catch (error) {
-      if (error instanceof Error) {
-        if (error instanceof FolderLockedError) {
-          return NextResponse.json({ error: error.message }, { status: error.status })
-        }
-
-        if (error.message === 'Source folder not found') {
-          logger.warn(`[${requestId}] Source folder ${sourceFolderId} not found`)
-          return NextResponse.json({ error: 'Source folder not found' }, { status: 404 })
-        }
-
-        if (error.message === 'Source folder not found or access denied') {
-          logger.warn(
-            `[${requestId}] User ${session.user.id} denied access to source folder ${sourceFolderId}`
-          )
-          return NextResponse.json({ error: 'Access denied' }, { status: 403 })
-        }
-
-        if (error.message === 'Cross-workspace folder duplication is not supported') {
-          logger.warn(
-            `[${requestId}] User ${session.user.id} attempted cross-workspace folder duplication for ${sourceFolderId}`
-          )
-          return NextResponse.json({ error: error.message }, { status: 400 })
-        }
+      if (error instanceof FolderLockedError) {
+        return NextResponse.json({ error: error.message }, { status: error.status })
+      }
 
-        if (
-          error.message === 'Target parent folder not found' ||
-          error.message === 'Cannot duplicate folder into itself or one of its descendants'
-        ) {
-          return NextResponse.json({ error: error.message }, { status: 400 })
-        }
+      if (error instanceof FolderDuplicationError) {
+        logger.warn(`[${requestId}] Folder duplication rejected: ${error.message}`, {
+          sourceFolderId,
+          userId: session.user.id,
+        })
+        return NextResponse.json({ error: error.publicMessage }, { status: error.status })
       }
 
       const elapsed = Date.now() - startTime
@@ -250,14 +238,19 @@ async function assertTargetParentFolderMutable(
         archivedAt: folderTable.deletedAt,
       })
       .from(folderTable)
-      .where(and(eq(folderTable.id, currentFolderId), eq(folderTable.resourceType, 'workflow')))
+      .where(
+        and(eq(folderTable.id, currentFolderId), eq(folderTable.resourceType, FOLDER_RESOURCE_TYPE))
+      )
       .limit(1)
 
     if (!folder || folder.workspaceId !== targetWorkspaceId || folder.archivedAt) {
-      throw new Error('Target parent folder not found')
+      throw new FolderDuplicationError('Target parent folder not found', 400)
     }
     if (folder.id === sourceFolderId) {
-      throw new Error('Cannot duplicate folder into itself or one of its descendants')
+      throw new FolderDuplicationError(
+        'Cannot duplicate folder into itself or one of its descendants',
+        400
+      )
     }
     if (folder.locked) {
       throw new FolderLockedError()
@@ -284,7 +277,7 @@ async function duplicateFolderStructure(
       and(
         eq(folderTable.parentId, sourceFolderId),
         eq(folderTable.workspaceId, sourceWorkspaceId),
-        eq(folderTable.resourceType, 'workflow'),
+        eq(folderTable.resourceType, FOLDER_RESOURCE_TYPE),
         isNull(folderTable.deletedAt)
       )
     )
@@ -295,7 +288,7 @@ async function duplicateFolderStructure(
 
     await tx.insert(folderTable).values({
       id: newChildFolderId,
-      resourceType: 'workflow',
+      resourceType: FOLDER_RESOURCE_TYPE,
       userId,
       workspaceId: targetWorkspaceId,
       name: childFolder.name,

apps/sim/app/api/folders/[id]/route.ts

@@ -2,7 +2,7 @@ import { db } from '@sim/db'
 import { folder as folderTable } from '@sim/db/schema'
 import { createLogger } from '@sim/logger'
 import { assertFolderMutable, FolderLockedError } from '@sim/platform-authz/workflow'
-import { and, eq } from 'drizzle-orm'
+import { and, eq, isNull } from 'drizzle-orm'
 import { type NextRequest, NextResponse } from 'next/server'
 import { deleteFolderContract, updateFolderContract } from '@/lib/api/contracts'
 import { parseRequest } from '@/lib/api/server'
@@ -45,10 +45,22 @@ export const PUT = withRouteHandler(
       const { resourceType } = parsed.data.query
       const { name, locked, parentId, sortOrder } = parsed.data.body
 
+      /**
+       * `isNull(deletedAt)` is load-bearing, not tidiness: `getFolderLockStatus` skips
+       * archived rows, so an archived-but-locked folder reports unlocked. Without this
+       * filter, deleting a folder makes every locked subfolder under it freely renameable
+       * and reparentable by any write-level member.
+       */
       const existingFolder = await db
         .select()
         .from(folderTable)
-        .where(and(eq(folderTable.id, id), eq(folderTable.resourceType, resourceType)))
+        .where(
+          and(
+            eq(folderTable.id, id),
+            eq(folderTable.resourceType, resourceType),
+            isNull(folderTable.deletedAt)
+          )
+        )
         .then((rows) => rows[0])
 
       if (!existingFolder) {
@@ -143,6 +155,12 @@ export const DELETE = withRouteHandler(
       const { id } = parsed.data.params
       const { resourceType } = parsed.data.query
 
+      /**
+       * Deliberately NOT filtered on `deletedAt`, unlike PUT above: `deleteFolder` reuses an
+       * already-archived folder's own `deletedAt` so a cascade that failed partway can be
+       * retried onto the same snapshot. 404ing here would strand those stragglers. Delete is
+       * also idempotent, so re-reaching an archived folder grants nothing new.
+       */
       const existingFolder = await db
         .select()
         .from(folderTable)

apps/sim/app/api/v1/admin/workflows/import/route.ts

@@ -17,6 +17,12 @@
 import { db } from '@sim/db'
 import { workflow, workspace } from '@sim/db/schema'
 import { createLogger } from '@sim/logger'
+import {
+  assertFolderInWorkspace,
+  assertFolderMutable,
+  FolderLockedError,
+  FolderNotFoundError,
+} from '@sim/platform-authz/workflow'
 import { generateId } from '@sim/utils/id'
 import { and, eq, isNull } from 'drizzle-orm'
 import { NextResponse } from 'next/server'
@@ -63,6 +69,23 @@ export const POST = withRouteHandler(
         return notFoundResponse('Workspace')
       }
 
+      /**
+       * Migration 0272 dropped the FK on `workflow.folder_id`, so nothing but this check
+       * stands between the caller and a folder in another workspace — or one from another
+       * resource's tree. A workflow filed under an unreachable folder still executes and
+       * bills, escapes the folder delete cascade, and never counts toward
+       * `guardLastWorkflows`.
+       *
+       * Ownership before lock state, mirroring `v1/workflows/import`: `assertFolderMutable`
+       * walks the ancestor chain without filtering on workspace, so checking it first would
+       * let a caller distinguish a locked folder in someone else's workspace (423) from a
+       * nonexistent one (404).
+       */
+      if (folderId) {
+        await assertFolderInWorkspace(folderId, workspaceId)
+      }
+      await assertFolderMutable(folderId ?? null)
+
       const workflowContent =
         typeof body.workflow === 'string' ? body.workflow : JSON.stringify(body.workflow)
 
@@ -148,6 +171,12 @@ export const POST = withRouteHandler(
 
       return NextResponse.json(response)
     } catch (error) {
+      if (error instanceof FolderNotFoundError) {
+        return badRequestResponse(error.message)
+      }
+      if (error instanceof FolderLockedError) {
+        return NextResponse.json({ error: error.message }, { status: error.status })
+      }
       logger.error('Admin API: Failed to import workflow', { error })
       return internalErrorResponse('Failed to import workflow')
     }

apps/sim/app/workspace/[workspaceId]/components/folders/folder-row.tsx

@@ -9,6 +9,13 @@ import type { WorkflowFolder } from '@/stores/folders/types'
 const FOLDER_ICON = <Folder className='size-[14px]' />
 
 export interface FolderRowOptions {
+  /**
+   * Whether this folder is pinned. Folders pin under `resourceType: 'folder'`, a different
+   * pin namespace from the resource they contain — a page listing both resolves two
+   * `usePinnedIds` sets and passes the right one here. Drives the glyph only; the pin action
+   * lives on the row's context menu.
+   */
+  pinned?: boolean
   /**
    * Cells for the page's non-name columns, keyed by `ResourceColumn.id`. Folders have no
    * value for most resource-specific columns, so a page passes either a derived roll-up or
@@ -30,7 +37,7 @@ export interface FolderRowOptions {
  * field rebuilds one cell instead of every row's cells.
  */
 export function folderRow(folder: WorkflowFolder, options: FolderRowOptions = {}): ResourceRow {
-  const { cells, nameColumnId = 'name' } = options
+  const { pinned, cells, nameColumnId = 'name' } = options
 
   return {
     id: folderRowId(folder.id),
@@ -39,6 +46,7 @@ export function folderRow(folder: WorkflowFolder, options: FolderRowOptions = {}
       [nameColumnId]: {
         icon: FOLDER_ICON,
         label: folder.name,
+        pinned,
       },
     },
   }