feat: establish durable file ownership and rollout compatibility

Add canonical entity ownership while preserving legacy workspace writers.
Make storage accounting, lifecycle cleanup, search, document artifacts, and
realtime transport tolerate project-owned data before feature activation.

Keep Project file user/API/tool entry points in the stacked feature change.

Author: mzxchandra

.github/workflows/test-build.yml

@@ -10,7 +10,7 @@ permissions:
 jobs:
   postgres-integration:
     # Runs the real-infrastructure test layer: every `*.integration.ts` in packages/db and
-    # apps/sim, discovered by glob (`vitest run --mode integration`), against the database each
+    # apps/sim and apps/realtime, discovered by glob (`vitest run --mode integration`), against the database each
     # provisioning path produces. A new integration suite needs no workflow change.
     name: PostgreSQL integration (${{ matrix.provision }})
     runs-on: ${{ (vars.CI_PROVIDER == '' || vars.CI_PROVIDER == 'blacksmith') && 'blacksmith-8vcpu-ubuntu-2404' || 'ubuntu-latest' }}
@@ -94,6 +94,10 @@ jobs:
           TZ: America/Los_Angeles
         run: bun run test --mode integration
 
+      - name: Run apps/realtime integration tests
+        working-directory: apps/realtime
+        run: bun run test --mode integration
+
       - name: Verify cumulative billing timeout recovery on PostgreSQL 16
         if: matrix.provision == 'push'
         working-directory: apps/sim
@@ -111,6 +115,7 @@ jobs:
           path: |
             packages/db/test-results/*.json
             apps/sim/test-results/*.json
+            apps/realtime/test-results/*.json
           if-no-files-found: warn
           retention-days: 14
 

apps/realtime/src/access-revalidation.ts

@@ -1,8 +1,10 @@
 import { createLogger } from '@sim/logger'
 import { ROOM_MEMBERSHIP_ACTIONS, satisfiesRoomMembership } from '@sim/platform-authz/room-policy'
 import type { AccessRevokedBroadcast } from '@sim/realtime-protocol/events'
+import { FILE_DOC_EVENTS, type FileDocPermission } from '@sim/realtime-protocol/file-doc'
 import {
   parseRoomName,
+  projectFileDocTarget,
   ROOM_TYPES,
   type RoomRef,
   type RoomType,
@@ -327,11 +329,21 @@ export function startAccessRevalidationSweep(roomManager: IRoomManager): AccessR
         // resolution keeps running in the background and is re-raced when the
         // rotation returns to this socket, so it is acted on once it settles.
         const role = await Promise.race([
-          resolveCurrentRoomPermission(userId, room, fallbackRoleFor(room.type)),
+          room.type === ROOM_TYPES.PROJECT_FILE_DOC
+            ? resolveCurrentRoomPermission(userId, room, fallbackRoleFor(room.type), socket.id)
+            : resolveCurrentRoomPermission(userId, room, fallbackRoleFor(room.type)),
           sleep(Math.min(SCAN_SOCKET_TIMEOUT_MS, remainingBudget)).then(() => SCAN_TIMED_OUT),
         ])
         // {@link SCAN_TIMED_OUT} is the only symbol this race can yield; matching on
         // the type narrows it out of the permission comparison below.
+        if (typeof role !== 'symbol' && room.type === ROOM_TYPES.PROJECT_FILE_DOC) {
+          const target = projectFileDocTarget(room)
+          if (target)
+            socket.emit(FILE_DOC_EVENTS.PERMISSION, {
+              ...target,
+              canWrite: role === 'write' || role === 'admin',
+            } satisfies FileDocPermission)
+        }
         if (typeof role === 'symbol') {
           logger.warn(
             `Authorization check timed out for user ${userId} on ${name}; skipping this pass`

apps/realtime/src/handlers/file-doc-app.ts

@@ -1,4 +1,5 @@
-import { FILE_DOC_TIMEOUTS } from '@sim/realtime-protocol/file-doc'
+import type { RoomAuthorizationResult } from '@sim/platform-authz/rooms'
+import { FILE_DOC_INTERNAL_HEADERS, FILE_DOC_TIMEOUTS } from '@sim/realtime-protocol/file-doc'
 import { env, getBaseUrl } from '@/env'
 
 /**
@@ -8,10 +9,24 @@ import { env, getBaseUrl } from '@/env'
  * timeouts (and their ordering vs. the app-side bounds) live in the shared `FILE_DOC_TIMEOUTS`.
  */
 
