@preventive/triage 1.0.0-alpha.4 → 1.0.0-alpha.40

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.
+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 & { reportId?: string | null } = {}): 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, options.reportId)
+    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, options.reportId)
+    // 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-npm-scopes.ts

@@ -0,0 +1,77 @@
+// npm scopes a team lists: its members, whatever their role, may read that
+// scope's private packages in the npm viewer (npm-packages.ts), as admins and
+// managers may read any. Hidden teams grant nothing, as for their content.
+import { MAX_TEAM_NPM_SCOPES, normalizeNpmScope } from '../common/managed/npm-packages.js'
+import { ManagedMutationError } from './management.ts'
+import type { ManagedSql } from './sql.ts'
+
+export const TEAM_NPM_SCOPE_SCHEMA = `
+CREATE TABLE IF NOT EXISTS managed_team_npm_scope (
+  team_id TEXT NOT NULL REFERENCES managed_team(id) ON DELETE CASCADE,
+  scope   TEXT NOT NULL,
+  PRIMARY KEY (team_id, scope)
+) STRICT;
+`
+
+export interface TeamNpmScopeStore {
+  // Every team's scopes, sorted, keyed by team id; teams without any are absent.
+  listTeamNpmScopes(): Promise<Record<string, string[]>>
+  // Replaces a team's scopes; admin only. Answers what changed, or null for no team.
+  setTeamNpmScopes(sessionId: string, teamId: string, scopes: unknown): Promise<{ added: string[]; removed: string[] } | null>
+  // The scopes a user's visible teams list.
+  listUserNpmScopes(userId: string): Promise<string[]>
+  // Whether any visible team lists the scope: whoever reads its packages,
+  // they are the instance's own, whose new releases aren't flagged (http.ts).
+  hasTeamNpmScope(scope: string): Promise<boolean>
+}
+
+// Each distinct scope, normalized; a list with one npm could not publish
+// under, or too many, is refused whole.
+export function parseTeamNpmScopes(input: unknown): string[] {
+  if (!Array.isArray(input)) throw new ManagedMutationError(400, 'bad-scopes')
+  const scopes = new Set<string>()
+  for (const value of input) {
+    const scope = normalizeNpmScope(value)
+    if (scope === null) throw new ManagedMutationError(400, 'bad-scope')
+    scopes.add(scope)
+  }
+  if (scopes.size > MAX_TEAM_NPM_SCOPES) throw new ManagedMutationError(400, 'too-many-scopes')
+  return [...scopes].toSorted()
+}
+
+export function teamNpmScopeMethods(db: ManagedSql): TeamNpmScopeStore {
+  return {
+    async listTeamNpmScopes() {
+      const rows = await db.prepare('SELECT team_id AS teamId, scope FROM managed_team_npm_scope ORDER BY team_id, scope').all() as { teamId: string; scope: string }[]
+      const result: Record<string, string[]> = {}
+      for (const { teamId, scope } of rows) (result[teamId] ??= []).push(scope)
+      return result
+    },
+    async setTeamNpmScopes(sessionId, teamId, input) {
+      const user = await db.prepare(`SELECT u.role FROM managed_session s JOIN managed_user u ON u.id = s.user_id
+        WHERE s.id = ? AND s.expires_at > ?`).get(sessionId, Date.now()) as { role: string } | undefined
+      if (!user) throw new ManagedMutationError(401, 'unauthenticated')
+      if (user.role !== 'admin') throw new ManagedMutationError(403, 'forbidden')
+      const scopes = parseTeamNpmScopes(input)
+      if (!await db.prepare('SELECT id FROM managed_team WHERE id = ?').get(teamId)) return null
+      const current = (await db.prepare('SELECT scope FROM managed_team_npm_scope WHERE team_id = ?').all(teamId) as { scope: string }[]).map(row => row.scope)
+      const removed = current.filter(scope => !scopes.includes(scope)).toSorted()
+      const added = scopes.filter(scope => !current.includes(scope))
+      for (const scope of removed) await db.prepare('DELETE FROM managed_team_npm_scope WHERE team_id = ? AND scope = ?').run(teamId, scope)
+      for (const scope of added) await db.prepare('INSERT INTO managed_team_npm_scope (team_id, scope) VALUES (?, ?)').run(teamId, scope)
+      return { added, removed }
+    },
+    async listUserNpmScopes(userId) {
+      const rows = await db.prepare(`SELECT DISTINCT ns.scope FROM managed_team_user tu
+        JOIN managed_team t ON t.id = tu.team_id AND t.hidden = 0
+        JOIN managed_team_npm_scope ns ON ns.team_id = tu.team_id
+        WHERE tu.user_id = ? ORDER BY ns.scope`).all(userId) as { scope: string }[]
+      return rows.map(row => row.scope)
+    },
+    async hasTeamNpmScope(scope) {
+      return !!await db.prepare(`SELECT 1 AS listed FROM managed_team_npm_scope ns
+        JOIN managed_team t ON t.id = ns.team_id AND t.hidden = 0
+        WHERE ns.scope = ? LIMIT 1`).get(scope)
+    },
+  }
+}

