perf(cache): switch local cache to <hash>.tar.zst artifacts (Turbo-style)

[Exelord]

Summary

After reading Turbo's actual cache_archive/restore.rs: they use
tar archives, not hardlinks. Converting our local cache to the
same layout.

Artifact layout

<cacheDir>/<hash>.tar.zst
├── outputs/                   ← only when task has output files
│   └── <project-relative>...
├── stdout                     ← only when non-empty
└── stderr                     ← only when non-empty

Empty task (no outputs, no logs) → ~1 KB empty archive.
The artifact is a pure dump of run byproducts; nothing else.

DB layout

entries:
  hash, project, task, command, exit_code, duration_ms,
  size_bytes, created_at, accessed_at

stdout/stderr removed from the entries row — they live in the
artifact so a remote pull carries them with the bytes.
SCHEMA_VERSION bumped v13 → v14 (mismatch nukes per project
convention; pre-alpha).

Why this should feel like Turbo

1. One sequential disk read of one compressed file instead of
   N small files scattered across <hash>/ trees. Kernel prefetches
   the whole tar in one pass.
2. One subprocess (tar -xf) handles all file writes in C
   instead of N async Bun.write() calls from JS.
3. Bun.zstdCompress / zstdDecompress — built in, no external
   zstd binary required.

Group tasks never touch the cache

executeGroupTask returns early with a hash computed from upstream
outcomes; never calls save / get / restoreOutputs. Confirmed
the contract holds.

What got removed

• Old <hash>/outputs/, <hash>/stdout, <hash>/stderr layout.
• outputsMatchCache whole-restore-skip (the per-file manifest
  skip Turbo does inline during extract is a deferred optimization).
• Hardlink-restore code from PR perf(cache): hardlink-based output restore (Turbo-style "instant" feel) #85 — wrong direction; Turbo
  explicitly rejects hardlink tar entries.

Implementation notes

• save(): stage outputs/+stdout+stderr in a temp dir, tar to
  stdout, zstd-compress, atomic rename to <hash>.tar.zst. Stage
  contents are conditional — no folder if no outputs, no file if
  no stdout/stderr.
• get(): read tar once into memory; peekTar() walks header
  blocks directly (no subprocess) to grab the entries list +
  stdout/stderr content in one pass.
• restoreOutputs(): decompress; if the artifact has an outputs/
  member, tar -xf - --strip-components=1 outputs extracts the
  files into the project dir. Skips when only logs are cached.

Test plan

• bun src/bin.ts run ci — 3/3 pass (format-check + lint + 458 tests)
• Updated tests/cache.test.ts assertions (old <hash>/ layout).
• 6 new tests in tests/cache-perf.test.ts:
  • single <hash>.tar.zst file (no <hash>/ dir)
  • stdout/stderr present in tar listing (not DB)
  • restoreOutputs round-trip
  • no-op when artifact missing
  • outputsPath returns .tar.zst
  • prune deletes .tar.zst

Expected impact

Should match Turbo's "instant" feel — single sequential read +
one tar invocation rather than N copies. Will validate against
your 100-pkg / 300-task benchmark.

https://claude.ai/code/session_016HXj6HW6bxSn8EYuKcxTD9

---

Generated by Claude Code