feat: establish shared file ownership foundation

.claude/rules/sim-testing.md

@@ -47,8 +47,9 @@ contracts, and demonstrated regressions.
   (`sim_test`); `TEST_REDIS_URL` must be loopback. `packages/db/testing/test-infrastructure.ts` owns
   those checks. Isolate with a unique schema or generated IDs, and clean up in `afterAll`.
 - Integration files run one at a time against one shared database. A new `*.integration.ts` is
-  picked up by CI with no workflow change, and the run writes `test-results/integration.json`, which
-  CI uploads. Never add a passing suite to the quarantine list in `apps/sim/vitest.config.ts`.
+  picked up by CI with no workflow change. By default, each workspace writes its generated report
+  to `<workspace>/test-results/integration.json`, which CI uploads. Never add a passing suite to the
+  quarantine list in `apps/sim/vitest.config.ts`.
 - `bun run test:integration` starts disposable Postgres and Redis containers, provisions the schema,
   and runs both workspaces; pass filenames to narrow the `apps/sim` run.
 

.cursor/rules/sim-testing.mdc

@@ -45,8 +45,9 @@ contracts, and demonstrated regressions.
   (`sim_test`); `TEST_REDIS_URL` must be loopback. `packages/db/testing/test-infrastructure.ts` owns
   those checks. Isolate with a unique schema or generated IDs, and clean up in `afterAll`.
 - Integration files run one at a time against one shared database. A new `*.integration.ts` is
-  picked up by CI with no workflow change, and the run writes `test-results/integration.json`, which
-  CI uploads. Never add a passing suite to the quarantine list in `apps/sim/vitest.config.ts`.
+  picked up by CI with no workflow change. By default, each workspace writes its generated report
+  to `<workspace>/test-results/integration.json`, which CI uploads. Never add a passing suite to the
+  quarantine list in `apps/sim/vitest.config.ts`.
 - `bun run test:integration` starts disposable Postgres and Redis containers, provisions the schema,
   and runs both workspaces; pass filenames to narrow the `apps/sim` run.
 

.github/scripts/resolve-audit-base.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ "$GITHUB_EVENT_NAME" = pull_request ]; then
+  git fetch --depth=1 origin "$GITHUB_BASE_REF"
+  echo "ref=origin/$GITHUB_BASE_REF" >> "$GITHUB_OUTPUT"
+elif [ "$GITHUB_EVENT_NAME" = workflow_dispatch ]; then
+  if [ "$GITHUB_REF_TYPE" != branch ]; then
+    echo 'Manual diff audits require a branch with exactly one open pull request.' >&2
+    exit 1
+  fi
+
+  pr_pages=$(gh api --method GET "repos/$GITHUB_REPOSITORY/pulls" \
+    -f state=open -f "head=${GITHUB_REPOSITORY%%/*}:$GITHUB_REF_NAME" --paginate --slurp)
+  matching_prs=$(jq -ce --arg repository "$GITHUB_REPOSITORY" --arg branch "$GITHUB_REF_NAME" \
+    '[.[][] | select(.state == "open" and .head.ref == $branch and .head.repo.full_name == $repository)]' \
+    <<< "$pr_pages")
+  if [ "$(jq 'length' <<< "$matching_prs")" != 1 ]; then
+    echo 'Manual diff audits require exactly one open pull request for the dispatched branch.' >&2
+    exit 1
+  fi
+  if [ "$(jq -r '.[0].head.sha' <<< "$matching_prs")" != "$GITHUB_SHA" ]; then
+    echo 'The pull request head changed after dispatch; dispatch again for its current head.' >&2
+    exit 1
+  fi
+
+  base_ref=$(jq -er '.[0].base.ref | select(type == "string" and length > 0)' <<< "$matching_prs")
+  if ! git check-ref-format "refs/heads/$base_ref"; then
+    echo 'The pull request did not provide a valid base branch.' >&2
+    exit 1
+  fi
+  git fetch --depth=1 origin "refs/heads/$base_ref"
+  base_sha=$(git rev-parse --verify 'FETCH_HEAD^{commit}')
+  echo "ref=$base_sha" >> "$GITHUB_OUTPUT"
+elif [ -n "${GITHUB_BEFORE:-}" ] &&
+     [ "$GITHUB_BEFORE" != 0000000000000000000000000000000000000000 ]; then
+  git fetch --depth=1 origin "$GITHUB_BEFORE"
+  echo "ref=$GITHUB_BEFORE" >> "$GITHUB_OUTPUT"
+else
+  echo 'ref=HEAD~1' >> "$GITHUB_OUTPUT"
+fi