package/server-managed/team-reports.ts

@@ -0,0 +1,228 @@
+// Team content is filtered as one workspace, with separate report envelopes.
+// Bounded snapshots retain filtered content and visibility for repeated reads.
+import { mergeLinkGroups } from './link-reports.ts'
+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 { visibleManagedIssues } from './managed-issues.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.hiddenReportId ?? null, snapshot.reports, snapshot.repositories, snapshot.linkRevision])
+}
+export async function teamSnapshot(db: ManagedDb, sessionId: string, teamId: string, reportId: string | null = null): Promise<TeamReportAccessSnapshot> {
+  const snapshot = await db.getTeamReportAccessSnapshot(sessionId, Date.now(), teamId, reportId)
+  if (!snapshot) throw new TeamReportsError(401, 'unauthenticated')
+  if (!snapshot.teamId) throw new TeamReportsError(404, 'no-team')
+  if (reportId !== null && !snapshot.reports.some(report => report.id === reportId)) throw new TeamReportsError(404, 'no-report')
+  return snapshot
+}
+export async function recheckTeam(db: ManagedDb, sessionId: string, snapshot: TeamReportAccessSnapshot): Promise<void> {
+  if (teamSnapshotKey(await teamSnapshot(db, sessionId, snapshot.teamId!, snapshot.reportId)) !== 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 globalLinks = snapshot.linkRevision ? await db.getEnabledLinkGroups(snapshot.linkRevision) : []
+  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 ids of globalLinks.concat(reports.flatMap(report => 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)
+    // Hidden previews are independently authorized; preserve a hidden links
+    // document even though its referenced findings are outside this response.
+    if (links && !snapshot.hiddenReportId) 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)
+  }
+  const links = mergeLinkGroups(globalLinks, allIds)
+  const suffix = Buffer.from(links.length > 0 ? `],"links":${JSON.stringify(links)}}` : ']}')
+  if (outputBytes + suffix.length > MAX_REPORT_QUERY_BYTES) throw new TeamReportsError(413, 'batch-too-large')
+  parts.push(suffix)
+  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, reportId)
+  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, reportId)
+  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, issues: savedIssues } = await db.getAnnotations([...ids])
+  const issues = Object.fromEntries(visibleManagedIssues(savedIssues, snapshot)
+    .map(issue => [issue.findingId, { url: issue.issueUrl!, autoFix: issue.autoFixUrl }]))
+  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), ...Object.keys(issues)])
+  const reports = Object.fromEntries([...visible].map(([id, report]) => [id, [...report.ids].filter(finding => annotated.has(finding))]))
+  return { reports, entries, comments, issues }
+}

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
+}

package/server-managed/type-only-worker.js

@@ -0,0 +1,19 @@
+// Which of a comparison's pairs of files changed in types alone (type-only.ts),
+// as @preventive/compare's compareTrees stamps a change `typeOnly`, off the
+// server's event loop: each pair a tree of a file a side, a side not there
+// none, its paths as they are, which say what a file is. Two paths pair as one
+// change wherever compareTrees takes them for a rename at all; where it
+// doesn't, the pair is types only where each of its two changes is, as each
+// side holds types alone and neither keeps an `export {}`, which is what it
+// would stamp of them paired. `[true, false, ...]` by pair.
+import { parentPort, workerData } from 'node:worker_threads'
+import { compareTrees } from '@preventive/compare'
+
+const tree = file => (file ? [{ name: file.path, data: file.text }] : [])
+const answer = workerData.pairs.map(([from, to]) => {
+  const changes = compareTrees(tree(from), tree(to), { paths: 'keys', lines: false, renames: Number.MIN_VALUE })
+  return changes.length > 0 && changes.every(change => change.typeOnly === true)
+})
+// Node worker messages have no browser target origin.
+// oxlint-disable-next-line unicorn/require-post-message-target-origin
+parentPort.postMessage(answer)

package/server-managed/type-only.ts

