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

package/server-managed/bundle-build.ts

@@ -0,0 +1,168 @@
+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'
+
+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[]; typescript?: boolean; jsx?: boolean }
+}
+
+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 => /\.[mc]?[jt]s$/u.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()
+  }
+  const options: BundleBuildInput['options'] = {}
+  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 (!['node', 'browser', 'metro'].includes(String(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')
+      Object.assign(options, { metro: true, platforms: [...new Set(platforms)] })
+    } else {
+      options.conditions = [...new Set(names)]
+      if (preset === 'browser') options.mainFields = ['browser', 'module', 'main']
+    }
+    options.typescript = true
+    options.jsx = true
+  }
+  return { repoId, commit, entries: selected, directory: parts.join('/'), options }
+}
+
+// Same portable name and 255-character limit as Stasis's githubBundleFile
+// (src/cmd/github-bundle.js), which is not a public package export.
+export function githubBundleFilename(github: string, directory: string, commit: string): string {
+  const portable = (value: string) => value.replaceAll(/[^\w.-]/gu, '_')
+  const repo = portable(github.replace('/', '-'))
+  const tail = `.${portable(commit.slice(0, 7))}.stasis.code.br`
+  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)[] }
+// 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')
+    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,166 @@
+// 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 { BUNDLE_METADATA_VERSION, type BundleDetails, createBundleMetadata, createBundleSummary, parseBundleContents } from '../common/bundle-metadata.js'
+import { bundleReasons } from '../common/bundle-reasons.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 }
+
+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 = 'v4-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(''))
+}
+
+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')
+  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 = createBundleSummary(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 createBundleSummary(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)
+    },
+    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()])
+}

package/server-managed/bundle-store.ts

@@ -0,0 +1,24 @@
+// Sourcemaps are stored once as Brotli. The DB retains the uploaded filename,
+// byte size and integrity so compression does not change report links/dedup.
+import type { Buffer } from 'node:buffer'
+import type { BlobStore, OpenedBlob } from './blob-store.ts'
+import { encodeBrotli } from './brotli.ts'
+
+export interface BundleStore {
+  put(id: string, bytes: Buffer, kind: string | null): Promise<string | null>
+  get(id: string, kind: string | null): Promise<Buffer | null>
+  open(id: string, kind: string | null): Promise<OpenedBlob | null>
+  delete(id: string): Promise<void>
+}
+
+export function createBundleStore(archives: BlobStore, sourcemaps: BlobStore): BundleStore {
+  const storage = (kind: string | null) => kind === 'sourcemap' ? sourcemaps : archives
+  return {
+    async put(id, bytes, kind) {
+      return storage(kind).put(id, kind === 'sourcemap' ? await encodeBrotli(bytes) : bytes)
+    },
+    get: (id, kind) => storage(kind).get(id),
+    open: (id, kind) => storage(kind).open(id),
+    async delete(id) { await Promise.all([archives.delete(id), sourcemaps.delete(id)]) },
+  }
+}

package/server-managed/bundle-summary-cache.ts

