@vzn/vx 0.0.16 → 0.0.21

package/src/cache/run-history.ts

@@ -0,0 +1,147 @@
+// The run history: one `runs` row per task outcome and one `invocations`
+// header per `vx run`, written together, plus their 30-day retention.
+// What `vx why`, `vx last`, `stats` and the history reader read. Owns
+// its statements over the store's handle; `Cache` delegates.
+
+import type { Database, SQLQueryBindings } from 'bun:sqlite'
+import type { InvocationRecord, RunRecord } from './layer.js'
+
+export class RunHistory {
+  private readonly insertRun: ReturnType<Database['prepare']>
+  private readonly insertInvocation: ReturnType<Database['prepare']>
+
+  constructor(private readonly db: Database) {
+    this.insertRun = this.db.prepare(`
+      INSERT INTO runs(
+        hash, project, task, status, exit_code, duration_ms, forward_args,
+        started_at, ended_at,
+        run_id, cpu_ms, peak_rss_bytes, wallclock_start_ns, wallclock_end_ns,
+        cache_hit, attempts, cached
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?,  ?, ?, ?, ?, ?,  ?, ?, ?)
+    `)
+    this.insertInvocation = this.db.prepare(`
+      INSERT INTO invocations(
+        run_id, command, requested_tasks, cache_policy, concurrency, flow,
+        started_at, ended_at, total_duration_ms,
+        task_count, failed_count, hit_count, hit_local_count, hit_remote_count,
+        exit_ok,
+        commit_sha, branch, dirty, ci, ci_provider,
+        host, os, arch, vx_version, tags
+      )
+      VALUES (?, ?, ?, ?, ?, ?,  ?, ?, ?,  ?, ?, ?, ?, ?,  ?,  ?, ?, ?, ?, ?,  ?, ?, ?, ?, ?)
+      ON CONFLICT(run_id) DO NOTHING
+    `)
+  }
+
+  recordRun(run: RunRecord): void {
+    this.insertRun.run(...bindRun(run))
+  }
+
+  recordRuns(runs: readonly RunRecord[]): void {
+    if (runs.length === 0) return
+    if (runs.length === 1) {
+      this.insertRun.run(...bindRun(runs[0]!))
+      return
+    }
+    // `bun:sqlite`'s `transaction()` returns a callable that wraps the
+    // body in BEGIN/COMMIT, fsyncing once at the end. For a 200-task
+    // run that's one fsync instead of 200.
+    const insert = this.insertRun
+    const tx = this.db.transaction((batch: readonly RunRecord[]) => {
+      for (const r of batch) insert.run(...bindRun(r))
+    })
+    tx(runs)
+  }
+
+  recordRunBundle(bundle: { runs: readonly RunRecord[]; invocation: InvocationRecord }): void {
+    // Whole run records atomically — one transaction, one fsync: the
+    // per-task `runs` rows and the one `invocations` header. The
+    // input-fingerprint rows do NOT live here: they're written inside
+    // the entry-save transaction (`save`/`ingest`) so a warm
+    // all-cache-hit run — which writes no `runs`-vs-`entry_inputs`
+    // mismatch — pays nothing for the moat it isn't refreshing.
+    const insertRun = this.insertRun
+    const insertInvocation = this.insertInvocation
+    this.db.transaction(() => {
+      for (const r of bundle.runs) insertRun.run(...bindRun(r))
+      insertInvocation.run(...bindInvocation(bundle.invocation))
+    })()
+  }
+
+  /**
+   * Retention: the runs table grows by one row per executed task per
+   * invocation — a 2000-task repo accretes ~20k rows in days. 30 days
+   * covers `vx stats` (24 h windows) and CI-side consumers. The
+   * `invocations` header is pruned on the SAME window, or a header would
+   * outlive its rows and `vx last` would list a run whose detail is gone.
+   */
+  pruneOlderThan(cutoff: number): void {
+    this.db.prepare('DELETE FROM runs WHERE started_at < ?').run(cutoff)
+    this.db.prepare('DELETE FROM invocations WHERE started_at < ?').run(cutoff)
+  }
+}
+
+/**
+ * Bind a RunRecord to the positional parameters expected by the
+ * `insertRun` prepared statement (17 columns). Shared between the
+ * single and batched record paths.
+ */
+function bindRun(run: RunRecord): SQLQueryBindings[] {
+  return [
+    // The ONE place the no-key sentinel is applied, so the column's
+    // NOT NULL invariant can't be violated from a call site.
+    run.hash ?? '',
+    run.project,
+    run.task,
+    run.status,
+    run.exitCode,
+    run.durationMs,
+    run.forwardArgs ? JSON.stringify(run.forwardArgs) : null,
+    run.startedAt,
+    run.endedAt,
+    run.runId ?? null,
+    run.cpuMs ?? null,
+    run.peakRssBytes ?? null,
+    run.wallclockStartNs !== undefined ? run.wallclockStartNs : null,
+    run.wallclockEndNs !== undefined ? run.wallclockEndNs : null,
+    run.cacheHit === undefined ? null : run.cacheHit ? 1 : 0,
+    run.attempts ?? null,
+    run.cached === undefined ? null : run.cached ? 1 : 0,
+  ]
+}
+
+/**
+ * Bind an InvocationRecord to the positional parameters of the
+ * `insertInvocation` prepared statement (25 columns). Booleans map to
+ * 0/1; null-or-bool columns (`dirty`) keep null distinct from 0.
+ */
+function bindInvocation(inv: InvocationRecord): SQLQueryBindings[] {
+  return [
+    inv.runId,
+    inv.command,
+    inv.requestedTasks,
+    inv.cachePolicy,
+    inv.concurrency,
+    inv.flow,
+    inv.startedAt,
+    inv.endedAt,
+    inv.totalDurationMs,
+    inv.taskCount,
+    inv.failedCount,
+    inv.hitCount,
+    inv.hitLocalCount,
+    inv.hitRemoteCount,
+    inv.exitOk ? 1 : 0,
+    inv.commitSha,
+    inv.branch,
+    inv.dirty === null ? null : inv.dirty ? 1 : 0,
+    inv.ci ? 1 : 0,
+    inv.ciProvider,
+    inv.host,
+    inv.os,
+    inv.arch,
+    inv.vxVersion,
+    inv.tags,
+  ]
+}

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/cache/zstd.ts

