# Event Replay Tool Design

**Date:** 2026-06-11
**Status:** Design proposal
**TODO:** TODO-043
**Requirements:** SysRS-171, SRS-098
**Effort:** L

## Purpose

Replay recorded protocol events for debugging state synchronization. Enables deterministic reproduction of state bugs by replaying a captured event sequence through the state reducer and comparing the result with expected state.

## Inputs

- Event log file (JSON or protobuf) recorded in diagnostics mode (SRS-097)
- Optional: expected final state snapshot for comparison

## Outputs

- Replayed session state at each step
- Diff between replayed state and expected state (if provided)
- Reducer execution trace for debugging

## Architecture

```text
┌──────────────┐     ┌───────────────┐     ┌──────────────────┐
│ Event Log    │────>│ Event Iterator│────>│ State Reducer    │
│ (JSON/PB)   │     │ (ordered)     │     │ (chanora_state)  │
└──────────────┘     └───────────────┘     └────────┬─────────┘
                                                     │
                                            ┌────────v─────────┐
                                            │ State Comparator │
                                            │ (expected vs     │
                                            │  actual)         │
                                            └──────────────────┘
```

1. **Load:** Parse event log file into ordered `StateEvent` sequence
2. **Iterate:** Feed events one-by-one to `chanora_state` reducer
3. **Capture:** Record state after each event for step-through debugging
4. **Compare:** If expected snapshot provided, diff final state against it
5. **Report:** Output pass/fail with reducer trace and state diff

## Implementation Plan

- New Rust binary crate: `tools/event-replay/`
- Reuse `chanora_state::ServerState` and reducer functions directly
- JSON event format matches `chanora_diagnostics` event recording output
- CLI interface: `event-replay <event-log> [--expected <snapshot>] [--trace]`
- `--trace` flag prints state after each event

## Dependencies

- `chanora_state` (reducer, ServerState)
- `chanora_diagnostics` (event log format)
- `serde_json` or `prost` (event deserialization)

## Verification

- Unit test: replay known event sequence, assert final state matches expected
- Integration test: record events from live session, replay, verify state reconstruction
- Demo: replay recorded session and show state diff