@@ -0,0 +1,116 @@
+import { Buffer } from 'node:buffer'
+import { setImmediate } from 'node:timers/promises'
+import { CacheMissError } from './cache-storage.ts'
+import { decodeUtf8 } from '../common/utf8.js'
+import { bundleCommitHash } from '../common/bundle-commit.js'
+import type { BundleCacheRecord, BundleCacheStorage, BundleSummary } from './bundle-cache.ts'
+
+// Version 3 adds the optional source commit; older bundles use bounded backfill.
+export const SUMMARY_FILENAME = 'v3-summary.json'
+const RETRY_MS = 5 * 60_000
+const BACKFILL_LIMIT = 4
+type CachedSummary = BundleSummary | { retryAt: number }
+
+async function readSummary(storage: BundleCacheStorage, id: string): Promise<CachedSummary> {
+  const cached = await storage.open(id, SUMMARY_FILENAME)
+  try {
+    const chunks: Buffer[] = []
+    let size = 0
+    for await (const chunk of cached.stream) {
+      size += chunk.length
+      if (size > 1024) throw new Error('Invalid bundle summary')
+      chunks.push(Buffer.from(chunk))
+    }
+    const summary = JSON.parse(decodeUtf8(Buffer.concat(chunks))) as CachedSummary
+    if (summary && 'retryAt' in summary && Number.isSafeInteger(summary.retryAt) && summary.retryAt > 0) return summary
+    const counts = summary as BundleSummary
+    if (!counts || ![counts.files, counts.codeFiles, counts.lines].every(value => Number.isSafeInteger(value) && value >= 0)
+        || counts.codeFiles > counts.files || (counts.commit !== undefined && !bundleCommitHash(counts.commit))) throw new Error('Invalid bundle summary')
+    return counts
+  } finally { cached.stream.destroy() }
+}
+
+export function createBundleSummaryCache(storage: BundleCacheStorage, build: (record: BundleCacheRecord) => Promise<BundleSummary>, exists: (id: string) => Promise<unknown>) {
+  const entries = new Map<string, { id: string; value: CachedSummary }>()
+  const reads = new Map<string, { id: string; job: Promise<CachedSummary | null> }>()
+  const active = new Map<string, Promise<void>>()
+  let pending: Promise<void> | null = null
+  function remember(record: BundleCacheRecord, value: CachedSummary) {
+    // A completed build supersedes any older storage read still in flight.
+    reads.delete(record.integrity)
+    // Summaries are tiny and immutable by integrity. Refuse overflow admission
+    // instead of evicting the next hit during a scan larger than the cache.
+    if (entries.size >= 4096 && !entries.has(record.integrity)) return
+    entries.set(record.integrity, { id: record.id, value })
+  }
+  function read(record: BundleCacheRecord): Promise<CachedSummary | null> {
+    const known = entries.get(record.integrity)
+    if (known) return Promise.resolve(known.value)
+    const existing = reads.get(record.integrity)
+    if (existing) return existing.job
+    // Concurrent catalogs share the decoded summary, never the response stream.
+    // Only in-flight work is shared: misses and failures remain retryable.
+    const job: Promise<CachedSummary | null> = readSummary(storage, record.id).then(value => {
+      if (reads.get(record.integrity)?.job === job) remember(record, value)
+      return entries.get(record.integrity)?.value ?? value
+    }).catch(error => {
+      if (error instanceof CacheMissError) return null
+      throw error
+    }).finally(() => { if (reads.get(record.integrity)?.job === job) reads.delete(record.integrity) })
+    reads.set(record.integrity, { id: record.id, job })
+    return job
+  }
+  async function publish(record: BundleCacheRecord, value: CachedSummary) {
+    if (!await exists(record.id)) return
+    await storage.put(record.id, SUMMARY_FILENAME, Buffer.from(JSON.stringify(value)))
+    if (!await exists(record.id)) { await storage.delete(record.id); return }
+    remember(record, value)
+  }
+  async function buildOne(record: BundleCacheRecord) {
+    try { await publish(record, await build(record)) }
+    catch { await publish(record, { retryAt: Date.now() + RETRY_MS }).catch(() => {}) }
+  }
+  async function summaryStatus(record: BundleCacheRecord) {
+    const value = ['stasis', 'sourcemap'].includes(record.kind ?? '') ? await read(record) : null
+    return { summary: value && !('retryAt' in value) ? value : null,
+      summaryRetryAt: value && 'retryAt' in value ? value.retryAt : null }
+  }
+  async function backfill(records: readonly BundleCacheRecord[]) {
+    // Start after the catalog has been sent. Keep this work awaited by the
+    // request owner (including serverless), with no detached tasks or backlog.
+    await setImmediate()
+    let attempts = 0
+    for (const record of records) {
+      if (!['stasis', 'sourcemap'].includes(record.kind ?? '')) continue
+      const cached = await read(record).catch(() => null)
+      if (cached && (!('retryAt' in cached) || cached.retryAt > Date.now())) continue
+      if (!await exists(record.id)) continue
+      if (attempts++ >= BACKFILL_LIMIT) break
+      const job = buildOne(record)
+      active.set(record.id, job)
+      try { await job } finally { active.delete(record.id) }
+    }
+  }
+  return {
+    remember,
+    summaryStatus,
+    async summary(record: BundleCacheRecord): Promise<BundleSummary | null> {
+      return (await summaryStatus(record)).summary
+    },
+    backfill(records: readonly BundleCacheRecord[]) {
+      if (pending) return Promise.resolve() // Another catalog already owns the bounded batch.
+      const job = backfill(records).finally(() => { if (pending === job) pending = null })
+      pending = job
+      return job
+    },
+    async forget(id: string) {
+      // Only this bundle can republish its cache during deletion. A stalled
+      // backfill elsewhere must not delay removing these bytes or responding.
+      await active.get(id)
+      for (const [hash, entry] of entries) if (entry.id === id) entries.delete(hash)
+      // Do not wait for remote reads during deletion. Their callers still own
+      // and drain them, but a late response must not repopulate this cache.
+      for (const [hash, entry] of reads) if (entry.id === id) reads.delete(hash)
+    },
+  }
+}

