docs: design replay Redis backends

Author: Enjoykkk

docs/superpowers/specs/2026-07-18-replay-redis-backends-design.md

@@ -0,0 +1,19 @@
+# Replay Redis Backends Design
+
+## Goal
+
+Extend `tests/sessions/test_replay_consistency.py` so every normal test run compares the InMemory baseline with SQLite and a deterministic mocked Redis backend. When `REPLAY_REDIS_URL` is set, the same replay cases also run against a real Redis server.
+
+## Design
+
+Keep all reusable test logic in `test_replay_consistency.py`. Add a minimal in-process Redis storage double implementing only the commands exercised by `RedisSessionService` and `RedisMemoryService`. Construct the existing Redis services with their storage dependency patched, then replace their storage instances with the shared test double. This exercises the production Redis service serialization and replay logic without requiring a Redis installation.
+
+`_create_backends()` will always return `in_memory`, `sql`, and `redis_mock`, except lightweight mode, which remains InMemory-only. If `REPLAY_REDIS_URL` is present, it will additionally return `redis` backed by the real server. Tests will assert the expected backend names, and the generated JSON report will include a comparison entry for each enabled backend.
+
+## Isolation and failure behavior
+
+Each replay creates independent mock storage. Real Redis uses per-run unique app, user, and session identifiers so stale keys cannot affect comparisons. Connection or command failures are not hidden as allowed differences: when a URL was explicitly supplied, the integration test fails with the Redis error. Backends are closed in `finally` blocks.
+
+## Verification
+
+First add a test requiring `redis_mock` in the default comparison and observe it fail. Then implement the smallest storage double needed to pass all ten replay cases. Run the replay test file without Redis, in lightweight mode, and—when a reachable `REPLAY_REDIS_URL` is available—with real Redis.