@preventive/triage 1.0.0-alpha.3 → 1.0.0-alpha.31

package/server-managed/storage-payload.ts

@@ -0,0 +1,72 @@
+import { Buffer } from 'node:buffer'
+import { createHash } from 'node:crypto'
+import { Readable, Writable } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
+import { createBrotliDecompress } from 'node:zlib'
+import { STORAGE_MAGIC } from '../server-common/storage-crypto.ts'
+import { type RawObject, isBlobId } from './object-storage.ts'
+import type { StorageRow, StorageRowKind } from './storage-db.ts'
+
+// A damaged/missing payload needs repair; retrying the whole cleanup job does
+// not fix it. Keep this distinct from database, storage and cancellation errors.
+export class StoragePayloadError extends Error {}
+
+export function storageRowPath(type: StorageRowKind, row: Pick<StorageRow, 'id' | 'kind'>): string {
+  return `${type === 'report' ? 'reports' : 'bundles'}/${row.id}${type === 'bundle' && row.kind === 'sourcemap' ? '.map.br' : ''}`
+}
+export function storageOwner(identity: string): { type: StorageRowKind; id: string; cache: boolean } | null {
+  const match = /^(reports|bundles)\/([^/]+)$/u.exec(identity)
+  if (match) {
+    const id = match[1] === 'bundles' ? match[2]!.replace(/\.map\.br$/u, '') : match[2]!
+    if (isBlobId(id)) return { type: match[1] === 'reports' ? 'report' : 'bundle', id, cache: false }
+  }
+  const cache = /^cache\/(?:bundles|report-sources)\/([a-f\d-]{36})\//u.exec(identity)
+  return cache && isBlobId(cache[1]!) ? { type: 'bundle', id: cache[1]!, cache: true } : null
+}
+
+// Peek without buffering the object or consuming bytes from its next reader.
+export async function inspectStorageObject(stored: RawObject): Promise<RawObject & { encrypted: boolean }> {
+  const original = stored.stream
+  const iterator = original[Symbol.asyncIterator]()
+  const first: Buffer[] = [], prefix = Buffer.alloc(STORAGE_MAGIC.length)
+  let length = 0
+  try {
+    while (length < prefix.length) {
+      const next = await iterator.next()
+      if (next.done) break
+      const bytes = Buffer.from(next.value)
+      first.push(bytes)
+      length += bytes.copy(prefix, length, 0, prefix.length - length)
+    }
+  } catch (err) { original.destroy(); throw err }
+  async function* joined() {
+    try {
+      yield* first
+      for (;;) { const next = await iterator.next(); if (next.done) return; yield next.value }
+    } finally { await iterator.return?.(); original.destroy() }
+  }
+  const stream = Readable.from(joined(), { objectMode: false })
+  stream.once('close', () => original.destroy())
+  return { ...stored, stream, encrypted: length === prefix.length && prefix.equals(STORAGE_MAGIC) }
+}
+
+// Sourcemap integrity describes the original upload, before Brotli storage.
+// Hash incrementally, including decompression, so migration stays streaming.
+export async function verifyStoragePayload(type: StorageRowKind, row: StorageRow, source: Readable, signal?: AbortSignal): Promise<void> {
+  const hash = createHash(type === 'report' ? 'sha256' : 'sha512')
+  const sink = new Writable({ write(chunk, _encoding, next) { hash.update(chunk); next() } })
+  const options = signal ? { signal } : {}
+  try {
+    if (type === 'bundle' && row.kind === 'sourcemap') {
+      await pipeline(source, createBrotliDecompress(), sink, options)
+    } else await pipeline(source, sink, options)
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code ?? ''
+    if (['Z_DATA_ERROR', 'Z_BUF_ERROR'].includes(code) || code.startsWith('ERR__ERROR_FORMAT_')) {
+      throw new StoragePayloadError('Stored sourcemap cannot be decompressed', { cause: err })
+    }
+    throw err
+  }
+  const actual = type === 'report' ? hash.digest('base64url') : `sha512-${hash.digest('base64')}`
+  if (actual !== row.hash) throw new StoragePayloadError('Stored payload does not match its upload hash')
+}

package/server-managed/storage-stores.ts

