@vzn/vx 0.0.643 → 0.0.644

package/src/cache/cache.ts

@@ -49,7 +49,7 @@ import {
   utimesSync,
   writeFileSync,
 } from 'node:fs'
-import { readdir, rm, stat, unlink, writeFile } from 'node:fs/promises'
+import { chmod, lstat, mkdir, readdir, rm, stat, unlink, utimes, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 import { createArtifactTables, createTables, inHashes, lazyStatement } from './schema.js'
 import {
@@ -76,7 +76,12 @@ import {
   packArtifactBytes,
   packArtifactStream,
   planArtifact,
+  planOfTree,
+  sealTree,
+  treeIntact,
+  writeTree,
 } from './archive.js'
+import { readUmask, restoredMode } from './umask.js'
 import {
   ArtifactVanishedError,
   type CacheEntry,
@@ -119,7 +124,7 @@ import { behindLink } from './linked-inputs.js'
  * An artifact or temp file without an `entries` row is never reaped
  * younger than this: a crashed save's temp is stale long before it. A
  * row-less artifact may still be in use (another vx version's open dropped
- * its row), so past this it is judged by the retention policy, its file
+ * its row), so past this it is judged by the prune policy, its file
  * time standing for `accessed_at`. A hit renews a file time older than
  * this, so the file time trails the last use by at most this much, and
  * the policy reads the file time plus this as the last use.
@@ -137,7 +142,7 @@ const ADOPT_STATS = 64
  * A hit renews an entry's `accessed_at` only once it is older than this:
  * renewing every hit rewrote 2,180 rows at a warm 1,090-package run's
  * close, ~30 ms of it. So `accessed_at` trails the last use by at most
- * this much, and the retention policy reads it plus this as the last use:
+ * this much, and the prune policy reads it plus this as the last use:
  * an entry used within the limit is never pruned, and one may stay up to
  * this long past it (owner, 2026-10-08).
  */
@@ -150,7 +155,7 @@ const ACCESS_REFRESH_MS = 60 * 60 * 1000
  * directory), and the sweep once took any `*.tar.zst` an hour old there,
  * the user's own release tarball included (item 968).
  */
-const VX_ARTIFACT_NAME = /^([0-9a-f]{16})\.tar\.zst(\.tmp-\d+-\d+-[0-9a-z]*)?$/
+const VX_ARTIFACT_NAME = /^([0-9a-f]{16})\.(?:tar\.zst|tree)(\.tmp-\d+-\d+-[0-9a-z]*)?$/
 
 /** What vx writes in a cache directory besides its artifacts. */
 const VX_CACHE_NAMES = new Set([
@@ -186,8 +191,8 @@ export function vxCacheEntries(cacheDir: string): string[] {
   })
 }
 
-/** The `schema_meta` key holding when the orphan sweep last ran (ms epoch). */
-const SWEPT_AT = 'orphans_swept_at'
+/** What `vx cache clean` keeps of run history and the hash memos. */
+const HISTORY_RETENTION_MS = 30 * 24 * 60 * 60 * 1000
 
 export interface SchemaReset {
   from: string
@@ -295,7 +300,7 @@ function outOfFdsAtOpen(dbFile: string, err: unknown): UserError | undefined {
 //        output_files' ino + ctime_ms moved to the workspace's own
 //        output_stamps, output_dirs lost its foreign key, and the value
 //        salt moved to store_meta. The cache KEY is unchanged.
-//   v33: an artifact of at most INLINE_MAX compressed bytes lives in the
+//   v33: an artifact of at most 32 KiB compressed lives in the
 //        store's `artifacts` table, written in its rows' transaction, and
 //        every entry read joins it. The artifact bytes and the cache KEY are
 //        unchanged (CACHE_VERSION not bumped).
@@ -370,13 +375,6 @@ const ARTIFACT_TABLES = ['artifacts', 'artifacts_meta']
  */
 const ARTIFACT_LAYOUT = 'a2'
 
-/**
- * The largest compressed artifact kept in the index rather than in a file
- * of its own: it is written in its rows' transaction, with no temp and no
- * rename (docs/design/cache-save-cpu-2026-10.md).
- */
-const INLINE_MAX = 32 * 1024
-
 /**
  * An index that records a schema other than this vx's: the one an opener
  * that writes resets. Reads the recorded version alone and touches
@@ -509,8 +507,9 @@ async function scanOrphanFiles(
       const file = path.join(cacheDir, name)
       try {
         const st = await stat(file)
-        if (st.isFile() && st.mtimeMs <= cutoff) {
-          found.push({ file, size: st.size, mtimeMs: st.mtimeMs, temp })
+        if ((name.includes('.tree') ? st.isDirectory() : st.isFile()) && st.mtimeMs <= cutoff) {
+          const size = st.isDirectory() ? await treeBytes(file) : st.size
+          found.push({ file, size, mtimeMs: st.mtimeMs, temp })
         }
       } catch {
         // Gone between readdir and stat: not an orphan any more.
@@ -520,6 +519,16 @@ async function scanOrphanFiles(
   return found
 }
 
+/** The bytes a tree-form artifact's files hold. */
+async function treeBytes(dir: string): Promise<number> {
+  let n = 0
+  for (const e of await readdir(dir, { recursive: true, withFileTypes: true }).catch(() => [])) {
+    if (e.isFile())
+      n += (await stat(path.join(e.parentPath, e.name)).catch(() => ({ size: 0 }))).size
+  }
+  return n
+}
+
 /**
  * SQL predicate selecting `runs` rows that record an EXECUTION.
  *
@@ -613,7 +622,7 @@ function usageOfEntry(entry: { cpuMs?: number; peakRssBytes?: number }): ExecUsa
  * it there", and the ignore file is created exclusively instead of probed
  * first. An existing cache costs three calls; it cost six.
  */
-function openCacheDir(cacheDir: string, workspaceRoot?: string): string | null {
+function openCacheDir(cacheDir: string, workspaceRoot?: string, index = 'cache.db'): string | null {
   const [ignore, ignoreText] = ignoreFileFor(cacheDir)
   try {
     accessSync(cacheDir, constants.W_OK)
@@ -624,7 +633,7 @@ function openCacheDir(cacheDir: string, workspaceRoot?: string): string | null {
     return null
   }
   try {
-    accessSync(path.join(cacheDir, 'cache.db'), constants.W_OK)
+    accessSync(path.join(cacheDir, index), constants.W_OK)
   } catch (err) {
     const code = (err as NodeJS.ErrnoException).code
     // A FILE at `cacheDir` passed the `access` above; mkdir names it.
@@ -649,7 +658,7 @@ function storeBlocked(storeDir: string, storeRoot: string | null): string | null
         if (refused !== null) return refused
       }
     }
-    return openCacheDir(storeDir)
+    return openCacheDir(storeDir, undefined, 'store.db')
   } catch (err) {
     return errorText(err)
   }
@@ -788,6 +797,33 @@ function errorText(err: unknown): string {
   return err instanceof Error ? err.message : String(err)
 }
 
+/** A tree the save wrote from its own outputs, with the scan its tar would give. */
+interface SavedTree {
+  tree: string
+  scan: Awaited<ReturnType<typeof scanArtifact>>
+  bytes: number
+}
+
+/** How a save keeps an entry locally (`cache.store`). */
+export interface StoreOptions {
+  /**
+   * The largest entry kept in the index, as one zstd tar (fewer files to
+   * make): written in its rows' transaction, with no temp and no rename
+   * (docs/design/cache-save-cpu-2026-10.md). 0 keeps every entry as files.
+   */
+  embeddings: number
+  /** A file-backed entry is a `<hash>.tree` of plain files; off, one `<hash>.tar.zst`. */
+  decompress: boolean
+  /** What a tree restore checks first: each file's size and mtime, every byte, or nothing. */
+  verify: 'stat' | 'hash' | 'none'
+}
+
+export const DEFAULT_STORE: StoreOptions = {
+  embeddings: 32 * 1024,
+  decompress: true,
+  verify: 'stat',
+}
+
 /** What a run's background uploads moved: totals over the ones that landed. */
 export interface UploadTally {
   count: number
@@ -939,6 +975,7 @@ export class Cache implements CacheLayer {
      * records none (deleted, or never written beside a run's store).
      */
     storeRoot?: string | null,
+    private readonly store: StoreOptions = DEFAULT_STORE,
   ) {
     this.inspecting = mode !== 'open'
     this.read = localPolicy.read
@@ -1677,7 +1714,7 @@ export class Cache implements CacheLayer {
     } else {
       // Verify the artifact file actually exists. The DB and the
       // filesystem can drift if someone manually deletes the cache dir.
-      const st = statSync(this.tarPath(hash), { throwIfNoEntry: false })
+      const st = this.artifactStat(hash)
       if (st === undefined) return null
       if (st.mtimeMs < Date.now() - ORPHAN_GRACE_MS) this.staleTimes.add(hash)
     }
@@ -1717,7 +1754,7 @@ export class Cache implements CacheLayer {
       names = []
     }
     this.artifactNames ??= new Set(names)
-    return !names.some((n) => n.endsWith('.tar.zst'))
+    return !names.some((n) => n.endsWith('.tar.zst') || n.endsWith('.tree'))
   }
 
   /**
@@ -1766,7 +1803,7 @@ export class Cache implements CacheLayer {
         if (r.inline_at < graceStart) this.staleInline.add(r.hash)
         return true
       }
-      const st = statSync(this.tarPath(r.hash), { throwIfNoEntry: false })
+      const st = this.artifactStat(r.hash)
       if (st !== undefined && st.mtimeMs < graceStart) this.staleTimes.add(r.hash)
       return st !== undefined
     })
@@ -1811,7 +1848,7 @@ export class Cache implements CacheLayer {
   private storedHere(hash: string): boolean {
     const row = this.entryExists.get(hash) as { inline_at: number | null } | null
     if (row === null) return false
-    return row.inline_at !== null || existsSync(this.tarPath(hash))
+    return row.inline_at !== null || this.artifactStat(hash) !== undefined
   }
 
   // Local cache has no slower layer to warm from — prefetch is a no-op.
@@ -1886,9 +1923,120 @@ export class Cache implements CacheLayer {
     }
   }
 
+  /**
+   * Restore a tree-form entry: its files checked as `cache.store.verify`
+   * says, then copied (or cloned) out one by one where the outputs are
+   * absent, as on every restore after a clean. Anything else (a tree to
+   * restore into, a workspace output, a link) goes through the extractor
+   * the tar form uses, fed the tree packed back into its tar.
+   */
+  private async restoreTree(
+    hash: string,
+    tree: string,
+    rows: readonly OutputFileRow[],
+    projectDir: string,
+    workspaceRoot: string | undefined,
+    verify: (provided: ReadonlySet<string>) => void,
+    accept: ((name: string) => boolean) | undefined,
+  ): Promise<void> {
+    const files = rows.filter((r) => !r.path.endsWith('/') && r.mode !== LINK_MODE)
+    let bytes = 0
+    for (const r of files) bytes += r.size
+    if (bytes > this.artifactCeiling) {
+      throw new CorruptArtifactError(
+        hash,
+        `its outputs hold ${formatBytes(bytes)}, past the ${formatBytes(this.artifactCeiling)} artifact ceiling`,
+      )
+    }
+    if (this.store.verify === 'stat') {
+      const changed = await Promise.all(
+        files.map((r) =>
+          stat(path.join(tree, treeName(r.path))).then(
+            (st) => st.size !== r.size || Math.floor(st.mtimeMs) !== r.mtimeMs,
+            () => true,
+          ),
+        ),
+      )
+      if (changed.includes(true)) {
+        throw new CorruptArtifactError(hash, 'a stored file changed since it was saved')
+      }
+    } else if (this.store.verify === 'hash' && !(await treeIntact(tree, this.stdoutText(hash)))) {
+      throw new CorruptArtifactError(hash, 'the stored files no longer sum to what was saved')
+    }
+    if (await this.copyTree(tree, rows, files, projectDir, accept)) return
+    await extractArtifactStream(
+      packArtifactStream(planOfTree(tree, this.stdoutText(hash))),
+      projectDir,
+      workspaceRoot,
+      verify,
+      accept,
+      workspaceRoot,
+    )
+  }
+
+  /** The copy-out: false, having written nothing, where it is not the case it serves. */
+  private async copyTree(
+    tree: string,
+    rows: readonly OutputFileRow[],
+    files: readonly OutputFileRow[],
+    projectDir: string,
+    accept: ((name: string) => boolean) | undefined,
+  ): Promise<boolean> {
+    const tops = new Set<string>()
+    for (const r of rows) {
+      if (r.path.startsWith(WORKSPACE_OUTPUT_PREFIX) || r.mode === LINK_MODE) return false
+      if (accept !== undefined && !r.path.endsWith('/') && !accept(`outputs/${r.path}`))
+        return false
+      tops.add(r.path.split('/')[0]!)
+    }
+    const held = await Promise.all(
+      [...tops].map((t) =>
+        lstat(path.join(projectDir, t)).then(
+          () => true,
+          () => false,
+        ),
+      ),
+    )
+    if (held.includes(true)) return false
+    readUmask()
+    const plain = restoredMode(0o666)
+    try {
+      const dirs = new Set<string>()
+      for (const r of rows) {
+        dirs.add(path.join(projectDir, r.path.endsWith('/') ? r.path : path.dirname(r.path)))
+      }
+      for (const d of dirs) await mkdir(d, { recursive: true })
+      await Promise.all(
+        files.map(async (r) => {
+          const to = path.join(projectDir, r.path)
+          await Bun.write(to, Bun.file(path.join(tree, treeName(r.path))), { createPath: false })
+          const mode = restoredMode(r.mode)
+          if (mode !== plain) await chmod(to, mode)
+          const at = new Date(r.mtimeMs)
+          await utimes(to, at, at)
+        }),
+      )
+    } catch (err) {
+      await Promise.all(
+        [...tops].map((t) => rm(path.join(projectDir, t), { recursive: true, force: true })),
+      )
+      throw err
+    }
+    return true
+  }
+
+  private stdoutText(hash: string): string {
+    const row = this.db.query('SELECT stdout FROM entry_stdout WHERE hash = ?').get(hash) as {
+      stdout: string | Uint8Array
+    } | null
+    if (row === null) return ''
+    return typeof row.stdout === 'string' ? row.stdout : utf8Decode.decode(row.stdout)
+  }
+
   /** Remove one entry: its artifact first, then its rows (as `prune` orders them). */
   private async dropEntry(hash: string): Promise<void> {
     await rm(this.tarPath(hash), { force: true })
+    await rm(this.treePath(hash), { recursive: true, force: true })
     const drop = this.db.transaction(() => {
       this.deleteBlob.run(hash)
       this.deleteEntryRow.run(hash)
@@ -1924,7 +2072,7 @@ export class Cache implements CacheLayer {
     // outputs, so a restore that did not fail 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 `vx cache clean` in another shell, or another workspace's retention
+    // (a `vx cache clean` in another shell, here or for another workspace
     // on a shared `--cache-dir`) — `ArtifactVanishedError`, which the caller
     // turns into a miss: the task runs.
     //
@@ -1986,6 +2134,8 @@ export class Cache implements CacheLayer {
     // 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.
+    const tree =
+      inline === undefined && existsSync(this.treePath(hash)) ? this.treePath(hash) : undefined
     const endExtract = span('restore: extract')
     try {
       // Every step here is an async filesystem call on purpose: a
@@ -1993,15 +2143,13 @@ export class Cache implements CacheLayer {
       // 0.62 ms sequential, 2026-09-10) and 30% slower in the run, where
       // four workers overlap their round trips and a blocking one stalls
       // the other three (1,000-project restore row 1.1–1.2 s → 1.5 s).
-      const tar = await decodedTar(inline ?? Bun.file(src), hash, this.artifactCeiling)
-      await extractArtifactStream(
-        tar,
-        projectDir,
-        workspaceRoot,
-        verify,
-        outputs === undefined ? undefined : declaredName(outputs),
-        workspaceRoot,
-      )
+      const accept = outputs === undefined ? undefined : declaredName(outputs)
+      if (tree !== undefined) {
+        await this.restoreTree(hash, tree, rows, projectDir, workspaceRoot, verify, accept)
+      } else {
+        const tar = await decodedTar(inline ?? Bun.file(src), hash, this.artifactCeiling)
+        await extractArtifactStream(tar, projectDir, workspaceRoot, verify, accept, workspaceRoot)
+      }
     } catch (err) {
       // A UserError here is the extractor naming the tree's fault (an
       // output directory that links out of the project).
@@ -2052,7 +2200,13 @@ export class Cache implements CacheLayer {
       // artifact is intact, the tree is not the process's to change.
       // A refusal to READ the artifact is the cache directory's, not the
       // outputs': the old line sent the reader to the wrong tree (A-40).
-      if (isFsRefusal(err) && err.path === src) {
+      // A tree copy's error can name its source; no read fails ENOSPC.
+      if (
+        isFsRefusal(err) &&
+        code !== 'ENOSPC' &&
+        code !== 'EDQUOT' &&
+        (err.path === src || (tree !== undefined && inTree(err.path, tree)))
+      ) {
         throw new UserError(
           `restore of ${hash} could not read its artifact (${code}: ${err.message}). ` +
             `Make the cache directory readable by this user, or point cacheDir / --cache-dir at one that is.`,
@@ -2164,23 +2318,21 @@ export class Cache implements CacheLayer {
     // again in `writeArtifactAndIndex` cost every save two thread-pool
     // round trips for an EEXIST and a stat (item 630).
     const endPack = span('save: pack')
-    const packed = await this.packArtifactToTemp(this.tempPath(args.hash), args).catch(
-      (err: unknown) => {
-        // A save that could not open an output names the limit, not only
-        // the file, which is fine (A-39).
-        if (isOutOfFds(err)) {
-          throw new UserError(
-            `save of ${args.hash} could not open a file (${err.message}) — ${OUT_OF_FDS_HINT}`,
-          )
-        }
-        throw err
-      },
-    )
+    const packed = await this.packForSave(args).catch((err: unknown) => {
+      // A save that could not open an output names the limit, not only
+      // the file, which is fine (A-39).
+      if (isOutOfFds(err)) {
+        throw new UserError(
+          `save of ${args.hash} could not open a file (${err.message}) — ${OUT_OF_FDS_HINT}`,
+        )
+      }
+      throw err
+    })
     endPack()
     await this.guard(() =>
       this.writeArtifactAndIndex(
         args.hash,
-        'tar' in packed ? packed.compressed : packed,
+        'tar' in packed ? packed.compressed : 'plan' in packed ? packed.saved : packed,
         {
           taskId: args.entry.taskId,
           command: args.entry.command,
@@ -2220,11 +2372,30 @@ export class Cache implements CacheLayer {
    * gone; `release` unlinks the name. An inline artifact is read once into
    * the body, which no re-save can change.
    */
-  pinArtifact(hash: string): { body: Blob; release: () => Promise<void> } {
+  async pinArtifact(hash: string): Promise<{ body: Blob; release: () => Promise<void> }> {
     const blob = this.guard(() => this.selectBlob.get(hash) as { bytes: Uint8Array } | null)
     if (blob !== null) return { body: new Blob([blob.bytes]), release: async () => {} }
     const pinned = this.tempPath(hash)
-    linkSync(this.tarPath(hash), pinned)
+    try {
+      linkSync(this.tarPath(hash), pinned)
+    } catch (err) {
+      const tree = this.treePath(hash)
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT' || !existsSync(tree)) throw err
+      // A tree is packed into the artifact a remote expects here, in the
+      // upload queue, off the save; a small one in memory.
+      const plan = planOfTree(tree, this.stdoutText(hash))
+      if (plan.size <= STREAM_DECODE_FROM) {
+        const bytes = await zstdCompress(await packArtifactBytes(plan))
+        return { body: new Blob([bytes]), release: async () => {} }
+      }
+      await Bun.write(
+        pinned,
+        new Response(packArtifactStream(plan).pipeThrough(zstdEncoder())),
+      ).catch(async (e: unknown) => {
+        await unlink(pinned).catch(() => undefined)
+        throw e
+      })
+    }
     return { body: Bun.file(pinned), release: () => unlink(pinned).catch(() => undefined) }
   }
 
@@ -2233,7 +2404,7 @@ export class Cache implements CacheLayer {
    * `Response` and copies a file `Blob` without collecting either, so a
    * pull never holds the artifact. A body that fails mid-stream (a dropped
    * socket) leaves a partial temp behind it, removed here; validation
-   * removes its own. A body of at most `INLINE_MAX` bytes — by its size,
+   * removes its own. A body of at most `cache.store.embeddings` bytes — by its size,
    * or counted as it streams — is read to memory and stored inline.
    */
   async ingest(hash: string, body: Blob | Response, meta: IngestMeta): Promise<void> {
@@ -2253,22 +2424,28 @@ export class Cache implements CacheLayer {
     let counted: ReadableStream<Uint8Array> | undefined
     let reader: ChunkReader | undefined
     let small: Uint8Array | undefined
+    // A store of plain files holds a body up to the bulk decode's bound:
+    // fetched whole, it is decoded in one call straight into the tree, with
+    // no temp archive between (`writeArtifactAndIndex`).
+    const held = this.store.decompress
+      ? Math.max(this.store.embeddings, STREAM_DECODE_FROM)
+      : this.store.embeddings
     try {
       const length =
         body instanceof Blob ? body.size : Number(body.headers.get('content-length') ?? 0)
       if (length > cap) throw past()
       if (body instanceof Blob) {
-        if (length <= INLINE_MAX) small = await body.bytes()
+        if (length <= held && held > 0) small = await body.bytes()
         else await Bun.write(tmpPath, body)
       } else {
         let source = body.body
         if (source === null) small = new Uint8Array(0)
-        else if (length <= INLINE_MAX) {
+        else if (length <= held && held > 0) {
           // Counted as it streams: a length the server did not send, or
-          // one it sent short, cannot make a large body inline.
+          // one it sent short, cannot read a large body to memory.
           const r: ChunkReader = source.getReader()
           reader = r
-          const head = await readUpTo(r, INLINE_MAX)
+          const head = await readUpTo(r, held)
           if (head.done) small = head.bytes
           else source = prepended(head.bytes, r)
         }
@@ -2406,6 +2583,36 @@ export class Cache implements CacheLayer {
     return { tmpPath }
   }
 
+  /**
+   * The save's local form: a small entry packed for the index when the
+   * store embeds, else a `.tar.zst` (`decompress: false`) or a tree of the outputs
+   * copied as they are.
+   */
+  private async packForSave(
+    args: Parameters<Cache['packArtifact']>[0],
+  ): Promise<
+    | { compressed: Uint8Array; tar: Uint8Array }
+    | { tmpPath: string }
+    | { plan: true; saved: SavedTree }
+  > {
+    if (!this.store.decompress) return this.packArtifactToTemp(this.tempPath(args.hash), args)
+    const plan = await this.planWithin(args)
+    if (this.store.embeddings > 0 && plan.size <= this.store.embeddings) {
+      const tar = await packArtifactBytes(plan)
+      return { compressed: await zstdCompress(tar), tar }
+    }
+    const tree = this.tempTreePath(args.hash)
+    try {
+      const scan = await writeTree(plan, tree)
+      let bytes = 0
+      for (const e of scan.entries) bytes += e.size
+      return { plan: true, saved: { tree, scan, bytes } }
+    } catch (err) {
+      await rm(tree, { recursive: true, force: true })
+      throw err
+    }
+  }
+
   /** 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
@@ -2416,7 +2623,7 @@ export class Cache implements CacheLayer {
 
   /**
    * Atomically write `compressed` to `<hash>.tar.zst`, or inline into
-   * `artifacts` when it is at most `INLINE_MAX` bytes, and (re)build the
+   * `artifacts` when it is at most `cache.store.embeddings` bytes, and (re)build the
    * entries + output_files SQL rows from the archive itself. Shared by
    * `save()` (we just packed the bytes) and `ingest()` (it streamed them
    * from the remote layer into a temp) — both index the identical values, because both
@@ -2424,7 +2631,7 @@ export class Cache implements CacheLayer {
    */
   private async writeArtifactAndIndex(
     hash: string,
-    compressed: Uint8Array | { tmpPath: string },
+    given: Uint8Array | { tmpPath: string } | SavedTree,
     meta: IngestMeta,
     /**
      * The tar `compressed` was made from, when this process packed it: it is
@@ -2441,12 +2648,25 @@ export class Cache implements CacheLayer {
     // restore, so the size/mode/mtime fingerprint we store matches
     // what isOutputsCurrent will compare against post-restore.
     const finalPath = this.tarPath(hash)
+    const saved = 'tree' in given ? given : undefined
+    const compressed = 'tree' in given ? new Uint8Array(0) : given
     // An inline artifact is written in the rows' transaction below: no
     // temp, no rename.
     const inline =
-      compressed instanceof Uint8Array && compressed.byteLength <= INLINE_MAX ? compressed : null
+      saved === undefined &&
+      this.store.embeddings > 0 &&
+      compressed instanceof Uint8Array &&
+      compressed.byteLength <= this.store.embeddings
+        ? compressed
+        : null
+    // A remote hit this store keeps as plain files is decoded once, into the
+    // tree, and checked there: nothing names the tree until the rows go in.
+    const oneTree =
+      saved === undefined && inline === null && tar === undefined && this.store.decompress
     let tmpPath: string | undefined
-    if (inline === null && compressed instanceof Uint8Array) {
+    if (saved !== undefined) {
+      // The tree save wrote and scanned its own outputs.
+    } else if (inline === null && compressed instanceof Uint8Array && !oneTree) {
       const temp = this.tempPath(hash)
       tmpPath = temp
       // The temp is written BEFORE validation so a large artifact can be
@@ -2470,9 +2690,35 @@ export class Cache implements CacheLayer {
       tmpPath = compressed.tmpPath
     }
     let scanned: Awaited<ReturnType<typeof scanArtifact>>
+    let tree = saved?.tree
     try {
       const endScan = span('save: scan')
-      if (tar !== undefined) {
+      if (saved !== undefined) {
+        scanned = saved.scan
+      } else if (oneTree) {
+        const dir = this.tempTreePath(hash)
+        tree = dir
+        let scan: Awaited<ReturnType<typeof scanArtifact>> | undefined
+        let raw: { meta: string; sum: string } | undefined
+        await extractArtifactStream(
+          await decodedTar(
+            compressed instanceof Uint8Array ? compressed : Bun.file(tmpPath!),
+            hash,
+            this.artifactCeiling,
+          ),
+          path.join(dir, 'outputs'),
+          path.join(dir, WORKSPACE_OUTPUT_PREFIX),
+          undefined,
+          undefined,
+          undefined,
+          (s, r) => {
+            scan = s
+            raw = r
+          },
+        )
+        scanned = scan!
+        await sealTree(dir, scanned, raw)
+      } else if (tar !== undefined) {
         // Our own tar, in memory: read in place, on this thread.
         scanned = scanTarBytes(tar)
       } else {
@@ -2505,12 +2751,45 @@ export class Cache implements CacheLayer {
       ])
     } catch (err) {
       if (tmpPath !== undefined) await unlink(tmpPath).catch(() => undefined)
+      if (tree !== undefined) await rm(tree, { recursive: true, force: true })
       if (err instanceof ArchiveSecurityError || err instanceof CorruptArtifactError) throw err
       throw new CorruptArtifactError(hash, 'artifact is not a readable archive', err)
     }
     const { entries } = scanned
     const totalBytes =
-      compressed instanceof Uint8Array ? compressed.byteLength : Bun.file(tmpPath!).size
+      saved !== undefined
+        ? saved.bytes
+        : compressed instanceof Uint8Array
+          ? compressed.byteLength
+          : Bun.file(tmpPath!).size
+    // A remote hit this store keeps as plain files: the archive passed its
+    // checks above, so it is unpacked once here and its temp goes.
+    if (oneTree && tmpPath !== undefined) {
+      await unlink(tmpPath).catch(() => undefined)
+      tmpPath = undefined
+    }
+    if (tree === undefined && inline === null && this.store.decompress) {
+      const dir = this.tempTreePath(hash)
+      try {
+        const source =
+          compressed instanceof Uint8Array && compressed.byteLength > 0
+            ? compressed
+            : Bun.file(tmpPath!)
+        await extractArtifactStream(
+          await decodedTar(source, hash, this.artifactCeiling),
+          path.join(dir, 'outputs'),
+          path.join(dir, WORKSPACE_OUTPUT_PREFIX),
+        )
+        await sealTree(dir, scanned)
+      } catch (err) {
+        await rm(dir, { recursive: true, force: true })
+        if (tmpPath !== undefined) await unlink(tmpPath).catch(() => undefined)
+        throw err
+      }
+      if (tmpPath !== undefined) await unlink(tmpPath).catch(() => undefined)
+      tmpPath = undefined
+      tree = dir
+    }
     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/`
@@ -2600,19 +2879,27 @@ export class Cache implements CacheLayer {
     // bytes are in one place. An inline save moves aside whatever file the
     // key has, as a file save does: one rename that finds nothing on a
     // first save, where asking the index first was a statement per save.
-    let aside: string | undefined
-    let renamed = false
+    let aside: string[] = []
+    let renamed: string | undefined
     const upsertBlob = this.upsertBlob
     const deleteBlob = this.deleteBlob
-    const moveAside = (): string | undefined => {
-      const to = this.tempPath(hash)
-      try {
-        renameSync(finalPath, to)
-        return to
-      } catch (err) {
-        if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err
-        return undefined
+    const treePath = this.treePath(hash)
+    // Both file forms are moved aside: a key re-saved under another
+    // `cache.store` leaves one live artifact.
+    const moveAside = (): string[] => {
+      const moved: string[] = []
+      for (const [from, to] of [
+        [finalPath, this.tempPath(hash)],
+        [treePath, this.tempTreePath(hash)],
+      ] as const) {
+        try {
+          renameSync(from, to)
+          moved.push(to)
+        } catch (err) {
+          if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err
+        }
       }
+      return moved
     }
     const tx = this.db.transaction(() => {
       if (inline !== null) {
@@ -2620,9 +2907,10 @@ export class Cache implements CacheLayer {
         upsertBlob.run(hash, now, inline)
       } else {
         aside = moveAside()
-        renameSync(tmpPath!, finalPath)
-        this.artifactNames?.add(path.basename(finalPath))
-        renamed = true
+        const live = tree !== undefined ? treePath : finalPath
+        renameSync(tree ?? tmpPath!, live)
+        this.artifactNames?.add(path.basename(live))
+        renamed = live
         deleteBlob.run(hash)
       }
       insertEntry.run(
@@ -2665,13 +2953,17 @@ export class Cache implements CacheLayer {
       tx.immediate()
     } catch (err) {
       endTx()
-      const left = renamed ? finalPath : tmpPath
-      if (left !== undefined) await unlink(left).catch(() => undefined)
-      if (aside !== undefined) await unlink(aside).catch(() => undefined)
+      const left = renamed ?? tree ?? tmpPath
+      if (left !== undefined) await rm(left, { recursive: true, force: true })
+      for (const a of aside) await rm(a, { recursive: true, force: true })
       throw err
     }
     endTx()
-    if (aside !== undefined) await unlink(aside).catch(() => undefined)
+    for (const a of aside) await rm(a, { recursive: true, force: true })
+  }
+
+  private tempTreePath(hash: string): string {
+    return `${this.treePath(hash)}.tmp-${process.pid}-${process.hrtime.bigint()}-${Math.random().toString(36).slice(2, 10)}`
   }
 
   /** Apply the deferred accessed_at bumps in one statement. */
@@ -2688,7 +2980,7 @@ export class Cache implements CacheLayer {
     const at = new Date(now)
     for (const hash of this.staleTimes) {
       try {
-        utimesSync(this.tarPath(hash), at, at)
+        utimesSync(this.artifactStat(hash)?.path ?? this.tarPath(hash), at, at)
       } catch {
         // Gone, or another user's file: a sweep judges its old time.
       }
@@ -2777,67 +3069,6 @@ export class Cache implements CacheLayer {
     }
   }
 
-  /**
-   * The workspace's `cacheRetention`, applied at the end of a run: `prune()`
-   * with the same policy, but only when it would evict something, else the
-   * orphan sweep alone when an hour has passed since the last one. A run
-   * with nothing due pays the accessed-at flush it owed at close anyway, one
-   * scan of the index and one read of the sweep's clock — never the
-   * sweep's readdir. Null when nothing was due or the directory is not this
-   * handle's to write. The local WRITE axis does not gate it: under
-   * `--cache-policy=local:r,remote:rw` a save writes nothing here, but every remote
-   * hit is still ingested (`ingest`, ungated by design), and gated on that
-   * axis the retention never ran while the store grew hit by hit (A-7).
-   */
-  async evictIfDue(
-    policy: { maxAgeMs?: number; maxBytes?: number },
-    now: number = Date.now(),
-  ): Promise<PruneResult | null> {
-    return this.guard(() => this.evictIfDueNow(policy, now))
-  }
-
-  private async evictIfDueNow(
-    policy: { maxAgeMs?: number; maxBytes?: number },
-    now: number,
-  ): Promise<PruneResult | null> {
-    if (this.writeBlocked !== null || this.inspecting) return null
-    // First: an entry this run restored still carries its old `accessed_at`
-    // until the deferred bump lands, and would read as due for eviction.
-    this.flushAccessed()
-    const olderThanMs = policy.maxAgeMs === undefined ? undefined : now - policy.maxAgeMs
-    const { oldest, bytes } = this.db
-      .prepare(
-        'SELECT MIN(accessed_at) AS oldest, COALESCE(SUM(size_bytes), 0) AS bytes FROM entries',
-      )
-      .get() as { oldest: number | null; bytes: number }
-    const ageDue =
-      olderThanMs !== undefined && oldest !== null && oldest + ACCESS_REFRESH_MS < olderThanMs
-    const sizeDue = policy.maxBytes !== undefined && bytes > policy.maxBytes
-    if (ageDue || sizeDue) {
-      return this.prune({
-        ...(olderThanMs !== undefined ? { olderThanMs } : {}),
-        ...(policy.maxBytes !== undefined ? { maxBytes: policy.maxBytes } : {}),
-      })
-    }
-    // Row-less artifacts are bytes the index cannot count, so the policy
-    // above never sees them (upstream survey, nx#35483: 9 MiB of them sat
-    // under a 1 MB limit). Listing the directory to find them costs 0.5 ms
-    // per 1,000 entries (4.9 ms at 10,000), every run; the sweep's own
-    // clock in `schema_meta` costs one indexed read. The sweep is the
-    // policy's own prune, with the row-less files counted.
-    const swept = this.db.prepare('SELECT value FROM schema_meta WHERE key = ?').get(SWEPT_AT) as {
-      value: string
-    } | null
-    if (swept !== null && now - Number(swept.value) < ORPHAN_GRACE_MS) return null
-    return this.pruneIndex(
-      {
-        ...(olderThanMs !== undefined ? { olderThanMs } : {}),
-        ...(policy.maxBytes !== undefined ? { maxBytes: policy.maxBytes } : {}),
-      },
-      now,
-    )
-  }
-
   async prune(options: PruneOptions): Promise<PruneResult> {
     return this.guard(() => this.pruneIndex(options))
   }
@@ -2891,7 +3122,12 @@ export class Cache implements CacheLayer {
       // and the one verb meant to free a full disk freed nothing (A-14). An
       // inline artifact goes with its rows, in their transaction.
       await Promise.all(
-        hashes.filter((h) => !inline.has(h)).map((h) => rm(this.tarPath(h), { force: true })),
+        hashes
+          .filter((h) => !inline.has(h))
+          .flatMap((h) => [
+            rm(this.tarPath(h), { force: true }),
+            rm(this.treePath(h), { recursive: true, force: true }),
+          ]),
       )
       const { test, params } = inHashes(rows)
       const deleteRows = this.db.transaction(() => {
@@ -2914,7 +3150,15 @@ export class Cache implements CacheLayer {
     } catch (err) {
       if (!isIndexFull(err)) throw err
     }
-    const orphans = await this.reapOrphans(picked.files, now)
+    // History and memo rows a month old go with a prune, never a run's
+    // close: five DELETEs on every run's exit was its slowest step (owner,
+    // 2026-10-18). `invocations` shares the window with `runs`, or `vx last`
+    // would list a run whose task rows are gone.
+    const cutoff = now - HISTORY_RETENTION_MS
+    this.history.pruneOlderThan(cutoff)
+    this.files.pruneOlderThan(cutoff)
+    this.folds.prune(cutoff)
+    const orphans = await this.reapOrphans(picked.files)
     return { evicted: victims.size, bytesFreed, ...orphans }
   }
 
@@ -2929,16 +3173,7 @@ export class Cache implements CacheLayer {
    */
   private async reapOrphans(
     taken: readonly RowlessFile[],
-    now: number,
   ): Promise<{ orphans: number; orphanBytes: number }> {
-    try {
-      this.db
-        .prepare('INSERT OR REPLACE INTO schema_meta(key, value) VALUES (?, ?)')
-        .run(SWEPT_AT, String(now))
-    } catch (err) {
-      // The sweep's clock: on a full disk the sweep runs again next time.
-      if (!isIndexFull(err)) throw err
-    }
     let orphans = 0
     let orphanBytes = 0
     const blobs = taken.filter((o) => o.blob !== undefined)
@@ -2967,7 +3202,7 @@ export class Cache implements CacheLayer {
         try {
           // unlink, not `rm({ force })`: force swallows ENOENT, and a file a
           // concurrent prune took first must not be counted as ours.
-          await unlink(o.file)
+          await rm(o.file, { recursive: true })
           orphans += 1
           orphanBytes += o.size
         } catch {
@@ -3016,7 +3251,8 @@ export class Cache implements CacheLayer {
     const phantoms = new Map<string, number>()
     const stale: string[] = []
     for (const r of rows) {
-      if (r.inline === 1 || present.has(`${r.hash}.tar.zst`)) continue
+      if (r.inline === 1 || present.has(`${r.hash}.tar.zst`) || present.has(`${r.hash}.tree`))
+        continue
       phantoms.set(r.hash, r.size_bytes)
       if (r.accessed_at < graceStart) stale.push(r.hash)
     }
@@ -3068,34 +3304,12 @@ export class Cache implements CacheLayer {
   }
 
   close(): void {
-    // Run-history retention: the runs table grows by one row per
-    // executed task per invocation — a 2000-task repo accretes ~20k
-    // rows in days, inflating insert and checkpoint cost forever.
-    // 30 days comfortably covers `vx info` (24 h windows) and any
-    // 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.
-    // A reading verb and a dry run delete nothing: `vx last --list` over
-    // month-old runs emptied the history it listed, and `vx cache clean
-    // --dry-run` pruned it (item 1004).
-    try {
-      if (!this.inspecting) {
-        const cutoff = Date.now() - 30 * 24 * 60 * 60 * 1000
-        this.history.pruneOlderThan(cutoff)
-        if (this.write) this.files.pruneOlderThan(cutoff)
-      }
-    } catch {
-      // Retention is best-effort; never block closing the handle.
-    }
     try {
       this.flushAccessed()
       this.outputs.flushOutputDirs()
-      this.folds.flush(Date.now() - 30 * 24 * 60 * 60 * 1000)
+      this.folds.flush()
     } catch {
-      // Same contract as the retention prune above, which was already
-      // guarded while this sibling was not: `accessed_at` is LRU
+      // `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
@@ -3109,6 +3323,21 @@ export class Cache implements CacheLayer {
   private tarPath(hash: string): string {
     return path.join(this.artifactDir, `${hash}.tar.zst`)
   }
+
+  private treePath(hash: string): string {
+    return path.join(this.artifactDir, `${hash}.tree`)
+  }
+
+  /** The key's file-backed artifact (tar or tree), the form this store writes asked first. */
+  private artifactStat(hash: string): { path: string; tree: boolean; mtimeMs: number } | undefined {
+    const order = this.store.decompress ? [true, false] : [false, true]
+    for (const tree of order) {
+      const at = tree ? this.treePath(hash) : this.tarPath(hash)
+      const st = statSync(at, { throwIfNoEntry: false })
+      if (st !== undefined) return { path: at, tree, mtimeMs: st.mtimeMs }
+    }
+    return undefined
+  }
 }
 
 /**
@@ -3181,6 +3410,17 @@ function assertArtifactNames(
   }
 }
 
+/** A row's path as the tree names its file. */
+function treeName(rowPath: string): string {
+  return rowPath.startsWith(WORKSPACE_OUTPUT_PREFIX) ? rowPath : `outputs/${rowPath}`
+}
+
+function inTree(p: string | undefined, tree: string): boolean {
+  return p !== undefined && (p === tree || p.startsWith(`${tree}/`))
+}
+
+const utf8Decode = new TextDecoder('utf-8', { ignoreBOM: true })
+
 /**
  * Whether an artifact entry names one of the task's declared outputs, as
  * the save could have packed it (`restorableOutput`: a `!` take-back, vx's