rust-cache: split registry from target, prune before the target save

One entry mixed the small, lockfile-bounded registry with the huge, churning target: every lock change re-uploaded everything, the restore-key fallback accreted each generation's stale artifacts into the next, and the tar/zstd staging of a raw multi-gigabyte target has filled a runner disk at save time.

The registry entry (index + tarballs + git db, toolchain-independent) keeps the restore-and-save behavior behind the existing save toggle.
The target entry becomes restore-only in rust-cache; the new rust-cache-save action prunes target/ down to dependency artifacts — workspace-member objects, final binaries, examples, incremental state and docs are rebuilt or relinked on any commit — and uploads under the exact key the restore computed, handed over via GITHUB_ENV so the halves cannot diverge.
It runs as the consumer's last job step, because composite actions have no post hooks; an exact restore hit skips prune and save, and save: false is the pull-request mode of the restore-everywhere/save-on-main pattern.

Measured on a consumer workspace, the prune selects only member artifacts (2201 paths; dependency objects untouched) and the qa target entry is expected to drop from ~3.1 GB compressed to roughly a third.
The selftest covers prune-keeps-the-dependency, prune-drops-the-member and the save: false no-op; actions/cache moves to v6 across the four uses, and the README gains the split's story plus a cache-size operations section (inventory, deleting superseded generations, clearing PR leftovers).

Author: gronke

.github/actions/rust-cache-save/action.yml

@@ -0,0 +1,39 @@
+name: Rust cache save
+description: >-
+  The save half of `rust-cache` for the target/ entry: prune target/ down to dependency artifacts,
+  then upload under the exact key the restore computed (handed over via $GITHUB_ENV, so the halves
+  cannot diverge). Call it as the LAST step of the job — composite actions have no post hooks, so
+  this is what runs "after the build, before the upload". An exact restore hit skips both prune and
+  save (the stored entry is already pruned and current). Jobs that should only consume — pull
+  requests, with the default branch's warmup feeding them — omit this action or pass save: false;
+  to also save when a build step failed, put `if: always()` on this step in the workflow.
+
+inputs:
+  save:
+    description: >-
+      Upload the pruned target. Pass `${{ github.ref == 'refs/heads/main' }}` for the
+      restore-everywhere/save-on-main pattern.
+    required: false
+    default: "true"
+  working-directory:
+    description: Workspace directory whose `cargo metadata` names the members to prune.
+    required: false
+    default: "."
+
+runs:
+  using: composite
+  steps:
+    # Dependency artifacts are the cache's value; everything else is rebuilt or relinked on any
+    # commit and only grows the archive plus the tar/zstd staging that can fill the runner disk.
+    - name: Prune target to dependency artifacts
+      if: ${{ inputs.save == 'true' && env.RUST_CI_TARGET_KEY != '' && env.RUST_CI_TARGET_HIT != 'true' }}
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      run: bash "$GITHUB_ACTION_PATH/prune-target.sh"
+
+    - name: Save target
+      if: ${{ inputs.save == 'true' && env.RUST_CI_TARGET_KEY != '' && env.RUST_CI_TARGET_HIT != 'true' }}
+      uses: actions/cache/save@v6
+      with:
+        path: ${{ env.RUST_CI_TARGET_DIR }}
+        key: ${{ env.RUST_CI_TARGET_KEY }}

.github/actions/rust-cache-save/prune-target.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Prune target/ down to what a cache is worth keeping: DEPENDENCY artifacts.
+# Workspace-member objects, final binaries, examples, incremental state and
+# docs are rebuilt or relinked on any commit — caching them only grows the
+# archive and the tar/zstd staging that can fill the runner disk at save time.
+#
+# DRY_RUN=1 prints what would go instead of removing it, for local runs.
+set -euo pipefail
+
+target="${RUST_CI_TARGET_DIR:?rust-cache did not export RUST_CI_TARGET_DIR}"
+if [ ! -d "$target" ]; then
+  echo "no $target directory; nothing to prune"
+  exit 0
+fi
+
+remove() {
+  if [ "${DRY_RUN:-}" = "1" ]; then
+    printf 'would remove %s\n' "$@"
+  else
+    rm -rf -- "$@"
+  fi
+}
+
+du -sh "$target" | sed 's/^/before: /'
+
+# Workspace member names; their compiled artifacts use underscores.
+members=$(cargo metadata --no-deps --format-version 1 | jq -r '.packages[].name' | tr '-' '_')
+
+# Incremental state (defaulted off, but belt and braces), examples and docs,
+# in the top-level and per-triple profile directories.
+while IFS= read -r dir; do
+  remove "$dir"
+done < <(find "$target" -mindepth 1 -maxdepth 3 -type d \
+  \( -name incremental -o -name examples -o -name doc \) 2>/dev/null)
+
+# Every profile directory: target/<profile>/ and target/<triple>/<profile>/,
+# recognized by their deps/ directory.
+for dir in "$target"/*/ "$target"/*/*/; do
+  [ -d "${dir}deps" ] || continue
+  # Top-level files are final binaries and their dep-info: always relinked.
+  while IFS= read -r file; do
+    remove "$file"
+  done < <(find "$dir" -maxdepth 1 -type f 2>/dev/null)
+  for name in $members; do
+    for pattern in "${dir}deps/${name}-"* "${dir}deps/lib${name}-"* \
+      "${dir}.fingerprint/${name}-"* "${dir}build/${name}-"*; do
+      [ -e "$pattern" ] || continue
+      remove "$pattern"
+    done
+  done
+done
+
+du -sh "$target" | sed 's/^/after:  /'

