@vzn/vx 0.0.16 → 0.0.18

package/src/cache/cache.ts

@@ -30,13 +30,19 @@
 //   close           : release the SQLite handle
 
 import { Database, type SQLQueryBindings } from 'bun:sqlite'
-import { mkdirSync, statSync } from 'node:fs'
-import { mkdir, mkdtemp, rename, rm, stat, utimes } from 'node:fs/promises'
-import os from 'node:os'
+import { existsSync, mkdirSync, statSync, writeFileSync } from 'node:fs'
+import { lstat, mkdir, readdir, rename, rm, stat, unlink, writeFile } from 'node:fs/promises'
 import path from 'node:path'
-import { relPosix, UserError, xxh3, xxh3hex } from '../util/index.js'
+import { relPosix, UserError, xxh3, xxh3hex, span } from '../util/index.js'
+import {
+  ArchiveSecurityError,
+  extractArtifactStream,
+  scanArtifact,
+  packArtifactBytes,
+  packArtifactStream,
+  planArtifact,
+} from './archive.js'
 import { FsCASBackend } from './cas-backend.js'
-import { extractOutputs, parseTarHeaders, readTarText } from './tar.js'
 
 // v17: artifact carries only logs + outputs (stdout + outputs/<rel>).
 // Local and remote layers transport the SAME tar.zst bytes — no
@@ -75,7 +81,28 @@ import { extractOutputs, parseTarHeaders, readTarText } from './tar.js'
 // inside the key fold (the new `captureInto` sink is a pure
 // side-channel). A task's hash is byte-identical before and after, so
 // existing artifacts stay valid and there is no cache-version bump.
-const CACHE_VERSION = 'vx-cache-v24'
+// v25: the ARTIFACT BYTES are wrong in every existing entry, while the
+// key that addresses them is unchanged — the one situation a version
+// bump exists for. Two defects: (a) `packArtifact` staged outputs with
+// `Bun.write`, which does not carry the source mode, so every artifact
+// records 0644 and a cache hit strips the executable bit off any binary
+// or generated script; (b) it packed `--format=ustar`, which splits a
+// name over 100 bytes into prefix+name, and the reader read only `name`
+// — so those entries lost their `outputs/` prefix and were silently
+// dropped from both the restore and the output_files index. Neither is
+// self-healing: the stored bytes/headers are already wrong, so without a
+// new namespace the fixed code would keep replaying them forever.
+// v26: same situation, different producer. A task whose child was killed by
+// a shutdown signal reported `aborted`, but `aborted` did not propagate to
+// dependents — so a dependent ran against PARTIAL outputs, succeeded, and
+// cached what it built. The fold takes the upstream's INPUT key, which a
+// signal does not change, so that entry sits under exactly the key a healthy
+// run derives and replays forever as a green hit. Fixing the propagation
+// stops new poison but cannot reach entries already written, and a
+// `LayeredCache` uploads them, so the reach is a whole team's shared cache
+// rather than one developer's disk. Pre-alpha, so one cold rebuild is the
+// cheap side of that trade.
+const CACHE_VERSION = 'vx-cache-v27'
 // SCHEMA history (drop+recreate on mismatch; pre-alpha, no migrations):
 //   v20: file_hashes.content_hash (git blob OIDs).
 //   v21: dropped the unused outputs_hash column (pure-input hashing).
@@ -94,7 +121,44 @@ const CACHE_VERSION = 'vx-cache-v24'
 //        passed under identical inputs is nondeterministic by definition;
 //        no cross-run inference needed). Nullable; NULL for a once-run
 //        task. Analytics-only — the cache KEY is unchanged.
-const SCHEMA_VERSION = 'v23'
+//   v24: file_hashes.ctime_ms + .ino — the stat memo's guard against a
+//        content change that PRESERVES mtime (`tar -x`, `cp -p`,
+//        `rsync --times`, SOURCE_DATE_EPOCH). (mtime, size) alone
+//        returned the previous run's digest for different bytes, i.e. a
+//        stale cache hit. `utimes` cannot suppress ctime unprivileged
+//        and an atomic write-then-rename changes the inode, so the two
+//        together close it; git's index keys on ctime+ino+dev for the
+//        same reason. Both come free from the stat already taken. The
+//        cache KEY derivation is unchanged (CACHE_VERSION not bumped) —
+//        the memo simply stops answering wrongly, so an affected task's
+//        key moves from a WRONG value to the right one: it misses once,
+//        re-runs, re-caches. Self-healing, never a wrong hit.
+const SCHEMA_VERSION = 'v24'
+
+/**
+ * SQL predicate selecting `runs` rows that record an EXECUTION.
+ *
+ * Every non-group, non-aborted outcome of a run gets a row, so the header's
+ * `task_count` matches `COUNT(*)` and the run-detail timeline is complete.
+ * But a `skipped` row is a task the run never executed — its upstream failed,
+ * so it has no exit of its own, no duration, and made no cache decision.
+ * Counting it in a RATE or a MEAN dilutes that figure with a non-event: a
+ * task skipped as often as it succeeds reads 50% success, and a zero-duration
+ * row drags every average toward zero.
+ *
+ * Lives here, beside the schema, because the same figure is computed in more
+ * than one place (`Cache.stats` and the run-history queries both answer
+ * "runs in the last 24h") and two copies of a rule are how they drift apart.
+ */
+export const EXECUTED_RUNS_SQL = "status <> 'skipped'"
+
+/**
+ * SQL predicate selecting `runs` rows that recorded a cache key. `hash` is
+ * `''` for an outcome that never derived one (see {@link RunRecord.hash}),
+ * and `''` is not a key: it can neither corroborate flakiness nor say the
+ * inputs changed. Mirrors the `hash <> ''` guards in the cloud analytics copy.
+ */
+export const KEYED_RUNS_SQL = "hash <> ''"
 
 /**
  * Artifact + `output_files` namespace prefix for workspace-root-
@@ -222,6 +286,29 @@ export interface CacheKeyInput {
    * absent, the captured `upstream` row falls back to `name = hash`.
    */
   upstreamIds?: ReadonlyMap<string, string>
+  /**
+   * The task's DEPENDENCY closure with GROUP tasks expanded into the real
+   * tasks they stand for — what an input-shipping executor must place in the
+   * input root. A different question from what the key folds, and derived
+   * differently in both directions:
+   *
+   * - It expands groups, which contribute a synthetic roll-up hash and no
+   *   outputs of their own, so a dependent of one would otherwise describe
+   *   an empty closure.
+   * - It ignores `cache.inputs.tasks`. That filter says which upstream KEYS
+   *   this task's key folds; what the task may READ is `dependsOn`, and
+   *   locally every dependency's outputs are on disk before the command runs
+   *   however the filter is written.
+   *
+   * NEVER folded into the digest — the key cascades through a group's own
+   * roll-up hash already, and folding either difference in would move every
+   * existing dependent's key without telling it anything new.
+   */
+  upstreamGraft?: ReadonlyArray<{
+    readonly taskId: string
+    readonly hash: string
+    readonly projectDir: string
+  }>
   /**
    * Workspace-level fingerprint — typically a hash of `pnpm-lock.yaml` +
    * `pnpm-workspace.yaml`. Folds resolved dep versions and workspace shape
@@ -253,6 +340,12 @@ export interface CacheKeyInput {
    * hash arrived via the map or the fallback.
    */
   fileHashes?: ReadonlyMap<string, string>
+  /**
+   * Material a plugin's `key` stage contributed, as sorted `[name, value]`
+   * pairs. Folded only when non-empty, so a workspace without a key plugin
+   * derives exactly the key it always did.
+   */
+  pluginParts?: ReadonlyArray<readonly [name: string, value: string]>
   /**
    * When set, `key()` pushes each component (kind, name, hash) it folds
    * — at the same fold sites, in fold order. Pure SIDE-CHANNEL: it does
@@ -276,6 +369,19 @@ export interface CacheEntry {
   exitCode: number
   durationMs: number
   outputFiles: string[]
+  /**
+   * The `output_files` rows behind `outputFiles` (size / mode / mtime), when
+   * the layer that produced this entry had them in hand. `restoreHit` reads
+   * them for its tree-is-current check instead of re-querying — one SQL
+   * round trip per cache hit, saved.
+   */
+  outputRows?: OutputFileRow[]
+  /**
+   * The `output_dirs` rows behind the directory short-circuit, when the
+   * batched `getMany` loaded them — one query for the run instead of one
+   * per hit (0.12 ms each across a warm 1000-project run before this).
+   */
+  outputDirRows?: OutputDirRow[]
   /** Captured stdout, always present (may be empty). stderr is not cached. */
   stdout: string
   storedAt: string
