# 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`

- [x] Write failing tests for URI/timeout validation, lifecycle close, binary get/set/delete and
  `EVALSHA -> NOSCRIPT -> EVAL`.
- [x] Confirm RED before adding the Lettuce production dependency.
- [x] Add `io.lettuce:lettuce-core` using the Boot BOM and update the affected dependency locks.
- [x] 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.
- [x] 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`

- [x] Write failing tests for hit, negative hit, miss, incompatible schema, positive/negative TTL,
  invalidation and provider failure certainty.
- [x] Confirm RED.
- [x] 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.
- [x] 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.

- [x] If a local Redis image is available, run an explicit real-service program/cache test; never
  silently skip it.
- [x] Mark standalone runtime/cache as R1 unless real service, restart, ACL/TLS and fault evidence
  required by the readiness card all pass.
- [x] Run the leaf check, dependency lock check, env-key gate and architecture gate.