@vzn/vx 0.0.16 → 0.0.21

package/src/cache/archive.ts

@@ -0,0 +1,659 @@
+// Cache artifact container: a zstd-compressed tar, read and written by
+// vx's own streaming tar code (`tar-stream.ts`).
+//
+// An artifact is a tar of:
+//   stdout                       always present; the vx-artifact marker
+//   outputs/<rel>                project-relative outputs
+//   workspace-outputs/<rel>      workspace-root-relative outputs
+//   .vx-meta.json                per-output mode + millisecond mtime
+//
+// Tar headers carry mode and SECOND mtimes; vx needs both exactly — a
+// lost executable bit builds cold and breaks warm, and `isOutputsCurrent`
+// skips a restore when size+mode+mtime match at millisecond precision —
+// so the pack side stats each output once and writes both into
+// `.vx-meta.json`, and the restore side applies them. That also makes a
+// REMOTE-ingested entry's index rows millisecond-accurate.
+//
+// Both directions stream. `packArtifactStream` reads each output as it is
+// written; `scanArtifact` lists what an artifact holds without
+// materialising a byte; `extractArtifactStream` restores while never
+// holding more than a chunk. `Bun.Archive` used to do all three and
+// needed the whole tar in memory on every side — restoring a 150 MiB
+// artifact peaked at 3.2× its size, saving one at 4.7× (measured
+// 2026-09-03). Every regular entry is written beside its target under a
+// `.vx-tmp-*` name and renamed into place only once the WHOLE archive has
+// been read and every name proven safe, so a poisoned entry anywhere —
+// even the last one — leaves nothing behind but the empty directories it
+// needed, which are pruned too.
+//
+// What stays here is the part no tar reader can decide for us: WHERE an
+// entry may land on disk. Every name is validated and every destination
+// is proven to stay inside its anchor before a byte is written, because a
+// cache artifact is attacker-reachable (a poisoned remote, a tampered
+// local entry) and "zip slip" is the class.
+//
+// Entries that are not regular files (symlinks, hardlinks, devices,
+// FIFOs) are never materialised — the reader reports them only to be
+// skipped — vx's outputs are regular files, and an artifact that claims
+// otherwise silently loses the claim rather than acting on it.
+
+import { chmodSync, renameSync, statSync, utimesSync } from 'node:fs'
+import { mkdir, realpath, rmdir, stat, unlink, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { UserError } from '../util/index.js'
+import { TarFormatError, type TarInput, tarEntries, tarPack, tarSize } from './tar-stream.js'
+
+/** Archive entry name carrying the per-output mode/mtime sidecar. */
+const META_ENTRY = '.vx-meta.json'
+
+/** Archive entry name of the always-present stdout record. */
+export const STDOUT_ENTRY = 'stdout'
+
+/**
+ * Sidecar shape. `files` maps an entry name to `[mode, mtimeMs]` — a
+ * pair, not an object, because the sidecar is real entropy inside an
+ * otherwise highly compressible artifact and per-file key names would
+ * be paid for once per output.
+ */
+interface MetaFile {
+  /** Bumped only if the sidecar's own shape changes; the artifact
+   *  container is versioned by CACHE_VERSION, which gates reads. */
+  version: 1
+  files: Record<string, [mode: number, mtimeMs: number]>
+  /**
+   * What the PRODUCING execution used (2026-09-12, additive: an artifact
+   * without it reads as before). Rides the artifact so a machine that
+   * never ran the task — a fresh CI runner on a remote hit — still learns
+   * what it needs; every wire ships the bytes verbatim, so no seam
+   * changes.
+   */
+  exec?: ExecUsage
+}
+
+/** CPU time and peak RSS of the execution that produced an artifact. */
+export interface ExecUsage {
+  cpuMs?: number
+  peakRssBytes?: number
+}
+
+/** One regular file in an artifact, with its restore metadata resolved. */
+export interface ArchiveEntry {
+  /** Full archive-relative name, e.g. `outputs/dist/index.js`. */
+  name: string
+  size: number
+  /** Permission bits (0o777 mask) from the sidecar. */
+  mode: number
+  /** Modification time in ms since epoch from the sidecar. */
+  mtimeMs: number
+}
+
+/**
+ * Thrown when an entry's name would let it escape the extraction anchor
+ * (absolute path, `..` traversal, doubled separator, Windows shapes).
+ * Callers treat this as a corrupt / malicious artifact — log it, drop
+ * the entry, re-run the task.
+ */
+export class ArchiveSecurityError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ArchiveSecurityError'
+  }
+}
+
+/** What `packArtifactStream` packs: stdout plus archive name → absolute source path. */
+export interface PackArgs {
+  stdout: string
+  outputs: ReadonlyMap<string, string>
+  /** The producing execution's usage, when the runner reported it. */
+  exec?: ExecUsage | undefined
+}
+
+/** A packed artifact's plan: its entries with their stats, and the tar's exact size. */
+export interface ArtifactPlan {
+  inputs: TarInput[]
+  size: number
+}
+
+/**
+ * Stat every output once (size, and the sidecar's mode + millisecond
+ * mtime) and lay out the tar — stdout first, the outputs, the sidecar
+ * last — with its exact size, so the caller can choose the one-call pack
+ * for a small artifact and the streamed one for a large one before a
+ * byte is read. A symlinked output is stored as its target's content, as
+ * it always was.
+ */
+export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
+  const meta: MetaFile = { version: 1, files: {} }
+  const exec = usageOf(args.exec)
+  if (exec !== undefined) meta.exec = exec
+  const files = await Promise.all(
+    [...args.outputs].map(async ([name, abs]) => {
+      // `stat` follows a symlink, so a link to a file is packed as that
+      // file's bytes and comes back as a regular file. A link to a
+      // directory, or a dangling one, has no bytes to pack: refuse loudly
+      // rather than store an entry that restores to nothing.
+      const shown = name.startsWith('outputs/') ? name.slice('outputs/'.length) : name
+      const st = await stat(abs).catch((err: NodeJS.ErrnoException) => {
+        if (err.code === 'ENOENT') {
+          throw new UserError(
+            `output ${shown} is a dangling symlink: vx stores regular files only — emit a file, or exclude it from cache.outputs`,
+          )
+        }
+        throw err
+      })
+      if (!st.isFile()) {
+        throw new UserError(
+          `output ${shown} is not a regular file (a symlink to a directory?): vx stores regular files only — emit a file, or exclude it from cache.outputs`,
+        )
+      }
+      meta.files[name] = [st.mode & 0o777, Math.floor(st.mtimeMs)]
+      return {
+        name,
+        abs,
+        size: st.size,
+        mode: st.mode & 0o777,
+        mtime: Math.floor(st.mtimeMs / 1000),
+      }
+    }),
+  )
+  const stdout = new TextEncoder().encode(args.stdout)
+  const metaBytes = new TextEncoder().encode(JSON.stringify(meta))
+  const inputs: TarInput[] = [
+    { name: STDOUT_ENTRY, size: stdout.byteLength, body: stdout },
+    ...files.map((f) => ({
+      name: f.name,
+      size: f.size,
+      mode: f.mode,
+      mtime: f.mtime,
+      body: Bun.file(f.abs) as Blob,
+    })),
+    { name: META_ENTRY, size: metaBytes.byteLength, body: metaBytes },
+  ]
+  return { inputs, size: tarSize(inputs) }
+}
+
+/** The tar as a stream: each output is read from disk as it is written. */
+export function packArtifactStream(plan: ArtifactPlan): ReadableStream<Uint8Array> {
+  return streamOf(tarPack(plan.inputs))
+}
+
+/**
+ * The tar in memory — the small-artifact path and the tests. Bodies are
+ * read whole (one `bytes()` each, in flight together) rather than
+ * streamed: a thousand one-file artifacts pay the stream setup
+ * otherwise (measured 2026-09-03: 238 → 293 ms per 1 000 saves).
+ */
+export async function packArtifactBytes(plan: ArtifactPlan): Promise<Uint8Array> {
+  const inputs = await Promise.all(
+    plan.inputs.map(async (i) =>
+      i.body instanceof Blob ? { ...i, body: await i.body.bytes() } : i,
+    ),
+  )
+  const out = new Uint8Array(plan.size)
+  let off = 0
+  for await (const chunk of tarPack(inputs)) {
+    out.set(chunk, off)
+    off += chunk.byteLength
+  }
+  if (off !== plan.size) throw new TarFormatError(`packed ${off} bytes, planned ${plan.size}`)
+  return out
+}
+
+/** Plan and pack in one go, in memory. */
+export async function packArtifact(args: PackArgs): Promise<Uint8Array> {
+  return await packArtifactBytes(await planArtifact(args))
+}
+
+function streamOf(gen: AsyncGenerator<Uint8Array>): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      const { done, value } = await gen.next()
+      if (done) controller.close()
+      else controller.enqueue(value)
+    },
+    cancel() {
+      void gen.return(undefined)
+    },
+  })
+}
+
+/**
+ * List an artifact's regular entries with their restore metadata, and
+ * its stdout text (`null` when the entry is absent — not a vx artifact),
+ * without materialising anything. Rejects the WHOLE archive when any
+ * name is unsafe — a partial reading of a poisoned artifact is the
+ * outcome the traversal defense exists to prevent.
+ */
+export async function scanArtifact(
+  tar: ReadableStream<Uint8Array>,
+): Promise<{ entries: ArchiveEntry[]; stdout: string | null; exec: ExecUsage | undefined }> {
+  const seen: Array<{ name: string; size: number; mtimeMs: number }> = []
+  let meta: MetaFile['files'] = {}
+  let exec: ExecUsage | undefined
+  let stdout: string | null = null
+  for await (const e of tarEntries(tar)) {
+    if (e.type !== '0') continue
+    if (e.name === META_ENTRY) {
+      const parsed = JSON.parse(await textOf(e.body)) as MetaFile
+      meta = parsed.files ?? {}
+      // The ingest side is the untrusted boundary: a foreign sidecar's
+      // usage is taken only when it is a plain non-negative number.
+      exec = usageOf(parsed.exec)
+      continue
+    }
+    assertSafeName(e.name)
+    if (e.name === STDOUT_ENTRY) stdout = await textOf(e.body)
+    seen.push({ name: e.name, size: e.size, mtimeMs: e.mtimeMs })
+  }
+  return {
+    entries: seen.map((s) => {
+      const m = meta[s.name]
+      // A foreign artifact (or one whose sidecar lost an entry) restores
+      // readable-but-not-executable rather than failing the hit: the
+      // sidecar is metadata, never the authority on whether bytes exist.
+      return { name: s.name, size: s.size, mode: m?.[0] ?? 0o644, mtimeMs: m?.[1] ?? s.mtimeMs }
+    }),
+    stdout,
+    exec,
+  }
+}
+
+/** The usage worth carrying: each axis a finite non-negative number, or absent; nothing → undefined. */
+function usageOf(raw: unknown): ExecUsage | undefined {
+  if (typeof raw !== 'object' || raw === null) return undefined
+  const { cpuMs, peakRssBytes } = raw as { cpuMs?: unknown; peakRssBytes?: unknown }
+  const out: { cpuMs?: number; peakRssBytes?: number } = {}
+  if (typeof cpuMs === 'number' && Number.isFinite(cpuMs) && cpuMs >= 0) out.cpuMs = cpuMs
+  if (typeof peakRssBytes === 'number' && Number.isFinite(peakRssBytes) && peakRssBytes >= 0)
+    out.peakRssBytes = peakRssBytes
+  return out.cpuMs === undefined && out.peakRssBytes === undefined ? undefined : out
+}
+
+/**
+ * Restore from `tar`, the DECOMPRESSED archive as a byte stream:
+ * `outputs/<rel>` lands under `destDir/<rel>` and — when `workspaceDest`
+ * is given — `workspace-outputs/<rel>` under `workspaceDest/<rel>`;
+ * entries in neither namespace are ignored. Entries are validated and staged
+ * as they arrive and renamed into place only after the archive has ended
+ * cleanly and `verify` (the caller's look at which output names the
+ * archive provided — the index's missing-output check) has passed. Any
+ * failure — an unsafe name, an escape, a truncated stream, `verify` —
+ * leaves nothing behind. Returns the provided output names.
+ */
+export async function extractArtifactStream(
+  tar: ReadableStream<Uint8Array>,
+  destDir: string,
+  workspaceDest: string | undefined,
+  verify?: (provided: ReadonlySet<string>) => void,
+): Promise<Set<string>> {
+  await mkdir(destDir, { recursive: true })
+  const x = new Extractor(destDir, workspaceDest)
+  const provided = new Set<string>()
+  const headerMtime = new Map<string, number>()
+  let meta: MetaFile['files'] = {}
+  try {
+    for await (const e of tarEntries(tar)) {
+      if (e.type !== '0') continue
+      if (e.name === META_ENTRY) {
+        meta = (JSON.parse(await textOf(e.body)) as MetaFile).files ?? {}
+        continue
+      }
+      assertSafeName(e.name)
+      const dest = x.destFor(e.name)
+      if (dest === null || dest.rel.length === 0) continue
+      const target = path.join(dest.base, dest.rel)
+      await x.assertContained(dest.base, target, e.name)
+      provided.add(e.name)
+      headerMtime.set(e.name, e.mtimeMs)
+      await x.stage(e.name, target, e.size <= SMALL_ENTRY ? await bytesOf(e.body) : e.body)
+    }
+    verify?.(provided)
+    await x.commit((name) => {
+      const m = meta[name]
+      return [m?.[0] ?? 0o644, m?.[1] ?? headerMtime.get(name) ?? 0]
+    })
+  } catch (err) {
+    await x.abort()
+    throw err
+  }
+  return provided
+}
+
+/**
+ * Entries up to this size are buffered and written without waiting, so a
+ * thousand tiny outputs restore in parallel; larger ones stream chunk by
+ * chunk to a file sink.
+ */
+const SMALL_ENTRY = 4 * 1024 * 1024
+
+/** Buffered small writes in flight before the next one waits for them. */
+const INFLIGHT_BYTES = 64 * 1024 * 1024
+
+async function bytesOf(body: AsyncIterable<Uint8Array>): Promise<Uint8Array> {
+  const parts: Uint8Array[] = []
+  let n = 0
+  for await (const c of body) {
+    parts.push(new Uint8Array(c))
+    n += c.byteLength
+  }
+  if (parts.length === 1) return parts[0]!
+  const out = new Uint8Array(n)
+  let off = 0
+  for (const p of parts) {
+    out.set(p, off)
+    off += p.byteLength
+  }
+  return out
+}
+
+const textOf = async (body: AsyncIterable<Uint8Array>): Promise<string> =>
+  new TextDecoder().decode(await bytesOf(body))
+
+/** One staged entry: written at `tmp`, renamed to `target` on commit. */
+interface Staged {
+  name: string
+  tmp: string
+  target: string
+  /** The topmost directory `mkdir -p` created for it, pruned on abort. */
+  created: string | undefined
+}
+
+/**
+ * The staging core. Nothing reaches its final name until `commit`;
+ * `abort` removes every temp and the empty directories this extraction
+ * created.
+ */
+class Extractor {
+  private readonly staged: Staged[] = []
+  private inflight: Promise<unknown>[] = []
+  private inflightBytes = 0
+  private readonly realBaseCache = new Map<string, string>()
+  // Per-directory memos. An artifact holds a few files per directory
+  // (payload's ui: 4,069 files in 535 directories), and the containment
+  // walk and the `mkdir -p` are properties of the directory, not the
+  // entry: doing both once per directory took the restore of that
+  // artifact from 220–300 µs per file to the write itself. The window
+  // this opens — a symlink planted at a validated directory between two
+  // of its entries — is the same one that already lies between an
+  // entry's own check and its write.
+  private readonly containedDirs = new Set<string>()
+  private readonly ensuredDirs = new Set<string>()
+
+  constructor(
+    private readonly destDir: string,
+    private readonly workspaceDest: string | undefined,
+  ) {}
+
+  /** Each namespace anchors at its own destination dir. */
+  destFor(name: string): { base: string; rel: string } | null {
+    if (name.startsWith('outputs/')) {
+      return { base: this.destDir, rel: name.slice('outputs/'.length) }
+    }
+    if (this.workspaceDest !== undefined && name.startsWith(WORKSPACE_PREFIX)) {
+      return { base: this.workspaceDest, rel: name.slice(WORKSPACE_PREFIX.length) }
+    }
+    return null
+  }
+
+  // The REAL path of each base dir (symlinks resolved), memoized. Used to
+  // catch a symlinked ANCESTOR under the output tree: the lexical check
+  // below stops a `..` name, but if `<dest>/dist` is already an on-disk
+  // symlink pointing outside (planted in the repo or by a dependency
+  // postinstall), a lexically-contained entry `dist/x` would follow it and
+  // escape. Both sides are realpath'd, so a legitimate symlinked ANCESTOR of
+  // the base dir itself (e.g. macOS /tmp → /private/tmp) resolves
+  // consistently and is not flagged.
+  private async realBaseOf(base: string): Promise<string> {
+    const key = path.resolve(base)
+    let r = this.realBaseCache.get(key)
+    if (r === undefined) {
+      // The base often does NOT exist yet — the workspace-outputs anchor is
+      // created lazily by the first entry. Falling back to the un-resolved
+      // path there would compare a real ancestor (`/private/tmp/...`, once
+      // mkdir has created it) against a symlinked base (`/tmp/...`) and
+      // refuse EVERY entry with a bogus security error. So resolve the
+      // deepest EXISTING ancestor and re-append the rest: the answer is the
+      // same before and after the base is created, which is what makes the
+      // memo safe.
+      r = await realpath(key).catch(async () => {
+        let probe = path.dirname(key)
+        const tail: string[] = [path.basename(key)]
+        while (probe !== path.dirname(probe)) {
+          const real = await realpath(probe).then(
+            (v) => v,
+            () => null,
+          )
+          if (real !== null) return path.join(real, ...tail.reverse())
+          tail.push(path.basename(probe))
+          probe = path.dirname(probe)
+        }
+        return key
+      })
+      this.realBaseCache.set(key, r)
+    }
+    return r
+  }
+
+  // Two checks per entry: lexical (the joined path stays under the base)
+  // and real (the deepest EXISTING ancestor still resolves inside the real
+  // base). Walking up to the deepest existing ancestor is what makes it
+  // sound BEFORE anything is created — checking only the immediate parent
+  // would pass for `dist/a/b` when `dist` is the symlink and `dist/a` does
+  // not exist yet.
+  async assertContained(base: string, target: string, name: string): Promise<void> {
+    const baseResolved = path.resolve(base)
+    const targetResolved = path.resolve(target)
+    if (targetResolved !== baseResolved && !targetResolved.startsWith(baseResolved + path.sep)) {
+      throw new ArchiveSecurityError(`archive entry escapes destDir (unsafe): ${name}`)
+    }
+    const parentResolved = path.dirname(targetResolved)
+    if (this.containedDirs.has(parentResolved)) return
+    await this.assertParentContained(base, targetResolved, name)
+    this.containedDirs.add(parentResolved)
+  }
+
+  private async assertParentContained(
+    base: string,
+    targetResolved: string,
+    name: string,
+  ): Promise<void> {
+    const baseResolved = path.resolve(base)
+    const realBase = await this.realBaseOf(base)
+    // Only ancestors strictly BELOW the base are candidates — those are the
+    // ones a poisoned entry could follow out of the tree. The walk must never
+    // climb past the base: when the base itself does not exist yet (the
+    // workspace-outputs anchor is created lazily), its parent legitimately
+    // resolves outside and comparing against it would reject every entry.
+    let probe = path.dirname(targetResolved)
+    while (probe.startsWith(baseResolved + path.sep)) {
+      const real = await realpath(probe).then(
+        (r) => r,
+        () => null,
+      )
+      if (real !== null) {
+        if (real !== realBase && !real.startsWith(realBase + path.sep)) {
+          throw new ArchiveSecurityError(
+            `archive entry escapes destDir via a symlinked parent: ${name}`,
+          )
+        }
+        return
+      }
+      probe = path.dirname(probe)
+    }
+    // Nothing between the base and the target exists yet, so there is no
+    // pre-existing symlink to follow — the chain will be created fresh.
+  }
+
+  /**
+   * Write the entry beside its target. A buffer is written without
+   * waiting, bounded by `INFLIGHT_BYTES`; a chunk stream goes to a file
+   * sink one piece at a time.
+   */
+  async stage(
+    name: string,
+    target: string,
+    body: Uint8Array | AsyncIterable<Uint8Array>,
+  ): Promise<void> {
+    const dir = path.dirname(target)
+    let created: string | undefined
+    if (!this.ensuredDirs.has(dir)) {
+      created = await mkdir(dir, { recursive: true })
+      this.ensuredDirs.add(dir)
+    }
+    // Write beside the target and RENAME into place. rename(2) replaces
+    // the destination's directory ENTRY without following it, which is
+    // what makes this both link-safe and concurrency-safe:
+    //
+    //   - a planted symlink or HARDLINK at the target is replaced, not
+    //     written through, so `ln <victim> <dest>/out.txt` cannot get
+    //     the artifact's bytes into <victim>;
+    //   - the target is never momentarily ABSENT. The unlink-then-write
+    //     version opened exactly that window, and a second extract of
+    //     the same payload could delete the file between this one's
+    //     write and its chmod — reproduced 3/400 locally, caught red on
+    //     darwin CI where a loaded runner widened the race;
+    //   - mode and mtime are applied BEFORE the file is visible, so no
+    //     reader sees it with the wrong metadata.
+    //
+    // A directory at the target makes the rename fail — the same
+    // fail-closed outcome the plain write had.
+    const tmp = `${target}.vx-tmp-${process.pid.toString(36)}-${(tmpSeq++).toString(36)}`
+    this.staged.push({ name, tmp, target, created })
+    if (body instanceof Uint8Array) {
+      this.inflightBytes += body.byteLength
+      // `writeFile`, not `Bun.write`: for a buffer this size `Bun.write`
+      // does the open, write and close on the calling thread and only
+      // its promise is asynchronous, so ten restores in flight wrote
+      // their 14,430 files one after another — a serial restore of
+      // payload took the same 6–7 s as one at concurrency 10, and a CPU
+      // profile put 6.7 of its 8.0 s inside `write` (2026-09-11). The
+      // thread-pool write lets the restores overlap their I/O.
+      const write = writeFile(tmp, body)
+      // A write that fails before `commit` or `abort` awaits it must not
+      // surface as an unhandled rejection; the awaiting `Promise.all` still
+      // sees the error through the original promise.
+      write.catch(() => undefined)
+      this.inflight.push(write)
+      if (this.inflightBytes > INFLIGHT_BYTES) await this.drain()
+      return
+    }
+    const sink = Bun.file(tmp).writer()
+    try {
+      for await (const piece of body) await sink.write(piece)
+    } finally {
+      await sink.end()
+    }
+  }
+
+  private async drain(): Promise<void> {
+    const pending = this.inflight
+    this.inflight = []
+    this.inflightBytes = 0
+    await Promise.all(pending)
+  }
+
+  /**
+   * Apply each entry's mode and mtime, then rename everything into place.
+   * Synchronous calls in batches: the three metadata calls per file are a
+   * few microseconds each on the calling thread and ~40 µs each as
+   * thread-pool round trips, and a large artifact has thousands of them
+   * (measured 2026-09-11 on payload's ui, 4,069 files: 892 ms → see the
+   * archive bench). A yield every `COMMIT_BATCH` files keeps the other
+   * restores' round trips flowing. The chmod is skipped when the mode is
+   * the one the temp file was created with — the common case.
+   */
+  async commit(metaFor: (name: string) => [mode: number, mtimeMs: number]): Promise<void> {
+    await this.drain()
+    const first = this.staged[0]
+    const createdMode = first === undefined ? -1 : statSync(first.tmp).mode & 0o777
+    let n = 0
+    for (const s of this.staged) {
+      const [mode, mtimeMs] = metaFor(s.name)
+      if (mode !== 0 && (mode & 0o777) !== createdMode) chmodSync(s.tmp, mode & 0o777)
+      if (mtimeMs > 0) {
+        const t = mtimeMs / 1000
+        utimesSync(s.tmp, t, t)
+      }
+      renameSync(s.tmp, s.target)
+      if (++n % COMMIT_BATCH === 0) await new Promise<void>((r) => setImmediate(r))
+    }
+    this.staged.length = 0
+  }
+
+  /**
+   * Never leave a stray `.vx-tmp-*` behind: the declared output globs would
+   * sweep it into the next artifact. Directories this extraction created
+   * are removed bottom-up while empty; one a concurrent writer has since
+   * filled is left alone.
+   */
+  async abort(): Promise<void> {
+    await Promise.allSettled(this.inflight)
+    this.inflight = []
+    await Promise.all(this.staged.map((s) => unlink(s.tmp).catch(() => undefined)))
+    for (const s of this.staged) {
+      if (s.created === undefined) continue
+      let dir = path.dirname(s.target)
+      const top = path.resolve(s.created)
+      while (dir.startsWith(top)) {
+        if (
+          !(await rmdir(dir).then(
+            () => true,
+            () => false,
+          ))
+        )
+          break
+        if (dir === top) break
+        dir = path.dirname(dir)
+      }
+    }
+    this.staged.length = 0
+  }
+}
+
+/** Files renamed into place between two yields of a commit. */
+const COMMIT_BATCH = 256
+
+/** Per-process counter for extract temp names; uniqueness only. */
+let tmpSeq = 0
+
+const WORKSPACE_PREFIX = 'workspace-outputs/'
+
+/**
+ * Path-traversal defense, applied to every entry name at read time.
+ * Mirrors Turbo's `restore.rs:check_path` normalization: an artifact is
+ * attacker-reachable, so a name that could resolve outside the anchor is
+ * refused before anything decides where to write it.
+ */
+function assertSafeName(name: string): void {
+  if (name.length === 0) {
+    throw new ArchiveSecurityError('archive entry has an empty name')
+  }
+  if (name.startsWith('/')) {
+    throw new ArchiveSecurityError(`archive entry name is absolute (unsafe): ${name}`)
+  }
+  if (hasParentSegment(name)) {
+    throw new ArchiveSecurityError(`archive entry name escapes via '..' (unsafe): ${name}`)
+  }
+  if (name.includes('//')) {
+    throw new ArchiveSecurityError(`archive entry name has empty path component (unsafe): ${name}`)
+  }
+  // Windows-shaped paths are categorically unsafe to extract on POSIX
+  // hosts (and vice versa): backslash separators, drive letters,
+  // extended-length prefixes.
+  if (name.includes('\\')) {
+    throw new ArchiveSecurityError(
+      `archive entry uses backslash separators (windows-unsafe): ${name}`,
+    )
+  }
+  if (/^[A-Za-z]:[\\/]/.test(name)) {
+    throw new ArchiveSecurityError(`archive entry has windows drive prefix (unsafe): ${name}`)
+  }
+  if (name.includes('\0')) {
+    throw new ArchiveSecurityError(`archive entry name contains a null byte (unsafe): ${name}`)
+  }
+}
+
+function hasParentSegment(p: string): boolean {
+  if (p === '..' || p.startsWith('../') || p.endsWith('/..')) return true
+  return p.includes('/../')
+}