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

package/server-managed/bundle-build-worker.js

@@ -0,0 +1,111 @@
+import { parentPort, workerData } from 'node:worker_threads'
+import { Buffer } from 'node:buffer'
+import { posix } from 'node:path'
+import { brotliCompressSync } from 'node:zlib'
+import { buildGitHubBundle, setCacheDir } from '@exodus/stasis/vfs-bundle'
+import { brotliOptions } from '@exodus/stasis-core/brotli'
+import { HttpError, createClient } from '@preventive/upstream/github.js'
+import { githubBundleFilename } from './bundle-build.ts'
+import { bundleBuildDiagnostic } from './bundle-build-diagnostics.js'
+
+const regularFile = entry => entry.type === 'blob' && ['100644', '100755'].includes(entry.mode)
+
+async function projectDirectory(input, github, client) {
+  // Input validation permits either JS/TS entries or Solidity entries, never a mix.
+  const manifests = input.entries[0].endsWith('.sol') ? ['foundry.toml', 'soldeer.toml', 'soldeer.lock'] : ['package.json']
+  if (!input.directory) return ''
+  for (let directory = input.directory; ; directory = posix.dirname(directory).replace(/^\.$/u, '')) {
+    const entries = await client.listRepoDir({ repo: github, sha: input.commit, directory: directory || undefined })
+    if (entries.some(entry => manifests.includes(entry.path) && regularFile(entry))) return directory
+    if (!directory) return input.directory
+  }
+}
+
+// The name Stasis read from the package.json in the project directory we
+// provide, where its module holds bundled files. JS builds only: a Solidity
+// build records `solidity-bundle` for a package.json without name and version.
+async function packageName(input, github, project, bundle, client) {
+  if (!project || input.entries[0].endsWith('.sol')) return null
+  const entries = await client.listRepoDir({ repo: github, sha: input.commit, directory: project })
+  if (!entries.some(entry => entry.path === 'package.json' && regularFile(entry))) return null
+  const name = bundle.modules.get(posix.relative(bundle.repo?.directory ?? '', project) || '.')?.name
+  return typeof name === 'string' ? name : null
+}
+
+// Prisma Client is what `prisma generate` writes, not what the repo holds: for
+// a JS project whose package.json depends on a @prisma/ package, Stasis
+// generates it before the scan (generate: ['prisma']).
+async function prismaGenerate(input, github, project, client) {
+  if (input.entries[0].endsWith('.sol')) return []
+  const listing = await client.listRepoDir({ repo: github, sha: input.commit, directory: project || undefined })
+  if (!listing.some(entry => entry.path === 'package.json' && regularFile(entry))) return []
+  const text = await client.getRepoFile({ repo: github, path: posix.join(project, 'package.json'), ref: input.commit })
+  let manifest
+  try { manifest = JSON.parse(text) } catch { return [] }
+  const named = ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies']
+    .flatMap(field => manifest?.[field] !== null && typeof manifest?.[field] === 'object' ? Object.keys(manifest[field]) : [])
+  return named.some(name => name.startsWith('@prisma/')) ? ['prisma'] : []
+}
+
+export async function buildStasisBundle({ input, github, token, maxBytes, scopes, cacheDir = null }, client = createClient({ token }), progress = () => {}) {
+  const allowed = path => scopes.some(scope => !scope || path === scope || path.startsWith(scope + '/'))
+  // Reuse these immutable listings when Stasis discovers the lockfile root.
+  const listings = new Map()
+  const buildClient = { ...client, listRepoDir(options) {
+    const key = JSON.stringify([options.repo, options.sha, options.directory ?? ''])
+    if (!listings.has(key)) listings.set(key, client.listRepoDir(options))
+    return listings.get(key)
+  } }
+  // Upstream's disk cache keeps the npm tarballs and version documents, and
+  // the repo's tree, in `cacheDir`; without one (Vercel), nothing is kept on
+  // disk. This fresh worker inherits no application credentials but NPM_TOKEN.
+  setCacheDir(cacheDir ?? false)
+  progress('build')
+  const project = await projectDirectory(input, github, buildClient)
+  if (!allowed(project)) throw new Error('build-scope')
+  const generate = await prismaGenerate(input, github, project, buildClient)
+  const { bundle } = await buildGitHubBundle({
+    github, sha: input.commit, directory: project || undefined,
+    entries: input.entries.map(entry => posix.relative(project || '.', entry)),
+    ...input.options, client: buildClient, ...(cacheDir === null && { cache: false }), ...(generate.length > 0 && { generate }),
+  })
+  const directory = bundle.repo?.directory ?? ''
+  progress('scope')
+  // Imports outside the selected package may widen the root. Never publish it under a
+  // narrower team grant: the storage location must cover the actual bundle.
+  if (!allowed(directory)) throw new Error('build-scope')
+  progress('serialize')
+  const serialized = bundle.serialize()
+  if (Buffer.byteLength(serialized) > 200 * 1024 * 1024) throw new Error('too-large')
+  progress('compress')
+  const bytes = brotliCompressSync(serialized, brotliOptions())
+  if (bytes.length > maxBytes) throw new Error('too-large')
+  const name = await packageName(input, github, project, bundle, buildClient)
+  return { bytes, directory, filename: githubBundleFilename(github, project, input.commit, name) }
+}
+
+// The code a failed build answers with. Never upstream bodies or paths outside
+// the caller's grants: those stay in the diagnostic. A missing or ambiguous
+// lockfile, or the named one missing, is the lockfile's.
+export function buildErrorCode(error, message) {
+  if (['build-scope', 'too-large'].includes(message)) return message
+  if (error instanceof HttpError) return error.status === 429 ? 'github-rate-limited' : 'github-build-failed'
+  return /no packageManager given|lockfile installs|no (?:pnpm-lock\.yaml|yarn\.lock|package-lock\.json|soldeer\.lock) found in /u.test(message) ? 'build-lockfile' : 'build-failed'
+}
+
+if (parentPort && workerData?.type === 'managed-bundle-build') {
+  // Send diagnostics to the request's parent thread, which writes them before
+  // returning the HTTP response. Worker stdout can be lost on termination.
+  const send = message => {
+    // Node worker messages have no browser target origin.
+    // oxlint-disable-next-line unicorn/require-post-message-target-origin
+    parentPort.postMessage(message)
+  }
+  try {
+    send(await buildStasisBundle(workerData, undefined, stage => send({ type: 'progress', stage })))
+  } catch (error) {
+    const diagnostic = bundleBuildDiagnostic(error, workerData.token)
+    const code = buildErrorCode(error, diagnostic.message)
+    send({ error: code, status: code === 'too-large' ? 413 : code === 'build-scope' ? 403 : 422, diagnostic })
+  }
+}