.github/actions/rust-cache/action.yml

@@ -4,9 +4,18 @@ description: >-
   CI (no edit→recompile loop) and the main thing that balloons target/ — while OBEYING an explicit
   CARGO_INCREMENTAL the consumer sets (some matrix/variant builds are faster with it on). It does not
   impose a build profile: the build stays cargo's default unless the consumer sets CARGO_* vars, which
-  flow through unchanged (incl. into the Docker actions via their CARGO_.* forwarding). Caches cargo's
-  download cache (registry index + .crate tarballs + git db) via the first-party actions/cache;
-  optionally caches target/ too, kept bounded by the Cargo.lock-based key (no restore-key ratchet).
+  flow through unchanged (incl. into the Docker actions via their CARGO_.* forwarding).
+
+  Two independent cache entries, split by churn rate. The REGISTRY entry (index + .crate tarballs +
+  git db, never registry/src — cargo re-extracts it, caching it is pure duplication) is small,
+  toolchain-independent and bounded by the Cargo.lock key; it restores here and saves at job end
+  unless `save: "false"`. The TARGET entry (opt-in via cache-target) is restore-ONLY here: a
+  restore-key fallback plus save-on-new-key would accrete every generation's stale artifacts into
+  the next one, so the save lives in the paired `rust-cache-save` action, which prunes target/ down
+  to dependency artifacts first and runs as the consumer's LAST job step (composite actions have no
+  post hooks, so an auto-save could not run after the build). Jobs that should only consume — PR
+  jobs reading what a default-branch warmup maintains — simply omit the save step.
+
   Avoids third-party cache actions whose behaviour drifts with the runner image.
 
 inputs:
@@ -16,45 +25,51 @@ inputs:
     default: rust
   save:
     description: >-
-      Also save the cache at job end (the actions/cache post step). Set "false" for restore-only
-      consumers — e.g. PR jobs reading a cache that a default-branch warmup job maintains, where
-      per-branch saves would only burn quota and job minutes.
+      Also save the REGISTRY entry at job end (the actions/cache post step). Set "false" for
+      restore-only consumers — e.g. PR jobs reading a cache that a default-branch warmup job
+      maintains, where per-branch saves would only burn quota and job minutes. The target entry is
+      restore-only here regardless; its save belongs to `rust-cache-save`.
     required: false
     default: "true"
   cache-target:
     description: >-
-      Also cache the build target/ directory (keeps compiled dependencies between runs). Off by
+      Also RESTORE the build target/ directory (compiled dependencies between runs). Off by
       default — registry/git alone is small and always safe; turn it on for a heavy dependency tree
-      where recompiling every run is the bottleneck. Bounded by the Cargo.lock-based key (no
-      restore-key ratchet); leave CARGO_INCREMENTAL at its default (off) to keep it tight.
+      where recompiling every run is the bottleneck. Saving the target back is the paired
+      `rust-cache-save` action's job (typically only on the default branch).
     required: false
     default: "false"
   target-dir:
