docs: design replay acceptance completion

Author: Enjoykkk

docs/superpowers/specs/2026-07-18-replay-acceptance-completion-design.md

@@ -0,0 +1,25 @@
+# Replay Acceptance Completion Design
+
+## Scope
+
+Complete Issue #89 acceptance coverage without modifying SDK source, adding dependencies, or creating more replay case files. All executable harness changes remain in `tests/sessions/test_replay_consistency.py`; the generated report and the required 150–300 Chinese-character design note remain in their existing locations.
+
+## Replay and summary flow
+
+The ten JSONL tracks remain the canonical inputs. Text, tool, state, and memory operations continue to use the production service APIs. Summary operations will use the production `SessionSummarizer` with a deterministic model double whose output is supplied by the JSONL operation. An always-true summarization check triggers the real summary creation and event-window compression path; the harness then records strict replay metadata—session ownership, version, update time, and replacement relationship—on the generated summary event before persisting it.
+
+## Modes and backends
+
+Default mode runs InMemory, SQLite, and mock Redis. Mock Redis replaces only Redis command storage while retaining production Redis Session/Memory services. `REPLAY_REDIS_URL` adds real Redis to the enabled backend set instead of replacing or invalidating default assertions. `REPLAY_LIGHTWEIGHT=1` runs all ten tracks with InMemory, validates snapshots and injected mutations locally, writes a valid report, and performs no cross-backend comparison.
+
+## Detection and metrics
+
+Each injected mutation is compared with the unmodified snapshot from the same backend, and its exact expected field path must appear. This prevents existing backend differences from satisfying injection assertions. Missing summary, replaced summary, and wrong summary ownership are passed through the same report-building comparison path and must include session ID, event index, path, expected value, and actual value. Normal-case false-positive rate is calculated from cases not marked as known backend defects and asserted at or below 5%.
+
+## Failure recovery
+
+Test-local fault wrappers inject acknowledged writes, rejected writes, and partial snapshot corruption without changing SDK implementations. Recovery checks assert event uniqueness/order, final state, memory idempotency, summary ownership/version, and absence of dirty data. Existing known InMemory aliasing differences remain real, unallowed differences and are not hidden through `allowed_diff`.
+
+## Verification
+
+Use red-green tests for each acceptance gap. Verify the full file in default and lightweight modes within 30 seconds, Black/Ruff formatting, report backend coverage, and optional real Redis behavior when a reachable URL is supplied. A configured but unreachable Redis URL fails explicitly rather than silently skipping.