execution: abort cache transitions after interrupted read-ahead drain

[yperbasis]

Problem

Block read-ahead runs asynchronously and can populate StateCache from a committed read-only snapshot. The execution paths already wait for read-ahead before an unwind epoch bump or FCU cache apply, but WaitForWarmup did not report whether the warmup completed or the module context cancelled the wait. A caller could therefore continue without satisfying the drain precondition.

Solution

• WaitForWarmup and drainReadAhead report whether the warmup fully drained.
• unwindToCommonCanonical, updateForkChoice, and SetHead stop when shutdown interrupts the drain.
• Under ASSERT_STATE_CACHE, StateCache.Unwind rejects an unwind while a directly cache-populating read-ahead warmup is counted as in flight.
• A warmup uses one launch-time StateCache instance for both its diagnostic gauge and cache writes.

The database-close path intentionally ignores the result because it only needs a bounded wait before shutdown.

Scope

This PR covers only the direct BlockReadAheader lifecycle. It does not address:

• startup cache coherence across ProcessFrozenBlocks, tracked by execution: fence StateCache across frozen-block startup processing #22925
• stale fills from read views older than a forward cache apply, handled by execution, db: bind StateCache fills to transaction views and reject stale fills #22444
• stale fills from pre-unwind read views, tracked by execution/cache: stale-fill admission is one-sided — pre-unwind read views refill dead-fork values, and unwound keys bypass the flush cache-apply #22463

#21414 proposes routing read-ahead through the published SharedDomains. That implementation must preserve the requirement that read-ahead fully drains before an unwind or cache apply.

Testing

• TestStateCache_UnwindAssertsWarmupInFlight
• TestWaitForWarmupReportsDrained
• go test ./execution/cache ./execution/exec ./execution/execmodule
• go test -race -count=1 ./execution/cache ./execution/exec ./execution/execmodule
• make erigon integration
• repeated clean make lint

[Copilot]

Pull request overview

This PR hardens the lifecycle of asynchronous cache-populating warmups so they cannot race cache epoch bumps (unwind/clear) and contaminate canonical state, and it reduces unnecessary work in read-ahead warm paths.

Changes:

• Make read-ahead warmup draining report “fully drained vs interrupted”, and gate unwind/clear/FCU paths on a successful drain.
• Track in-flight warmups in StateCache and (under ASSERT_STATE_CACHE) assert that Unwind never runs while a cache-populating warmup is still running.
• Add side-effect-free “live binding” probes (CodeCache.ContainsLive / StateCache.HasLiveCode) so read-ahead can skip keccak+copy when a conditional put would no-op; add tests for the new behaviors.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
execution/execmodule/set_head.go	Bail out of SetHead unwind if read-ahead warmup drain is interrupted.
execution/execmodule/forkchoice.go	Treat interrupted warmup drain as shutdown and abort FCU handling early.
execution/execmodule/exec_module.go	Make drainReadAhead return a drained/undrained boolean; drain+clear on Start; enforce drain before unwind.
execution/exec/blocks_read_ahead.go	Add warmup Started/Done bracketing + cache snapshot binding; make WaitForWarmup return bool; implement negative stamping and “skip for live code” logic.
execution/exec/blocks_read_ahead_test.go	Add coverage for drained reporting, live-binding skip, and negative invalidation behavior.
execution/cache/state_cache.go	Add warmup gauge + assert in Unwind; expose HasLiveCode.
execution/cache/grow_lru.go	Add Peek passthrough for side-effect-free LRU probes.
execution/cache/code_cache.go	Add ContainsLive probe for “live binding” detection without recency/counter side effects.
execution/cache/cache_test.go	Add tests for CodeCache.ContainsLive and the unwind-vs-warmup invariant assertion.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mh0lt]

Heads-up: #21414's latest commit reworks the same read-ahead prefetch this PR hardens, taking a different approach — flagging so we can coordinate direction before either merges.

What #21414 does: warmBody now prefetches through the published SharedDomains (its own coordinated tx, sd.AsGetter) instead of the raw tx, and deletes cachePopulatingGetter — cache population becomes the SD's own read-fill. Driven by two invariants: the state cache is a SharedDomains implementation feature (only the SD writes it), and all reads go through the in-flight SD. This removes the one cache-writer that sat outside the SD, and reads now see in-flight tip state rather than committed-behind-tip state.

Direct conflict: both PRs edit blocks_read_ahead.go (+ its test, exec_module.go, forkchoice.go, set_head.go). #21414 deletes cachePopulatingGetter and its test; this PR extends both.

Complementary vs obviated, if the SD-routed prefetch is the agreed direction:

• Obviated: finding 12 (ContainsLive skip) and the negative-progress oracle — they harden a getter execution: FCU background-commit worker + generation-chain reader consistency #21414 removes; population and negative-stamping move into the SD read-fill.
• Still valuable, worth keeping on top of the SD-routed prefetch: Recommendation A (the WarmupStarted/WarmupDone gauge + Unwind assert — it enforces exactly the drain-before-epoch-bump execution: FCU background-commit worker + generation-chain reader consistency #21414 relies on for lifetime safety), the drain-precondition return values (drainReadAhead/WaitForWarmup reporting drained + call sites bailing — execution: FCU background-commit worker + generation-chain reader consistency #21414's SetHead calls drainReadAhead but currently ignores the result), and finding 10 (the pre-Start warmup gap).

My read: the SD-routed prefetch (remove the anomaly) with this PR's drain/gauge/finding-10 hardening layered on top is the clean combination — but it's your call on direction. Related: #22520 (SD-owned run-task API + dropping the parallel-exec start queue).

[yperbasis]

@mh0lt Agreed. On current main, the normal read-ahead drains before unwinds and FCU cache apply are already present. #22469 is therefore limited to making an interrupted drain a failed precondition and adding an optional ASSERT_STATE_CACHE diagnostic for direct read-ahead warmups.

The getter-specific optimization and behavior are no longer part of the PR. #21414 should preserve the successful-drain requirement when it routes read-ahead through published SharedDomains.

The broader cache-coherence cases remain separate: startup processing is #22925, forward stale read-view fills are #22444, and pre-unwind stale read-view fills are #22463.