feat(cache): give same-ref jobs separate build directories via cache-lineage

A cache key names a REF. What a target directory holds is the product of a ref
and a build configuration, and emowheel builds the same ref twice on every
push — once for the host, once for wasm32, in two jobs that start together.
Keyed on the ref alone, `cargo-cache@v1` handed both the same
CARGO_TARGET_DIR, and Cargo's target-directory lock is exclusive: the second
job sat on "Blocking waiting for file lock on build directory" for the length
of the first while holding a runner capacity slot, so a third repo's queued
job waited behind a job doing nothing.

`cache-lineage` is that second dimension. It names ONE directory level under
the cache root:

    <cache-root>/target-<key>              no lineage (unchanged)
    <cache-root>/<lineage>/target-<key>    a lineage

Nesting, not a suffix on the key, and that is the whole design decision.
`prune-cache.sh`'s liveness pass classifies a directory by recomputing
`target-<cache_key(branch)>` for every branch on origin and evicting whatever
does not match — a `target-<key>-wasm32` matches nothing, so it would be
classified dead and evicted unconditionally on every run. daniel/gitdan's
host-level arbiter reads the same shape (BRANCH_DIR_RE); a suffixed name falls
out of that too, so those caches would never be reclaim candidates and a whole
lineage would go missing from the shared disk budget. Nesting leaves both
matchers reading exactly the names they already read, one level down — which
is a layout that arbiter already walks (CI_CACHE_MAX_DEPTH is 2, and its own
suite pins the depth-2 case).

Every interacting part, checked rather than assumed:

- SEED: `seed-target-dir.sh` takes the root as an argument, so a PR branch in
  a lineage layers over THAT lineage's base snapshot. Asserted.
- PUBLISH: `publish-snapshot.sh` derives both ends of the swap from the root.
  The publish action now takes the root from the `CARGO_CACHE_ROOT` the
  consume step exported, and CHECKS its own inputs against it — a publish step
  left at the default while its consume step nested would otherwise republish
  a different lineage's live target dir over that lineage's snapshot, on every
  push, silently. `mode: release-lock` is exempt: it releases a lock on
  `$CARGO_TARGET_DIR` and never touches a root.
- WATERMARK: per target dir, so it follows the lineage. Unchanged.
- PRUNE and LIVENESS: scoped to the root they are given, so a pass in one
  lineage neither evicts nor sees a sibling's caches, or the flat layout's.
  Liveness keeps resolving real branch names, which is what a key suffix would
  have broken.
- ci_cache_reclaim: verified by dry-run against a fixture in this layout —
  all six nested and flat dirs collected as candidates, protection resolved
  correctly on the nested ones, and a `.stage-` stranded inside the lineage
  found by the leftover sweep.

