fix(files): resolve v2 file paths only on the v2 surface, through the canonical resolver

apps/docs/content/docs/cli/files.mdx

@@ -102,7 +102,7 @@ sim files describe <fileId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `fileId` | Yes | File identifier, or the file’s VFS path: `files/<folder>/<name>`. |
+| `fileId` | Yes | File identifier, or the VFS path of a live file: `files/<folder>/<name>`. Pass the id when two files in a folder have names that display alike. |
 
 </CommandTable>
 
@@ -303,7 +303,7 @@ sim files rename <fileId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `fileId` | Yes | File identifier, or the file’s VFS path: `files/<folder>/<name>`. |
+| `fileId` | Yes | File identifier, or the VFS path of a live file: `files/<folder>/<name>`. Pass the id when two files in a folder have names that display alike. |
 
 </CommandTable>
 
@@ -613,7 +613,7 @@ sim files delete <fileId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `fileId` | Yes | File identifier, or the file’s VFS path: `files/<folder>/<name>`. |
+| `fileId` | Yes | File identifier, or the VFS path of a live file: `files/<folder>/<name>`. Pass the id when two files in a folder have names that display alike. |
 
 </CommandTable>
 

apps/docs/content/docs/cli/reference.mdx

@@ -1181,7 +1181,7 @@ sim files delete <fileId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `fileId` | Yes | File identifier, or the file’s VFS path: `files/<folder>/<name>`. |
+| `fileId` | Yes | File identifier, or the VFS path of a live file: `files/<folder>/<name>`. Pass the id when two files in a folder have names that display alike. |
 
 </CommandTable>
 
@@ -1426,7 +1426,7 @@ sim files describe <fileId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `fileId` | Yes | File identifier, or the file’s VFS path: `files/<folder>/<name>`. |
+| `fileId` | Yes | File identifier, or the VFS path of a live file: `files/<folder>/<name>`. Pass the id when two files in a folder have names that display alike. |
 
 </CommandTable>
 
@@ -1591,7 +1591,7 @@ sim files rename <fileId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `fileId` | Yes | File identifier, or the file’s VFS path: `files/<folder>/<name>`. |
+| `fileId` | Yes | File identifier, or the VFS path of a live file: `files/<folder>/<name>`. Pass the id when two files in a folder have names that display alike. |
 
 </CommandTable>
 

apps/docs/openapi-v2-files-audit.json

@@ -2151,12 +2151,12 @@
             "name": "fileId",
             "in": "path",
             "required": true,
-            "description": "File identifier, or the file’s VFS path: `files/<folder>/<name>`.",
+            "description": "File identifier, or the VFS path of a live file: `files/<folder>/<name>`. Pass the id when two files in a folder have names that display alike.",
             "schema": {
               "type": "string",
               "minLength": 1,
               "maxLength": 4096,
-              "description": "File identifier, or the file’s VFS path: `files/<folder>/<name>`."
+              "description": "File identifier, or the VFS path of a live file: `files/<folder>/<name>`. Pass the id when two files in a folder have names that display alike."
             }
           },
           {
@@ -2237,12 +2237,12 @@
             "name": "fileId",
             "in": "path",
             "required": true,
-            "description": "File identifier, or the file’s VFS path: `files/<folder>/<name>`.",
+            "description": "File identifier, or the VFS path of a live file: `files/<folder>/<name>`. Pass the id when two files in a folder have names that display alike.",
             "schema": {
               "type": "string",
               "minLength": 1,
               "maxLength": 4096,
-              "description": "File identifier, or the file’s VFS path: `files/<folder>/<name>`."
+              "description": "File identifier, or the VFS path of a live file: `files/<folder>/<name>`. Pass the id when two files in a folder have names that display alike."
             }
           }
         ],
@@ -2487,12 +2487,12 @@
             "name": "fileId",
             "in": "path",
             "required": true,
