@preventive/triage 1.0.0-alpha.5 → 1.0.0-alpha.50

package/server-managed/lru.ts

@@ -0,0 +1,30 @@
+// Values by key, the least recently used going first once their weights
+// (`weight`, 1 each unless given) are past `limit`.
+export interface Lru<V> { get(key: string): V | undefined; set(key: string, value: V): void }
+export function lru<V>(limit: number, weight: (value: V) => number = () => 1): Lru<V> {
+  const kept = new Map<string, V>()
+  let total = 0
+  const forget = (key: string) => {
+    const value = kept.get(key)
+    if (value === undefined) return
+    kept.delete(key)
+    total -= weight(value)
+  }
+  return {
+    get(key) {
+      const value = kept.get(key)
+      if (value !== undefined) { kept.delete(key); kept.set(key, value) }
+      return value
+    },
+    set(key, value) {
+      forget(key)
+      if (weight(value) > limit) return
+      kept.set(key, value)
+      total += weight(value)
+      for (const first of kept.keys()) {
+        if (total <= limit) break
+        forget(first)
+      }
+    },
+  }
+}

package/server-managed/managed-issues.ts

@@ -0,0 +1,78 @@
+import type { ManagedSql } from './sql.ts'
+import type { TeamReportAccessSnapshot } from './db.ts'
+import { parseGithubPrUrl } from '../common/github-pr.ts'
+
+// One immutable reference per finding, shared across reports and teams. Keep
+// reservations across crashes/uncertain GitHub responses to prevent duplicates.
+// No triage/import/admin patch accepts these fields.
+export const MANAGED_ISSUE_SCHEMA = `
+CREATE TABLE IF NOT EXISTS managed_finding_issue (
+  finding_id TEXT PRIMARY KEY,
+  repo_id INTEGER NOT NULL,
+  repository TEXT NOT NULL,
+  request_id TEXT NOT NULL,
+  issue_url TEXT,
+  auto_fix_url TEXT,
+  auto_fix_checked_at INTEGER,
+  created_by TEXT REFERENCES managed_user(id) ON DELETE SET NULL,
+  created_at INTEGER NOT NULL
+) STRICT;
+`
+export interface ManagedIssue {
+  findingId: string
+  repoId: number
+  repository: string
+  requestId: string
+  issueUrl: string | null
+  autoFixUrl: string | null
+  autoFixCheckedAt: number | null
+  createdBy: string | null
+  createdAt: number
+}
+export interface ManagedIssueStore {
+  getManagedIssue(findingId: string): Promise<ManagedIssue | null>
+  listManagedIssues(findingIds: readonly string[]): Promise<ManagedIssue[]>
+  claimManagedIssue(issue: Omit<ManagedIssue, 'issueUrl' | 'autoFixUrl' | 'autoFixCheckedAt'>): Promise<boolean>
+  finishManagedIssue(findingId: string, requestId: string, url: string): Promise<boolean>
+  releaseManagedIssue(findingId: string, requestId: string): Promise<void>
+  setManagedIssueAutoFix(findingId: string, issueUrl: string, previous: string | null, next: string | null, checkedAt: number): Promise<boolean>
+}
+
+// A repeated finding ID never grants access to another team's repository.
+export function visibleManagedIssues(issues: ManagedIssue[], snapshot: TeamReportAccessSnapshot) {
+  if (snapshot.user.id.startsWith('share:')) return []
+  const repos = new Set(snapshot.repositories.map(repo => repo.repoId))
+  const names = new Set(snapshot.repositories.map(repo => repo.github.toLowerCase()))
+  return issues.filter(issue => issue.issueUrl && repos.has(issue.repoId)).map(issue => {
+    const ref = parseGithubPrUrl(issue.autoFixUrl)
+    return { ...issue, autoFixUrl: ref && names.has(ref.repo.toLowerCase()) ? issue.autoFixUrl : null }
+  })
+}
+export function managedIssueMethods(db: ManagedSql): ManagedIssueStore {
+  const fields = `finding_id AS findingId, repo_id AS repoId, repository, request_id AS requestId,
+    issue_url AS issueUrl, auto_fix_url AS autoFixUrl, auto_fix_checked_at AS autoFixCheckedAt, created_by AS createdBy, created_at AS createdAt`
+  const get = db.prepare(`SELECT ${fields} FROM managed_finding_issue WHERE finding_id = ?`)
+  const list = db.prepare(`SELECT ${fields} FROM managed_finding_issue WHERE finding_id IN (SELECT value FROM json_each(?)) ORDER BY finding_id`)
+  // A lookup's derived Fix replaces the one it read, unless one started later
+  // changed it since: the check time, which only changes stamp
+  // (github-issue-links.ts issueUpdates), orders them.
+  const autoFix = db.prepare(`UPDATE managed_finding_issue SET auto_fix_url = ?, auto_fix_checked_at = ?
+    WHERE finding_id = ? AND issue_url = ? AND COALESCE(auto_fix_url, '') = COALESCE(?, '')
+      AND (auto_fix_checked_at IS NULL OR auto_fix_checked_at <= ?)`)
+  const claim = db.prepare(`INSERT INTO managed_finding_issue (finding_id, repo_id, repository, request_id, created_by, created_at)
+    VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT (finding_id) DO NOTHING`)
+  const finish = db.prepare(`UPDATE managed_finding_issue SET issue_url = ? WHERE finding_id = ? AND request_id = ? AND issue_url IS NULL`)
+  const release = db.prepare(`DELETE FROM managed_finding_issue WHERE finding_id = ? AND request_id = ? AND issue_url IS NULL`)
+  return {
+    async getManagedIssue(findingId) { return (await get.get(findingId) as ManagedIssue | undefined) ?? null },
+    async listManagedIssues(ids) { return await list.all(JSON.stringify(ids)) as ManagedIssue[] },
+    async setManagedIssueAutoFix(findingId, issueUrl, previous, next, checkedAt) {
+      return Number((await autoFix.run(next, checkedAt, findingId, issueUrl, previous, checkedAt)).changes) > 0
+    },
+    async claimManagedIssue(issue) {
+      return Number((await claim.run(issue.findingId, issue.repoId, issue.repository, issue.requestId, issue.createdBy, issue.createdAt)).changes) > 0
+    },
+    async finishManagedIssue(findingId, requestId, url) { return Number((await finish.run(url, findingId, requestId)).changes) > 0 },
+    async releaseManagedIssue(findingId, requestId) { await release.run(findingId, requestId) },
+  }
+}

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/management.ts

