fix(files,realtime): issue a revision on revert and stop resurrecting cleared cursors (#8098)

* fix(files,realtime): issue a revision on revert and stop resurrecting cleared cursors

Follow-ups to review findings on the v0.8.48 release PR.

- POST /api/v2/files/:id/versions/:version/revert now returns the revision
  naming the content the file holds after the revert. A revert consumes the
  caller's revision, so without it chaining a second conditional write needed a
  metadata re-read, and the gap between the two reopened the TOCTOU window the
  revision exists to close.
- The presence roster merge now distinguishes an absent cursor from an explicit
  null. The fallback is load-bearing: the server rebuilds a socket's presence
  record on join, so a re-join broadcasts a roster with cursor omitted. But a
  null is a pointer the peer cleared, and coalescing both with ?? re-pinned a
  ghost cursor whenever the clearing cursor-update was missed.
- Corrected two File block output descriptions that named operations the block
  does not have: revision claimed a get operation (this block has Get Content,
  which emits no revision) and lineCount named insert, which is an edit mode.

Also collapses the five hand-rolled copies of the revision conditional spread
into workspaceFileRevisionField, beside the token it describes.

* fix(docs): match the revert example revision to its own record timestamp

The revert response example carried a revision token encoding
2026-01-16T09:12:00.000Z while its file and version showed
2026-01-15T10:30:00Z. A revision is base64url(fileId:contentUpdatedAt), so
the token has to name the record it ships with; every other example in the
document already pairs them, and the one using the later timestamp overrides
updatedAt to match. Echoing the old example back as expectedRevision would
have named content the response never described.

Author: waleedlatif1

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

@@ -4923,6 +4923,10 @@
           "version": {
             "description": "The current version of the file after the revert: a new `revert` version; the requested version when it was already current; or the unchanged current version when its content already matched the requested one.",
             "$ref": "#/components/schemas/V2FileVersion"
+          },
+          "revision": {
+            "description": "Opaque token for the content the file holds after the revert — the one it just wrote, or the unchanged current content when `reverted` is false. Send it back as `expectedRevision` on the next write.",
+            "type": "string"
           }
         },
         "required": ["reverted", "file", "version"],
@@ -4976,7 +4980,8 @@
                 "createdAt": "2026-01-15T10:30:00Z",
                 "updatedAt": "2026-01-15T10:30:00Z",
                 "supersededAt": null
-              }
+              },
+              "revision": "d2ZfVjFTdEdYUjh6NWpkSGk2Qm15VDkxOjIwMjYtMDEtMTVUMTA6MzA6MDAuMDAwWg"
             }
           }
         ]

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

