@vzn/vx 0.0.650 → 0.0.652

package/src/cache/git-inputs.ts

@@ -8,11 +8,15 @@
 import os from 'node:os'
 import path from 'node:path'
 import {
+  closeSync,
   existsSync,
+  fstatSync,
   lstatSync,
   mkdtempSync,
+  openSync,
   readdirSync,
   readFileSync,
+  readSync,
   realpathSync,
   renameSync,
   rmSync,
@@ -892,7 +896,12 @@ export function fileIdentity(mode: string, oid: string): string {
 function parseLsFilesOutput(
   records: readonly string[],
   undecodableRecords: ReadonlySet<string>,
-  debug?: { sizes: readonly number[]; indexed: Map<string, { oid: string; size: number }> },
+  debug?: {
+    sizes: readonly number[]
+    ctimes: readonly number[]
+    mtimes: readonly number[]
+    indexed: Map<string, { oid: string; size: number; ctime: number; mtime: number }>
+  },
 ): GitLsResult {
   const files: string[] = []
   const oids = new Map<string, string>()
@@ -914,7 +923,12 @@ function parseLsFilesOutput(
     if ((mode === '100644' || mode === '100755' || mode === '120000') && stage === '0') {
       oids.set(filePath, fileIdentity(mode, m[3]!))
       if (debug !== undefined && mode !== '120000') {
-        debug.indexed.set(filePath, { oid: m[3]!, size: debug.sizes[i]! })
+        debug.indexed.set(filePath, {
+          oid: m[3]!,
+          size: debug.sizes[i]!,
+          ctime: debug.ctimes[i]!,
+          mtime: debug.mtimes[i]!,
+        })
       }
     } else if (mode === '160000') {
       gitlinks.add(filePath)
@@ -940,11 +954,15 @@ function parseLsFilesOutput(
 function splitLsDebug(run: GitRun): {
   records: string[]
   sizes: number[]
+  ctimes: number[]
+  mtimes: number[]
   undecodable: Set<string>
 } {
   const segs = run.stdout.split('\0')
   const records: string[] = []
   const sizes: number[] = []
+  const ctimes: number[] = []
+  const mtimes: number[] = []
   const undecodable = new Set<string>()
   let record = segs[0]!
   let recordRaw = record
@@ -952,12 +970,22 @@ function splitLsDebug(run: GitRun): {
     const seg = segs[i]
     let rest = ''
     let size = -1
+    let ctime = -1
+    let mtime = -1
     if (seg !== undefined) {
       let at = 0
       for (let k = 0; k < 5 && at >= 0; k++) {
         const nl = seg.indexOf('\n', at)
         if (nl < 0) at = -1
         else {
+          // `  ctime: <sec>:<nsec>`, then `  mtime: <sec>:<nsec>`.
+          if (k < 2) {
+            const n = parseInt(seg.slice(seg.indexOf(':', at) + 1, nl), 10)
+            if (!Number.isNaN(n)) {
+              if (k === 0) ctime = n
+              else mtime = n
+            }
+          }
           if (k === 4) {
             const field = seg.indexOf('size: ', at)
             if (field >= 0 && field < nl) {
@@ -973,12 +1001,14 @@ function splitLsDebug(run: GitRun): {
     if (record.length > 0) {
       records.push(record)
       sizes.push(size)
+      ctimes.push(ctime)
+      mtimes.push(mtime)
       if (run.undecodable.has(recordRaw)) undecodable.add(record)
     }
     record = rest
     recordRaw = seg ?? ''
   }
-  return { records, sizes, undecodable }
+  return { records, sizes, ctimes, mtimes, undecodable }
 }
 
 /**
@@ -998,6 +1028,8 @@ export interface IndexBlobs {
   paths: string[]
   oids: string[]
   sizes: number[]
+  /** Entries git cannot see a same-second rewrite of (`sameSecond`). */
+  sameSecond: string[]
 }
 
 /** What the blob-size check reads, lazily: the verdict's key, and the listing a miss needs. */
@@ -1010,6 +1042,31 @@ export interface IndexBlobCheck {
   rekey(): Promise<string | undefined>
 }
 
+/** At most `n` contiguous parts of `items`, none under `CAT_FILE_MIN`: a spawn costs more than a few lookups. */
+function chunks<T>(items: readonly T[], n: number): T[][] {
+  const parts = Math.min(n, Math.ceil(items.length / CAT_FILE_MIN))
+  const size = Math.ceil(items.length / Math.max(1, parts))
+  const out: T[][] = []
+  for (let at = 0; at < items.length; at += size) out.push(items.slice(at, at + size))
+  return out
+}
+const CAT_FILE_MIN = 256
+
+const sizeChecks = new WeakMap<GitEnumeration, Promise<void>>()
+/**
+ * `dropResizedOids` once per enumeration: a run starts it as soon as its
+ * cache opens, so the check runs beside the config load and graph build
+ * instead of after them, and `applyGitEnumeration` waits on the same one.
+ */
+export function checkBlobSizes(enumeration: GitEnumeration, memo?: BlobSizeMemo): Promise<void> {
+  let check = sizeChecks.get(enumeration)
+  if (check === undefined) {
+    check = dropResizedOids(enumeration, memo)
+    sizeChecks.set(enumeration, check)
+  }
+  return check
+}
+
 /**
  * Drop each trusted OID whose blob is not the size the index recorded for
  * the worktree file (A-60). A clean filter's blob differs from the file it
@@ -1026,6 +1083,8 @@ export interface IndexBlobCheck {
  * (racy) entry records 0 and is hashed from disk. An answer that cannot be
  * read trusts nothing. A filter that keeps the size (`tr a-z A-Z`) is not
  * caught: only a read of every trusted file would be (caching.md, step 12).
+ * The verdict also holds each entry git cannot see a same-second rewrite
+ * of (`sameSecond`), read from the same listing.
  */
 async function dropResizedOids(enumeration: GitEnumeration, memo?: BlobSizeMemo): Promise<void> {
   const { trusted, blobCheck } = enumeration
@@ -1033,31 +1092,47 @@ async function dropResizedOids(enumeration: GitEnumeration, memo?: BlobSizeMemo)
   const key = blobCheck.key
   let resized = key === undefined ? undefined : memo?.blobVerdict(key)
   if (resized === undefined) {
-    const blobs = await blobCheck.blobs()
+    // The sizes are asked beside the listing: both read the index the
+    // enumeration listed (the listing refuses one written since), so the
+    // OIDs are the listing's. One after the other, a cold 9,603-task run
+    // waited on the listing's 70-95 ms before the first spawn (2026-11-01).
+    const listing = blobCheck.blobs()
+    // Only what is still trusted: a path dropped already needs no size.
+    // Built here, not with the listing: a run whose verdict is memoized
+    // never needs it, and on 9,603 tasks it cost 17-35 ms (2026-11-01).
+    // A non-regular mode rides its value (`100755:<oid>`); cat-file takes the OID.
+    const oids = [...new Set(Array.from(trusted.values(), (v) => v.slice(v.lastIndexOf(':') + 1)))]
+    const sizes = memo?.knownBlobSizes(oids) ?? new Map<string, number>()
+    const unknown = oids.filter((oid) => !sizes.has(oid))
+    // One cat-file per core: a fresh clone's objects are loose, and one
+    // process opened and inflated 2,505 of them in 30 ms before the first
+    // task of a cold 100-package run; four took 14 (2026-11-03).
+    const asked = Promise.all(
+      chunks(unknown, Math.max(1, navigator.hardwareConcurrency)).map((part) =>
+        enumeration.catFile(part.join('\n') + '\n'),
+      ),
+    )
+    const [blobs, runs] = await Promise.all([listing, asked])
     if (blobs === null) {
       trusted.clear()
       return
     }
-    const unique = [...new Set(blobs.oids)]
-    const sizes = memo?.knownBlobSizes(unique) ?? new Map<string, number>()
-    const unknown = unique.filter((oid) => !sizes.has(oid))
-    if (unknown.length > 0) {
-      const run = await enumeration.catFile(unknown.join('\n') + '\n')
-      if (run === null || run.exitCode !== 0) {
-        trusted.clear()
-        return
-      }
-      const learned = new Map<string, number>()
-      for (const line of run.stdout.split('\n')) {
+    if (runs.some((run) => run === null || run.exitCode !== 0)) {
+      trusted.clear()
+      return
+    }
+    const learned = new Map<string, number>()
+    for (const run of runs) {
+      for (const line of run!.stdout.split('\n')) {
         const sp = line.indexOf(' ')
         const n = Number(line.slice(sp + 1))
         if (sp > 0 && line.slice(sp + 1) !== '' && Number.isInteger(n))
           learned.set(line.slice(0, sp), n)
       }
-      for (const [oid, n] of learned) sizes.set(oid, n)
-      memo?.rememberBlobSizes(learned)
     }
-    resized = []
+    for (const [oid, n] of learned) sizes.set(oid, n)
+    if (learned.size > 0) memo?.rememberBlobSizes(learned)
+    resized = [...blobs.sameSecond]
     for (let i = 0; i < blobs.oids.length; i++) {
       const size = sizes.get(blobs.oids[i]!)
       // The index keeps the low 32 bits of a size.
@@ -1626,6 +1701,19 @@ function hasRacyEntry(index: Uint8Array, mtimeSec: number, oidBytes: number): bo
   return false
 }
 
+/**
+ * git compares a file's ctime to the second only, and its racy rule reads
+ * mtime alone: a same-size rewrite that keeps (or restores) an older mtime,
+ * made in the second the index recorded the file, keeps every stat git
+ * compares, and `status` calls it clean. An entry whose recorded ctime, not
+ * its mtime, reaches the second its index was written can hide one; git
+ * re-hashes an entry racy by mtime. Its OID is not trusted. The stamps are
+ * git's own (`ls-files --debug`), judged once per index (the verdict).
+ */
+function sameSecond(ctimeSec: number, mtimeSec: number, writtenSec: number): boolean {
+  return ctimeSec < 0 || (ctimeSec >= writtenSec && mtimeSec < writtenSec)
+}
+
 /** A private copy a run older than this may still have handed to `status`. */
 const STALE_INDEX_MS = 60_000
 
@@ -1711,7 +1799,7 @@ export async function startGitEnumeration(
     stdin?: string,
     env?: Record<string, string>,
   ): Promise<GitRun | null> => {
-    const spawn = <Out extends 'pipe' | Bun.BunFile>(stdout: Out) =>
+    const spawn = <Out extends 'pipe' | number>(stdout: Out) =>
       Bun.spawn({
         // `status` refreshes the index when it can take `index.lock`, so
         // the user's own `git add` or `commit` failed on the lock while a
@@ -1728,23 +1816,30 @@ export async function startGitEnumeration(
     // loading configs while git lists, and a pipe held a 10 MB listing
     // until the thread came back to drain it 64 KiB at a time (~90 ms of
     // a warm 5,000-project run). In a directory of its own, so no link
-    // another user planted in a shared temp directory takes the bytes. A
-    // temp directory that takes none falls back to the pipe.
-    let dir: string | undefined
+    // another user planted in a shared temp directory takes the bytes, and
+    // the directory goes the moment the file is open: a run stopped
+    // mid-listing (a Ctrl-C before the run's signal handlers, or a kill)
+    // runs no `finally`, and each left a `vx-git-*` behind. A temp
+    // directory that takes none falls back to the pipe.
+    let fd: number | undefined
     try {
-      dir = mkdtempSync(path.join(os.tmpdir(), 'vx-git-'))
+      const dir = mkdtempSync(path.join(os.tmpdir(), 'vx-git-'))
+      try {
+        fd = openSync(path.join(dir, 'out'), 'w+', 0o600)
+      } finally {
+        rmSync(dir, { recursive: true, force: true })
+      }
     } catch {
-      dir = undefined
+      fd = undefined
     }
     try {
       let stdout: Uint8Array
       let stderr: string
       let exitCode: number
-      if (dir !== undefined) {
-        const out = path.join(dir, 'out')
-        const proc = spawn(Bun.file(out))
+      if (fd !== undefined) {
+        const proc = spawn(fd)
         ;[stderr, exitCode] = await Promise.all([new Response(proc.stderr).text(), proc.exited])
-        stdout = await Bun.file(out).bytes()
+        stdout = readWhole(fd)
       } else {
         const piped = spawn('pipe')
         ;[stdout, stderr, exitCode] = await Promise.all([
@@ -1758,7 +1853,7 @@ export async function startGitEnumeration(
     } catch {
       return null
     } finally {
-      if (dir !== undefined) rmSync(dir, { recursive: true, force: true })
+      if (fd !== undefined) closeSync(fd)
     }
   }
   const startedAtMs = Date.now()
@@ -1834,7 +1929,9 @@ export async function startGitEnumeration(
         bytes,
         hash,
         st,
-        key: `${hash}:${pathspecKey}`,
+        // The mtime too: which entries git can see a same-second rewrite
+        // of (`sameSecond`) turns on the second the index was written.
+        key: `${hash}:${pathspecKey}:${Math.floor(st.mtimeMs / 1000)}`,
         stamp: `${st.ino}:${st.ctimeMs}:${st.size}`,
       }
     } catch {
@@ -1863,10 +1960,16 @@ export async function startGitEnumeration(
       index === undefined ? undefined : { GIT_INDEX_FILE: index },
     )
   // An index with no racy entry is read as it is: `status` spawns now.
+  // The copy `status` read, when it read one: its stats are the ones the
+  // dirty set came from, so the blob check lists it too.
+  let statusCopy: string | undefined
   const statusRun =
     read === undefined || indexFile === undefined || !racyIndex(read, facts!.objectFormat)
       ? spawnStatus(undefined)
-      : refreshedIndex(indexFile, read, spawnGit).then(spawnStatus)
+      : refreshedIndex(indexFile, read, spawnGit).then((copy) => {
+          statusCopy = copy
+          return spawnStatus(copy)
+        })
   const running = Promise.all([listing, statusRun, varsRun])
   const gitPrefix = facts?.prefix ?? ''
   const gitDir = facts?.commonDir ?? ''
@@ -1888,6 +1991,17 @@ export async function startGitEnumeration(
   // the stamp moves with any write) and is still in place after it: a
   // `git add` between the listing and the read paired one index's verdict
   // with the other's entries. Otherwise this run asks for no verdict.
+  // A verdict read from the copy holds for that copy file only: a copy
+  // written again (a new inode) asks again.
+  const copyKey = (key: string): string | undefined => {
+    if (statusCopy === undefined) return key
+    try {
+      const st = lstatSync(statusCopy)
+      return `${key}:${st.ino}:${st.mtimeMs}`
+    } catch {
+      return undefined
+    }
+  }
   let indexKey: string | undefined
   if (
     read !== undefined &&
@@ -1895,7 +2009,7 @@ export async function startGitEnumeration(
   ) {
     try {
       const st = lstatSync(indexFile!)
-      if (`${st.ino}:${st.ctimeMs}:${st.size}` === read.stamp) indexKey = read.key
+      if (`${st.ino}:${st.ctimeMs}:${st.size}` === read.stamp) indexKey = copyKey(read.key)
     } catch {
       // gone: no key
     }
@@ -1997,24 +2111,47 @@ export async function startGitEnumeration(
     blobCheck: {
       key: indexKey,
       async blobs() {
-        const run = await spawnGit(['ls-files', '-s', '-v', '-z', '--debug', '--', ...pathspecs])
+        const listed = statusCopy ?? indexFile
+        let writtenSec = 0
+        try {
+          if (listed !== undefined) writtenSec = Math.floor(lstatSync(listed).mtimeMs / 1000)
+        } catch {
+          return null
+        }
+        const run = await spawnGit(
+          ['ls-files', '-s', '-v', '-z', '--debug', '--', ...pathspecs],
+          undefined,
+          statusCopy === undefined ? undefined : { GIT_INDEX_FILE: statusCopy },
+        )
         if (run === null || run.exitCode !== 0) return null
         // Sizes from an index written since the listing judge entries the
         // trusted OIDs did not come from: an add there rewrote a resized
         // entry to one that fits, and the listed OID stood (A-60).
         if (indexStamp() !== stampBefore) return null
         const debug = splitLsDebug(run)
-        const indexed = new Map<string, { oid: string; size: number }>()
-        parseLsFilesOutput(debug.records, debug.undecodable, { sizes: debug.sizes, indexed })
-        const blobs: IndexBlobs = { paths: [], oids: [], sizes: [] }
-        for (const [rel, { oid, size }] of indexed) {
+        const indexed = new Map<
+          string,
+          { oid: string; size: number; ctime: number; mtime: number }
+        >()
+        parseLsFilesOutput(debug.records, debug.undecodable, {
+          sizes: debug.sizes,
+          ctimes: debug.ctimes,
+          mtimes: debug.mtimes,
+          indexed,
+        })
+        const blobs: IndexBlobs = { paths: [], oids: [], sizes: [], sameSecond: [] }
+        for (const [rel, { oid, size, ctime, mtime }] of indexed) {
           blobs.paths.push(rel)
           blobs.oids.push(oid)
           blobs.sizes.push(size)
+          if (sameSecond(ctime, mtime, writtenSec)) blobs.sameSecond.push(rel)
         }
         return blobs
       },
-      rekey: async () => (await readIndex())?.key,
+      rekey: async () => {
+        const key = (await readIndex())?.key
+        return key === undefined ? undefined : copyKey(key)
+      },
     },
     // A missing blob is an answer ("missing"), never a fetch from a partial
     // clone's promisor remote.
@@ -2083,7 +2220,7 @@ export async function applyGitEnumeration(
   workspaceWide = false,
   memo?: BlobSizeMemo,
 ): Promise<void> {
-  await dropResizedOids(enumeration, memo)
+  await checkBlobSizes(enumeration, memo)
   const { all, trusted } = enumeration
   cache.setWorktreeDirty(enumeration.dirty)
   cache.setGitVars(enumeration.vars)
@@ -2218,3 +2355,15 @@ export async function applyGitEnumeration(
     cache.setWorkspaceRoot(workspaceRoot)
   }
 }
+
+/** The whole of a file held only by `fd`, from its start. */
+function readWhole(fd: number): Uint8Array {
+  const bytes = new Uint8Array(fstatSync(fd).size)
+  let at = 0
+  while (at < bytes.length) {
+    const n = readSync(fd, bytes, at, bytes.length - at, at)
+    if (n === 0) break
+    at += n
+  }
+  return at === bytes.length ? bytes : bytes.subarray(0, at)
+}

package/src/cache/history-stream.ts

@@ -0,0 +1,134 @@
+// A run's hits written to the history while the graph still runs, on a
+// thread of their own (history-writer.ts). A warm run's rows were the
+// main thread's last ~65 ms at 8,002 hits, after the graph; here they land
+// while it runs. What does not land (no thread, a refused batch) is
+// handed back and goes in the run's own bundle, as before.
+
+import type { RunRecord } from './layer.js'
+import type { HistoryWriterIn, HistoryWriterOut } from './history-writer.js'
+
+/**
+ * Rows per batch, and the hits a run has before it starts a thread: a
+ * run with fewer writes them in its bundle, as cheap as a thread's start.
+ */
+const BATCH = 512
+
+/** A record of `T` whose row the stream holds. */
+export interface Streamed<T> {
+  item: T
+  record: RunRecord
+}
+
+export class HistoryStream<T> {
+  private worker: Worker | undefined
+  private buffer: Streamed<T>[] = []
+  private readonly sent = new Map<number, Streamed<T>[]>()
+  private readonly landed: Streamed<T>[] = []
+  private seq = 0
+  /** A batch was refused or the thread died: nothing more is sent. */
+  private dead = false
+  /** The thread died: no batch answers any more. */
+  private gone = false
+  private readonly refused = new Set<number>()
+  private settle: (() => void) | undefined
+  private ended: (() => void) | undefined
+
+  constructor(private readonly files: { index: string; store?: string }) {}
+
+  add(item: T, record: RunRecord): void {
+    this.buffer.push({ item, record })
+    if (this.buffer.length >= BATCH && !this.dead) this.send()
+  }
+
+  /**
+   * Waits for every batch sent, closes the thread, and returns what landed
+   * and what did not (the run's bundle writes those).
+   */
+  async finish(): Promise<{ landed: Streamed<T>[]; unlanded: Streamed<T>[] }> {
+    const w = this.worker
+    if (w !== undefined && !this.gone) {
+      // Unreferenced, its answers alone left the loop with nothing to
+      // wait on: the run ended "awaited can never settle".
+      w.ref()
+      await new Promise<void>((resolve) => {
+        this.settle = resolve
+        this.settled()
+      })
+      if (!this.gone) {
+        await new Promise<void>((resolve) => {
+          this.ended = resolve
+          w.postMessage({ end: true } satisfies HistoryWriterIn)
+        })
+      }
+    }
+    w?.terminate()
+    const unlanded = [...this.sent.values()].flat().concat(this.buffer)
+    this.sent.clear()
+    this.buffer = []
+    return { landed: this.landed, unlanded }
+  }
+
+  private send(): void {
+    const w = (this.worker ??= this.start())
+    const batch = this.buffer
+    this.buffer = []
+    const seq = this.seq++
+    this.sent.set(seq, batch)
+    // A record's spans are bigint, which JSON cannot carry: as numbers, exact
+    // below 2^53 ns (104 days into a run). A replacer function cost 20 ms
+    // of 8,002 rows, the copies 4.
+    const hits = JSON.stringify(
+      batch.map(({ record: r }) => ({
+        ...r,
+        wallclockStartNs: r.wallclockStartNs === undefined ? undefined : Number(r.wallclockStartNs),
+        wallclockEndNs: r.wallclockEndNs === undefined ? undefined : Number(r.wallclockEndNs),
+      })),
+    )
+    w.postMessage({ seq, hits } satisfies HistoryWriterIn)
+  }
+
+  private start(): Worker {
+    const w = new Worker(new URL('./history-writer.ts', import.meta.url).href)
+    // A run that throws before `finish` must still exit; a batch cut off
+    // mid-write rolls back whole.
+    w.unref()
+    w.onmessage = (e: MessageEvent<HistoryWriterOut>) => {
+      const m = e.data
+      if ('ended' in m) {
+        this.ended?.()
+        return
+      }
+      const batch = this.sent.get(m.seq)
+      if (batch === undefined) return
+      if (m.error === undefined) {
+        this.sent.delete(m.seq)
+        for (const b of batch) this.landed.push(b)
+      } else {
+        // Kept in `sent`, so the bundle writes it; no later batch is sent.
+        this.refused.add(m.seq)
+        this.dead = true
+      }
+      this.settled()
+    }
+    // A thread that cannot start or dies: what it did not answer for is
+    // the bundle's.
+    w.onerror = (e) => {
+      e.preventDefault()
+      this.dead = true
+      this.gone = true
+      this.settled()
+      this.ended?.()
+    }
+    w.postMessage({ open: this.files } satisfies HistoryWriterIn)
+    return w
+  }
+
+  /** Resolves `finish`'s wait once every batch sent has answered, or the thread is gone. */
+  private settled(): void {
+    if (this.settle === undefined) return
+    if (!this.gone && [...this.sent.keys()].some((seq) => !this.refused.has(seq))) return
+    const s = this.settle
+    this.settle = undefined
+    s()
+  }
+}

package/src/cache/history-writer.ts

@@ -0,0 +1,76 @@
+// The thread that writes a run's hits to the history while the run goes on
+// (history-stream.ts). A connection of its own on the run's cache files,
+// opened as `Cache` opens them; each batch is one IMMEDIATE transaction,
+// answered by its sequence number so the run knows which landed.
+// A separate entry point: `bun build --compile` embeds it beside bin.ts.
+
+import { Database } from 'bun:sqlite'
+import type { RunRecord } from './layer.js'
+import { RunHistory } from './run-history.js'
+import { SQLITE_FCNTL_PERSIST_WAL } from './schema.js'
+
+export type HistoryWriterIn =
+  | { open: { index: string; store?: string } }
+  | { seq: number; hits: string }
+  | { end: true }
+
+export type HistoryWriterOut = { seq: number; error?: string } | { ended: true }
+
+declare const self: Worker
+
+let db: Database | undefined
+let history: RunHistory | undefined
+let refused: string | undefined
+
+function open(files: { index: string; store?: string }): void {
+  // The timeout first, as `Cache` sets it: every later pragma waits under it.
+  db = new Database(files.index)
+  db.exec('PRAGMA busy_timeout = 5000')
+  db.fileControl(SQLITE_FCNTL_PERSIST_WAL, 1)
+  db.exec('PRAGMA journal_size_limit = 67108864')
+  db.exec('PRAGMA synchronous = NORMAL')
+  if (files.store !== undefined) {
+    db.prepare('ATTACH DATABASE ? AS store').run(files.store)
+    db.fileControl('store', SQLITE_FCNTL_PERSIST_WAL, 1)
+    db.exec('PRAGMA store.journal_size_limit = 67108864')
+    db.exec('PRAGMA store.synchronous = NORMAL')
+  }
+  // A streamed hit carries no forward args (history-stream.ts): nothing digests.
+  history = new RunHistory(db, () => {
+    throw new Error('a streamed hit has no value to digest')
+  })
+}
+
+self.onmessage = (e: MessageEvent<HistoryWriterIn>) => {
+  const m = e.data
+  if ('open' in m) {
+    try {
+      open(m.open)
+    } catch (err) {
+      refused = err instanceof Error ? err.message : String(err)
+    }
+    return
+  }
+  if ('end' in m) {
+    try {
+      db?.close()
+    } catch {
+      // The rows are in; a close that fails leaves the WAL to the next opener.
+    }
+    postMessage({ ended: true } satisfies HistoryWriterOut)
+    return
+  }
+  if (history === undefined) {
+    postMessage({ seq: m.seq, error: refused ?? 'not open' } satisfies HistoryWriterOut)
+    return
+  }
+  try {
+    history.recordHits(JSON.parse(m.hits) as RunRecord[])
+    postMessage({ seq: m.seq } satisfies HistoryWriterOut)
+  } catch (err) {
+    postMessage({
+      seq: m.seq,
+      error: err instanceof Error ? err.message : String(err),
+    } satisfies HistoryWriterOut)
+  }
+}

package/src/cache/index.ts

@@ -18,6 +18,7 @@ export {
   type CachePolicy,
   cachesNothing,
   EXECUTED_RUNS_SQL,
+  historyFiles,
   indexDb,
   formatCachePolicy,
   FULL_CACHE_POLICY,
@@ -81,6 +82,7 @@ export {
   MAX_SCOPED_PATHSPECS,
   repoRootOf,
   startGitEnumeration,
+  checkBlobSizes,
   lazyGitEnumeration,
   type LazyGitEnumeration,
   type GitEnumeration,
@@ -103,6 +105,7 @@ export {
 } from './plugin-cache.js'
 export { packRunOutputs, putRunEntry, runEntryName, writesRunStore } from './run-store.js'
 export { branchSource } from './run-history.js'
+export { HistoryStream } from './history-stream.js'
 export {
   type KeptFailure,
   keepRunNotes,