Coalesce simultaneous availability misses for one key

Project context

A fictional equipment-rental service caches availability summaries. A campaign sends repeated reads, while stock updates and shared expiry times create bursts against the origin. Build a local origin stub and cache-backed read API using synthetic depots and products.

Setup prerequisites

• Create a deterministic local availability origin and Redis-backed reader with synthetic tenant, depot and product data.
• Use a seeded hot-key distribution and controlled time; record cache capacity, TTLs, runtime and machine limits.

Preceding work

Complete these dependencies, or supply their agreed outputs before taking this ticket.

• PCACHE-101 · Specify which availability responses may be reused
• PCACHE-102 · Measure saved origin work instead of celebrating the hit ratio
• PCACHE-103 · Create a hot-key workload that exposes synchronized expiry

Acceptance criteria

• Share one bounded in-flight fill per semantic key within the declared process scope.
• Give each waiter its own deadline and release the in-flight entry on success, failure and cancellation.
• Keep different tenants and keys independent, and document that process-local coalescing does not coordinate multiple instances.

Implementation constraints

• Use a deterministic origin latch to prove fan-in; a fast origin can hide duplicate concurrent fills in a timing-only test.

Verification to include

• Release 100 simultaneous same-key reads and verify one origin fill with identical successful results.
• Cancel some waiters and fail the fill; verify remaining outcomes, cleanup and a successful subsequent retry.

Deliverables

• Single-flight implementation and concurrency/failure regressions

Rollout and recovery

Gate coalescing locally; disabling it preserves the same freshness contract and drains existing waiters before removing entries.

Value of the work

For the engineer: Learn to evaluate caching through avoided work, bounded staleness, concurrency and recovery rather than hit rate alone.

For the team: Produce a reviewable cache policy and failure exercise for a read-heavy service with changing business data.

Evidence boundaries

Outcome Evidence: Tests, patches, and runbooks are requested deliverables. They become Outcome Evidence only through a qualified Mission and immutable Evidence IDs.

Ownership Evidence: Independent adaptation must be observed under a declared verification policy and cite immutable Evidence IDs. Completing a planning ticket establishes no Ownership Evidence.