@@ -5,7 +5,7 @@ import {
 import { defineV2JsonRoute, v2ApiKeyAuth, v2RateLimits } from '@/lib/api/server/routes'
 import { v2FileErrorPolicies } from '@/lib/workspace-files/api'
 import { editWorkspaceFileContent } from '@/lib/workspace-files/application/edit-workspace-file-content'
-import { workspaceFileRevision } from '@/lib/workspace-files/application/file-revision'
+import { workspaceFileRevisionField } from '@/lib/workspace-files/application/file-revision'
 import { fileOperations } from '@/lib/workspace-files/application/operations'
 import {
   admitUpdateWorkspaceFileContent,
@@ -40,10 +40,9 @@ export const PUT = defineV2JsonRoute({
     expectedRevision: body.expectedRevision,
   }),
   useCase: updateWorkspaceFileContent,
-  present: async ({ file }) => {
-    const revision = workspaceFileRevision(file)
-    return { data: { ...(await toV2File(file)), ...(revision === null ? {} : { revision }) } }
-  },
+  present: async ({ file }) => ({
+    data: { ...(await toV2File(file)), ...workspaceFileRevisionField(file) },
+  }),
 })
 
 /**
@@ -78,10 +77,7 @@ export const PATCH = defineV2JsonRoute({
     expectedRevision: body.expectedRevision,
   }),
   useCase: editWorkspaceFileContent,
-  present: async ({ file, lineCount }) => {
-    const revision = workspaceFileRevision(file)
-    return {
-      data: { file: await toV2File(file), lineCount, ...(revision === null ? {} : { revision }) },
-    }
-  },
+  present: async ({ file, lineCount }) => ({
+    data: { file: await toV2File(file), lineCount, ...workspaceFileRevisionField(file) },
+  }),
 })

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

@@ -1,7 +1,7 @@
 import { v2GetFileContract } from '@/lib/api/contracts/v2/files'
 import { defineV2JsonRoute, v2ApiKeyAuth, v2RateLimits } from '@/lib/api/server/routes'
 import { v2FileErrorPolicies } from '@/lib/workspace-files/api'
-import { workspaceFileRevision } from '@/lib/workspace-files/application/file-revision'
+import { workspaceFileRevisionField } from '@/lib/workspace-files/application/file-revision'
 import { fileOperations } from '@/lib/workspace-files/application/operations'
 import { readWorkspaceFileMetadataWithVersion } from '@/lib/workspace-files/application/read-workspace-file-metadata'
 import { toV2File } from '@/app/api/v2/files/utils'
@@ -30,15 +30,12 @@ export const GET = defineV2JsonRoute({
     includeDeleted: query.scope === 'archived',
   }),
   useCase: readWorkspaceFileMetadataWithVersion,
-  present: async ({ file, share }) => {
-    const revision = workspaceFileRevision(file)
-    return {
-      data: {
-        ...(await toV2File(file)),
-        share,
-        currentVersion: file.currentVersion,
-        ...(revision === null ? {} : { revision }),
-      },
-    }
-  },
+  present: async ({ file, share }) => ({
+    data: {
+      ...(await toV2File(file)),
+      share,
+      currentVersion: file.currentVersion,
+      ...workspaceFileRevisionField(file),
+    },
+  }),
 })

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

@@ -0,0 +1,163 @@
+/**
+ * @vitest-environment node
+ */
+import {
+  V2_OPERATION_RATE_LIMIT_ALLOWED,
+  V2_PREAUTH_RATE_LIMIT_ALLOWED,
+  v2ApiKeyAuthModuleMock,
+  v2RateLimiterModuleMock,
+  v2RouteMocks,
+} from '@sim/testing'
+import { NextRequest } from 'next/server'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  revertVersion: vi.fn(),
+  getUserEmailsByIds: vi.fn(),
+  findUserEmailsByIds: vi.fn(),
+}))
+
+vi.mock('@/lib/workspace-files/application/file-versions', () => ({
+  revertWorkspaceFileVersion: {
+    operation: { id: 'files.versions.revert', minimumRole: 'write', workspaceApiKey: 'allow' },
+    execute: mocks.revertVersion,
+  },
+}))
+
+vi.mock('@/lib/api/server/routes/v2-api-key-auth', () => v2ApiKeyAuthModuleMock)
+vi.mock('@/lib/core/rate-limiter', () => v2RateLimiterModuleMock)
+
+vi.mock('@/lib/users/queries', () => ({
+  getUserEmailsByIds: mocks.getUserEmailsByIds,
+  findUserEmailsByIds: mocks.findUserEmailsByIds,
+  requireResolvedUserEmail: (emails: Map<string, string>, userId: string) => emails.get(userId)!,
+}))
+
+import { workspaceFileRevision } from '@/lib/workspace-files/application/file-revision'
+import { POST } from '@/app/api/v2/files/[fileId]/versions/[version]/revert/route'
+
+const WORKSPACE_ID = 'workspace-1'
+const FILE_ID = 'wf_1'
+const auth = {
+  principal: {
+    kind: 'workspace_api_key' as const,
+    workspaceId: WORKSPACE_ID,
+    keyId: 'key-1',
+  },
+  rateLimitSubjectIds: ['api-key:key-1', `workspace:${WORKSPACE_ID}`] as const,
+  rateLimitSubscription: null,
+  keyType: 'workspace' as const,
+}
+
+const record = {
+  id: FILE_ID,
+  workspaceId: WORKSPACE_ID,
+  name: 'data.csv',
+  key: 'workspace/ws/1-x-data.csv',
+  path: '/api/files/serve/x',
+  size: 8,
+  type: 'text/csv',
+  uploadedBy: 'user-1',
+  folderId: null,
+  uploadedAt: new Date('2024-01-01T00:00:00Z'),
+  updatedAt: new Date('2024-01-03T00:00:00Z'),
+  contentUpdatedAt: new Date('2024-01-04T00:00:00Z'),
+}
+
+const versionRecord = {
+  fileId: FILE_ID,
+  version: 4,
+  isCurrent: true,
+  size: 8,
+  contentType: 'text/csv',
+  source: 'revert' as const,
+  authorUserIds: ['user-1'],
+  restoredFromVersion: 2,
+  createdAt: new Date('2024-01-04T00:00:00Z'),
+  updatedAt: new Date('2024-01-04T00:00:00Z'),
+  supersededAt: null,
+}
+
+const callRevert = (body: unknown) =>
+  POST(
+    new NextRequest(`http://localhost:3000/api/v2/files/${FILE_ID}/versions/2/revert`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    }),
+    { params: Promise.resolve({ fileId: FILE_ID, version: '2' }) }
+  )
+
+describe('POST /api/v2/files/[fileId]/versions/[version]/revert', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    v2RouteMocks.authenticate.mockResolvedValue(auth)
+    v2RouteMocks.preauthRate.mockResolvedValue(V2_PREAUTH_RATE_LIMIT_ALLOWED)
+    v2RouteMocks.operationRate.mockResolvedValue(V2_OPERATION_RATE_LIMIT_ALLOWED)
+    mocks.revertVersion.mockResolvedValue({
+      file: record,
+      version: versionRecord,
+      reverted: true,
+      revertedFrom: 3,
+    })
+    mocks.getUserEmailsByIds.mockResolvedValue(new Map([['user-1', 'ada@example.com']]))
+    mocks.findUserEmailsByIds.mockResolvedValue(new Map([['user-1', 'ada@example.com']]))
+  })
+
+  /**
+   * A revert consumes the caller's revision, so the response has to issue its replacement —
+   * otherwise chaining a second conditional write needs a metadata re-read, and the window
+   * between the two is exactly what the revision is meant to close.
+   */
+  it('returns the revision naming the content the revert produced', async () => {
+    const expectedRevision = workspaceFileRevision(record)!
+
+    const response = await callRevert({ workspaceId: WORKSPACE_ID, expectedRevision })
+
+    expect(response.status).toBe(200)
+    const body = await response.json()
+    expect(body.data.reverted).toBe(true)
+    expect(body.data.revision).toBe(expectedRevision)
+    expect(mocks.revertVersion).toHaveBeenCalledWith(
+      expect.objectContaining({
+        input: expect.objectContaining({
+          fileId: FILE_ID,
+          assertedWorkspaceId: WORKSPACE_ID,
+          version: 2,
+          expectedRevision,
+        }),
+      })
+    )
+  })
+
+  it('returns the current content revision when the version was already current', async () => {
+    mocks.revertVersion.mockResolvedValue({
+      file: record,
+      version: { ...versionRecord, version: 3, source: 'api', restoredFromVersion: null },
+      reverted: false,
+      revertedFrom: 3,
+    })
+
+    const body = await (await callRevert({ workspaceId: WORKSPACE_ID })).json()
+
+    expect(body.data.reverted).toBe(false)
+    expect(body.data.revision).toBe(workspaceFileRevision(record))
+  })
+
+  it('forwards the caller revision precondition to the use case', async () => {
+    const expectedRevision = workspaceFileRevision(record)!
+
+    await callRevert({ workspaceId: WORKSPACE_ID, expectedRevision })
+
+    expect(mocks.revertVersion).toHaveBeenCalledWith(
+      expect.objectContaining({
+        input: expect.objectContaining({
+          fileId: FILE_ID,
+          assertedWorkspaceId: WORKSPACE_ID,
+          version: 2,
+          expectedRevision,
+        }),
+      })
+    )
+  })
+})

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

