ci(cache): Actions cache budget が main で恒常的に 85% 閾値を超える(削除による緩和は main-cache-absent を生む)

[rizumita]

観測

main の cache budget audit が ca2d5e7d (push) で failure。run 33047056553。

budget-exhausted: cache usage is 11.55 GiB of a 10.00 GiB limit (116%), at or above the 85%
threshold. 11.55 GiB is 1.55 GiB above the limit; a sufficiently large save can trigger
least-recently-used eviction, including a default-branch cache that a main-targeting pull
request depends on.

内訳(実測、上位):

サイズ	key	最終アクセス
2.72 GiB	v0-rust-semantic-mutation-Linux-x64-718c915e-9efe1eb7	06:29
2.72 GiB	v0-rust-semantic-mutation-Linux-x64-0b9fd15e-9efe1eb7	06:46
1.50 GiB	v0-rust-rust-workspace-Linux-x64-718c915e-9efe1eb7	06:46
1.50 GiB	v0-rust-rust-workspace-Linux-x64-0b9fd15e-9efe1eb7	06:46
1.35 GiB	v0-rust-wasm-Linux-x64-718c915e-9efe1eb7	06:46
1.16 GiB	v0-rust-rust-native-z3-Darwin-arm64-cf75cde1-9efe1eb7	06:46

718c915e 世代と 0b9fd15e 世代が並存しており、大きい3キー
(semantic-mutation, rust-workspace, wasm)がそれぞれ二重に乗ると
それだけで 85% 閾値 (8.5 GiB) に達する。

削除による対処を試し、裏目に出た(記録)

旧世代 718c915e の3件(2.72 + 1.50 + 1.35 GiB)を削除して 11.55 GiB → 5.99 GiB (60%) にした。
その後 audit を再実行した結果は failure、finding が 2 件に増えた:

budget-exhausted: cache usage is 8.84 GiB of a 10.00 GiB limit (88%), ...
main-cache-absent: no `refs/heads/main` cache for shared key `wasm` on platform `Linux`.

2つの事実が分かった。

1. 使用量はすぐ埋め戻る。 削除の直後にローカルで測ると 5.99 GiB だが、audit の再実行時点では
   8.84 GiB だった。走行中の CI が保存を続けるため、この観測量は分単位で動く。
   単発の計測で「解消した」と判断できない。
2. 削除は main-cache-absent を新たに生む。 現行世代 0b9fd15e には wasm エントリが無く、
   wasm の refs/heads/main キャッシュは削除した 718c915e の1件だけだった。実測で確認:
   削除後に wasm を含むキャッシュは Linux-wasm-bindgen-cli-0.2.126(8 MB、別キー)のみ。
   結果として main-targeting PR の wasm ジョブがコールドになる。

つまり削除は運用的な緩和にならない。削除する場合は最低限「そのキーが refs/heads/main の
唯一のエントリではないこと」を事前に確認する必要があり、それを確認すると削除できるキーはほとんど残らない。

求める対応(構造的削減)

以下のいずれか、または組み合わせ:

1. 世代の並存を短くする。 キーに含まれる2つのハッシュ(718c915e / 0b9fd15e 側)が何に
   由来するかを明示し、restore-keys で旧世代から復元できるなら旧世代の保存を止める。
2. 保存対象を絞る。 semantic-mutation (2.72 GiB) と rust-workspace (1.50 GiB) が
   同じ target/ の大部分を二重に持っていないか確認する。共有できるなら1つにする。
3. 共有キーの main エントリを保証する。 main-cache-absent が出るキー集合について、
   main で必ず1エントリが保存される経路(どのワークフローがそのキーを save するか)を
   設計文書に書き、監査がその不在を検出したときの復旧手順も書く。
4. docs/DESIGN-ci.md の "Actions cache budget" 節 (docs/DESIGN-ci.md:514) に、
   監査が赤になったときの正しい対応を書く。今回は「削除」を選んで finding を増やした。
   その反例を節に残す。

補足

この audit は post-merge の main で走り、PR では cache budget audit wiring として別に緑になる。
つまり PR では検出されず main で初めて落ちるクラスであり、native Z3 レーンと同じ性質を持つ。

[rizumita]

追加観測: 削除したキャッシュは走行中の run では戻らない

wasm の main キャッシュを削除した後、ca2d5e7d の product gate (run 33047056408) の
WASM ジョブは success したが、キャッシュは再保存されなかった。実測: 削除から30分以上後も
gh cache list に v0-rust-wasm-* は1件も無い。

機構: そのジョブは私の削除より前に開始してキャッシュを復元済みであり、Swatinem/rust-cache は
cache hit のときは保存しない。つまり削除は「次にそのキーで cache miss する run」まで穴が空いたままになる。

