tech-log-backend/docs/superpowers/plans/2026-07-28-redis-cache-resilience.md

Redis Cache Resilience Implementation Plan

Repository commit policy is human-only. Do not stage, commit, amend or push.

Goal: Implement the approved cache-aside, bounded source protection and soft/hard TTL design without promoting Redis beyond standalone cache R1.

Task 1: Application cache-aside outcomes and policy

Files:

• Create/modify src/application-core/src/main/java/dev/caskeleton/application/cache/*

• Test src/application-core/src/test/java/dev/caskeleton/application/cache/*

• Write RED tests for fresh/negative/miss/stale/source outcome transitions.

• Add typed loader, failure, result, cancellation and immutable policy contracts.

• Implement cache-aside sequencing; only authoritative absence may be negative-cached.

• Preserve unclassified exceptions and interruption.

• Verify focused application cache tests GREEN.

Task 2: Bounded local single-flight and source bulkhead

Files:

• Create CacheSingleFlight.java

• Create CacheSourceBulkhead.java

• Test their concurrency behavior through focused unit tests.

• Write RED concurrency tests.

• Bound in-flight keys, waiters, admission wait and load wait.

• Remove completed/failed/abandoned flights and preserve loader failure fan-out.

• Prove Redis outage cannot create unlimited source concurrency.

Task 3: Redis soft/hard TTL, jitter and stale envelope

Files:

• Modify RedisCacheRegionPolicy.java

• Modify RedisCacheEnvelopeCodec.java

• Modify RedisStringCacheRegion.java

• Modify/add focused Redis cache tests.

• Write RED boundary, jitter, minimum and schema-compatibility tests.

• Add an injected Clock and deterministic policy-revision jitter.

• Encode absolute soft/hard expiry in envelope version 2.

• Use the encoded hard expiry as physical Redis TTL.

• Verify focused Redis tests GREEN.

Task 4: Documentation and verification

• Synchronize the completed foundation-plan checkboxes with existing code/evidence.
• Update Redis README/CLAUDE/design readiness truth.
• Run application and Redis leaf checks.
• Run dependency locks, architecture, public path, env and diff checks.
• Request independent specification and code-quality review.