Declare a machine-readable cache and trust contract

[rldyourmnd]

Caching in this library is currently whatever each pinned setup action does by
default, plus one deliberate exception. There is no single machine-readable
contract saying what may be cached, by whom, restored from where, and with what
trust level — so the properties below are true by accident rather than by
construction.

What is already right

• release.yml sets enable-cache: false on setup-uv, with the reasoning in a
  comment: a cache entry written from a lower-trust ref would otherwise become an
  input to a release build (zizmor cache-poisoning, high).
• Action and tool pins are immutable, so the code that populates a cache is fixed.
• Some workflows can disable caching on warm self-hosted runners.

What is missing

No declared contract covering:

• repository/tenant namespace, and what isolates one caller's entries from another's
• which event and ref trust levels may write a cache versus only restore one
• the dependency inputs that must appear in a key for a hit to be meaningful
• exact-key versus prefix/restore-keys behaviour, and default-branch fallback
• persistent self-hosted state: what survives a job, and what must be cleaned
• eviction/retention, and what a cold versus warm run is expected to cost
• hosted/fleet equivalence — whether the same key means the same thing on both

Why it matters here specifically

GitHub's cache scoping is ref-based with default-branch fallback, and a pull
request's cache is scoped to the merge ref. A cache is not signed provenance. On a
persistent self-hosted runner the workspace itself is additional retained state
that GitHub makes no cleanliness guarantee about. Any of those can turn a cache
into an input nobody reviewed.

Suggested shape

1. Inventory every cache producer and consumer across the reusables — setup-uv,
   setup-go, setup-gradle, Flutter/Qt, ccache, package managers, container
   layers, and anything a fleet keeps locally.
2. Declare the contract in catalog/, in the same style as
   workflow-routing.yml and python-execution.yml, and compile it fail-closed.
3. Add adversarial checks: PR merge-ref scope, default-branch fallback, a
   hostile branch writing a key a trusted job restores, stale/corrupt entries,
   and fleet workspace residue.
4. Record cold and warm timings so the optimisation is measured, without
   narrowing any verification to buy the speed.

This is not a proposal to disable caching. It is a proposal to make it a typed
optimisation with proven trust boundaries.

Not currently a demonstrated exploit — no poisoned-cache path has been shown
in this repository. This is a completeness gap, and it should be scoped and
prioritised as one.

[rldyourmnd]

Inventory and contract are done in #168 (35ce81d). The adversarial runtime half stays open here.

What landed

catalog/cache-contract.yml names all eight cache-capable actions in the tree, each with the input that controls it and its behaviour with no input at all. The part that was genuinely invisible: three cache without being asked — actions/setup-go, gradle/actions/setup-gradle and hendrikmuhs/ccache-action.

Six refusals are declared job-exactly rather than as prose: the release resolve job, the CodeQL analysis (a restored build cache lets compilation be skipped, so the analysis covers less than it appears to), and all four ci-gate jobs. Two of those gate jobs previously relied on setup-uv not caching by default; they state it now. Nothing changes today, which is the point — the blocking gate must not begin taking an unreviewed input because somebody else's default moved.

check_cache_contract.py runs in the blocking tier and is fail-closed in both directions. Discovery uses two signals, because one was not enough: a step taking a cache-shaped input, and an action whose name says it caches — the input test alone let ccache-action through, since its key input is called key. Stale declarations are findings too, so the contract cannot quietly stop describing the tree.

Proven by mutation: flipping the release refusal fails and quotes the reason; removing ccache-action from producers fails naming both call sites; a declared producer nobody uses fails.

What is honestly not covered

Recorded in the validator's own docstring rather than left implied: an action that caches by default and exposes no input at all is invisible to static analysis. default_caches is recorded per producer precisely because classifying a new dependency stays a human judgement made when it is added.

And the four items from the original list that need experiments across a trust boundary:

• pull-request merge-ref scope and default-branch fallback, observed rather than described;
• a hostile branch writing a key a trusted job then restores;
• stale or corrupt entry behaviour;
• persistent self-hosted workspace residue, and cold-versus-warm timings.

Those need a disposable estate and deliberate cross-trust runs — the same shape as #133 and #135 — so this issue stays open for them rather than being closed on the half that was tractable.