.github/workflows/checks.yml

@@ -10,7 +10,7 @@ permissions:
 jobs:
   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.
     #
     # The two paths build different schemas (migrations add triggers, checks and NOT VALID
@@ -112,6 +112,11 @@ jobs:
           TZ: America/Los_Angeles
         run: bun run test --mode integration --shard=${{ matrix.shard }}/4
 
+      - name: Run apps/realtime integration tests
+        if: matrix.shard == 1
+        working-directory: apps/realtime
+        run: bun run test --mode integration
+
       - name: Verify cumulative billing timeout recovery on PostgreSQL 16
         if: matrix.provision == 'push' && matrix.shard == 1
         working-directory: apps/sim
@@ -129,6 +134,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
 
@@ -429,6 +435,9 @@ jobs:
   # kept off the test shards so neither waits on the other.
   lint:
     name: lint
+    permissions:
+      contents: read
+      pull-requests: read
     runs-on: *runner-4vcpu
     timeout-minutes: 15
 
@@ -518,19 +527,14 @@ jobs:
       # It is fetched by SHA at depth 1; the audits diff two tips and need no
       # common ancestry. An all-zero `before` means the branch is new and has no
       # predecessor to diff, so `HEAD~1` remains the fallback there.
+      # Manual runs pin the actual base SHA of the dispatched branch's unique open PR.
+      # A merge commit's first parent does not identify a stacked PR's review base.
       - name: Resolve base ref for diff-based audits
         id: audit_base
-        run: |
-          if [ "${{ github.event_name }}" = "pull_request" ]; then
-            git fetch --depth=1 origin "${{ github.base_ref }}"
-            echo "ref=origin/${{ github.base_ref }}" >> "$GITHUB_OUTPUT"
-          elif [ -n "${{ github.event.before }}" ] &&
-               [ "${{ github.event.before }}" != "0000000000000000000000000000000000000000" ]; then
-            git fetch --depth=1 origin "${{ github.event.before }}"
-            echo "ref=${{ github.event.before }}" >> "$GITHUB_OUTPUT"
-          else
-            echo "ref=HEAD~1" >> "$GITHUB_OUTPUT"
-          fi
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GITHUB_BEFORE: ${{ github.event.before }}
+        run: bash .github/scripts/resolve-audit-base.sh
 
       - name: Check block registry invariants
         run: bun run apps/sim/scripts/check-block-registry.ts "${{ steps.audit_base.outputs.ref }}"

.github/workflows/ci.yml

@@ -34,6 +34,9 @@ permissions:
 jobs:
   checks:
     name: checks
+    permissions:
+      contents: read
+      pull-requests: read
     if: github.ref != 'refs/heads/dev' || github.event_name == 'pull_request'
     uses: ./.github/workflows/checks.yml
 

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,
@@ -116,7 +118,7 @@ function collectScanTargets(io: IRoomManager['io']): ScanTarget[] {
     for (const name of socket.rooms) {
       if (name === socket.id) continue
       const ref = parseRoomName(name)
-      if (!ref) continue
+      if (!ref || ref.id.includes(':')) continue
       targets.push({ room: ref, name, socket: authed, userId: authed.userId })
     }
   }
@@ -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
+}