@vzn/vx 0.0.649 → 0.0.651

package/src/cache/fold-memo.ts

@@ -13,7 +13,14 @@ export interface FoldMemoRow {
   key: string
 }
 
-export class FoldMemo {
+/** What a key fold asks of the memo; the rows stay core's (`IndexFoldMemo`). */
+export interface FoldMemo {
+  /** The key remembered for `taskId` under `probe`, if that is the probe it was folded under. */
+  get(taskId: string, probe: string): string | undefined
+  set(taskId: string, probe: string, key: string): void
+}
+
+export class IndexFoldMemo implements FoldMemo {
   private rows: Map<string, FoldMemoRow> | undefined
   private readonly dirty = new Map<string, FoldMemoRow>()
 

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

@@ -18,6 +18,7 @@ export {
   type CachePolicy,
   cachesNothing,
   EXECUTED_RUNS_SQL,
+  indexDb,
   formatCachePolicy,
   FULL_CACHE_POLICY,
   type InvocationRecord,
@@ -80,6 +81,7 @@ export {
   MAX_SCOPED_PATHSPECS,
   repoRootOf,
   startGitEnumeration,
+  checkBlobSizes,
   lazyGitEnumeration,
   type LazyGitEnumeration,
   type GitEnumeration,
@@ -102,3 +104,13 @@ export {
 } from './plugin-cache.js'
 export { packRunOutputs, putRunEntry, runEntryName, writesRunStore } from './run-store.js'
 export { branchSource } from './run-history.js'
+export {
+  type KeptFailure,
+  keepRunNotes,
+  keptFailures,
+  keptSteps,
+  keptWarnings,
+  type RunNotes,
+  type RunStep,
+} from './run-notes.js'
+export { readLockfileMemo, writeLockfileMemo, type LockfileMemo } from './lockfile-memo.js'

package/src/cache/inputs.ts

@@ -101,6 +101,9 @@ const ALWAYS_IGNORE = [
   // must not select every `**` reader under --affected.
   '.vx/.gitattributes',
   '.vx/.gitignore',
+  // `vx lock`'s record of the dependency edges and digests: the key folds
+  // the digests through `fingerprint` already.
+  '.vx/dependencies.lock.json',
   // Where restores stage (archive.ts): vx's own, never an input.
   '.vx/tmp/**',
 ]

package/src/cache/layer.ts

@@ -232,6 +232,15 @@ export interface RunRecord {
   placementMemoryBytes?: number
   /** The share of a core each runnable thread got there (`ExecuteResult.machine.cpuShare`, v49). */
   cpuShare?: number
+  /** How long it waited ready for a slot (`TaskOutcome.queuedMs`, v51). */
+  queuedMs?: number
+  /** Its output files' bytes (`TaskOutcome.outputBytes`, v51). */
+  outputBytes?: number
+  /** The tasks and groups downstream of it in the run, the scheduler's count (v51). */
+  blocks?: number
+  /** The flaky record its row's note quoted (`TaskOutcome.flaky`, v51). */
+  flakyPasses?: number
+  flakyFailures?: number
 }
 
 /**
@@ -823,6 +832,8 @@ export interface CacheLayer {
   outputsPath(hash: string): string
   /** The stored artifact's compressed size, wherever it lives; undefined when none is stored. */
   artifactSize?(hash: string): number | undefined
+  /** The output files' bytes, uncompressed, of the entry this process just saved; asked once. */
+  outputBytes?(hash: string): number | undefined
   prune(options: PruneOptions): Promise<PruneResult>
   close(): void
 }

package/src/cache/layered-cache.ts

@@ -575,6 +575,10 @@ export class LayeredCache implements CacheLayer {
     return this.local.artifactSize(hash)
   }
 
+  outputBytes(hash: string): number | undefined {
+    return this.local.outputBytes(hash)
+  }
+
   hashFile(filePath: string): Promise<string> {
     return this.local.hashFile(filePath)
   }

package/src/cache/linked-inputs.ts

@@ -71,6 +71,9 @@ export async function behindLink(
     return NOTHING_BEHIND
   }
   if (seen.has(real)) return NOTHING_BEHIND
+  // A repository's own store, as a `.git/**` input names nothing: walked,
+  // every commit and index write re-keyed the task. Its target string keys.
+  if (real.split(path.sep).includes('.git')) return NOTHING_BEHIND
   if (st.isFile()) return `file\0${await hashFile(real).catch(absentOr)}`
   if (!st.isDirectory()) return 'special'
   const inner = new Set(seen).add(real)

package/src/cache/lockfile-memo.ts

@@ -0,0 +1,120 @@
+// A lockfile claimant's parse, kept in cache.db's `lockfile_memos` (v50; a
+// `lockfile-claims/` file before): what orchestrator/lockfile-claim.ts reads
+// so a warm run never parses the lockfile. Its readers run where no `Cache`
+// is open yet — a `discover` hook, `--affected`'s selection, a verb that
+// opens none — so each call opens the index on its own and closes it. Only
+// an index that exists and holds this vx's schema is read or written: one
+// another vx wrote is reset by the next run, and a directory with none is
+// left for the run that makes it. A failure of any kind is a miss: the memo
+// is a speed-up, never a requirement.
+
+import { Database } from 'bun:sqlite'
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { closeDb, SCHEMA_VERSION, SQLITE_FCNTL_PERSIST_WAL } from './cache.js'
+
+/** One claimant's parse of one lockfile's content. */
+export interface LockfileMemo {
+  /** The claimant's own counter: bumped when it digests differently. */
+  version: number
+  /** xxh3 of the lockfile's bytes. */
+  lock: string
+  /** Each extra file the digests read → its content hash then. */
+  extras: Record<string, string>
+  /** Each importer's digest; null when the parse that wrote it left them out (a run's). */
+  importers: Record<string, string> | null
+  edges: Record<string, unknown>
+  /** Each importer's recorded dependency names; absent when the claimant reads none. */
+  recorded?: Record<string, readonly string[]>
+}
+
+function withIndex<T>(cacheDir: string, use: (db: Database) => T): T | undefined {
+  const file = path.join(cacheDir, 'cache.db')
+  if (!existsSync(file)) return undefined
+  let db: Database
+  try {
+    db = new Database(file, { readwrite: true })
+  } catch {
+    return undefined
+  }
+  try {
+    // As `Cache` opens it: wait for another run's write, and keep `-wal`
+    // and `-shm` when this is the last connection to close (O-10).
+    db.exec('PRAGMA busy_timeout = 5000')
+    db.fileControl(SQLITE_FCNTL_PERSIST_WAL, 1)
+    db.exec('PRAGMA journal_size_limit = 67108864')
+    return use(db)
+  } catch {
+    return undefined
+  } finally {
+    closeDb(db)
+  }
+}
+
+const CURRENT = "(SELECT value FROM schema_meta WHERE key = 'version') = ?"
+
+/** The memo `claimant` kept of `file`; undefined when none or another content's. */
+export function readLockfileMemo(
+  cacheDir: string,
+  file: string,
+  claimant: string,
+): LockfileMemo | undefined {
+  return withIndex(cacheDir, (db) => {
+    const row = db
+      .query(
+        `SELECT version, lock, extras, importers, edges, recorded FROM lockfile_memos
+         WHERE file = ? AND claimant = ? AND ${CURRENT}`,
+      )
+      .get(file, claimant, SCHEMA_VERSION) as {
+      version: number
+      lock: string
+      extras: string
+      importers: string
+      edges: string
+      recorded: string | null
+    } | null
+    if (row === null) return undefined
+    return {
+      version: row.version,
+      lock: row.lock,
+      extras: JSON.parse(row.extras) as Record<string, string>,
+      importers: JSON.parse(row.importers) as Record<string, string> | null,
+      edges: JSON.parse(row.edges) as Record<string, unknown>,
+      ...(row.recorded !== null
+        ? { recorded: JSON.parse(row.recorded) as Record<string, readonly string[]> }
+        : {}),
+    }
+  })
+}
+
+/** Keep `memo` as `claimant`'s of `file`, replacing the last; false when it was not kept. */
+export function writeLockfileMemo(
+  cacheDir: string,
+  file: string,
+  claimant: string,
+  memo: LockfileMemo,
+): boolean {
+  return (
+    withIndex(
+      cacheDir,
+      (db) =>
+        db
+          .query(
+            `INSERT OR REPLACE INTO lockfile_memos
+               (file, claimant, version, lock, extras, importers, edges, recorded)
+             SELECT ?, ?, ?, ?, ?, ?, ?, ? WHERE ${CURRENT}`,
+          )
+          .run(
+            file,
+            claimant,
+            memo.version,
+            memo.lock,
+            JSON.stringify(memo.extras),
+            JSON.stringify(memo.importers),
+            JSON.stringify(memo.edges),
+            memo.recorded === undefined ? null : JSON.stringify(memo.recorded),
+            SCHEMA_VERSION,
+          ).changes > 0,
+    ) ?? false
+  )
+}

package/src/cache/output-index.ts

@@ -143,17 +143,20 @@ export class OutputIndex {
   /**
    * Replace an entry's file rows. Called INSIDE the store's save transaction,
    * so an entry and its fingerprints land together (an UPDATE on the same
-   * hash refreshes rather than appends).
+   * hash refreshes rather than appends). Answers the files' bytes.
    */
-  replaceFileRows(hash: string, rows: ReadonlyArray<[string, number, number, number]>): void {
+  replaceFileRows(hash: string, rows: ReadonlyArray<[string, number, number, number]>): number {
     // A stamp taken for the rows this replaces describes their files, not these.
     this.held.delete(hash)
     this.pendingStamps.delete(hash)
     this.deleteOutputFiles.run(hash)
     this.deleteStamps.run(hash)
+    let bytes = 0
     for (const [rel, size, mode, mtime] of rows) {
       this.insertOutputFile.run(hash, rel, size, mode, mtime)
+      bytes += size
     }
+    return bytes
   }
 
   /** Hold a probe's rows for its restores (`held`), in place of the last probe's. */