これは対処手順として重要:

• キャッシュを削除したら、その穴は自動では埋まらない。 埋めるには対象キーで cache miss する
  run を新たに走らせる必要がある(main への次の push、または該当ワークフローの手動実行)。
• したがって budget-exhausted を削除で緩和すると、main-cache-absent が
  次の main push まで残る。その間 main-targeting PR はそのキーでコールドビルドになる。

docs/DESIGN-ci.md:514 の "Actions cache budget" 節に書くべき復旧手順は、
「削除 → 対象キーで miss する run を意図的に走らせる → audit 再実行」の順序を含む必要がある。

[rizumita]

スコープを #835 と整理する。

#835(2026-08-18 起票)が既に同じ audit の over-budget から「recovery diagnosis が恒久的に手作業である部分を直す」ことを求めており、本 issue と実質的に重複していた。私の起票時に既存 issue を確認しなかった。

分割:

• 診断出力の改善は meta(ci): the cache budget audit cannot distinguish reclaimable superseded duplicates from genuine growth, so recovery diagnosis stays manual #835 が正本 — replacement group の判定、reclaimable bytes、irreducible 総量の報告。本 issue で実測した3点(削除が main-cache-absent を生む / 削除した穴は走行中の run では埋まらない / 使用量は分単位で動く)は meta(ci): the cache budget audit cannot distinguish reclaimable superseded duplicates from genuine growth, so recovery diagnosis stays manual #835 にコメントとして移した。特に「key prefix だけでは superseded と判定できない、世代ごとに存在するキー集合が違う」は meta(ci): the cache budget audit cannot distinguish reclaimable superseded duplicates from genuine growth, so recovery diagnosis stays manual #835 の replacement group 判定の要件になる。
• 本 issue に残すのは構造的削減と手順の記載:
  1. 世代並存の短縮(restore-keys で旧世代から復元できるなら旧世代の保存を止める)
  2. 保存対象の絞り込み(semantic-mutation 2.72 GiB と rust-workspace 1.50 GiB が同じ target/ の大部分を二重に持っていないか)
  3. docs/DESIGN-ci.md:514 の "Actions cache budget" 節に、監査が赤になったときの正しい対応順序を書く(「削除 → 対象キーで miss する run を走らせる → audit 再実行」)。今回「削除」だけを選んで finding を増やした反例を節に残す。

重複起票は私の確認漏れ。#835 を先に読むべきだった。

[rizumita]

構造の実測(推測ではなく設定から)

#835 で「重複 2.08 GiB を解消すれば 9.41 GiB → 7.33 GiB (73%) で 85% 閾値以下」と定量化した。
その重複がどこから来るかを .github/workflows/ci.yml から実測した。

shared-key の割り当て

shared-key	ジョブ数	行	workspaces	save-if
rust-workspace	3	:120, :163, :701	rust -> target	2つが github.event_name != 'pull_request'、:701 は save-if: false(読むだけ)
semantic-mutation	2	:482, :541	rust -> target	github.event_name != 'pull_request'
(未設定 → ジョブ名由来)	3	:294, :375, :426	rust -> target	—

項目2 の疑いは構造として裏付けられた

rust-workspace と semantic-mutation は同じ rust -> target をキャッシュしている。
異なるのはキーだけで、対象ディレクトリは同一である。現在の実サイズ:

• rust-workspace: 1.50 GiB × 2世代 = 3.00 GiB
• semantic-mutation: 2.72 GiB × 1世代

合計 5.72 GiB = 総量 9.41 GiB の 61%。

項目1(世代の並存)の機構

rust-workspace は main push ごとに2つのジョブが保存する(save-if が pull_request 以外で真)。
キーのハッシュが変わるたびに新世代が生まれ、旧世代は LRU 退避まで残る。
restore-keys の prefix 一致があるなら、旧世代は新世代が存在する時点で冗長である。

同じことが native-z3-Windows(0.58 GiB × 2世代)にも起きている。

実装時に確認すべきこと(まだ未検証)

1. restore-keys が実際に prefix 一致で旧世代から復元しているか。しているなら
   旧世代の保存を止められる(項目1)。していないなら旧世代の削除は次回コールドを招く。
2. rust-workspace と semantic-mutation を統合できるか。mutation ジョブは mutant を追加で
   ビルドするので、統合すると相互に thrash する可能性がある。統合が安全でないなら、
   統合ではなく「どちらかの保存対象を絞る」方向になる。
3. キャッシュ設定の変更は全ジョブをコールドにし得る。meta(ci): the cache budget audit cannot distinguish reclaimable superseded duplicates from genuine growth, so recovery diagnosis stays manual #835 が記録したとおり
   main-cache-absent は次に当該キーで miss する run まで埋まらないので、変更後に
   意図的にその run を走らせる手順が必要。