package/server-managed/bundle.ts

@@ -0,0 +1,104 @@
+// Bundle helpers for the managed server: the content-addressed identity used to
+// dedupe stored bundles and to auto-link reports to them.
+//
+// A report's top-level `bundleHashes` lists the `sha512-<base64>` integrities
+// the analyzer ran against (see ui/view/ingest.js); a stored bundle's identity
+// is that same integrity computed from its bytes. Matching the two is how a
+// report auto-links to its bundle.
+import { createHash } from 'node:crypto'
+import type { Buffer } from 'node:buffer'
+import { StringDecoder } from 'node:string_decoder'
+import { createBrotliDecompress } from 'node:zlib'
+
+// `sha512-<base64>` identity for a bundle's bytes. MUST stay byte-identical to
+// the client's common/integrity.js (SHA-512 → standard base64 WITH padding) so
+// a report's `bundleHashes` entries match a stored bundle's computed integrity.
+// (The client uses `Uint8Array.toBase64()`, whose default is standard base64 +
+// padding — the same bytes node:crypto's base64 digest emits.)
+export function bundleIntegrity(bytes: Buffer): string {
+  return `sha512-${createHash('sha512').update(bytes).digest('base64')}`
+}
+
+// Classify an uploaded bundle by filename — mirrors ui/view/ingest.js
+// `bundleKind`: sourcemap (.map) or stasis (stasis.code.br / .stasis.code.br).
+// null for anything else (stored anyway; the kind is informational).
+export function bundleKind(filename: string): 'sourcemap' | 'stasis' | null {
+  // Browsers insert a duplicate-download counter before the final extension.
+  const lower = filename.toLowerCase().replace(/ \(\d+\)(?=\.[^.]*$)/u, '')
+  if (lower.endsWith('.map')) return 'sourcemap'
+  if (lower === 'stasis.code.br' || lower.endsWith('.stasis.code.br')) return 'stasis'
+  return null
+}
+
+interface BundleRepo { github?: unknown; directory?: unknown }
+const HEADER_KEYS = new Set(['version', 'config', 'repo', 'package'])
+const MAX_HEADER_BYTES = 64 * 1024
+
+// Stasis writes origin metadata before entries, formats and source bodies.
+// undefined means another chunk is needed; null means the header has no repo.
+function headerRepo(text: string): BundleRepo | null | undefined {
+  let depth = 0, escaped = false, expectKey = false, quoted = false
+  let key = '', start = 0, valueStart = 0
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]
+    if (quoted) {
+      if (escaped) { escaped = false; continue }
+      if (c === '\\') { escaped = true; continue }
+      if (c !== '"') continue
+      quoted = false
+      if (depth === 1 && expectKey) {
+        key = JSON.parse(text.slice(start, i + 1)) as string
+        if (!HEADER_KEYS.has(key)) return null
+        expectKey = false
+      }
+      continue
+    }
+    if (c === '"') { quoted = true; start = i; continue }
+    if (c === '{' || c === '[') {
+      if (depth === 0 && c !== '{') return null
+      depth++
+      if (depth === 1) expectKey = true
+    } else if (depth === 1 && (c === ',' || c === '}')) {
+      if (key === 'repo') {
+        const repo: unknown = JSON.parse(text.slice(valueStart, i))
+        return repo != null && typeof repo === 'object' && !Array.isArray(repo) ? repo as BundleRepo : null
+      }
+      if (c === '}') return null
+      expectKey = true
+    } else if (c === '}' || c === ']') depth--
+    else if (depth === 1 && c === ':') valueStart = i + 1
+    else if (depth === 0 && c?.trim()) return null
+  }
+  return undefined
+}
+
+// Decode only a bounded prefix, stopping as soon as repo is read or the
+// header ends. Unknown/malformed archives remain uploadable as opaque bytes.
+export async function bundleRepo(bytes: Buffer): Promise<BundleRepo | null> {
+  const stream = createBrotliDecompress({ chunkSize: 4096 })
+  const decoder = new StringDecoder('utf8')
+  let size = 0, text = ''
+  stream.end(bytes)
+  try {
+    for await (const chunk of stream) {
+      size += chunk.length
+      if (size > MAX_HEADER_BYTES) return null
+      text += decoder.write(chunk)
+      const repo = headerRepo(text)
+      if (repo !== undefined) return repo
+    }
+    return null
+  } catch { return null }
+  finally { stream.destroy() }
+}
+
+// Extract the bundle integrities a report declares (its top-level
+// `bundleHashes`). Non-JSON reports (markdown / CSV) or a missing field → [].
+export function reportBundleHashes(bytes: Buffer): string[] {
+  let data: unknown
+  try { data = JSON.parse(bytes.toString('utf8')) } catch { return [] }
+  if (data == null || typeof data !== 'object') return []
+  const hashes = (data as { bundleHashes?: unknown }).bundleHashes
+  if (!Array.isArray(hashes)) return []
+  return hashes.filter((x): x is string => typeof x === 'string' && x !== '')
+}

