Replay integration (#123)

## Description

This PR delivers a full replay + telemetry feature set and hardens
docs/wiki synchronization.

It solves two core gaps:
1. No first-class way to record, serialize, and replay real P2P matches
for deterministic debugging and validation.
2. Wiki mirror generation and SYNC-header validation were easier to
drift or fail with less-actionable diagnostics.

### What changed

- Added replay domain types and serialization:
  - `Replay<I>` and `ReplayMetadata`
- `Replay::to_bytes()`, `Replay::from_bytes()`, `Replay::validate()`,
`Replay::total_frames()`
- Added replay playback session:
  - `ReplaySession<T>` implementing `Session<T>`
  - `ReplaySession::new()` and `ReplaySession::new_with_validation()`
- Validation mode emits `SaveGameState` before `AdvanceFrame` and
compares checksums frame-by-frame
- Added replay recording support to P2P sessions:
  - `SessionBuilder::with_recording(bool)`
- `P2PSession::is_recording()`, `P2PSession::into_replay()`,
`P2PSession::take_replay()`
  - Recording now captures confirmed inputs and recorded checksums
- Added session telemetry API and built-in collector:
  - `SessionTelemetry` trait
- `TelemetryEvent` enum (`Rollback`, `PredictionMiss`,
`NetworkStatsUpdate`, `FrameAdvance`)
  - `CollectingTelemetry`
  - `SessionBuilder::with_telemetry(...)`
- P2P telemetry emission integrated in rollback, prediction miss,
network stats polling, and frame advance paths
- Added sync-layer helper used for telemetry:
  - `players_with_incorrect_predictions(...)`
- Expanded public exports and docs:
  - Re-exports for replay/telemetry in `lib.rs` and prelude
  - New docs: replay and telemetry guides
  - Added MkDocs nav entries and wiki mirror pages/sidebar links
- Hardened docs/wiki synchronization pipeline:
  - Added pre-commit `sync-wiki` hook before wiki consistency checks
  - `sync-wiki.py` now:
    - injects/normalizes reciprocal wiki SYNC headers
    - validates sidebar coverage before writing files
    - normalizes generated markdown EOF/newline format deterministically
- `check-sync-headers.py` now reports case-mismatch hints and
remediation guidance
  - Added/expanded script tests for sync behavior and diagnostics
- Added `.gitignore` entries for local pre-commit/pre-push log artifacts

### Breaking change

- Added `FortressEvent::ReplayDesync { frame, expected_checksum,
actual_checksum }`.
- Because `FortressEvent` is not `#[non_exhaustive]`, downstream
exhaustive `match` statements must add a branch for `ReplayDesync`.

## Type of Change

- [x] 🐛 Bug fix (non-breaking change that fixes an issue)
- [x] ✨ New feature (non-breaking change that adds functionality)
- [x] 💥 Breaking change (fix or feature that would cause existing
functionality to change)
- [x] 📚 Documentation (changes to documentation only)
- [ ] ♻️ Refactor (code change that neither fixes a bug nor adds a
feature)
- [x] 🧪 Test (adding or updating tests)
- [x] 🔧 CI/Build (changes to CI configuration or build process)

## Checklist

### Required

- [ ] I have read the [CONTRIBUTING guide](../docs/contributing.md)
- [ ] I have followed the **zero-panic policy**:
  - No `unwrap()` in production code
  - No `expect()` in production code
  - No `panic!()` or `todo!()`
  - All fallible operations return `Result`
- [x] I have added tests that prove my fix is effective or my feature
works
- [ ] I have run `cargo fmt && cargo clippy --all-targets --features
tokio,json` with no warnings
- [ ] I have run `cargo nextest run` and all tests pass

### If Applicable

- [x] I have updated the documentation accordingly
- [x] I have added an entry to `CHANGELOG.md` for user-facing changes
- [ ] I have updated relevant examples in the `examples/` directory
- [ ] My changes generate no new compiler warnings

## Testing

**Tests added/modified:**

- Added replay model tests in `src/replay.rs` (serialization roundtrip,
validation invariants, metadata/display, recorder behavior)
- Added replay session tests in `src/sessions/replay_session.rs`
(playback flow, completion behavior, validation mode, checksum mismatch
event emission)
- Added event display coverage for `ReplayDesync` in `src/lib.rs`
- Added builder/session tests in `src/sessions/builder.rs` and
`src/sessions/p2p_session.rs` for replay-session creation and recording
API behavior
- Added new script tests in `scripts/tests/test_check_sync_headers.py`
- Expanded `scripts/tests/test_sync_wiki.py` coverage for SYNC header
generation, sidebar coverage validation, idempotent output
normalization, and fail-before-write behavior

**Manual testing performed:**

- Reviewed API docs and migration impact for new replay + telemetry APIs
- Verified docs navigation additions and wiki mirror wiring in this
branch
- Full local command status (`cargo fmt`, `cargo clippy`, `cargo
nextest`) intentionally left unchecked in checklist for final author
confirmation

## Related Issues

- N/A (no issue links provided in branch metadata)

---

<!-- Thank you for contributing to Fortress Rollback! -->

Author: wallstop

.github/workflows/ci-docs.yml

@@ -247,6 +247,19 @@ jobs:
           path: code-fence-output.txt
           retention-days: 7
 
+  # ============================================================================
+  # DOC CLAIMS - Check doc comments for misleading claims
+  # ============================================================================
+  doc-claims:
+    name: Doc Claims Check
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Check doc comment accuracy
+        run: ./scripts/ci/check-doc-claims.sh
+
   link-check:
     name: Link Check
     runs-on: ubuntu-latest

.gitignore

@@ -62,3 +62,8 @@ package.json
 node_modules/
 *.pyc
 *.pyo
+
+pre-commit.txt
+pre-commit.log
+pre-push.txt
+pre-push.log

.llm/context.md

@@ -216,18 +216,23 @@ For protocol tests that poll in loops (`poll_remote_clients()` / protocol `poll(
 
 **Exclude:** internal refactoring, test improvements, doc-only changes, CI/tooling, lint fixes.
 
+**Unreleased code rule:** Never add separate "Fixed" or "Changed" entries for code that has not yet been released. Fixes to unreleased features should be folded into the existing "Added" entry describing that feature. The changelog should describe the final shipped state, not intermediate development history.
+
 ## Mandatory Linting
 
 - **After Rust changes:** `cargo fmt && cargo clippy --all-targets --features tokio,json` (or `cargo c`)
 - **After workflow changes:** `actionlint` (no exceptions)
 - **After doc changes:** `cargo doc --no-deps`
 - **After markdown changes:** `npx markdownlint 'file.md' --config .markdownlint.json --fix`
+- **After shell-script changes:** `bash scripts/ci/check-shell-portability.sh`
 - **After `.llm/` changes:** All `.md` files under `.llm/` must be **300 lines or fewer** (enforced by pre-commit hook `llm-line-limit`)
 - **Link validation:** `./scripts/docs/check-links.sh`
 - **Spell check:** `typos`
 - **Vale (advisory):** `vale docs/` -- checks prose quality, non-blocking in CI
 - **Full pre-commit:** `cargo fmt && cargo clippy --all-targets --features tokio,json && cargo nextest run --no-capture`
 
+Shell regex portability rule: avoid PCRE-style escapes in `grep -E`/`sed -E` (`\b`, `\s`, `\w`, etc.). Use POSIX-safe classes like `[[:space:]]`, `[[:alnum:]_]`, and token boundaries `(^|[^[:alnum:]_])word([^[:alnum:]_]|$)`.
+
 ## Skill Code Examples
 
 Code examples in `.llm/skills/` must follow zero-panic rules with these exceptions:

.llm/skills/ci-cd-tooling/wiki-sync.md

@@ -15,12 +15,12 @@ Fix content in `docs/`, then re-sync.
 
 ## Link Format Rules
 
-| Context | Format | Example |
-|---------|--------|---------|
-| `docs/` files | Lowercase with `.md` | `[Guide](user-guide.md)` |
-| `wiki/` files | PascalCase, no extension | `[Guide](User-Guide)` |
-| `wiki/_Sidebar.md` | PascalCase, no extension | `[User Guide](User-Guide)` |
-| External (non-docs) | Full GitHub URL | `[Code](https://github.com/.../blob/main/src/lib.rs)` |
+| Context             | Format                   | Example                                               |
+| ------------------- | ------------------------ | ----------------------------------------------------- |
+| `docs/` files       | Lowercase with `.md`     | `[Guide](user-guide.md)`                              |
+| `wiki/` files       | PascalCase, no extension | `[Guide](User-Guide)`                                 |
+| `wiki/_Sidebar.md`  | PascalCase, no extension | `[User Guide](User-Guide)`                            |
+| External (non-docs) | Full GitHub URL          | `[Code](https://github.com/.../blob/main/src/lib.rs)` |
 
 Use standard markdown `[Text](Page)` syntax in sidebar -- NOT wiki-link `[[Page|Text]]` syntax (has URL generation bugs).
 
@@ -57,6 +57,14 @@ docs/*.md --> sync-wiki.py
   +-- Add SYNC comment header
   +-- Generate _Sidebar.md
 --> wiki/*.md
+
+Pre-commit enforcement now runs this sequence for docs/wiki changes:
+
+1. `sync-wiki` regenerates `wiki/*.md` from `docs/`
+2. `wiki-consistency` validates links/sidebar/mapping integrity
+3. `check-sync-headers` validates reciprocal `<!-- SYNC: ... -->` headers
+
+This prevents committing stale or manually-edited wiki mirrors.
 ```
 
 ## MkDocs Conversion Patterns
@@ -124,26 +132,37 @@ python3 scripts/docs/validate-wiki-output.py      # Check rendering issues
 3. All wiki pages have sidebar entries
 4. No special characters in wiki-link display text
 
+`sync-wiki.py` also validates that every `WIKI_STRUCTURE` page appears in
+the generated sidebar and fails fast if any mapped page is missing.
+
+`sync-wiki.py` now enforces deterministic writer normalization for generated
+markdown: non-empty outputs end with exactly one LF newline (trailing
+whitespace/newlines are normalized). This prevents churn with
+`end-of-file-fixer` and keeps repeated sync runs idempotent.
+
+Sidebar coverage validation runs before any wiki writes, so an invalid sidebar
+template fails early without leaving partial regenerated output.
+
 ### Common Errors
 
-| Error | Fix |
-|-------|-----|
+| Error                            | Fix                          |
+| -------------------------------- | ---------------------------- |
 | Link points to non-existent page | Add file or fix sidebar link |
-| `docs/file.md` not mapped | Add to `WIKI_STRUCTURE` |
-| Wiki page has no sidebar entry | Add to `generate_sidebar()` |
-| Stale WIKI_STRUCTURE mapping | Remove entry |
+| `docs/file.md` not mapped        | Add to `WIKI_STRUCTURE`      |
+| Wiki page has no sidebar entry   | Add to `generate_sidebar()`  |
+| Stale WIKI_STRUCTURE mapping     | Remove entry                 |
 
 ## Markdown Link Validation
 
 ### Relative Path Resolution
 
 Links resolve from the directory containing the markdown file:
 
-| From | To Root | Example |
-|------|---------|---------|
-| `docs/` | `../` | `[README](../README.md)` |
-| `.github/` | `../` | `[Context](../.llm/context.md)` |
-| `.llm/skills/<category>/` | `../../../` | `[README](../../../README.md)` |
+| From                      | To Root     | Example                         |
+| ------------------------- | ----------- | ------------------------------- |
+| `docs/`                   | `../`       | `[README](../README.md)`        |
+| `.github/`                | `../`       | `[Context](../.llm/context.md)` |
+| `.llm/skills/<category>/` | `../../../` | `[README](../../../README.md)`  |
 
 ### Heading Anchor Generation Rules
 
@@ -153,11 +172,11 @@ Links resolve from the directory containing the markdown file:
 4. ` / ` becomes `--`
 5. `~` removed
 
-| Heading | Anchor |
-|---------|--------|
-| `## Quick Start` | `#quick-start` |
+| Heading                              | Anchor                         |
+| ------------------------------------ | ------------------------------ |
+| `## Quick Start`                     | `#quick-start`                 |
 | `## LAN / Local Network (~20ms RTT)` | `#lan--local-network-20ms-rtt` |
-| `## Web / WASM Integration` | `#web--wasm-integration` |
+| `## Web / WASM Integration`          | `#web--wasm-integration`       |
 
 ### Pipe Escaping in Tables
 

.pre-commit-config.yaml

@@ -102,6 +102,20 @@ repos:
         pass_filenames: false
         files: '\.rs$'
 
+      - id: check-doc-claims
+        name: check doc comment accuracy
+        entry: bash scripts/ci/check-doc-claims.sh
+        language: system
+        pass_filenames: false
+        files: '\.rs$'
+
+      - id: check-derive-bounds
+        name: check derive bounds
+        entry: bash scripts/ci/check-derive-bounds.sh
+        language: system
+        pass_filenames: false
+        files: '\.rs$'
+
       # ══════════════════════════════════════════════════════════════════════
       # Documentation checks
       # ══════════════════════════════════════════════════════════════════════
@@ -134,6 +148,13 @@ repos:
         pass_filenames: false
         files: '\.md$'
 
+      - id: sync-wiki
+        name: sync wiki mirrors
+        entry: python scripts/docs/sync-wiki.py
+        language: python
+        pass_filenames: false
+        files: '^(docs/.*\.md|wiki/.*\.md|scripts/docs/sync-wiki\.py)$'
+
       - id: wiki-consistency
         name: wiki consistency check
         entry: python scripts/docs/check-wiki-consistency.py
@@ -148,6 +169,13 @@ repos:
         files: '^(docs/.*\.md|wiki/.*\.md)$'
         pass_filenames: false
 
+      - id: changelog-unreleased-rule
+        name: changelog unreleased code rule
+        entry: python scripts/hooks/check-changelog-unreleased.py
+        language: python
+        pass_filenames: false
+        files: '^CHANGELOG\.md$'
+
       - id: llm-line-limit
         name: check .llm file line limit (300)
         entry: python scripts/hooks/check-llm-line-limit.py
@@ -189,6 +217,13 @@ repos:
         files: '^scripts/(hooks/|build/|docs/|verification/|ci/)?[a-z][^/]*\.py$'
         pass_filenames: true
 
+      - id: check-shell-portability
+        name: check shell portability
+        entry: bash scripts/ci/check-shell-portability.sh
+        language: system
+        files: '\.sh$'
+        pass_filenames: false
+
       # ══════════════════════════════════════════════════════════════════════
       # CI validation (skip gracefully if tools not installed)
       # ══════════════════════════════════════════════════════════════════════

.typos.toml

@@ -18,7 +18,8 @@ resimulates = "resimulates"
 resimulating = "resimulating"
 
 # Mathematical/algorithmic variable names
-ba = "ba" # b minus a
+ba = "ba"  # b minus a
+ser = "ser"  # Mermaid state diagram alias in docs/replay.md and wiki/Replay.md
 
 # Technical terms
 clonable = "clonable"

CHANGELOG.md

@@ -14,6 +14,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0]
+
+### Changed
+
+- **Breaking:** `FortressEvent::ReplayDesync` — new variant added. Since `FortressEvent` is not `#[non_exhaustive]`, exhaustive matches must now handle this variant.
+- **Breaking:** `InvalidFrameReason::ReplayExhausted` — new variant added. Since `InvalidFrameReason` is not `#[non_exhaustive]`, exhaustive matches must now handle this variant.
+- **Breaking:** `Config::Input` now requires `Eq` in addition to `PartialEq`. Types used as `Config::Input` must derive or implement `Eq`. This ensures reflexive equality, which is a correctness requirement for deterministic rollback — non-reflexive types (e.g., floats with `NaN`) would cause phantom prediction misses and unnecessary rollbacks. All integer and struct-of-integer types already implement `Eq`; add `#[derive(Eq)]` to any custom input types that are missing it.
+
+### Added
+
+- `ReplaySession::new_with_validation()` constructor that enables checksum validation mode, emitting `SaveGameState` requests, comparing checksums against the replay recording, and flushing final-frame validation when `events()` is drained after completion
+- `ReplaySession::is_validating()` accessor to check if checksum validation mode is enabled
+- `SessionBuilder::start_replay_session_with_validation()` builder method for creating a validation-enabled replay session
+- `SessionTelemetry` trait for observing session performance events (rollbacks, prediction misses, frame advances, network stats)
+- `CollectingTelemetry` test helper that accumulates `TelemetryEvent` values for assertions
+- `TelemetryEvent` enum with `Rollback`, `PredictionMiss`, `NetworkStatsUpdate`, and `FrameAdvance` variants
+- `SessionBuilder::with_telemetry()` to attach a telemetry observer to P2P sessions
+- `Replay<I>` type for recorded match data with `to_bytes()` / `from_bytes()` serialization using deterministic bincode codec
+- `ReplayMetadata` type containing library version, player count, total frame count, and skipped frame count
+- `ReplaySession<T>` session type implementing `Session<T>` for deterministic replay playback
+- `SessionBuilder::with_recording(bool)` to enable input recording (including game state checksums) during P2P sessions
+- `SessionBuilder::start_replay_session(replay)` to create a replay playback session
+- `P2PSession::is_recording()` to check if replay recording is active
+- `P2PSession::into_replay()` to extract the recorded `Replay` after a session ends (consumes the session)
+- `P2PSession::take_replay()` to extract the recorded `Replay` without consuming the session (recording stops after extraction)
+- `Replay::validate()` to verify internal consistency of replay data
+- Re-exports `Replay`, `ReplayMetadata`, and `ReplaySession` in prelude
+
 ## [0.7.0]
 
 ### Added

Cargo.lock

@@ -320,6 +320,12 @@ renamed_function_params = "warn"            # Consistent parameter names across
 try_err = "warn"                            # Use ? instead of Err(e)?
 undocumented_unsafe_blocks = "warn"         # Require SAFETY comments on unsafe
 
+# cargo-shear: macroquad and z3 are optional deps behind feature flags
+# (graphical-examples and z3-verification). They cannot be dev-dependencies
+# because dev-deps cannot be feature-gated in Cargo.
+[package.metadata.cargo-shear]
+ignored = ["macroquad", "z3"]
+
 [features]
 sync-send = []
 # Enable runtime invariant checking in release builds (for debugging production issues)
@@ -379,8 +385,6 @@ proptest = "1.11"
 serde_json = "1.0"
 # Benchmarking
 criterion = { version = "0.8", features = ["html_reports"] }
-# Additional testing utilities
-arbitrary = { version = "1.3", features = ["derive"] }
 # Macro utilities for data-driven tests
 pastey = "0.2"
 

Cargo.toml

@@ -25,7 +25,7 @@ use std::hint::black_box;
 use std::net::SocketAddr;
 
 /// Simple test input type for benchmarking
-#[derive(Copy, Clone, PartialEq, Default, Serialize, Deserialize, Debug)]
+#[derive(Copy, Clone, PartialEq, Eq, Default, Serialize, Deserialize, Debug)]
 struct BenchInput {
     buttons: u8,
     stick_x: i8,