@vzn/vx 0.0.15 → 0.0.18

package/src/cache/layered-cache.ts

@@ -23,6 +23,7 @@ import type {
   CacheLayer,
   CachePolicy,
   CacheStats,
+  CacheStatsOptions,
   IngestMeta,
   InvocationRecord,
   OutputFileRow,
@@ -31,7 +32,7 @@ import type {
   RunRecord,
   SaveArgs,
 } from './cache.js'
-import { FULL_CACHE_POLICY } from './cache.js'
+import { FULL_CACHE_POLICY, type OutputDirRow } from './cache.js'
 
 /**
  * What a remote cache layer must provide — THE plugin seam for remote
@@ -47,6 +48,15 @@ import { FULL_CACHE_POLICY } from './cache.js'
 export interface RemoteCacheLayer {
   /** Existence probe (drives the plan path's `--dry` remote prediction). */
   has(hash: string): Promise<boolean>
+  /**
+   * Optional batch existence probe: given N hashes, return the subset stored
+   * remotely in ONE round-trip. Lets the prefetch pass collapse N per-hash
+   * network probes into one, then fetch only the hits. A remote that can't
+   * batch omits this method (or returns `null`) and the layer falls back to
+   * the per-hash path. Never throws for control flow — `null` means "no batch
+   * info; use per-hash".
+   */
+  hasMany?(hashes: readonly string[]): Promise<Set<string> | null>
   /** Fetch an artifact's bytes; `null` = miss. `durationMs` is the
    *  producing task's duration when the wire carries it. */
   get(hash: string): Promise<{ body: ArrayBuffer; durationMs: number | undefined } | null>
@@ -73,6 +83,9 @@ export interface LayeredCacheOptions {
 }
 
 export class LayeredCache implements CacheLayer {
+  /** A remote layer is composed in by construction — see `CacheLayer.hasRemote`. */
+  readonly hasRemote = true
+
   /**
    * In-flight remote pulls keyed by hash. `prefetch` and `get` both go
    * through here, so a key probed concurrently by both resolves a
@@ -109,7 +122,7 @@ export class LayeredCache implements CacheLayer {
   private readonly policy: CachePolicy
 
   constructor(
-    private readonly local: Cache,
+    readonly local: Cache,
     private readonly remote: RemoteCacheLayer,
     private readonly options: LayeredCacheOptions = {},
   ) {
@@ -123,9 +136,45 @@ export class LayeredCache implements CacheLayer {
   async prefetch(hash: string, ctx?: CacheGetContext): Promise<boolean> {
     // No-op when remote reads are off — there's nothing to warm from.
     if (!this.policy.remoteRead) return false
+    // The local-first skip lives in doPullFromRemote (the shared choke
+    // point): pullFromRemote registers the `inflight` entry SYNCHRONOUSLY,
+    // so a concurrent markRemoteAbsent can't clobber a pending pull — a
+    // guard done here (behind an async local.has) would reopen that race.
     return await this.pullFromRemote(hash, ctx)
   }
 
+  /**
+   * Batch existence probe over the remote layer — the subset of `hashes`
+   * present remotely, in one round-trip, or `null` when the remote can't
+   * batch (no `hasMany`, reads disabled, or an error). The prefetch pass uses
+   * this to fetch only the hits and to pre-mark the misses (`markRemoteAbsent`)
+   * so their lazy `get` skips the network. Never throws — a batch failure
+   * degrades to "no batch info" and the caller falls back to per-hash.
+   */
+  async remoteHasMany(hashes: readonly string[]): Promise<Set<string> | null> {
+    if (!this.policy.remoteRead || this.remote.hasMany === undefined) return null
+    try {
+      return await this.remote.hasMany(hashes)
+    } catch (err) {
+      this.reportRemoteError(err)
+      return null
+    }
+  }
+
+  /**
+   * Record that the remote layer has NO artifact for each of `hashes` (from a
+   * batch probe), so a later `get`/`prefetch` short-circuits to a miss WITHOUT
+   * a network round-trip. Byte-for-byte equivalent to a background prefetch GET
+   * having resolved `false` into `inflight` — same at-most-once semantics, same
+   * point-in-time staleness window — but without spending the GET. Never
+   * overwrites an entry already in flight.
+   */
+  markRemoteAbsent(hashes: Iterable<string>): void {
+    for (const hash of hashes) {
+      if (!this.inflight.has(hash)) this.inflight.set(hash, Promise.resolve(false))
+    }
+  }
+
   async get(hash: string, ctx?: CacheGetContext): Promise<CacheEntry | null> {
     const localHit = await this.local.get(hash, ctx)
     if (localHit) {
@@ -147,11 +196,23 @@ export class LayeredCache implements CacheLayer {
     const ingested = await this.pullFromRemote(hash, ctx)
     if (!ingested) return null
 
-    // The artifact is now in local, but this *lookup* was a remote
-    // hit — flip the source so callers can distinguish "saved work
-    // via the remote cache" from "saved work via a prior local run".
-    const materialized = await this.local.get(hash, ctx)
-    return materialized ? { ...materialized, source: 'remote' } : null
+    // Read past the local READ gate: `ingest` is deliberately ungated, so
+    // the artifact + index row this pull just wrote exist regardless of
+    // policy, and the gate ("don't serve hits from the pre-existing local
+    // cache") must not discard them. Going through the gated `get` here
+    // made `--cache=local:,remote:rw` download the artifact, throw the hit
+    // away, re-execute and re-upload — on every run, forever.
+    const materialized = await this.local.getIngested(hash)
+    if (!materialized) return null
+
+    // `remoteSourced` — not merely "the pull returned true" — is what says
+    // the remote cache saved this work. `doPullFromRemote` also returns true
+    // for its local-first skip, which issues NO remote GET: when a run
+    // sharing this cache dir ingests the artifact between the local read
+    // above and that skip's `local.has`, stamping 'remote' here reported a
+    // purely-local hit as `cache-hit-remote` and inflated the remote
+    // hit-rate. Whatever provenance the entry has is the truth.
+    return this.remoteSourced.has(hash) ? { ...materialized, source: 'remote' } : materialized
   }
 
   // Existence probe: local first, then a remote HEAD — no body
@@ -185,6 +246,16 @@ export class LayeredCache implements CacheLayer {
   }
 
   private async doPullFromRemote(hash: string, ctx?: CacheGetContext): Promise<boolean> {
+    // Local-first, mirroring get()/has(): if local ALREADY holds the artifact
+    // there is nothing to pull — skip the remote GET (a warm-local run would
+    // otherwise re-download every artifact it already has) and DON'T mark it
+    // `remoteSourced` (that would mislabel a purely-local warm hit as
+    // cache-hit-remote and inflate the remote hit-rate). Returning `true` is
+    // correct for a get() read-through too: "the artifact is in local" — the
+    // caller re-reads it, keeping whatever provenance it already had (local,
+    // or remote if a concurrent prefetch set it).
+    if ((await this.local.has(hash)) === 'local') return true
+
     let remoteResult
     try {
       remoteResult = await this.remote.get(hash)
@@ -233,32 +304,48 @@ export class LayeredCache implements CacheLayer {
   }
 
   async save(args: SaveArgs): Promise<void> {
-    // Local write honors its own gate inside Cache.save (no-op when
-    // local writes are disabled).
+    // Local write honors its own gates inside Cache.save (no-op when local
+    // writes are disabled, or when ChainedCache marked this a duplicate save
+    // to a shared local handle — see `skipLocalWrite` on the contract).
     await this.local.save(args)
     if (!this.policy.remoteWrite) return
-    // Write-through upload, OFF the task's critical path. The bytes are
-    // captured NOW — read from the artifact the local layer just wrote
-    // (same format on both sides, no repacking), or, when local writes
-    // are disabled (`--cache=local:,remote:rw`), packed in memory while
-    // the output files are guaranteed still on disk. The PUT itself then
-    // runs in the bounded background pool so the task's worker slot is
-    // released immediately; `run()` awaits `drainUploads()` before
-    // closing the cache. Errors are logged, not propagated: the task
-    // already succeeded; we don't fail it on cache-server issues.
-    let bytes: Uint8Array
-    try {
-      bytes = this.local.localWritesEnabled
-        ? await Bun.file(this.local.outputsPath(args.hash)).bytes()
-        : await this.local.packArtifactBytes(args)
-    } catch (err) {
-      this.reportRemoteError(err)
-      return
-    }
+    // Write-through upload, OFF the task's critical path: the PUT runs in
+    // the bounded background pool so the task's worker slot is released
+    // immediately, and `run()` awaits `drainUploads()` before closing the
+    // cache. Errors are logged, not propagated: the task already
+    // succeeded; we don't fail it on cache-server issues.
+    //
+    // The artifact bytes are read INSIDE the job, not here.
+    // UPLOAD_CONCURRENCY bounds sockets, not memory: a queued closure
+    // holding its own artifact keeps the WHOLE backlog resident, so peak
+    // RSS scaled with a run's total miss artifact bytes rather than with
+    // the pool — any cold monorepo run whose remote uploads slower than the
+    // build produces artifacts held every pending one at once. Reading in
+    // the job caps resident artifact bytes at UPLOAD_CONCURRENCY. The
+    // artifact is content-addressed and immutable, so a deferred read sees
+    // the same bytes; if a concurrent `vx cache prune` removed it first the
+    // read throws and this upload is skipped — the never-fail contract.
+    const hash = args.hash
     const durationMs = args.entry.durationMs
+    // Local writes disabled (`--cache=local:,remote:rw`): there is no
+    // on-disk artifact to read later, so the bytes must be packed NOW,
+    // while this task's output files are still on disk. Deferring THIS
+    // read would pack whatever the tree happens to hold when the job
+    // runs. Such a run keeps the old memory profile by necessity — the
+    // bytes exist nowhere else.
+    let packed: Uint8Array | undefined
+    if (!this.local.localWritesEnabled) {
+      try {
+        packed = await this.local.packArtifactBytes(args)
+      } catch (err) {
+        this.reportRemoteError(err)
+        return
+      }
+    }
     this.enqueueUpload(async () => {
       try {
-        await this.remote.put(args.hash, bytes, { durationMs })
+        const bytes = packed ?? (await Bun.file(this.local.outputsPath(hash)).bytes())
+        await this.remote.put(hash, bytes, { durationMs })
       } catch (err) {
         this.reportRemoteError(err)
       }
@@ -311,6 +398,18 @@ export class LayeredCache implements CacheLayer {
     return this.local.isOutputsCurrent(projectDir, expected)
   }
 
+  recordOutputDirs(hash: string, projectDir: string, prefixes: readonly string[]): Promise<void> {
+    return this.local.recordOutputDirs(hash, projectDir, prefixes)
+  }
+
+  loadOutputDirsBatch(hashes: readonly string[]): Map<string, OutputDirRow[]> {
+    return this.local.loadOutputDirsBatch(hashes)
+  }
+
+  outputDirsCurrent(projectDir: string, rows: readonly OutputDirRow[]): Promise<boolean> {
+    return this.local.outputDirsCurrent(projectDir, rows)
+  }
+
   recordRun(run: RunRecord): void {
     this.local.recordRun(run)
   }
@@ -323,8 +422,8 @@ export class LayeredCache implements CacheLayer {
     this.local.recordRunBundle(bundle)
   }
 
-  stats(): CacheStats {
-    return this.local.stats()
+  stats(opts?: CacheStatsOptions): CacheStats {
+    return this.local.stats(opts)
   }
 
   async prune(options: PruneOptions): Promise<PruneResult> {

package/src/cache/tar-stream.ts

@@ -0,0 +1,358 @@
+// A streaming tar reader for the restore path. `Bun.Archive` needs the whole
+// tar in memory and `.files()` copies every entry, so restoring a 150 MiB
+// artifact peaked at 3.2× its size (measured 2026-09-03). This reads the
+// tar as it streams out of the zstd decoder and hands each entry's body to
+// the caller as chunks, so memory is bounded by one chunk, not the archive.
+//
+// Dialect: what libarchive (Bun.Archive) writes — ustar with the name/prefix
+// split, pax extended headers (`x`: path, size) past ustar's limits — plus
+// GNU long names (`L`) for foreign artifacts. Every header's checksum is
+// verified; an archive that ends before its data does is an error, never a
+// short entry. Non-regular entries are reported with their type and their
+// bodies skipped; the caller decides what to materialise (nothing but `0`).
+
+export interface TarEntry {
+  name: string
+  size: number
+  /** POSIX typeflag: '0' regular, '5' directory, '2' symlink, … */
+  type: string
+  /** Header mtime in ms (second precision — the sidecar carries the real one). */
+  mtimeMs: number
+  /** The entry's bytes, in stream order. Must be drained before the next entry. */
+  body: AsyncIterable<Uint8Array>
+}
+
+export class TarFormatError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'TarFormatError'
+  }
+}
+
+const BLOCK = 512
+const decoder = new TextDecoder()
+
+function field(h: Uint8Array, off: number, len: number): string {
+  let end = off
+  while (end < off + len && h[end] !== 0) end++
+  return decoder.decode(h.subarray(off, end))
+}
+
+function octal(h: Uint8Array, off: number, len: number): number {
+  // GNU base-256 (high bit set) for sizes ≥ 8 GiB.
+  if (h[off]! & 0x80) {
+    let n = 0
+    for (let i = off + 1; i < off + len; i++) n = n * 256 + h[i]!
+    return n
+  }
+  const s = field(h, off, len).trim()
+  if (s === '') return 0
+  // Every digit, not the longest parseable prefix: `parseInt` would read
+  // a corrupt `5zz` as 5 and let the damage surface later, if at all.
+  if (!/^[0-7]+$/.test(s)) throw new TarFormatError(`bad octal field: ${JSON.stringify(s)}`)
+  return parseInt(s, 8)
+}
+
+function checksumOk(h: Uint8Array): boolean {
+  const stored = octal(h, 148, 8)
+  let sum = 0
+  for (let i = 0; i < BLOCK; i++) sum += i >= 148 && i < 156 ? 32 : h[i]!
+  return sum === stored
+}
+
+/** pax `x` body: `<len> <key>=<value>\n` records. */
+function parsePax(body: Uint8Array): Map<string, string> {
+  const out = new Map<string, string>()
+  let i = 0
+  while (i < body.byteLength) {
+    let sp = i
+    while (sp < body.byteLength && body[sp] !== 32) sp++
+    const len = Number(decoder.decode(body.subarray(i, sp)))
+    if (!Number.isInteger(len) || len <= 0 || i + len > body.byteLength) {
+      throw new TarFormatError('malformed pax record')
+    }
+    const rec = decoder.decode(body.subarray(sp + 1, i + len - 1))
+    const eq = rec.indexOf('=')
+    if (eq > 0) out.set(rec.slice(0, eq), rec.slice(eq + 1))
+    i += len
+  }
+  return out
+}
+
+/** A byte source with exact-size reads over a stream of arbitrary chunks. */
+class Source {
+  private chunks: Uint8Array[] = []
+  private head = 0
+  private done = false
+  constructor(private readonly reader: AsyncIterator<Uint8Array>) {}
+
+  private async fill(): Promise<boolean> {
+    if (this.done) return false
+    const { done, value } = await this.reader.next()
+    if (done === true || value === undefined) {
+      this.done = true
+      return false
+    }
+    if (value.byteLength > 0) this.chunks.push(value)
+    return true
+  }
+
+  /** Exactly `n` bytes, or null at a clean end (nothing buffered), or a TarFormatError mid-entry. */
+  async exact(n: number, what: string): Promise<Uint8Array | null> {
+    const out = new Uint8Array(n)
+    let got = 0
+    while (got < n) {
+      if (this.chunks.length === 0 && !(await this.fill())) {
+        if (got === 0) return null
+        throw new TarFormatError(`archive ends inside ${what} (${got} of ${n} bytes)`)
+      }
+      const c = this.chunks[0]!
+      const take = Math.min(n - got, c.byteLength - this.head)
+      out.set(c.subarray(this.head, this.head + take), got)
+      got += take
+      this.head += take
+      if (this.head === c.byteLength) {
+        this.chunks.shift()
+        this.head = 0
+      }
+    }
+    return out
+  }
+
+  /** Up to `n` bytes as they arrive (never more), for streaming a body. */
+  async *take(n: number, what: string): AsyncIterable<Uint8Array> {
+    let left = n
+    while (left > 0) {
+      if (this.chunks.length === 0 && !(await this.fill())) {
+        throw new TarFormatError(`archive ends inside ${what} (${n - left} of ${n} bytes)`)
+      }
+      const c = this.chunks[0]!
+      const take = Math.min(left, c.byteLength - this.head)
+      const piece = c.subarray(this.head, this.head + take)
+      left -= take
+      this.head += take
+      if (this.head === c.byteLength) {
+        this.chunks.shift()
+        this.head = 0
+      }
+      yield piece
+    }
+  }
+}
+
+/**
+ * Iterate a tar stream entry by entry. Each entry's `body` MUST be fully
+ * consumed (or the iterator drains it) before the next entry is read.
+ */
+export async function* tarEntries(stream: ReadableStream<Uint8Array>): AsyncGenerator<TarEntry> {
+  const src = new Source(stream[Symbol.asyncIterator]())
+  let pendingPath: string | undefined
+  let pendingSize: number | undefined
+  let zeroBlocks = 0
+  for (;;) {
+    const h = await src.exact(BLOCK, 'a header')
+    if (h === null) {
+      if (zeroBlocks === 0) throw new TarFormatError('archive has no end-of-archive marker')
+      return
+    }
+    if (h.every((b) => b === 0)) {
+      zeroBlocks++
+      if (zeroBlocks >= 2) return
+      continue
+    }
+    zeroBlocks = 0
+    if (!checksumOk(h)) throw new TarFormatError('header checksum mismatch')
+    const type = h[156] === 0 ? '0' : String.fromCharCode(h[156]!)
+    const size = pendingSize ?? octal(h, 124, 12)
+    const mtimeMs = octal(h, 136, 12) * 1000
+    const padded = Math.ceil(size / BLOCK) * BLOCK
+    const magic = field(h, 257, 6)
+    const prefix = magic.startsWith('ustar') ? field(h, 345, 155) : ''
+    const rawName = field(h, 0, 100)
+    let name = pendingPath ?? (prefix ? `${prefix}/${rawName}` : rawName)
+    pendingPath = undefined
+    pendingSize = undefined
+
+    if (type === 'x' || type === 'L') {
+      // Extended header: applies to the NEXT entry only.
+      const body = await src.exact(padded, 'an extended header')
+      if (body === null) throw new TarFormatError('archive ends inside an extended header')
+      if (type === 'x') {
+        const pax = parsePax(body.subarray(0, size))
+        const p = pax.get('path')
+        if (p !== undefined) pendingPath = p
+        const s = pax.get('size')
+        if (s !== undefined) pendingSize = Number(s)
+      } else {
+        pendingPath = field(body, 0, size)
+      }
+      continue
+    }
+    if (type === 'g') {
+      // pax global header: not used by Bun.Archive; skip its body.
+      await src.exact(padded, 'a global header')
+      continue
+    }
+    name = name.replace(/\/+$/, type === '5' ? '/' : '')
+
+    let drained = false
+    const body = (async function* (): AsyncIterable<Uint8Array> {
+      if (size > 0) for await (const c of src.take(size, `entry ${name}`)) yield c
+      const pad = padded - size
+      if (pad > 0 && (await src.exact(pad, `padding after ${name}`)) === null) {
+        throw new TarFormatError(`archive ends inside padding after ${name}`)
+      }
+      drained = true
+    })()
+    yield { name, size, type, mtimeMs, body }
+    if (!drained) {
+      // The caller skipped this body: drain it so the next header lines up.
+      for await (const _ of body) {
+        // discard
+      }
+    }
+  }
+}
+
+// ─── Writer ───────────────────────────────────────────────────────────
+
+/** One regular file to pack. `body` is read as it is written. */
+export interface TarInput {
+  name: string
+  size: number
+  /** Permission bits; the sidecar carries the exact value, this is for foreign readers. */
+  mode?: number
+  /** Seconds since epoch; the sidecar carries the millisecond value. */
+  mtime?: number
+  body: Blob | Uint8Array | string
+}
+
+const encoder = new TextEncoder()
+
+function writeOctal(h: Uint8Array, off: number, len: number, n: number): void {
+  const digits = n.toString(8).padStart(len - 1, '0')
+  if (digits.length > len - 1)
+    throw new TarFormatError(`value ${n} does not fit a ${len}-byte field`)
+  h.set(encoder.encode(digits), off)
+  h[off + len - 1] = 0
+}
+
+function header(
+  name: string | Uint8Array,
+  size: number,
+  type: string,
+  mode: number,
+  mtime: number,
+): Uint8Array {
+  const h = new Uint8Array(BLOCK)
+  const nameBytes = typeof name === 'string' ? encoder.encode(name) : name
+  if (nameBytes.byteLength <= 100) {
+    h.set(nameBytes, 0)
+  } else {
+    // ustar prefix split: the longest tail that fits 100 bytes, split at
+    // a `/`, with the head fitting 155. Anything else needs pax.
+    const cut = splitForUstar(nameBytes)
+    if (cut === null)
+      throw new TarFormatError(`name too long for ustar: ${decoder.decode(nameBytes)}`)
+    h.set(nameBytes.subarray(cut + 1), 0)
+    h.set(nameBytes.subarray(0, cut), 345)
+  }
+  writeOctal(h, 100, 8, mode & 0o7777)
+  writeOctal(h, 108, 8, 0)
+  writeOctal(h, 116, 8, 0)
+  writeOctal(h, 124, 12, size)
+  writeOctal(h, 136, 12, mtime)
+  h[156] = type.charCodeAt(0)
+  h.set(encoder.encode('ustar\0'), 257)
+  h.set(encoder.encode('00'), 263)
+  h.fill(32, 148, 156)
+  let sum = 0
+  for (let i = 0; i < BLOCK; i++) sum += h[i]!
+  h.set(encoder.encode(sum.toString(8).padStart(6, '0')), 148)
+  h[154] = 0
+  h[155] = 32
+  return h
+}
+
+/** Byte index of the `/` to split at, or null when no split satisfies both fields. */
+function splitForUstar(name: Uint8Array): number | null {
+  for (let i = name.byteLength - 1; i > 0; i--) {
+    if (name[i] !== 47) continue
+    const tail = name.byteLength - i - 1
+    if (tail > 100) return null
+    if (tail >= 1 && i <= 155) return i
+  }
+  return null
+}
+
+function paxRecord(key: string, value: string): Uint8Array {
+  const body = encoder.encode(` ${key}=${value}\n`)
+  let len = body.byteLength + 1
+  while (String(len).length + body.byteLength !== len) len = String(len).length + body.byteLength
+  const out = new Uint8Array(len)
+  out.set(encoder.encode(String(len)), 0)
+  out.set(body, String(len).length)
+  return out
+}
+
+const padding = (size: number): Uint8Array => new Uint8Array((BLOCK - (size % BLOCK)) % BLOCK)
+const padded = (size: number): number => size + ((BLOCK - (size % BLOCK)) % BLOCK)
+
+/** Whether `name` needs a pax `path` record (fits neither ustar field). */
+function needsPax(name: string): boolean {
+  const bytes = encoder.encode(name)
+  return bytes.byteLength > 100 && splitForUstar(bytes) === null
+}
+
+/** The exact number of bytes `tarPack` writes for these inputs. */
+export function tarSize(inputs: readonly TarInput[]): number {
+  let size = BLOCK * 2
+  for (const i of inputs) {
+    if (needsPax(i.name)) size += BLOCK + padded(paxRecord('path', i.name).byteLength)
+    size += BLOCK + padded(i.size)
+  }
+  return size
+}
+
+/**
+ * Pack regular files as a tar stream: ustar with the name/prefix split,
+ * a pax `path` record when a name fits neither field — exactly the
+ * dialect `tarEntries` reads — and the two-block end marker. Bodies are
+ * streamed, so memory is bounded by a chunk, never by an entry.
+ */
+export async function* tarPack(
+  inputs: AsyncIterable<TarInput> | Iterable<TarInput>,
+): AsyncGenerator<Uint8Array> {
+  for await (const input of inputs) {
+    const mode = input.mode ?? 0o644
+    const mtime = input.mtime ?? 0
+    // Under a pax record the ustar name is a courtesy for readers that
+    // ignore pax: its first 100 BYTES, never characters — a multibyte
+    // name sliced by characters can be over 100 bytes again.
+    let headerName: string | Uint8Array = input.name
+    if (needsPax(input.name)) {
+      const pax = paxRecord('path', input.name)
+      yield header('PaxHeaders/entry', pax.byteLength, 'x', 0o644, mtime)
+      yield pax
+      yield padding(pax.byteLength)
+      headerName = encoder.encode(input.name).subarray(0, 100)
+    }
+    yield header(headerName, input.size, '0', mode, mtime)
+    if (input.body instanceof Blob) {
+      let n = 0
+      for await (const chunk of input.body.stream()) {
+        n += chunk.byteLength
+        yield chunk
+      }
+      if (n !== input.size)
+        throw new TarFormatError(`${input.name}: ${n} bytes read, ${input.size} declared`)
+    } else {
+      const bytes = typeof input.body === 'string' ? encoder.encode(input.body) : input.body
+      if (bytes.byteLength !== input.size)
+        throw new TarFormatError(`${input.name}: ${bytes.byteLength} bytes, ${input.size} declared`)
+      yield bytes
+    }
+    yield padding(input.size)
+  }
+  yield new Uint8Array(BLOCK * 2)
+}

package/src/cli/cache.ts

@@ -1,5 +1,5 @@
 import { Cache } from '../cache/index.js'
-import { parseSize } from '../util/index.js'
+import { parseDecimalInt, parseSize } from '../util/index.js'
 import { findWorkspaceRoot, loadWorkspaceConfig, resolveCacheDir } from '../workspace/index.js'
 import { formatBytes } from './format.js'
 
@@ -31,17 +31,35 @@ export function parsePruneArgs(args: readonly string[]): PruneArgs {
   const out: PruneArgs = {}
   for (let i = 0; i < args.length; i++) {
     const a = args[i]
-    if (a === '--older-than') {
-      const v = args[++i]
-      if (v === undefined) return { error: `${a} requires a value (e.g. 30d, 24h, 60m)` }
+    if (a === '--older-than' || a?.startsWith('--older-than=')) {
+      const v = a === '--older-than' ? args[++i] : a.slice('--older-than='.length)
+      if (v === undefined || v === '') {
+        return { error: `--older-than requires a value (e.g. 30d, 24h, 60m)` }
+      }
       const ms = parseDuration(v)
       if (ms === null) return { error: `invalid duration: ${v}` }
+      // `0d` evicts everything ever cached. That is far more often a
+      // computed-to-zero retention than an intent, and no other flag
+      // combination expresses "wipe the cache" — so refuse it and name
+      // the deliberate way to do it.
+      if (ms === 0) {
+        return {
+          error: `--older-than 0 would evict every entry — delete the cache directory instead`,
+        }
+      }
       out.olderThanMs = Date.now() - ms
-    } else if (a === '--max-size') {
-      const v = args[++i]
-      if (v === undefined) return { error: `${a} requires a value (e.g. 500M, 1G)` }
+    } else if (a === '--max-size' || a?.startsWith('--max-size=')) {
+      const v = a === '--max-size' ? args[++i] : a.slice('--max-size='.length)
+      if (v === undefined || v === '') {
+        return { error: `--max-size requires a value (e.g. 500M, 1G)` }
+      }
       const bytes = parseSize(v)
       if (bytes === null) return { error: `invalid size: ${v}` }
+      if (bytes === 0) {
+        return {
+          error: `--max-size 0 would evict every entry — delete the cache directory instead`,
+        }
+      }
       out.maxBytes = bytes
     } else {
       return { error: `unknown argument: ${a}` }
@@ -86,11 +104,19 @@ async function pruneCmd(args: readonly string[]): Promise<number> {
   return 0
 }
 
+/**
+ * Parse `<n><unit>` where unit is s/m/h/d, case-insensitively (`parseSize`
+ * has always been case-insensitive; this matched only lowercase, so `30D`
+ * was rejected while `1GB` and `1gb` both worked).
+ */
 export function parseDuration(input: string): number | null {
-  const m = input.match(/^(\d+)([smhd])$/)
+  const m = input.match(/^(\d+)([smhd])$/i)
   if (!m) return null
-  const n = Number(m[1])
-  const unit = m[2]
+  const n = parseDecimalInt(m[1]!)
+  if (n === null) return null
+  // Lowercase before the switch: with the /i flag an uppercase `M` would
+  // otherwise fall through to the days branch.
+  const unit = m[2]!.toLowerCase()
   const mult = unit === 's' ? 1000 : unit === 'm' ? 60_000 : unit === 'h' ? 3_600_000 : 86_400_000
   return n * mult
 }