What

Fixes stale Redis cache fills after invalidation by fencing Redis-backed cache misses internally.

The problematic sequence is:

1. A reader calls load() and misses.
2. Another flow writes newer backing data and invalidates the cache with purge() or flush().
3. The original reader finishes its stale read and calls save().
4. Without fencing, that stale value can repopulate Redis after invalidation.

This PR keeps the public cache API unchanged. Callers still use load(), save(), purge(), and flush() normally; the cache layer tracks an internal token for Redis miss fills and Redis only accepts the follow-up save when that token is still valid.

Why this is narrow

This intentionally keeps the fix Redis-focused:

• Only concrete Redis adapters create and validate fenced fill tokens: Redis, RedisCluster, and Redis\Multiplexing.
• Non-Redis storage adapters are unchanged.
• Adapter remains unchanged; the new behavior is behind a small Feature\FencedFill capability.
• Pool, Sharding, and CircuitBreaker only forward FencedFill when their inner adapter supports it, so Redis-backed wrapper deployments keep the same protection.
• Public method signatures and return types are unchanged.

Changes

• Adds internal Token and Feature\FencedFill types.
• Updates Cache to remember fill tokens only when the top-level adapter supports FencedFill.
• Stores pending tokens by normalized key/hash and bounds them to 1024 entries.
• Uses Swoole coroutine context for pending tokens when running inside a coroutine, so concurrent coroutine requests do not consume each other’s fill tokens.
• Clears matching pending tokens after successful same-instance purge(), including all known hashes for key-level purge.
• Adds Redis Lua scripts for atomic load/token checks, fenced saves, tombstone writes on purge, and tombstone cleanup on normal save.
• Uses short-lived Redis tombstones to reject stale fills after hash-level or key-level purges.
• Writes a short-lived Redis flush marker from Redis-family flush() implementations so pre-flush absent tokens cannot save after a flush.
• Expires absent fill tokens using the same TTL window as tombstones and flush markers.
• Keeps Redis Cluster tombstone keys hash-tagged to the same slot as the cache key. Redis Cluster checks the flush marker outside the per-key Lua script to avoid cross-slot Lua access, with a post-write cleanup check if a flush wins the race.
• Adds focused unit coverage for cache token bookkeeping and wrapper forwarding, plus Redis-only E2E coverage for purge and flush fencing scenarios.

Redis behavior

• Cache hits decode and return existing values.
• Plain adapter load() still returns false on misses.
• Cache::load() receives an internal token on Redis misses and returns false to callers.
• Cache::save() consumes the matching token and calls saveFenced() only for Redis fenced fills.
• Normal Redis saves still work without requiring a token and atomically clear the field tombstone.
• A purge writes a short-lived tombstone, so older miss tokens from other requests/processes cannot repopulate a purged value.
• A successful same-instance purge clears that instance’s pending fill token, so an explicit invalidate-then-save refresh flow can repopulate normally.
• A flush writes a short-lived marker, so absent tokens issued before the flush are rejected for TOKEN_TTL seconds.

Greptile follow-up

Latest Greptile P1s are now handled:

• Fence Redis flushes: Redis::flush() and Redis\Multiplexing::flush() now perform FLUSHDB and marker write in one Lua script. RedisCluster::flush() writes a marker after flushing masters and saveFenced() checks that marker before and after the per-key fenced save.
• Clear purge tokens: successful Cache::purge() now clears pending local fill tokens for the purged key/hash, or all known hashes for key-level purge.

Earlier Greptile notes:

• Wrapper forwarding: fixed by forwarding FencedFill through Pool, Sharding, and CircuitBreaker when supported by the inner adapter.
• Absent token lifetime: fixed by expiring absent fill tokens with TOKEN_TTL during fenced saves.
• Coroutine flush tokens: not changed; flush() increments the shared token generation, so old coroutine-context tokens are no longer looked up by later saves.
• PHP 8.2 parse error on typed constants: not changed; this repo requires PHP >=8.3 in composer.json.

Validation

Passed locally:

• php -l on all touched PHP files
• vendor/bin/phpunit --configuration phpunit.xml tests/Cache/Unit
• vendor/bin/phpstan analyse --level max src tests --memory-limit 2G
• vendor/bin/pint --test ... on touched files
• Temporary local Redis 7 Docker check for standalone Redis flush fencing:
  • verified FLUSHDB is accepted inside EVAL
  • verified the flush marker survives the flush
  • verified a pre-flush miss token is rejected after another cache instance flushes

Could not run the repo Redis E2E files from this host because the expected Docker DNS names are not resolvable here:

• redis
• redis-cluster

The Redis E2E attempt failed in setup/connection before assertions ran. Pint passes, but PHP 8.5 emits deprecation noise from Pint’s bundled dependencies.

Risk

Risk is limited to Redis-backed cache behavior and wrappers around Redis-backed adapters. The main compatibility surface is that Redis load(), fenced save(), purge(), and standalone flush() now execute Lua scripts, and Redis invalidations keep short-lived tombstone/flush markers for TOKEN_TTL seconds.