@@ -0,0 +1,99 @@
+import type { AdminReport, BundleReuse, ManagedBundle, ManagedDb, ManagedRepo, RepoDataItem, RepoReportItem, ReportRecord, StoredUser } from './db-methods.ts'
+import { roleAtLeast } from '../common/managed/roles.ts'
+
+export class ManagedMutationError extends Error {
+  status: number
+  constructor(status: number, message: string) { super(message); this.status = status }
+}
+
+export type ContentMutation = { type: 'delete' } | { type: 'repo'; repoId: number | null; directory: string } | { type: 'visibility'; visible: boolean }
+export type ReportMutation = ContentMutation
+type RemovalRepo = Pick<ManagedRepo, 'repoId' | 'fullName' | 'addedAt'>
+type RemovalAnnotations = { reports: string; ids: string[] }
+export interface ManagementStore {
+  mutateReport(sessionId: string, id: string, change: ReportMutation): Promise<{ report: ReportRecord; user: StoredUser }>
+  mutateBundle(sessionId: string, id: string, change: ContentMutation): Promise<{ bundle: ManagedBundle; user: StoredUser }>
+  // A repeated upload/build of stored bytes (see reuseBundle). Renames need the
+  // access other bundle mutations need; a server build labels the row anyway.
+  reuseBundleUpload(sessionId: string, id: string, reuse: Omit<BundleReuse, 'rename'>): Promise<boolean>
+  removeRepository(sessionId: string, expected: RemovalRepo, annotations: RemovalAnnotations | null): Promise<{
+    reports: RepoReportItem[]; bundles: RepoDataItem[]; deletedReports: number; deletedBundles: number; deletedTriage: number
+  }>
+}
+type ManagementDb = Pick<ManagedDb, 'sessionWithUser' | 'getReport' | 'getBundle' | 'listReports' | 'listReportsForRepo'
+  | 'listBundlesForRepo' | 'listAllRepos' | 'listSelectedRepos' | 'userCanReadReport' | 'userCanReadBundle' | 'userCanReadRepoPath'
+  | 'deleteReport' | 'setReportRepo' | 'setReportVisible' | 'deleteBundle' | 'setBundleRepo' | 'setBundleVisible' | 'reuseBundle'
+  | 'deleteReportsForRepo' | 'deleteBundlesForRepo' | 'deleteRepo' | 'deleteTriage' | 'recordActivity'>
+
+// Only immutable bytes/format and repository membership affect the overlap
+// scan. Ignore publication, user display names, and unrelated bundle links.
+export function reportReferenceSnapshot(reports: readonly Pick<AdminReport, 'id' | 'sha256' | 'filename' | 'repoId'>[]): string {
+  return JSON.stringify(reports.map(r => [r.id, r.sha256, r.filename, r.repoId]).toSorted((a, b) => String(a[0]).localeCompare(String(b[0]))))
+}
+
+// These methods are wrapped by scopeManagedMethods: authorization, comparison,
+// metadata changes (and repository-removal audit) share the writer transaction. Blob reads
+// and deletes stay outside it. Use the raw store here, never nested scopes.
+export function managementMethods(db: ManagementDb): ManagementStore {
+  async function authorize(sessionId: string, role: 'admin' | 'manage') {
+    const s = await db.sessionWithUser(sessionId, Date.now())
+    if (!s) throw new ManagedMutationError(401, 'unauthenticated')
+    if (!roleAtLeast(s.user.role, role)) throw new ManagedMutationError(403, 'forbidden')
+    return s.user
+  }
+  async function destination(user: { id: string; role: string }, change: ContentMutation) {
+    if (change.type !== 'repo' || change.repoId === null) return
+    if (!(await db.listSelectedRepos()).some(repo => repo.repoId === change.repoId)) throw new ManagedMutationError(400, 'bad-repo')
+    if (user.role !== 'admin' && !await db.userCanReadRepoPath(user.id, change.repoId, change.directory)) throw new ManagedMutationError(403, 'repo-forbidden')
+  }
+  return {
+    async mutateReport(sessionId: string, id: string, change: ReportMutation) {
+      const user = await authorize(sessionId, 'manage')
+      const report = await db.getReport(id)
+      if (!report || (user.role !== 'admin' && report.uploadedBy !== user.id && !await db.userCanReadReport(user.id, id))) throw new ManagedMutationError(404, 'no-report')
+      if (user.role !== 'admin' && report.repoId !== null && !await db.userCanReadReport(user.id, id)) throw new ManagedMutationError(403, 'repo-forbidden')
+      if (change.type === 'repo' && report.repoEmbedded) throw new ManagedMutationError(409, 'repo-in-report')
+      if (change.type !== 'visibility') await destination(user, change)
+      if (change.type === 'delete') await db.deleteReport(id)
+      else if (change.type === 'visibility') await db.setReportVisible(id, change.visible)
+      else await db.setReportRepo(id, change.repoId, change.directory)
+      return { report, user }
+    },
+    async mutateBundle(sessionId: string, id: string, change: ContentMutation) {
+      const user = await authorize(sessionId, 'manage')
+      const bundle = await db.getBundle(id)
+      if (!bundle || (user.role !== 'admin' && !await db.userCanReadBundle(user.id, id))) throw new ManagedMutationError(404, 'no-bundle')
+      if (user.role !== 'admin' && bundle.repoId !== null && !await db.userCanReadRepoPath(user.id, bundle.repoId, bundle.repoDirectory)) throw new ManagedMutationError(403, 'repo-forbidden')
+      await destination(user, change)
+      if (change.type === 'delete') await db.deleteBundle(id)
+      else if (change.type === 'visibility') await db.setBundleVisible(id, change.visible)
+      else await db.setBundleRepo(id, change.repoId, change.directory)
+      return { bundle, user }
+    },
+    async reuseBundleUpload(sessionId: string, id: string, reuse: Omit<BundleReuse, 'rename'>) {
+      const user = await authorize(sessionId, 'manage')
+      const bundle = await db.getBundle(id)
+      if (!bundle) return false
+      const rename = user.role === 'admin' || (await db.userCanReadBundle(user.id, id)
+        && (bundle.repoId === null || await db.userCanReadRepoPath(user.id, bundle.repoId, bundle.repoDirectory)))
+      if (!rename && reuse.provenance !== 'build') return false
+      return db.reuseBundle(id, { ...reuse, rename })
+    },
+    async removeRepository(sessionId: string, expected: RemovalRepo, annotations: RemovalAnnotations | null) {
+      const user = await authorize(sessionId, 'admin')
+      const repo = (await db.listAllRepos()).find(r => r.repoId === expected.repoId)
+      if (!repo) throw new ManagedMutationError(404, 'no-repo')
+      if (repo.fullName !== expected.fullName || repo.addedAt !== expected.addedAt) throw new ManagedMutationError(409, 'repository-changed')
+      if (annotations && reportReferenceSnapshot(await db.listReports()) !== annotations.reports) throw new ManagedMutationError(409, 'repository-changed')
+      const reports = await db.listReportsForRepo(repo.repoId)
+      const bundles = await db.listBundlesForRepo(repo.repoId)
+      const deletedReports = await db.deleteReportsForRepo(repo.repoId)
+      const deletedBundles = await db.deleteBundlesForRepo(repo.repoId)
+      const deletedTriage = await db.deleteTriage(annotations?.ids ?? [])
+      await db.deleteRepo(repo.repoId)
+      await db.recordActivity({ kind: 'delete', actor: user.login, actorId: user.id, repo: repo.fullName,
+        action: `removed a repository (${deletedReports} reports, ${deletedBundles} bundles, ${deletedTriage} triage entries)` }, Date.now())
+      return { reports, bundles, deletedReports, deletedBundles, deletedTriage }
+    },
+  }
+}

