fix(files): serve rendered documents and stream workspace archives (#5995)

* fix(files): serve rendered documents instead of generator source

Generated docs (docx/pptx/pdf/xlsx) store their generation source as the primary
file; the rendered binary lives in a separate content-addressed artifact store.
resolveServableDocBytes is the chokepoint that swaps one for the other, and the
serve route, single-file download and ~50 tool routes all go through it.

Archive compression and the public v1 download read raw bytes instead, so a
generated document arrived as source text under a .docx name and Word reported
it as corrupt. Both now resolve through the servable reader.

Adds fetchServableWorkspaceFileBuffer beside the raw reader so the record to
UserFile mapping lives in one place, preserving storageContext; the raw reader's
doc comment now says it returns generation source, so the next call site has to
choose deliberately. v1 also has to send the resolved content type rather than
the record's source MIME, and returns a retryable 409 rather than a 500 when an
artifact is still compiling. docNotReadyMessage centralizes the 409 copy, and
isRenderableDocumentName is shared so the read path and its callers agree on
which extensions can expand.

* perf(files): stream workspace archives instead of buffering them

The bulk download route materialized every selected file before writing a byte,
so peak memory tracked the size of the selection. Ordinary files are now
appended as lazy streams: each opens its storage read only when the archiver
reaches it, so one entry is resident at a time rather than the whole archive.

Generated documents still resolve to buffers first. They are the only entries
whose bytes decide anything, and every status this route returns comes from
them — once the first byte is written the status code is committed, so those
decisions have to happen before the archive starts. The per-entry allowance and
byte budget therefore govern documents only.

archiver processes appended entries through a sequential queue; lazystream
defers each storage read until that entry's turn, since handing the archiver an
open stream per entry would hold more connections than the storage client pools.
nodeReadableToWebStream moves out of input-validation.server.ts into a shared
util rather than being written twice: Readable.toWeb throws ERR_INVALID_STATE
when a consumer cancels while the source is still flowing, which is exactly what
a cancelled download does.

Trade: a storage read failing mid-archive truncates the response rather than
returning 500, since the status is already sent. Documents cannot hit this. The
table export route already behaves this way.

* improvement(files): surface archive download errors in place

Bulk and folder downloads navigated to the API route, so any rejection replaced
the Files page with the raw JSON error body. Single-file download already
fetched and saved the blob, so the two paths had diverged.

That was survivable when the only failures were "too many files" and "too
large"; resolving rendered documents adds a 409 for a still-compiling artifact,
which is reachable in normal use. Both archive paths now fetch the zip and show
the server's message as a toast — the route writes that copy for a person, so it
is worth surfacing rather than discarding. Single-file download shows its error
too instead of only logging it.

* improvement(files): simplify the archive route and stop buffering real uploads

Four review passes over the branch converged on the same points.

Routing every office extension through the buffered path held an entire selection
of genuinely uploaded documents in memory — for a check the resolver settles on
the first few magic bytes. Only files stored under a generator-source content
type need resolving; a real .docx serves what is stored and now streams like
anything else, which is what the change was for.

With resolution sequential, the AbortController cancelled nothing (its signal
never reached the storage read), the success-path over-limit branch was
unreachable, and the cancellation guard in the catch could not fire. A plain loop
that returns at the point of failure replaces the outcome record, the sentinel,
the fan-out helper at limit 1, and four post-hoc scans. ZIP_MATERIALIZE_CONCURRENCY
was dead, and the aggregate over-limit message reported a byte count that was by
construction under the limit.

lazystream and its types are gone: Readable.from over an async generator defers
the open the same way and propagates source errors natively, so the PassThrough
relay went with them. The client uses requestRaw with the existing binary
contract instead of a hand-built query string and a re-typed error extractor, and
both archive call sites share one callback. The render headroom moves beside
isRenderableDocumentName, the servable reader stops minting a request id per
file, and the v1 download returns a view rather than a second full copy.

* improvement(files): keep the lazy entry stream in byte mode

Readable.from defaults to object mode; these chunks are bytes headed for an
archive, so the mode is now explicit. Also makes the fire-and-forget bulk
download call consistent with its sibling.

* improvement(files): correct the servable reader's 409 note

Batch callers build the response from docNotReadyMessage rather than through
docNotReadyResponse, so the doc comment now describes the outcome instead of
naming one of the two helpers.

* improvement(files): correct two comments that described the wrong behavior

The resolution loop's comment claimed at most one rendered document is resident.
It is not: every resolved buffer is held until the archive is assembled, bounded
by the request's remaining budget. The loop resolves one at a time, it does not
release one at a time.

RENDERED_DOCUMENT_HEADROOM_BYTES was documented as bounding the expansion beyond
the declared size, but it is passed straight through as maxBytes and is an
absolute ceiling on the rendered document — renamed to MAX_RENDERED_DOCUMENT_BYTES
so the name matches. Download failures also carry a fallback message, so a
transport error surfaces something better than a bare "Failed to fetch".

* fix(files): put streamed files and rendered documents on one byte budget

The budget only counted rendered documents, so streamed entries never reserved
their declared bytes. A mixed selection could clear the up-front declared-size
gate and still ship close to two full limits: ordinary files up to the cap, plus
documents drawing a fresh cap of their own.

Streamed entries ship exactly what they declared, so their share is known before
anything is read and is now reserved up front; documents draw from what is left.

The budget-exhausted rejection also quoted declared sizes, which for a selection
of small sources reads as a tiny total exceeding the limit. That case has no
knowable byte count — the documents have not been rendered — so it now says what
happened without inventing a number.

* fix(files): attach the download anchor and handle a finalize rejection

A detached anchor's click() works in current browsers, but every other download
helper in the app attaches first, and a silent no-op on this path would look
exactly like a download that never started. Not worth the ambiguity for two DOM
operations.

archive.finalize() was fired with void, so a failure after the response had
started became an unhandled rejection on top of the stream error event that
already fails the response. It is caught and logged now.

* fix(files): guard the archive download against concurrent clicks

Navigating to the route meant a second click just re-navigated. Fetching the
archive instead means each click starts another download that holds the whole
zip in tab memory, and the Download button gave no sign anything was happening.

The button now reflects the in-flight download alongside the existing move and
delete states. The ref guard is there as well as the state because two clicks in
the same tick would both pass a state check.

* fix(files): resolve every generated-document source type, not four of five

The archive keyed off a locally enumerated set of source content types that
omitted text/x-pdflibjs — the isolated-vm PDF generator. Those files failed the
check and streamed their generator source under a .pdf name, which is the exact
corruption this change exists to fix.

A canonical five-member set already existed in the file viewer; enumerating a
fourth copy was the mistake, not the missing string. The set moves to file-utils
beside the other file-type predicates, the viewer imports it, and the route asks
isGeneratedDocumentSourceType rather than carrying its own list. A parameterized
test pins all five, so adding a generator without extending the set fails.

* test(files): validate the produced archive with a real zip reader

Every existing test mocks the storage stream and reads the result back with the
same JS library that wrote it, which cannot catch the failure this route exists
to fix: an archive a real zip reader will not open.

This drives 5 MB of non-repeating bytes from an fs stream through archiver, the
lazy entry generator and the Node-to-web bridge, then checks the output with the
operating system's unzip and compares the extracted bytes. Skips rather than
fails where unzip is unavailable.

* fix(files): bound the markdown export's embedded-asset bundling

The embed list is produced by scanning the document body, so its length and the
bytes behind it are whatever the author put there. Every referenced asset was
downloaded at once with no concurrency bound, no per-file cap and no total cap,
so one request could materialize an unbounded number of unbounded files. Its
sibling bulk-download route already had a count cap and a byte cap.

Metadata is now resolved first, which bounds the download from declared sizes
before a byte is read and moves the authorization check off the download path.
Assets are then fetched with bounded concurrency and a per-file cap; a single
unreadable or oversized asset drops out of the bundle rather than failing the
export, which is what the previous allSettled did.

* fix(files): mount rendered documents into the sandbox, not generator source

Mounting a generated document handed the sandbox its generator source under a
.docx name, so a python-docx or openpyxl script failed on a file that looked
fine and the agent debugged code that was correct.

Both branches were wrong, not just the buffered one: with cloud storage the
mount presigns record.key, which is the raw source object, so swapping the
buffered read alone would have fixed only local storage. Source-backed documents
now always take the servable path — they are bounded by the render ceiling, so
routing them through the web process instead of presigning is affordable.

The text/binary decision also keyed off record.type, which for these files is
text/x-docxjs, so a resolved binary would have been decoded as UTF-8. It reads
the resolved content type now.

* chore(deps): regenerate the lockfile against staging's dependency rework

Staging reworked the OTel split, dropped dead deps and declared emcn peers, so
the lockfile is regenerated on top of that rather than carrying a stale merge.
The archive dependency is the only addition; lazystream stays as archiver's
transitive dep now that it is no longer declared directly.

Regenerated incrementally rather than from scratch: a clean resolve fails the
bunfig age gate because minimumReleaseAgeExcludes lists only the darwin and
linux-gnu @next/swc binaries, not the musl and windows variants that a full
re-resolve also pulls.

* fix(files): budget sandbox mounts on rendered bytes, not declared source size

A source-backed document declares the size of its generator, not of the document,
so the per-file and aggregate mount pre-checks were reading a number unrelated to
what was about to be mounted — tiny sources cleared the guard and only afterwards
was the running total updated with the real length.

Those pre-checks now apply only to files that serve what they declare. A document
is capped by the read instead, at the smaller of the per-file limit and the budget
left, and a size rejection is reported in the same terms as the other mount
limits. Same invariant the archive route already had to learn: declared size is
not a bound once bytes can be rendered.

* test(files): cover the two surfaces added without tests

The markdown export route had no test file at all, and the sandbox mount's
source-backed branch was exercised by nothing — both were changed in this PR and
one of them shipped a defect a reviewer caught within minutes.

Export: the embed-count rejection, the declared-bytes rejection landing before
any asset leaves storage, the per-asset download cap, an unreadable asset
dropping out rather than failing the export, and an unauthorized asset never
being read.

Mount: a generated document never presigning its raw key even on cloud storage,
its rendered bytes mounting as base64 rather than being utf-8 decoded off the
source MIME, and the budget rejecting on rendered length.

* fix(files): stop the export caps from rejecting documents that used to work

The caps I picked would have failed exports that previously succeeded: a
screenshot-heavy document can hold more than 100 embeds, and 100 embeds of
unoptimised PNGs can exceed 100 MB. Adding a limit to bound memory is right;
setting it below real usage turns a memory risk into a broken feature.

The byte ceiling now matches the bulk-download route, so the two export surfaces
reject at the same size rather than at two invented ones. The count is only a
guard on the metadata lookups that run before the byte check, so it moves well
above any hand-authored document instead of sitting where a legitimate one
could reach it.

Author: waleedlatif1

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

@@ -0,0 +1,158 @@
+/**
+ * @vitest-environment node
+ */
+import { createMockRequest } from '@sim/testing'
+import JSZip from 'jszip'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const {
+  mockCheckAuth,
+  mockGetFileMetadataById,
+  mockVerifyFileAccess,
+  mockDownloadFile,
+  mockExtractEmbeddedImageIds,
+} = vi.hoisted(() => ({
+  mockCheckAuth: vi.fn(),
+  mockGetFileMetadataById: vi.fn(),
+  mockVerifyFileAccess: vi.fn(),
+  mockDownloadFile: vi.fn(),
+  mockExtractEmbeddedImageIds: vi.fn(),
+}))
+
+vi.mock('@/lib/auth/hybrid', () => ({ checkSessionOrInternalAuth: mockCheckAuth }))
+vi.mock('@/lib/uploads/server/metadata', () => ({
+  getFileMetadataById: mockGetFileMetadataById,
+}))
+vi.mock('@/app/api/files/authorization', () => ({ verifyFileAccess: mockVerifyFileAccess }))
+vi.mock('@/lib/uploads/core/storage-service', () => ({ downloadFile: mockDownloadFile }))
+vi.mock('@/lib/copilot/tools/server/files/embedded-image-refs', () => ({
+  extractEmbeddedImageIds: mockExtractEmbeddedImageIds,
+}))
+vi.mock('@sim/audit', () => ({
+  recordAudit: vi.fn(),
+  AuditAction: { FILE_DOWNLOADED: 'file.downloaded' },
+  AuditResourceType: { FILE: 'file' },
+}))
+vi.mock('@/lib/posthog/server', () => ({ captureServerEvent: vi.fn() }))
+
+import { GET } from '@/app/api/files/export/[id]/route'
+
+const MB = 1024 * 1024
+const DOC_ID = 'doc-1'
+const context = { params: Promise.resolve({ id: DOC_ID }) }
+
+function request() {
+  return createMockRequest('GET', undefined, {}, `http://localhost:3000/api/files/export/${DOC_ID}`)
+}
+
+function assetRecord(id: string, size: number) {
+  return {
+    id,
+    key: `workspace/ws-1/${id}`,
+    originalName: `${id}.png`,
+    contentType: 'image/png',
+    context: 'workspace',
+    size,
+    workspaceId: 'ws-1',
+  }
+}
+
+describe('markdown export bundling', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockCheckAuth.mockResolvedValue({ success: true, userId: 'user-1' })
+    mockVerifyFileAccess.mockResolvedValue(true)
+    mockGetFileMetadataById.mockImplementation(async (id: string) =>
+      id === DOC_ID
+        ? {
+            id: DOC_ID,
+            key: 'workspace/ws-1/doc.md',
+            originalName: 'doc.md',
+            contentType: 'text/markdown',
+            context: 'workspace',
+            size: 1024,
+            workspaceId: 'ws-1',
+          }
+        : assetRecord(id, 1 * MB)
+    )
+    mockDownloadFile.mockResolvedValue(Buffer.from('# Doc\n'))
+    mockExtractEmbeddedImageIds.mockReturnValue([])
+  })
+
+  it('rejects a document embedding more assets than an export may bundle', async () => {
+    mockExtractEmbeddedImageIds.mockReturnValue(
+      Array.from({ length: 501 }, (_, index) => `img-${index}`)
+    )
+
+    const response = await GET(request(), context)
+
+    expect(response.status).toBe(400)
+    expect((await response.json()).error).toContain('501')
+    // Rejected on the embed count alone: nothing was resolved or downloaded.
+    expect(mockGetFileMetadataById).toHaveBeenCalledTimes(1)
+  })
+
+  it('rejects on declared asset bytes before downloading any of them', async () => {
+    mockExtractEmbeddedImageIds.mockReturnValue(['a', 'b', 'c'])
+    mockGetFileMetadataById.mockImplementation(async (id: string) =>
+      id === DOC_ID
+        ? {
+            id: DOC_ID,
+            key: 'workspace/ws-1/doc.md',
+            originalName: 'doc.md',
+            contentType: 'text/markdown',
+            context: 'workspace',
+            size: 1024,
+            workspaceId: 'ws-1',
+          }
+        : assetRecord(id, 100 * MB)
+    )
+
+    const response = await GET(request(), context)
+
+    expect(response.status).toBe(400)
+    expect((await response.json()).error).toContain('exceeds')
+    // Only the markdown body was read; the 300 MB of assets never left storage.
+    expect(mockDownloadFile).toHaveBeenCalledTimes(1)
+  })
+
+  it('caps each asset download rather than trusting its declared size', async () => {
+    mockExtractEmbeddedImageIds.mockReturnValue(['a'])
+
+    await GET(request(), context)
+
+    const assetCall = mockDownloadFile.mock.calls.find(
+      ([options]) => options.key === 'workspace/ws-1/a'
+    )
+    expect(assetCall?.[0].maxBytes).toBe(25 * MB)
+  })
+
+  it('drops an unreadable asset instead of failing the whole export', async () => {
+    mockExtractEmbeddedImageIds.mockReturnValue(['good', 'bad'])
+    mockDownloadFile.mockImplementation(async ({ key }: { key: string }) => {
+      if (key.endsWith('doc.md')) return Buffer.from('# Doc\n![x](/api/files/view/good)\n')
+      if (key.endsWith('bad')) throw new Error('storage down')
+      return Buffer.from('png-bytes')
+    })
+
+    const response = await GET(request(), context)
+
+    expect(response.status).toBe(200)
+    const zip = await JSZip.loadAsync(Buffer.from(await response.arrayBuffer()))
+    expect(zip.file('assets/good.png')).not.toBeNull()
+    expect(zip.file('assets/bad.png')).toBeNull()
+  })
+
+  it('skips an asset the caller cannot read', async () => {
+    mockExtractEmbeddedImageIds.mockReturnValue(['secret'])
+    mockVerifyFileAccess.mockImplementation(async (key: string) => !key.endsWith('secret'))
+
+    const response = await GET(request(), context)
+
+    expect(response.status).toBe(200)
+    // Authorization is settled during metadata resolution, before any asset read.
+    expect(mockDownloadFile.mock.calls.some(([options]) => options.key.endsWith('secret'))).toBe(
+      false
+    )
+  })
+})

