@preventive/triage 1.0.0-alpha.27 → 1.0.0-alpha.29

package/server-managed/index.ts

@@ -1,5 +1,6 @@
 // Managed HTTP app and standalone boot. The combined launcher mounts this
 // same app on e2e's listener; storage, routing and cleanup stay here.
+import { randomUUID } from 'node:crypto'
 import { type Server, createServer } from 'node:http'
 import { fileURLToPath } from 'node:url'
 import { createOriginGate } from '../server-common/origin.ts'
@@ -48,17 +49,31 @@ async function assembleManagedApp(config: ManagedConfig, options: ManagedAppOpti
 
   let cleanup: Promise<void> | undefined
   let nextCleanupAt = 0
-  function reap(): Promise<void> {
+  const maintenance = new AbortController()
+  function reap(automatic = false): Promise<void> {
     if (cleanup) return cleanup
+    if (isShuttingDown()) return Promise.resolve()
     const startedAt = Date.now()
     nextCleanupAt = startedAt + REAP_INTERVAL_MS
     let sessions = 0, uploads = 0
-    cleanup = runReapers({
-      sessions: async () => { sessions = await db.deleteExpiredSessions(Date.now()) },
-      ...(storage.reapUploads ? { uploads: async () => { uploads = await storage.reapUploads!() } } : {}),
-      ...('reapStorage' in storage ? { storage: () => storage.reapStorage() } : {}),
-    }).then(() => {
+    cleanup = (async () => {
+      const owner = automatic && config.serverless ? randomUUID() : null
+      if (owner && !await db.claimMaintenanceLease(owner, startedAt, startedAt + Math.max(300_000, (config.storageEncryptionMigrateMaxMs ?? 0) + 60_000), config.storageEncryptionMigrate)) return false
+      let succeeded = false
+      try {
+        await runReapers({
+          sessions: async () => { sessions = await db.deleteExpiredSessions(Date.now()) },
+          ...(storage.reapUploads ? { uploads: async () => { uploads = await storage.reapUploads!(maintenance.signal) } } : {}),
+          ...('reapStorage' in storage ? { storage: () => storage.reapStorage(maintenance.signal) } : {}),
+        })
+        succeeded = true
+        return true
+      } finally {
+        if (owner) await db.finishMaintenanceLease(owner, Date.now() + (succeeded ? REAP_INTERVAL_MS : REAP_RETRY_MS))
+      }
+    })().then(ran => {
       nextCleanupAt = Date.now() + REAP_INTERVAL_MS
+      if (!ran) return
       return console.info(`managed-reaper: removed ${sessions} expired session(s), ${uploads} stale upload part(s) in ${Date.now() - startedAt}ms`)
     }, err => {
       nextCleanupAt = Date.now() + REAP_RETRY_MS
@@ -69,14 +84,15 @@ async function assembleManagedApp(config: ManagedConfig, options: ManagedAppOpti
   }
   function automaticReap(): Promise<void> {
     if (isShuttingDown() || cleanup || Date.now() < nextCleanupAt) return Promise.resolve()
-    return reap().catch(err => console.warn('managed-reaper: cleanup failed:', err))
+    return reap(true).catch(err => console.warn('managed-reaper: cleanup failed:', err))
   }
   async function handleRequest(req: Parameters<typeof routeRequest>[0], res: Parameters<typeof routeRequest>[1]): Promise<void> {
-    const maintenance = automaticReap()
-    // Send the normal response without waiting for storage housekeeping, but
-    // keep the invocation alive until both finish. No detached serverless work.
+    const pendingMaintenance = automaticReap()
+    // Send the normal response without waiting for storage housekeeping. The
+    // Vercel entrypoint registers this whole promise with waitUntil; awaiting
+    // work after res.end() alone cannot extend a serverless invocation.
     try { await routeRequest(req, res) }
-    finally { await maintenance }
+    finally { await pendingMaintenance }
   }
   const gcTimer = config.serverless ? null : setInterval(() => {
     void automaticReap()
@@ -85,6 +101,7 @@ async function assembleManagedApp(config: ManagedConfig, options: ManagedAppOpti
 
   function stop(): void {
     shuttingDown = true
+    maintenance.abort()
     if (gcTimer) clearInterval(gcTimer)
   }
 

package/server-managed/management-catalog.ts

@@ -0,0 +1,45 @@
+import { roleAtLeast } from '../common/managed/roles.ts'
+import { type RepoScope, contentAccess } from './content-access.ts'
+import type { AdminBundle, AdminReport, ManagedDb } from './db-methods.ts'
+import { ManagedMutationError } from './management.ts'
+
+type CatalogAccess = { repos: { repoId: number; fullName: string }[]; repoScopes: RepoScope[] | null }
+export interface ManagementCatalogStore {
+  getReportCatalog(sessionId: string, now: number): Promise<CatalogAccess & { reports: (AdminReport & { canChangeRepo: boolean })[] }>
+  getBundleCatalog(sessionId: string, now: number): Promise<CatalogAccess & { bundles: (AdminBundle & { canChangeRepo: boolean })[] }>
+}
+type CatalogDb = Pick<ManagedDb, 'getReportAccessSnapshot' | 'listRepoScopesForUser' | 'listSelectedRepos'
+  | 'listReports' | 'listBundles' | 'listReadableBundleIds'>
+
+// The outer store method owns one read snapshot. Use raw methods here so the
+// session, grants, rows and action flags agree without per-row transactions.
+export function managementCatalogMethods(db: CatalogDb): ManagementCatalogStore {
+  async function access(sessionId: string, now: number) {
+    const snapshot = await db.getReportAccessSnapshot(sessionId, now, [])
+    if (!snapshot) throw new ManagedMutationError(401, 'unauthenticated')
+    if (!roleAtLeast(snapshot.user.role, 'manage')) throw new ManagedMutationError(403, 'forbidden')
+    const scope = await contentAccess(db, snapshot.user)
+    const repos = (await db.listSelectedRepos()).filter(scope.bundle).map(({ repoId, fullName }) => ({ repoId, fullName }))
+    return { userId: snapshot.user.role === 'admin' ? undefined : snapshot.user.id, scope, repos }
+  }
+  return {
+    async getReportCatalog(sessionId, now) {
+      const { userId, scope, repos } = await access(sessionId, now)
+      const reports = await db.listReports(userId)
+      const linked = reports.flatMap(report => report.bundleId ? [report.bundleId] : [])
+      const readable = userId === undefined ? new Set(linked) : new Set(await db.listReadableBundleIds(userId, linked))
+      return { repos, repoScopes: scope.scopes, reports: reports.map(report => ({ ...report,
+        canChangeRepo: report.repoId === null || scope.report(report),
+        bundleId: report.bundleId && readable.has(report.bundleId) ? report.bundleId : null,
+        bundleFilename: report.bundleId && readable.has(report.bundleId) ? report.bundleFilename : null,
+      })) }
+    },
+    async getBundleCatalog(sessionId, now) {
+      const { userId, scope, repos } = await access(sessionId, now)
+      const bundles = await db.listBundles(userId)
+      return { repos, repoScopes: scope.scopes, bundles: bundles.map(bundle => ({ ...bundle,
+        canChangeRepo: bundle.repoId === null || scope.report(bundle),
+      })) }
+    },
+  }
+}

package/server-managed/object-storage-vercel.ts

@@ -24,7 +24,7 @@ export async function openVercelObjectStorage(token: string, sdk?: VercelBlobSdk
         }
         return { size: result.blob.size === 0 ? null : result.blob.size, version: result.blob.etag,
           modifiedAt: new Date(result.blob.uploadedAt ?? Date.now()).getTime(),
-          stream: Readable.fromWeb(result.stream as Parameters<typeof Readable.fromWeb>[0]) }
+          stream: Readable.fromWeb(result.stream as Parameters<typeof Readable.fromWeb>[0], signal ? { signal } : {}) }
       } catch (err) { if (isNotFound(err, blobs)) return null; throw err }
     },
     async put(key, bytes, signal, expected, sizeHint) {

package/server-managed/public-workspace.ts

@@ -5,13 +5,13 @@ import type { ManagedHttpDeps } from './http.ts'
 import type { ManagedBundle } from './db.ts'
 import type { OpenedBlob } from './blob-store.ts'
 import type { WorkspaceShareSnapshot } from './workspace-shares.ts'
-import { sendJson } from './http-response.ts'
+import { sendJson, writeResponse } from './http-response.ts'
 import { hashToken } from './crypto.ts'
-import { TeamReportsError, loadTeamReports, teamReportVisibility } from './team-reports.ts'
+import { TeamReportsError, loadTeamAnnotations, loadTeamReportsResponse, teamReportVisibility } from './team-reports.ts'
 import { triageWireEntry } from './triage-response.ts'
 import { MAX_PACKAGE_INVENTORY_BYTES } from './bundle-cache.ts'
 import { backfillBundleSummaries, bundleSummaries } from './bundle-catalog.ts'
-import { NPM_ADVISORIES_TIMEOUT_MS, fetchNpmAdvisories } from '../server-common/npm-advisories.ts'
+import { ADVISORIES_TIMEOUT_MS, fetchBundleAdvisories } from './bundle-advisories.ts'
 import { serveTeamFeed } from './team-feed.ts'
 
 function json(res: ServerResponse, status: number, body: unknown): void {
@@ -28,7 +28,7 @@ export async function handlePublicWorkspace(req: IncomingMessage, res: ServerRes
   const method = req.method ?? 'GET'
   if (method !== 'GET' && method !== 'HEAD') { json(res, 403, { error: 'share-read-only' }); return }
   const shareRoute = /^\/api\/shares\/([A-Za-z0-9_-]+)\/workspace$/u.exec(url.pathname)
-  const teamRoute = /^\/api\/teams\/([^/]+)\/(shared|reports|feed)$/u.exec(url.pathname)
+  const teamRoute = /^\/api\/teams\/([^/]+)\/(shared|reports|feed|annotations)$/u.exec(url.pathname)
   const reportRoute = /^\/api\/reports\/([^/]+)\/(triage|comments|sources)$/u.exec(url.pathname)
   const bundleRoute = /^\/api\/bundles\/([^/]+)\/(metadata|contents|download|advisories)$/u.exec(url.pathname)
   if (!shareRoute && !teamRoute && !reportRoute && !bundleRoute) { json(res, 403, { error: 'share-scope-required' }); return }
@@ -72,10 +72,16 @@ export async function handlePublicWorkspace(req: IncomingMessage, res: ServerRes
     if (teamRoute[1] !== snapshot.teamId) { json(res, 404, { error: 'no-team' }); return }
     if (teamRoute[2] === 'feed') {
       if (method !== 'GET') { json(res, 405, { error: 'method-not-allowed' }); return }
-      await serveTeamFeed(res, deps, snapshot, recheck); return
+      await serveTeamFeed(res, deps, snapshot, recheck, { readState: () => deps.db.getWorkspaceShareFeedState(tokenHash) }); return
+    }
+    if (teamRoute[2] === 'annotations') {
+      await send(await loadTeamAnnotations(deps.db, deps.reportStore, snapshot, url.searchParams.get('reportId'))); return
     }
     if (teamRoute[2] === 'shared') { await sendTeam(); return }
-    await send({ reports: await loadTeamReports(deps.db, deps.reportStore, snapshot) }); return
+    const body = await loadTeamReportsResponse(deps.db, deps.reportStore, snapshot)
+    await recheck()
+    res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'private, no-store', 'referrer-policy': 'no-referrer' })
+    writeResponse(res, body); return
   }
   if (reportRoute) {
     const id = reportRoute[1]!, part = reportRoute[2]!
@@ -103,16 +109,16 @@ async function serveBundle(res: ServerResponse, deps: ManagedHttpDeps, bundle: M
   if (!deps.bundleCache) { json(res, 503, { error: 'unavailable' }); return }
   if (part === 'advisories') {
     if (bundle.kind !== 'stasis') { json(res, 422, { error: 'unsupported-bundle' }); return }
-    const packages = await deps.bundleCache.packageVersions(bundle, url.searchParams.get('reason') ?? '')
+    const inventory = await deps.bundleCache.advisoryInventory(bundle, url.searchParams.get('reason') ?? '')
     await recheck()
-    if (packages === null) { json(res, 413, { error: 'payload-too-large' }); return }
-    if (packages === undefined) { json(res, 400, { error: 'unknown-reason' }); return }
-    const body = Buffer.from(JSON.stringify(packages))
-    if (body.length > MAX_PACKAGE_INVENTORY_BYTES) { json(res, 413, { error: 'payload-too-large' }); return }
-    const result = Object.keys(packages).length === 0 ? { status: 200, body: {} }
-      : await fetchNpmAdvisories(body, AbortSignal.timeout(NPM_ADVISORIES_TIMEOUT_MS), deps.config.debug)
+    if (inventory === null) { json(res, 413, { error: 'payload-too-large' }); return }
+    if (inventory === undefined) { json(res, 400, { error: 'unknown-reason' }); return }
+    if (Buffer.byteLength(JSON.stringify(inventory)) > MAX_PACKAGE_INVENTORY_BYTES) { json(res, 413, { error: 'payload-too-large' }); return }
+    const result = await fetchBundleAdvisories(inventory.packages, AbortSignal.timeout(ADVISORIES_TIMEOUT_MS), {
+      debug: deps.config.debug, repoAdvisories: url.searchParams.get('repoAdvisories') === 'true',
+    })
     await recheck()
-    json(res, result.status, result.status === 200 ? { packages, advisories: result.body } : result.body); return
+    json(res, result.status, result.status === 200 ? { ...inventory, advisories: result.body } : result.body); return
   }
   let cached
   try { cached = await deps.bundleCache.open(bundle, part as 'metadata' | 'contents') }

package/server-managed/report-migration.ts

@@ -4,7 +4,7 @@
 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import type { DatabaseSync } from 'node:sqlite'
-import { reportRepoGithub } from '../report/index.js'
+import { reportRepoGithub } from '@preventive/report'
 import { readManagedReport } from '../common/managed/report-content.ts'
 import { normalizeTeamPath } from './repo-path.ts'
 

package/server-managed/report-sources.ts

@@ -5,9 +5,10 @@ import { promisify } from 'node:util'
 import { gzip } from 'node:zlib'
 import { bundleSourcesAsMap } from '../common/bundle-sources.js'
 import { bundleSourceImports } from '../common/bundle-source-links.js'
+import type { BundleDetails } from '../common/bundle-metadata.js'
 import { loadManagedFindings, managedFindingSourcePaths } from '../common/managed/report-content.ts'
 import { type ViewerPermissions, filterReportContent } from '../common/managed/report-filter.ts'
-import type { CacheStorage } from './cache-storage.ts'
+import { CacheMissError, type CacheStorage } from './cache-storage.ts'
 import { readBundleDetails } from './bundle-cache.ts'
 import type { BlobStore } from './blob-store.ts'
 import type { BundleStore } from './bundle-store.ts'
@@ -28,7 +29,7 @@ function formatDirectory(bundleId: string, sha256: string, name: string) {
 }
 function sourceCacheFilename(report: ReportRecord, bundle: ManagedBundle, permissions: ViewerPermissions, repo: { github: string | null }, sourcePaths?: Set<string>) {
   const key = createHash('sha256').update(JSON.stringify([
-    'finding-access-v5', sourcePaths ? [...sourcePaths].toSorted() : null, bundle.integrity, bundle.kind, permissions.dependencies, permissions.security, repo,
+    'finding-access-v6', sourcePaths ? [...sourcePaths].toSorted() : null, bundle.integrity, bundle.kind, permissions.dependencies, permissions.security, repo,
   ])).digest('hex')
   return `${formatDirectory(bundle.id, report.sha256, report.filename)}/${key}.json.gz`
 }
@@ -60,6 +61,14 @@ function selectSources(sourcePaths: Set<string>, sources: Map<string, string>) {
   return { files: [...files], paths: [...paths] }
 }
 
+function encodeSources(integrity: string, details: BundleDetails, selection: ReturnType<typeof selectSources>) {
+  const sources = new Map(selection.files)
+  const imports = [...bundleSourceImports(details, sources)].map(([parent, targets]) => [parent, [...targets]])
+  const bundle = details.kind === 'stasis' ? details.bundle as { formats: Map<string, string> } : null
+  const formats = [...(bundle?.formats ?? [])].filter(([file]) => sources.has(file))
+  return compress(Buffer.from(JSON.stringify({ integrity, ...selection, imports, formats })), { level: 6 })
+}
+
 // Immutable report hashes share a derivative across duplicate uploads. Bundle
 // identity and visibility are part of the key: a broader viewer's sources must
 // never populate a restricted response. Group derivatives by hash and filename
@@ -89,8 +98,7 @@ export function createReportSourcesCache(storage: CacheStorage, db: ManagedDb, r
     const details = await readBundleDetails(bundle, bundles)
     if (!details) return false
     const selection = selectSources(sourcePaths, bundleSourcesAsMap(details))
-    const imports = [...bundleSourceImports(details, new Map(selection.files))].map(([parent, targets]) => [parent, [...targets]])
-    const body = await compress(Buffer.from(JSON.stringify({ integrity: bundle.integrity, ...selection, imports })), { level: 6 })
+    const body = await encodeSources(bundle.integrity, details, selection)
     // A duplicate with the same hash AND format can use these parsed bytes.
     // Another format must not keep a deleted variant's late build alive.
     if (!(await referenced(report, bundle))) return false
@@ -128,6 +136,8 @@ export function createReportSourcesCache(storage: CacheStorage, db: ManagedDb, r
     async open(report: ReportRecord, bundle: ManagedBundle, permissions: ViewerPermissions, sourcePaths?: Set<string>) {
       const repo = { github: (await db.listAllRepos()).find(entry => entry.repoId === report.repoId)?.fullName ?? null }
       const target = sourceCacheFilename(report, bundle, permissions, repo, sourcePaths)
+      try { return { ...await storage.open(target), repo } }
+      catch (error) { if (!(error instanceof CacheMissError)) throw error }
       if (!(await ensure(target, report, bundle, permissions, repo, sourcePaths))) return null
       const opened = await storage.open(target)
       return { ...opened, repo }

package/server-managed/repository-browser.ts

@@ -97,6 +97,9 @@ async function repositoryReader(repo: SelectedRepo, userToken: string | null, in
   const defaultBranch = typeof current.default_branch === 'string' ? current.default_branch : ''
   return {
     recheckAccess: () => checkAccess(true),
+    // Server-only credential, selected by the same live visibility/permission
+    // gate as directory browsing. Never included in an HTTP response.
+    readToken: () => token,
     async refs() {
       // Suggestions are bounded; the input also accepts any branch or tag name.
       const results = await Promise.all(['branches', 'tags'].map(async kind => {

package/server-managed/repository-discovery.ts

@@ -65,7 +65,7 @@ export class RepositoryDiscovery {
       // Cache the two sources separately so failed installation discovery is
       // retried without caching a degraded combined list for another minute.
       const [userRepos, installedRepos] = await Promise.all([
-        this.read(key, () => listUserRepos(token, this.fetchImpl)),
+        this.read(key, () => listUserRepos(token)),
         installed().catch((err: unknown) => {
           console.warn('managed: installed repo deduplication failed:', err)
           return []

package/server-managed/revisions.ts

@@ -0,0 +1,35 @@
+// Internal invalidation counters. Never expose these global values to clients:
+// feeds still publish only the existing user/visibility-scoped revisions.
+const catalogTables = ['managed_team', 'managed_team_user', 'managed_team_repo', 'managed_report', 'managed_bundle', 'managed_selected_repo']
+const annotationTables = ['managed_finding_triage', 'managed_finding_triage_event', 'managed_finding_comment']
+export function revisionSchema(postgres = false): string {
+  let sql = `CREATE TABLE IF NOT EXISTS managed_maintenance_lease (
+    id INTEGER PRIMARY KEY, owner TEXT NOT NULL, expires_at INTEGER NOT NULL
+  ); CREATE TABLE IF NOT EXISTS managed_change_revision (
+    id INTEGER PRIMARY KEY, catalog INTEGER NOT NULL, annotations INTEGER NOT NULL
+  ); INSERT INTO managed_change_revision VALUES (1, 0, 0) ON CONFLICT(id) DO NOTHING;`
+  for (const [column, tables] of [['catalog', catalogTables], ['annotations', annotationTables]] as const) {
+    const update = `UPDATE managed_change_revision SET ${column} = ${column} + 1 WHERE id = 1;`
+    if (postgres) {
+      sql += `CREATE OR REPLACE FUNCTION managed_${column}_changed() RETURNS trigger LANGUAGE plpgsql AS $$
+        BEGIN IF EXISTS (SELECT 1 FROM managed_revision_rows) THEN ${update} END IF; RETURN NULL; END $$;`
+    }
+    for (const table of tables) {
+      if (postgres) {
+        sql += `DROP TRIGGER IF EXISTS ${table}_revision ON ${table};`
+        for (const event of ['INSERT', 'UPDATE', 'DELETE']) {
+          sql += `DROP TRIGGER IF EXISTS ${table}_revision_${event} ON ${table};
+            CREATE TRIGGER ${table}_revision_${event} AFTER ${event} ON ${table}
+            REFERENCING ${event === 'DELETE' ? 'OLD' : 'NEW'} TABLE AS managed_revision_rows
+            FOR EACH STATEMENT EXECUTE FUNCTION managed_${column}_changed();`
+        }
+      } else {
+        for (const event of ['INSERT', 'UPDATE', 'DELETE']) {
+          sql += `CREATE TRIGGER IF NOT EXISTS ${table}_revision_${event}
+            AFTER ${event} ON ${table} BEGIN ${update} END;`
+        }
+      }
+    }
+  }
+  return sql
+}

package/server-managed/sql-postgres.ts

@@ -4,6 +4,7 @@ export function postgresSql(source: string): { sql: string; names: string[] } {
   const names: string[] = []
   let position = 0
   let sql = source.replaceAll('json_each(:contexts)', 'jsonb_array_elements(:contexts::jsonb)')
+    .replaceAll("CAST(unixepoch('subsec') * 1000 AS INTEGER)", 'CAST(EXTRACT(EPOCH FROM clock_timestamp()) * 1000 AS BIGINT)')
     .replaceAll(/json_extract\((\w+\.value), '\$\.(\w+)'\)/gu, "($1->>'$2')")
     .replaceAll('json_each(?)', 'jsonb_array_elements_text(?::jsonb)')
     .replaceAll('INSERT OR IGNORE INTO', 'INSERT INTO')

package/server-managed/sql.ts

@@ -1,5 +1,5 @@
 // Each public store operation owns a transaction. SQLite serializes access to
-// its single connection across awaits; Neon binds one connection per operation.
+// its single connection across awaits; Neon can reuse a request-owned connection.
 import type { DatabaseSync, SQLInputValue } from 'node:sqlite'
 import type { ManagedDb } from './db-methods.ts'
 
@@ -13,14 +13,25 @@ export interface ManagedSql {
   close(): MaybePromise<void>
 }
 export interface ManagedSqlDriver extends ManagedSql {
-  scope<T>(write: boolean, work: () => Promise<T>): Promise<T>
+  scope<T>(write: boolean, work: () => Promise<T>, options?: { lock?: boolean; statement?: boolean }): Promise<T>
 }
 
+// These operations execute exactly one SQL statement. Postgres already gives
+// that statement an atomic snapshot; an explicit BEGIN/COMMIT adds only trips.
+// Lease writes coordinate through their conditional UPSERT/UPDATE alone.
+const SINGLE_STATEMENTS = new Set(['getReport', 'getBundle', 'getStorageRow', 'getStorageEncryption',
+  'listReports', 'listBundles', 'listReadableBundleIds', 'listAllRepos', 'listSelectedRepos', 'listRepoScopesForUser', 'listTriage',
+  'getFeedState', 'getWorkspaceShareFeedState', 'claimMaintenanceLease', 'finishMaintenanceLease', 'cacheRepoDefaultBranch', 'releaseBundleBuildLease'])
+
 export function scopeManagedMethods(methods: ManagedDb, driver: ManagedSqlDriver): ManagedDb {
   const entries = Object.entries(methods).map(([name, method]) => {
     if (name === 'close') return [name, async () => { await driver.close() }]
     const write = !/^(?:get|list|userCanRead|reportPermissionsFor)/u.test(name)
-    return [name, (...args: unknown[]) => driver.scope(write, () => method(...args))]
+    return [name, (...args: unknown[]) => driver.scope(write, () => method(...args), {
+      // Presence writes only one user's timestamp; they need no application
+      // writer lock. Keep the session/user read and timestamp in one transaction.
+      lock: write && name !== 'sessionWithUser', statement: SINGLE_STATEMENTS.has(name),
+    })]
   })
   return Object.fromEntries(entries) as ManagedDb
 }

package/server-managed/storage-db.ts

@@ -84,11 +84,18 @@ export function decodeStorageTokens(key: StorageKey, id: string, row: StoredToke
   return { access: decode('access', row.access), refresh: decode('refresh', row.refresh) }
 }
 
-const PENDING = `SELECT 'bundle:' || id AS position, id, 'bundle' AS type FROM managed_bundle WHERE storage_encrypted = 0
-  UNION ALL SELECT 'report:' || id AS position, id, 'report' AS type FROM managed_report WHERE storage_encrypted = 0
-  UNION ALL SELECT 'user:' || id AS position, id, 'user' AS type FROM managed_user
+// Fixed-width sizes make the saved position sort by type, then numeric byte
+// size, then ID in both SQLite and Postgres. Sixteen digits cover JS safe sizes.
+const PADDED_SIZE = "substr('0000000000000000', 1, 16 - length(CAST(byte_size AS TEXT))) || CAST(byte_size AS TEXT)"
+const PENDING = `SELECT '0:' || ${PADDED_SIZE} || ':' || id AS position, id, 'report' AS type FROM managed_report WHERE storage_encrypted = 0
+  UNION ALL SELECT '1:' || ${PADDED_SIZE} || ':' || id AS position, id, 'bundle' AS type FROM managed_bundle WHERE storage_encrypted = 0
+  UNION ALL SELECT '2:0000000000000000:' || id AS position, id, 'user' AS type FROM managed_user
     WHERE gh_tokens_encrypted = 0 AND (gh_access_token IS NOT NULL OR gh_refresh_token IS NOT NULL)`
 
+// Restart the pending pass for a cursor saved under the previous ID ordering.
+// Completed rows are excluded by PENDING; the original cursor still fences CAS.
+const orderedCursor = (cursor: string | null): string => cursor && /^[012]:[0-9]{16}:/u.test(cursor) ? cursor : ''
+
 export function storageMethods(db: ManagedSql, key: StorageKey | null): StorageDb {
   async function requireEnabled() {
     const state = await storageState(db, key)
@@ -135,11 +142,11 @@ export function storageMethods(db: ManagedSql, key: StorageKey | null): StorageD
     async listStorageMigrationRows(after, limit) {
       await requireEnabled()
       return await db.prepare(`SELECT position, id, type FROM (${PENDING}) AS pending
-        WHERE position > ? ORDER BY position LIMIT ?`).all(after ?? '', limit) as StorageMigrationRow[]
+        WHERE position > ? ORDER BY position LIMIT ?`).all(orderedCursor(after), limit) as StorageMigrationRow[]
     },
     async advanceStorageMigration(expected, next) {
       await requireEnabled()
-      if (expected !== null && next !== null && next <= expected) return
+      if (next !== null && next <= orderedCursor(expected)) return
       // End-of-pass completion checks every pending row, including failed rows
       // before the cursor. A failure cannot be mistaken for a finished pass.
       await db.prepare(`UPDATE managed_storage_encryption SET cursor = ?, complete =

package/server-managed/storage-maintenance.ts

@@ -2,9 +2,9 @@ import { type StorageKey, decryptStorageStream, encryptStorageStream } from '../
 import { ENCRYPTED_CACHE_PREFIX, type RawObjectStorage, deleteObjects, isBlobId, openObjectVersion } from './object-storage.ts'
 import { type StorageDb, type StorageEncryptionState, type StorageMigrationRow, unwrapDataKey } from './storage-db.ts'
 import { STORAGE_UPLOAD_TTL_MS } from './storage-encryption.ts'
-import { inspectStorageObject, storageOwner, storageRowPath, verifyStoragePayload } from './storage-payload.ts'
+import { StoragePayloadError, inspectStorageObject, storageOwner, storageRowPath, verifyStoragePayload } from './storage-payload.ts'
 
-async function migrateRow(raw: RawObjectStorage, db: StorageDb, key: StorageKey, item: StorageMigrationRow, signal: AbortSignal) {
+async function migrateRow(raw: RawObjectStorage, db: StorageDb, key: StorageKey, item: StorageMigrationRow, signal: AbortSignal): Promise<string | void> {
   if (item.type === 'user') { await db.migrateStorageUserTokens(item.id); return }
   const row = await db.ensureStorageDataKey(item.type, item.id)
   if (!row || row.encrypted) return
@@ -13,7 +13,7 @@ async function migrateRow(raw: RawObjectStorage, db: StorageDb, key: StorageKey,
     const source = await raw.open(identity, signal)
     if (!source) {
       if (!await db.getStorageRow(item.type, item.id)) return
-      throw new Error('Migration payload unavailable')
+      throw new StoragePayloadError('Migration payload unavailable')
     }
     let inspected = await inspectStorageObject(source)
     if (inspected.encrypted) {
@@ -26,7 +26,7 @@ async function migrateRow(raw: RawObjectStorage, db: StorageDb, key: StorageKey,
         // Legacy arbitrary bytes can share the magic prefix. A matching
         // original upload hash is required before encrypting them as plaintext.
         const legacy = await openObjectVersion(raw, identity, source.version, signal)
-        if (!legacy) return
+        if (!legacy) return 'Payload disappeared or changed version before plaintext verification'
         inspected = { ...legacy, encrypted: false }
       }
     }
@@ -34,18 +34,18 @@ async function migrateRow(raw: RawObjectStorage, db: StorageDb, key: StorageKey,
       await verifyStoragePayload(item.type, row, inspected.stream, signal)
       signal.throwIfAborted()
       const current = await openObjectVersion(raw, identity, source.version, signal)
-      if (!current) return
+      if (!current) return 'Payload disappeared or changed version before encryption'
       const encrypted = encryptStorageStream(current.stream, dataKey, identity, current.size)
       let replaced: boolean
       try { replaced = await raw.put(identity, encrypted, signal, source.version, current.size ?? undefined) }
       finally { encrypted.destroy(); current.stream.destroy() }
-      if (!replaced) return
+      if (!replaced) return 'Conditional replacement rejected (object version precondition failed)'
       // Do not mark the row encrypted until the stored bytes authenticate and
       // match the original upload (including decompression for sourcemaps).
       const replacement = await raw.open(identity, signal)
       if (!replacement) {
         if (!await db.getStorageRow(item.type, item.id)) return
-        throw new Error('Migrated payload unavailable')
+        throw new StoragePayloadError('Migrated payload unavailable')
       }
       const decoded = await decryptStorageStream(replacement.stream, dataKey, identity)
       await verifyStoragePayload(item.type, row, decoded.stream, signal)
@@ -130,38 +130,60 @@ async function cleanupLegacy(raw: RawObjectStorage, db: StorageDb, state: Storag
   return { processed: page.objects.length || 1, retryAt }
 }
 
-interface StorageMigrationResult extends StorageEncryptionState { retryAt: number | null }
+interface StorageMigrationResult extends StorageEncryptionState {
+  retryAt: number | null
+  failures: { type: StorageMigrationRow['type']; id: string; message: string }[]
+}
+function rowFailure(row: StorageMigrationRow, message: string) {
+  const failure = { type: row.type, id: row.id, message }
+  // Emit before continuing: a later failure or terminated invocation must not
+  // hide earlier diagnostics. Never include provider errors or storage values.
+  console.warn('managed-storage-migration-row:', JSON.stringify(failure))
+  return failure
+}
+interface MigrationOptions { maxObjects?: number; maxMs?: number | undefined; signal?: AbortSignal | undefined }
 export async function migrateStorage(raw: RawObjectStorage, db: StorageDb, key: StorageKey,
-  { maxObjects = 64, maxMs = 150_000 } = {}): Promise<StorageMigrationResult> {
+  { maxObjects = 64, maxMs = 150_000, signal: stopping }: MigrationOptions = {}): Promise<StorageMigrationResult> {
   if (!Number.isSafeInteger(maxObjects) || maxObjects < 1 || !Number.isSafeInteger(maxMs) || maxMs < 1) throw new Error('Invalid migration budget')
-  const deadline = Date.now() + maxMs, signal = AbortSignal.timeout(maxMs)
+  const deadline = Date.now() + maxMs, timeout = AbortSignal.timeout(maxMs)
+  const signal = stopping ? AbortSignal.any([stopping, timeout]) : timeout
   const errors: unknown[] = []
+  const failures: StorageMigrationResult['failures'] = []
   let processed = 0, retryAt: number | null = null, state = await db.getStorageEncryption()
   if (!state) throw new Error('Storage encryption is not enabled; configure MANAGED_STORAGE_ENCRYPTION_KEY')
   // At most one SQL pass per invocation. Checkpoint each row, including a
   // failure: other rows progress, and the failed row is retried next pass.
-  while (!state.complete && processed < maxObjects && Date.now() < deadline) {
+  while (!state.complete && processed < maxObjects && Date.now() < deadline && !signal.aborted) {
     const rows = await db.listStorageMigrationRows(state.cursor, Math.min(16, maxObjects - processed))
+    if (stopping?.aborted) break
     if (rows.length === 0) { await db.advanceStorageMigration(state.cursor, null); break }
     for (const row of rows) {
-      if (Date.now() >= deadline) break
-      try { await migrateRow(raw, db, key, row, signal) }
+      if (Date.now() >= deadline || signal.aborted) break
+      console.info('managed-storage-migration-row-start:', JSON.stringify({ type: row.type, id: row.id }))
+      try {
+        const pending = await migrateRow(raw, db, key, row, signal)
+        if (pending) failures.push(rowFailure(row, pending))
+      }
       catch (err) {
         // A row started late gets a full budget next time. Skip an oversized
         // first row until the next pass so later rows and tokens can advance.
-        if (signal.aborted && processed > 0) break
-        const message = signal.aborted
+        if (stopping?.aborted || (signal.aborted && processed > 0)) break
+        const failure = signal.aborted
           ? `Could not migrate ${row.type} ${row.id} within MANAGED_STORAGE_ENCRYPTION_MIGRATE_MAX_MS=${maxMs}; increase the budget`
-          : `Could not migrate ${row.type} ${row.id}`
-        errors.push(new Error(message, { cause: err }))
+          : err instanceof StoragePayloadError ? err.message : null
+        if (failure === null) {
+          rowFailure(row, 'Migration operation failed')
+          errors.push(new Error(`Could not migrate ${row.type} ${row.id}`, { cause: err }))
+        } else failures.push(rowFailure(row, failure))
       }
+      if (stopping?.aborted) break
       await db.advanceStorageMigration(state.cursor, row.position)
       processed++
       state = (await db.getStorageEncryption())!
     }
   }
   state = (await db.getStorageEncryption())!
-  while (!state.cleanupComplete && processed < maxObjects && Date.now() < deadline) {
+  while (!state.cleanupComplete && processed < maxObjects && Date.now() < deadline && !signal.aborted) {
     try {
       const cleanup = await cleanupLegacy(raw, db, state, maxObjects - processed, signal)
       processed += cleanup.processed
@@ -172,11 +194,14 @@ export async function migrateStorage(raw: RawObjectStorage, db: StorageDb, key:
     if (retryAt !== null) break // Wait for staging grace rather than spinning over live temp files.
   }
   if (errors.length > 0) throw new AggregateError(errors, 'Storage migration has pending failures', { cause: errors[0] })
-  return { ...state, retryAt }
+  return { ...state, retryAt, failures }
 }
 
-export async function reapStorageUploads(raw: RawObjectStorage, db: StorageDb, now = Date.now()): Promise<number> {
-  const signal = AbortSignal.timeout(150_000)
+export async function reapStorageUploads(raw: RawObjectStorage, db: StorageDb, now = Date.now(), stopping?: AbortSignal): Promise<number> {
+  if (stopping?.aborted) return 0
+  const timeout = AbortSignal.timeout(150_000)
+  const signal = stopping ? AbortSignal.any([stopping, timeout]) : timeout
   await db.getStorageEncryption()
-  return deleteObjects(raw, 'uploads/', signal, now - STORAGE_UPLOAD_TTL_MS)
+  try { return await deleteObjects(raw, 'uploads/', signal, now - STORAGE_UPLOAD_TTL_MS) }
+  catch (err) { if (stopping?.aborted) return 0; throw err }
 }

package/server-managed/storage-payload.ts

@@ -7,6 +7,10 @@ import { STORAGE_MAGIC } from '../server-common/storage-crypto.ts'
 import { type RawObject, isBlobId } from './object-storage.ts'
 import type { StorageRow, StorageRowKind } from './storage-db.ts'
 
+// A damaged/missing payload needs repair; retrying the whole cleanup job does
+// not fix it. Keep this distinct from database, storage and cancellation errors.
+export class StoragePayloadError extends Error {}
+
 export function storageRowPath(type: StorageRowKind, row: Pick<StorageRow, 'id' | 'kind'>): string {
   return `${type === 'report' ? 'reports' : 'bundles'}/${row.id}${type === 'bundle' && row.kind === 'sourcemap' ? '.map.br' : ''}`
 }
@@ -52,9 +56,17 @@ export async function verifyStoragePayload(type: StorageRowKind, row: StorageRow
   const hash = createHash(type === 'report' ? 'sha256' : 'sha512')
   const sink = new Writable({ write(chunk, _encoding, next) { hash.update(chunk); next() } })
   const options = signal ? { signal } : {}
-  if (type === 'bundle' && row.kind === 'sourcemap') {
-    await pipeline(source, createBrotliDecompress(), sink, options)
-  } else await pipeline(source, sink, options)
+  try {
+    if (type === 'bundle' && row.kind === 'sourcemap') {
+      await pipeline(source, createBrotliDecompress(), sink, options)
+    } else await pipeline(source, sink, options)
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code ?? ''
+    if (['Z_DATA_ERROR', 'Z_BUF_ERROR'].includes(code) || code.startsWith('ERR__ERROR_FORMAT_')) {
+      throw new StoragePayloadError('Stored sourcemap cannot be decompressed', { cause: err })
+    }
+    throw err
+  }
   const actual = type === 'report' ? hash.digest('base64url') : `sha512-${hash.digest('base64')}`
-  if (actual !== row.hash) throw new Error('Stored payload does not match its upload hash')
+  if (actual !== row.hash) throw new StoragePayloadError('Stored payload does not match its upload hash')
 }

package/server-managed/storage-stores.ts

@@ -5,7 +5,7 @@ import type { AvatarStore } from './avatar-store.ts'
 import type { BlobStore } from './blob-store.ts'
 import type { BundleCacheStorage } from './bundle-cache.ts'
 import { createBundleStore } from './bundle-store.ts'
-import { type CacheStorage, validateCacheKey } from './cache-storage.ts'
+import { CacheMissError, type CacheStorage, validateCacheKey } from './cache-storage.ts'
 import { type ObjectStorage, isBlobId } from './object-storage.ts'
 
 function id(value: string): string {
@@ -30,7 +30,7 @@ function cacheStore(objects: ObjectStorage, name: string): CacheStorage {
     put: async (key, bytes) => { await objects.put(path(key), bytes) },
     async open(key) {
       const value = await objects.open(path(key))
-      if (!value) throw new Error('Managed cache unavailable')
+      if (!value) throw new CacheMissError()
       return value
     },
     delete: prefix => objects.deletePrefix(`${path(prefix)}/`),