package/server-managed/npm-delta-worker.js

@@ -0,0 +1,23 @@
+// The lines a package's files change from one side to another (npm-delta.ts),
+// as @preventive/compare's compareTrees counts them (git's --numstat), off
+// the server's event loop: of its text files, renames found as git finds
+// them, a side not there empty; and, apart, those of its changes it stamps
+// `typeOnly`, declaration files changed in types alone.
+import { parentPort, workerData } from 'node:worker_threads'
+import { compareTrees } from '@preventive/compare'
+
+const tree = files => files.map(([name, data]) => ({ name, data }))
+const changes = compareTrees(tree(workerData.base), tree(workerData.other), { paths: 'keys', lines: true, renames: true })
+const answer = { additions: 0, deletions: 0, typeAdditions: 0, typeDeletions: 0, typeFiles: 0 }
+for (const change of changes) {
+  if (change.binary) continue
+  answer.additions += change.insertions ?? 0
+  answer.deletions += change.deletions ?? 0
+  if (change.typeOnly !== true) continue
+  answer.typeAdditions += change.insertions ?? 0
+  answer.typeDeletions += change.deletions ?? 0
+  answer.typeFiles++
+}
+// Node worker messages have no browser target origin.
+// oxlint-disable-next-line unicorn/require-post-message-target-origin
+parentPort.postMessage(answer)

