fix(files): stop promising immutable caching for documents compiled against other files

A versioned serve URL (`?v=<updatedAt>`) was always answered with a one-year
`immutable` Cache-Control. That holds for a stored source — a content write
rotates the storage key, so a given key's bytes never change — but not for a
response the route resolves against OTHER files: a document compiled against the
files it references, or a sim page inlining its images, recompiles on every
request. Those bytes change when a referenced file changes, while this file's key
and `updatedAt` stay put, so the whole URL is unchanged and the browser served a
stale render from cache until the document itself was edited.

The resolver now reports when it read referenced content, and the route withholds
the immutable lifetime for exactly those responses, keeping it for stored sources
and self-contained artifacts.

Also corrects three comments that claimed generated docs are edited in place under
the same storage key. That stopped being true in #5545 (2026-07-13), which made
every content write allocate a new key; the caching rule above was reasoned from
the stale claim.

Author: waleedlatif1

apps/sim/app/api/files/serve/[...path]/route.test.ts

@@ -439,6 +439,59 @@ describe('File Serve API Route', () => {
     expect(mockVerifyFileAccess).not.toHaveBeenCalled()
   })
 
+  describe('versioned cache lifetime', () => {
+    const principal = {
+      kind: 'delegated' as const,
+      serviceId: 'executor' as const,
+      subjectUserId: 'test-user-id',
+      workspaceId: 'test-workspace-id',
+      delegationId: 'delegation-1',
+      audience: 'sim:workspace-files',
+      issuedAt: new Date('2026-08-01T00:00:00Z'),
+      expiresAt: new Date('2026-08-01T01:00:00Z'),
+      delegationContext: {
+        kind: 'workflow_execution' as const,
+        workflowId: 'workflow-1',
+      },
+    }
+
+    async function serveVersionedDoc(dependsOnReferencedFiles: boolean) {
+      mockResolveStoredFileContext.mockResolvedValue('workspace')
+      mockParseWorkspaceFileKey.mockReturnValue('test-workspace-id')
+      mockAuthenticateWorkspaceFile.mockResolvedValue(principal)
+      mockResolveServableDocBytes.mockResolvedValue({
+        buffer: Buffer.from('compiled'),
+        contentType: 'application/pdf',
+        ...(dependsOnReferencedFiles ? { dependsOnReferencedFiles: true } : {}),
+      })
+
+      const req = new NextRequest(
+        'http://localhost:3000/api/files/serve/workspace/test-workspace-id/report.pdf?v=1756684800000'
+      )
+      await GET(req, {
+        params: Promise.resolve({ path: ['workspace', 'test-workspace-id', 'report.pdf'] }),
+      })
+      return mockCreateFileResponse.mock.calls.at(-1)?.[0]
+    }
+
+    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' })
+      )
+    })
+
+    it('keeps a versioned document revalidated when it was compiled against referenced files', async () => {
+      /**
+       * The URL carries the file's own `updatedAt`, which does not move when a
+       * REFERENCED file changes — so an immutable lifetime would pin the stale
+       * render in the browser cache until the document itself is edited.
+       */
+      expect(await serveVersionedDoc(true)).toEqual(
+        expect.objectContaining({ cacheControl: 'private, no-cache, must-revalidate' })
+      )
+    })
+  })
+
   it('serves a mothership chat attachment stored under a workspace key', async () => {
     /**
      * The attachment shares the `workspace/…` prefix but is recorded as

apps/sim/app/api/files/serve/[...path]/route.ts

@@ -64,10 +64,22 @@ interface ServeOptions {
   raw: boolean
   /** `preview=1` — the caller renders these bytes rather than saving them. */
   preview: boolean
-  /** `v=<updatedAt>` — the URL addresses content-immutable bytes. */
+  /** `v=<updatedAt>` — the caller asserts the URL addresses one fixed content revision. */
   versioned: boolean
 }
 
+interface ServableBytes {
+  buffer: Buffer
+  contentType: string
+  /**
+   * These bytes were resolved against OTHER files' current content — a sim page inlining its
+   * images, or a document compiled against the files it references. The same storage key can
+   * therefore serve different bytes over time, with nothing about this file changing, so the
+   * response must stay revalidated even when the request carries a version.
+   */
+  dependsOnReferencedFiles?: boolean
+}
+
 /**
  * Resolves the bytes + content type to serve for a stored file.
  *
@@ -95,7 +107,7 @@ async function resolveServableBytes(params: {
   /** The stored record's content type, where the caller has the record. */
   fileType?: string
   signal: AbortSignal | undefined
-}): Promise<{ buffer: Buffer; contentType: string }> {
+}): Promise<ServableBytes> {
   // `raw` is the stored source, already bounded by the read that produced it, but it
   // goes through the same check so the ceiling holds for everything this returns
   // rather than for every branch someone remembered to cover.
@@ -120,7 +132,7 @@ async function resolveTransformedBytes(params: {
   filePrincipal?: Principal
   fileType?: string
   signal: AbortSignal | undefined
-}): Promise<{ buffer: Buffer; contentType: string }> {
+}): Promise<ServableBytes> {
   const {
     buffer,
     filename,
@@ -146,7 +158,8 @@ async function resolveTransformedBytes(params: {
         await renderSimPageDocumentWithAssets(text, { workspaceId }),
         'utf8'
       )
-      return { buffer: rendered, contentType: 'text/html' }
+      // Inlines the workspace images the page references, read at their CURRENT content.
+      return { buffer: rendered, contentType: 'text/html', dependsOnReferencedFiles: true }
     }
   }
 
@@ -184,18 +197,29 @@ const WORKSPACE_REVALIDATE_CACHE_CONTROL = 'private, no-cache, must-revalidate'
 const PUBLIC_ASSET_CACHE_CONTROL = 'public, max-age=31536000'
 
 /**
- * Cache-Control for a served file. A versioned request (`?v=<updatedAt>`) addresses
- * content-immutable bytes — generated docs are content-addressed and the version
- * bumps on every edit — so the browser may cache it indefinitely; re-opens and
- * focus refetches then resolve from cache with no round trip. Unversioned workspace
- * reads stay revalidated because the same storage key is edited in place.
+ * Cache-Control for a served file.
+ *
+ * A versioned request (`?v=<updatedAt>`) normally addresses content-immutable bytes: a workspace
+ * file's content write stores the new bytes under a NEW storage key, so a given key's stored
+ * source never changes and the browser may cache it indefinitely — re-opens and focus refetches
+ * then resolve from cache with no round trip.
+ *
+ * That promise does NOT hold when the response was resolved against other files' current content
+ * (`dependsOnReferencedFiles`): a document compiled against the files it references, or a sim page
+ * inlining its images, recompiles per request, so the same key serves different bytes once a
+ * referenced file changes — while this file's key and `updatedAt`, and therefore the whole URL,
+ * stay put. Promising immutability there pins a stale render in the browser cache for a year, so
+ * those responses stay revalidated whether or not the request carried a version.
  */
 function resolveServeCacheControl(
   versioned: boolean,
-  context: string | undefined
+  context: string | undefined,
+  dependsOnReferencedFiles: boolean | undefined
 ): string | undefined {
-  if (versioned) return IMMUTABLE_CACHE_CONTROL
-  return context === 'workspace' ? WORKSPACE_REVALIDATE_CACHE_CONTROL : undefined
+  if (versioned && !dependsOnReferencedFiles) return IMMUTABLE_CACHE_CONTROL
+  return context === 'workspace' || dependsOnReferencedFiles
+    ? WORKSPACE_REVALIDATE_CACHE_CONTROL
+    : undefined
 }
 
 export const GET = withRouteHandler(
@@ -385,7 +409,11 @@ async function handleWorkspaceFile(
     buffer: resolved.buffer,
     contentType: resolved.contentType,
     filename: file.name,
-    cacheControl: resolveServeCacheControl(options.versioned, 'workspace'),
+    cacheControl: resolveServeCacheControl(
+      options.versioned,
+      'workspace',
+      resolved.dependsOnReferencedFiles
+    ),
   })
 }
 