@@ -0,0 +1,81 @@
+// Logical stores share one encryption boundary. Compression, identifiers and
+// public response bytes stay the same with either physical backend.
+import { Buffer } from 'node:buffer'
+import type { AvatarStore } from './avatar-store.ts'
+import type { BlobStore } from './blob-store.ts'
+import type { BundleCacheStorage } from './bundle-cache.ts'
+import { createBundleStore } from './bundle-store.ts'
+import { CacheMissError, type CacheStorage, validateCacheKey } from './cache-storage.ts'
+import { type ObjectStorage, isBlobId } from './object-storage.ts'
+
+function id(value: string): string {
+  if (!isBlobId(value)) throw new Error('Invalid managed blob id')
+  return value
+}
+
+function blobStore(objects: ObjectStorage, name: string, suffix = ''): BlobStore {
+  const path = (value: string) => `${name}/${id(value)}${suffix}`
+  return {
+    put: (value, bytes) => objects.put(path(value), bytes),
+    get: value => objects.get(path(value)),
+    open: value => objects.open(path(value)),
+    delete: value => objects.delete(path(value)),
+  }
+}
+
+function cacheStore(objects: ObjectStorage, name: string): CacheStorage {
+  const path = (key: string) => `cache/${name}/${validateCacheKey(key)}`
+  return {
+    exists: key => objects.exists(path(key)),
+    put: async (key, bytes) => { await objects.put(path(key), bytes) },
+    async open(key) {
+      const value = await objects.open(path(key))
+      if (!value) throw new CacheMissError()
+      return value
+    },
+    delete: prefix => objects.deletePrefix(`${path(prefix)}/`),
+  }
+}
+
+function avatarStore(objects: ObjectStorage, sidecar: boolean): AvatarStore {
+  return {
+    async put(value, contentType, bytes) {
+      const path = `avatars/${id(value)}`, type = contentType.split(';', 1)[0]!.trim()
+      if (!/^image\/[a-z0-9.+-]+$/iu.test(type)) throw new Error('Invalid avatar type')
+      if (sidecar) {
+        await objects.put(path, bytes)
+        await objects.put(`${path}.type`, Buffer.from(type))
+      } else await objects.put(path, Buffer.concat([Buffer.from(`${type}\n`), bytes]))
+    },
+    async get(value) {
+      const path = `avatars/${id(value)}`
+      const bytes = await objects.get(path)
+      if (!bytes) return null
+      if (sidecar) {
+        const type = await objects.get(`${path}.type`)
+        return type ? { bytes, contentType: type.toString().trim() || 'application/octet-stream' } : null
+      }
+      const split = bytes.indexOf(10)
+      if (split < 0 || split > 100) throw new Error('Invalid cached avatar')
+      return { contentType: bytes.subarray(0, split).toString(), bytes: bytes.subarray(split + 1) }
+    },
+  }
+}
+
+export function createManagedStores(objects: ObjectStorage, avatarSidecar: boolean) {
+  const bundles = cacheStore(objects, 'bundles')
+  const cacheStorage: BundleCacheStorage = {
+    exists: (value, file) => bundles.exists(`${id(value)}/${file}`),
+    put: (value, file, bytes) => bundles.put(`${id(value)}/${file}`, bytes),
+    open: (value, file) => bundles.open(`${id(value)}/${file}`),
+    delete: value => bundles.delete(id(value)),
+  }
+  return {
+    reportStore: blobStore(objects, 'reports'),
+    bundleStore: createBundleStore(blobStore(objects, 'bundles'), blobStore(objects, 'bundles', '.map.br')),
+    uploadStore: blobStore(objects, 'uploads'),
+    avatarStore: avatarStore(objects, avatarSidecar),
+    cacheStorage,
+    reportSourcesStorage: cacheStore(objects, 'report-sources'),
+  }
+}

package/server-managed/storage.ts