-            "description": "File identifier, or the file’s VFS path: `files/<folder>/<name>`.",
+            "description": "File identifier, or the VFS path of a live file: `files/<folder>/<name>`. Pass the id when two files in a folder have names that display alike.",
             "schema": {
               "type": "string",
               "minLength": 1,
               "maxLength": 4096,
-              "description": "File identifier, or the file’s VFS path: `files/<folder>/<name>`."
+              "description": "File identifier, or the VFS path of a live file: `files/<folder>/<name>`. Pass the id when two files in a folder have names that display alike."
             }
           },
           {

apps/sim/app/api/v2/files/[fileId]/metadata/route.test.ts

@@ -113,7 +113,12 @@ describe('GET /api/v2/files/[fileId]/metadata', () => {
     expect((await response.json()).error.code).toBe('NOT_FOUND')
     expect(readMetadata).toHaveBeenCalledWith(
       expect.objectContaining({
-        input: { fileId: FILE_ID, assertedWorkspaceId: WORKSPACE_ID, includeDeleted: false },
+        input: {
+          fileId: FILE_ID,
+          acceptVfsPath: true,
+          assertedWorkspaceId: WORKSPACE_ID,
+          includeDeleted: false,
+        },
       })
     )
   })
@@ -127,7 +132,12 @@ describe('GET /api/v2/files/[fileId]/metadata', () => {
     expect((await response.json()).error.code).toBe('NOT_FOUND')
     expect(readMetadata).toHaveBeenCalledWith(
       expect.objectContaining({
-        input: { fileId: FILE_ID, assertedWorkspaceId: WORKSPACE_ID, includeDeleted: false },
+        input: {
+          fileId: FILE_ID,
+          acceptVfsPath: true,
+          assertedWorkspaceId: WORKSPACE_ID,
+          includeDeleted: false,
+        },
       })
     )
   })
@@ -159,7 +169,12 @@ describe('GET /api/v2/files/[fileId]/metadata', () => {
     expect(readMetadata).toHaveBeenCalledWith(
       expect.objectContaining({
         principal: auth.principal,
-        input: { fileId: FILE_ID, assertedWorkspaceId: WORKSPACE_ID, includeDeleted: true },
+        input: {
+          fileId: FILE_ID,
+          acceptVfsPath: true,
+          assertedWorkspaceId: WORKSPACE_ID,
+          includeDeleted: true,
+        },
       })
     )
   })

apps/sim/app/api/v2/files/[fileId]/metadata/route.ts

@@ -26,6 +26,7 @@ export const GET = defineV2JsonRoute({
   errorPolicy: v2FileErrorPolicies.concealResourceAuthorization,
   mapInput: ({ params, query }) => ({
     fileId: params.fileId,
+    acceptVfsPath: true,
     assertedWorkspaceId: query.workspaceId,
     includeDeleted: query.scope === 'archived',
   }),

apps/sim/app/api/v2/files/[fileId]/route.ts

@@ -63,6 +63,7 @@ export const PATCH = defineV2JsonRoute({
   errorPolicy: v2FileErrorPolicies.concealResourceAuthorization,
   mapInput: ({ params, body }) => ({
     fileId: params.fileId,
+    acceptVfsPath: true,
     assertedWorkspaceId: body.workspaceId,
     name: body.name,
   }),
@@ -85,6 +86,7 @@ export const DELETE = defineV2JsonRoute({
   errorPolicy: v2FileErrorPolicies.concealResourceAuthorization,
   mapInput: ({ params, query }) => ({
     fileId: params.fileId,
+    acceptVfsPath: true,
     assertedWorkspaceId: query.workspaceId,
   }),
   useCase: deleteWorkspaceFileOperation,

apps/sim/lib/api/contracts/v2/files.ts

@@ -311,7 +311,9 @@ const v2FileIdOrPathParamsSchema = z.object({
       (value) => isWorkspaceFileVfsPath(value) || workspaceFileIdSchema.safeParse(value).success,
       'Invalid file id or path: pass a file id or its `files/<folder>/<name>` VFS path'
     )
-    .describe('File identifier, or the file’s VFS path: `files/<folder>/<name>`.'),
+    .describe(
+      'File identifier, or the VFS path of a live file: `files/<folder>/<name>`. Pass the id when two files in a folder have names that display alike.'
+    ),
 })
 
 export const v2CreateFileBodySchema = z

apps/sim/lib/uploads/contexts/workspace/file-manager.ts

@@ -2342,40 +2342,6 @@ async function getWorkspaceFileByExactReference(
   return folderId ? getWorkspaceFileByName(workspaceId, segments.at(-1) ?? '', { folderId }) : null
 }
 
-/**
- * The live workspace file whose canonical `files/…` path — as listings print it — is `vfsPath`,
- * or null. Unlike {@link findWorkspaceFileRecord} there is no virtual `/content` or `/meta.json`
- * suffix and no leaf-name fallback, so a mutation addressed by path lands only on the file it
- * names. Two names that display alike are ambiguous and refused. Throws `VfsPathError` if
- * malformed.
- */
-export async function getWorkspaceFileByVfsPath(
-  workspaceId: string,
-  vfsPath: string
-): Promise<WorkspaceFileRecord | null> {
-  const segments = decodeVfsReferenceSegments(vfsPath.slice('files/'.length))
-  const leaf = segments.at(-1)
-  if (leaf === undefined) return null
-  const pathKey = segments.map(normalizeVfsSegment).join('/')
-  const candidates = await listWorkspaceFileCandidates(workspaceId, {
-    ids: [],
-    leafNames: [normalizeDisplaySegment(leaf)],
-  })
-  const matches = candidates.filter(
-    (file) =>
-      canonicalWorkspaceFilePath({ folderPath: file.folderPath, name: file.name }).slice(
-        'files/'.length
-      ) === pathKey
-  )
-  if (matches.length > 1) {
-    throw new OrchestrationError(
-      'validation',
-      `"${vfsPath}" names more than one file whose names display alike; pass the file id instead`
-    )
-  }
-  return matches[0] ?? null
-}
-
 /**
  * Resolve a workspace file record from either its id or a VFS/name reference.
  *

apps/sim/lib/vfs/path.ts

@@ -10,9 +10,12 @@ export class VfsPathError extends Error {
   }
 }
 
-/** A `files/…` workspace-file VFS path. File ids are drawn from `[A-Za-z0-9_-]`, so no id is one. */
+/**
+ * A `files/…` workspace-file VFS path naming something under the prefix. File ids are drawn from
+ * `[A-Za-z0-9_-]`, so no id is one.
+ */
 export function isWorkspaceFileVfsPath(reference: string): boolean {
-  return reference.startsWith('files/')
+  return reference.startsWith('files/') && reference.length > 'files/'.length
 }
 
 /**