package/server-managed/bundle-build.ts

@@ -0,0 +1,198 @@
+import { Buffer } from 'node:buffer'
+import { createHash, randomUUID } from 'node:crypto'
+import { posix } from 'node:path'
+import { Worker } from 'node:worker_threads'
+import { BUNDLE_BUILD_TIMEOUT_MS, type BundleBuildLeaseStore } from './bundle-build-leases.ts'
+import { type BundleBuildDiagnostic, type BundleBuildStage, bundleBuildDiagnostic } from './bundle-build-diagnostics.js'
+import type { BundleBuildConditions } from './db-methods.ts'
+
+export class BundleBuildError extends Error {
+  status: number
+  code: string
+  constructor(status: number, code: string) { super(code); this.status = status; this.code = code }
+}
+
+export interface BundleBuildInput {
+  repoId: number
+  commit: string
+  entries: string[]
+  directory: string
+  options: { conditions?: string[]; mainFields?: string[]; metro?: boolean; platforms?: string[]; jsx?: boolean; packageManager?: 'soldeer' }
+  // What the stored bundle records; null for Solidity, which takes no conditions.
+  conditions: BundleBuildConditions | null
+}
+
+function path(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0 && value.length <= 1024 && !/[\\\p{Cc}]/u.test(value)
+    && value.split('/').every(part => part !== '' && part !== '.' && part !== '..')
+}
+
+export function parseBundleBuild(value: unknown): BundleBuildInput {
+  const fail = (code = 'bad-request'): never => { throw new BundleBuildError(400, code) }
+  if (value == null || typeof value !== 'object' || Array.isArray(value)) return fail()
+  const { repoId, commit, entries, conditions } = value as Record<string, unknown>
+  if (typeof repoId !== 'number' || !Number.isSafeInteger(repoId) || repoId <= 0
+    || typeof commit !== 'string' || !/^[a-f\d]{40}$/u.test(commit)
+    || !Array.isArray(entries) || entries.length === 0 || entries.length > 100 || !entries.every(path)) return fail()
+  const selected = [...new Set(entries as string[])]
+  const scripts = selected.every(entry => /\.[cm]?[tj]sx?$/iu.test(entry))
+  if (!scripts && !selected.every(entry => entry.endsWith('.sol'))) return fail('unsupported-entries')
+  const parts = posix.dirname(selected[0]!).split('/').filter(part => part !== '.')
+  for (const entry of selected) {
+    const parent = posix.dirname(entry).split('/')
+    while (parts.some((part, i) => parent[i] !== part)) parts.pop()
+  }
+  // Stasis builds Solidity with Soldeer alone. Named, a JS lockfile beside or
+  // above the project no longer leaves it unable to tell which one installs it.
+  const options: BundleBuildInput['options'] = scripts ? {} : { packageManager: 'soldeer' }
+  let recorded: BundleBuildConditions | null = null
+  if (scripts) {
+    if (conditions == null || typeof conditions !== 'object' || Array.isArray(conditions)) return fail('bad-conditions')
+    const { preset, conditions: names, platforms } = conditions as Record<string, unknown>
+    if (typeof preset !== 'string' || !['node', 'browser', 'metro'].includes(preset) || !Array.isArray(names) || names.length > 16
+      || !names.every(name => typeof name === 'string' && name.length > 0 && name.length <= 64
+        && !/^\.|^\d+$|[\s,/\\\p{Cc}]/u.test(name) && !['default', 'import', 'require'].includes(name))) return fail('bad-conditions')
+    if (preset === 'metro') {
+      if (names.length !== 1 || names[0] !== 'react-native') return fail('metro-conditions')
+      if (!Array.isArray(platforms) || platforms.length === 0 || platforms.length > 2
+        || !platforms.every(platform => ['ios', 'android'].includes(platform))) return fail('bad-conditions')
+      // React Native's convention puts JSX in .js files, which Stasis parses as
+      // JSX only on request. TypeScript is left to Stasis to detect.
+      Object.assign(options, { metro: true, platforms: [...new Set(platforms)], jsx: true })
+    } else {
+      options.conditions = [...new Set(names)]
+      if (preset === 'browser') options.mainFields = ['browser', 'module', 'main']
+    }
+    recorded = { preset: preset as BundleBuildConditions['preset'], conditions: [...new Set(names as string[])],
+      platforms: options.platforms ?? [] }
+  }
+  return { repoId, commit, entries: selected, directory: parts.join('/'), options, conditions: recorded }
+}
+
+// A package name as a filename base: `@scope/name` as `scope-name`, or as
+// `name` alone where it is `scope` or already starts with `scope-`. Null for
+// a name npm could not publish by its length or leading dot.
+function packageBase(name: string): string | null {
+  const match = name.length <= 214 ? /^(?:@([^/.][^/]*)\/)?([^/.][^/]*)$/u.exec(name) : null
+  if (!match) return null
+  const base = match[2]!, scope = match[1]
+  return scope === undefined || base === scope || base.startsWith(`${scope}-`) ? base : `${scope}-${base}`
+}
+
+// Same portable name and 255-character limit as Stasis's githubBundleFile
+// (src/cmd/github-bundle.js), which is not a public package export, except
+// that a usable `packageName` replaces both the repo and the directory.
+export function githubBundleFilename(github: string, directory: string, commit: string, packageName: string | null = null): string {
+  const portable = (value: string) => value.replaceAll(/[^\w.-]/gu, '_')
+  const tail = `.${portable(commit.slice(0, 7))}.stasis.code.br`
+  const named = packageName === null ? null : packageBase(packageName)
+  if (named !== null) return `${portable(named)}${tail}`
+  const repo = portable(github.replace('/', '-'))
+  if (!directory) return `${repo}${tail}`
+  const room = 255 - `${repo}.${tail}`.length
+  let dir = portable(directory.replaceAll('/', '-'))
+  if (dir.length > room) dir = `${dir.slice(0, room - 9)}_${createHash('sha256').update(directory).digest('hex').slice(0, 8)}`
+  return `${repo}.${dir}${tail}`
+}
+
+export interface BuiltBundle { bytes: Uint8Array; directory: string; filename: string }
+export interface BuildRequest {
+  input: BundleBuildInput; github: string; token: string | null; maxBytes: number; scopes: (string | null)[]
+  // Upstream's disk cache for what a build fetches (setCacheDir), or null for
+  // none, as on Vercel. Resolved here: the worker's env holds NPM_TOKEN alone.
+  cacheDir: string | null
+}
+// An extra per-process ceiling; admission must also hold the shared DB lease.
+const active = new Set<string>()
+
+export async function withBundleBuildLease<T>(db: BundleBuildLeaseStore, userId: string, signal: AbortSignal,
+  work: (signal: AbortSignal) => Promise<T>): Promise<T> {
+  signal.throwIfAborted()
+  const owner = randomUUID(), started = performance.now(), timeout = new AbortController()
+  const expired = () => timeout.abort(new BundleBuildError(504, 'build-timeout'))
+  const timer = setTimeout(expired, BUNDLE_BUILD_TIMEOUT_MS)
+  const combined = AbortSignal.any([signal, timeout.signal])
+  let claimed = false
+  try {
+    claimed = await db.claimBundleBuildLease(userId, owner)
+    if (!claimed) throw new BundleBuildError(429, 'build-busy')
+    // Account for a slow/lost claim response or a suspended invocation before
+    // starting work. The three-minute budget starts before lease acquisition.
+    if (performance.now() - started >= BUNDLE_BUILD_TIMEOUT_MS) expired()
+    combined.throwIfAborted()
+    return await work(combined)
+  } catch (error) {
+    if (timeout.signal.aborted && !signal.aborted) throw timeout.signal.reason
+    throw error
+  } finally {
+    clearTimeout(timer)
+    // buildRepositoryBundle waits for worker termination before settling.
+    // Unknown claim/release outcomes expire safely without starting more work.
+    if (claimed) await db.releaseBundleBuildLease(owner)
+  }
+}
+
+// Parsing repositories and compressing bundles stays off the HTTP event loop.
+// Cap concurrent builds, terminate disconnected/timed-out work, and share no
+// credentials or mutable Stasis state between requests.
+export async function buildRepositoryBundle(userId: string, request: BuildRequest, signal: AbortSignal): Promise<BuiltBundle> {
+  if (active.has(userId) || active.size >= 2) throw new BundleBuildError(429, 'build-busy')
+  signal.throwIfAborted()
+  active.add(userId)
+  let worker: Worker | undefined
+  let workerUrl: URL | undefined
+  let stage: BundleBuildStage = 'worker-start'
+  const buildId = randomUUID(), started = performance.now()
+  const context = { buildId, repoId: request.input.repoId, github: request.github, commit: request.input.commit,
+    directory: request.input.directory, entryCount: request.input.entries.length, node: process.version }
+  const log = (event: string, details: Record<string, unknown> = {}) => {
+    const write = event === 'failed' ? console.error : console.info
+    write('managed-bundle-build:', JSON.stringify({ ...context, workerUrl: workerUrl?.href, event, stage, elapsedMs: Math.round(performance.now() - started), ...details }))
+  }
+  try {
+    workerUrl = new URL('./bundle-build-worker.js', import.meta.url)
+    log('started')
+    // Upstream reads NPM_TOKEN from the env for scoped packages, which npm
+    // answers with 404 when private and asked without it. Nothing else passes.
+    const npmToken = process.env['NPM_TOKEN']
+    const env = npmToken ? { NPM_TOKEN: npmToken } : {}
+    worker = new Worker(workerUrl, {
+      workerData: { ...request, type: 'managed-bundle-build' }, env, execArgv: [], resourceLimits: { maxOldGenerationSizeMb: 512 },
+    })
+    const running = worker
+    return await new Promise((resolve, reject) => {
+      let settled = false
+      const cleanup = () => { clearTimeout(timer); signal.removeEventListener('abort', abort) }
+      const fail = (status: number, code: string, details: Record<string, unknown> = {}) => {
+        if (settled) return
+        settled = true
+        cleanup()
+        log(code === 'build-cancelled' ? 'cancelled' : 'failed', { code, ...details })
+        reject(new BundleBuildError(status, code))
+      }
+      const timer = setTimeout(() => fail(504, 'build-timeout'), BUNDLE_BUILD_TIMEOUT_MS)
+      const abort = () => fail(signal.reason instanceof BundleBuildError ? signal.reason.status : 499,
+        signal.reason instanceof BundleBuildError ? signal.reason.code : 'build-cancelled')
+      signal.addEventListener('abort', abort, { once: true })
+      running.on('message', (message: BuiltBundle & { type?: string; stage?: BundleBuildStage; error?: string; status?: number; diagnostic?: BundleBuildDiagnostic }) => {
+        if (settled) return
+        if (message.type === 'progress' && message.stage) { stage = message.stage; log('progress'); return }
+        if (message.error) { fail(message.status ?? 422, message.error, { diagnostic: message.diagnostic }); return }
+        settled = true
+        cleanup()
+        log('completed', { byteSize: message.bytes.length })
+        resolve({ bytes: Buffer.from(message.bytes), directory: message.directory, filename: message.filename })
+      })
+      running.once('error', error => fail(422, 'build-failed', { diagnostic: bundleBuildDiagnostic(error, request.token) }))
+      running.once('exit', exitCode => fail(422, 'build-failed', { exitCode }))
+      if (signal.aborted) abort()
+    })
+  } catch (error) {
+    if (!(error instanceof BundleBuildError)) {
+      log('failed', { code: 'build-failed', diagnostic: bundleBuildDiagnostic(error, request.token) })
+    }
+    throw error
+  } finally {
+    try { await worker?.terminate() } finally { active.delete(userId) }
+  }
+}

