fix(files): bound file version retention per run and document both coalescing cutoffs

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. 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`.",
+        "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, and repeated workflow writes by one author, fold into the current version while it is under ten minutes old and written in the last five. Renames and moves are not versions. An empty file is version 1 until its first content replaces it. Retention keeps the newest ten, so numbers can have gaps.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "files.versions.list",
         "x-oauth-scope": "api:read",
         "tags": ["Files"],

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

@@ -6,6 +6,7 @@ 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 {
+  DEFAULT_BATCH_SIZE,
   DEFAULT_DELETE_CHUNK_SIZE,
   DEFAULT_MAX_BATCHES_PER_TABLE,
   DEFAULT_WORKSPACE_CHUNK_SIZE,
@@ -22,6 +23,12 @@ const cleanupDb = dbFor('cleanup')
 /** Candidate files whose histories are ranked in one query. */
 const FILES_PER_QUERY = 500
 
+/**
+ * Bounds one run like the other cleanup jobs: {@link DEFAULT_MAX_BATCHES_PER_TABLE} batches per
+ * workspace chunk and this many versions overall. The next run resumes where this one stopped.
+ */
+const MAX_VERSIONS_PER_RUN = DEFAULT_BATCH_SIZE * DEFAULT_MAX_BATCHES_PER_TABLE
+
 /**
  * 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.
@@ -146,16 +153,26 @@ export async function runCleanupFileVersions(payload: CleanupJobPayload): Promis
   )
 
   let deleted = 0
+  let attempted = 0
   for (const group of chunkArray(workspaceIds, DEFAULT_WORKSPACE_CHUNK_SIZE)) {
+    if (attempted >= MAX_VERSIONS_PER_RUN) break
     const candidates = await selectCandidateFileIds(group, cutoff, maxSuperseded)
+    let batches = 0
     for (const fileIds of chunkArray(candidates, FILES_PER_QUERY)) {
-      for (let batch = 0; batch < DEFAULT_MAX_BATCHES_PER_TABLE; batch++) {
+      let exhausted = false
+      while (
+        !exhausted &&
+        batches < DEFAULT_MAX_BATCHES_PER_TABLE &&
+        attempted < MAX_VERSIONS_PER_RUN
+      ) {
+        batches++
         const expired = await selectExpiredVersions(fileIds, cutoff, maxSuperseded)
-        if (expired.length === 0) break
-        const removed = await deleteVersions(expired)
+        attempted += expired.length
+        const removed = expired.length > 0 ? await deleteVersions(expired) : 0
         deleted += removed
-        if (expired.length < DEFAULT_DELETE_CHUNK_SIZE || removed === 0) break
+        exhausted = expired.length < DEFAULT_DELETE_CHUNK_SIZE || removed === 0
       }
+      if (!exhausted) break
     }
   }
 

apps/sim/lib/api/contracts/v2/openapi/files-audit.ts

@@ -447,7 +447,7 @@ const declaredRoutes = [
       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. 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.',
+        'List the versions of a file, newest first by default. Each write that changes the bytes records one; identical rewrites do not. Collaborative edits, and repeated workflow writes by one author, fold into the current version while it is under ten minutes old and written in the last five. Renames and moves are not versions. An empty file is version 1 until its first content replaces it. Retention keeps the newest ten, so numbers can have gaps.',
       errors: RESOURCE_ERRORS,
       success: { description: 'A page of file versions.' },
     }),

apps/sim/lib/api/mcp/generated/v2-operations.ts

@@ -1425,7 +1425,7 @@ export const V2_MCP_OPERATIONS = {
     contract: v2ListFileVersionsContract,
     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. 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`.',
+      'List the versions of a file, newest first by default. Each write that changes the bytes records one; identical rewrites do not. Collaborative edits, and repeated workflow writes by one author, fold into the current version while it is under ten minutes old and written in the last five. Renames and moves are not versions. An empty file is version 1 until its first content replaces it. Retention keeps the newest ten, so numbers can have gaps.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/files/[fileId]/versions/route').then((route) => route.GET),
   },
   listKnowledgeBases: {