@vzn/vx 0.0.595 → 0.0.596

package/README.md

@@ -98,7 +98,7 @@ More: [Quickstart](https://vznjs.github.io/vx/quickstart/) ·
 Beside `turbo.json` or `nx.json`, `vx init` writes only a
 `vx.workspace.ts` that maps the old config until then: a temporary
 start, not a way to run the repo. The numbers above are native vx
-config. `@vzn/vx-migrate`'s first npm publish is pending.
+config.
 [Migration guide](https://vznjs.github.io/vx/guides/migrate/).
 
 ## Why it is faster

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.595",
+  "version": "0.0.596",
   "description": "The fastest task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.595",
-    "@vzn/vx-linux-arm64": "0.0.595",
-    "@vzn/vx-darwin-x64": "0.0.595",
-    "@vzn/vx-darwin-arm64": "0.0.595"
+    "@vzn/vx-linux-x64": "0.0.596",
+    "@vzn/vx-linux-arm64": "0.0.596",
+    "@vzn/vx-darwin-x64": "0.0.596",
+    "@vzn/vx-darwin-arm64": "0.0.596"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cache/cache.ts

@@ -44,6 +44,7 @@ import {
   openSync,
   readdirSync,
   renameSync,
+  statSync,
   utimesSync,
   writeFileSync,
 } from 'node:fs'
@@ -111,12 +112,13 @@ import { RunHistory } from './run-history.js'
 import { CACHE_VERSION, foldKey } from './key-fold.js'
 
 /**
- * An artifact or temp file without an `entries` row is reaped by
- * `prune()` only once it is this old. A save renames the artifact into
- * place inside its `BEGIN IMMEDIATE` row transaction (A-3), so a live
- * artifact without a row is one whose commit failed and was taken back
- * out; a crashed save's temp is stale long before this. Generous on purpose — a false orphan costs a
- * re-run, a leaked temp costs disk.
+ * 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
+ * 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.
  */
 const ORPHAN_GRACE_MS = 60 * 60 * 1000
 
@@ -271,6 +273,62 @@ function indexOfAnotherSchema(dbFile: string): boolean {
 const SELECT_ENTRY =
   "SELECT e.*, COALESCE(s.stdout, '') AS stdout FROM entries e LEFT JOIN entry_stdout s ON s.hash = e.hash"
 
+/** A file the orphan sweep may judge: a row-less artifact, or a temp. */
+interface RowlessFile {
+  file: string
+  size: number
+  mtimeMs: number
+  temp: boolean
+}
+
+/**
+ * What a prune takes under `policy`: index rows by `accessed_at` and
+ * row-less artifacts by file time, under one rule (a temp always). The
+ * rows are the non-phantom ones; the files are past the in-flight grace.
+ */
+function pickVictims(
+  rows: ReadonlyArray<{ hash: string; size_bytes: number; accessed_at: number }>,
+  files: readonly RowlessFile[],
+  policy: { olderThanMs?: number; maxBytes?: number },
+): { hashes: Set<string>; bytesFreed: number; files: RowlessFile[] } {
+  const { olderThanMs, maxBytes } = policy
+  const hashes = new Set<string>()
+  let bytesFreed = 0
+  const taken: RowlessFile[] = []
+  const kept: Array<{ at: number; size: number; row?: string; file?: RowlessFile }> = []
+  let remaining = 0
+  for (const r of rows) {
+    if (olderThanMs !== undefined && r.accessed_at < olderThanMs) {
+      hashes.add(r.hash)
+      bytesFreed += r.size_bytes
+    } else {
+      kept.push({ at: r.accessed_at, size: r.size_bytes, row: r.hash })
+      remaining += r.size_bytes
+    }
+  }
+  for (const f of files) {
+    const at = f.mtimeMs + ORPHAN_GRACE_MS
+    if (f.temp || (olderThanMs !== undefined && at < olderThanMs)) taken.push(f)
+    else {
+      kept.push({ at, size: f.size, file: f })
+      remaining += f.size
+    }
+  }
+  if (maxBytes !== undefined && remaining > maxBytes) {
+    kept.sort((a, b) => a.at - b.at)
+    for (const k of kept) {
+      if (remaining <= maxBytes) break
+      remaining -= k.size
+      if (k.file !== undefined) taken.push(k.file)
+      else {
+        hashes.add(k.row!)
+        bytesFreed += k.size
+      }
+    }
+  }
+  return { hashes, bytesFreed, files: taken }
+}
+
 /**
  * Artifacts `indexed` does not hold, and temps, past the in-flight grace
  * window: one readdir, one stat per candidate. `indexed` is asked only
@@ -281,7 +339,7 @@ const SELECT_ENTRY =
 async function scanOrphanFiles(
   cacheDir: string,
   indexedHashes: () => ReadonlySet<string>,
-): Promise<Array<{ file: string; size: number }>> {
+): Promise<RowlessFile[]> {
   let names: string[]
   try {
     names = await readdir(cacheDir)
@@ -290,19 +348,22 @@ async function scanOrphanFiles(
   }
   const indexed = indexedHashes()
   const cutoff = Date.now() - ORPHAN_GRACE_MS
-  const candidates: string[] = []
+  const candidates: Array<{ name: string; temp: boolean }> = []
   for (const name of names) {
     const m = VX_ARTIFACT_NAME.exec(name)
     if (m === null) continue
-    if (m[2] !== undefined || !indexed.has(m[1]!)) candidates.push(name)
+    const temp = m[2] !== undefined
+    if (temp || !indexed.has(m[1]!)) candidates.push({ name, temp })
   }
-  const found: Array<{ file: string; size: number }> = []
+  const found: RowlessFile[] = []
   await Promise.all(
-    candidates.map(async (name) => {
+    candidates.map(async ({ name, temp }) => {
       const file = path.join(cacheDir, name)
       try {
         const st = await stat(file)
-        if (st.isFile() && st.mtimeMs <= cutoff) found.push({ file, size: st.size })
+        if (st.isFile() && st.mtimeMs <= cutoff) {
+          found.push({ file, size: st.size, mtimeMs: st.mtimeMs, temp })
+        }
       } catch {
         // Gone between readdir and stat: not an orphan any more.
       }
@@ -570,6 +631,8 @@ export class Cache implements CacheLayer {
   private readonly deleteStdout: ReturnType<Database['prepare']>
   private readonly entryExists: ReturnType<Database['prepare']>
   private readonly touched = new Set<string>()
+  /** Hit artifacts whose file time is past the grace: renewed at the flush (`ORPHAN_GRACE_MS`). */
+  private readonly staleTimes = new Set<string>()
   private readonly insertEntryInput: ReturnType<Database['prepare']>
   /** The per-file (mtime, size) → blob-OID memo behind `hashFile`. */
   private readonly files: FileHashStore
@@ -1268,7 +1331,9 @@ export class Cache implements CacheLayer {
 
     // Verify the tar artifact actually exists. The DB and the
     // filesystem can drift if someone manually deletes the cache dir.
-    if (!existsSync(this.tarPath(hash))) return null
+    const st = statSync(this.tarPath(hash), { throwIfNoEntry: false })
+    if (st === undefined) return null
+    if (st.mtimeMs < Date.now() - ORPHAN_GRACE_MS) this.staleTimes.add(hash)
 
     // Deferred: per-hit UPDATEs cost ~60 ms across 2000+ probes on a
     // full-cache run. Hashes are collected and flushed as ONE batched
@@ -1301,7 +1366,7 @@ export class Cache implements CacheLayer {
   ): Promise<Map<string, CacheEntry>> {
     return this.guard(async () => {
       const out = await this.getManyEntries(hashes)
-      if (ctx === undefined || !this.write || out.size === hashes.length) return out
+      if (ctx === undefined || !this.read || !this.write || out.size === hashes.length) return out
       // An artifact the index does not know is still a hit (`adopt`).
       for (const hash of hashes) {
         if (out.has(hash) || !(await this.adopt(hash, ctx(hash)))) continue
@@ -1318,8 +1383,12 @@ export class Cache implements CacheLayer {
     const { test, params } = inHashes(hashes)
     const rows = this.db.query(`${SELECT_ENTRY} WHERE e.hash ${test}`).all(...params) as EntryRow[]
     if (rows.length === 0) return out
-    const present = rows.map((r) => existsSync(this.tarPath(r.hash)))
-    const live = rows.filter((_r, i) => present[i])
+    const graceStart = Date.now() - ORPHAN_GRACE_MS
+    const live = rows.filter((r) => {
+      const st = statSync(this.tarPath(r.hash), { throwIfNoEntry: false })
+      if (st !== undefined && st.mtimeMs < graceStart) this.staleTimes.add(r.hash)
+      return st !== undefined
+    })
     const liveHashes = live.map((r) => r.hash)
     const fileRows = this.loadOutputFilesBatch(liveHashes)
     const dirRows = this.loadOutputDirsBatch(liveHashes)
@@ -2047,6 +2116,17 @@ export class Cache implements CacheLayer {
     const hashes = [...this.touched]
     this.touched.clear()
     const now = Date.now()
+    // The file time is the last use another vx version's sweep can see:
+    // its open dropped this index's rows (`pickVictims`).
+    const at = new Date(now)
+    for (const hash of this.staleTimes) {
+      try {
+        utimesSync(this.tarPath(hash), at, at)
+      } catch {
+        // Gone, or another user's file: a sweep judges its old time.
+      }
+    }
+    this.staleTimes.clear()
     // LRU bookkeeping: on a full disk the bumps are dropped, never the prune
     // or the stats that asked for them (A-14).
     try {
@@ -2161,21 +2241,26 @@ export class Cache implements CacheLayer {
     // 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. An orphan is reapable
-    // only an hour after its last write anyway, so an hourly sweep reaps
-    // it within two.
+    // 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 { evicted: 0, bytesFreed: 0, ...(await this.reapOrphans(now)) }
+    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))
   }
 
-  private async pruneIndex(options: PruneOptions): Promise<PruneResult> {
+  private async pruneIndex(options: PruneOptions, now: number = Date.now()): Promise<PruneResult> {
     this.flushAccessed()
     // Before any entry is deleted, so a kept entry's pending snapshot is on
     // disk whatever the eviction does next. A pruned hash's snapshot cannot
@@ -2187,50 +2272,24 @@ export class Cache implements CacheLayer {
       throw new Error('prune: pass at least one of `olderThanMs` or `maxBytes`')
     }
 
-    const victims = new Set<string>()
-    let bytesFreed = 0
     // Rows whose artifact is gone (deleted by hand, or by a disk cleaner):
     // never a hit, and their bytes are on no disk, but `--max-size` counted
     // them and evicted real entries to make room for them (item 975). None
     // is evicted or freed, whatever its age (item 1081); the ones past the
     // grace window are dropped.
-    const { phantoms, stale } = await this.phantomRows()
-
-    if (olderThanMs !== undefined) {
-      const rows = this.db
-        .prepare('SELECT hash, size_bytes FROM entries WHERE accessed_at < ?')
-        .all(olderThanMs) as Array<{ hash: string; size_bytes: number }>
-      for (const r of rows) {
-        if (phantoms.has(r.hash)) continue
-        victims.add(r.hash)
-        bytesFreed += r.size_bytes
-      }
-    }
-
-    if (maxBytes !== undefined) {
-      const totalRow = this.db
-        .prepare('SELECT COALESCE(SUM(size_bytes), 0) AS bytes FROM entries')
-        .get() as { bytes: number }
-      let phantomBytes = 0
-      for (const b of phantoms.values()) phantomBytes += b
-      let remaining = totalRow.bytes - phantomBytes - bytesFreed
-      if (remaining > maxBytes) {
-        // Exclude already-picked victims in JS, not via a SQL NOT-IN —
-        // an IN-list over tens of thousands of TTL victims would blow
-        // SQLite's bound-parameter ceiling (see flushAccessed's 900 cap).
-        const candidates = (
-          this.db
-            .prepare('SELECT hash, size_bytes FROM entries ORDER BY accessed_at ASC')
-            .all() as Array<{ hash: string; size_bytes: number }>
-        ).filter((row) => !victims.has(row.hash) && !phantoms.has(row.hash))
-        for (const row of candidates) {
-          if (remaining <= maxBytes) break
-          victims.add(row.hash)
-          bytesFreed += row.size_bytes
-          remaining -= row.size_bytes
-        }
-      }
-    }
+    const { phantoms, stale, rows } = await this.phantomRows()
+    const picked = pickVictims(
+      rows.filter((r) => !phantoms.has(r.hash)),
+      await this.scanOrphans(),
+      {
+        ...(olderThanMs !== undefined ? { olderThanMs } : {}),
+        ...(maxBytes !== undefined ? { maxBytes } : {}),
+      },
+    )
+    const victims = picked.hashes
+    const { bytesFreed } = picked
+    let orphanBytes = 0
+    for (const o of picked.files) orphanBytes += o.size
 
     // Delete DB rows in a single transaction (one fsync; ON DELETE
     // CASCADE clears `output_files`) and unlink artifacts in parallel.
@@ -2239,13 +2298,7 @@ export class Cache implements CacheLayer {
     // flushAccessed so a huge eviction stays under any build's
     // bound-parameter ceiling.
     if (dryRun) {
-      const orphans = await this.orphanStats()
-      return {
-        evicted: victims.size,
-        bytesFreed,
-        orphans: orphans.orphans,
-        orphanBytes: orphans.orphanBytes,
-      }
+      return { evicted: victims.size, bytesFreed, orphans: picked.files.length, orphanBytes }
     }
     if (victims.size > 0 || stale.length > 0) {
       const hashes = [...victims]
@@ -2275,23 +2328,21 @@ export class Cache implements CacheLayer {
     } catch (err) {
       if (!isIndexFull(err)) throw err
     }
-    const orphans = await this.reapOrphans()
+    const orphans = await this.reapOrphans(picked.files, now)
     return { evicted: victims.size, bytesFreed, ...orphans }
   }
 
   /**
-   * Unlink artifacts the index does not know: a `<hash>.tar.zst` with no
-   * `entries` row (a `SCHEMA_VERSION` drop, a `cache.db` deleted by hand)
-   * and a `<hash>.tar.zst.tmp-*` a crashed save never renamed. Nothing
-   * else reaps them — a lookup starts at the row, and a save of the same
-   * key renames over the file, so a key that never recurs leaks its bytes
-   * forever. Files younger than the grace window are left alone: a save
-   * renames the artifact into place BEFORE its row commits, and its temp
-   * exists while the bytes are still being written, so a fresh file
-   * without a row is a save in flight, not an orphan.
+   * Unlink the row-less files `pickVictims` took: a `<hash>.tar.zst` with
+   * no `entries` row (another vx version's open dropped it, a `cache.db`
+   * deleted by hand) past the policy, and a `<hash>.tar.zst.tmp-*` a
+   * crashed save never renamed. Nothing else reaps them — a lookup starts
+   * at the row, and a save of the same key renames over the file, so a key
+   * that never recurs leaks its bytes forever.
    */
   private async reapOrphans(
-    now: number = Date.now(),
+    taken: readonly RowlessFile[],
+    now: number,
   ): Promise<{ orphans: number; orphanBytes: number }> {
     try {
       this.db
@@ -2304,7 +2355,7 @@ export class Cache implements CacheLayer {
     let orphans = 0
     let orphanBytes = 0
     await Promise.all(
-      (await this.scanOrphans()).map(async (o) => {
+      taken.map(async (o) => {
         try {
           // unlink, not `rm({ force })`: force swallows ENOENT, and a file a
           // concurrent prune took first must not be counted as ours.
@@ -2328,7 +2379,11 @@ export class Cache implements CacheLayer {
    * dropped — a row is never deleted on one listing's word while it may be
    * in use. An unreadable directory judges nothing.
    */
-  private async phantomRows(): Promise<{ phantoms: Map<string, number>; stale: string[] }> {
+  private async phantomRows(): Promise<{
+    phantoms: Map<string, number>
+    stale: string[]
+    rows: Array<{ hash: string; size_bytes: number; accessed_at: number }>
+  }> {
     const graceStart = Date.now() - ORPHAN_GRACE_MS
     const rows = this.db
       .prepare('SELECT hash, size_bytes, accessed_at FROM entries')
@@ -2341,7 +2396,7 @@ export class Cache implements CacheLayer {
     try {
       names = await readdir(this.artifactDir)
     } catch {
-      return { phantoms: new Map(), stale: [] }
+      return { phantoms: new Map(), stale: [], rows }
     }
     const present = new Set(names)
     const phantoms = new Map<string, number>()
@@ -2351,10 +2406,10 @@ export class Cache implements CacheLayer {
       phantoms.set(r.hash, r.size_bytes)
       if (r.accessed_at < graceStart) stale.push(r.hash)
     }
-    return { phantoms, stale }
+    return { phantoms, stale, rows }
   }
 
-  /** What `prune()` would reap right now, for `vx info` to say before anyone prunes. */
+  /** Row-less files past the in-flight grace, for `vx info`: a prune reaps them by its policy. */
   async orphanStats(): Promise<{ orphans: number; orphanBytes: number }> {
     const found = await this.scanOrphans()
     let orphanBytes = 0
@@ -2363,7 +2418,7 @@ export class Cache implements CacheLayer {
   }
 
   /** Row-less artifacts and temps past the in-flight grace window: one readdir, one stat per candidate. */
-  private async scanOrphans(): Promise<Array<{ file: string; size: number }>> {
+  private async scanOrphans(): Promise<RowlessFile[]> {
     const found = await scanOrphanFiles(
       this.artifactDir,
       () =>

package/src/cache/chained-cache.ts

@@ -4,7 +4,8 @@
 // once. Restore goes to the layer that produced the hit — remembered per
 // hash — because an entry's artifact lives wherever it was found.
 //
-// A layer that throws in a lookup is a miss there and the walk goes on; one
+// A layer that throws in a lookup (a batch row load or a has-many included)
+// is a miss there and the walk goes on; a throwing drain is passed; one
 // that throws in a save is skipped and the rest still save. Unisolated, a
 // plugin layer's throw ended the walk before the local floor under it: its
 // `get` failed the task, its `save` kept the entry from every later layer
@@ -122,14 +123,22 @@ export class ChainedCache implements CacheLayer {
       const found = await this.ask(
         layer,
         'remoteHasMany',
-        async () => (await layer.remoteHasMany?.(hashes)) ?? null,
+        // The shape check and the mark sit inside the ask: a layer that
+        // answers a non-Set or throws marking gave no answer.
+        async () => {
+          const got: unknown = (await layer.remoteHasMany?.(hashes)) ?? null
+          if (got === null) return null
+          if (!(got instanceof Set)) throw new TypeError('remoteHasMany answered a non-Set')
+          const set = got as Set<string>
+          layer.markRemoteAbsent?.(hashes.filter((h) => !set.has(h)))
+          return set
+        },
         null,
       )
       if (found === null) {
         complete = false
         continue
       }
-      layer.markRemoteAbsent?.(hashes.filter((h) => !found.has(h)))
       out ??= new Set()
       for (const h of found) out.add(h)
     }
@@ -142,15 +151,24 @@ export class ChainedCache implements CacheLayer {
   }
 
   async drainUploads(): Promise<void> {
-    await Promise.all(this.layers.map((l) => l.drainUploads?.()))
+    await Promise.all(
+      this.layers.map((l) =>
+        this.ask(l, 'drainUploads', async () => l.drainUploads?.(), undefined),
+      ),
+    )
   }
 
   loadOutputFilesBatch(hashes: readonly string[]): Map<string, OutputFileRow[]> {
     const out = new Map<string, OutputFileRow[]>()
-    for (const layer of this.layers) {
-      for (const [h, rows] of layer.loadOutputFilesBatch(hashes)) {
-        if (!out.has(h)) out.set(h, rows)
+    for (const [i, layer] of this.layers.entries()) {
+      let rows: Map<string, OutputFileRow[]>
+      try {
+        rows = layer.loadOutputFilesBatch(hashes)
+      } catch (err) {
+        this.onLayerError(i, 'loadOutputFilesBatch', err)
+        continue
       }
+      for (const [h, r] of rows) if (!out.has(h)) out.set(h, r)
     }
     return out
   }

package/src/cache/index.ts

@@ -11,6 +11,7 @@ export {
   type CacheKeyInput,
   type CacheLayer,
   type CachePolicy,
+  cachesNothing,
   EXECUTED_RUNS_SQL,
   FULL_CACHE_POLICY,
   type InvocationRecord,

package/src/cache/inputs.ts

@@ -109,10 +109,10 @@ export interface ResolveInputsArgs {
   envSource: NodeJS.ProcessEnv
   inputs: CacheInputs | undefined
   /** Project-relative output globs to exclude from inputs. */
-  ownOutputs: string[]
+  ownOutputs: readonly string[]
   /** Root-relative `outputs.workspaceFiles` globs to exclude from
    *  `inputs.workspaceFiles` (a task cannot invalidate itself). */
-  ownWorkspaceOutputs?: string[]
+  ownWorkspaceOutputs?: readonly string[]
   /** Absolute dirs of nested projects (cross-boundary isolation). */
   nestedProjectDirs: string[]
   /**
@@ -646,7 +646,7 @@ function outputExcludes(outputs: readonly string[]): Bun.Glob[] {
 /** Resolve declared output globs (project-relative) to actual produced files. */
 export async function resolveOutputs(args: {
   projectDir: string
-  outputs: string[]
+  outputs: readonly string[]
   nestedProjectDirs: string[]
 }): Promise<string[]> {
   const { positive, negative } = splitNegations(args.outputs)
@@ -747,7 +747,7 @@ function isInside(dir: string, abs: string): boolean {
  */
 export async function cleanOutputs(args: {
   projectDir: string
-  outputs: string[]
+  outputs: readonly string[]
   nestedProjectDirs: string[]
 }): Promise<string[]> {
   const files = await resolveOutputs(args)
@@ -801,7 +801,7 @@ export interface OutputStamp {
  */
 export async function stampOutputs(args: {
   projectDir: string
-  outputs: string[]
+  outputs: readonly string[]
   nestedProjectDirs: string[]
 }): Promise<Map<string, OutputStamp>> {
   return stampFiles(await resolveOutputs(args))
@@ -810,7 +810,7 @@ export async function stampOutputs(args: {
 /** `stampOutputs` for root-anchored `cache.outputs.workspaceFiles` (A-43). */
 export async function stampWorkspaceOutputs(args: {
   workspaceRoot: string
-  outputs: string[]
+  outputs: readonly string[]
 }): Promise<Map<string, OutputStamp>> {
   return stampFiles(await resolveWorkspaceOutputs(args))
 }
@@ -841,7 +841,7 @@ function stampFiles(files: readonly string[]): Map<string, OutputStamp> {
  * file back, so no entry reproduces that run and none is saved.
  */
 export async function ownOutputsSince(
-  args: { projectDir: string; outputs: string[]; nestedProjectDirs: string[] },
+  args: { projectDir: string; outputs: readonly string[]; nestedProjectDirs: string[] },
   before: ReadonlyMap<string, OutputStamp>,
 ): Promise<string[] | undefined> {
   return changedSince(await resolveOutputs(args), before)
@@ -849,7 +849,7 @@ export async function ownOutputsSince(
 
 /** `ownOutputsSince` for root-anchored `cache.outputs.workspaceFiles` (A-43). */
 export async function ownWorkspaceOutputsSince(
-  args: { workspaceRoot: string; outputs: string[] },
+  args: { workspaceRoot: string; outputs: readonly string[] },
   before: ReadonlyMap<string, OutputStamp>,
 ): Promise<string[] | undefined> {
   return changedSince(await resolveWorkspaceOutputs(args), before)
@@ -1067,7 +1067,7 @@ function inScope(dir: string, scope: PruneScope): boolean {
  */
 export async function resolveWorkspaceOutputs(args: {
   workspaceRoot: string
-  outputs: string[]
+  outputs: readonly string[]
 }): Promise<string[]> {
   const { positive, negative } = splitNegations(args.outputs)
   if (positive.length === 0) return []
@@ -1090,7 +1090,7 @@ export async function resolveWorkspaceOutputs(args: {
  */
 export async function cleanWorkspaceOutputs(args: {
   workspaceRoot: string
-  outputs: string[]
+  outputs: readonly string[]
 }): Promise<string[]> {
   const files = await resolveWorkspaceOutputs(args)
   await pruneEmptiedDirs(
@@ -1195,8 +1195,8 @@ async function assertNoInvisibleLiteralInputs(
 interface ResolveFilesArgs {
   projectDir: string
   workspaceRoot: string
-  files: string[] | undefined
-  ownOutputs: string[]
+  files: readonly string[] | undefined
+  ownOutputs: readonly string[]
   /** Root-relative `outputs.workspaceFiles`, and the project's root-relative directory. */
   ownWorkspaceOutputs: readonly string[]
   projectRel: string

package/src/cache/layer.ts

@@ -296,7 +296,8 @@ export interface PruneOptions {
   olderThanMs?: number
   /**
    * After applying olderThanMs, if the cache still exceeds this size in
-   * bytes, evict LRU (smallest `accessed_at` first) until under it.
+   * bytes, evict LRU (smallest `accessed_at` first, a row-less artifact
+   * by its file time) until under it.
    */
   maxBytes?: number
   /**
@@ -312,10 +313,11 @@ export interface PruneResult {
   /** Bytes the evicted entries occupied, per the index. */
   bytesFreed: number
   /**
-   * Artifacts and temp files with no index row, unlinked by the orphan
-   * sweep that runs after eviction (a `SCHEMA_VERSION` drop, a deleted
-   * `cache.db`, a save that crashed before its rename). Files younger
-   * than one hour are never counted: they may be a save in flight.
+   * Artifacts and temp files with no index row, unlinked by the same
+   * policy (another vx version's open dropped the row, a deleted
+   * `cache.db`, a save that crashed before its rename). An artifact's file
+   * time plus an hour stands for its last use; a temp goes once an hour
+   * old. Files younger than one hour are never counted.
    */
   orphans: number
   /** Bytes the reaped orphans occupied on disk. */

package/src/cache/policy.ts

@@ -36,6 +36,11 @@ export const FULL_CACHE_POLICY: CachePolicy = {
   remoteWrite: true,
 }
 
+/** No axis on (`--no-cache`, `--cache=local:`): no cache answers for any task. */
+export function cachesNothing(p: CachePolicy): boolean {
+  return !(p.localRead || p.localWrite || p.remoteRead || p.remoteWrite)
+}
+
 /**
  * Parse a `--cache=<spec>` value into a `CachePolicy`, starting from a
  * base (defaults to {@link FULL_CACHE_POLICY}). The spec is a

package/src/cache/zstd.ts

@@ -194,15 +194,21 @@ export async function decodedTar(
     }
     return oneChunk(await zstdDecompressBounded(source, hash, cap))
   }
+  // A BunFile reads no further than the size its first stat cached, and a
+  // save or ingest of the same key may rename a longer copy over the path
+  // after that stat: the read came back cut short, the restore called the
+  // new artifact corrupt and dropped it. The size only picks the decode;
+  // each read goes through a handle that has not stat the path yet.
+  const fresh = (): Bun.BunFile => Bun.file(source.name!)
   if (source.size <= STREAM_DECODE_FROM) {
-    const bytes = await source.bytes()
+    const bytes = await fresh().bytes()
     if (assertDeclaredSize(bytes, hash, cap) === null || !isOneFrame(bytes)) {
-      return zstdDecodeStream(source, hash, cap)
+      return zstdDecodeStream(new Blob([bytes]), hash, cap)
     }
     return oneChunk(await zstdDecompressBounded(bytes, hash, cap))
   }
-  assertDeclaredSize(await source.slice(0, 32).bytes(), hash, cap)
-  return zstdDecodeStream(source, hash, cap)
+  assertDeclaredSize(await fresh().slice(0, 32).bytes(), hash, cap)
+  return zstdDecodeStream(fresh(), hash, cap)
 }
 
 /**