package/server-managed/bundle-cache.ts

@@ -0,0 +1,199 @@
+// Metadata is cached as Brotli. Contents use the stored Brotli bytes directly:
+// unchanged Stasis uploads or sourcemaps compressed once at upload.
+import { Buffer } from 'node:buffer'
+import { brotliDecompress } from 'node:zlib'
+import { promisify } from 'node:util'
+import { bundleEdges } from '@preventive/sourcemap/edges.js'
+import { BUNDLE_METADATA_VERSION, type BundleDetails, createBundleMetadata, createBundleSummary, parseBundleContents, parseBundleMetadata } from '../common/bundle-metadata.js'
+import { bundleReasons } from '../common/bundle-reasons.js'
+import { sourcemapEdges } from '../common/bundle-sourcemap.js'
+import { type BundleAdvisoryInventory, bundleAdvisoryInventory } from './bundle-advisory-inventory.ts'
+import { decodeUtf8 } from '../common/utf8.js'
+import type { OpenedBlob } from './blob-store.ts'
+import type { BundleStore } from './bundle-store.ts'
+import { encodeBrotli } from './brotli.ts'
+import type { ManagedBundle, ManagedDb } from './db.ts'
+import { CacheMissError } from './cache-storage.ts'
+import { SUMMARY_FILENAME, createBundleSummaryCache } from './bundle-summary-cache.ts'
+
+const decompress = promisify(brotliDecompress)
+const MAX_DECODED_BYTES = 512 * 1024 * 1024
+export const MAX_PACKAGE_INVENTORY_BYTES = 1024 * 1024
+export type BundleCachePart = 'metadata' | 'contents'
+export type BundleCacheRecord = Pick<ManagedBundle, 'id' | 'integrity' | 'filename' | 'kind' | 'byteSize'>
+export interface BundleSummary { files: number; codeFiles: number; lines: number; commit?: string; stasisVersion?: number; versionedPackages?: number }
+
+export async function readBundleDetails(record: BundleCacheRecord, store: BundleStore) {
+  const bytes = await store.get(record.id, record.kind)
+  if (!bytes) return null
+  const decoded = record.kind === 'stasis' || record.kind === 'sourcemap' ? await decompress(bytes, { maxOutputLength: MAX_DECODED_BYTES }) : bytes
+  if (decoded.length > MAX_DECODED_BYTES) throw new Error('Decoded bundle too large')
+  return parseBundleContents(decodeUtf8(decoded), { integrity: record.integrity, kind: record.kind, size: record.byteSize })
+}
+
+export interface BundleCacheStorage {
+  exists(id: string, file: string): Promise<boolean>
+  put(id: string, file: string, bytes: Buffer): Promise<void>
+  open(id: string, file: string): Promise<OpenedBlob>
+  // Remove all cached versions for this bundle, including legacy derivatives.
+  delete(id: string): Promise<void>
+}
+
+const filename = `v${BUNDLE_METADATA_VERSION}-metadata.json.br`
+const packagesFilename = 'v6-advisory-inventory.json'
+
+// All scopes share one bounded derivative. Never decode full bundle metadata
+// on advisory requests, including when selecting a reason. Persist null when
+// the combined inventory exceeds the budget, without disabling metadata.
+function encodePackageInventory(details: BundleDetails): Buffer {
+  const parts: string[] = []
+  let size = 0
+  function append(part: string) {
+    size += Buffer.byteLength(part)
+    if (size > MAX_PACKAGE_INVENTORY_BYTES) return false
+    parts.push(part)
+    return true
+  }
+  function entries(rows: unknown[]) {
+    if (!append('[')) return false
+    let first = true
+    for (const row of rows) {
+      if (!append(`${first ? '' : ','}${JSON.stringify(row)}`)) return false
+      first = false
+    }
+    return append(']')
+  }
+  function inventory(paths: Set<string> | null) {
+    const { packages, skipped } = bundleAdvisoryInventory(details, paths)
+    return append('{"packages":') && entries(packages) && append(',"skipped":') && entries(skipped) && append('}')
+  }
+  append('{"all":')
+  if (!inventory(null) || !append(',"reasons":{')) return Buffer.from('null')
+  let first = true
+  for (const [reason, paths] of bundleReasons(details)) {
+    if (!append(`${first ? '' : ','}${JSON.stringify(reason)}:`) || !inventory(paths)) return Buffer.from('null')
+    first = false
+  }
+  if (!append('}}')) return Buffer.from('null')
+  return Buffer.from(parts.join(''))
+}
+
+// What a catalog sends of a bundle before it opens. A Stasis bundle's
+// `versionedPackages` counts the name@version pairs its unscoped advisory
+// audit covers, audited or skipped: with none, Advisories has nothing to show.
+export function bundleSummary(details: BundleDetails, metadata?: Parameters<typeof createBundleSummary>[1]): BundleSummary {
+  const summary = createBundleSummary(details, metadata)
+  if (details.kind !== 'stasis') return summary
+  const { packages, skipped } = bundleAdvisoryInventory(details)
+  return { ...summary, versionedPackages: packages.reduce((count, pkg) => count + pkg.versions.length, 0) + skipped.length }
+}
+
+// A sourcemap's edges, read with the parser (edges.js) that the client goes
+// without: every map's, where the client reads Metro's alone. Without it,
+// the metadata keeps what the client would read. A map with no
+// sourcesContent has no source to read them from.
+function readSourcemapEdges(details: BundleDetails) {
+  if (details.kind !== 'sourcemap' || !details.map?.files.some(file => file.content !== null)) return
+  try { details.edges = sourcemapEdges(details.map, bundleEdges) }
+  catch (err) { console.warn('managed: sourcemap edges failed:', err) }
+}
+
+async function build(record: BundleCacheRecord, storage: BundleCacheStorage, db: ManagedDb, store: BundleStore) {
+  const details = await readBundleDetails(record, store)
+  if (!details) throw new Error('Bundle bytes unavailable')
+  readSourcemapEdges(details)
+  const metadata = { ...await createBundleMetadata(details), id: record.id, filename: record.filename }
+  const body = await encodeBrotli(Buffer.from(JSON.stringify(metadata)))
+  if (!(await db.getBundle(record.id))) throw new Error('Bundle deleted')
+  await storage.put(record.id, filename, body)
+  if (record.kind === 'stasis') await storage.put(record.id, packagesFilename, encodePackageInventory(details))
+  const summary = bundleSummary(details, metadata)
+  await storage.put(record.id, SUMMARY_FILENAME, Buffer.from(JSON.stringify(summary)))
+  // A different instance may have deleted the row while these writes ran.
+  // Reconcile after publishing so its cleanup cannot be undone by us.
+  if (!(await db.getBundle(record.id))) {
+    await storage.delete(record.id)
+    throw new Error('Bundle deleted')
+  }
+  return summary
+}
+
+export function createBundleCache(storage: BundleCacheStorage, db: ManagedDb, store: BundleStore) {
+  const pending = new Map<string, Promise<void>>()
+  // The database deduplicates by integrity, so each hash has one persistent
+  // bundle/cache directory, shared across teams and repeated uploads.
+  const summaries = createBundleSummaryCache(storage, async record => {
+    const details = await readBundleDetails(record, store)
+    if (!details) throw new Error('Bundle bytes unavailable')
+    return bundleSummary(details)
+  }, id => db.getBundle(id))
+  let queue = Promise.resolve()
+  async function ensure(record: BundleCacheRecord): Promise<void> {
+    const existing = pending.get(record.id)
+    if (existing) return existing
+    const job = (async () => {
+      if (await storage.exists(record.id, filename) && (record.kind !== 'stasis' || await storage.exists(record.id, packagesFilename))) return
+      const work = queue.then(async () => summaries.remember(record, await build(record, storage, db, store)))
+      queue = work.catch(() => {})
+      await work
+    })()
+    pending.set(record.id, job)
+    try { await job } finally { if (pending.get(record.id) === job) pending.delete(record.id) }
+  }
+  async function openCached(record: BundleCacheRecord, file: string) {
+    try { return await storage.open(record.id, file) }
+    catch (error) { if (!(error instanceof CacheMissError)) throw error }
+    await ensure(record)
+    return storage.open(record.id, file)
+  }
+  return {
+    prebuild: ensure,
+    summary: summaries.summary,
+    summaryStatus: summaries.summaryStatus,
+    backfillSummaries: summaries.backfill,
+    async open(record: ManagedBundle, part: BundleCachePart) {
+      if (part === 'contents') {
+        if (record.kind !== 'stasis' && record.kind !== 'sourcemap') throw new Error('Unsupported bundle')
+        const stored = await store.open(record.id, record.kind)
+        if (!stored) throw new Error('Bundle bytes unavailable')
+        return stored
+      }
+      return openCached(record, filename)
+    },
+    // A sourcemap's edges as its metadata keeps them, read with the parser
+    // once, for a derivative that reads the bundle itself (report previews).
+    async sourcemapEdges(record: ManagedBundle): Promise<BundleDetails['edges']> {
+      const cached = await openCached(record, filename)
+      const chunks: Buffer[] = []
+      try { for await (const chunk of cached.stream) chunks.push(Buffer.from(chunk)) }
+      finally { cached.stream.destroy() }
+      const decoded = await decompress(Buffer.concat(chunks), { maxOutputLength: MAX_DECODED_BYTES })
+      return parseBundleMetadata(JSON.parse(decodeUtf8(decoded)), record.integrity).edges
+    },
+    async advisoryInventory(record: ManagedBundle, reason = ''): Promise<BundleAdvisoryInventory | null | undefined> {
+      if (record.kind !== 'stasis') return { packages: [], skipped: [] }
+      const cached = await openCached(record, packagesFilename)
+      try {
+        if (cached.size != null && cached.size > MAX_PACKAGE_INVENTORY_BYTES) return null
+        const chunks: Buffer[] = []
+        let size = 0
+        for await (const chunk of cached.stream) {
+          size += chunk.length
+          if (size > MAX_PACKAGE_INVENTORY_BYTES) return null
+          chunks.push(Buffer.from(chunk))
+        }
+        const inventory = JSON.parse(decodeUtf8(Buffer.concat(chunks)))
+        if (inventory === null) return null
+        return reason ? (Object.hasOwn(inventory.reasons, reason) ? inventory.reasons[reason] : undefined) : inventory.all
+      } finally { cached.stream.destroy() }
+    },
+    async delete(id: string) {
+      // Call after deleting the row. Waiting prevents an in-flight builder
+      // from recreating its files after deletion has completed.
+      await pending.get(id)?.catch(() => {})
+      await summaries.forget(id)
+      await storage.delete(id)
+    },
+  }
+}
+export type BundleCache = ReturnType<typeof createBundleCache>