-    description: Workspace-relative target directory to cache when cache-target is true (e.g. an out-of-workspace crate's target).
+    description: Workspace-relative target directory to restore when cache-target is true (e.g. an out-of-workspace crate's target).
     required: false
     default: target
   lockfiles:
-    description: Glob of lockfile(s) whose hash keys the cache.
+    description: Glob of lockfile(s) whose hash keys the caches.
     required: false
     default: "**/Cargo.lock"
   cache-directories:
-    description: Extra newline-separated paths to add to the cache.
+    description: >-
+      Extra newline-separated paths to add to the registry entry (bounded, lockfile-keyed) — suited
+      to vendored/download caches that track the lockfiles.
     required: false
     default: ""
 
+outputs:
+  target-cache-hit:
+    description: '"true" when the target entry restored from its exact key.'
+    value: ${{ steps.target.outputs.cache-hit }}
+
 runs:
   using: composite
   steps:
     # Incremental compilation is pure cost in CI (no edit→recompile loop) and is what balloons target/
     # — gigabytes of codegen units + dep-graph data that are never reused across runs. Defaulting it
     # off is the single biggest size reduction and is what makes caching target/ safe; a consumer who
     # knows a variant build benefits can still set CARGO_INCREMENTAL and have it honoured.
-    - name: Configure cargo for CI + compute cache key
+    - name: Configure cargo for CI + compute cache keys
       id: meta
       shell: bash
       env:
-        CACHE_TARGET: ${{ inputs.cache-target }}
-        TARGET_DIR: ${{ inputs.target-dir }}
         EXTRA_DIRS: ${{ inputs.cache-directories }}
       run: |
         set -euo pipefail
@@ -63,50 +78,76 @@ runs:
         if [ -z "${CARGO_INCREMENTAL:-}" ]; then echo "CARGO_INCREMENTAL=0" >> "$GITHUB_ENV"; fi
         if [ -z "${CARGO_TERM_COLOR:-}" ]; then echo "CARGO_TERM_COLOR=always" >> "$GITHUB_ENV"; fi
 
-        # Fold the toolchain into the key so a rustc bump can't reuse incompatible artifacts.
+        # Fold the toolchain into the TARGET key so a rustc bump can't reuse incompatible
+        # artifacts. The registry (downloads only) is toolchain-independent.
         if command -v rustc >/dev/null 2>&1; then
           rust=$(rustc -V | sha256sum | cut -c1-12)
         else
           rust=norustc
         fi
         echo "rust=$rust" >> "$GITHUB_OUTPUT"
 
-        # Cache cargo's DOWNLOAD cache — registry index + .crate tarballs + git db. Never
-        # registry/src: cargo re-extracts it from the tarballs, so caching it is pure duplication
-        # (it roughly doubles the registry footprint for no benefit). The cargo home comes from
-        # CARGO_HOME when set — container images that bake the toolchain elsewhere (e.g.
-        # /opt/cargo) rely on it, and $HOME/.cargo would cache a directory cargo never touches.
+        # Cargo's DOWNLOAD cache — registry index + .crate tarballs + git db. Never registry/src:
+        # cargo re-extracts it from the tarballs, so caching it is pure duplication (it roughly
+        # doubles the registry footprint for no benefit). The cargo home comes from CARGO_HOME when
+        # set — container images that bake the toolchain elsewhere (e.g. /opt/cargo) rely on it,
+        # and $HOME/.cargo would cache a directory cargo never touches.
         CARGO_DIR="${CARGO_HOME:-$HOME/.cargo}"
         {
-          echo 'paths<<__PATHS__'
+          echo 'registry_paths<<__PATHS__'
           echo "$CARGO_DIR/registry/index"
           echo "$CARGO_DIR/registry/cache"
           echo "$CARGO_DIR/git/db"
-          if [ "$CACHE_TARGET" = "true" ]; then echo "$TARGET_DIR"; fi
           if [ -n "$EXTRA_DIRS" ]; then printf '%s\n' "$EXTRA_DIRS"; fi
           echo '__PATHS__'
         } >> "$GITHUB_OUTPUT"
 
-    # actions/cache restores here and auto-saves at job end (its post step runs even when nested in a
-    # composite action). An exact-key save is skipped on a hit, so an unchanged Cargo.lock never grows
-    # the cache; a changed lock seeds a fresh entry and the stale one is LRU-evicted — no ratchet.
-    # `save: "false"` swaps in the restore-only variant of the same first-party action.
-    - name: Cache cargo registry/git (+ target)
+    # Registry: restores here and auto-saves at job end (its post step runs even when nested in a
+    # composite action). An exact-key save is skipped on a hit, so an unchanged Cargo.lock never
+    # grows the cache; a changed lock seeds a fresh entry and the stale one is LRU-evicted — no
+    # ratchet. `save: "false"` swaps in the restore-only variant of the same first-party action.
+    - name: Cache cargo registry/git
       if: inputs.save == 'true'
-      uses: actions/cache@v5
+      uses: actions/cache@v6
       with:
-        path: ${{ steps.meta.outputs.paths }}
-        key: ${{ inputs.prefix }}-${{ runner.os }}-rust-${{ steps.meta.outputs.rust }}-${{ hashFiles(inputs.lockfiles) }}
+        path: ${{ steps.meta.outputs.registry_paths }}
+        key: ${{ inputs.prefix }}-${{ runner.os }}-registry-${{ hashFiles(inputs.lockfiles) }}
         restore-keys: |
-          ${{ inputs.prefix }}-${{ runner.os }}-rust-${{ steps.meta.outputs.rust }}-
-          ${{ inputs.prefix }}-${{ runner.os }}-rust-
+          ${{ inputs.prefix }}-${{ runner.os }}-registry-
 
-    - name: Restore cargo registry/git (+ target) without saving
+    - name: Restore cargo registry/git without saving
       if: inputs.save != 'true'
-      uses: actions/cache/restore@v5
+      uses: actions/cache/restore@v6
+      with:
+        path: ${{ steps.meta.outputs.registry_paths }}
+        key: ${{ inputs.prefix }}-${{ runner.os }}-registry-${{ hashFiles(inputs.lockfiles) }}
+        restore-keys: |
+          ${{ inputs.prefix }}-${{ runner.os }}-registry-
+
+    # Target: restore-only (see the action description); `rust-cache-save` prunes and uploads under
+    # the same key, handed over via $GITHUB_ENV so the two halves can never diverge.
+    - name: Restore target
+      if: inputs.cache-target == 'true'
+      id: target
+      uses: actions/cache/restore@v6
       with:
-        path: ${{ steps.meta.outputs.paths }}
-        key: ${{ inputs.prefix }}-${{ runner.os }}-rust-${{ steps.meta.outputs.rust }}-${{ hashFiles(inputs.lockfiles) }}
+        path: ${{ inputs.target-dir }}
+        key: ${{ inputs.prefix }}-${{ runner.os }}-target-${{ steps.meta.outputs.rust }}-${{ hashFiles(inputs.lockfiles) }}
         restore-keys: |
-          ${{ inputs.prefix }}-${{ runner.os }}-rust-${{ steps.meta.outputs.rust }}-
-          ${{ inputs.prefix }}-${{ runner.os }}-rust-
+          ${{ inputs.prefix }}-${{ runner.os }}-target-${{ steps.meta.outputs.rust }}-
+          ${{ inputs.prefix }}-${{ runner.os }}-target-
+
+    - name: Hand the target key to rust-cache-save
+      if: inputs.cache-target == 'true'
+      shell: bash
+      env:
+        KEY: ${{ inputs.prefix }}-${{ runner.os }}-target-${{ steps.meta.outputs.rust }}-${{ hashFiles(inputs.lockfiles) }}
+        HIT: ${{ steps.target.outputs.cache-hit }}
+        TARGET_DIR: ${{ inputs.target-dir }}
+      run: |
+        set -euo pipefail
+        {
+          echo "RUST_CI_TARGET_KEY=$KEY"
+          echo "RUST_CI_TARGET_DIR=$TARGET_DIR"
+          echo "RUST_CI_TARGET_HIT=${HIT:-false}"
+        } >> "$GITHUB_ENV"

.github/workflows/selftest.yml

@@ -84,6 +84,33 @@ jobs:
           fi
           echo "✓ malicious tool name rejected; no injection"
 
+      # The save half of rust-cache: prune target/ to dependency artifacts,
+      # upload under the restore's key. Runs as (nearly) the last step, the
+      # position consumers use; a fresh key exercises prune + upload, an
+      # exact-hit re-run skips both (the stored entry is already pruned).
+      - name: rust-cache-save (fixture; prune + upload)
+        uses: ./.github/actions/rust-cache-save
+        with:
+          working-directory: fixtures/sample-crate
+
+      - name: prune kept the dependency and dropped the member
+        if: env.RUST_CI_TARGET_HIT != 'true'
+        run: |
+          deps=fixtures/sample-crate/target/debug/deps
+          ls "$deps" | grep -q '^liblibc-' || {
+            echo "::error::dependency artifacts missing after prune"; exit 1; }
+          if ls "$deps" | grep -q '^cicd_rust_selftest_fixture-'; then
+            echo "::error::workspace member artifacts survived the prune"; exit 1
+          fi
+          echo "✓ prune kept libc, dropped the member"
+
+      # save: false is the pull-request mode — the step must no-op.
+      - name: rust-cache-save honours save=false (no-op control)
+        uses: ./.github/actions/rust-cache-save
+        with:
+          save: "false"
+          working-directory: fixtures/sample-crate
+
   # The Docker action set: build the image locally (no GHCR dependency to prove)
   # and run fetch (networked) -> lint/test (sealed, --network none) -> readiness
   # (networked) against the fixture.