clean-architecture-backend-template/docs/superpowers/plans/2026-07-28-redis-runtime-cache.md

Redis Runtime And Semantic Cache Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking. Repository policy is human-only, so no step stages or commits changes.

Goal: Replace the SDK-less Redis seam with an opt-in managed Lettuce runtime, a real Lua executor, and a bounded semantic string-cache implementation.

Architecture: A package-private runtime owns RedisClient, connection and synchronous binary commands. The Lua executor uses the compiled catalog checksum and EVALSHA, falling back to EVAL only for NOSCRIPT. A versioned binary envelope distinguishes positive, negative and incompatible entries behind CacheRegionPort<String,String>.

Tech Stack: Java 21, Lettuce Core managed by Spring Boot 4 BOM, Spring Boot configuration properties, JUnit 5, optional Docker-backed Redis qualification.

---

Task 1: Add the managed runtime and typed program execution

Files:

• Modify: src/adapter/outbound/cache-redis/build.gradle

• Create: src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/RedisRuntimeSettings.java

• Create: src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/LettuceRedisRuntime.java

• Modify: src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/RedisCacheAdapterConfig.java

• Create: src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/LettuceRedisRuntimeTest.java

• Write failing tests for URI/timeout validation, lifecycle close, binary get/set/delete and EVALSHA -> NOSCRIPT -> EVAL.

• Confirm RED before adding the Lettuce production dependency.

• Add io.lettuce:lettuce-core using the Boot BOM and update the affected dependency locks.

• Implement a package-private runtime with finite command/shutdown timeouts, bounded reconnect behavior, and no connection side effects while disabled or in external-client mode.

• Verify focused tests GREEN.

Task 2: Implement the semantic cache region

Files:

• Create: src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/RedisCacheRegionPolicy.java

• Create: src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/RedisCacheEnvelopeCodec.java

• Create: src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/RedisStringCacheRegion.java

• Test: src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/RedisStringCacheRegionTest.java

• Write failing tests for hit, negative hit, miss, incompatible schema, positive/negative TTL, invalidation and provider failure certainty.

• Confirm RED.

• Implement a bounded versioned binary envelope and HMAC-derived physical keys. Support UPSERT; return NOT_RECORDED_PROVIDER_POLICY for opaque revision ordering the provider cannot prove.

• Confirm GREEN and run the complete Redis leaf test suite.

Task 3: Qualify and document without false promotion

Files:

• Modify: src/adapter/outbound/cache-redis/README.md

• Modify: src/adapter/outbound/cache-redis/CLAUDE.md

• Modify: docs/superpowers/specs/2026-07-26-redis-production-capability-design.md

• Modify: runtime configuration and env-key registry only for settings actually introduced.

• If a local Redis image is available, run an explicit real-service program/cache test; never silently skip it.

• Mark standalone runtime/cache as R1 unless real service, restart, ACL/TLS and fault evidence required by the readiness card all pass.

• Run the leaf check, dependency lock check, env-key gate and architecture gate.