apps/sim/app/api/files/export/[id]/route.ts

@@ -9,17 +9,33 @@ import { fileExportContract } from '@/lib/api/contracts/storage-transfer'
 import { parseRequest } from '@/lib/api/server'
 import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
 import { extractEmbeddedImageIds } from '@/lib/copilot/tools/server/files/embedded-image-refs'
+import { MATERIALIZE_CONCURRENCY, mapWithConcurrency } from '@/lib/core/utils/concurrency'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 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 { getFileMetadataById } from '@/lib/uploads/server/metadata'
+import { formatFileSize } from '@/lib/uploads/utils/file-utils'
 import { verifyFileAccess } from '@/app/api/files/authorization'
 import { encodeFilenameForHeader } from '@/app/api/files/utils'
 
 const logger = createLogger('FilesExportAPI')
 
+/**
+ * Bundling caps. The embed list comes from scanning the document body, so its length
+ * and the bytes behind it are whatever the author put there — without these the export
+ * would materialize an unbounded number of unbounded assets in one request.
+ *
+ * The byte ceilings are the real bound and match the bulk-download route, so the two
+ * export surfaces reject at the same size. The count is only a guard on the metadata
+ * lookups that precede the byte check, so it sits far above any hand-authored document
+ * rather than at a number a screenshot-heavy doc could plausibly reach.
+ */
+const MAX_EXPORT_ASSETS = 500
+const MAX_EXPORT_ASSET_BYTES = 25 * 1024 * 1024
+const MAX_EXPORT_TOTAL_BYTES = 250 * 1024 * 1024
+
 const MARKDOWN_MIME_TYPES = new Set(['text/markdown', 'text/x-markdown'])
 const MARKDOWN_EXTENSIONS = new Set(['md', 'markdown'])
 