@@ -0,0 +1,103 @@
+// Compare's changes to TypeScript declaration files in types alone (GET
+// /api/bundles/:id/type-only?other=, GET /api/npm/type-only): every file
+// that changed between a comparison's two sides, added and removed ones too,
+// paired as its viewer pairs them (rename-diff.ts comparedFiles), whose
+// change @preventive/compare's compareTrees stamps
+// `typeOnly` -- each side there a file named as a declaration file and
+// proven to hold types alone, so that it runs nothing (proveTypeOnly) --
+// and nothing else. Proven in a worker, off the event loop, a comparison at a
+// time per process, for at most a minute; told a line each, `{ path, hash,
+// otherPath, otherHash }`, a side not there null, which the viewer checks
+// name the files it shows. Access is the caller's to check.
+import { Worker } from 'node:worker_threads'
+import { type ComparedSide, PrettyError, type PrettyRequest } from './pretty-print.ts'
+import { comparedFiles } from './rename-diff.ts'
+
+// TypeScript files, by extension as the pretty-print cache reads them: none
+// other is asked about.
+const TYPESCRIPT = new Set(['ts', 'mts', 'cts'])
+// Comparisons proven at once per process, and those waiting their turn past
+// them, any more refused; the longest one may take, its wait included.
+const MAX_ACTIVE_PROOFS = 1
+const MAX_WAITING_PROOFS = 16
+const PROOF_TIMEOUT_MS = 60_000
+
+type File = PrettyRequest & { text: string }
+export interface TypeOnlyLine { path: string | null; hash: string | null; otherPath: string | null; otherHash: string | null }
+
+let active = 0
+const waiting: Array<() => void> = []
+
+async function turn(deadline: number): Promise<void> {
+  if (active < MAX_ACTIVE_PROOFS) { active++; return }
+  if (waiting.length >= MAX_WAITING_PROOFS) throw new PrettyError(429, 'proof-busy')
+  await new Promise<void>((resolve, reject) => {
+    const next = () => { clearTimeout(timer); resolve() }
+    const timer = setTimeout(() => {
+      waiting.splice(waiting.indexOf(next), 1)
+      reject(new PrettyError(504, 'proof-timeout'))
+    }, deadline - Date.now())
+    waiting.push(next)
+  })
+}
+function done() {
+  const next = waiting.shift()
+  if (next) next()
+  else active--
+}
+
+// Which of `pairs` compareTrees stamps types only, by index, in a worker
+// settled once it is gone; none where it fails, as no proof should.
+function proven(pairs: Array<[File | null, File | null]>, deadline: number): Promise<boolean[]> {
+  let worker: Worker
+  try {
+    worker = new Worker(new URL('./type-only-worker.js', import.meta.url), {
+      workerData: { pairs: pairs.map(sides => sides.map(file => file && { path: file.path, text: file.text })) },
+      // Node's type stripping, which the proof holds oxc's tree to, warns it is experimental.
+      execArgv: ['--disable-warning=ExperimentalWarning'], resourceLimits: { maxOldGenerationSizeMb: 1024 },
+    })
+  } catch (err) {
+    console.warn('managed: a type-only proof could not start:', err)
+    throw new PrettyError(503, 'unavailable')
+  }
+  return new Promise((resolve, reject) => {
+    let answer: boolean[] | null = null, failure = new PrettyError(422, 'unproven')
+    const timer = setTimeout(() => { failure = new PrettyError(504, 'proof-timeout'); void worker.terminate() }, deadline - Date.now())
+    worker.once('message', (told: unknown) => {
+      if (Array.isArray(told) && told.length === pairs.length && told.every(one => typeof one === 'boolean')) answer = told
+      void worker.terminate()
+    })
+    worker.once('error', err => { console.warn('managed: a type-only proof failed:', err) })
+    worker.once('exit', () => {
+      clearTimeout(timer)
+      if (answer) resolve(answer)
+      else reject(failure)
+    })
+  })
+}
+
+// The files that changed between a comparison's two sides in types alone,
+// as the viewer pairs them, a line each once all are proven, in path order.
+export function typeOnlyFiles([base, other]: readonly [ComparedSide, ComparedSide]): AsyncGenerator<TypeOnlyLine> {
+  const typescript = ({ files }: ComparedSide) => new Map(files.filter(file => TYPESCRIPT.has(file.extension)).map(file => [file.path, file]))
+  const [olds, news] = [typescript(base), typescript(other)]
+  const { changed, onlyBase, onlyOther } = comparedFiles([base, other])
+  // A side there not a TypeScript file this reads leaves its pair out; one not there is null.
+  const pairs = [...changed.map(({ path, basePath = path }) => [olds.get(basePath), news.get(path)]),
+    ...onlyBase.map(({ path, basePath = path }) => [olds.get(basePath), null]), ...onlyOther.map(({ path }) => [null, news.get(path)])]
+    .filter((sides): sides is [File | null, File | null] => sides.every(file => file !== undefined) && sides.some(file => file !== null) && sides[0]?.hash !== sides[1]?.hash)
+    .toSorted(([a, b], [c, d]) => {
+      const [x, y] = [(b ?? a)!.path, (d ?? c)!.path]
+      return x < y ? -1 : x > y ? 1 : 0
+    })
+  return (async function* () {
+    if (pairs.length === 0) return
+    const deadline = Date.now() + PROOF_TIMEOUT_MS
+    await turn(deadline)
+    let stamped
+    try { stamped = await proven(pairs, deadline) } finally { done() }
+    for (const [i, [from, to]] of pairs.entries()) {
+      if (stamped[i]) yield { path: from?.path ?? null, hash: from?.hash ?? null, otherPath: to?.path ?? null, otherHash: to?.hash ?? null }
+    }
+  })()
+}