@@ -0,0 +1,58 @@
+// Backend selection is shared by standalone, combined and function entrypoints.
+import { dirname } from 'node:path'
+import { parseStorageKey } from '../server-common/storage-crypto.ts'
+import { createBundleCache } from './bundle-cache.ts'
+import { createReportSourcesCache } from './report-sources.ts'
+import { openNeonManagedDb } from './db-neon.ts'
+import type { ManagedConfig } from './config.ts'
+import { createEncryptedObjectStorage } from './storage-encryption.ts'
+import { createManagedStores } from './storage-stores.ts'
+import { createDiskObjectStorage } from './object-storage-disk.ts'
+import { openVercelObjectStorage } from './object-storage-vercel.ts'
+import { migrateStorage, reapStorageUploads } from './storage-maintenance.ts'
+
+// Database-only callers (notably status) must not activate byte encryption.
+export async function openManagedStorageDb(config: ManagedConfig) {
+  const options = { triageHistoryLimit: config.triageHistoryLimit, storageEncryptionKey: parseStorageKey(config.storageEncryptionKey) }
+  return config.neonUrl ? openNeonManagedDb(config.neonUrl, options)
+    : (await import('./db.ts')).openSqliteManagedDb(config.dbPath, options)
+}
+
+export async function openManagedStorage(config: ManagedConfig) {
+  const key = parseStorageKey(config.storageEncryptionKey)
+  if (config.storageEncryptionMigrate && !key) throw new Error('MANAGED_STORAGE_ENCRYPTION_MIGRATE requires MANAGED_STORAGE_ENCRYPTION_KEY')
+  if (config.neonUrl && !config.blobToken) throw new Error('Managed Neon mode requires BLOB_READ_WRITE_TOKEN')
+  if (config.serverless && !config.neonUrl) throw new Error('Serverless managed storage requires Neon')
+  const db = await openManagedStorageDb(config)
+  try {
+    const raw = config.neonUrl ? await openVercelObjectStorage(config.blobToken!) : createDiskObjectStorage(dirname(config.dbPath))
+    // Enable before exposing stores or token writers. Concurrent first starts
+    // serialize activation in the database and validate the winning key.
+    if (key && !await db.getStorageEncryption()) {
+      if (config.vercelPreview) throw new Error('Storage encryption must be enabled outside a Vercel preview deployment')
+      await db.enableStorageEncryption()
+    }
+    const objects = await createEncryptedObjectStorage(raw, db, key)
+    const storage = createManagedStores(objects, !config.neonUrl)
+    return { ...storage, db, uploadStore: config.neonUrl ? storage.uploadStore : undefined,
+      bundleCache: createBundleCache(storage.cacheStorage, db, storage.bundleStore),
+      reportSourcesCache: createReportSourcesCache(storage.reportSourcesStorage, db, storage.reportStore, storage.bundleStore),
+      async reapStorage(signal?: AbortSignal) {
+        if (!config.storageEncryptionMigrate || signal?.aborted) return
+        const state = await db.getStorageEncryption()
+        if (state?.complete && state.cleanupComplete) return
+        console.info('managed-storage-migration-start:', JSON.stringify({ migrated: state?.migrated, cursor: state?.cursor }))
+        const result = await migrateStorage(raw, db, key!, { maxMs: config.storageEncryptionMigrateMaxMs, signal })
+        console.info('managed-storage-migration:', JSON.stringify({
+          complete: result.complete === 1, cleanupComplete: result.cleanupComplete === 1,
+          migrated: result.migrated, cursor: result.cursor, retryAt: result.retryAt,
+          failed: result.failures.length, cancelled: signal?.aborted === true,
+        }))
+      },
+      ...(config.neonUrl ? { reapUploads: (signal?: AbortSignal) => reapStorageUploads(raw, db, Date.now(), signal) } : {}),
+    }
+  } catch (err) {
+    await db.close()
+    throw err
+  }
+}

package/server-managed/team-catalog.ts

@@ -0,0 +1,7 @@
+import { createHash } from 'node:crypto'
+
+// Version only this user's visible catalog, including access and content keys.
+// REST and the live feed must describe exactly the same snapshot.
+export function teamCatalogRevision(teams: readonly unknown[]): string {
+  return createHash('sha256').update(JSON.stringify(teams)).digest('base64url')
+}

package/server-managed/team-feed.ts