@@ -427,7 +455,11 @@ async function handleLocalFile(
     const segment = filename.split('/').pop() || filename
     const displayName = stripStorageKeyPrefix(segment)
     const workspaceId = getWorkspaceIdForCompile(filename)
-    const { buffer: fileBuffer, contentType } = await resolveServableBytes({
+    const {
+      buffer: fileBuffer,
+      contentType,
+      dependsOnReferencedFiles,
+    } = await resolveServableBytes({
       buffer: rawBuffer,
       filename: displayName,
       storageKey: filename,
@@ -443,7 +475,7 @@ async function handleLocalFile(
       buffer: fileBuffer,
       contentType,
       filename: displayName,
-      cacheControl: resolveServeCacheControl(options.versioned, context),
+      cacheControl: resolveServeCacheControl(options.versioned, context, dependsOnReferencedFiles),
     })
   } catch (error) {
     logServeFailure('Error reading local file:', error)
@@ -494,7 +526,11 @@ async function handleCloudProxy(
     const segment = cloudKey.split('/').pop() || 'download'
     const displayName = stripStorageKeyPrefix(segment)
     const workspaceId = getWorkspaceIdForCompile(cloudKey)
-    const { buffer: fileBuffer, contentType } = await resolveServableBytes({
+    const {
+      buffer: fileBuffer,
+      contentType,
+      dependsOnReferencedFiles,
+    } = await resolveServableBytes({
       buffer: rawBuffer,
       filename: displayName,
       storageKey: cloudKey,
@@ -515,7 +551,7 @@ async function handleCloudProxy(
       buffer: fileBuffer,
       contentType,
       filename: displayName,
-      cacheControl: resolveServeCacheControl(options.versioned, context),
+      cacheControl: resolveServeCacheControl(options.versioned, context, dependsOnReferencedFiles),
     })
   } catch (error) {
     logServeFailure('Error downloading from cloud storage:', error)

apps/sim/hooks/queries/workspace-files.ts

@@ -373,13 +373,14 @@ export class DocNotReadyError extends Error {
 /**
  * Fetch compiled/binary file content via the serve URL.
  *
- * A `version` (the file record's `updatedAt`) makes the URL content-immutable: the
- * serve route marks versioned responses `immutable`, so the browser HTTP cache
- * resolves re-opens and focus refetches with no round trip. Generated docs are
- * edited in place (same storage key), so an unversioned caller cannot assume
- * immutability and instead busts + bypasses the cache to always read fresh. A 409
- * means a generated doc is still compiling — surfaced as {@link DocNotReadyError}
- * so the query keeps polling.
+ * A `version` (the file record's `updatedAt`) lets the serve route mark the response
+ * `immutable`, so the browser HTTP cache resolves re-opens and focus refetches with no
+ * round trip. The route withholds that promise for bytes it resolved against OTHER
+ * files — a doc compiled against its references, a page inlining its images — which the
+ * same key can serve differently over time. An unversioned caller makes no immutability
+ * claim at all and busts + bypasses the cache to always read fresh. A 409 means a
+ * generated doc is still compiling — surfaced as {@link DocNotReadyError} so the query
+ * keeps polling.
  */
 async function fetchWorkspaceFileBinary(
   url: string,
@@ -401,11 +402,10 @@ async function fetchWorkspaceFileBinary(
  * storage key (e.g. after a file is re-uploaded) correctly busts the cache.
  *
  * `options.version` is a content version (the record's `updatedAt`) folded into the
- * query key. Generated docs are edited IN PLACE — `edit_content` keeps the SAME
- * storage key — so without a version the cache is never busted and the open
- * preview keeps showing the stale binary after a regenerate. Versioning the key
- * makes the preview refetch whenever the file's content changes (and on first
- * open, keyed to the current content rather than a stale cached entry).
+ * query key, and it is what lets the response be cached as immutable. A content write
+ * rotates the storage key, so `key` alone would already re-key the query; `version`
+ * additionally covers a recompile that leaves the key alone, and keys the first open to
+ * the current content rather than a stale cached entry.
  */
 export function useWorkspaceFileBinary(
   workspaceId: string,

apps/sim/lib/copilot/tools/server/files/doc-compile.ts

@@ -147,6 +147,13 @@ export interface CompiledDocResult {
   buffer: Buffer
   contentType: string
   contributingFiles?: readonly WorkspaceFileSecretProvenanceIdentity[]
+  /**
+   * The artifact was resolved against OTHER files' current content, so these bytes are not a
+   * function of this file's stored source alone: the same storage key compiles to different bytes
+   * once a referenced file changes, with nothing about this file changing. A caller that assigns
+   * the response a cache lifetime must not promise immutability for it.
+   */
+  dependsOnReferencedFiles?: boolean
 }
 
 function referencedImageIdentities(
@@ -912,12 +919,20 @@ export async function resolveServableDocBytes(args: {
         const published = await loadCompiledDocByExt(workspaceId, source, extNoDot, {
           allowPublishedReferencedArtifact: true,
         })
-        if (published) return published
+        if (published) return { ...published, dependsOnReferencedFiles: true }
         throw new Error(
           'Referenced document resolution requires an authorized workspace file principal'
         )
       }
-      return compileDoc({ source, fileName, workspaceId, filePrincipal, ownerKey, signal })
+      const compiled = await compileDoc({
+        source,
+        fileName,
+        workspaceId,
+        filePrincipal,
+        ownerKey,
+        signal,
+      })
+      return { ...compiled, dependsOnReferencedFiles: true }
     }
     const stored = await loadCompiledDocByExt(workspaceId, source, extNoDot, {
       allowLegacyReferencedArtifact: true,

apps/sim/lib/copilot/tools/server/files/doc-servable.test.ts

@@ -168,6 +168,7 @@ describe('resolveServableDocBytes', () => {
     expect(result).toEqual({
       buffer: Buffer.from('%PDF-rebuilt'),
       contentType: 'application/pdf',
+      dependsOnReferencedFiles: true,
       contributingFiles: [
         {
           fileId: 'reference-1',
@@ -273,6 +274,7 @@ describe('resolveServableDocBytes', () => {
     ).resolves.toEqual({
       buffer: publishedArtifact,
       contentType: 'application/pdf',
+      dependsOnReferencedFiles: true,
     })
     expect(mockReadWorkspaceFileMetadata).not.toHaveBeenCalled()
     expect(mockReadWorkspaceFileContent).not.toHaveBeenCalled()