@@ -0,0 +1,160 @@
+// zstd framing for artifacts: the declared-size gate that refuses a
+// decompression bomb before it can expand, and the bounded one-call /
+// streamed decoders the store and the ingest path share.
+
+import { CorruptArtifactError } from './layer.js'
+
+/**
+ * A decompressed artifact above this is refused as a zstd bomb rather than
+ * expanded into memory. 2 GiB comfortably exceeds any real build output while
+ * bounding a malicious/compromised remote's ability to OOM a victim who takes
+ * a cache hit.
+ */
+const MAX_DECOMPRESSED_ARTIFACT_BYTES = 2 * 1024 * 1024 * 1024
+
+/**
+ * Read a zstd frame's declared Frame_Content_Size (RFC 8878 §3.1.1) WITHOUT
+ * decompressing. Returns null when the frame omits it (streaming frames) or
+ * the header is too short to parse. vx's own producer (single-shot
+ * `Bun.zstdCompress` of a known buffer) always writes it, so an artifact that
+ * declares an enormous size can be rejected before a byte is allocated.
+ *
+ * Exported for tests: pins the per-`fcsFlag` byte layouts (incl. the 2-byte
+ * `+256` adjustment and the `dictIdFlag` offset) that a bomb-refusal e2e can't
+ * discriminate (their max declarable sizes sit below the ceiling).
+ */
+export function zstdContentSize(b: Uint8Array): bigint | null {
+  if (b.length < 5) return null
+  // Magic_Number 0xFD2FB528, little-endian.
+  if (b[0] !== 0x28 || b[1] !== 0xb5 || b[2] !== 0x2f || b[3] !== 0xfd) return null
+  const desc = b[4]!
+  const fcsFlag = desc >> 6
+  const singleSegment = (desc >> 5) & 1
+  const dictIdFlag = desc & 3
+  let off = 5
+  if (singleSegment === 0) off += 1 // Window_Descriptor byte
+  off += dictIdFlag === 3 ? 4 : dictIdFlag // Dictionary_ID: 0,1,2,4 bytes
+  let fcsSize: number
+  if (fcsFlag === 0) fcsSize = singleSegment === 1 ? 1 : 0
+  else if (fcsFlag === 1) fcsSize = 2
+  else if (fcsFlag === 2) fcsSize = 4
+  else fcsSize = 8
+  if (fcsSize === 0 || b.length < off + fcsSize) return null
+  let v = 0n
+  for (let i = 0; i < fcsSize; i++) v |= BigInt(b[off + i]!) << BigInt(8 * i)
+  if (fcsSize === 2) v += 256n // per spec, the 2-byte field stores value − 256
+  return v
+}
+
+/**
+ * Decompress a zstd artifact that DECLARES its content size, with a hard
+ * output ceiling: refused before a byte is allocated when the declaration
+ * is over the cap, and again on the actual length. A frame with no
+ * declaration (a streamed producer's — vx's own, above 4 MiB) never comes
+ * here: `decodedTar` decodes it as a stream under the running count, so
+ * a sizeless bomb has nowhere to expand.
+ */
+async function zstdDecompressBounded(compressed: Uint8Array, hash: string): Promise<Uint8Array> {
+  assertDeclaredSize(compressed, hash)
+  const out = await Bun.zstdDecompress(compressed)
+  if (out.length > MAX_DECOMPRESSED_ARTIFACT_BYTES) {
+    throw new CorruptArtifactError(
+      hash,
+      `decompressed to ${out.length} bytes (> ${MAX_DECOMPRESSED_ARTIFACT_BYTES} cap)`,
+    )
+  }
+  return out
+}
+
+/** The pre-decompress half of the ceiling: the frame header's own claim, when it makes one. */
+function assertDeclaredSize(compressed: Uint8Array, hash: string): bigint | null {
+  const declared = zstdContentSize(compressed)
+  if (declared !== null && declared > BigInt(MAX_DECOMPRESSED_ARTIFACT_BYTES)) {
+    throw new CorruptArtifactError(
+      hash,
+      `declares ${declared} decompressed bytes (> ${MAX_DECOMPRESSED_ARTIFACT_BYTES} cap)`,
+    )
+  }
+  return declared
+}
+
+/** Compressed artifacts above this size are decoded as a stream, on restore and on ingest. */
+export const STREAM_DECODE_FROM = 4 * 1024 * 1024
+
+/** Collect a byte stream; only ever used where the seam wants bytes. */
+export async function bytesOf(stream: ReadableStream<Uint8Array>): Promise<Uint8Array> {
+  return new Uint8Array(await new Response(stream).arrayBuffer())
+}
+
+/**
+ * Bun's `CompressionStream` types do not satisfy `pipeThrough`'s pair
+ * (its readable side is typed `NonSharedUint8Array`); the runtime object
+ * is a plain byte transform.
+ */
+export const zstdEncoder = (): TransformStream<Uint8Array, Uint8Array> =>
+  new CompressionStream('zstd') as unknown as TransformStream<Uint8Array, Uint8Array>
+
+const oneChunk = (bytes: Uint8Array): ReadableStream<Uint8Array> =>
+  new ReadableStream({
+    start(c) {
+      c.enqueue(bytes)
+      c.close()
+    },
+  })
+
+/**
+ * The decoded tar as a stream: one call for a small artifact that
+ * declares its size, a streamed decode otherwise — the stream setup is
+ * ~35 µs, which matters at a thousand one-file artifacts and nowhere
+ * else. Bytes in memory are only ever the small case (a large source
+ * must be a FILE: a Blob copies its bytes and hands the decoder
+ * everything at once, measured +519 MiB on 150 MiB against +448 for the
+ * plain decode). The 2 GiB ceiling applies either way: the declaration
+ * and the result length in one call, a running count on the stream.
+ */
+export async function decodedTar(
+  source: Uint8Array | Bun.BunFile,
+  hash: string,
+): Promise<ReadableStream<Uint8Array>> {
+  if (source instanceof Uint8Array) {
+    if (assertDeclaredSize(source, hash) === null) return zstdDecodeStream(new Blob([source]), hash)
+    return oneChunk(await zstdDecompressBounded(source, hash))
+  }
+  if (source.size <= STREAM_DECODE_FROM) {
+    const bytes = await source.bytes()
+    if (assertDeclaredSize(bytes, hash) === null) return zstdDecodeStream(source, hash)
+    return oneChunk(await zstdDecompressBounded(bytes, hash))
+  }
+  assertDeclaredSize(await source.slice(0, 32).bytes(), hash)
+  return zstdDecodeStream(source, hash)
+}
+
+/**
+ * The streaming twin of `zstdDecompressBounded`: the decoded bytes as a
+ * stream, refused past the same ceiling. A malicious frame cannot expand
+ * past the cap here either — the count runs as bytes are produced, before
+ * any of them reach the reader's next entry.
+ */
+function zstdDecodeStream(source: Blob, hash: string): ReadableStream<Uint8Array> {
+  let total = 0
+  return source
+    .stream()
+    .pipeThrough(new DecompressionStream('zstd'))
+    .pipeThrough(
+      new TransformStream<Uint8Array, Uint8Array>({
+        transform(chunk, controller) {
+          total += chunk.byteLength
+          if (total > MAX_DECOMPRESSED_ARTIFACT_BYTES) {
+            controller.error(
+              new CorruptArtifactError(
+                hash,
+                `decompresses past ${MAX_DECOMPRESSED_ARTIFACT_BYTES} bytes (cap)`,
+              ),
+            )
+            return
+          }
+          controller.enqueue(chunk)
+        },
+      }),
+    )
+}