@@ -0,0 +1,173 @@
+import type { ServerResponse } from 'node:http'
+import { setTimeout as delay } from 'node:timers/promises'
+import type { ManagedHttpDeps } from './http.ts'
+import type { StoredUser, TeamReportAccessSnapshot } from './db.ts'
+import { TeamReportsError, teamSnapshotKey, teamWorkspaceFindingIds } from './team-reports.ts'
+import type { WorkspaceShareFeedState } from './workspace-shares.ts'
+
+// Short database reads work across instances without pinning a Neon connection.
+// All polling belongs to the awaited request; nothing runs after it completes.
+export const TEAM_FEED_POLL_MS = 3_000
+export const TEAM_FEED_LIFETIME_MS = 240_000 // below the configured Vercel 300s
+const HEARTBEAT_MS = 15_000
+
+type FeedOptions = { pollMs?: number; lifetimeMs?: number }
+type Publish = (event: 'teams' | 'triage', revision: string | undefined) => boolean
+
+// Public capabilities remain scoped to their single shared workspace.
+export async function serveTeamFeed(res: ServerResponse, deps: ManagedHttpDeps,
+  snapshot: TeamReportAccessSnapshot, recheck: () => Promise<void>,
+  options: FeedOptions & { readState?: () => Promise<WorkspaceShareFeedState | null> } = {}): Promise<void> {
+  let ids: string[] | undefined
+  let previous: WorkspaceShareFeedState | undefined
+  const sameAccess = (a: WorkspaceShareFeedState, b?: WorkspaceShareFeedState) => a.grant === b?.grant && a.catalog === b.catalog
+  const readState = async () => {
+    const state = await options.readState!()
+    if (!state) throw new TeamReportsError(404, 'workspace-changed')
+    return state
+  }
+  await serveFeed(res, deps, async publish => {
+    const state = options.readState ? await readState() : undefined
+    // The first poll still compares the full snapshot loaded before the stream.
+    // Unchanged polls validate the live grant without reading report catalogs.
+    if (state && sameAccess(state, previous)) {
+      if (state.annotations === previous!.annotations) return
+    } else await recheck()
+    ids ??= [...await teamWorkspaceFindingIds(deps.db, deps.reportStore, snapshot)]
+    const triage = await deps.db.getAnnotationRevision(ids)
+    const after = options.readState ? await readState() : undefined
+    if (!after || !sameAccess(after, state)) await recheck()
+    publish('triage', triage)
+    // A write during the read must remain pending for the following poll.
+    if (after?.annotations === state?.annotations) previous = after
+  }, options)
+}
+
+// Membership and content notifications cover all of the user's teams. Only
+// the focused team needs report parsing or annotation reads; null is the
+// catalog-only subscription used on landing and management pages.
+export async function serveUserTeamFeed(res: ServerResponse, deps: ManagedHttpDeps,
+  sessionId: string, user: StoredUser, teamId: string | null, options: FeedOptions = {}): Promise<void> {
+  let ids: string[] = [], visibilityKey: string | undefined
+  let focusedKey: string | undefined
+  let previousState: { catalog: number; annotations: number } | undefined
+  const checkUser = (current: { user: Pick<StoredUser, 'id' | 'role'> } | null) => {
+    if (!current) throw new TeamReportsError(401, 'unauthenticated')
+    if (current.user.id !== user.id || current.user.role !== user.role || current.user.role === 'none') {
+      throw new TeamReportsError(403, 'access-changed')
+    }
+  }
+  await serveFeed(res, deps, async publish => {
+    const state = await deps.db.getFeedState(sessionId, Date.now())
+    checkUser(state)
+    if (state!.catalog === previousState?.catalog && (!teamId || state!.annotations === previousState?.annotations)) return
+    if (teamId && focusedKey !== undefined && state!.catalog === previousState?.catalog) {
+      // Annotation changes cannot change visibility. Read only this workspace's
+      // IDs, then fence against concurrent access/content changes before sending.
+      const triage = JSON.stringify([focusedKey, await deps.db.getAnnotationRevision(ids)])
+      const after = await deps.db.getFeedState(sessionId, Date.now())
+      checkUser(after)
+      if (after!.catalog !== state!.catalog) return
+      publish('triage', triage)
+      if (after!.annotations === state!.annotations) previousState = state!
+      return
+    }
+    const catalog = await deps.db.getUserTeamFeedSnapshot(sessionId, Date.now())
+    checkUser(catalog)
+    checkUser(await deps.db.getReportAccessSnapshot(sessionId, Date.now(), []))
+    // Publish catalog state before loading any report blobs. A slow or broken
+    // focused report must not hide membership/content changes from the client.
+    if (!publish('teams', catalog!.revision)) return
+    if (!teamId) {
+      // A mutation during the snapshot must cause a fresh read next poll.
+      const current = await deps.db.getFeedState(sessionId, Date.now())
+      checkUser(current)
+      if (current!.catalog === state!.catalog) previousState = state!
+      return
+    }
+    let triage: string | undefined
+    const snapshot = await deps.db.getTeamReportAccessSnapshot(sessionId, Date.now(), teamId)
+    if (!snapshot) throw new TeamReportsError(401, 'unauthenticated')
+    checkUser(snapshot)
+    const key = teamSnapshotKey(snapshot)
+    if (key !== visibilityKey) {
+      try {
+        ids = snapshot.teamId ? [...await teamWorkspaceFindingIds(deps.db, deps.reportStore, snapshot)] : []
+        visibilityKey = key
+      } catch {
+        // Missing, malformed or temporarily unavailable blobs only suspend
+        // triage. Retry visibility on the next poll, even for the same key.
+        publish('triage', undefined)
+        return
+      }
+    }
+    if (snapshot.teamId) triage = JSON.stringify([key, await deps.db.getAnnotationRevision(ids)])
+    const current = await deps.db.getTeamReportAccessSnapshot(sessionId, Date.now(), teamId)
+    // A concurrent access/content change discards only the annotation read.
+    checkUser(current)
+    if (!current || teamSnapshotKey(current) !== key) return
+    publish('triage', triage)
+    focusedKey = snapshot.teamId ? key : undefined
+    const after = await deps.db.getFeedState(sessionId, Date.now())
+    checkUser(after)
+    if (after!.catalog === state!.catalog && after!.annotations === state!.annotations) previousState = state!
+  }, options)
+}
+
+async function serveFeed(res: ServerResponse, deps: ManagedHttpDeps, read: (publish: Publish) => Promise<void>,
+  { pollMs = TEAM_FEED_POLL_MS, lifetimeMs = TEAM_FEED_LIFETIME_MS }: FeedOptions): Promise<void> {
+  const controller = new AbortController()
+  const close = () => controller.abort()
+  res.once('close', close)
+  const deadline = setTimeout(close, lifetimeMs)
+  const stopped = () => controller.signal.aborted || res.destroyed || deps.isShuttingDown()
+  // Notifications carry no annotation bodies, finding IDs, or global cursors.
+  // The catalog's opaque version lets clients reuse an identical REST snapshot;
+  // every connection still confirms current access, including after reconnects.
+  function write(frame: string): boolean {
+    if (stopped()) return false
+    if (res.write(frame)) return true
+    // Slow consumers reconnect and read current state; never queue a backlog.
+    res.destroy()
+    return false
+  }
+  try {
+    if (stopped()) return
+    res.writeHead(200, { 'content-type': 'text/event-stream; charset=utf-8',
+      'cache-control': 'private, no-store, no-transform', 'x-accel-buffering': 'no',
+      'x-content-type-options': 'nosniff', 'referrer-policy': 'no-referrer' })
+    res.flushHeaders()
+    let heartbeat = Date.now()
+    const previous = new Map<string, string>()
+    const publish: Publish = (event, revision) => {
+      if (stopped()) return false
+      if (revision === undefined) { previous.delete(event); return true }
+      if (revision === previous.get(event)) return true
+      const data = event === 'teams' ? JSON.stringify({ revision }) : '{}'
+      if (!write(`event: ${event}\ndata: ${data}\n\n`)) return false
+      previous.set(event, revision)
+      heartbeat = Date.now()
+      return true
+    }
+    while (!stopped()) {
+      if (deps.db.withRequest) await deps.db.withRequest(() => read(publish))
+      else await read(publish)
+      if (stopped()) break
+      if (Date.now() - heartbeat >= HEARTBEAT_MS) {
+        if (!write(': keepalive\n\n')) break
+        heartbeat = Date.now()
+      }
+      await delay(pollMs, undefined, { signal: controller.signal }).catch(error => {
+        if (!controller.signal.aborted) throw error
+      })
+    }
+  } catch (error) {
+    if (!res.headersSent) throw error
+    if (error instanceof TeamReportsError) write('event: close\ndata: {}\n\n')
+    else if (!stopped()) throw error
+  } finally {
+    clearTimeout(deadline)
+    res.off('close', close)
+    if (res.headersSent && !res.destroyed) res.end()
+  }
+}