@@ -291,7 +397,17 @@ export interface CacheEntry {
 }
 
 export interface RunRecord {
-  hash: string
+  /**
+   * The task's cache key. ABSENT when the outcome never derived one — a
+   * `skipped` task (its upstream failed, so it never probed) or a
+   * `persistent` one (a dev server is never cached). Such a row is still a
+   * task of the run and must be recorded, so the column keeps a `''`
+   * sentinel rather than going nullable: `''` is impossible for a real key
+   * (`Cache.key` returns 16 hex chars), the reads that must not treat it as
+   * a key already guard it, and it matches what the cloud `task_runs.hash`
+   * column has stored for the same concept since its first migration.
+   */
+  hash?: string
   project: string
   task: string
   status: 'success' | 'failed' | 'cache-hit' | 'cache-hit-remote' | 'skipped'
@@ -373,6 +489,11 @@ export interface CacheStats {
   hitCountLast24h: number
 }
 
+export interface CacheStatsOptions {
+  /** Narrow every aggregate to one project. Absent = the whole workspace. */
+  project?: string
+}
+
 export interface PruneOptions {
   /** Drop entries last accessed before this ms-epoch threshold. */
   olderThanMs?: number
@@ -408,6 +529,27 @@ export interface OutputFileRow {
   mtimeMs: number
 }
 
+/** One directory under a whole-subtree output glob, as it stood after the last save or restore on THIS machine. */
+export interface OutputDirRow {
+  path: string
+  mtimeMs: number
+}
+
+/** More directories than this under a task's output prefixes: record nothing, keep the walk. */
+export const OUTPUT_DIRS_CAP = 256
+
+/**
+ * A directory whose mtime lies within this many ms of the snapshot is RACY
+ * and the whole snapshot is dropped. File timestamps are coarse on Linux
+ * (a kernel tick, up to 10 ms), so a write landing in the same tick as the
+ * one that made the directory's recorded mtime leaves the mtime unchanged
+ * and the change invisible — git's index distrusts stats this young for
+ * the same reason (a stray survived a hit on the ubuntu job, 2026-09-03).
+ * The next hit walks, and once the tree is older than the window it is
+ * recorded for good.
+ */
+export const OUTPUT_DIRS_RACY_MS = 50
+
 /**
  * The shape every cache implementation honors. `Cache` (the local v10
  * implementation) and `LayeredCache` both `implements` this so the
@@ -466,7 +608,7 @@ export class CorruptArtifactError extends Error {
  * bounding a malicious/compromised remote's ability to OOM a victim who takes
  * a cache hit.
  */
-export const MAX_DECOMPRESSED_ARTIFACT_BYTES = 2 * 1024 * 1024 * 1024
+const MAX_DECOMPRESSED_ARTIFACT_BYTES = 2 * 1024 * 1024 * 1024
 
 /**
  * Read a zstd frame's declared Frame_Content_Size (RFC 8878 §3.1.1) WITHOUT
@@ -503,18 +645,27 @@ export function zstdContentSize(b: Uint8Array): bigint | null {
 }
 
 /**
- * Decompress a zstd artifact with a hard output ceiling. `trusted` marks a
- * locally-produced artifact (always carries a declared content size); an
- * UNTRUSTED (remote-sourced) frame that declares no content size is refused,
- * since our producer and the Turbo servers we interop with always write one —
- * a sizeless frame from the network is the shape a bomb takes to dodge the
- * pre-decompress check.
+ * Decompress a zstd artifact that DECLARES its content size, with a hard
+ * output ceiling: refused before a byte is allocated when the declaration
+ * is over the cap, and again on the actual length. A frame with no
+ * declaration (a streamed producer's — vx's own, above 4 MiB) never comes
+ * here: `decodedTar` decodes it as a stream under the running count, so
+ * a sizeless bomb has nowhere to expand.
  */
-async function zstdDecompressBounded(
-  compressed: Uint8Array,
-  hash: string,
-  trusted: boolean,
-): Promise<Uint8Array> {
+async function zstdDecompressBounded(compressed: Uint8Array, hash: string): Promise<Uint8Array> {
+  assertDeclaredSize(compressed, hash)
+  const out = await Bun.zstdDecompress(compressed)
+  if (out.length > MAX_DECOMPRESSED_ARTIFACT_BYTES) {
+    throw new CorruptArtifactError(
+      hash,
+      `decompressed to ${out.length} bytes (> ${MAX_DECOMPRESSED_ARTIFACT_BYTES} cap)`,
+    )
+  }
+  return out
+}
+
+/** The pre-decompress half of the ceiling: the frame header's own claim, when it makes one. */
+function assertDeclaredSize(compressed: Uint8Array, hash: string): bigint | null {
   const declared = zstdContentSize(compressed)
   if (declared !== null && declared > BigInt(MAX_DECOMPRESSED_ARTIFACT_BYTES)) {
     throw new CorruptArtifactError(
@@ -522,22 +673,143 @@ async function zstdDecompressBounded(
       `declares ${declared} decompressed bytes (> ${MAX_DECOMPRESSED_ARTIFACT_BYTES} cap)`,
     )
   }
-  if (declared === null && !trusted) {
-    throw new CorruptArtifactError(hash, 'remote zstd frame carries no declared content size')
+  return declared
+}
+
+/** Compressed artifacts above this size are decoded as a stream, on restore and on ingest. */
+const STREAM_DECODE_FROM = 4 * 1024 * 1024
+
+/** Collect a byte stream; only ever used where the seam wants bytes. */
+async function bytesOf(stream: ReadableStream<Uint8Array>): Promise<Uint8Array> {
+  return new Uint8Array(await new Response(stream).arrayBuffer())
+}
+
+/**
+ * Bun's `CompressionStream` types do not satisfy `pipeThrough`'s pair
+ * (its readable side is typed `NonSharedUint8Array`); the runtime object
+ * is a plain byte transform.
+ */
+const zstdEncoder = (): TransformStream<Uint8Array, Uint8Array> =>
+  new CompressionStream('zstd') as unknown as TransformStream<Uint8Array, Uint8Array>
+
+const oneChunk = (bytes: Uint8Array): ReadableStream<Uint8Array> =>
+  new ReadableStream({
+    start(c) {
+      c.enqueue(bytes)
+      c.close()
+    },
+  })
+
+/**
+ * The decoded tar as a stream: one call for a small artifact that
+ * declares its size, a streamed decode otherwise — the stream setup is
+ * ~35 µs, which matters at a thousand one-file artifacts and nowhere
+ * else. Bytes in memory are only ever the small case (a large source
+ * must be a FILE: a Blob copies its bytes and hands the decoder
+ * everything at once, measured +519 MiB on 150 MiB against +448 for the
+ * plain decode). The 2 GiB ceiling applies either way: the declaration
+ * and the result length in one call, a running count on the stream.
+ */
+async function decodedTar(
+  source: Uint8Array | Bun.BunFile,
+  hash: string,
+): Promise<ReadableStream<Uint8Array>> {
+  if (source instanceof Uint8Array) {
+    if (assertDeclaredSize(source, hash) === null) return zstdDecodeStream(new Blob([source]), hash)
+    return oneChunk(await zstdDecompressBounded(source, hash))
   }
-  const out = await Bun.zstdDecompress(compressed)
-  if (out.length > MAX_DECOMPRESSED_ARTIFACT_BYTES) {
-    throw new CorruptArtifactError(
-      hash,
-      `decompressed to ${out.length} bytes (> ${MAX_DECOMPRESSED_ARTIFACT_BYTES} cap)`,
-    )
+  if (source.size <= STREAM_DECODE_FROM) {
+    const bytes = await source.bytes()
+    if (assertDeclaredSize(bytes, hash) === null) return zstdDecodeStream(source, hash)
+    return oneChunk(await zstdDecompressBounded(bytes, hash))
   }
-  return out
+  assertDeclaredSize(await source.slice(0, 32).bytes(), hash)
+  return zstdDecodeStream(source, hash)
+}
+
+/**
+ * The streaming twin of `zstdDecompressBounded`: the decoded bytes as a
+ * stream, refused past the same ceiling. A malicious frame cannot expand
+ * past the cap here either — the count runs as bytes are produced, before
+ * any of them reach the reader's next entry.
+ */
+function zstdDecodeStream(source: Blob, hash: string): ReadableStream<Uint8Array> {
+  let total = 0
+  return source
+    .stream()
+    .pipeThrough(new DecompressionStream('zstd'))
+    .pipeThrough(
+      new TransformStream<Uint8Array, Uint8Array>({
+        transform(chunk, controller) {
+          total += chunk.byteLength
+          if (total > MAX_DECOMPRESSED_ARTIFACT_BYTES) {
+            controller.error(
+              new CorruptArtifactError(
+                hash,
+                `decompresses past ${MAX_DECOMPRESSED_ARTIFACT_BYTES} bytes (cap)`,
+              ),
+            )
+            return
+          }
+          controller.enqueue(chunk)
+        },
+      }),
+    )
 }
 
 export interface CacheLayer {
+  /**
+   * The local handle this layer wraps, when it wraps one (`LayeredCache`).
+   * `resolveCache` uses it to drop a bare local layer another declared layer
+   * already contains, so `[cloud(), localCachePlugin()]` does not write the
+   * local store twice.
+   */
+  readonly local?: Cache | undefined
+  /**
+   * `true` iff a REMOTE cache sits behind this layer. THE answer to "can
+   * the remote axes of the cache policy do anything on this run?" — the
+   * orchestrator clamps `remoteRead`/`remoteWrite` off when it is absent,
+   * skips the up-front local classify when it is present (that classify's
+   * `cache.get` would be a remote read-through awaited before scheduling),
+   * and drives the prefetch pass off it.
+   *
+   * A layer must answer TRUTHFULLY: identity against the local cache
+   * ("something other than the handle I passed in") is NOT the same
+   * question — an ordinary pass-through decorator with no remote at all
+   * answers yes to it. `LayeredCache` sets it, a bare `Cache` denies it,
+   * and a third-party layer opts in when, and only when, it really has a
+   * remote. Optional so a layer written before this contract keeps
+   * type-checking; absent reads as "no remote", the safe answer.
+   */
+  readonly hasRemote?: boolean
+  /**
+   * Batch existence probe over the remote — the subset of `hashes` stored
+   * remotely, in ONE round-trip, or `null` for "no batch info; use
+   * per-hash". Only meaningful with `hasRemote`; a remote layer that can't
+   * batch omits it and the prefetch pass falls back to per-hash GETs.
+   */
+  remoteHasMany?(hashes: readonly string[]): Promise<Set<string> | null>
+  /**
+   * Record that the remote has NO artifact for each of `hashes` (from a
+   * batch probe), so a later `get`/`prefetch` short-circuits to a miss with
+   * no round-trip. Only meaningful with `hasRemote`.
+   */
+  markRemoteAbsent?(hashes: Iterable<string>): void
+  /**
+   * Resolve once every background write-through upload settles. The
+   * orchestrator awaits it before `close()` — an upload reading layer state
+   * after close would race. Only meaningful with `hasRemote`; a layer that
+   * uploads synchronously (or not at all) omits it.
+   */
+  drainUploads?(): Promise<void>
   key(input: CacheKeyInput): Promise<string>
   get(hash: string, ctx?: CacheGetContext): Promise<CacheEntry | null>
+  /**
+   * Optional batched `get` (same answers, fewer round trips). The
+   * short-circuit probe uses it when a layer offers one; a layer without it
+   * is probed hash by hash.
+   */
+  getMany?(hashes: readonly string[]): Promise<Map<string, CacheEntry>>
   /**
    * Lightweight existence probe. `'local'` / `'remote'` names the layer
    * that holds the artifact; `null` is a miss. NEVER moves bytes: no
@@ -583,6 +855,19 @@ export interface CacheLayer {
    * restore.
    */
   isOutputsCurrent(projectDir: string, expected: readonly OutputFileRow[]): Promise<boolean>
+  /**
+   * The directory-mtime short-circuit behind a warm hit (optional — a layer
+   * without it keeps the output walk). `recordOutputDirs` snapshots every
+   * directory under each of `prefixes` (project-relative, whole-subtree
+   * globs only — see `wholeSubtreePrefixes`) after a save or restore;
+   * `loadOutputDirsBatch` reads them back; `outputDirsCurrent` is true iff
+   * every recorded directory still carries its recorded mtime, which proves
+   * no file was added or removed anywhere the glob could see. Machine-local
+   * state, like the output rows: a remote ingest records none.
+   */
+  recordOutputDirs?(hash: string, projectDir: string, prefixes: readonly string[]): Promise<void>
+  loadOutputDirsBatch?(hashes: readonly string[]): Map<string, OutputDirRow[]>
+  outputDirsCurrent?(projectDir: string, rows: readonly OutputDirRow[]): Promise<boolean>
   /**
    * Extract the artifact's `outputs/` entries into `projectDir` and —
    * when `workspaceRoot` is given — its `workspace-outputs/` entries
@@ -592,9 +877,25 @@ export interface CacheLayer {
   restoreOutputs(hash: string, projectDir: string, workspaceRoot?: string): Promise<void>
   save(args: {
     hash: string
-    entry: Omit<CacheEntry, 'hash' | 'storedAt' | 'outputFiles'>
+    /**
+     * `exitCode` is deliberately NOT accepted: vx caches only successes, so
+     * the stored value is pinned to 0 and there is nothing for a caller to
+     * decide. Accepting a number and discarding it invited the one shape that
+     * launders a failure into a success — cache a failing task's outputs, read
+     * the entry back as exit 0, and the hit classifies `cache-hit` while the
+     * broken build's files are restored over a good tree. Unrepresentable
+     * beats guarded.
+     */
+    entry: Omit<CacheEntry, 'hash' | 'storedAt' | 'outputFiles' | 'exitCode'>
     projectDir: string
     outputFiles: string[]
+    /**
+     * Set only by ChainedCache when an EARLIER layer in the chain already
+     * wrote this artifact to the same local handle: the local pack + write
+     * is skipped and only the layer's remote side acts. A layer with no
+     * remote side treats it as a full no-op.
+     */
+    skipLocalWrite?: boolean
     /**
      * Resolved `outputs.workspaceFiles` (absolute paths) + the root
      * they're relative to. Packed under `workspace-outputs/<rel>`.
@@ -636,7 +937,7 @@ export interface CacheLayer {
    * all-cache-hit run writes nothing.
    */
   recordRunBundle(bundle: { runs: readonly RunRecord[]; invocation: InvocationRecord }): void
-  stats(): CacheStats
+  stats(opts?: CacheStatsOptions): CacheStats
   /**
    * Content-hash a file with an mtime+size fast path. If the
    * `(mtime_ms, size_bytes)` of `filePath` match a previously seen
@@ -680,7 +981,25 @@ interface EntryRow {
   accessed_at: number
 }
 
+function entryOf(row: EntryRow, fileRows: OutputFileRow[]): CacheEntry {
+  return {
+    hash: row.hash,
+    taskId: `${row.project}#${row.task}`,
+    command: row.command,
+    exitCode: row.exit_code,
+    durationMs: row.duration_ms,
+    outputFiles: fileRows.map((r) => r.path),
+    outputRows: fileRows,
+    stdout: row.stdout,
+    storedAt: new Date(row.created_at).toISOString(),
+    source: 'local',
+  }
+}
+
 export class Cache implements CacheLayer {
+  /** This IS the local layer — there is nothing slower behind it. */
+  readonly hasRemote = false
+
   private readonly db: Database
   private readonly insertEntry: ReturnType<Database['prepare']>
   private readonly selectEntry: ReturnType<Database['prepare']>
@@ -692,7 +1011,11 @@ export class Cache implements CacheLayer {
   private readonly selectFileHash: ReturnType<Database['prepare']>
   private readonly upsertFileHash: ReturnType<Database['prepare']>
   private readonly insertOutputFile: ReturnType<Database['prepare']>
+  private readonly insertOutputDir: ReturnType<Database['prepare']>
+  private readonly deleteOutputDirs: ReturnType<Database['prepare']>
   private readonly deleteOutputFiles: ReturnType<Database['prepare']>
+  private readonly selectConfigEval: ReturnType<Database['prepare']>
+  private readonly insertConfigEval: ReturnType<Database['prepare']>
   /** Memoized repo object format for blob-OID hashing (lazy-detected). */
   private objectFormat: 'sha1' | 'sha256' | null = null
 
@@ -717,6 +1040,15 @@ export class Cache implements CacheLayer {
     // because callers use `new Cache(...)` directly; `mkdirSync` keeps
     // that property without a subprocess fork.
     mkdirSync(cacheDir, { recursive: true })
+    // Make the cache dir invisible to git, every time it is created: a
+    // `*` .gitignore inside it (the Cargo / Nx convention). Two reasons,
+    // both measured. A cache nobody ignored gets COMMITTED by the next
+    // `git add -A`; and vx's own `git status -uall` walks it — 1000
+    // artifacts doubled the enumeration on the bench workspace before
+    // its generator ignored `.vx`. An ignored directory is skipped by the
+    // walk entirely. Only written when absent, so a user's own file wins.
+    const ignore = path.join(cacheDir, '.gitignore')
+    if (!existsSync(ignore)) writeFileSync(ignore, '*\n')
     this.db = new Database(path.join(cacheDir, 'cache.db'), { create: true })
     this.db.exec('PRAGMA journal_mode = WAL')
     this.db.exec('PRAGMA synchronous = NORMAL')
@@ -744,7 +1076,7 @@ export class Cache implements CacheLayer {
       | undefined
     if (meta && meta.value !== SCHEMA_VERSION) {
       this.db.exec(
-        'DROP TABLE IF EXISTS entries; DROP TABLE IF EXISTS runs; DROP TABLE IF EXISTS file_hashes; DROP TABLE IF EXISTS output_files; DROP TABLE IF EXISTS invocations; DROP TABLE IF EXISTS run_task_inputs; DROP TABLE IF EXISTS entry_inputs;',
+        'DROP TABLE IF EXISTS entries; DROP TABLE IF EXISTS runs; DROP TABLE IF EXISTS file_hashes; DROP TABLE IF EXISTS output_files; DROP TABLE IF EXISTS invocations; DROP TABLE IF EXISTS run_task_inputs; DROP TABLE IF EXISTS entry_inputs; DROP TABLE IF EXISTS config_evals;',
       )
       this.db.prepare("UPDATE schema_meta SET value = ? WHERE key = 'version'").run(SCHEMA_VERSION)
     } else if (!meta) {
@@ -753,6 +1085,17 @@ export class Cache implements CacheLayer {
         .run(SCHEMA_VERSION)
     }
 
+    // Cached config evaluations (workspace/config-cache.ts): the validated
+    // config as JSON, keyed by everything the evaluation could observe. A
+    // separate exec so the artifact schema above stays byte-identical.
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS config_evals (
+        key        TEXT PRIMARY KEY,
+        json       TEXT NOT NULL,
+        created_at INTEGER NOT NULL
+      );
+    `)
+
     this.db.exec(`
       -- stdout/stderr live in the <hash>.tar.zst artifact, not here
       -- (v14+) — so they survive remote round-trips. The entries
@@ -772,6 +1115,8 @@ export class Cache implements CacheLayer {
       );
       CREATE TABLE IF NOT EXISTS runs (
         id                  INTEGER PRIMARY KEY AUTOINCREMENT,
+        -- '' when the outcome derived no cache key (skipped / persistent).
+        -- Every reader that must not mistake it for a key guards hash != ''.
         hash                TEXT NOT NULL,
         project             TEXT NOT NULL,
         task                TEXT NOT NULL,
@@ -794,7 +1139,12 @@ export class Cache implements CacheLayer {
         -- The direct within-run flaky signal.
         attempts            INTEGER
       );
-      CREATE INDEX IF NOT EXISTS runs_hash       ON runs(hash);
+      -- runs_hash had no reader: every consumer of runs.hash looks the row
+      -- up by run_id or (project, task) first. Dropped 2026-09-03 — it cost
+      -- 1,000 warm-run inserts 11.5 → 3.9 ms; the DROP sheds it from
+      -- existing databases (a schema-meta bump is for stored shapes, and
+      -- an index is not one).
+      DROP INDEX IF EXISTS runs_hash;
       CREATE INDEX IF NOT EXISTS runs_started_at ON runs(started_at);
       CREATE INDEX IF NOT EXISTS runs_project    ON runs(project, task);
       CREATE INDEX IF NOT EXISTS runs_ended      ON runs(ended_at);
@@ -808,6 +1158,8 @@ export class Cache implements CacheLayer {
         path         TEXT PRIMARY KEY,
         mtime_ms     INTEGER NOT NULL,
         size_bytes   INTEGER NOT NULL,
+        ctime_ms     INTEGER NOT NULL,
+        ino          INTEGER NOT NULL,
         content_hash TEXT NOT NULL,
         seen_at      INTEGER NOT NULL
       );
@@ -829,6 +1181,27 @@ export class Cache implements CacheLayer {
         PRIMARY KEY (entry_hash, path),
         FOREIGN KEY (entry_hash) REFERENCES entries(hash) ON DELETE CASCADE
       );
+      -- Every directory under a whole-subtree output glob, with its mtime
+      -- as of the last save/restore on THIS machine (2026-09-03). On a warm
+      -- hit, unchanged mtimes prove the output SET is unchanged, replacing
+      -- the glob walk that cost 0.36 ms per hit. Machine-local: a remote
+      -- ingest writes none, and the first hit after it walks and records.
+      -- Each config's ORDERED import closure (the config first), so a warm
+      -- load keys it by stat-hashing the list (the file_hashes memo) instead
+      -- of reading and scanning every file. Machine-local; pruned with
+      -- config_evals (2026-09-03).
+      CREATE TABLE IF NOT EXISTS config_closures (
+        config_path TEXT PRIMARY KEY,
+        files_json  TEXT NOT NULL,
+        created_at  INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS output_dirs (
+        entry_hash  TEXT NOT NULL,
+        path        TEXT NOT NULL,
+        mtime_ms    INTEGER NOT NULL,
+        PRIMARY KEY (entry_hash, path),
+        FOREIGN KEY (entry_hash) REFERENCES entries(hash) ON DELETE CASCADE
+      );
       -- v22 (Tier 3): one header row per vx-run invocation. The runs
       -- table is per-task; this is the per-invocation record that
       -- carries git/CI/host context, the command, tags, and run-level
@@ -928,14 +1301,16 @@ export class Cache implements CacheLayer {
       VALUES (?, ?, ?, ?)
     `)
     this.selectFileHash = this.db.prepare(
-      'SELECT mtime_ms, size_bytes, content_hash FROM file_hashes WHERE path = ?',
+      'SELECT mtime_ms, size_bytes, ctime_ms, ino, content_hash FROM file_hashes WHERE path = ?',
     )
     this.upsertFileHash = this.db.prepare(`
-      INSERT INTO file_hashes(path, mtime_ms, size_bytes, content_hash, seen_at)
-      VALUES (?, ?, ?, ?, ?)
+      INSERT INTO file_hashes(path, mtime_ms, size_bytes, ctime_ms, ino, content_hash, seen_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(path) DO UPDATE SET
         mtime_ms     = excluded.mtime_ms,
         size_bytes   = excluded.size_bytes,
+        ctime_ms     = excluded.ctime_ms,
+        ino          = excluded.ino,
         content_hash = excluded.content_hash,
         seen_at      = excluded.seen_at
     `)
@@ -948,20 +1323,89 @@ export class Cache implements CacheLayer {
         mtime_ms   = excluded.mtime_ms
     `)
     this.deleteOutputFiles = this.db.prepare('DELETE FROM output_files WHERE entry_hash = ?')
+    this.insertOutputDir = this.db.prepare(
+      'INSERT INTO output_dirs(entry_hash, path, mtime_ms) VALUES (?, ?, ?)',
+    )
+    this.deleteOutputDirs = this.db.prepare('DELETE FROM output_dirs WHERE entry_hash = ?')
+    this.selectConfigEval = this.db.prepare('SELECT json FROM config_evals WHERE key = ?')
+    this.insertConfigEval = this.db.prepare(
+      'INSERT OR REPLACE INTO config_evals(key, json, created_at) VALUES (?, ?, ?)',
+    )
+  }
+
+  /** `ConfigEvalStore`: a cached config evaluation, honouring the local READ axis. */
+  getConfigEval(key: string): string | null {
+    if (!this.read) return null
+    const row = this.selectConfigEval.get(key) as { json: string } | null
+    return row?.json ?? null
+  }
+
+  /** `ConfigEvalStore`: each config's ordered closure, one `IN` query per 900 paths. */
+  getConfigClosures(configPaths: readonly string[]): Map<string, string[]> {
+    const out = new Map<string, string[]>()
+    if (!this.read || configPaths.length === 0) return out
+    for (let i = 0; i < configPaths.length; i += 900) {
+      const chunk = configPaths.slice(i, i + 900)
+      const rows = this.db
+        .query(
+          `SELECT config_path, files_json FROM config_closures WHERE config_path IN (${chunk.map(() => '?').join(',')})`,
+        )
+        .all(...(chunk as readonly SQLQueryBindings[])) as Array<{
+        config_path: string
+        files_json: string
+      }>
+      for (const r of rows) out.set(r.config_path, JSON.parse(r.files_json) as string[])
+    }
+    return out
+  }
+
+  /** `ConfigEvalStore`: remember a config's ordered closure, honouring the local WRITE axis. */
+  putConfigClosure(configPath: string, files: readonly string[]): void {
+    if (!this.write) return
+    this.db
+      .prepare(
+        'INSERT INTO config_closures(config_path, files_json, created_at) VALUES (?, ?, ?) ON CONFLICT(config_path) DO UPDATE SET files_json = excluded.files_json, created_at = excluded.created_at',
+      )
+      .run(configPath, JSON.stringify(files), Date.now())
+  }
+
+  /** `ConfigEvalStore`: the batched read — one `IN` query per 900 keys, honouring the local READ axis. */
+  getConfigEvals(keys: readonly string[]): Map<string, string> {
+    const out = new Map<string, string>()
+    if (!this.read || keys.length === 0) return out
+    for (let i = 0; i < keys.length; i += 900) {
+      const chunk = keys.slice(i, i + 900)
+      const rows = this.db
+        .query(
+          `SELECT key, json FROM config_evals WHERE key IN (${chunk.map(() => '?').join(',')})`,
+        )
+        .all(...(chunk as readonly SQLQueryBindings[])) as Array<{ key: string; json: string }>
+      for (const r of rows) out.set(r.key, r.json)
+    }
+    return out
+  }
+
+  /** `ConfigEvalStore`: remember a validated evaluation, honouring the local WRITE axis. */
+  putConfigEval(key: string, json: string): void {
+    if (!this.write) return
+    this.insertConfigEval.run(key, json, Date.now())
   }
 
   /**
    * Content-hash a file (as a git blob OID, v20) with an mtime+size
    * fast path. If the `file_hashes` table has a row for `path` whose
-   * `(mtime_ms, size_bytes)` match the current stat, we reuse the
-   * stored content_hash (a memory + SQLite lookup, no disk read).
-   * Otherwise we read + hash + upsert.
+   * `(mtime_ms, size_bytes, ctime_ms, ino)` all match the current
+   * stat, we reuse the stored content_hash (a memory + SQLite lookup,
+   * no disk read). Otherwise we read + hash + upsert. All four fields
+   * are load-bearing — see the comment at the comparison.
    *
    * The OID is byte-identical to what `git hash-object` (and the git
    * index) computes for the same content, so this fallback and the
-   * `CacheKeyInput.fileHashes` index-OID fast path never diverge —
-   * a file's key contribution can't flip across dirty↔clean
-   * transitions.
+   * `CacheKeyInput.fileHashes` index-OID fast path agree on any file
+   * git stores verbatim. They do NOT agree when a clean filter
+   * (`text`/`eol`/`ident`) is active: the index blob is the filtered
+   * form while this hashes the worktree bytes, so `inputs.ts` drops
+   * the index OID for those paths and routes them here.
    */
   async hashFile(filePath: string): Promise<string> {
     // statSync intentional: a single stat is ~1.6µs (Bun 1.3); the
@@ -980,14 +1424,36 @@ export class Cache implements CacheLayer {
     }
     const mtimeMs = Math.floor(st.mtimeMs)
     const size = st.size
+    // ctime + ino are what make this memo SAFE, not merely fast. mtime is
+    // caller-settable, so (mtime, size) alone hands back the previous run's
+    // digest for genuinely different bytes whenever a producer preserves
+    // mtime — `tar -x`, `unzip`, `cp -p`, `rsync --times`, any
+    // SOURCE_DATE_EPOCH generator — which is a stale cache hit. `utimes`
+    // cannot suppress ctime without root, and an atomic write-then-rename
+    // changes the inode; git's own index keys on ctime+ino+dev for exactly
+    // this reason. Both fields come from the stat we already took.
+    const ctimeMs = Math.floor(st.ctimeMs)
+    const ino = Number(st.ino)
     const row = this.selectFileHash.get(filePath) as
-      | { mtime_ms: number; size_bytes: number; content_hash: string }
+      | {
+          mtime_ms: number
+          size_bytes: number
+          ctime_ms: number
+          ino: number
+          content_hash: string
+        }
       | undefined
-    if (row && row.mtime_ms === mtimeMs && row.size_bytes === size) {
+    if (
+      row &&
+      row.mtime_ms === mtimeMs &&
+      row.size_bytes === size &&
+      row.ctime_ms === ctimeMs &&
+      row.ino === ino
+    ) {
       return row.content_hash
     }
     const ch = await this.hashFileFromDisk(filePath)
-    this.upsertFileHash.run(filePath, mtimeMs, size, ch, Date.now())
+    this.upsertFileHash.run(filePath, mtimeMs, size, ctimeMs, ino, ch, Date.now())
     return ch
   }
 
@@ -1098,14 +1564,27 @@ export class Cache implements CacheLayer {
       }
     }
 
+    const pluginParts = input.pluginParts ?? []
+    if (pluginParts.length > 0) {
+      h = xxh3(`plugin:${pluginParts.length}`, h)
+      for (const [n, v] of pluginParts) h = xxh3(`${n}\0${v}`, h)
+      if (cap) {
+        for (const [n, v] of pluginParts) cap.push({ kind: 'plugin', name: n, hash: xxh3hex(v) })
+      }
+    }
+
     const sortedInputs = [...input.inputFiles].sort()
     h = xxh3(`inputs:${sortedInputs.length}`, h)
     // Per-file hash source, in preference order: the caller-supplied
     // index-OID map (clean tracked files — zero I/O), then hashFile's
-    // mtime+size memo (no read), then a full in-process blob-OID
-    // computation. All three produce identical bytes for identical
-    // content. The fold order is locked to `sortedInputs` so results
-    // are stable across runs.
+    // stat memo (no read), then a full in-process blob-OID computation.
+    // All three describe the WORKTREE bytes, which is what the task
+    // reads — the index-OID map is only populated for paths whose
+    // worktree form matches their index form, because a clean filter
+    // (`text`/`eol`/`ident`) makes the index blob a DIFFERENT sequence
+    // of bytes and folding it would let two distinct worktree contents
+    // share a key. The fold order is locked to `sortedInputs` so
+    // results are stable across runs.
     const fileHashes = await Promise.all(
       sortedInputs.map((f) => input.fileHashes?.get(f) ?? this.hashFile(f)),
     )
@@ -1128,6 +1607,23 @@ export class Cache implements CacheLayer {
     // Local reads disabled (e.g. `--force` / `--cache=local:w`): report a
     // miss so the task re-executes. The artifact + index are untouched.
     if (!this.read) return null
+    return await this.readEntry(hash)
+  }
+
+  /**
+   * Read an entry BYPASSING the local read gate. The gate means "don't
+   * serve hits out of the PRE-EXISTING local cache" — it must not throw
+   * away bytes this run just downloaded. `LayeredCache` calls this to
+   * deliver an artifact it ingested from the remote; under
+   * `--cache=local:,remote:rw` the gated `get` returned null for the row
+   * `ingest` had just written, so the task re-executed and re-uploaded on
+   * every single run.
+   */
+  async getIngested(hash: string): Promise<CacheEntry | null> {
+    return await this.readEntry(hash)
+  }
+
+  private async readEntry(hash: string): Promise<CacheEntry | null> {
     const row = this.selectEntry.get(hash) as EntryRow | undefined
     if (!row) return null
 
@@ -1147,18 +1643,45 @@ export class Cache implements CacheLayer {
     // for four up-to-date hits on ~70 MB binaries). restoreOutputs
     // reads the artifact itself, only when extraction actually runs.
     const fileRows = this.loadOutputFilesBatch([hash]).get(hash) ?? []
+    const entry = entryOf(row, fileRows)
+    entry.outputDirRows = this.loadOutputDirsBatch([hash]).get(hash) ?? []
+    return entry
+  }
 
-    return {
-      hash: row.hash,
-      taskId: `${row.project}#${row.task}`,
-      command: row.command,
-      exitCode: row.exit_code,
-      durationMs: row.duration_ms,
-      outputFiles: fileRows.map((r) => r.path),
-      stdout: row.stdout,
-      storedAt: new Date(row.created_at).toISOString(),
-      source: 'local',
+  /**
+   * `get` for many hashes at once: one `entries` query and one
+   * `output_files` query per chunk instead of two per hash, with the
+   * artifact-existence stats in flight together. Same answers as N calls
+   * to `get` — a hash whose artifact is gone is simply absent from the map.
+   * The up-front short-circuit probe is the caller; per-hit `get` stays for
+   * the lazy path.
+   */
+  async getMany(hashes: readonly string[]): Promise<Map<string, CacheEntry>> {
+    const out = new Map<string, CacheEntry>()
+    if (!this.read || hashes.length === 0) return out
+    const rows: EntryRow[] = []
+    for (let i = 0; i < hashes.length; i += 900) {
+      const chunk = hashes.slice(i, i + 900)
+      const placeholders = chunk.map(() => '?').join(',')
+      rows.push(
+        ...(this.db
+          .query(`SELECT * FROM entries WHERE hash IN (${placeholders})`)
+          .all(...(chunk as readonly SQLQueryBindings[])) as EntryRow[]),
+      )
+    }
+    if (rows.length === 0) return out
+    const present = await Promise.all(rows.map((r) => Bun.file(this.tarPath(r.hash)).exists()))
+    const live = rows.filter((_r, i) => present[i])
+    const liveHashes = live.map((r) => r.hash)
+    const fileRows = this.loadOutputFilesBatch(liveHashes)
+    const dirRows = this.loadOutputDirsBatch(liveHashes)
+    for (const row of live) {
+      this.touched.add(row.hash)
+      const entry = entryOf(row, fileRows.get(row.hash) ?? [])
+      entry.outputDirRows = dirRows.get(row.hash) ?? []
+      out.set(row.hash, entry)
     }
+    return out
   }
 
   // Existence probe: SQL row + artifact-on-disk check, no byte reads
@@ -1213,6 +1736,10 @@ export class Cache implements CacheLayer {
     // current; the on-disk tree under projectDir is whatever it was,
     // and nothing was supposed to land there.
     if (expected.length === 0) return true
+    // Promise-form stat, deliberately: statSync is ~2 µs against ~13 µs in
+    // isolation, but this runs under the scheduler's concurrency and the
+    // async form keeps the stats on the thread pool in parallel — the sync
+    // version measured slower on a 1000-hit warm run (2026-09-02).
     const results = await Promise.all(
       expected.map(async (e) => {
         try {
@@ -1243,8 +1770,101 @@ export class Cache implements CacheLayer {
     return this.tarPath(hash)
   }
 
+  /**
+   * Snapshot every directory under each of `prefixes` for `hash`. Called
+   * after a save and after a restore, when the tree is known to equal the
+   * entry's set. Symlinked directories are not descended (the output walk
+   * refuses them too). Over `OUTPUT_DIRS_CAP` directories, or on any
+   * error, the rows are cleared and the next hit keeps the walk.
+   */
+  async recordOutputDirs(
+    hash: string,
+    projectDir: string,
+    prefixes: readonly string[],
+  ): Promise<void> {
+    const rows: Array<[string, number]> = []
+    const walk = async (rel: string): Promise<boolean> => {
+      const abs = path.join(projectDir, rel)
+      let st
+      try {
+        st = await lstat(abs)
+      } catch {
+        return false
+      }
+      if (!st.isDirectory()) return false
+      rows.push([rel, st.mtimeMs])
+      if (rows.length > OUTPUT_DIRS_CAP) return false
+      let entries
+      try {
+        entries = await readdir(abs, { withFileTypes: true })
+      } catch {
+        return false
+      }
+      for (const e of entries) {
+        if (e.isDirectory() && !e.isSymbolicLink()) {
+          if (!(await walk(`${rel}/${e.name}`))) return false
+        }
+      }
+      return true
+    }
+    let ok = true
+    for (const prefix of prefixes) {
+      if (!(await walk(prefix))) {
+        ok = false
+        break
+      }
+    }
+    // All or nothing: a racy directory dropped alone would leave its
+    // parent trusted while an addition inside it bumps only the dropped one.
+    const youngest = Date.now() - OUTPUT_DIRS_RACY_MS
+    if (rows.some(([, mtime]) => mtime > youngest)) ok = false
+    this.db.transaction(() => {
+      this.deleteOutputDirs.run(hash)
+      if (!ok) return
+      for (const [rel, mtime] of rows) this.insertOutputDir.run(hash, rel, mtime)
+    })()
+  }
+
+  loadOutputDirsBatch(hashes: readonly string[]): Map<string, OutputDirRow[]> {
+    const out = new Map<string, OutputDirRow[]>()
+    if (hashes.length === 0) return out
+    const placeholders = hashes.map(() => '?').join(',')
+    const rows = this.db
+      .query(
+        `SELECT entry_hash, path, mtime_ms FROM output_dirs WHERE entry_hash IN (${placeholders})`,
+      )
+      .all(...(hashes as readonly SQLQueryBindings[])) as Array<{
+      entry_hash: string
+      path: string
+      mtime_ms: number
+    }>
+    for (const r of rows) {
+      const list = out.get(r.entry_hash)
+      const row = { path: r.path, mtimeMs: r.mtime_ms }
+      if (list) list.push(row)
+      else out.set(r.entry_hash, [row])
+    }
+    return out
+  }
+
+  /** True iff every recorded directory exists with its recorded mtime (ms). Same forged-mtime trade as the file check. */
+  async outputDirsCurrent(projectDir: string, rows: readonly OutputDirRow[]): Promise<boolean> {
+    if (rows.length === 0) return false
+    const results = await Promise.all(
+      rows.map(async (r) => {
+        try {
+          const st = await stat(path.join(projectDir, r.path))
+          return st.isDirectory() && Math.abs(st.mtimeMs - r.mtimeMs) < 1
+        } catch {
+          return false
+        }
+      }),
+    )
+    return results.every(Boolean)
+  }
+
   async restoreOutputs(hash: string, projectDir: string, workspaceRoot?: string): Promise<void> {
-    // In-process tar extraction — no fork+exec on the hot path
+    // In-process extraction — no fork+exec on the hot path
     // (~5-10ms reclaimed per hit vs the prior subprocess `tar -xf`).
     //
     // The "tree is already current" skip-everything check happens at
@@ -1256,52 +1876,60 @@ export class Cache implements CacheLayer {
     // path — they're surfaced via `get()` for the orchestrator to
     // replay through the logger.
     const src = this.tarPath(hash)
-    if (!(await Bun.file(src).exists())) return
-    const compressed = await Bun.file(src).bytes()
-    // Local artifact (already validated at ingest): trusted, so a missing
-    // declared size is allowed; the oversize ceiling still applies.
-    const tarBytes = await zstdDecompressBounded(compressed, hash, true)
-
-    const headers = parseTarHeaders(tarBytes)
-    if (
-      !headers.some(
-        (h) => h.name.startsWith('outputs/') || h.name.startsWith(WORKSPACE_OUTPUT_PREFIX),
-      )
-    ) {
-      return
+    // The caller already committed to this hit and WIPED the declared
+    // outputs, so returning quietly here would report a green cache hit over
+    // an emptied output tree. The artifact existed when `get()` probed it, so
+    // its absence now means something removed it underneath us (a concurrent
+    // `vx cache prune` is the documented way) — fail loud; the task re-runs.
+    if (!(await Bun.file(src).exists())) {
+      throw new CorruptArtifactError(hash, 'artifact file vanished before restore')
+    }
+    // The index says exactly which files this entry materializes. If the
+    // archive cannot produce one of them, restoring "successfully" leaves a
+    // hole that no later run detects: the skip-restore check compares the
+    // same truncated expectation against the same truncated tree and agrees
+    // forever. Refuse instead of silently under-restoring — checked before
+    // anything is renamed into place.
+    const rows = this.loadOutputFilesBatch([hash]).get(hash) ?? []
+    const expected = rows
+      .filter((r) => workspaceRoot !== undefined || !r.path.startsWith(WORKSPACE_OUTPUT_PREFIX))
+      .map((r) => (r.path.startsWith(WORKSPACE_OUTPUT_PREFIX) ? r.path : `outputs/${r.path}`))
+    const verify = (provided: ReadonlySet<string>): void => {
+      const missing = expected.filter((name) => !provided.has(name))
+      if (missing.length > 0) {
+        throw new CorruptArtifactError(
+          hash,
+          `artifact is missing ${missing.length} recorded output(s): ${missing.slice(0, 3).join(', ')}`,
+        )
+      }
     }
 
-    await extractOutputs(tarBytes, projectDir, workspaceRoot)
-
-    // Re-sync restored files' mtimes to the manifest rows (extract set
-    // them from the tar's SECOND-precision headers). After this, disk
-    // matches the rows at millisecond precision, so isOutputsCurrent
-    // compares exactly — and any later edit moves the mtime off the
-    // recorded historical value and is detected.
-    const rows = this.loadOutputFilesBatch([hash]).get(hash)
-    if (rows !== undefined) {
-      await Promise.all(
-        rows.map(async (r) => {
-          try {
-            const abs = r.path.startsWith(WORKSPACE_OUTPUT_PREFIX)
-              ? path.join(workspaceRoot ?? projectDir, r.path.slice(WORKSPACE_OUTPUT_PREFIX.length))
-              : path.join(projectDir, r.path)
-            const t = r.mtimeMs / 1000
-            await utimes(abs, t, t)
-          } catch {
-            // File absent from this extract (or unwritable) — the next
-            // probe simply restores again; never fail a hit over mtimes.
-          }
-        }),
-      )
+    // One tar reader and one extractor either way; only the decode differs
+    // by size. A large artifact is decoded and read as it streams, so the
+    // restore costs a chunk of memory, not 4× the artifact (measured
+    // 2026-09-03 on 150 MiB: +644 MiB in memory, +49 MiB streamed, same
+    // wall time). A small one is decoded in one call: the stream setup
+    // costs ~35 µs per artifact, which is 4% of the headline restore row
+    // when every artifact is a one-file `dist/` (measured: 390 vs 355 ms
+    // per 1 000). The local artifact was validated at ingest, so a missing
+    // declared size is allowed; the output ceiling applies to both.
+    try {
+      const tar = await decodedTar(Bun.file(src), hash)
+      await extractArtifactStream(tar, projectDir, workspaceRoot, verify)
+    } catch (err) {
+      if (err instanceof ArchiveSecurityError || err instanceof CorruptArtifactError) throw err
+      throw new CorruptArtifactError(hash, 'artifact is not a readable archive', err)
     }
   }
 
   async save(args: {
     hash: string
-    entry: Omit<CacheEntry, 'hash' | 'storedAt' | 'outputFiles'>
+    /** See `CacheLayer.save` — `exitCode` is not a caller's to supply. */
+    entry: Omit<CacheEntry, 'hash' | 'storedAt' | 'outputFiles' | 'exitCode'>
     projectDir: string
     outputFiles: string[]
+    /** See `CacheLayer.save`. */
+    skipLocalWrite?: boolean
     workspaceOutputFiles?: string[]
     workspaceRoot?: string
     inputComponents?: readonly TaskInputRow[]
@@ -1324,23 +1952,17 @@ export class Cache implements CacheLayer {
     // still uploads to remote — it calls `packArtifact` itself to get
     // the bytes, since there's no local artifact to read off disk.
     if (!this.write) return
-    const compressed = await this.packArtifact(args)
-    await this.writeArtifactAndIndex(
-      args.hash,
-      compressed,
-      {
-        taskId: args.entry.taskId,
-        command: args.entry.command,
-        durationMs: args.entry.durationMs,
-        ...(args.inputComponents !== undefined ? { inputComponents: args.inputComponents } : {}),
-      },
-      // Save-path rows get millisecond mtimes from a fresh stat (tar
-      // headers carry only seconds) — see the row loop for the guard.
-      {
-        projectDir: args.projectDir,
-        ...(args.workspaceRoot !== undefined ? { workspaceRoot: args.workspaceRoot } : {}),
-      },
-    )
+    if (args.skipLocalWrite === true) return
+    await mkdir(this.cacheDir, { recursive: true })
+    const endPack = span('save: pack')
+    const compressed = await this.packArtifactToTemp(this.tempPath(args.hash), args)
+    endPack()
+    await this.writeArtifactAndIndex(args.hash, compressed, {
+      taskId: args.entry.taskId,
+      command: args.entry.command,
+      durationMs: args.entry.durationMs,
+      ...(args.inputComponents !== undefined ? { inputComponents: args.inputComponents } : {}),
+    })
   }
 
   /**
@@ -1366,179 +1988,199 @@ export class Cache implements CacheLayer {
   }
 
   /**
-   * Stage stdout + outputs, tar them, zstd-compress, return the bytes.
-   * No disk write to the final cache path — that's the index step's
-   * job. Pure transform, so `ingest()` can skip this and just hand its
-   * remote-supplied bytes straight to `writeArtifactAndIndex`.
+   * Collect stdout + outputs into artifact bytes, zstd-compress, return
+   * them. No disk write to the final cache path — that's the index
+   * step's job. Pure transform, so `ingest()` can skip this and hand
+   * its remote-supplied bytes straight to `writeArtifactAndIndex`.
+   *
+   * Entries are named directly into the archive, so there is no staging
+   * copy of every output byte and no `tar` subprocess (see
+   * `archive.ts`).
+   */
+  /** Archive name → absolute source path for every declared output. */
+  private outputsOf(args: {
+    projectDir: string
+    outputFiles: string[]
+    workspaceOutputFiles?: string[]
+    workspaceRoot?: string
+  }): Map<string, string> {
+    const outputs = new Map<string, string>()
+    for (const f of args.outputFiles) {
+      outputs.set(`outputs/${path.relative(args.projectDir, f)}`, f)
+    }
+    // Caller passes workspaceRoot whenever workspaceOutputFiles is
+    // non-empty; the rels are root-anchored by construction.
+    for (const f of args.workspaceOutputFiles ?? []) {
+      outputs.set(`${WORKSPACE_OUTPUT_PREFIX}${path.relative(args.workspaceRoot!, f)}`, f)
+    }
+    return outputs
+  }
+
+  /**
+   * The compressed artifact, in memory: the remote upload when local
+   * writes are off. A large artifact is packed and compressed as a
+   * stream and collected — the seam takes bytes.
    */
   private async packArtifact(args: {
-    hash: string
-    entry: Omit<CacheEntry, 'hash' | 'storedAt' | 'outputFiles'>
+    entry: Omit<CacheEntry, 'hash' | 'storedAt' | 'outputFiles' | 'exitCode'>
     projectDir: string
     outputFiles: string[]
     workspaceOutputFiles?: string[]
     workspaceRoot?: string
   }): Promise<Uint8Array> {
-    const wsOutputFiles = args.workspaceOutputFiles ?? []
-    const stage = await mkdtemp(path.join(os.tmpdir(), 'vx-save-'))
+    // stdout is ALWAYS present in the artifact, even if empty, so the
+    // layout is predictable: a successful read finds `stdout` and
+    // zero-or-more `outputs/<rel>` / `workspace-outputs/<rel>` entries.
+    const plan = await planArtifact({
+      stdout: args.entry.stdout ?? '',
+      outputs: this.outputsOf(args),
+    })
+    if (plan.size <= STREAM_DECODE_FROM)
+      return await Bun.zstdCompress(await packArtifactBytes(plan))
+    return await bytesOf(packArtifactStream(plan).pipeThrough(zstdEncoder()))
+  }
+
+  /**
+   * Pack for the local save. A large artifact is read from disk as it is
+   * written and compressed as a stream straight into the temp, so it
+   * never sits in memory (measured 2026-09-03 on a 150 MiB output: +705
+   * MiB before). The streamed compressor is ~2.4× the one-call cost per
+   * byte and a stream costs ~35 µs to set up, so a small artifact is
+   * packed in memory and compressed in one call — returned as bytes,
+   * nothing written yet.
+   */
+  private async packArtifactToTemp(
+    tmpPath: string,
+    args: Parameters<Cache['packArtifact']>[0],
+  ): Promise<Uint8Array | { tmpPath: string }> {
+    const plan = await planArtifact({
+      stdout: args.entry.stdout ?? '',
+      outputs: this.outputsOf(args),
+    })
+    if (plan.size <= STREAM_DECODE_FROM)
+      return await Bun.zstdCompress(await packArtifactBytes(plan))
+    const sink = Bun.file(tmpPath).writer()
     try {
-      if (args.outputFiles.length > 0) {
-        const stageOutputs = path.join(stage, 'outputs')
-        await Promise.all(
-          args.outputFiles.map(async (f) => {
-            const rel = path.relative(args.projectDir, f)
-            const dest = path.join(stageOutputs, rel)
-            // Bun.write creates parent dirs as needed.
-            await Bun.write(dest, Bun.file(f))
-          }),
-        )
-      }
-      if (wsOutputFiles.length > 0) {
-        // Caller passes workspaceRoot whenever workspaceOutputFiles is
-        // non-empty; the rels are root-anchored by construction.
-        const stageWs = path.join(stage, 'workspace-outputs')
-        await Promise.all(
-          wsOutputFiles.map(async (f) => {
-            const rel = path.relative(args.workspaceRoot!, f)
-            await Bun.write(path.join(stageWs, rel), Bun.file(f))
-          }),
-        )
-      }
-      // stdout is ALWAYS present in the artifact, even if empty, so the
-      // archive layout is predictable: a successful read finds `stdout`
-      // and zero-or-more `outputs/<rel>` / `workspace-outputs/<rel>`
-      // entries.
-      await Bun.write(path.join(stage, 'stdout'), args.entry.stdout ?? '')
-
-      const topLevel: string[] = ['stdout']
-      if (wsOutputFiles.length > 0) topLevel.unshift('workspace-outputs')
-      if (args.outputFiles.length > 0) topLevel.unshift('outputs')
-
-      // `--format=ustar` forces strict POSIX ustar — no PAX extended-
-      // header records. BSD tar (macOS default) emits PAX per entry
-      // by default for xattrs / mtime-nanos; those records would
-      // otherwise show up as junk `PaxHeaders/<name>` entries in our
-      // restored trees. GNU tar also accepts the flag (no-op on its
-      // side). Names > 100 chars still work via ustar's prefix+name
-      // (255 chars) or GNU longname fallback if the tar binary
-      // chooses to emit one.
-      const proc = Bun.spawn(['tar', '--format=ustar', '-cf', '-', '-C', stage, ...topLevel], {
-        stdout: 'pipe',
-        stderr: 'pipe',
-        // COPYFILE_DISABLE blocks Apple's copyfile() from attaching
-        // xattrs to staged files via inherited child copies; tar then
-        // has nothing to emit AppleDouble for.
-        env: { ...process.env, COPYFILE_DISABLE: '1' },
-      })
-      const [tarBytes, stderrText] = await Promise.all([
-        new Response(proc.stdout).bytes(),
-        new Response(proc.stderr).text(),
-      ])
-      await proc.exited
-      if (proc.exitCode !== 0) {
-        throw new Error(`save: tar exited ${proc.exitCode}: ${stderrText.trim()}`)
+      for await (const chunk of packArtifactStream(plan).pipeThrough(zstdEncoder())) {
+        await sink.write(chunk)
       }
-      return await Bun.zstdCompress(tarBytes)
-    } finally {
-      await rm(stage, { recursive: true, force: true })
+    } catch (err) {
+      // An output that vanished or changed shape between the plan's stat
+      // and its read: the partial temp must not outlive the failure.
+      await sink.end()
+      await unlink(tmpPath).catch(() => undefined)
+      throw err
     }
+    await sink.end()
+    return { tmpPath }
   }
 
   /**
-   * Atomically write `compressed` to `<hash>.tar.zst` and (re)build
-   * the entries + output_files SQL rows from the tar headers. Shared
-   * by `save()` (we just packed the bytes) and `ingest()` (we got
-   * them from the remote layer).
+   * Atomically write `compressed` to `<hash>.tar.zst` and (re)build the
+   * entries + output_files SQL rows from the archive itself. Shared by
+   * `save()` (we just packed the bytes) and `ingest()` (we got them from
+   * the remote layer) — both index the identical values, because both
+   * read them out of the artifact.
    */
+  /** tmp suffix mixes pid + hrtime + a random hex chunk so two saves of
+   *  the same hash from the same process (or from two forked workers that
+   *  happen to share a wall-clock ms) don't pick the same tmp filename and
+   *  race on the rename. */
+  private tempPath(hash: string): string {
+    return `${this.tarPath(hash)}.tmp-${process.pid}-${process.hrtime.bigint()}-${Math.random().toString(36).slice(2, 10)}`
+  }
+
   private async writeArtifactAndIndex(
     hash: string,
-    compressed: Uint8Array,
+    compressed: Uint8Array | { tmpPath: string },
     meta: IngestMeta,
-    statBase?: { projectDir: string; workspaceRoot?: string },
   ): Promise<void> {
     // Validate BEFORE anything touches the final path. `ingest()` feeds
     // us network bytes; a truncated/garbage body that went live first
     // would leave a corrupt `<hash>.tar.zst` behind (with no SQL row,
     // since the decompress throw aborted indexing) for every later
     // reader to trip over. Decompress + parse also produce the
-    // `output_files` rows: same headers extractOutputs will see on
+    // `output_files` rows: same headers the restore will see on
     // restore, so the size/mode/mtime fingerprint we store matches
     // what isOutputsCurrent will compare against post-restore.
-    let tarBytes: Uint8Array
+    const finalPath = this.tarPath(hash)
+    let tmpPath: string
+    if (compressed instanceof Uint8Array) {
+      tmpPath = this.tempPath(hash)
+      await mkdir(this.cacheDir, { recursive: true })
+      // The temp is written BEFORE validation so a large artifact can be
+      // scanned from the file as it decodes — a file stream reads in
+      // bounded pieces; the bytes in memory would not (see `decodedTar`).
+      // The final path is still untouched until the archive has passed.
+      // node's writeFile, not Bun.write: the latter copies the buffer first
+      // (measured on 150 MiB: +151 MiB and 33 ms against +0 and 21 ms).
+      const endWrite = span('save: write temp')
+      await writeFile(tmpPath, compressed)
+      endWrite()
+    } else {
+      // `save` already streamed the artifact into its temp.
+      tmpPath = compressed.tmpPath
+    }
+    let scanned: Awaited<ReturnType<typeof scanArtifact>>
     try {
       // ingest() is the UNTRUSTED boundary — `compressed` is bytes just
       // pulled from a remote. Refuse a bomb (declared or sizeless) before it
       // can expand into memory.
-      tarBytes = await zstdDecompressBounded(compressed, hash, false)
+      const source =
+        compressed instanceof Uint8Array && compressed.byteLength <= STREAM_DECODE_FROM
+          ? compressed
+          : Bun.file(tmpPath)
+      const endScan = span('save: scan')
+      scanned = await scanArtifact(await decodedTar(source, hash))
+      endScan()
+      // v17 invariant: every artifact carries a `stdout` entry. Its
+      // absence means the bytes decompressed but aren't a vx artifact.
+      if (scanned.stdout === null) {
+        throw new CorruptArtifactError(hash, 'missing stdout entry')
+      }
     } catch (err) {
-      if (err instanceof CorruptArtifactError) throw err
-      throw new CorruptArtifactError(hash, 'zstd decompression failed', err)
-    }
-    const headers = parseTarHeaders(tarBytes)
-    // v17 invariant: every artifact carries a `stdout` entry. Its
-    // absence means the bytes decompressed but aren't a vx artifact.
-    if (!headers.some((h) => h.name === 'stdout' && !h.isDir)) {
-      throw new CorruptArtifactError(hash, 'missing stdout entry')
+      await unlink(tmpPath).catch(() => undefined)
+      if (err instanceof ArchiveSecurityError || err instanceof CorruptArtifactError) throw err
+      throw new CorruptArtifactError(hash, 'artifact is not a readable archive', err)
     }
-
-    const finalPath = this.tarPath(hash)
-    // tmp suffix mixes pid + hrtime + a random hex chunk so two saves
-    // of the same hash from the same process (or from two forked
-    // workers that happen to share a wall-clock ms) don't pick the
-    // same tmp filename and race on the rename.
-    const tmpPath = `${finalPath}.tmp-${process.pid}-${process.hrtime.bigint()}-${Math.random().toString(36).slice(2, 10)}`
-    await mkdir(this.cacheDir, { recursive: true })
-    await Bun.write(tmpPath, compressed)
+    const { entries } = scanned
     // POSIX rename atomically REPLACES the destination if it exists,
     // so we don't need a pre-rm. The pre-rm was actively harmful —
     // it opened a race window where writer B could delete writer A's
     // just-renamed file BEFORE A's subsequent stat, producing a
     // spurious ENOENT. The rename itself preserves the "either-or"
     // semantics for concurrent readers.
+    const endRename = span('save: rename')
     await rename(tmpPath, finalPath)
+    endRename()
 
-    const totalBytes = compressed.byteLength
+    const totalBytes =
+      compressed instanceof Uint8Array ? compressed.byteLength : Bun.file(finalPath).size
     const outputFileRows: Array<[string, number, number, number]> = []
     // Per-output-file fingerprint rows feed the skip-restore check.
     // Row paths: project entries store the bare rel (`outputs/`
     // stripped); workspace entries keep the full
     // `workspace-outputs/<rel>` name as the namespace discriminator.
-    for (const h of headers) {
-      if (h.isDir) continue
+    //
+    // Mode and MILLISECOND mtime come from the artifact's own sidecar
+    // (`.vx-meta.json`), written from a stat taken while packing. Both
+    // paths — save and remote ingest — therefore index the same values,
+    // and `restoreOutputs` materialises exactly them, so
+    // `isOutputsCurrent` compares equal at ms precision straight after a
+    // restore. (Tar headers carry seconds, which is why the save path
+    // used to need a second stat pass the ingest path could not have.)
+    for (const e of entries) {
       let rowPath: string | null = null
-      if (h.name.startsWith('outputs/')) {
-        const rel = h.name.slice('outputs/'.length)
+      if (e.name.startsWith('outputs/')) {
+        const rel = e.name.slice('outputs/'.length)
         if (rel.length > 0) rowPath = rel
-      } else if (h.name.startsWith(WORKSPACE_OUTPUT_PREFIX)) {
-        if (h.name.length > WORKSPACE_OUTPUT_PREFIX.length) rowPath = h.name
+      } else if (e.name.startsWith(WORKSPACE_OUTPUT_PREFIX)) {
+        if (e.name.length > WORKSPACE_OUTPUT_PREFIX.length) rowPath = e.name
       }
       if (rowPath === null) continue
-      let mtimeMs = Math.floor(h.mtimeMs)
-      // Save path only (ingest has no filesystem to consult): tar
-      // headers truncate mtimes to SECONDS, which is what made the
-      // skip-restore check blind to same-second same-size edits. A
-      // fresh stat refines the row to millisecond precision — but only
-      // when the size still matches the packed header, so the row
-      // always describes the ARTIFACT's bytes; a file mutated between
-      // pack and stat keeps the coarse header time (degraded, not
-      // wrong). restoreOutputs re-syncs disk mtimes to these rows.
-      if (statBase !== undefined) {
-        try {
-          const abs = rowPath.startsWith(WORKSPACE_OUTPUT_PREFIX)
-            ? path.join(
-                statBase.workspaceRoot ?? statBase.projectDir,
-                rowPath.slice(WORKSPACE_OUTPUT_PREFIX.length),
-              )
-            : path.join(statBase.projectDir, rowPath)
-          const st = await stat(abs)
-          if (st.size === h.size) mtimeMs = Math.floor(st.mtimeMs)
-        } catch {
-          // stat failed — keep the header-seconds fallback.
-        }
-      }
-      outputFileRows.push([rowPath, h.size, h.mode & 0o777, mtimeMs])
+      outputFileRows.push([rowPath, e.size, e.mode & 0o777, Math.floor(e.mtimeMs)])
     }
-    const stdoutText = readTarText(tarBytes, headers, 'stdout')
+    const stdoutText = scanned.stdout
 
     const [project, task] = splitTaskId(meta.taskId)
     const now = Date.now()
@@ -1559,7 +2201,12 @@ export class Cache implements CacheLayer {
         project,
         task,
         meta.command,
-        0, // exitCode: we never cache failures
+        // exitCode. Pinned, not supplied: vx caches only successes, and neither
+        // `save` nor `ingest` accepts one (see their arg types). The column
+        // stays because the READ side still defends against a non-zero value —
+        // a row from a foreign or hand-edited cache.db classifies the hit
+        // `failed` rather than laundering a broken build into a green run.
+        0,
         meta.durationMs,
         totalBytes,
         stdoutText,
@@ -1580,7 +2227,9 @@ export class Cache implements CacheLayer {
         }
       }
     })
+    const endTx = span('save: index tx')
     tx()
+    endTx()
   }
 
   /** Apply the deferred accessed_at bumps in one statement. */
@@ -1658,17 +2307,26 @@ export class Cache implements CacheLayer {
     })()
   }
 
-  stats(): CacheStats {
+  stats(opts: CacheStatsOptions = {}): CacheStats {
     this.flushAccessed()
+    const project = opts.project
+    const scoped = project !== undefined
+    const scopeParams: string[] = project === undefined ? [] : [project]
     const aggregate = this.db
-      .prepare('SELECT COUNT(*) AS n, COALESCE(SUM(size_bytes), 0) AS bytes FROM entries')
-      .get() as { n: number; bytes: number }
+      .prepare(
+        `SELECT COUNT(*) AS n, COALESCE(SUM(size_bytes), 0) AS bytes FROM entries${
+          scoped ? ' WHERE project = ?' : ''
+        }`,
+      )
+      .get(...scopeParams) as { n: number; bytes: number }
     const since = Date.now() - 24 * 60 * 60 * 1000
     const runs = this.db
       .prepare(
-        "SELECT COUNT(*) AS total, COALESCE(SUM(CASE WHEN status IN ('cache-hit', 'cache-hit-remote') THEN 1 ELSE 0 END), 0) AS hits FROM runs WHERE started_at >= ?",
+        `SELECT COUNT(*) AS total, COALESCE(SUM(CASE WHEN status IN ('cache-hit', 'cache-hit-remote') THEN 1 ELSE 0 END), 0) AS hits FROM runs WHERE started_at >= ? AND ${EXECUTED_RUNS_SQL}${
+          scoped ? ' AND project = ?' : ''
+        }`,
       )
-      .get(since) as { total: number; hits: number }
+      .get(since, ...scopeParams) as { total: number; hits: number }
     return {
       entryCount: aggregate.n,
       totalBytes: aggregate.bytes,
@@ -1747,15 +2405,34 @@ export class Cache implements CacheLayer {
     // executed task per invocation — a 2000-task repo accretes ~20k
     // rows in days, inflating insert and checkpoint cost forever.
     // 30 days comfortably covers `vx stats` (24 h windows) and any
-    // CI-side analytics consumers.
+    // CI-side analytics consumers. The `invocations` header table (one
+    // row per `vx run`) is pruned on the SAME window — otherwise a
+    // header would outlive its `runs` rows, so `vx info`/`vx last` would
+    // list an invocation whose task detail is already gone, and the
+    // table would grow unbounded on a long-lived checkout.
     try {
-      this.db
-        .prepare('DELETE FROM runs WHERE ended_at < ?')
-        .run(Date.now() - 30 * 24 * 60 * 60 * 1000)
+      const cutoff = Date.now() - 30 * 24 * 60 * 60 * 1000
+      this.db.prepare('DELETE FROM runs WHERE ended_at < ?').run(cutoff)
+      this.db.prepare('DELETE FROM invocations WHERE ended_at < ?').run(cutoff)
+      // A config that has not been loaded in 30 days was edited (its key
+      // moved) or its project left; either way the row is dead weight.
+      this.db.prepare('DELETE FROM config_evals WHERE created_at < ?').run(cutoff)
+      this.db.prepare('DELETE FROM config_closures WHERE created_at < ?').run(cutoff)
     } catch {
       // Retention is best-effort; never block closing the handle.
     }
-    this.flushAccessed()
+    try {
+      this.flushAccessed()
+    } catch {
+      // Same contract as the retention prune above, which was already
+      // guarded while this sibling was not: `accessed_at` is LRU
+      // bookkeeping, never correctness, and the run's results are
+      // already recorded by the time we get here. Letting it throw also
+      // SKIPPED `db.close()` below, leaking the handle. Reachable when
+      // the cache dir is removed under a live handle (a concurrent
+      // `rm -rf .vx/cache`): macOS answers SQLITE_IOERR_VNODE on a
+      // write to an unlinked file where Linux happily writes on.
+    }
     this.db.close()
   }
 
@@ -1771,7 +2448,9 @@ export class Cache implements CacheLayer {
  */
 function bindRun(run: RunRecord): SQLQueryBindings[] {
   return [
-    run.hash,
+    // The ONE place the no-key sentinel is applied, so the column's
+    // NOT NULL invariant can't be violated from a call site.
+    run.hash ?? '',
     run.project,
     run.task,
     run.status,