@@ -243,6 +243,14 @@ jobs:
         working-directory: packages/db
         run: bun run db:migrate
 
+      - name: Build native isolate addon for Project file rendering
+        if: matrix.group == 'project-files'
+        working-directory: apps/sim
+        run: |
+          addon_dir="$(node -p 'require("node:path").dirname(require.resolve("isolated-vm/package.json", { paths: ["./apps/sim"] }))')"
+          cd "$addon_dir"
+          bun run install
+
       # No step timeout: the job's bound covers a hang without cutting a slow but healthy suite
       # short of writing its report.
       - name: Run end-to-end suites
 
@@ -21,8 +21,8 @@ import {
 import { PayloadSizeLimitError, readStreamToBufferWithLimit } from '@/lib/core/utils/stream-limits'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { workspaceFileVfsPath } from '@/lib/uploads/contexts/workspace'
+import { encodeFilenameForHeader } from '@/lib/uploads/server/delivery'
 import { internalFileErrorPolicies } from '@/lib/workspace-files/api'
-import { encodeFilenameForHeader } from '@/app/api/files/utils'
 
 export const dynamic = 'force-dynamic'
 
 
@@ -13,6 +13,7 @@ import { captureServerEvent } from '@/lib/posthog/server'
 import type { StorageContext } from '@/lib/uploads/config'
 import { getServeStoragePrefix } from '@/lib/uploads/config'
 import { downloadFile } from '@/lib/uploads/core/storage-service'
+import { encodeFilenameForHeader } from '@/lib/uploads/server/delivery'
 import { extractEmbeddedFileRefs } from '@/lib/uploads/server/embedded-image-refs'
 import {
   createMarkdownExport,
@@ -27,7 +28,6 @@ import { getWorkspaceFileSize } from '@/lib/uploads/shared/types'
 import { storedFileId } from '@/lib/uploads/utils/embedded-image-ref'
 import { formatFileSize } from '@/lib/uploads/utils/file'
 import { verifyFileAccess } from '@/app/api/files/authorization'
-import { encodeFilenameForHeader } from '@/app/api/files/utils'
 
 const logger = createLogger('FilesExportAPI')
 
 
@@ -13,7 +13,12 @@ import {
   createSessionPrincipal,
 } from '@sim/testing/factories/principal.factory'
 import { createRouteContext } from '@sim/testing/helpers/http'
+import { fileReadReceiptMock } from '@sim/testing/mocks/file-read-receipt.mock'
 import { fileUtilsMock, fileUtilsMockFns } from '@sim/testing/mocks/file-utils.mock'
+import {
+  fileUtilsServerMock,
+  fileUtilsServerMockFns,
+} from '@sim/testing/mocks/file-utils-server.mock'
 import {
   filesAuthorizationMock,
   filesAuthorizationMockFns,
@@ -36,6 +41,8 @@ const {
   mockReadFile,
   mockAuthenticateWorkspaceFile,
   mockReadWorkspaceFileContentByKey,
+  mockReadWorkspaceFileRecordByKey,
+  mockAuthorizeWorkspaceFileRecordByKey,
   mockResolveServableDocBytes,
   mockGetContentType,
   mockFindLocalFile,
@@ -57,6 +64,8 @@ const {
     mockReadFile: vi.fn(),
     mockAuthenticateWorkspaceFile: vi.fn(),
     mockReadWorkspaceFileContentByKey: vi.fn(),
+    mockReadWorkspaceFileRecordByKey: vi.fn(),
+    mockAuthorizeWorkspaceFileRecordByKey: vi.fn(async () => undefined),
     mockResolveServableDocBytes: vi.fn(),
     mockGetContentType: vi.fn(),
     mockFindLocalFile: vi.fn(),
@@ -86,6 +95,9 @@ vi.mock('@/lib/uploads/core/storage-service', () => storageServiceMock)
 
 vi.mock('@/lib/uploads/utils/file', () => fileUtilsMock)
 
+vi.mock('@/lib/uploads/utils/file.server', () => fileUtilsServerMock)
+vi.mock('@/lib/workspace-files/read-receipt', () => fileReadReceiptMock)
+
 vi.mock('@/lib/uploads/server/metadata', () => uploadsMetadataMock)
 
 vi.mock('@/lib/uploads/setup.server', () => ({}))
@@ -106,6 +118,10 @@ vi.mock('@/lib/workspace-files/api', () => ({
 
 vi.mock('@/lib/workspace-files/application/read-workspace-file-content-by-key', () => ({
   readWorkspaceFileContentByKey: { execute: mockReadWorkspaceFileContentByKey },
+  readWorkspaceFileRecordByKey: {
+    execute: mockReadWorkspaceFileRecordByKey,
+    authorize: mockAuthorizeWorkspaceFileRecordByKey,
+  },
 }))
 
 vi.mock('@/lib/uploads/documents/compile', () => ({
@@ -161,6 +177,17 @@ describe('File Serve API Route', () => {
       },
       content: Buffer.from('generated source'),
     })
+    mockReadWorkspaceFileRecordByKey.mockResolvedValue({
+      file: {
+        id: 'file-1',
+        workspaceId: 'test-workspace-id',
+        name: 'report.pdf',
+        key: 'workspace/test-workspace-id/report.pdf',
+        type: 'text/x-pdflibjs',
+        size: 16,
+        contentUpdatedAt: new Date('2026-09-06'),
+      },
+    })
     mockResolveServableDocBytes.mockImplementation(
       async ({ rawBuffer, fileName }: { rawBuffer: Buffer; fileName: string }) => ({
         buffer: rawBuffer,
@@ -173,24 +200,23 @@ describe('File Serve API Route', () => {
       mockReadFile(filePath)
     )
     mockCreateFileResponse.mockImplementation(
-      (file: { buffer: Buffer; contentType: string; filename: string }) => {
+      (file: { buffer: Buffer; contentType: string; filename: string; cacheControl?: string }) => {
         return new Response(file.buffer, {
           status: 200,
           headers: {
             'Content-Type': file.contentType,
+            ...(file.cacheControl ? { 'Cache-Control': file.cacheControl } : {}),
             'Content-Disposition': `inline; filename="${file.filename}"`,
           },
         })
       }
     )
-    // Delegates so the existing assertions on the response payload — including its
-    // Cache-Control — read the same call list whichever helper the route reached for.
     mockCreateConditionalFileResponse.mockImplementation((file: unknown) =>
       mockCreateFileResponse(file)
     )
-    mockFileErrorResponse.mockImplementation((error: Error) => {
+    mockFileErrorResponse.mockImplementation((error: Error, status = 500) => {
       return new Response(JSON.stringify({ error: error.name, message: error.message }), {
-        status: error.name === 'FileNotFoundError' ? 404 : 500,
+        status: error.name === 'FileNotFoundError' ? 404 : status,
         headers: { 'Content-Type': 'application/json' },
       })
     })
@@ -284,9 +310,9 @@ describe('File Serve API Route', () => {
     // The real createFileErrorResponse owns the status mapping; mirror it here so the
     // route's own error path is what decides, not the mock's default 500.
     mockFileErrorResponse.mockImplementation(
-      (error: Error) =>
+      (error: Error, status = 500) =>
         new Response(JSON.stringify({ error: error.name }), {
-          status: error.name === 'PayloadSizeLimitError' ? 413 : 500,
+          status: error.name === 'PayloadSizeLimitError' ? 413 : status,
         })
     )
 
@@ -312,32 +338,48 @@ describe('File Serve API Route', () => {
       },
     })
 
-    async function serveVersionedDoc(dependsOnReferencedFiles: boolean) {
+    async function serveVersionedDoc(
+      dependsOnReferencedFiles: boolean,
+      method: 'GET' | 'HEAD' = 'GET'
+    ) {
       mockResolveStoredFileContext.mockResolvedValue('workspace')
       mockParseWorkspaceFileKey.mockReturnValue('test-workspace-id')
       mockAuthenticateWorkspaceFile.mockResolvedValue(principal)
-      mockResolveServableDocBytes.mockResolvedValue({
+      fileUtilsServerMockFns.mockDownloadServableFileFromStorage.mockResolvedValue({
         buffer: Buffer.from('compiled'),
         contentType: 'application/pdf',
         ...(dependsOnReferencedFiles ? { dependsOnReferencedFiles: true } : {}),
       })
 
       const req = createMockRequest({
+        method,
         url: 'http://localhost:3000/api/files/serve/workspace/test-workspace-id/report.pdf?v=1756684800000',
       })
-      await GET(req, createRouteContext({ path: ['workspace', 'test-workspace-id', 'report.pdf'] }))
-      return mockCreateFileResponse.mock.calls.at(-1)?.[0]
+      const response = await GET(
+        req,
+        createRouteContext({ path: ['workspace', 'test-workspace-id', 'report.pdf'] })
+      )
+      expect(response.status).toBe(200)
+      return response
     }
 
+    it('authorizes HEAD without compiling a representation or inventing its length', async () => {
+      const response = await serveVersionedDoc(true, 'HEAD')
+      expect(await response.text()).toBe('')
+      expect(response.headers.get('Content-Length')).toBeNull()
+      expect(response.headers.get('Cache-Control')).toBe('private, no-store')
+      expect(mockReadWorkspaceFileRecordByKey).toHaveBeenCalled()
+      expect(fileUtilsServerMockFns.mockDownloadServableFileFromStorage).not.toHaveBeenCalled()
+    })
+
     it('caches a versioned document immutably when its bytes derive from the stored source alone', async () => {
-      expect(await serveVersionedDoc(false)).toEqual(
-        expect.objectContaining({ cacheControl: 'private, max-age=31536000, immutable' })
-      )
+      const response = await serveVersionedDoc(false)
+      expect(response.headers.get('Cache-Control')).toBe('private, max-age=31536000, immutable')
     })
 
-    it('attaches a validator to a revalidated response so the next check can be answered 304', async () => {
-      await serveVersionedDoc(true)
-      expect(mockCreateConditionalFileResponse).toHaveBeenCalled()
+    it('requires revalidation for a versioned document with referenced inputs', async () => {
+      const response = await serveVersionedDoc(true)
+      expect(response.headers.get('Cache-Control')).toBe('private, no-cache, must-revalidate')
     })
   })
 })