@@ -136,34 +152,73 @@ export const GET = withRouteHandler(
       })
     }
 
-    const fetchResults = await Promise.allSettled(
-      imageIds.map(async (imageId) => {
-        const imgRecord = await getFileMetadataById(imageId)
-        if (!imgRecord) return null
-        const imgHasAccess = await verifyFileAccess(imgRecord.key, userId)
-        if (!imgHasAccess) return null
-        const imgBuffer = await downloadFile({
-          key: imgRecord.key,
-          context: imgRecord.context as StorageContext,
-        })
-        return { imageId, originalName: imgRecord.originalName, buffer: imgBuffer }
+    if (imageIds.length > MAX_EXPORT_ASSETS) {
+      return NextResponse.json(
+        {
+          error: `This document embeds ${imageIds.length} files, more than the ${MAX_EXPORT_ASSETS} an export can bundle.`,
+        },
+        { status: 400 }
+      )
+    }
+
+    // Metadata first: declared sizes bound the download before a byte is read, and the
+    // authorization check costs nothing to run here.
+    const assetTargets = (
+      await mapWithConcurrency(imageIds, MATERIALIZE_CONCURRENCY, async (imageId) => {
+        try {
+          const imgRecord = await getFileMetadataById(imageId)
+          if (!imgRecord) return null
+          if (!(await verifyFileAccess(imgRecord.key, userId))) return null
+          return { imageId, record: imgRecord }
+        } catch (error) {
+          logger.warn('Failed to resolve asset for export', {
+            imageId,
+            error: toError(error).message,
+          })
+          return null
+        }
       })
+    ).filter((target): target is NonNullable<typeof target> => target !== null)
+
+    const declaredAssetBytes = assetTargets.reduce((sum, target) => sum + target.record.size, 0)
+    if (declaredAssetBytes > MAX_EXPORT_TOTAL_BYTES) {
+      return NextResponse.json(
+        {
+          error: `Embedded files total ${formatFileSize(declaredAssetBytes)}, which exceeds the ${formatFileSize(MAX_EXPORT_TOTAL_BYTES)} export limit.`,
+        },
+        { status: 400 }
+      )
+    }
+
+    const fetched = await mapWithConcurrency(
+      assetTargets,
+      MATERIALIZE_CONCURRENCY,
+      async ({ imageId, record: imgRecord }) => {
+        try {
+          const buffer = await downloadFile({
+            key: imgRecord.key,
+            context: imgRecord.context as StorageContext,
+            maxBytes: MAX_EXPORT_ASSET_BYTES,
+          })
+          return { imageId, originalName: imgRecord.originalName, buffer }
+        } catch (error) {
+          // A single unreadable or oversized asset drops out of the bundle rather than
+          // failing the whole export; the markdown keeps its original link.
+          logger.warn('Failed to fetch asset for export', {
+            imageId,
+            error: toError(error).message,
+          })
+          return null
+        }
+      }
     )
 
     const assetMap = new Map<string, { filename: string; buffer: Buffer }>()
     const usedFilenames = new Set<string>()
 
-    for (let i = 0; i < fetchResults.length; i++) {
-      const result = fetchResults[i]
-      if (result.status === 'rejected') {
-        logger.warn('Failed to fetch asset for export', {
-          imageId: imageIds[i],
-          error: toError(result.reason).message,
-        })
-        continue
-      }
-      if (!result.value) continue
-      const { imageId, originalName, buffer } = result.value
+    for (const result of fetched) {
+      if (!result) continue
+      const { imageId, originalName, buffer } = result
       const preferred = safeFilename(originalName)
       const filename = deduplicatedFilename(preferred, usedFilenames, imageId)
       usedFilenames.add(filename)

apps/sim/app/api/tools/file/manage/route.ts

@@ -11,6 +11,7 @@ import { checkInternalAuth } from '@/lib/auth/hybrid'
 import { splitWorkspaceFilePath } from '@/lib/copilot/tools/server/files/workspace-file'
 import { acquireLock, releaseLock } from '@/lib/core/config/redis'
 import { generateRequestId } from '@/lib/core/utils/request'
+import { isPayloadSizeLimitError } from '@/lib/core/utils/stream-limits'
 import { ensureAbsoluteUrl } from '@/lib/core/utils/urls'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { isSupportedFileType, parseBuffer } from '@/lib/file-parsers'
@@ -685,7 +686,11 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
           const denied = await assertToolFileAccess(userFile.key, userId, requestId, logger)
           if (denied) return denied
 
-          const buffer = await downloadFileFromStorage(userFile, requestId, logger, {
+          // Generated docs store their generation source, not the rendered binary, so
+          // the archive must carry the servable bytes instead of the raw source text.
+          // A still-compiling artifact throws, and the handler's catch turns that into
+          // the shared 409 via `docNotReadyResponse`.
+          const { buffer } = await downloadServableFileFromStorage(userFile, requestId, logger, {
             maxBytes: MAX_COMPRESS_FILE_BYTES,
           })
           totalBytes += buffer.length
@@ -864,6 +869,11 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
     }
     const notReady = docNotReadyResponse(error)
     if (notReady) return notReady
+    // A file over its per-file cap is a size rejection, not a fault. Rendered
+    // documents can cross it even when the stored source was well under.
+    if (isPayloadSizeLimitError(error)) {
+      return NextResponse.json({ success: false, error: error.message }, { status: 413 })
+    }
     if (error instanceof ShareValidationError) {
       return NextResponse.json({ success: false, error: error.message }, { status: 400 })
     }

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

@@ -6,7 +6,11 @@ import { parseRequest } from '@/lib/api/server'
 import { generateRequestId } from '@/lib/core/utils/request'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { captureServerEvent } from '@/lib/posthog/server'
-import { fetchWorkspaceFileBuffer, getWorkspaceFile } from '@/lib/uploads/contexts/workspace'
+import {
+  fetchServableWorkspaceFileBuffer,
+  getWorkspaceFile,
+} from '@/lib/uploads/contexts/workspace'
+import { docNotReadyMessage, isDocNotReadyError } from '@/lib/uploads/utils/servable-file-response'
 import { performDeleteWorkspaceFileItems } from '@/lib/workspace-files/orchestration'
 import {
   checkRateLimit,
@@ -48,7 +52,9 @@ export const GET = withRouteHandler(async (request: NextRequest, context: FileRo
       return NextResponse.json({ error: 'File not found' }, { status: 404 })
     }
 
-    const buffer = await fetchWorkspaceFileBuffer(fileRecord)
+    // Generated docs store their generation source; serve the rendered artifact.
+    // Its content type is the rendered one, not the source MIME on the record.
+    const { buffer, contentType } = await fetchServableWorkspaceFileBuffer(fileRecord)
 
     recordAudit({
       workspaceId,
@@ -73,21 +79,30 @@ export const GET = withRouteHandler(async (request: NextRequest, context: FileRo
       { groups: { workspace: workspaceId } }
     )
 
-    return new Response(new Uint8Array(buffer), {
-      status: 200,
-      headers: {
-        'Content-Type': fileRecord.type || 'application/octet-stream',
-        'Content-Disposition': `attachment; filename="${fileRecord.name.replace(/[^\w.-]/g, '_')}"; filename*=UTF-8''${encodeURIComponent(fileRecord.name)}`,
-        'Content-Length': String(buffer.length),
-        'X-File-Id': fileRecord.id,
-        'X-File-Name': encodeURIComponent(fileRecord.name),
-        'X-Uploaded-At':
-          fileRecord.uploadedAt instanceof Date
-            ? fileRecord.uploadedAt.toISOString()
-            : String(fileRecord.uploadedAt),
-      },
-    })
+    // View, not copy — a second full copy would double peak memory for a large file.
+    return new Response(
+      new Uint8Array(buffer.buffer as ArrayBuffer, buffer.byteOffset, buffer.byteLength),
+      {
+        status: 200,
+        headers: {
+          'Content-Type': contentType || fileRecord.type || 'application/octet-stream',
+          'Content-Disposition': `attachment; filename="${fileRecord.name.replace(/[^\w.-]/g, '_')}"; filename*=UTF-8''${encodeURIComponent(fileRecord.name)}`,
+          'Content-Length': String(buffer.length),
+          'X-File-Id': fileRecord.id,
+          'X-File-Name': encodeURIComponent(fileRecord.name),
+          'X-Uploaded-At':
+            fileRecord.uploadedAt instanceof Date
+              ? fileRecord.uploadedAt.toISOString()
+              : String(fileRecord.uploadedAt),
+        },
+      }
+    )
   } catch (error) {
+    // A generated doc whose artifact is still compiling is retryable, not a fault:
+    // without this the caller sees a 500 and has no reason to try again.
+    if (isDocNotReadyError(error)) {
+      return NextResponse.json({ error: docNotReadyMessage() }, { status: 409 })
+    }
     logger.error(`[${requestId}] Error downloading file:`, error)
     return NextResponse.json({ error: 'Failed to download file' }, { status: 500 })
   }