ci: a Zig cache is one cold build, saved once

[foxnne]

Follows #232, now merged; rebased onto main. It touches only ci.yml.

What changes

Every other CI run on main was building from nothing, and this fixes it. I first guessed that cancelled runs were the cause. The logs show otherwise:

Run	What its Linux test cache did
37320334563, main, 10-05	Cold; ended at 3.67 GB, under the limit, so it was saved
37682171347, main, 10-07	Restored 683 MB (compressed); ended at 6.94 GB and was "exceeding limit of 5368709120 bytes; clearing cache", so it was saved empty
37785306976, main, 10-08	Restored that empty cache (188 B) and built from scratch, about 10 min
37786098520 and 37786730490, 10-08	7.07 GB and 5.69 GB, both cleared and saved empty

The cause is how setup-zig caches. It saves each run under a new key and restores the newest, so a warm run saves what it restored plus everything it rebuilt. For Linux, one run is enough to go past the limit, and an over-limit cache is saved empty. Cancellation only took part because cancelled runs grow too. The near-duplicates also fill the repo's 10 GB of Actions cache, which stood at 9.6 GB.

Now:

• setup-zig's own caching is off (use-cache: false). It still points ZIG_GLOBAL_CACHE_DIR and ZIG_LOCAL_CACHE_DIR at .zig-cache.
• Each job restores and saves .zig-cache itself with actions/cache/restore and actions/cache/save, under a fixed key: Zig version, job, OS, arch, and the hash of every build.zig.zon, taken before anything is unpacked.
• A fixed key can't be overwritten, so only a run that missed saves, and only if it succeeded. A job's cache is one complete cold build (about 3.7 GB for Linux tests), and every later run with the same dependencies, Zig and OS starts from it. Nothing reaches a size limit, warm runs upload nothing, and a run cancelled or failed mid-build never leaves a partial cache.
• A bug fixed on the way: Windows build (fizzy backend, cross-compiled) still computed its key inline, the bug the test job's comment already described. Restore asked for d259c36b… and save wrote a0d09007…, so it missed every time (run 37786098520: "Cache miss"). It now takes its key from a step, like the other jobs.

What a warm run keeps, and what it doesn't:

• It reuses the expensive, unchanging parts: package downloads (no network, so no HttpConnectionClosing), the C libraries (SDL3 ×5, freetype, tree-sitter), and the build tools.
• The app, tests and wasm are rebuilt whenever their code changed, which is true of nearly every commit. That was already the case for warm runs.
• A cache is rebuilt from cold only when a build.zig.zon, Zig or the runner OS changes.

Not touched: web.yml's build job also uses setup-zig's caching. Its entries stay around 264 MB, so it doesn't hit the limit. It could move to the same scheme later.

SDK impact

• None

Verified

• The workflow parses. Each of the three jobs runs: key step → setup-zig (use-cache: false) → restore → … → save, with save gated on success() && cache-hit != 'true'. No setup-zig cache inputs remain.
• Live: this PR's first run will miss every new key (cold) and save one entry per job. Its next run should restore them ("Cache restored from key: zig-0.16.0-test-Linux-X64-…") and skip "Save Zig cache". I'll check both before asking for a merge.
• After merge, main's first run is cold once and saves main's copies, which every PR then restores. The old setup-zig-cache-v2-* entries go unused and age out after 7 days, or sooner under the 10 GB limit.

Follow-ups

• Move web.yml to the same scheme if its cache ever grows.

🤖 Generated with Claude Code