Refused lineage names are refused at resolve time, each rejection naming the
reader that imposes it: a path separator (the arbiter's depth budget), a
Cargo profile name (its no-descend list), a `target-`/`snapshot-` prefix (this
repo's own prune globs), a hex suffix (its per-branch-dir shape), a dot prefix
(the leftover-naming contract). None of these fails visibly on its own — each
produces a working directory that some pass silently stops seeing.

Setting no lineage resolves to the cache root byte for byte, so lublub, zemyna
and emowheel's `ci` job keep the exact directories they have on the volume.

New suite `cache-root-selftest.sh` (19 assertions), red-proven against three
deliberate breakages: a `cache_root_for` that ignores the lineage, a disabled
validator, and a `verify` that never rejects a mismatch.

cargo-cache/action.yml

@@ -10,6 +10,18 @@ inputs:
     description: 'Mount point of the persistent cache volume inside the job container.'
     required: false
     default: '/cache'
+  cache-lineage:
+    description: >-
+      Distinguishes two jobs that build the SAME ref for different targets or
+      profiles (a host build and a wasm32 build, say) and would otherwise
+      resolve to one CARGO_TARGET_DIR and serialise on Cargo's exclusive
+      build-directory lock. Names one directory level under cache-root:
+      <cache-root>/<lineage>/target-<key>. Must be a single path component;
+      several names are refused outright because a reader elsewhere would stop
+      seeing the caches under them (see validate_cache_lineage in
+      scripts/cache-lib.sh). Pass the same value to cargo-cache-publish.
+    required: false
+    default: ''
   protected-branches:
     description: >-
       Space-separated refs that publish snapshots and are never evicted.
@@ -54,8 +66,9 @@ inputs:
   watermark-file:
     description: >-
       Name of this job's build-watermark file inside the target dir. MUST be
-      distinct per job when two jobs share one cache key. Defaults to
-      .ci-watermark-<job>-sha.
+      distinct per job when two jobs share one target directory — which two
+      jobs no longer need to do; cache-lineage gives them separate ones.
+      Defaults to .ci-watermark-<job>-sha, already distinct per job.
     required: false
     default: ''
   lock-id:
@@ -74,6 +87,12 @@ outputs:
   cache-key:
     description: 'Sanitized cache key for this run''s own ref.'
     value: ${{ steps.resolve.outputs.cache-key }}
+  cache-root:
+    description: >-
+      Resolved cache root — cache-root, plus the lineage directory when one is
+      set. Every directory this action reads or writes is under it. Also
+      exported as CARGO_CACHE_ROOT.
+    value: ${{ steps.resolve.outputs.cache-root }}
   seeded-from:
     description: 'Where the target dir came from: own | base-snapshot | own-snapshot | fallback-dir | concurrent-peer | cold.'
     value: ${{ steps.seed.outputs.seeded-from }}
@@ -95,6 +114,16 @@ runs:
     # `base_ref` is populated only for pull_request events. A push run has
     # nothing to layer over: its own ref IS the reference branch. It
     # publishes, it does not consume.
+    #
+    # The cache root is resolved first because every path below hangs off it.
+    # A lineage nests one directory level (`<root>/<lineage>/target-<key>`),
+    # which is what lets two jobs on ONE ref hold two build directories and so
+    # not serialise on Cargo's exclusive lock. It is resolved through
+    # cache-root.sh rather than interpolated here so the name is validated —
+    # several otherwise-reasonable lineage names put their whole subtree out of
+    # reach of a pass that has to see it. Everything downstream reads the
+    # resolved value, and it is exported as CARGO_CACHE_ROOT so the publish
+    # action can check it agrees with its own inputs.
     - id: resolve
       shell: bash
       run: |
@@ -102,6 +131,8 @@ runs:
         SCRIPTS=$(cd "${{ github.action_path }}/.." && pwd)/scripts
         [ -d "$SCRIPTS" ] || { echo "::error::cargo-cache: scripts/ not found at $SCRIPTS"; exit 1; }
         echo "CARGO_CACHE_SCRIPTS=${SCRIPTS}" >> "$GITHUB_ENV"
+        CACHE_ROOT=$(bash "${SCRIPTS}/cache-root.sh" resolve \
+          "${{ inputs.cache-root }}" "${{ inputs.cache-lineage }}")
         OWN_REF="${{ inputs.own-ref }}"
         [ -n "$OWN_REF" ] || OWN_REF="${{ github.head_ref || github.ref_name }}"
         BASE_REF="${{ inputs.base-ref }}"
@@ -116,7 +147,7 @@ runs:
           echo "cache: own ref '${OWN_REF}' -> ${OWN_KEY} (no base ref — this ref publishes, it does not consume)"
         fi
 
-        TARGET_DIR="${{ inputs.cache-root }}/target-${OWN_KEY}"
+        TARGET_DIR="${CACHE_ROOT}/target-${OWN_KEY}"
         WATERMARK="${{ inputs.watermark-file }}"
         [ -n "$WATERMARK" ] || WATERMARK=".ci-watermark-${{ github.job }}-sha"
         LOCK_ID="${{ inputs.lock-id }}"
@@ -128,10 +159,11 @@ runs:
           echo "base-key=${BASE_KEY}"
           echo "lock-id=${LOCK_ID}"
           echo "watermark-file=${WATERMARK}"
+          echo "cache-root=${CACHE_ROOT}"
         } >> "$GITHUB_OUTPUT"
         {
           echo "CARGO_TARGET_DIR=${TARGET_DIR}"
-          echo "CARGO_CACHE_ROOT=${{ inputs.cache-root }}"
+          echo "CARGO_CACHE_ROOT=${CACHE_ROOT}"
           echo "CARGO_CACHE_KEY=${OWN_KEY}"
           echo "CARGO_CACHE_LOCK_ID=${LOCK_ID}"
           echo "CI_WATERMARK_FILE=${WATERMARK}"
@@ -155,7 +187,7 @@ runs:
         bash "${SCRIPTS}/seed-target-dir.sh" \
           "${{ steps.resolve.outputs.cache-key }}" \
           "${{ steps.resolve.outputs.base-key }}" \
-          "${{ inputs.cache-root }}" \
+          "${{ steps.resolve.outputs.cache-root }}" \
           "${{ github.job }}-${{ github.run_id }}-$$" \
           "${{ inputs.seed-fallback-dir }}" \
           "${{ steps.resolve.outputs.lock-id }}"
@@ -206,7 +238,7 @@ runs:
         set -euo pipefail
         SCRIPTS=$(cd "${{ github.action_path }}/.." && pwd)/scripts
         bash "${SCRIPTS}/prune-cache.sh" \
-          "${{ inputs.cache-root }}" \
+          "${{ steps.resolve.outputs.cache-root }}" \
           "${{ steps.resolve.outputs.target-dir }}" \
           "${{ inputs.protected-branches }}" \
           "${{ inputs.min-free-percent }}"