package/server-managed/cache-storage.ts

@@ -0,0 +1,19 @@
+import type { Buffer } from 'node:buffer'
+import type { OpenedBlob } from './blob-store.ts'
+
+export class CacheMissError extends Error {
+  constructor() { super('Managed cache unavailable') }
+}
+
+// Keys are internal relative paths; delete removes a whole directory of variants.
+export interface CacheStorage {
+  exists(key: string): Promise<boolean>
+  put(key: string, bytes: Buffer): Promise<void>
+  open(key: string): Promise<OpenedBlob>
+  delete(prefix: string): Promise<void>
+}
+
+export function validateCacheKey(key: string): string {
+  if (!key.split('/').every(part => /^[a-z0-9][a-z0-9.-]*$/iu.test(part))) throw new Error('Invalid cache key')
+  return key
+}

package/server-managed/cli.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// Executable entry for the managed-server bin. See server-e2e/cli.js for the
+// full rationale: Node refuses to strip TypeScript types from files under
+// node_modules, so once this package is installed as a dependency
+// server-managed/index.ts can't be executed directly. Register the in-thread
+// type-stripping hook FIRST, then load the server via a dynamic import (a
+// static import would be fetched before the hook is active) and start it.
+//
+// Imported here rather than run as the process entry, so index.ts's
+// `import.meta.main` auto-start gate stays off and we call `start()` ourselves.
+import '../strip-types-loader.js'
+const command = process.argv[2]
+if (command === '--storage-encryption-status') {
+  const { storageCommand } = await import('./storage-command.ts')
+  await storageCommand(process.argv[3])
+} else if (command) {
+  throw new Error(`Unknown command: ${command}`)
+} else {
+  const { start } = await import('./index.ts')
+  await start()
+}