@@ -1,6 +1,7 @@
 import { v2RevertFileVersionContract } from '@/lib/api/contracts/v2/file-versions'
 import { defineV2JsonRoute, v2ApiKeyAuth, v2RateLimits } from '@/lib/api/server/routes'
 import { v2FileErrorPolicies } from '@/lib/workspace-files/api'
+import { workspaceFileRevisionField } from '@/lib/workspace-files/application/file-revision'
 import { revertWorkspaceFileVersion } from '@/lib/workspace-files/application/file-versions'
 import { fileOperations } from '@/lib/workspace-files/application/operations'
 import { toV2File, toV2FileVersion } from '@/app/api/v2/files/utils'
@@ -13,6 +14,9 @@ export const revalidate = 0
  *
  * Writes the version's bytes as a new version, so the revert can itself be reverted. Reverting to
  * the current version is a no-op that reports `reverted: false`.
+ *
+ * A revert invalidates the revision the caller guarded it with, so the response carries the one
+ * naming the content the file now holds.
  */
 export const POST = defineV2JsonRoute({
   contract: v2RevertFileVersionContract,
@@ -30,6 +34,13 @@ export const POST = defineV2JsonRoute({
   useCase: revertWorkspaceFileVersion,
   present: async ({ file, version, reverted }) => {
     const [v2File, v2Version] = await Promise.all([toV2File(file), toV2FileVersion(version)])
-    return { data: { reverted, file: v2File, version: v2Version } }
+    return {
+      data: {
+        reverted,
+        file: v2File,
+        version: v2Version,
+        ...workspaceFileRevisionField(file),
+      },
+    }
   },
 })

apps/sim/app/workspace/providers/socket-presence-merge.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest'
+import { mergePresenceRoster } from '@/app/workspace/providers/socket-presence-merge'
+import type { PresenceUser } from '@/stores/presence/types'
+
+function peer(overrides: Partial<PresenceUser> = {}): PresenceUser {
+  return {
+    socketId: 'socket-1',
+    userId: 'user-1',
+    userName: 'Ada',
+    ...overrides,
+  }
+}
+
+describe('mergePresenceRoster', () => {
+  it('clears the pointer when the roster carries an explicit null cursor', () => {
+    const previous = [peer({ cursor: { x: 10, y: 20 } })]
+
+    const merged = mergePresenceRoster(previous, [peer({ cursor: null })])
+
+    expect(merged[0].cursor).toBeNull()
+  })
+
+  it('keeps the known pointer when the roster omits the cursor', () => {
+    const previous = [peer({ cursor: { x: 10, y: 20 } })]
+
+    const merged = mergePresenceRoster(previous, [peer()])
+
+    expect(merged[0].cursor).toEqual({ x: 10, y: 20 })
+  })
+
+  it('keeps the known selection when the roster omits it', () => {
+    const previous = [peer({ selection: { type: 'block', id: 'block-1' } })]
+
+    const merged = mergePresenceRoster(previous, [peer()])
+
+    expect(merged[0].selection).toEqual({ type: 'block', id: 'block-1' })
+  })
+
+  it('applies a cleared selection, which the wire spells as type none', () => {
+    const previous = [peer({ selection: { type: 'block', id: 'block-1' } })]
+
+    const merged = mergePresenceRoster(previous, [peer({ selection: { type: 'none' } })])
+
+    expect(merged[0].selection).toEqual({ type: 'none' })
+  })
+
+  it('passes through a peer it has no previous presence for', () => {
+    const joining = peer({ socketId: 'socket-2', userId: 'user-2', cursor: { x: 1, y: 2 } })
+
+    expect(mergePresenceRoster([], [joining])).toEqual([joining])
+  })
+
+  it('drops peers the roster no longer lists', () => {
+    const previous = [peer(), peer({ socketId: 'socket-2', userId: 'user-2' })]
+
+    const merged = mergePresenceRoster(previous, [peer()])
+
+    expect(merged.map((user) => user.socketId)).toEqual(['socket-1'])
+  })
+})

apps/sim/app/workspace/providers/socket-presence-merge.ts

@@ -0,0 +1,32 @@
+import type { PresenceUser } from '@/stores/presence/types'
+
+/**
+ * Folds a `presence-update` roster over the presence already held for each socket.
+ *
+ * The server rebuilds a socket's presence record from scratch when it joins a room, so a re-join
+ * of the same workflow broadcasts a roster whose `cursor` and `selection` are simply absent. The
+ * fields are carried over rather than blanked, which is what keeps a peer's pointer from
+ * flickering on every re-join.
+ *
+ * A `null` `cursor` is therefore not the same as an absent one: it is a pointer the peer
+ * explicitly cleared on leaving the canvas. Coalescing the two with `??` would resurrect a stale
+ * pointer whenever the clearing `cursor-update` was missed — dropped by the visibility gate
+ * during a join, or by a rejoin that never refreshed the roster. `selection` needs no such
+ * split: a cleared selection is `{ type: 'none' }`, and the wire type admits no `null`.
+ */
+export function mergePresenceRoster(
+  previous: PresenceUser[],
+  incoming: PresenceUser[]
+): PresenceUser[] {
+  const previousBySocketId = new Map(previous.map((user) => [user.socketId, user]))
+
+  return incoming.map((user) => {
+    const existing = previousBySocketId.get(user.socketId)
+    if (!existing) return user
+    return {
+      ...user,
+      cursor: user.cursor === undefined ? existing.cursor : user.cursor,
+      selection: user.selection ?? existing.selection,
+    }
+  })
+}