package/server-managed/npm-delta.ts

@@ -0,0 +1,194 @@
+// The lines a version of a package changes against another, or against none,
+// its whole package's (GET /api/npm/delta), as a list of versions wanting
+// reviews tells them beside each: added and removed (`additions`,
+// `deletions`), as git's --numstat counts them, of their text files, a
+// renamed one diffed with what it was; and, where some of the files changed
+// are declaration files @preventive/compare's compareTrees proves changed in
+// types alone (`typeOnly`, proveTypeOnly: types and comments alone erased,
+// the runtime they leave as it was, an added one's empty or a single bare
+// `export {}`), those of the rest (`typeless`), what a reviewer may pass by
+// leaving those out; and whether a binary file, which they count none of,
+// was added, removed or changed (`binary`), one moved as it was not. Worked
+// out in a worker, off the event loop, as many at once per process as
+// MAX_ACTIVE, both sides' files read together only once their turn has come,
+// those waiting past MAX_WAITING refused, each waiting a minute at most and
+// counting in a minute at most; one asked again meanwhile sharing the
+// first's; and kept by both sides' integrities, in this instance and beyond
+// it (`kept`), what a version holds never changing. Access is the caller's
+// to check.
+import { Worker } from 'node:worker_threads'
+import { createHash } from 'node:crypto'
+import type { KeptStore } from './npm-kept.ts'
+import { type Lru, lru } from './lru.ts'
+import { NpmPackageError, type NpmPackageFile, npmFileText } from './npm-packages.ts'
+
+export interface NpmDelta { additions: number; deletions: number; typeless: { additions: number; deletions: number } | null; binary: boolean }
+
+const MAX_ACTIVE = 2
+const MAX_WAITING = 64
+const DELTA_TIMEOUT_MS = 60_000
+// The text the two sides may hold together, past which none is counted.
+const MAX_TEXT_LENGTH = 64 * 1024 * 1024
+
+const deltas: Lru<NpmDelta> = lru(20_000)
+const working = new Map<string, Promise<NpmDelta>>()
+let active = 0
+const waiting: Array<() => void> = []
+
+async function turn(deadline: number): Promise<void> {
+  if (active < MAX_ACTIVE) { active++; return }
+  if (waiting.length >= MAX_WAITING) throw new NpmPackageError(429, 'delta-busy')
+  await new Promise<void>((resolve, reject) => {
+    const next = () => { clearTimeout(timer); resolve() }
+    const timer = setTimeout(() => {
+      waiting.splice(waiting.indexOf(next), 1)
+      reject(new NpmPackageError(504, 'delta-timeout'))
+    }, deadline - Date.now())
+    waiting.push(next)
+  })
+}
+function done() {
+  const next = waiting.shift()
+  if (next) next()
+  else active--
+}
+
+const lines = (told: unknown): told is { additions: number; deletions: number } => typeof told === 'object' && told !== null
+  && Number.isSafeInteger((told as { additions?: unknown }).additions) && Number.isSafeInteger((told as { deletions?: unknown }).deletions)
+// A delta as kept, none where it isn't one, or was kept before it told of
+// binary files.
+const deltaOf = (told: unknown): NpmDelta | null => lines(told) && ((told as NpmDelta).typeless === null || lines((told as NpmDelta).typeless))
+  && typeof (told as NpmDelta).binary === 'boolean' ? { additions: told.additions, deletions: told.deletions, typeless: (told as NpmDelta).typeless,
+    binary: (told as NpmDelta).binary } : null
+
+type Counted = { additions: number; deletions: number; typeAdditions: number; typeDeletions: number; typeFiles: number }
+const isCounted = (told: unknown): told is Counted => typeof told === 'object' && told !== null
+  && ['additions', 'deletions', 'typeAdditions', 'typeDeletions', 'typeFiles'].every(key => Number.isSafeInteger((told as Record<string, unknown>)[key]))
+
+// What the worker counts of `base` against `other`, each its text files' paths and texts.
+function counted(base: [string, string][], other: [string, string][], deadline: number): Promise<Counted> {
+  let worker: Worker
+  try {
+    worker = new Worker(new URL('./npm-delta-worker.js', import.meta.url), {
+      workerData: { base, other }, execArgv: ['--disable-warning=ExperimentalWarning'], resourceLimits: { maxOldGenerationSizeMb: 1536 },
+    })
+  } catch (err) {
+    console.warn('managed: a package delta could not start:', err)
+    throw new NpmPackageError(503, 'unavailable')
+  }
+  return new Promise((resolve, reject) => {
+    let answer: Counted | null = null, failure = new NpmPackageError(422, 'delta-failed')
+    const timer = setTimeout(() => { failure = new NpmPackageError(504, 'delta-timeout'); void worker.terminate() }, deadline - Date.now())
+    worker.once('message', (told: unknown) => {
+      if (isCounted(told)) answer = told
+      void worker.terminate()
+    })
+    worker.once('error', err => { console.warn('managed: a package delta failed:', err) })
+    worker.once('exit', () => {
+      clearTimeout(timer)
+      if (answer) resolve(answer)
+      else reject(failure)
+    })
+  })
+}
+
+// A side's text files, by path, how long their texts are, and its other,
+// binary, files.
+function texts(files: NpmPackageFile[] | null) {
+  let length = 0
+  const binaries: NpmPackageFile[] = []
+  const read = (files ?? []).flatMap(file => {
+    const text = npmFileText(file.bytes)
+    if (text === null) { binaries.push(file); return [] }
+    length += text.length
+    return [[file.path, text] as [string, string]]
+  })
+  return { read, length, binaries }
+}
+
+const same = (a: Uint8Array, b: Uint8Array) => Buffer.from(a.buffer, a.byteOffset, a.byteLength).equals(b)
+const digest = (bytes: Uint8Array) => createHash('sha256').update(bytes).digest('base64')
+
+// Whether `news`, a side's binary files, differ from `olds`, the other's:
+// one added, removed or changed, one moved where it is the same as one that
+// was elsewhere not, matched by their digests, each file looked at once.
+function binaryChanged(olds: NpmPackageFile[], news: NpmPackageFile[]): boolean {
+  if (olds.length !== news.length) return true
+  const left = new Map(olds.map(({ path, bytes }) => [path, bytes]))
+  const moved: Uint8Array[] = []
+  for (const { path, bytes } of news) {
+    const was = left.get(path)
+    if (was && same(was, bytes)) left.delete(path)
+    else moved.push(bytes)
+  }
+  // Those not where they were, by their digests, as many of each as there are.
+  const unmoved = new Map<string, number>()
+  for (const bytes of left.values()) {
+    const key = digest(bytes)
+    unmoved.set(key, (unmoved.get(key) ?? 0) + 1)
+  }
+  return moved.some(bytes => {
+    const key = digest(bytes)
+    const count = unmoved.get(key) ?? 0
+    if (count === 0) return true
+    unmoved.set(key, count - 1)
+    return false
+  })
+}
+
+type Side = { integrity: string; files: () => Promise<NpmPackageFile[]> }
+
+// The delta of `other` (its integrity, and how to read its files) against
+// `base`, or none, as held, else shared with one asked before it, else
+// looked for where it is kept, else worked out and kept: shared from before
+// it is looked for, lest those asked together each look, find none, and work
+// it out.
+export function npmDelta(base: Side | null, other: Side, kept: KeptStore<NpmDelta> | null = null): Promise<NpmDelta> {
+  const key = `${base?.integrity ?? '(empty)'}\0${other.integrity}`
+  const known = deltas.get(key)
+  if (known) return Promise.resolve(known)
+  const shared = working.get(key)
+  if (shared) return shared
+  const work = worked(key, base, other, kept).finally(() => working.delete(key))
+  working.set(key, work)
+  return work
+}
+
+// The deltas of those of `sides` (each the integrities of the version it is
+// against, or none, and of the version) held or kept, by their keys
+// (npmDelta's), in one read of `kept` for those not held: none worked out.
+export async function keptNpmDeltas(sides: [string | null, string][], kept: KeptStore<NpmDelta>): Promise<Map<string, NpmDelta>> {
+  const keys = [...new Set(sides.map(([base, other]) => `${base ?? '(empty)'}\0${other}`))]
+  const found = new Map(keys.flatMap(key => { const known = deltas.get(key); return known ? [[key, known] as const] : [] }))
+  const unheld = keys.filter(key => !found.has(key))
+  for (const [key, row] of unheld.length > 0 ? await kept.readMany(unheld) : []) {
+    const known = deltaOf(row.value)
+    if (!known) continue
+    deltas.set(key, known)
+    found.set(key, known)
+  }
+  return found
+}
+
+// As kept, else its turn awaited, then both sides' files read, counted and kept.
+async function worked(key: string, base: Side | null, other: Side, kept: KeptStore<NpmDelta> | null): Promise<NpmDelta> {
+  const known = deltaOf((await kept?.read(key))?.value)
+  if (known) { deltas.set(key, known); return known }
+  await turn(Date.now() + DELTA_TIMEOUT_MS)
+  let binary, told
+  try {
+    // Its turn held till both sides are read, or have failed.
+    const [baseRead, otherRead] = await Promise.allSettled([base ? base.files() : Promise.resolve(null), other.files()])
+    if (baseRead.status === 'rejected') throw baseRead.reason
+    if (otherRead.status === 'rejected') throw otherRead.reason
+    const [olds, news] = [texts(baseRead.value), texts(otherRead.value)]
+    if (olds.length + news.length > MAX_TEXT_LENGTH) throw new NpmPackageError(413, 'package-too-large')
+    binary = binaryChanged(olds.binaries, news.binaries)
+    told = await counted(olds.read, news.read, Date.now() + DELTA_TIMEOUT_MS)
+  } finally { done() }
+  const delta = { additions: told.additions, deletions: told.deletions,
+    typeless: told.typeFiles > 0 ? { additions: told.additions - told.typeAdditions, deletions: told.deletions - told.typeDeletions } : null, binary }
+  deltas.set(key, delta)
+  await kept?.write(key, delta, Date.now())
+  return delta
+}