Dev: keep focused test builds fast and cache-bounded

Parent: #50 Related: #52

Problem

Repeated focused ReleaseFast test filters relinked the monolithic root test artifact under distinct cache keys. During baseline-JIT development, the repository-local .zig-cache grew to 92 GB and LLVM failed with No space left on device. Clearing only the reproducible cache recovered 92 GB. This made the intended focused-test workflow unnecessarily slow and unsafe for developer disks.

Resolution

Completed by 23526ac5 and 9ddc0d4b.

• zig build test-jit is a 91-test root over the production JIT, selector, AArch64 backend, and their actual dependencies; it does not link the Context/C-API/Worker integration root.
• zig build test-vm and zig build test-concurrency share one small production semantic executable. Their -Dtest-filter value is a runtime case selector, so distinct filters reuse the same linked artifact instead of creating another test image.
• zig build benchmark-comparison-test remains the focused benchmark-harness gate.
• CI runs all three focused engine steps while retaining the complete sharded root suite as the authoritative integration gate.
• tools/zig-cache-tool.sh report inspects the repository-local cache. prune --dry-run previews cleanup, and prune removes only the fixed .zig-cache and zig-out targets.
• The cleanup tool now removes .zig-cache coherently. Retaining Zig 0.17's c/, h/, and z/ metadata after deleting o/ caused an observed CacheCheckFailed; the fully cold cleanup avoids stale manifests.

Measured bound

On July 16, 2026, Zig 0.17.0-dev.956+2dca73595 on an Apple M3 Pro grew a fully cold repository cache to 121 MiB after ten distinct passing Debug invocations:

• four JIT filters: Tier claims, native entry, integer provenance, guarded unsigned
• three VM filters: numeric loop, packed array, property loop
• three concurrency filters: atomic increments, distinct property, join chain

The documented development-loop bound is 256 MiB. The measured cache contained one 55 MiB production semantic executable, four roughly 5–13 MiB JIT test artifacts, and 27 MiB of Zig metadata rather than ten monolithic root test images. The exact workflow and cleanup safety contract are documented in docs/dev-cache.md and linked from the README.

Acceptance criteria

• JIT/VM focused tests compile and link without the monolithic root test artifact.
• Ten distinct focused test invocations keep repository-local cache growth within a documented reasonable bound.
• CI still runs the complete root suite and focused steps use the same production modules/options.
• Developer documentation explains inspection and safe cleanup of reproducible Zig caches.
• No cleanup command can target paths outside the repository cache/build outputs.

Incident detail: repository-local .zig-cache reached 92 GB across distinct monolithic filtered-test artifacts and LLVM failed at 117 MB free. Reproducible Zig caches/build outputs were cleared across ~/Code/Libraries/zig-*; clean stale worktrees were removed, dirty worktree edits were preserved in named stashes before removal, and free space recovered to 108 GB. This is mitigation only; the focused-artifact/cache-bound acceptance work remains open.