improvement(files): simplify file version history internals

- read metadata and its current version in one statement; drop the retry and 409
- move provenance policy branching into the provenance module
- project stored provenance out of list, head, and get reads; revert reads it on demand
- chunk storage-cleanup enqueues to the outbox bulk limit in one place
- drop the write-only content_updated_at version column (unreleased 0365)
- reuse findCause, the shared cleanup batch constants, and the version-number primitives
- share the v2 text presenter between the file and version routes

Author: waleedlatif1

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

@@ -868,7 +868,7 @@
       "get": {
         "operationId": "listFileVersions",
         "summary": "List File Versions",
-        "description": "List the versions of a file, newest first by default. Each write that changes the bytes records one; identical rewrites do not, and collaborative edits or repeated workflow writes by one author within ten minutes fold into one. Renames and moves are not versions. An empty file is version 1 until its first content replaces it. Retention keeps the newest ten and removes older versions by plan, so numbers can have gaps.\n\nOAuth scope: `api:read`.",
+        "description": "List the versions of a file, newest first by default. Each write that changes the bytes records one; identical rewrites do not. Collaborative edits within ten minutes fold into one version, as do repeated workflow writes by one author. Renames and moves are not versions. An empty file is version 1 until its first content replaces it. Retention keeps the newest ten and removes older versions by plan, so numbers can have gaps.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "files.versions.list",
         "x-oauth-scope": "api:read",
         "tags": ["Files"],
@@ -2068,7 +2068,7 @@
       "get": {
         "operationId": "getFile",
         "summary": "Get File Metadata",
-        "description": "Get file metadata, its public-share configuration, and the version number of its current content. The `share` field is null when the file has never been shared. `currentVersion` identifies the content in List File Versions and is the precondition Revert File Version accepts. A file rewritten continuously while it is read returns `409`; retry.\n\nOAuth scope: `api:read`.",
+        "description": "Get file metadata, its public-share configuration, and the version number of its current content. The `share` field is null when the file has never been shared. `currentVersion` identifies the content in List File Versions and is the precondition Revert File Version accepts.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "files.read_metadata",
         "x-oauth-scope": "api:read",
         "tags": ["Files"],
@@ -2145,9 +2145,6 @@
           "404": {
             "$ref": "#/components/responses/NotFound"
           },
-          "409": {
-            "$ref": "#/components/responses/Conflict"
-          },
           "429": {
             "$ref": "#/components/responses/RateLimited"
           },

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

@@ -84,9 +84,8 @@ const callGet = (query: string) =>
 const archivedFileUseCase = async ({ input }: { input: { includeDeleted?: boolean } }) => {
   if (!input.includeDeleted) throw new OrchestrationError('not_found', 'File not found')
   return {
-    file: { ...buildRecord(), deletedAt: new Date('2024-01-03T00:00:00Z') },
+    file: { ...buildRecord(), deletedAt: new Date('2024-01-03T00:00:00Z'), currentVersion: 3 },
     share: SHARE,
-    currentVersion: 3,
   }
 }
 
@@ -96,7 +95,10 @@ describe('GET /api/v2/files/[fileId]/metadata', () => {
     v2RouteMocks.authenticate.mockResolvedValue(auth)
     v2RouteMocks.preauthRate.mockResolvedValue(V2_PREAUTH_RATE_LIMIT_ALLOWED)
     v2RouteMocks.operationRate.mockResolvedValue(V2_OPERATION_RATE_LIMIT_ALLOWED)
-    mocks.readMetadata.mockResolvedValue({ file: buildRecord(), share: SHARE, currentVersion: 3 })
+    mocks.readMetadata.mockResolvedValue({
+      file: { ...buildRecord(), currentVersion: 3 },
+      share: SHARE,
+    })
     mocks.getUserEmailsByIds.mockResolvedValue(new Map([['user-1', 'ada@example.com']]))
   })
 
@@ -244,9 +246,8 @@ describe('GET /api/v2/files/[fileId]/metadata', () => {
 
   it('returns a null share when the file has no share configuration', async () => {
     mocks.readMetadata.mockResolvedValueOnce({
-      file: buildRecord(),
+      file: { ...buildRecord(), currentVersion: 3 },
       share: null,
-      currentVersion: 3,
     })
 
     const response = await callGet(`workspaceId=${WORKSPACE_ID}`)

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

@@ -29,7 +29,7 @@ export const GET = defineV2JsonRoute({
     includeDeleted: query.scope === 'archived',
   }),
   useCase: readWorkspaceFileMetadataWithVersion,
-  present: async ({ file, share, currentVersion }) => ({
-    data: { ...(await toV2File(file)), share, currentVersion },
+  present: async ({ file, share }) => ({
+    data: { ...(await toV2File(file)), share, currentVersion: file.currentVersion },
   }),
 })

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

@@ -3,6 +3,7 @@ import { defineV2JsonRoute, v2ApiKeyAuth, v2RateLimits } from '@/lib/api/server/
 import { v2FileErrorPolicies } from '@/lib/workspace-files/api'
 import { fileOperations } from '@/lib/workspace-files/application/operations'
 import { readWorkspaceFileText } from '@/lib/workspace-files/application/read-workspace-file-text'
+import { toV2FileText } from '@/app/api/v2/files/utils'
 
 export const dynamic = 'force-dynamic'
 
@@ -39,18 +40,5 @@ export const GET = defineV2JsonRoute({
     limit: query.limit,
   }),
   useCase: readWorkspaceFileText,
-  present: ({ file, text, truncated, degraded, degradedReason, byteCount, lineRange }) => ({
-    data: {
-      fileId: file.id,
-      name: file.name,
-      type: file.type,
-      text,
-      truncated,
-      degraded,
-      degradedReason,
-      charCount: text.length,
-      byteCount,
-      ...(lineRange ? { lineRange } : {}),
-    },
-  }),
+  present: (result) => ({ data: toV2FileText(result) }),
 })

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

@@ -3,6 +3,7 @@ import { defineV2JsonRoute, v2ApiKeyAuth, v2RateLimits } from '@/lib/api/server/
 import { v2FileErrorPolicies } from '@/lib/workspace-files/api'
 import { readWorkspaceFileVersionText } from '@/lib/workspace-files/application/file-versions'
 import { fileOperations } from '@/lib/workspace-files/application/operations'
+import { toV2FileText } from '@/app/api/v2/files/utils'
 
 export const dynamic = 'force-dynamic'
 
@@ -27,28 +28,5 @@ export const GET = defineV2JsonRoute({
     limit: query.limit,
   }),
   useCase: readWorkspaceFileVersionText,
-  present: ({
-    file,
-    version,
-    text,
-    truncated,
-    degraded,
-    degradedReason,
-    byteCount,
-    lineRange,
-  }) => ({
-    data: {
-      fileId: file.id,
-      version: version.version,
-      name: file.name,
-      type: version.contentType,
-      text,
-      truncated,
-      degraded,
-      degradedReason,
-      charCount: text.length,
-      byteCount,
-      ...(lineRange ? { lineRange } : {}),
-    },
-  }),
+  present: (result) => ({ data: { ...toV2FileText(result), version: result.version.version } }),
 })

apps/sim/app/api/v2/files/utils.test.ts

@@ -27,7 +27,6 @@ const version: WorkspaceFileVersionRecord = {
   createdAt: new Date('2026-01-02T00:00:00Z'),
   updatedAt: new Date('2026-01-02T00:05:00Z'),
   supersededAt: null,
-  secretProvenance: { status: 'exact', entries: [] },
 }
 
 describe('toV2FileVersions', () => {

apps/sim/app/api/v2/files/utils.ts

@@ -1,5 +1,5 @@
 import type { V2FileVersion } from '@/lib/api/contracts/v2/file-versions'
-import type { V2File } from '@/lib/api/contracts/v2/files'
+import type { V2File, V2FileText } from '@/lib/api/contracts/v2/files'
 import { getBaseUrl } from '@/lib/core/utils/urls'
 import { buildFolderPath } from '@/lib/folders/paths'
 import { workspaceResourceWebUrl } from '@/lib/resources'
@@ -10,6 +10,7 @@ import {
   getUserEmailsByIds,
   requireResolvedUserEmail,
 } from '@/lib/users/queries'
+import type { ReadWorkspaceFileTextResult } from '@/lib/workspace-files/application/read-workspace-file-text'
 import { parseWorkspaceFileFolderDisplayPath } from '@/lib/workspace-files/folder-display-path'
 
 /** Shared serialization for the v2 files surface. */
@@ -66,6 +67,30 @@ export async function toV2Files(records: WorkspaceFileRecord[]): Promise<V2File[
   )
 }
 
+/** Serializes extracted text for the file or version the result was read from. */
+export function toV2FileText({
+  file,
+  text,
+  truncated,
+  degraded,
+  degradedReason,
+  byteCount,
+  lineRange,
+}: ReadWorkspaceFileTextResult): V2FileText {
+  return {
+    fileId: file.id,
+    name: file.name,
+    type: file.type,
+    text,
+    truncated,
+    degraded,
+    degradedReason,
+    charCount: text.length,
+    byteCount,
+    ...(lineRange ? { lineRange } : {}),
+  }
+}
+
 function serializeV2FileVersion(
   record: WorkspaceFileVersionRecord,
   emailByUserId: Map<string, string>

apps/sim/background/cleanup-file-versions.ts

@@ -5,8 +5,11 @@ import { chunkArray } from '@sim/utils/helpers'
 import { task } from '@trigger.dev/sdk'
 import { and, count, gt, inArray, isNotNull, lt, min, or, sql } from 'drizzle-orm'
 import type { CleanupJobPayload } from '@/lib/billing/cleanup-dispatcher'
-import type { PlanCategory } from '@/lib/billing/plan-helpers'
-import { DEFAULT_DELETE_CHUNK_SIZE } from '@/lib/cleanup/batch-delete'
+import {
+  DEFAULT_DELETE_CHUNK_SIZE,
+  DEFAULT_MAX_BATCHES_PER_TABLE,
+  DEFAULT_WORKSPACE_CHUNK_SIZE,
+} from '@/lib/cleanup/batch-delete'
 import { retentionCleanupQueue } from '@/lib/cleanup/queue'
 import { enqueueWorkspaceFileStorageCleanups } from '@/lib/uploads/contexts/workspace/workspace-file-storage-cleanup-outbox'
 import { MAX_SUPERSEDED_FILE_VERSIONS } from '@/lib/uploads/contexts/workspace/workspace-file-versions'
@@ -16,31 +19,20 @@ const logger = createLogger('CleanupFileVersions')
 /** All cleanup queries run on the dedicated cleanup pool. */
 const cleanupDb = dbFor('cleanup')
 
-/** Workspaces whose candidate files are found in one query. */
-const WORKSPACES_PER_QUERY = 50
 /** Candidate files whose histories are ranked in one query. */
 const FILES_PER_QUERY = 500
-const VERSIONS_PER_BATCH = 1000
-/** Bounds one run's work per file chunk; the next daily run continues where this stopped. */
-const MAX_BATCHES_PER_CHUNK = 50
 
 /**
- * Most superseded versions a file keeps, per plan; any beyond it are pruned whatever their age. Free
- * keeps its newest 100 versions (the current one included); every other plan is bounded only by the
- * inline write-time ceiling.
+ * Superseded versions a free file keeps (its newest 100 with the current one); versions beyond it
+ * are pruned whatever their age. Paid plans are bounded only by the inline write-time ceiling.
  */
-const MAX_SUPERSEDED_VERSIONS_BY_PLAN: Record<PlanCategory, number> = {
-  free: 99,
-  pro: MAX_SUPERSEDED_FILE_VERSIONS,
-  team: MAX_SUPERSEDED_FILE_VERSIONS,
-  enterprise: MAX_SUPERSEDED_FILE_VERSIONS,
-}
-
-/** Retention never prunes the newest versions of a file, whatever their age. */
-const FILE_VERSION_RETENTION_KEEP_LATEST = 10
+const FREE_MAX_SUPERSEDED_VERSIONS = 99
 
-/** Newest superseded versions a file keeps whatever their age (the current version is the tenth). */
-const KEEP_SUPERSEDED = FILE_VERSION_RETENTION_KEEP_LATEST - 1
+/**
+ * Newest superseded versions retention never prunes, whatever their age, so a file always keeps its
+ * newest ten versions with the current one.
+ */
+const KEEP_SUPERSEDED = 9
 
 /**
  * Files in the group that can lose any version: more superseded versions than the keep-latest floor,
@@ -79,7 +71,7 @@ async function selectCandidateFileIds(
 
 /**
  * Superseded versions of the given files past retention: older than the cutoff or beyond the plan's
- * count, but never among the newest {@link FILE_VERSION_RETENTION_KEEP_LATEST} versions of a file.
+ * count, but never among the newest {@link KEEP_SUPERSEDED} superseded versions of a file.
  */
 function selectExpiredVersions(fileIds: string[], cutoff: Date, maxSuperseded: number) {
   const ranked = cleanupDb
@@ -108,38 +100,34 @@ function selectExpiredVersions(fileIds: string[], cutoff: Date, maxSuperseded: n
         or(lt(ranked.supersededAt, cutoff), gt(ranked.rank, maxSuperseded))
       )
     )
-    .limit(VERSIONS_PER_BATCH)
+    .limit(DEFAULT_DELETE_CHUNK_SIZE)
 }
 
 /**
  * Deletes the expired version rows and enqueues their stored objects on the storage-cleanup outbox
  * in the same transaction, so a row never outlives its release and every released object is
  * deleted durably — the outbox retries failures and treats an already-missing object as done.
  */
-async function deleteVersions(rows: Array<{ id: string }>) {
-  let deleted = 0
-  for (const batch of chunkArray(rows, DEFAULT_DELETE_CHUNK_SIZE)) {
-    deleted += await cleanupDb.transaction(async (tx) => {
-      const removed = await tx
-        .delete(workspaceFileVersion)
-        .where(
-          and(
-            inArray(
-              workspaceFileVersion.id,
-              batch.map((row) => row.id)
-            ),
-            isNotNull(workspaceFileVersion.supersededAt)
-          )
+function deleteVersions(rows: Array<{ id: string }>): Promise<number> {
+  return cleanupDb.transaction(async (tx) => {
+    const removed = await tx
+      .delete(workspaceFileVersion)
+      .where(
+        and(
+          inArray(
+            workspaceFileVersion.id,
+            rows.map((row) => row.id)
+          ),
+          isNotNull(workspaceFileVersion.supersededAt)
         )
-        .returning({ key: workspaceFileVersion.key })
-      await enqueueWorkspaceFileStorageCleanups(
-        tx,
-        removed.map((row) => row.key)
       )
-      return removed.length
-    })
-  }
-  return deleted
+      .returning({ key: workspaceFileVersion.key })
+    await enqueueWorkspaceFileStorageCleanups(
+      tx,
+      removed.map((row) => row.key)
+    )
+    return removed.length
+  })
 }
 
 export async function runCleanupFileVersions(payload: CleanupJobPayload): Promise<void> {
@@ -151,21 +139,22 @@ export async function runCleanupFileVersions(payload: CleanupJobPayload): Promis
   }
 
   const cutoff = new Date(Date.now() - retentionHours * 60 * 60 * 1000)
-  const maxSuperseded = MAX_SUPERSEDED_VERSIONS_BY_PLAN[plan]
+  const maxSuperseded =
+    plan === 'free' ? FREE_MAX_SUPERSEDED_VERSIONS : MAX_SUPERSEDED_FILE_VERSIONS
   logger.info(
     `[${label}] Processing ${workspaceIds.length} workspaces, cutoff: ${cutoff.toISOString()}`
   )
 
   let deleted = 0
-  for (const group of chunkArray(workspaceIds, WORKSPACES_PER_QUERY)) {
+  for (const group of chunkArray(workspaceIds, DEFAULT_WORKSPACE_CHUNK_SIZE)) {
     const candidates = await selectCandidateFileIds(group, cutoff, maxSuperseded)
     for (const fileIds of chunkArray(candidates, FILES_PER_QUERY)) {
-      for (let batch = 0; batch < MAX_BATCHES_PER_CHUNK; batch++) {
+      for (let batch = 0; batch < DEFAULT_MAX_BATCHES_PER_TABLE; batch++) {
         const expired = await selectExpiredVersions(fileIds, cutoff, maxSuperseded)
         if (expired.length === 0) break
         const removed = await deleteVersions(expired)
         deleted += removed
-        if (expired.length < VERSIONS_PER_BATCH || removed === 0) break
+        if (expired.length < DEFAULT_DELETE_CHUNK_SIZE || removed === 0) break
       }
     }
   }

apps/sim/lib/api/contracts/deployments.test.ts

@@ -1,9 +1,9 @@
 import { describe, expect, it } from 'vitest'
 import {
-  DEPLOYMENT_VERSION_MAX,
   deploymentVersionOrActiveParamsSchema,
   deploymentVersionParamsSchema,
 } from '@/lib/api/contracts/deployments'
+import { INT4_MAX } from '@/lib/api/contracts/primitives'
 
 describe('deployment version route params', () => {
   it('coerces numeric path params from the server boundary', () => {
@@ -32,12 +32,10 @@ describe('deployment version route params', () => {
   it.each([deploymentVersionParamsSchema, deploymentVersionOrActiveParamsSchema])(
     'bounds the path version to the integer column range',
     (schema) => {
-      expect(
-        schema.safeParse({ id: 'workflow-1', version: String(DEPLOYMENT_VERSION_MAX) }).success
-      ).toBe(true)
-      expect(
-        schema.safeParse({ id: 'workflow-1', version: String(DEPLOYMENT_VERSION_MAX + 1) }).success
-      ).toBe(false)
+      expect(schema.safeParse({ id: 'workflow-1', version: String(INT4_MAX) }).success).toBe(true)
+      expect(schema.safeParse({ id: 'workflow-1', version: String(INT4_MAX + 1) }).success).toBe(
+        false
+      )
     }
   )
 })

apps/sim/lib/api/contracts/deployments.ts

@@ -1,9 +1,5 @@
 import { z } from 'zod'
-import {
-  INT4_MAX,
-  versionNumberPathSchema,
-  versionNumberSchema,
-} from '@/lib/api/contracts/primitives'
+import { versionNumberPathSchema } from '@/lib/api/contracts/primitives'
 import { defineRouteContract } from '@/lib/api/contracts/types'
 import { workflowIdParamsSchema } from '@/lib/api/contracts/workflows'
 import {
@@ -26,17 +22,6 @@ export const deployedWorkflowStateSchema = z
     additionalProperties: true,
   })
 
-/**
- * Upper bound of `workflow_deployment_version.version`, whose column is a
- * Postgres `integer`. A larger value has no row to address and overflows the
- * comparison instead of missing, so every schema carrying a deployment version
- * — path param, request body, or cursor payload — must be bounded by this.
- */
-export const DEPLOYMENT_VERSION_MAX = INT4_MAX
-
-/** A deployment version number, bounded to the range its column can hold. */
-export const deploymentVersionNumberSchema = versionNumberSchema
-
 export const deploymentVersionParamsSchema = z.object({
   id: z.string().min(1, 'Invalid workflow ID'),
   version: versionNumberPathSchema,