package/server-managed/team-reports.ts

@@ -0,0 +1,219 @@
+// Team content is filtered as one workspace, with separate report envelopes.
+// Bounded snapshots retain filtered content and visibility for repeated reads.
+import { Buffer } from 'node:buffer'
+import { backfillFindingIds, reportEntries, stampSecurityGroups } from '@preventive/report'
+import { managedFindingSourcePaths, readManagedReport } from '../common/managed/report-content.ts'
+import { filterReportData, projectFinding } from '../common/managed/report-filter.ts'
+import type { BlobStore } from './blob-store.ts'
+import type { ManagedDb, TeamReportAccessSnapshot } from './db.ts'
+import { triageWireEntry } from './triage-response.ts'
+import { MAX_REPORT_QUERY_BYTES, MAX_REPORT_QUERY_COUNT } from './report-query.ts'
+
+type Finding = Record<string, unknown>
+type TeamReport = { id: string; filename: string; data: unknown; repo: { github: string | null; directory: string } }
+type ReportVisibility = { ids: Set<string>; sourcePaths: Set<string> }
+type Visibility = Map<string, ReportVisibility>
+const VISIBILITY_CACHE_MAX_ITEMS = 250_000
+const VISIBILITY_CACHE_MAX_SNAPSHOTS = 32
+const caches = new WeakMap<ManagedDb, Map<string, Visibility>>()
+const REPORT_CACHE_BYTES = 16 * 1024 * 1024
+const reportCaches = new WeakMap<ManagedDb, Map<string, Buffer>>()
+function retainReports(db: ManagedDb, key: string, bytes: Buffer) {
+  if (bytes.length > REPORT_CACHE_BYTES) return
+  let cache = reportCaches.get(db)
+  if (!cache) { cache = new Map(); reportCaches.set(db, cache) }
+  cache.delete(key)
+  let total = bytes.length + [...cache.values()].reduce((sum, value) => sum + value.length, 0)
+  for (const [oldest, value] of cache) {
+    if (total <= REPORT_CACHE_BYTES && cache.size < VISIBILITY_CACHE_MAX_SNAPSHOTS) break
+    cache.delete(oldest); total -= value.length
+  }
+  cache.set(key, bytes)
+}
+function visibilityWeight(visible: Visibility): number {
+  return [...visible.values()].reduce((sum, v) => sum + v.ids.size + v.sourcePaths.size, 0)
+}
+function retainVisibility(db: ManagedDb, key: string, visible: Visibility): void {
+  let cache = caches.get(db)
+  // Replacement contributes its weight once and does not evict a peer merely
+  // because the cache already holds the maximum number of snapshots.
+  cache?.delete(key)
+  const incoming = visibilityWeight(visible)
+  if (incoming > VISIBILITY_CACHE_MAX_ITEMS) return
+  if (!cache) { cache = new Map(); caches.set(db, cache) }
+  let total = incoming + [...cache.values()].reduce((sum, entry) => sum + visibilityWeight(entry), 0)
+  for (const [oldest, entry] of cache) {
+    if (cache.size < VISIBILITY_CACHE_MAX_SNAPSHOTS && total <= VISIBILITY_CACHE_MAX_ITEMS) break
+    cache.delete(oldest)
+    total -= visibilityWeight(entry)
+  }
+  cache.set(key, visible)
+}
+export class TeamReportsError extends Error {
+  status: number
+  constructor(status: number, error: string) { super(error); this.status = status }
+}
+export function teamSnapshotKey(snapshot: TeamReportAccessSnapshot): string {
+  return JSON.stringify([snapshot.user.id, snapshot.user.role, snapshot.teamId, snapshot.reports, snapshot.repositories])
+}
+export async function teamSnapshot(db: ManagedDb, sessionId: string, teamId: string): Promise<TeamReportAccessSnapshot> {
+  const snapshot = await db.getTeamReportAccessSnapshot(sessionId, Date.now(), teamId)
+  if (!snapshot) throw new TeamReportsError(401, 'unauthenticated')
+  if (!snapshot.teamId) throw new TeamReportsError(404, 'no-team')
+  return snapshot
+}
+export async function recheckTeam(db: ManagedDb, sessionId: string, snapshot: TeamReportAccessSnapshot): Promise<void> {
+  if (teamSnapshotKey(await teamSnapshot(db, sessionId, snapshot.teamId!)) !== teamSnapshotKey(snapshot)) throw new TeamReportsError(404, 'workspace-changed')
+}
+function groupsOf(data: unknown): Finding[][] {
+  return (reportEntries(data) ?? []).map(entry => (Array.isArray(entry) ? entry : [entry]).filter(
+    (finding): finding is Finding => finding !== null && typeof finding === 'object' && !Array.isArray(finding),
+  ))
+}
+function linksOf(data: unknown): string[][] | null {
+  const record = data as { source?: string; links?: string[][] }
+  if (record?.source !== 'links' || !Array.isArray(record.links)) return null
+  if (!record.links.every(ids => Array.isArray(ids) && ids.every(id => typeof id === 'string'))) throw new TeamReportsError(422, 'unreadable-links')
+  return record.links
+}
+async function buildTeamWorkspace(db: ManagedDb, store: BlobStore, snapshot: TeamReportAccessSnapshot): Promise<{ body: Buffer; visible: Visibility }> {
+  if (snapshot.reports.length > MAX_REPORT_QUERY_COUNT || snapshot.reports.reduce((n, r) => n + r.byteSize, 0) > MAX_REPORT_QUERY_BYTES) throw new TeamReportsError(413, 'batch-too-large')
+  const reports: TeamReport[] = []
+  let inputBytes = 0, next = 0
+  // Bound both remote reads and raw buffers, retaining stable report order for
+  // the cross-report classification that follows. Finish workers on failure.
+  const results = await Promise.allSettled(Array.from({ length: Math.min(4, snapshot.reports.length) }, async () => {
+    while (next < snapshot.reports.length) {
+      const index = next++
+      const access = snapshot.reports[index]!
+
+      const bytes = await store.get(access.id)
+      if (!bytes) throw new TeamReportsError(503, 'unavailable')
+      inputBytes += bytes.length
+      if (inputBytes > MAX_REPORT_QUERY_BYTES) throw new TeamReportsError(413, 'batch-too-large')
+      const parsed = readManagedReport(bytes.toString('utf8'), access.filename)
+      if (!parsed.data) throw new TeamReportsError(422, 'unreadable-report')
+      // Backfill before filtering so links, annotations and the client agree on
+      // IDs even when hiding a component would change the original row shape.
+      await backfillFindingIds(groupsOf(parsed.data).flat())
+      reports[index] = { id: access.id, filename: access.filename, data: parsed.data, repo: access.repo }
+    }
+  }))
+  for (const result of results) if (result.status === 'rejected') throw result.reason
+  const edges = new Map<string, Set<string>>()
+  const connect = (a: string, b: string) => {
+    if (!edges.has(a)) edges.set(a, new Set())
+    edges.get(a)!.add(b)
+  }
+  // A star is enough for transitive security propagation, without a quadratic
+  // expansion for large links. Unknown IDs can connect known findings.
+  for (const report of reports) {
+    for (const ids of linksOf(report.data) ?? []) {
+      for (const id of ids.slice(1)) { connect(ids[0]!, id); connect(id, ids[0]!) }
+    }
+  }
+  const groups = reports.flatMap(report => groupsOf(report.data).map(group => group.map(f => projectFinding(f, report.data as Finding)!)))
+  stampSecurityGroups(groups, { linkedIds: id => edges.get(id) ?? [] })
+  const securityIds = new Set(groups.flat().filter(f => f['isSecurity'] === true).map(f => String(f['id'])))
+  const allIds = new Set<string>(), visible: Visibility = new Map()
+  for (let i = 0; i < reports.length; i++) {
+    const access = snapshot.reports[i]!, report = reports[i]!
+    report.data = filterReportData(report.data, access.permissions, access.repo, securityIds)
+    const ids = new Set<string>()
+    for (const finding of groupsOf(report.data).flat()) {
+      // Preserve linked security classification for the UI lens, including a
+      // linked component that a dependency permission will hide from the UI.
+      finding['isSecurity'] = securityIds.has(String(finding['id']))
+      if (typeof finding['id'] === 'string') { ids.add(finding['id']); allIds.add(finding['id']) }
+    }
+    visible.set(report.id, { ids, sourcePaths: managedFindingSourcePaths(groupsOf(report.data).flat()) })
+  }
+  for (const report of reports) {
+    const links = linksOf(report.data)
+    if (links) report.data = { source: 'links', findings: [], links: links.map(ids => [...new Set(ids.filter(id => allIds.has(id)))]).filter(ids => ids.length >= 2) }
+  }
+  let outputBytes = 14
+  const parts = [Buffer.from('{"reports":[')]
+  for (const [index, report] of reports.entries()) {
+    const bytes = Buffer.from(JSON.stringify(report))
+    outputBytes += bytes.length + 1
+    if (outputBytes > MAX_REPORT_QUERY_BYTES) throw new TeamReportsError(413, 'batch-too-large')
+    if (index) parts.push(Buffer.from(','))
+    parts.push(bytes)
+  }
+  parts.push(Buffer.from(']}'))
+  const body = Buffer.concat(parts)
+  retainVisibility(db, teamSnapshotKey(snapshot), visible)
+  retainReports(db, teamSnapshotKey(snapshot), body)
+  return { body, visible }
+}
+const pendingWorkspaces = new WeakMap<ManagedDb, Map<string, ReturnType<typeof buildTeamWorkspace>>>()
+async function loadTeamWorkspace(db: ManagedDb, store: BlobStore, snapshot: TeamReportAccessSnapshot) {
+  let pending = pendingWorkspaces.get(db)
+  if (!pending) { pending = new Map(); pendingWorkspaces.set(db, pending) }
+  const key = teamSnapshotKey(snapshot)
+  const existing = pending.get(key)
+  if (existing) return existing
+  const job = buildTeamWorkspace(db, store, snapshot)
+  pending.set(key, job)
+  try { return await job } finally { pending.delete(key) }
+}
+// Treat the encoded body as immutable and recheck access before sending it.
+// Warm HTTP reads need neither a parsed copy nor another serialization pass.
+export async function loadTeamReportsResponse(db: ManagedDb, store: BlobStore, snapshot: TeamReportAccessSnapshot): Promise<Buffer> {
+  const cached = reportCaches.get(db)?.get(teamSnapshotKey(snapshot))
+  return cached ?? (await loadTeamWorkspace(db, store, snapshot)).body
+}
+export async function loadTeamReports(db: ManagedDb, store: BlobStore, snapshot: TeamReportAccessSnapshot): Promise<TeamReport[]> {
+  // Object consumers get their own copy, including when sharing a cold load.
+  const body = await loadTeamReportsResponse(db, store, snapshot)
+  return (JSON.parse(body.toString('utf8')) as { reports: TeamReport[] }).reports
+}
+async function teamVisibility(db: ManagedDb, store: BlobStore, snapshot: TeamReportAccessSnapshot): Promise<Visibility> {
+  const key = teamSnapshotKey(snapshot)
+  let visible = caches.get(db)?.get(key)
+  if (!visible) {
+    // A large snapshot may deliberately remain uncached, or be evicted by
+    // another request. Authorization uses this load's result in either case.
+    visible = (await loadTeamWorkspace(db, store, snapshot)).visible
+  }
+  return visible
+}
+export async function teamWorkspaceFindingIds(db: ManagedDb, store: BlobStore, snapshot: TeamReportAccessSnapshot): Promise<Set<string>> {
+  const ids = new Set<string>()
+  for (const report of (await teamVisibility(db, store, snapshot)).values()) for (const id of report.ids) ids.add(id)
+  return ids
+}
+export async function teamReportVisibility(db: ManagedDb, store: BlobStore, snapshot: TeamReportAccessSnapshot, reportId: string): Promise<ReportVisibility> {
+  if (!snapshot.reports.some(r => r.id === reportId)) throw new TeamReportsError(404, 'no-report')
+  const visible = await teamVisibility(db, store, snapshot)
+  return visible.get(reportId)!
+}
+export async function teamFindingIds(db: ManagedDb, store: BlobStore, sessionId: string, teamId: string, reportId: string): Promise<Set<string>> {
+  const snapshot = await teamSnapshot(db, sessionId, teamId)
+  const visible = await teamReportVisibility(db, store, snapshot, reportId)
+  await recheckTeam(db, sessionId, snapshot)
+  return visible.ids
+}
+export async function teamSourcePaths(db: ManagedDb, store: BlobStore, sessionId: string, teamId: string, reportId: string): Promise<Set<string>> {
+  const snapshot = await teamSnapshot(db, sessionId, teamId)
+  const visible = await teamReportVisibility(db, store, snapshot, reportId)
+  await recheckTeam(db, sessionId, snapshot)
+  return visible.sourcePaths
+}
+
+// Serialize shared annotation bodies once. Reports carry only the annotated
+// finding IDs visible in that report; callers revalidate access before sending.
+export async function loadTeamAnnotations(db: ManagedDb, store: BlobStore, snapshot: TeamReportAccessSnapshot, reportId: string | null = null) {
+  // Restrict annotation reads only after classifying the complete workspace:
+  // links and findings in other reports can affect this report's visibility.
+  const visible = reportId === null ? await teamVisibility(db, store, snapshot)
+    : new Map([[reportId, await teamReportVisibility(db, store, snapshot, reportId)]])
+  const ids = new Set<string>()
+  for (const report of visible.values()) for (const id of report.ids) ids.add(id)
+  const { triage, comments } = await db.getAnnotations([...ids])
+  const entries = Object.fromEntries(triage.map(row => [row.findingId, triageWireEntry(row)]))
+  const annotated = new Set([...triage.map(row => row.findingId), ...comments.map(comment => comment.findingId)])
+  const reports = Object.fromEntries([...visible].map(([id, report]) => [id, [...report.ids].filter(finding => annotated.has(finding))]))
+  return { reports, entries, comments }
+}

package/server-managed/triage-response.ts

@@ -0,0 +1,16 @@
+import type { TriageRow } from './db.ts'
+import { type TriageEntryPatch, isTriageBucket } from '../common/managed/triage.ts'
+
+// A stored triage row (current state or a trail event) → its wire entry: only
+// set fields present, `false` kept for flagged (the explicit un-flag tombstone
+// must round-trip), and null for the row of a cleared entry (every field
+// null) — the reader adopts the clear.
+export function triageWireEntry(row: Pick<TriageRow, 'color' | 'triage' | 'comment' | 'fix' | 'flagged'>, legacyHistory = false): TriageEntryPatch | null {
+  const e: TriageEntryPatch = {}
+  if (row.color != null) e.color = row.color
+  if (isTriageBucket(row.triage)) e.triage = row.triage
+  if (legacyHistory && row.comment != null) e.comment = row.comment
+  if (row.fix != null) e.fix = row.fix
+  if (row.flagged != null) e.flagged = row.flagged
+  return Object.keys(e).length > 0 ? e : null
+}