package/server-managed/bundle-catalog.ts

@@ -0,0 +1,29 @@
+import type { BundleCache, BundleSummary } from './bundle-cache.ts'
+import type { AdminBundle, UserTeamBundle } from './db.ts'
+
+const SUMMARY_READ_CONCURRENCY = 8
+
+// Read only existing summaries: cold/malformed bundles must never trigger
+// parsing or wait for metadata builds before the catalog response is sent.
+export async function bundleSummaries(bundles: readonly (AdminBundle | UserTeamBundle)[], cache?: BundleCache) {
+  const summaries = new Map<string, { summary: BundleSummary | null; summaryRetryAt: number | null }>()
+  if (cache) {
+    const unique = [...new Map(bundles.map(bundle => [bundle.integrity, bundle])).values()]
+    let next = 0
+    // Cold reads may each access remote storage. Bound those requests as well
+    // as the subsequent backfill, without dropping entries from large catalogs.
+    await Promise.all(Array.from({ length: Math.min(SUMMARY_READ_CONCURRENCY, unique.length) }, async () => {
+      while (next < unique.length) {
+        const bundle = unique[next++]!
+        summaries.set(bundle.integrity, await cache.summaryStatus(bundle).catch(() => ({ summary: null, summaryRetryAt: null })))
+      }
+    }))
+  }
+  return summaries
+}
+
+// Called after sending the response. Each cache permits one small batch at a
+// time, deduplicated by content hash, and skips persisted retry-backoff markers.
+export async function backfillBundleSummaries(bundles: readonly (AdminBundle | UserTeamBundle)[], cache?: BundleCache) {
+  await cache?.backfillSummaries([...new Map(bundles.map(bundle => [bundle.integrity, bundle])).values()])
+}