-function postToApp(path: string, payload: unknown, timeoutMs: number): Promise<Response> {
+function postToApp(
+  path: string,
+  payload: unknown,
+  timeoutMs: number,
+  actor?: { userId: string; connectionId: string }
+): Promise<Response> {
   return fetch(`${getBaseUrl()}${path}`, {
     method: 'POST',
-    headers: { 'Content-Type': 'application/json', 'x-api-key': env.INTERNAL_API_SECRET },
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': env.INTERNAL_API_SECRET,
+      ...(actor
+        ? {
+            [FILE_DOC_INTERNAL_HEADERS.userId]: actor.userId,
+            [FILE_DOC_INTERNAL_HEADERS.connectionId]: actor.connectionId,
+          }
+        : {}),
+    },
     body: JSON.stringify(payload),
     signal: AbortSignal.timeout(timeoutMs),
   })
@@ -123,3 +138,92 @@ export async function fetchFileDocPersist(
   }
   return body
 }
+
+interface ProjectDocumentRequest {
+  projectId: string
+  fileId: string
+  userId: string
+  connectionId: string
+}
+
+function projectDocumentPath(
+  target: ProjectDocumentRequest,
+  action: 'access' | 'seed' | 'persist'
+) {
+  return `/api/internal/project-file-doc/${encodeURIComponent(target.projectId)}/${encodeURIComponent(target.fileId)}/${action}`
+}
+
+/** Resolve current Project membership without manufacturing a workspace permission or identity. */
+export async function fetchProjectFileDocAccess(
+  target: ProjectDocumentRequest
+): Promise<RoomAuthorizationResult & { docId?: string | null }> {
+  const response = await postToApp(
+    projectDocumentPath(target, 'access'),
+    {},
+    FILE_DOC_TIMEOUTS.seedRequestMs,
+    target
+  )
+  if (response.status === 403 || response.status === 404) {
+    return { allowed: false, status: response.status, workspaceId: null, workspacePermission: null }
+  }
+  if (!response.ok) throw new Error(`Project document authorization failed: ${response.status}`)
+  const body = (await response.json()) as {
+    projectId?: unknown
+    fileId?: unknown
+    canRead?: unknown
+    canWrite?: unknown
+    docId?: unknown
+  }
+  if (
+    body.projectId !== target.projectId ||
+    body.fileId !== target.fileId ||
+    body.canRead !== true ||
+    typeof body.canWrite !== 'boolean' ||
+    (body.docId !== null &&
+      (typeof body.docId !== 'string' || !body.docId || body.docId.length > 128))
+  )
+    throw new Error('Malformed Project document authorization')
+  return {
+    allowed: true,
+    status: 200,
+    workspaceId: null,
+    workspacePermission: body.canWrite ? 'write' : 'read',
+    docId: body.docId,
+  }
+}
+
+/** Fetch a seed under the joining socket's current Project read access. */
+export async function fetchProjectFileDocSeed(
+  target: ProjectDocumentRequest
+): Promise<{ update: Uint8Array; version: number }> {
+  const response = await postToApp(
+    projectDocumentPath(target, 'seed'),
+    {},
+    FILE_DOC_TIMEOUTS.seedRequestMs,
+    target
+  )
+  if (!response.ok) throw new Error(`Project document seed failed: ${response.status}`)
+  const body = (await response.json()) as { update?: unknown; version?: unknown }
+  if (typeof body.update !== 'string' || typeof body.version !== 'number')
+    throw new Error('Malformed Project document seed')
+  return { update: new Uint8Array(Buffer.from(body.update, 'base64')), version: body.version }
+}
+
+/** Persist as the authenticated author captured with the accepted stream snapshot. */
+export async function fetchProjectFileDocPersist(
+  target: ProjectDocumentRequest,
+  docState: Uint8Array,
+  expectedVersion?: number
+): Promise<PersistResult> {
+  const response = await postToApp(
+    projectDocumentPath(target, 'persist'),
+    { docState: Buffer.from(docState).toString('base64'), expectedVersion },
+    FILE_DOC_TIMEOUTS.persistRequestMs,
+    target
+  )
+  if (!response.ok) throw new Error(`Project document persist failed: ${response.status}`)
+  const body = (await response.json()) as PersistResult
+  if (!['persisted', 'missing', 'conflict', 'deferred'].includes(body?.status))
+    throw new Error('Malformed Project document persist')
+  return body
+}