fix(folders): reach nested stragglers on retry and confine locking to workflows

Two follow-ons from the cascade reordering.

The delete subtree walk still collected active folders only. Since the
cascade now stamps folders before children, a failure during the child pass
leaves intermediate folders archived, and an active-only walk drops them —
so resources still live underneath were never reached on the retry and
stayed outside every later timestamp-matched restore. The walk now admits
folders that are active OR already carry this cascade's own timestamp, which
reaches the stragglers while still excluding folders archived independently
under a different stamp.

Locking was only half-confined to workflows. `assertFolderMutable` was gated
but the admin check and the `locked` write were not, so an admin could
persist `locked` on a knowledge-base or table folder — a column nothing reads
for those types — and a non-admin update that merely mentioned `locked` was
rejected on a type where locking does not exist. Locking is now a declared
capability on the resource config; the routes reject the field outright for
types that lack it, and the engine refuses to write it as a backstop for the
copilot tools that call it directly.

Author: waleedlatif1

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

@@ -244,6 +244,26 @@ describe('Individual Folder API Route', () => {
       expect(data).toHaveProperty('folder')
     })
 
+    it('rejects a locked write on a resource type that has no lock semantics', async () => {
+      mockAuthenticatedUser()
+      queueFolderLookup()
+
+      const req = createMockRequest(
+        'PUT',
+        { locked: true },
+        {},
+        'http://localhost:3000/api/folders/folder-1?resourceType=knowledge_base'
+      )
+      const params = Promise.resolve({ id: 'folder-1' })
+
+      const response = await PUT(req, { params })
+
+      expect(response.status).toBe(400)
+      const data = await response.json()
+      expect(data.error).toBe('Folder locking is only supported for workflow folders')
+      expect(mockUpdateFolder).not.toHaveBeenCalled()
+    })
+
     it('should return 400 when trying to set folder as its own parent', async () => {
       mockAuthenticatedUser()
 

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

@@ -9,6 +9,7 @@ import { parseRequest } from '@/lib/api/server'
 import { getSession } from '@/lib/auth'
 import { HttpError } from '@/lib/core/utils/http-error'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { folderResourceConfig } from '@/lib/folders/config'
 import { deleteFolder, updateFolder } from '@/lib/folders/lifecycle'
 import { toFolderApi } from '@/lib/folders/queries'
 import { folderMutationStatus } from '@/lib/folders/status'
@@ -68,15 +69,27 @@ export const PUT = withRouteHandler(
         )
       }
 
-      if (locked !== undefined && workspacePermission !== 'admin') {
+      // Locking is workflow-only. Reject the field outright for the other types rather than
+      // dropping it silently, and keep the admin gate and the lock checks behind the same
+      // capability so a non-workflow folder can neither be 403'd by a field that has no
+      // meaning for it nor persist a `locked` value nothing will ever read.
+      const supportsLocking = Boolean(folderResourceConfig(resourceType).supportsLocking)
+
+      if (locked !== undefined && !supportsLocking) {
         return NextResponse.json(
-          { error: 'Admin access required to lock folders' },
-          { status: 403 }
+          { error: 'Folder locking is only supported for workflow folders' },
+          { status: 400 }
         )
       }
 
-      // Folder locking is a workflow-only feature; other resource types leave `locked` false.
-      if (resourceType === 'workflow') {
+      if (supportsLocking) {
+        if (locked !== undefined && workspacePermission !== 'admin') {
+          return NextResponse.json(
+            { error: 'Admin access required to lock folders' },
+            { status: 403 }
+          )
+        }
+
         const hasNonLockUpdate = Object.keys(parsed.data.body).some((key) => key !== 'locked')
         if (hasNonLockUpdate) {
           await assertFolderMutable(id)

apps/sim/app/api/folders/reorder/route.ts

@@ -10,6 +10,7 @@ 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 { folderResourceConfig } from '@/lib/folders/config'
 import { getUserEntityPermissions } from '@/lib/workspaces/permissions/utils'
 
 const logger = createLogger('FolderReorderAPI')
@@ -116,7 +117,7 @@ export const PUT = withRouteHandler(async (req: NextRequest) => {
     }
 
     // Folder locking is a workflow-only feature; other resource types leave `locked` false.
-    if (resourceType === 'workflow') {
+    if (folderResourceConfig(resourceType).supportsLocking) {
       for (const update of validUpdates) {
         await assertFolderMutable(update.id)
         if (update.parentId !== undefined) {

apps/sim/app/api/folders/route.ts

@@ -5,6 +5,7 @@ import { createFolderContract, listFoldersContract } from '@/lib/api/contracts'
 import { parseRequest } from '@/lib/api/server'
 import { getSession } from '@/lib/auth'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { folderResourceConfig } from '@/lib/folders/config'
 import { createFolder } from '@/lib/folders/lifecycle'
 import { listFoldersForWorkspace, toFolderApi } from '@/lib/folders/queries'
 import { folderMutationStatus } from '@/lib/folders/status'
@@ -78,7 +79,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
     }
 
     // Folder locking is a workflow-only feature; other resource types leave `locked` false.
-    if (resourceType === 'workflow') {
+    if (folderResourceConfig(resourceType).supportsLocking) {
       await assertFolderMutable(parentId ?? null)
     }
 

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

@@ -4,8 +4,8 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import {
   archiveFolderCascade,
-  collectActiveSubtreeIds,
   collectArchivedSubtreeIds,
+  collectCascadeSubtreeIds,
   type DbOrTx,
   restoreFolderCascade,
   restoreFolderRows,
@@ -101,8 +101,8 @@ function hasCondition(
 const TIMESTAMP = new Date('2026-01-01T00:00:00.000Z')
 const NOW = new Date('2026-02-02T00:00:00.000Z')
 
-describe('collectActiveSubtreeIds', () => {
-  it('returns the folder plus every active descendant', async () => {
+describe('collectCascadeSubtreeIds', () => {
+  it('returns the folder plus every descendant in the cascade', async () => {
     const { tx, selectCalls } = makeTx({
       selects: [
         [
@@ -114,17 +114,41 @@ describe('collectActiveSubtreeIds', () => {
       ],
     })
 
-    const ids = await collectActiveSubtreeIds(tx, 'ws-1', 'table', 'root')
+    const ids = await collectCascadeSubtreeIds(tx, 'ws-1', 'table', 'root', TIMESTAMP)
 
     expect(ids).toEqual(['root', 'child', 'grandchild'])
     expect(selectCalls).toHaveLength(1)
-    expect(hasCondition(selectCalls[0].where, (node) => node.type === 'isNull')).toBe(true)
+  })
+
+  it('admits folders already stamped by this cascade so a retry reaches nested stragglers', async () => {
+    // The cascade stamps folders before children, so a failure during the child pass leaves
+    // intermediate folders archived. An active-only walk would drop `child` here and never
+    // reach the resources still live under it.
+    const { tx, selectCalls } = makeTx({
+      selects: [
+        [
+          { id: 'root', parentId: null },
+          { id: 'child', parentId: 'root' },
+          { id: 'grandchild', parentId: 'child' },
+        ],
+      ],
+    })
+
+    const ids = await collectCascadeSubtreeIds(tx, 'ws-1', 'table', 'root', TIMESTAMP)
+
+    expect(ids).toEqual(['root', 'child', 'grandchild'])
+    // Either still active, or carrying this cascade's own stamp — never another snapshot's.
+    const clause = flattenConditions(selectCalls[0].where).find((node) => node.type === 'or')
+    expect(clause).toBeDefined()
+    const branches = (clause?.conditions ?? []) as Array<Record<string, unknown>>
+    expect(branches.some((node) => node.type === 'isNull')).toBe(true)
+    expect(branches.some((node) => node.right === TIMESTAMP)).toBe(true)
   })
 
   it('scopes the walk to the workspace and resourceType', async () => {
     const { tx, selectCalls } = makeTx({ selects: [[]] })
 
-    await collectActiveSubtreeIds(tx, 'ws-1', 'knowledge_base', 'root')
+    await collectCascadeSubtreeIds(tx, 'ws-1', 'knowledge_base', 'root', TIMESTAMP)
 
     expect(hasCondition(selectCalls[0].where, (node) => node.right === 'knowledge_base')).toBe(true)
     expect(hasCondition(selectCalls[0].where, (node) => node.right === 'ws-1')).toBe(true)
@@ -395,6 +419,15 @@ describe('FOLDER_RESOURCES', () => {
     }
   })
 
+  it('grants lock semantics to workflows only', () => {
+    // `folder.locked` predates the generic table and is deliberately not extended. Anything
+    // that flips a second resource to lockable has to add the UI and authz to match.
+    const lockable = Object.values(FOLDER_RESOURCES)
+      .filter((config) => config.supportsLocking)
+      .map((config) => config.resourceType)
+    expect(lockable).toEqual(['workflow'])
+  })
+
   it('guards the delete of resources that gate their own deletion', () => {
     // Tables refuse deletion while delete-locked; deleting the folder around one must not
     // become a way around that control.

apps/sim/lib/folders/cascade.ts

@@ -1,6 +1,6 @@
 import type { db } from '@sim/db'
 import { folder as folderTable } from '@sim/db/schema'
-import { and, eq, inArray, isNull, type SQL } from 'drizzle-orm'
+import { and, eq, inArray, isNull, or, type SQL } from 'drizzle-orm'
 import type { FolderCascadeCountsApi, FolderResourceType } from '@/lib/api/contracts/folders'
 import type { FolderResourceConfig } from '@/lib/folders/config'
 import { collectDescendantFolderIds } from '@/lib/folders/subtree'
@@ -16,28 +16,36 @@ export interface FolderCascadeCounts {
 }
 
 /**
- * Resolves the folder plus every *active* descendant, in one query. Used by delete: an
- * archived descendant was archived independently and keeps its own timestamp, so it must
- * not be swept into this cascade.
+ * Resolves the folder plus every descendant that belongs to this delete cascade, in one
+ * query: folders still active, OR already stamped with this cascade's own `timestamp`.
+ *
+ * Both halves are load-bearing. Excluding other archived folders is what keeps a descendant
+ * archived independently — with its own timestamp — from being swept into this snapshot.
+ * Including folders stamped with *this* timestamp is what makes a retry work: the cascade
+ * stamps folders before children, so a failure partway through the child pass leaves nested
+ * subfolders already archived. An active-only walk would drop those intermediate folders and
+ * never reach the still-active resources beneath them, leaving them outside every future
+ * timestamp-matched restore.
  */
-export async function collectActiveSubtreeIds(
+export async function collectCascadeSubtreeIds(
   tx: DbOrTx,
   workspaceId: string,
   resourceType: FolderResourceType,
-  folderId: string
+  folderId: string,
+  timestamp: Date
 ): Promise<string[]> {
-  const activeFolders = await tx
+  const cascadeFolders = await tx
     .select({ id: folderTable.id, parentId: folderTable.parentId })
     .from(folderTable)
     .where(
       and(
         eq(folderTable.workspaceId, workspaceId),
         eq(folderTable.resourceType, resourceType),
-        isNull(folderTable.deletedAt)
+        or(isNull(folderTable.deletedAt), eq(folderTable.deletedAt, timestamp))
       )
     )
 
-  return [folderId, ...collectDescendantFolderIds(activeFolders, folderId)]
+  return [folderId, ...collectDescendantFolderIds(cascadeFolders, folderId)]
 }
 
 /**

apps/sim/lib/folders/config.ts

@@ -89,6 +89,16 @@ export interface FolderResourceConfig {
    * hand the cascade a `Record<string, unknown>` literal.
    */
   buildSoftDeleteSet: (timestamp: Date | null, now: Date) => Record<string, unknown>
+  /**
+   * Whether folders of this type participate in the folder-locking feature.
+   *
+   * Only workflow folders do. `folder.locked` exists because workflow-folder locking shipped
+   * before the generic table; it is deliberately not extended to the other resource types.
+   * Declared here rather than checked as `resourceType === 'workflow'` at each call site, so
+   * every surface that touches locking asks the same question and a future lockable resource
+   * is one flag rather than a hunt through routes.
+   */
+  supportsLocking?: boolean
   /** Narrows which rows of `table` participate in folder membership at all. */
   scope?: SQL
   /**
@@ -404,6 +414,7 @@ export const FOLDER_RESOURCES: Record<FolderResourceType, FolderResourceConfig>
           >,
       },
     ],
+    supportsLocking: true,
     archiveChildren: archiveWorkflowChildren,
     guardDelete: guardLastWorkflows,
   },

apps/sim/lib/folders/lifecycle.ts

@@ -8,8 +8,8 @@ import { and, eq, isNull, min } from 'drizzle-orm'
 import type { FolderCascadeCountsApi, FolderResourceType } from '@/lib/api/contracts/folders'
 import {
   archiveFolderCascade,
-  collectActiveSubtreeIds,
   collectArchivedSubtreeIds,
+  collectCascadeSubtreeIds,
   restoreFolderChildren,
   restoreFolderRows,
   toCascadeCounts,
@@ -235,6 +235,8 @@ export async function createFolder(params: CreateFolderParams): Promise<FolderMu
 }
 
 export async function updateFolder(params: UpdateFolderParams): Promise<FolderMutationResult> {
+  const config = folderResourceConfig(params.resourceType)
+
   try {
     if (params.parentId && params.parentId === params.folderId) {
       return { success: false, error: 'Folder cannot be its own parent', errorCode: 'validation' }
@@ -266,7 +268,9 @@ export async function updateFolder(params: UpdateFolderParams): Promise<FolderMu
     // let `color`/`isExpanded` survive an earlier cutover after the create path dropped them.
     const updates: Partial<typeof folderTable.$inferInsert> = { updatedAt: new Date() }
     if (params.name !== undefined) updates.name = params.name.trim()
-    if (params.locked !== undefined) updates.locked = params.locked
+    // Backstop for the route's rejection: the engine is also reachable from the copilot
+    // tools, and a `locked` value on a type that has no lock semantics must never persist.
+    if (params.locked !== undefined && config.supportsLocking) updates.locked = params.locked
     if (params.parentId !== undefined) updates.parentId = params.parentId || null
     if (params.sortOrder !== undefined) updates.sortOrder = params.sortOrder
 
@@ -332,20 +336,24 @@ export async function deleteFolder(params: DeleteFolderParams): Promise<DeleteFo
     return { success: false, error: 'Folder not found', errorCode: 'not_found' }
   }
 
-  const folderIds = await collectActiveSubtreeIds(db, workspaceId, resourceType, folderId)
+  // Resolve the timestamp before the subtree, because the subtree walk needs it: on a retry
+  // it is what distinguishes folders this cascade already stamped from folders archived
+  // independently.
+  const timestamp = existing.deletedAt ?? new Date()
+  const folderIds = await collectCascadeSubtreeIds(
+    db,
+    workspaceId,
+    resourceType,
+    folderId,
+    timestamp
+  )
 
   const rejection = await config.guardDelete?.({ workspaceId, folderIds })
   if (rejection) {
     return { success: false, error: rejection.error, errorCode: rejection.errorCode }
   }
 
-  const counts = await archiveFolderCascade(
-    db,
-    config,
-    workspaceId,
-    folderIds,
-    existing.deletedAt ?? new Date()
-  )
+  const counts = await archiveFolderCascade(db, config, workspaceId, folderIds, timestamp)
 
   logger.info('Deleted folder and all contents', { folderId, resourceType, counts })