[mgravell]

Stacked on #3349 (marc/v4-cache-result-reuse); only the last commit is new here.

What

A caching layer built on top of the client-side cache (StackExchange.Redis.HybridCache's tag-timestamp memo is the concrete consumer; a FusionCache backplane adapter is a prospective second) keeps derived structures coherent with cached keys, and needs to be told when a key stops being current. This adds that: a per-context removal observer.

var ctx = db.AsRespContext().WithRemovalHandler(static (key, reason) => ...);

• CacheKeyRemovedHandler — void (ReadOnlySpan<byte> key, CacheKeyRemovalReason reason); the span is the key exactly as stored (prefixes included), valid only for the callback.
• CacheKeyRemovalReason — Invalidated (server push), LocalWrite (our own write), Replaced (a fresh fill displaced a live value, e.g. refresh-ahead), Expired (aged out, fired at physical reclamation), Evicted (budget), Flushed (flush/reconnect/dispose).

Enrollment model: one-shot, armed by the read

You hear about the keys you read, nothing else. Each read through the context arms one notification for that key; the first removal at-or-after the read consumes it; reading again re-arms. That makes exactly-once structural (Interlocked.Exchange take), needs no unenrollment API, and bounds dangling handlers — a consumer that stops reading a key stops hearing about it after at most one trailing event, and dropping a notification on the floor is always safe.

Observers hang on the key-table node, not the entry: invalidation touches the node while entry release is lazy, nodes are immortal and carried by reference across growth, and Node.Key is already an immortal byte[] — so slab compaction is invisible (not a death, enrollment survives) and dispatch needs no key copy.

The contract holds under the races:

• arm-then-recheck on the hit path: either the invalidation's take sees the new observer, or the second look sees the invalidation and fires here.
• a fill that raced an invalidation enrolls after the store, then rechecks: the consumer gets the value and an immediate Invalidated.
• a stale-grace serve (value handed out already dead) likewise fires immediately — an already-wrong value is announced, never smuggled.
• only a still-valid entry fires at release/replace: an invalidated corpse already announced itself, and firing again would steal next-epoch enrollments.

Dispatch

Never on the killing thread. NotifyRemoved takes the observer set and queues one ThreadPool.QueueUserWorkItem — the same model as pub/sub (CompleteAsWorker) — so user code never runs on the socket reader, under the key table's all-stripe locks (flush queues under them, fires after), or on the evictor. Handler exceptions are swallowed per handler. Cost when unused: one null field per key-table node and a null check per death.

Scope cuts, documented in code: a fill whose CLIENT CACHING YES prefix was dropped enrolls nothing (no invalidation will ever come), error replies likewise, and the shared-fill fallback send has no dependencies to enroll. Under default admission the doorkeeper's first-miss read isn't a fill, so coverage starts when caching does.

Tests

14 new tests in RespCacheRemovalTests cover every contract point: each reason, one-shot/re-arm, the fill-race (an executor that invalidates mid-send), stale-grace announcement, two consumers, a throwing consumer not silencing another, prefix fidelity, compaction-is-not-death (real slab promotion churn), and residency at fire time. Full cache/tracking sweep: 284/284 across 17 classes; all TFMs build clean.

[mgravell]

Reworked per review discussion: the per-knob withers are gone. WithCachePolicy(CachePolicy) is the one extension point (both context types), CachePolicy is now a record carrying RemovalHandler, and a handler on the DefaultPolicy gives connection-wide enrollment (new test). A per-read policy replaces the default wholesale and narrows-never-widens on lifetime; RefreshAfter/grace are now genuinely per-caller (grace still gated on the default policy's stamping). Docs updated.