上記1〜3は設定を読んだだけの構造分析であり、restore 挙動の実測はしていない。
実装者はまず1を実測すること。

[rizumita]

項目1 の答え: restore-keys の prefix 復元は起きていない。旧世代は容量を占めるだけ

run 33067448407 の2つの attempt のログを直接読んだ。native Z3 4.16 (windows-latest):

attempt	キャッシュのログ行	経過	結果
1	No cache found.	61分12秒	timeout(cancelled と報告)
2	Cache hit for: v0-rust-rust-native-z3-Windows_NT-x64-368f6b88-9efe1eb7 / Restored from cache key "…-368f6b88-…" full match: true.	44分10秒	success

私の先の推測の訂正

#835 に「e61e1838 からの prefix 部分復元になり 60分予算を超えた」と書いた。それは誤りだった。
1回目は部分復元ではなく No cache found.(復元ゼロ) である。

attempt 1 の時点で旧世代 e61e1838 は存在していた(その後のインベントリで確認済み)。
それでも No cache found. だった。つまり:

restore-keys による prefix 一致復元は、少なくともこのジョブでは働いていない。

項目1 の方針が変わる

本 issue の項目1 は「restore-keys で旧世代から復元できるなら旧世代の保存を止める」だった。
前提が成り立たないので、結論はより単純になる:

旧世代は復元に使われていない。容量を占めるだけである。 したがって:

• 旧世代の保存を止めることは安全(復元機会を奪わない)。項目1 は条件付きではなく無条件に実施できる。
• ただし「止める」実装は save-if の条件では表現できない(save するかどうかはキーが変わったかで決まる)。
  実際に必要なのは、キーが変わったときに旧エントリを消すか、
  restore-keys を効かせて世代を1つに保つかのどちらかである。
• 後者を選ぶなら、なぜ現状 prefix 復元が効いていないのかを先に突き止める必要がある
  (Swatinem/rust-cache の restore-keys 設定の有無、あるいはキーの構造)。
  .github/workflows/ci.yml の当該ステップに restore-keys 相当の設定があるかを確認すること。

影響の大きさ(再掲、数値は確定)

• キャッシュあり: 44分 → 予算 60分に対し 16分の余裕
• キャッシュなし: 61分 → 1分超過して kill

このジョブが緑になるかどうかは、キャッシュが1件あるかどうかで決まる。 旧世代が容量を食って
一致キーを退避させている限り、main の required product gate は間欠的に赤になる。

まだ未検証

• rust-workspace(1.50 GiB × 2世代)と semantic-mutation(2.72 GiB)が同じ target/ の
  大部分を二重に持つか(項目2)。両者は同じ workspaces: rust -> target を指しているが、
  中身の重複率は測っていない。
• 他のジョブでも No cache found. が起きているか。windows Z3 以外は未確認。

[rizumita]

追記: 範囲の実測と、世代が「死に票」である機構

前のコメントで「restore-keys の prefix 復元は働いていない」と書いたが、範囲を測ったら
そのジョブのその時点だけだった。同じ run 33067448407 の他ジョブ:

ジョブ	キャッシュのログ
native Z3 4.16 (windows-latest) attempt 1	No cache found.
native Z3 4.16 (windows-latest) attempt 2	full match: true
WASM	full match: true
mutation mutants	full match: true
rust workspace	(キャッシュ行が取れず。ログ形式が違う可能性)

したがって「restore-keys が全体的に効かない」のではない。一致キーが存在すれば full match で復元し、
退避されていれば No cache found. になる。

世代が死に票である機構(観測からの導出)

No cache found. の時点で旧世代 …-Windows_NT-x64-e61e1838-9efe1eb7 は存在していた。
2つのキーは v0-rust-rust-native-z3-Windows_NT-x64- まで共通で、違うのは hash1
(e61e1838 vs 368f6b88)、hash2(9efe1eb7)は同じ。

それでも No cache found. になったので、有効な restore-key は hash1 を切り落としていない。
.github/workflows/ci.yml の当該ステップに restore-keys の明示指定は無く、
shared-key も無い(キーはジョブ名由来)。

結論: 旧世代は新しいキーの復元には永久に使われない。 容量だけを占め、
その容量が LRU 退避を引き起こして一致キーを消す。つまり旧世代の存在が、
自分より新しい世代の復元機会を奪っている。

したがって削減方針は単純になる

