Ci cache save if main only

.github/workflows/ci.yaml

@@ -40,6 +40,11 @@ jobs:
       with:
         components: rustfmt, clippy
     - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4  # v2.9.1
+      with:
+        # PRs restore from main's cache but don't write their own —
+        # otherwise every (rustc, Cargo.lock) tuple per PR adds a
+        # ~500 MB entry and the per-repo cache budget blows up.
+        save-if: ${{ github.ref == 'refs/heads/main' }}
     - run: cargo fmt --all -- --check
     - run: cargo clippy --workspace --all-targets --locked -- -Dwarnings
     - name: unit + integration tests (no docker)
@@ -56,6 +61,10 @@ jobs:
       run: sudo apt-get update && sudo apt-get install -y --no-install-recommends $LIBRDKAFKA_BUILD_DEPS
     - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8  # stable as of 2026-03-27
     - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4  # v2.9.1
+      with:
+        # See note in the `test` job: PRs restore but don't save,
+        # so PR runs don't proliferate the per-repo cache budget.
+        save-if: ${{ github.ref == 'refs/heads/main' }}
     - name: prepull e2e images
       run: |
         docker pull quay.io/ogunalp/kafka-native:latest &
@@ -73,6 +82,9 @@ jobs:
     permissions:
       packages: write
       contents: read
+      # The prune-superseded-caches step at the end of this job
+      # deletes obsolete buildkit blobs via `gh cache delete`.
+      actions: write
     steps:
     - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
     - uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a  # v4.0.0
@@ -117,3 +129,35 @@ jobs:
         cache-from: type=gha
         cache-to: type=gha,mode=max
         provenance: false
+    - name: prune superseded main buildkit caches
+      # Buildx writes content-addressed blobs and an index per build;
+      # the next main build only reads from the most recent entries
+      # (main rarely reverts), so older runs' blobs are dead weight
+      # that pushes the rust-cache and other useful entries closer
+      # to GHA's per-repo eviction ceiling. Keep the top N most-
+      # recently-created buildkit-* / index-buildkit-* entries on
+      # refs/heads/main; delete the rest.
+      #
+      # N=200 is roughly 2-4 main builds' worth (one multi-arch build
+      # writes ~30-50 entries). Adjust if a single build ever pushes
+      # close to the limit — symptom is the *next* main build going
+      # cold despite this step running.
+      if: github.ref == 'refs/heads/main' && github.event_name == 'push' && success()
+      env:
+        GH_TOKEN: ${{ github.token }}
+      run: |
+        set -euo pipefail
+        to_delete=$(gh cache list -R "$GITHUB_REPOSITORY" -L 1000 \
+          --json id,key,ref,createdAt \
+          --jq '[ .[]
+                  | select(.ref == "refs/heads/main")
+                  | select((.key | startswith("buildkit-")) or (.key | startswith("index-buildkit-")))
+                ]
+                | sort_by(.createdAt) | reverse | .[200:] | .[].id')
+        if [ -n "${to_delete:-}" ]; then
+          count=$(echo "$to_delete" | wc -l | tr -d ' ')
+          echo "Pruning $count superseded buildkit cache entries on main"
+          echo "$to_delete" | xargs -I {} gh cache delete -R "$GITHUB_REPOSITORY" {}
+        else
+          echo "No superseded buildkit caches to prune"
+        fi

.gitignore

@@ -1 +1,6 @@
 /target
+
+# Local design memos / shelf notes — useful for human resumption
+# of in-flight design work but not stable enough to commit. Files
+# matching this pattern stay in the working tree, unversioned.
+NOTES_*.md