fix(ci): key the chipdb cache on the openXC7 image so it can hit

[gHashTag]

Part of #851. Fixes #843 and #845.

What was wrong

61 workflows build the nextpnr-xilinx chipdb for an openXC7 job. Before this PR only one of them could reuse it:

class	before	after
OK: an exact key that changes when the image changes	1	54
NEVER_HIT: key carries github.run_id, so cache-hit is never true and the build step always runs (#843)	48	0
STALE_RISK: fixed key on a floating regymm/openxc7 tag (#845)	5	0
NO_CACHE: other parts or a source-built nextpnr (#846)	7	7

Counts are from tri devkit speed coverage --repo ., run on main and on this branch.

What changes

A composite action, .github/actions/openxc7-chipdb:

1. It resolves the image the job's nextpnr runs to its local image ID. It pulls the image only if the runner does not already have it, so the chipdb and the job use the same image.
2. It restores ~/.cache/openxc7-chipdb/<part>.bin under the key chipdb-<part>-<image id>-bbasm-le-v1.
3. On an exact miss it builds the chipdb inside that image (bbaexport.py then bbasm -l). It saves it at once with actions/cache/save, so a later nextpnr failure does not lose it.
4. It copies the file to the workflow's own out path.

Why one cached path for every workflow. actions/cache folds the path list into the entry version. Caching each workflow's out path directly would store 50 copies of one identical file.

53 workflows have their cache step and guarded build step replaced by one step:

- id: chipdb
  uses: ./.github/actions/openxc7-chipdb
  with:
    part: xc7a200tfbg484-2
    out: build/gf10_sub/chipdb/xc7a200tfbg484-2.bin

The step keeps the id chipdb, so any later steps.chipdb.outputs.cache-hit still resolves. The four build-* workflows pass image: regymm/openxc7:latest. The two tnf-* workflows pass their pinned @sha256: image.

How the rewrite was checked

• The rewrite was done by a script, not by hand. For each file:
  • the new YAML must parse to the old document with exactly the two chipdb steps replaced by the one above;
  • the file must re-classify as OK.
• The script refuses shapes it does not model:
  • more than one chipdb cache step;
  • no guarded build step next to it;
  • more than one image;
  • shell variables in the part or path;
  • no actions/checkout before the step.
• Negative controls:
  • 5 of 5 corrupted rewrites are refused: a wrong out path, a dropped step name, a changed job field, a lost id, and the old build step kept.
  • 5 of 5 mutants of the coverage checker are killed.
• The coverage checker reads the action itself. It reports NEVER_HIT if the action is missing, or if its key loses the image ID, uses a per-run key, caches out directly, or does not save early.
• All 54 changed YAML files parse. The action's run steps all name a shell.
• shellcheck is clean on the action's three run steps.
• actionlint (with shellcheck) on the changed workflows reports 124 findings. All of them are shellcheck notes on run steps this PR does not touch, and none mentions the chipdb step.

When this merges

46 of the 53 changed workflows list their own file in push: paths, so the merge push starts 46 FPGA runs at once.

• They run in parallel against an empty main cache, so each one builds its chipdb, as every run does today. One of them saves the entry, and the rest log that another job is creating it.
• From then on, every run on main, and every branch and PR, restores that entry while the image stays the same.
• If ci(cache): prune Actions cache entries nothing can restore #853 merges first, the entry also has room to survive.

Measured on CI

ax7203-gf10-sub.yml was run twice on this branch, with main as the control.

run	ref	chipdb step	result
37197232296	this branch, first	3 m 19 s	"Cache not found", then built and saved before nextpnr (11:09:41; nextpnr starts 11:09:41)
37198736545	this branch, second	1 s	Cache hit for: chipdb-xc7a200tfbg484-2-591b377b…-bbasm-le-v1, about 68 MB restored, build step skipped, 332105196 bytes cache-hit=true
37198621522	main, control	3 m 24 s	built; the Post Run actions/cache@v4 step was skipped because the job failed, so nothing was saved

All three fail later, at the nextpnr seed search, with a bare no clean seed. main fails the same way, so the failure was already there. Its last success on main was 2026-07-14, before regymm/openxc7:latest moved. Why it fails is #856, and #857 makes the log visible.

That failure also shows something the "after" column of the table above does not. On main, a run that fails after the chipdb step never saves the chipdb, so every failing run pays the build again. With the explicit early save here, the first run pays once, failure or not.

A change to the action itself (0c5f415)

The action is called by 46 workflows, and none of their triggers covered .github/actions/openxc7-chipdb/. So a change to the action alone ran nothing, on the PR or on main. speed actionpaths reported 0 PR and 0 push triggers on this branch before the commit, and 1 and 1 after. ax7203-led-onehot.yml, the smallest design with one seed, now runs on a PR or a push to main that touches the action.

Its first PR run, 37260180318 on refs/pull/852/merge, succeeded: chipdb step 2 m 54 s (Cache not found, built, then saved chipdb-xc7a200tfbg484-2-591b377b…-bbasm-le-v1, cache-hit=false), nextpnr 29 s, 9.3 MB .bit. It missed because a PR run reads only its merge ref and main, and the entry saved on this branch on 2026-10-04 had already been evicted (#844 comment 5987858206; #895 is the fix).

Not measured

• CI minutes saved. Earlier logs show about 5 minutes of chipdb build per job (runs 34017182751, 34016575130, 29338858369, 29325601871). That figure is not summed over the history.
• Cache size headroom. The repository was at 10.96 GB of caches, 163 of them setup-zig-cache-v2-* (ci: setup-zig caches fill the 10 GB Actions cache and evict every chipdb #844), and at 11.11 GB on 2026-10-05 03:54Z after ci(cache): prune Actions cache entries nothing can restore #853's prune merged. Chipdb entries can still be evicted, and this branch's was. ci(cache): prune to an 8 GB budget, and after brain-ci and CI #895 adds a budget that never spends a chipdb.

🤖 Generated with Claude Code

[github-actions]

X Brain Health Check

Score: 100.0/100
Status: 🟢 HEALTHY
Threshold: 80/100

X Brain is above merge threshold

[github-actions]

🧪 Brain Stress Test Results

Score: not measured (no stress test prints a Score: line)
Status: 🟢 PASS
Threshold: 270/300

X Stress test passed

[gHashTag]

Merge-order note: this PR and #897 both edit the chipdb steps of tnf-cost-sweep.yml, and git merge-tree reports a content conflict there. This PR swaps actions/cache + "Build chipdb" for the openxc7-chipdb composite action; #897 adds a "Package pins" step right after "Build chipdb". Resolution: keep the composite action, then the package-pins step. Whichever merges second gets rebased; I will do that after the first one lands.

🤖 Generated with Claude Code

[tri-claw]

Summary by t27-bees

This PR replaces per-workflow chipdb cache+build steps with a shared composite action keyed on the Docker image ID (not github.run_id), fixing cache misses on every run (#843) and stale caches from floating tags (#845). The action resolves the image to its local ID, restores/builds/saves the chipdb to a single canonical path, and copies it to each workflow's out directory.

Worth a look

• .github/actions/openxc7-chipdb/action.yml:54 – docker pull -q "$IMAGE" >/dev/null silences pull failures; if the pull fails (network, auth, missing image), the subsequent docker image inspect fails with an obscure error and the root cause is hidden.
• .github/actions/openxc7-chipdb/action.yml:53–55 – No set -e/set -o pipefail in the ident step; a transient docker image inspect error (e.g., daemon hiccup) would leave image_id empty, producing a malformed key and likely a confusing downstream failure.
• .github/actions/openxc7-chipdb/action.yml:65–70 – The build step runs bbaexport.py and bbasm via bash -c with && chaining; if bbaexport.py crashes with a non-zero exit but prints to stdout/stderr, the failure is captured, but any command outside the chain (e.g., the mkdir -p before docker run) would not fail the step on error.
• .github/actions/openxc7-chipdb/action.yml:73–77 – The actions/cache/save step runs only on cache miss. If the restore step reports a hit but the cached file is corrupted/truncated, the build is skipped and the workflow proceeds with a bad chipdb.
• .github/workflows/ax7203-trinet-baud.yml:66 / ax7203-trinet-fleet.yml:103 – The out path uses ${{ matrix.name }}; the action’s copy step (cp -f "$HOME/.cache/openxc7-chipdb/$PART.bin" "$OUT") receives the expanded path via env.OUT, which works, but the action does not validate that OUT’s parent directory is writable or that the matrix expansion doesn’t introduce unexpected characters.

---

_{Read: 55 files, +330 -605, the whole diff up to 60000 characters (the rest was not read). Head 779168a. Model: openai-compatible/nvidia/nemotron-3-ultra-550b-a55b. Commands: @t27-bees review | summary | help | pause | resume. Free for every repository.}