• 旧世代を消すことは復元機会を奪わない(元々使われない)。項目1 は条件付きでなく実施できる。
• ただし削除は meta(ci): the cache budget audit cannot distinguish reclaimable superseded duplicates from genuine growth, so recovery diagnosis stays manual #835 で実測したとおり次にそのキーで miss する run まで穴が残る。
  新世代が既に存在するキーの旧世代だけを消すなら、その穴は生じない
  (新世代が full match するため)。これが最も安全な削減手順である。
• 恒久策としては、キーが変わったときに旧エントリを消す仕組みか、
  hash1 を含まない restore-keys を明示して世代を1つに保つか。後者は
  「古い target を復元して部分的に再利用する」挙動になるので、
  ビルド時間が縮むか伸びるかは実測が必要(rust-cache の部分復元は必ずしも速くない)。

数値(確定)

• キャッシュあり: 44分10秒 / 予算 60分 → 16分の余裕
• キャッシュなし: 61分12秒 → 1分超過して kill

このジョブの緑/赤は、一致キーが1件あるかどうかで決まる。

[rizumita]

訂正: 項目1 の前提が誤っていた。キーは交替し、旧世代は「使われない」のではない

先のコメントで「旧世代は復元に使われず容量を占めるだけ」「したがって旧世代の保存を止めることは
安全」と書いた。どちらも誤りである。 詳細と実測は #835 のコメントに書いた。要点:

hash1 は 2値(e61e1838 / 368f6b88)の間で交替しており、「古い/新しい」ではない。
私が「旧世代」として削除した e61e1838 を必要とする commit が来て、
main の product gate が No cache found. から 61分38秒でタイムアウトした
(cache 総量は 73% で閾値以下だったので、budget 超過は原因ではない)。

項目1 の書き直しが必要

本 issue の項目1 は「restore-keys で旧世代から復元できるなら旧世代の保存を止める」だった。
実態は:

• restore-keys は hash1 を切らないので、異なる hash1 の間で復元は起きない(これは正しかった)
• しかし hash1 は世代ではなく交替する2値なので、両方が現役である
• したがって「旧世代の保存を止める」対象が存在しない

先に特定すべきは「なぜ hash1 が2値を行き来するのか」である。 それが分かるまで、
削除も保存停止も安全に設計できない。Swatinem/rust-cache のキー計算に入る要素
(rustc バージョン、Cargo.lock、env、workspaces の解決結果など)のどれが
2状態を持つのかを実測すること。

項目2・項目3 は影響を受けない

• 項目2(rust-workspace と semantic-mutation が同じ rust -> target を二重に持つか)は
  独立した観察であり、有効なまま。
• 項目3(docs/DESIGN-ci.md:514 に復旧手順を書く)も有効。ただし書く内容が変わる:
  「削除してよい条件」ではなく、**「手で削除しない。現役キーを消す危険がある」**が
  現時点で正しい運用である。

私が今日踏んだ順序(記録として)

1. 午前: 旧世代を無条件削除 → main-cache-absent を作った
2. 午後: 「新世代が実在するか確認してから削除」という判定を導入 → 94% → 73% に削減、
   穴は生じなかったとその時点では見えた
3. 夜: その削除が原因で main の product gate がタイムアウト

2の判定は1より良いが、まだ誤っていた。 「新しいエントリが存在する」は
「このキーはもう要らない」を意味しない。

[rizumita]

The growth mechanism is now measured, in #835: Swatinem/rust-cache folds every installed Rust toolchain into the first key hash, not just the pinned one. Two concurrent windows-latest jobs on the same commit computed different keys (368f6b88 with 1.98.0 alone, e61e1838 with the image's preinstalled 1.97.1 plus 1.98.0), both legitimately live.

That makes the 85% overrun on main genuine growth, not reclaimable duplication: every runner-image change strands the previous key permanently — about 591 MiB per Windows entry and 1.1 GiB per macOS entry — while the new key is created alongside it. Nothing in the cache listing distinguishes the stranded entry from the live one, because the distinguishing input (the image's toolchain list) only appears in a job log's Cache Configuration group.

It also settles this issue's parenthetical, "削除による緩和は main-cache-absent を生む", more sharply than when it was written: hand deletion is unsafe even with a freshness predicate, because the newest entry can be the least reused one. The entry created most recently on 2026-08-27 (368f6b88, 13:21Z) came from a cancelled job's cache-on-failure post step, while the entry most jobs actually compute was older. Deleting by recency deleted the live one and cost the next main push a cold 61m38s Windows gate against a 60-minute limit.

See #835 for the full measurement table and for the proposed structural reduction (normalize the toolchain set before rust-cache runs, so one (job, OS, lockfile) triple yields one key across image rollouts). That reduction is what would let this issue's threshold be met by construction rather than by periodic manual reclamation; it is not applied yet and costs one cold build per OS when it lands.