65 lines
3.8 KiB
Markdown
65 lines
3.8 KiB
Markdown
# 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.
|