docs: add ReplayLoader port design spec and implementation plan

Spec covers ReplayLoader (0x462DF0, stdcall, ~1800 lines) and
ParseReplayPosition (0x4E3490, stdcall). Plan has 10 tasks:
addresses, ReplayStream, ParseReplayPosition, hook install,
header parsing, scheme parsing, team data, post-parse, log output,
and optional version 1 legacy path.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs/superpowers/plans/2026-03-19-replay-loader.md

@@ -0,0 +1,980 @@
+# ReplayLoader Port Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development
+> (if subagents available) or superpowers:executing-plans to implement this plan.
+> Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Port ReplayLoader (0x462DF0) and ParseReplayPosition (0x4E3490) from
+WA.exe to Rust, enabling .WAgame file parsing in Rust code.
+
+**Architecture:** Hook-and-replace strategy. ReplayLoader is stdcall(2 params),
+~1800 lines. We decompose it into: (1) a ReplayStream cursor abstraction porting
+the 6 usercall stream helpers, (2) ParseReplayPosition as a standalone pure
+function, (3) the main ReplayLoader function replacing incrementally — header
+first, then payload parsing, delegating unimplemented modes to the original via
+trampoline.
+
+**Tech Stack:** Rust (i686-pc-windows-msvc), MinHook, openwa-core types, WA.exe
+FFI bridges for complex sub-functions.
+
+**Spec:** `docs/superpowers/specs/2026-03-19-replay-loader-design.md`
+
+---
+
+## File Structure
+
+| File | Action | Responsibility |
+|------|--------|---------------|
+| `crates/openwa-core/src/engine/replay.rs` | Create | ReplayStream struct, ParseReplayPosition, replay data types |
+| `crates/openwa-core/src/engine/mod.rs` | Modify | Add `pub mod replay` |
+| `crates/openwa-core/src/address.rs` | Modify | Add replay global addresses |
+| `crates/openwa-wormkit/src/replacements/replay.rs` | Create | Hook installation, ReplayLoader replacement |
+| `crates/openwa-wormkit/src/replacements/mod.rs` | Modify | Add `mod replay` + `replay::install()?` |
+
+---
+
+## Task 1: Add Replay Addresses to address.rs
+
+**Files:**
+- Modify: `crates/openwa-core/src/address.rs`
+
+- [ ] **Step 1: Add replay global addresses**
+
+In the `va` module (top-level function addresses section), the addresses
+`REPLAY_LOADER` (0x462DF0) and `PARSE_REPLAY_POSITION` (0x4E3490) already exist.
+Add the remaining replay-related globals and helper function addresses:
+
+```rust
+// In the va module, near the existing REPLAY_LOADER entries:
+
+/// Stream helper: read length-prefixed string. usercall(EDI=ctx) + stdcall(dest, max_len). RET 0x8.
+pub const REPLAY_READ_BYTES: u32 = 0x0046_1340;
+/// Stream helper: read byte with range validation. usercall(EAX=ctx) + stdcall(dest, min, max). RET 0xC.
+pub const REPLAY_READ_BYTE_VALIDATED: u32 = 0x0046_14D0;
+/// Stream helper: read byte with signed range validation. usercall(EAX=ctx) + stdcall(dest, min, max). RET 0xC.
+pub const REPLAY_READ_BYTE_RANGE: u32 = 0x0046_1540;
+/// Stream helper: read u16 with range validation. usercall(EAX=ctx) + stdcall(dest, min, max). RET 0xC.
+pub const REPLAY_READ_U16_VALIDATED: u32 = 0x0046_15B0;
+/// Stream helper: read worm name (0x11 bytes or length-prefixed). usercall(EAX=ctx) + thiscall(this, flag). RET 0x4.
+pub const REPLAY_READ_WORM_NAME: u32 = 0x0046_1620;
+/// Validate team type byte range. fastcall(ECX=type). Plain RET.
+pub const REPLAY_VALIDATE_TEAM_TYPE: u32 = 0x0046_1690;
+/// Post-process team color assignments. stdcall(1 param). RET 0x4.
+pub const REPLAY_PROCESS_TEAM_COLORS: u32 = 0x0046_6460;
+/// Apply scheme default values. No params (uses globals). Plain RET.
+pub const REPLAY_PROCESS_SCHEME_DEFAULTS: u32 = 0x0046_70F0;
+/// Process replay feature flags. No params (uses globals). Plain RET.
+pub const REPLAY_PROCESS_FLAGS: u32 = 0x0046_7280;
+/// Register observer team entry. stdcall(1 param). RET 0x4.
+pub const REPLAY_REGISTER_OBSERVER: u32 = 0x0046_7BC0;
+/// Process alliance/team setup. No params (uses globals). Plain RET.
+pub const REPLAY_PROCESS_ALLIANCE: u32 = 0x0046_8890;
+/// Validate team configuration. stdcall(1 param).
+pub const REPLAY_VALIDATE_TEAM_SETUP: u32 = 0x0046_5E10;
+```
+
+Add replay-related global data addresses:
+
+```rust
+// In a globals section (or near existing DAT_ references):
+
+/// Global game state struct passed to ReplayLoader. Always 0x87D3F8.
+pub const G_REPLAY_STATE: u32 = 0x0087_D3F8;
+/// Team header data buffer (0x5728 bytes), cleared by ReplayLoader.
+pub const G_TEAM_HEADER_DATA: u32 = 0x0087_79E4;
+/// Secondary team/game data buffer (0xD9DC bytes).
+pub const G_TEAM_SECONDARY_DATA: u32 = 0x0087_D438;
+/// XOR'd game ID (payload ^ 0xEF5B5C49).
+pub const G_REPLAY_GAME_ID: u32 = 0x0088_AF50;
+/// Replay sub-format flag.
+pub const G_REPLAY_SUB_FORMAT: u32 = 0x0088_AF54;
+/// Game version ID from replay.
+pub const G_REPLAY_VERSION_ID: u32 = 0x0088_ABB0;
+/// Scheme present flag (1 = has scheme data).
+pub const G_REPLAY_SCHEME_PRESENT: u32 = 0x0088_AE0C;
+/// Scheme defaults buffer (0x6E bytes).
+pub const G_SCHEME_DEFAULTS_BUF: u32 = 0x0088_DC04;
+/// Version/ArtClass counter. ReplayLoader fails if > 0x33.
+pub const G_ARTCLASS_COUNTER: u32 = 0x0088_C790;
+/// Random seed global.
+pub const G_RANDOM_SEED: u32 = 0x0088_D0B4;
+/// Saved random seed.
+pub const G_SAVED_RANDOM_SEED: u32 = 0x0088_ABAC;
+/// Replay filename buffer.
+pub const G_REPLAY_FILENAME: u32 = 0x0088_AF58;
+```
+
+- [ ] **Step 2: Label all replay functions in Ghidra**
+
+Use `batch_rename_function_components` to name all replay-related functions:
+- `FUN_00461340` → `Replay__ReadPrefixedString`
+- `FUN_004614D0` → `Replay__ReadByteValidated`
+- `FUN_00461540` → `Replay__ReadByteRange`
+- `FUN_004615B0` → `Replay__ReadU16Validated`
+- `FUN_00461620` → `Replay__ReadWormName`
+- `FUN_00461690` → `Replay__ValidateTeamType`
+- `FUN_00466460` → `Replay__ProcessTeamColors`
+- `FUN_004670F0` → `Replay__ProcessSchemeDefaults`
+- `FUN_00467280` → `Replay__ProcessReplayFlags`
+- `FUN_00467BC0` → `Replay__RegisterObserver`
+- `FUN_00468890` → `Replay__ProcessAllianceData`
+- `FUN_00465E10` → `Replay__ValidateTeamSetup`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add crates/openwa-core/src/address.rs
+git commit -m "feat: add replay system addresses for stream helpers and globals"
+```
+
+---
+
+## Task 2: Create ReplayStream and Port Stream Helpers
+
+**Files:**
+- Create: `crates/openwa-core/src/engine/replay.rs`
+- Modify: `crates/openwa-core/src/engine/mod.rs`
+
+The 6 stream helper functions all operate on a shared 3-DWORD context:
+`[data_ptr: *const u8, total_size: u32, cursor: u32]`. Port them all as methods
+on a Rust `ReplayStream` struct.
+
+- [ ] **Step 1: Define ReplayStream struct and error type**
+
+```rust
+// crates/openwa-core/src/engine/replay.rs
+
+/// Error codes returned by ReplayLoader.
+#[repr(i32)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ReplayError {
+    FileNotFound = -1,       // 0xFFFFFFFF
+    InvalidFormat = -2,      // 0xFFFFFFFE
+    VersionTooNew = -3,      // 0xFFFFFFFD
+    MallocFailure = -4,      // 0xFFFFFFFC
+    MapLoadFailure = -5,     // 0xFFFFFFFB
+    ArtClassLimit = -6,      // 0xFFFFFFFA
+    RepairWithTeams = -7,    // 0xFFFFFFF9
+    NoScheme = -9,           // 0xFFFFFFF7
+    SchemeSaveFailure = -10, // 0xFFFFFFF6
+}
+
+/// Replay file magic: "WA" in little-endian.
+pub const REPLAY_MAGIC: u16 = 0x4157;
+/// Maximum supported replay version.
+pub const REPLAY_MAX_VERSION: u16 = 0x13;
+/// XOR key for game ID integrity check.
+pub const REPLAY_XOR_KEY: u32 = 0xEF5B_5C49;
+
+/// Cursor over a replay payload byte buffer.
+///
+/// Mirrors the 3-DWORD stream context used by WA's stream helper functions:
+/// `[data_ptr, total_size, cursor_offset]`.
+pub struct ReplayStream<'a> {
+    data: &'a [u8],
+    cursor: usize,
+}
+
+impl<'a> ReplayStream<'a> {
+    pub fn new(data: &'a [u8]) -> Self {
+        Self { data, cursor: 0 }
+    }
+
+    pub fn remaining(&self) -> usize {
+        self.data.len().saturating_sub(self.cursor)
+    }
+
+    pub fn cursor(&self) -> usize {
+        self.cursor
+    }
+
+    /// Advance cursor by `n` bytes, returning the slice. Fails if not enough data.
+    fn advance(&mut self, n: usize) -> Result<&'a [u8], ReplayError> {
+        let end = self.cursor + n;
+        if end > self.data.len() {
+            return Err(ReplayError::InvalidFormat);
+        }
+        let slice = &self.data[self.cursor..end];
+        self.cursor = end;
+        Ok(slice)
+    }
+
+    /// Read a single byte. Port of parts of FUN_004614D0 / FUN_00461540.
+    pub fn read_u8(&mut self) -> Result<u8, ReplayError> {
+        let slice = self.advance(1)?;
+        Ok(slice[0])
+    }
+
+    /// Read a single byte, validating it is in [min, max]. Port of FUN_004614D0.
+    pub fn read_u8_validated(&mut self, min: u8, max: u8) -> Result<u8, ReplayError> {
+        let val = self.read_u8()?;
+        if val < min || val > max {
+            return Err(ReplayError::InvalidFormat);
+        }
+        Ok(val)
+    }
+
+    /// Read a little-endian u16. Part of FUN_004615B0.
+    pub fn read_u16(&mut self) -> Result<u16, ReplayError> {
+        let slice = self.advance(2)?;
+        Ok(u16::from_le_bytes([slice[0], slice[1]]))
+    }
+
+    /// Read a little-endian u16, validating range. Port of FUN_004615B0.
+    pub fn read_u16_validated(&mut self, min: u16, max: u16) -> Result<u16, ReplayError> {
+        let val = self.read_u16()?;
+        if val < min || val > max {
+            return Err(ReplayError::InvalidFormat);
+        }
+        Ok(val)
+    }
+
+    /// Read a little-endian u32.
+    pub fn read_u32(&mut self) -> Result<u32, ReplayError> {
+        let slice = self.advance(4)?;
+        Ok(u32::from_le_bytes([slice[0], slice[1], slice[2], slice[3]]))
+    }
+
+    /// Read a little-endian i32.
+    pub fn read_i32(&mut self) -> Result<i32, ReplayError> {
+        Ok(self.read_u32()? as i32)
+    }
+
+    /// Read `n` bytes into a destination buffer. Fails if not enough data.
+    pub fn read_into(&mut self, dest: &mut [u8]) -> Result<(), ReplayError> {
+        let slice = self.advance(dest.len())?;
+        dest.copy_from_slice(slice);
+        Ok(())
+    }
+
+    /// Read a length-prefixed string into buffer. Port of FUN_00461340.
+    ///
+    /// Reads 1 byte (length), then `length` bytes of string data, null-terminates.
+    /// `max_len` is the destination buffer capacity (excluding null).
+    pub fn read_prefixed_string(&mut self, dest: &mut [u8]) -> Result<usize, ReplayError> {
+        let len = self.read_u8()? as usize;
+        if len > dest.len().saturating_sub(1) {
+            return Err(ReplayError::InvalidFormat);
+        }
+        let slice = self.advance(len)?;
+        dest[..len].copy_from_slice(slice);
+        dest[len] = 0; // null-terminate
+        Ok(len)
+    }
+
+    /// Read a worm name: either 0x11 fixed bytes or length-prefixed. Port of FUN_00461620.
+    pub fn read_worm_name(&mut self, dest: &mut [u8; 0x11], use_fixed: bool) -> Result<(), ReplayError> {
+        if use_fixed {
+            let slice = self.advance(0x11)?;
+            dest.copy_from_slice(slice);
+        } else {
+            dest.fill(0);
+            self.read_prefixed_string(dest)?;
+        }
+        Ok(())
+    }
+
+    /// Skip `n` bytes.
+    pub fn skip(&mut self, n: usize) -> Result<(), ReplayError> {
+        self.advance(n)?;
+        Ok(())
+    }
+}
+
+/// Validate team type byte. Port of FUN_00461690.
+///
+/// Returns true if the team type value is in a valid range:
+/// - Non-negative: 0..12 (0 through 12 exclusive → type < 13)
+/// - Negative: -100 or absolute value < 100
+pub fn validate_team_type(team_type: i8) -> bool {
+    if team_type >= 0 {
+        team_type < 13
+    } else {
+        team_type == -100 || -(team_type as i32) <= 100
+    }
+}
+```
+
+- [ ] **Step 2: Add module declaration**
+
+In `crates/openwa-core/src/engine/mod.rs`, add:
+```rust
+pub mod replay;
+```
+
+And in the re-exports section if desired (or leave access via `engine::replay::`).
+
+- [ ] **Step 3: Write unit tests for ReplayStream**
+
+Add tests at the bottom of `replay.rs`:
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_read_u8() {
+        let data = [0x42, 0xFF];
+        let mut s = ReplayStream::new(&data);
+        assert_eq!(s.read_u8().unwrap(), 0x42);
+        assert_eq!(s.read_u8().unwrap(), 0xFF);
+        assert!(s.read_u8().is_err());
+    }
+
+    #[test]
+    fn test_read_u8_validated() {
+        let data = [5, 0, 20];
+        let mut s = ReplayStream::new(&data);
+        assert_eq!(s.read_u8_validated(0, 10).unwrap(), 5);
+        assert_eq!(s.read_u8_validated(0, 10).unwrap(), 0);
+        assert!(s.read_u8_validated(0, 10).is_err()); // 20 > 10
+    }
+
+    #[test]
+    fn test_read_u16_le() {
+        let data = [0x57, 0x41]; // "WA" = 0x4157
+        let mut s = ReplayStream::new(&data);
+        assert_eq!(s.read_u16().unwrap(), 0x4157);
+    }
+
+    #[test]
+    fn test_read_u32_le() {
+        let data = [0x78, 0x56, 0x34, 0x12];
+        let mut s = ReplayStream::new(&data);
+        assert_eq!(s.read_u32().unwrap(), 0x12345678);
+    }
+
+    #[test]
+    fn test_read_prefixed_string() {
+        let data = [3, b'f', b'o', b'o', 0, b'x']; // len=3, "foo"
+        let mut s = ReplayStream::new(&data);
+        let mut buf = [0u8; 16];
+        let len = s.read_prefixed_string(&mut buf).unwrap();
+        assert_eq!(len, 3);
+        assert_eq!(&buf[..4], b"foo\0");
+        assert_eq!(s.cursor(), 4);
+    }
+
+    #[test]
+    fn test_read_worm_name_fixed() {
+        let mut data = [0u8; 0x11];
+        data[0] = b'W';
+        data[1] = b'o';
+        data[2] = b'r';
+        data[3] = b'm';
+        let mut s = ReplayStream::new(&data);
+        let mut name = [0u8; 0x11];
+        s.read_worm_name(&mut name, true).unwrap();
+        assert_eq!(name[0], b'W');
+        assert_eq!(s.cursor(), 0x11);
+    }
+
+    #[test]
+    fn test_validate_team_type() {
+        assert!(validate_team_type(0));
+        assert!(validate_team_type(12));
+        assert!(!validate_team_type(13));
+        assert!(validate_team_type(-1));
+        assert!(validate_team_type(-99));
+        assert!(validate_team_type(-100));
+        assert!(!validate_team_type(-101));
+    }
+}
+```
+
+- [ ] **Step 4: Run tests**
+
+```bash
+cargo test -p openwa-core -- replay
+```
+
+Expected: all tests pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/openwa-core/src/engine/replay.rs crates/openwa-core/src/engine/mod.rs
+git commit -m "feat: add ReplayStream cursor and stream helper ports"
+```
+
+---
+
+## Task 3: Port ParseReplayPosition
+
+**Files:**
+- Modify: `crates/openwa-core/src/engine/replay.rs`
+
+Port the `ParseReplayPosition` function (0x4E3490) as pure Rust. This converts
+time strings like `"1:30.25"` to frame counts at 50fps.
+
+- [ ] **Step 1: Write failing tests**
+
+Add to the test module in `replay.rs`:
+
+```rust
+#[test]
+fn test_parse_replay_position_seconds() {
+    assert_eq!(parse_replay_position(b"30\0"), 30 * 50);
+}
+
+#[test]
+fn test_parse_replay_position_minutes_seconds() {
+    assert_eq!(parse_replay_position(b"1:30\0"), (60 + 30) * 50);
+}
+
+#[test]
+fn test_parse_replay_position_with_frames() {
+    assert_eq!(parse_replay_position(b"1:30.5\0"), (60 + 30) * 50 + 25);
+}
+
+#[test]
+fn test_parse_replay_position_zero() {
+    assert_eq!(parse_replay_position(b"0\0"), 0);
+}
+
+#[test]
+fn test_parse_replay_position_invalid() {
+    assert_eq!(parse_replay_position(b"abc\0"), -1);
+}
+
+#[test]
+fn test_parse_replay_position_seconds_over_59() {
+    // After a colon, seconds > 59 is invalid
+    assert_eq!(parse_replay_position(b"1:60\0"), -1);
+}
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+```bash
+cargo test -p openwa-core -- parse_replay
+```
+
+Expected: FAIL (function not defined).
+
+- [ ] **Step 3: Implement parse_replay_position**
+
+Add to `replay.rs`:
+
+```rust
+/// Parse a replay position time string to frame count (50fps).
+///
+/// Format: `[MM:]SS[.FF]` where:
+/// - MM = minutes (multiplied by 60)
+/// - SS = seconds (max 59 after a colon)
+/// - FF = fractional (multiplied by 50 for frames, divided by power of 10)
+/// - Maximum 2 colons allowed
+///
+/// Returns frame count, or -1 on parse error.
+/// Port of WA.exe ParseReplayPosition (0x4E3490).
+pub fn parse_replay_position(input: &[u8]) -> i32 {
+    let mut colon_count: i32 = 0;
+    let mut accumulated: i32 = 0;
+    let mut current: i32 = 0;
+    let mut digit_count: i32 = 0;
+    let mut frac_divisor: i32 = 0; // 0 = integer part, >0 = fractional
+    let mut i = 0;
+
+    loop {
+        if i >= input.len() {
+            return -1;
+        }
+        let ch = input[i];
+
+        // Process digit runs
+        while i < input.len() && input[i] >= b'0' && input[i] <= b'9' {
+            let max_digits = if colon_count < 1 { 4 } else { 2 };
+            if digit_count >= max_digits {
+                return -1;
+            }
+            if frac_divisor == 0 {
+                current = current * 10 + (input[i] - b'0') as i32;
+                digit_count += 1;
+            } else {
+                let frac_value = ((input[i] - b'0') as i32 * 50) / frac_divisor;
+                frac_divisor *= 10;
+                accumulated += frac_value;
+            }
+            i += 1;
+        }
+
+        // Check delimiter
+        if i >= input.len() {
+            return -1;
+        }
+        let delim = input[i];
+
+        if delim != b':' && delim != b'.' && delim != 0 {
+            return -1;
+        }
+
+        if frac_divisor == 0 {
+            // Integer part complete
+            if colon_count > 0 && current > 59 {
+                return -1;
+            }
+            accumulated = current + accumulated * 60;
+            current = 0;
+            digit_count = 0;
+
+            if delim == b':' {
+                if colon_count >= 2 {
+                    return -1;
+                }
+                colon_count += 1;
+            } else {
+                // '.' or '\0' — convert seconds to frames
+                accumulated *= 50;
+            }
+        } else {
+            // Fractional part — ':' and '.' are invalid after '.'
+            if delim == b':' || delim == b'.' {
+                return -1;
+            }
+        }
+
+        if delim == 0 {
+            return accumulated;
+        }
+
+        if delim == b'.' {
+            frac_divisor = 10;
+        }
+
+        i += 1;
+    }
+}
+```
+
+**Note:** This must match the original's behavior exactly. The decompilation shows
+the algorithm accumulates digits, multiplies by 60 at each colon, and by 50 at
+the final conversion. Fractional part: each digit contributes `(digit * 50) / 10^position`.
+
+- [ ] **Step 4: Run tests**
+
+```bash
+cargo test -p openwa-core -- parse_replay
+```
+
+Expected: all pass. If any fail, adjust to match the original's exact logic.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/openwa-core/src/engine/replay.rs
+git commit -m "feat: port ParseReplayPosition to Rust"
+```
+
+---
+
+## Task 4: Hook Installation — Passthrough + ParseReplayPosition Replacement
+
+**Files:**
+- Create: `crates/openwa-wormkit/src/replacements/replay.rs`
+- Modify: `crates/openwa-wormkit/src/replacements/mod.rs`
+
+Install hooks for both functions. ReplayLoader starts as a passthrough (call
+original, log params). ParseReplayPosition is fully replaced.
+
+- [ ] **Step 1: Create replay.rs hook file**
+
+```rust
+// crates/openwa-wormkit/src/replacements/replay.rs
+
+use crate::hook;
+use crate::log_line;
+use openwa_core::address::va;
+use openwa_core::engine::replay;
+
+static mut REPLAY_LOADER_ORIG: *const () = core::ptr::null();
+static mut PARSE_POSITION_ORIG: *const () = core::ptr::null();
+
+// ReplayLoader: stdcall(param_1: u32, mode: i32) -> u32. RET 0x8.
+unsafe extern "stdcall" fn hook_replay_loader(param_1: u32, mode: i32) -> u32 {
+    let _ = log_line(&format!(
+        "[Replay] ReplayLoader param_1=0x{param_1:08X} mode={mode}"
+    ));
+    let orig: unsafe extern "stdcall" fn(u32, i32) -> u32 =
+        core::mem::transmute(REPLAY_LOADER_ORIG);
+    let result = orig(param_1, mode);
+    let _ = log_line(&format!(
+        "[Replay] ReplayLoader returned 0x{result:08X}"
+    ));
+    result
+}
+
+// ParseReplayPosition: stdcall(input: *const u8) -> i32. RET 0x4.
+unsafe extern "stdcall" fn hook_parse_replay_position(input: *const u8) -> i32 {
+    // Build a safe slice from the C string
+    let mut len = 0usize;
+    while *input.add(len) != 0 {
+        len += 1;
+        if len > 256 { break; } // safety limit
+    }
+    let slice = core::slice::from_raw_parts(input, len + 1); // include null
+    replay::parse_replay_position(slice)
+}
+
+pub fn install() -> Result<(), String> {
+    unsafe {
+        REPLAY_LOADER_ORIG = hook::install(
+            "ReplayLoader",
+            va::REPLAY_LOADER,
+            hook_replay_loader as *const (),
+        )? as *const ();
+
+        // ParseReplayPosition — full replacement, trampoline stored but unused
+        PARSE_POSITION_ORIG = hook::install(
+            "ParseReplayPosition",
+            va::PARSE_REPLAY_POSITION,
+            hook_parse_replay_position as *const (),
+        )? as *const ();
+    }
+    Ok(())
+}
+```
+
+- [ ] **Step 2: Register in mod.rs**
+
+In `crates/openwa-wormkit/src/replacements/mod.rs`, add:
+- `mod replay;` in the module list
+- `replay::install()?;` in `install_all()`
+
+- [ ] **Step 3: Build**
+
+```bash
+cargo build --release -p openwa-wormkit
+```
+
+Expected: compiles successfully.
+
+- [ ] **Step 4: Run headful replay test**
+
+```bash
+powershell -ExecutionPolicy Bypass -File replay-test.ps1
+```
+
+Expected: game loads replay, plays through. Check `testdata/logs/openwa_latest.log`
+for `[Replay] ReplayLoader` log lines confirming the hook fires and returns 0.
+
+- [ ] **Step 5: Run headless replay test**
+
+```bash
+powershell -ExecutionPolicy Bypass -File replay-test.ps1 -Headless
+```
+
+Expected: PASS (byte-identical output). This confirms ParseReplayPosition's Rust
+port produces the same frame numbers as the original.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add crates/openwa-wormkit/src/replacements/replay.rs crates/openwa-wormkit/src/replacements/mod.rs
+git commit -m "feat: hook ReplayLoader (passthrough) and replace ParseReplayPosition"
+```
+
+---
+
+## Task 5: ReplayLoader Skeleton — Mode Routing + Header Parsing
+
+**Files:**
+- Modify: `crates/openwa-wormkit/src/replacements/replay.rs`
+- Modify: `crates/openwa-core/src/engine/replay.rs`
+
+Replace the passthrough with a mode-routing skeleton. Mode 1 (play) enters Rust;
+other modes delegate to original. Start with header parsing only.
+
+**Resource cleanup:** The original uses SEH try/catch to ensure fclose + free on
+error. Our Rust replacement must use a guard pattern:
+
+```rust
+/// RAII guard for file handle and malloc'd buffer cleanup.
+struct ReplayGuard {
+    file: *mut FILE,
+    payload: *mut u8,
+}
+impl Drop for ReplayGuard {
+    fn drop(&mut self) {
+        unsafe {
+            if !self.payload.is_null() {
+                free(self.payload as *mut core::ffi::c_void);
+            }
+            if !self.file.is_null() {
+                fclose(self.file);
+            }
+        }
+    }
+}
+```
+
+- [ ] **Step 1: Add CRT FFI declarations and ReplayGuard**
+
+Add to `replay.rs` (wormkit crate) or a shared location:
+- `extern "cdecl"` declarations for `fopen`, `fread`, `fclose`, `fseek`,
+  `malloc`, `free`, `memset`, `memcpy`, `SetCurrentDirectoryA`
+- `ReplayGuard` struct with `Drop` impl
+
+- [ ] **Step 2: Implement mode routing + header**
+
+```rust
+unsafe extern "stdcall" fn hook_replay_loader(param_1: u32, mode: i32) -> u32 {
+    // Modes 2, 3, 4: delegate to original
+    if mode != 1 {
+        let orig: unsafe extern "stdcall" fn(u32, i32) -> u32 =
+            core::mem::transmute(REPLAY_LOADER_ORIG);
+        return orig(param_1, mode);
+    }
+
+    // Mode 1 (play): Rust implementation
+    match replay_loader_play(param_1) {
+        Ok(()) => 0,
+        Err(e) => e as u32,
+    }
+}
+```
+
+Header parsing in `replay_loader_play`:
+1. Check `DAT_0088c790 > 0x33` → return ArtClassLimit
+2. Set `param_1+0xDB48 = 1`, `param_1+0xEF60 = 0`
+3. `SetCurrentDirectoryA` to game data dir
+4. `fopen(param_1+0xDB60, "rb")` → create ReplayGuard
+5. Read 4 bytes: validate magic `0x4157`, extract version from upper 16 bits
+6. Validate version ≤ 0x13
+7. Store version at `param_1+0xDB50`, `param_1+0xDB54`, set `param_1+0xDB58 = 0xFFFFFFFF`
+8. Read 4-byte payload size, validate against file size
+9. malloc payload, fread into it → store in ReplayGuard
+
+On any error, `ReplayGuard::drop` handles cleanup automatically.
+
+- [ ] **Step 3: Run headful replay test**
+
+```bash
+powershell -ExecutionPolicy Bypass -File replay-test.ps1
+```
+
+If game crashes, debug calling convention. If it loads but errors, check header
+field offsets.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add crates/openwa-wormkit/src/replacements/replay.rs crates/openwa-core/src/engine/replay.rs
+git commit -m "feat: ReplayLoader mode routing + header parsing in Rust"
+```
+
+---
+
+## Task 6: Version 2+ Payload Parsing — Scheme + Sub-version
+
+**Files:**
+- Modify: `crates/openwa-wormkit/src/replacements/replay.rs`
+- Modify: `crates/openwa-core/src/engine/replay.rs`
+
+Parse the first portion of the version 2+ payload: sub-version flags, game version
+ID, and scheme data. Version 1 (legacy) delegates to original.
+
+- [ ] **Step 1: Parse sub-version flags and format indicators**
+
+After reading the payload into a `ReplayStream`:
+1. Read secondary payload size + data
+2. Parse sub-version flags, set globals (`DAT_0088AF54`, `DAT_0088AF41` etc.)
+3. Read game version ID → `DAT_0088ABB0`, validate < 0x1F8
+4. Read scheme presence flag → `DAT_0088AE0C`
+
+- [ ] **Step 2: Parse scheme data**
+
+If scheme present:
+1. Read `SCHM` magic (4 bytes = `0x4D484353`), validate
+2. Read scheme version byte (1, 2, or 3)
+3. Call scheme reader helper via FFI bridge (`FUN_004613D0`)
+4. For version 3: call `Scheme__ValidateExtendedOptions` via existing bridge
+5. Copy scheme defaults from `SCHEME_V3_DEFAULTS` where needed
+
+- [ ] **Step 3: Run headful + headless tests**
+
+```bash
+powershell -ExecutionPolicy Bypass -File replay-test.ps1
+powershell -ExecutionPolicy Bypass -File replay-test.ps1 -Headless
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add crates/openwa-wormkit/src/replacements/replay.rs crates/openwa-core/src/engine/replay.rs
+git commit -m "feat: ReplayLoader version 2+ scheme parsing"
+```
+
+---
+
+## Task 7: Version 2+ Payload Parsing — Team Data
+
+**Files:**
+- Modify: `crates/openwa-wormkit/src/replacements/replay.rs`
+
+Parse the team data section. This is the largest parsing section: 6 teams ×
+0xD7B stride with per-worm names and weapon data blocks.
+
+- [ ] **Step 1: Observer team loop**
+
+Read observer/spectator player names (up to 0xD entries, stride 0x78) into global
+buffers. Uses `read_prefixed_string` for names.
+
+- [ ] **Step 2: Main team iteration**
+
+For each of 6 team slots (stride 0xD7B at `0x878120`):
+1. Read team flag byte — if zero, skip (empty slot)
+2. Read team type byte, validate via `validate_team_type`
+3. Read 5 sub-fields via stream helpers
+4. Read worm alliance byte
+5. Per-worm names: 8 worms × 0x11 bytes (fixed for version ≥ 10, else prefixed)
+6. Worm count (validate 1-8), color, flag, grave, soundbank bytes
+7. Team name (0x40 bytes), config name (0x40 bytes)
+8. Weapon data: `memcpy` 0x400 + 0x154 + 0x400 + 0x300 bytes into global buffers
+
+Write all data to the same global buffer addresses the original uses.
+
+- [ ] **Step 3: Post-team validation**
+
+1. Validate team count matches header
+2. XOR integrity: `DAT_0088AF50 = payload_dword ^ 0xEF5B5C49`
+3. Call `ProcessTeamColors` (0x466460, stdcall 1 param) via FFI
+4. Call `Scheme__CheckWeaponLimits` via existing bridge
+
+- [ ] **Step 4: Call remaining processing functions**
+
+Bridge calls to:
+- `ProcessSchemeDefaults` (0x4670F0, no params, plain RET)
+- `ProcessReplayFlags` (0x467280, no params, plain RET)
+- `ProcessAllianceData` (0x468890, no params, plain RET)
+- `ValidateTeamSetup` (0x465E10)
+
+- [ ] **Step 5: Run headful + headless tests**
+
+```bash
+powershell -ExecutionPolicy Bypass -File replay-test.ps1
+powershell -ExecutionPolicy Bypass -File replay-test.ps1 -Headless
+```
+
+Headful: game must load and play correctly.
+Headless: validates team/scheme data was written correctly.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add crates/openwa-wormkit/src/replacements/replay.rs
+git commit -m "feat: ReplayLoader team data parsing"
+```
+
+---
+
+## Task 8: Post-Parse + Map Loading (Section 4)
+
+**Files:**
+- Modify: `crates/openwa-wormkit/src/replacements/replay.rs`
+
+- [ ] **Step 1: Port post-parse logic**
+
+1. Write payload to `data\playback.thm` via fopen/fwrite/fclose
+2. Call map loader (`FUN_00490890`) via FFI bridge
+3. Artclass index lookup via table at `0x6ACD38`
+4. Version flag setup for compatibility
+
+- [ ] **Step 2: Run headful + headless tests**
+
+```bash
+powershell -ExecutionPolicy Bypass -File replay-test.ps1
+powershell -ExecutionPolicy Bypass -File replay-test.ps1 -Headless
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add crates/openwa-wormkit/src/replacements/replay.rs
+git commit -m "feat: ReplayLoader post-parse and map loading"
+```
+
+---
+
+## Task 9: Log Output (Section 5)
+
+**Files:**
+- Modify: `crates/openwa-wormkit/src/replacements/replay.rs`
+
+Port the /getlog formatted output (~600 lines). This must match byte-for-byte
+for headless replay testing.
+
+**Strategy:** Use WA's own string resource and formatting functions via FFI.
+Don't reimplement string resource loading or codepage conversion — bridge them.
+
+- [ ] **Step 1: Port version/game info header lines**
+
+1. Date/time via `_gmtime64` (CRT)
+2. Version string lookup from tables at `0x6AB480` / `0x6AB7A4`
+3. Format "Game:" and "Replay:" lines using `fprintf` or WA's format helpers
+4. WA version line ("3.8.1")
+
+- [ ] **Step 2: Port team listing**
+
+1. Per-team line with flag letter (uppercased via codepage)
+2. Team name in quotes, padded for alignment
+3. Player name assignment
+4. CPU teams: difficulty float
+5. Human teams: host/first markers
+6. Observer teams (negative team type)
+
+- [ ] **Step 3: Run headless test after each sub-section**
+
+```bash
+powershell -ExecutionPolicy Bypass -File replay-test.ps1 -Headless
+```
+
+Compare output byte-for-byte. Fix any differences.
+
+- [ ] **Step 4: Run full test suite**
+
+```bash
+powershell -ExecutionPolicy Bypass -File replay-test.ps1
+powershell -ExecutionPolicy Bypass -File replay-test.ps1 -Headless
+```
+
+Both must pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/openwa-wormkit/src/replacements/replay.rs
+git commit -m "feat: ReplayLoader log output formatting"
+```
+
+---
+
+## Task 10: Version 1 Legacy Path (Optional/Deferred)
+
+**Files:**
+- Modify: `crates/openwa-wormkit/src/replacements/replay.rs`
+
+Version 1 replays are from pre-3.5 WA. If encountered, the current implementation
+would need to delegate to the original. This task ports the version 1 path.
+
+**Deferred:** Only implement if a version 1 test replay is available.
+
+- [ ] **Step 1: Find or create a version 1 test replay**
+- [ ] **Step 2: Port version 1 parsing path**
+- [ ] **Step 3: Test with version 1 replay**
+- [ ] **Step 4: Commit**
+
+---
+
+---
+
+## Verification Checklist
+
+After Tasks 1-9:
+- [ ] Headful replay test passes (all validations)
+- [ ] Headless replay test passes (byte-identical output)
+- [ ] `cargo test -p openwa-core -- replay` passes (unit tests)
+- [ ] No regressions in existing tests
+- [ ] ReplayLoader uses Rust path for mode 1 (play)
+- [ ] ParseReplayPosition fully replaced (no trampoline calls)
+- [ ] All replay helper functions named in Ghidra

docs/superpowers/specs/2026-03-19-replay-loader-design.md

@@ -0,0 +1,263 @@
+# ReplayLoader Port Design
+
+## Summary
+
+Port `ReplayLoader` (0x462DF0) and `ParseReplayPosition` (0x4E3490) from WA.exe
+to Rust as hook-and-replace functions. ReplayLoader is a ~1800-line function that
+parses `.WAgame` replay files, validates their format, extracts team/scheme/map
+data, and produces `/getlog` formatted output. ParseReplayPosition is a small
+utility that converts `MM:SS.FF` time strings to frame counts at 50fps.
+
+## Target functions
+
+### ReplayLoader (0x462DF0)
+
+- **Signature:** `undefined4 ReplayLoader(uint param_1, int param_2)`
+- **Convention:** stdcall (`RET 0x8`, callee cleans 2 params). Also has a plain
+  `RET` at 0x465BC4 which is the SEH exception cleanup path.
+- **param_1:** Global game state struct at `0x87D3F8` (NOT DDGame). Always the
+  same global address — callers pass the literal constant `0x87D3F8`. The struct
+  holds replay/team/scheme state; its relationship to DDGame is that DDGame reads
+  from some of the same globals after ReplayLoader populates them.
+- **param_2:** Mode — 1=play, 2=getmap, 3=getscheme, 4=repair
+- **Returns:** 0 on success, negative error codes on failure
+
+Error codes:
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| -1 (0xFFFFFFFF) | File not found / read error |
+| -2 (0xFFFFFFFE) | Invalid format / validation failure |
+| -3 (0xFFFFFFFD) | Version too new / unsupported scheme version |
+| -4 (0xFFFFFFFC) | Malloc failure |
+| -5 (0xFFFFFFFB) | Map load failure |
+| -6 (0xFFFFFFFA) | DAT_0088c790 > 0x33 |
+| -7 (0xFFFFFFF9) | Repair with teams present |
+| -9 (0xFFFFFFF7) | No scheme in file / game type mismatch |
+| -8 (0xFFFFFFF8) | Not used by this function (gap in error codes) |
+| -10 (0xFFFFFFF6) | Scheme save failure |
+
+### ParseReplayPosition (0x4E3490)
+
+- **Signature:** `int ParseReplayPosition(char *param_1)`
+- **Convention:** stdcall (`RET 0x4`, callee cleans 1 param)
+- **Returns:** Frame count (50fps), or -1 on parse error
+- **Format:** `[H:]MM:SS[.FF]` — hours optional, fractional seconds optional
+
+## Function structure
+
+ReplayLoader breaks into 5 logical sections:
+
+### Section 1: Header & file I/O (~100 lines)
+
+1. Guard: `DAT_0088c790 > 0x33` → return -6
+2. Set `param_1+0xDB48 = 1` (replay active flag)
+3. Set `param_1+0xEF60 = 0` (init counter)
+4. `SetCurrentDirectoryA` to game data dir
+5. `fopen(param_1+0xDB60, "rb")` — replay file path
+6. Read 4-byte header: lower 16 bits must be `0x4157` ("WA")
+7. Version = upper 16 bits; must be ≤ 0x13 (19)
+8. Store version at `param_1+0xDB50`, `param_1+0xDB54`; set `param_1+0xDB58 = 0xFFFFFFFF`
+9. Read 4-byte payload size; validate against file size
+10. For modes 3/4: seek past payload. For modes 1/2: malloc + fread payload.
+
+### Section 2: Version 1 legacy path (~200 lines)
+
+When `version == 1`:
+- Read 4-byte team count from file, then 0x5728 bytes of team header into `0x8779E4`
+- Validate team count (1-6) and team type bounds
+- Iterate teams via `FUN_00461690` (team data reader)
+- Copy scheme defaults from `SCHEME_V3_DEFAULTS`
+- Read 0xD5D0-byte game state block via malloc, validate fields
+- Copy ~20 field groups from game state block into `param_1` at various offsets
+  (0x40, 0x44, 0x48C, 0x490, 0xD0FC, 0x4AF8, 0x4AFC, 0x4AFA, 0x8EFC, etc.)
+- Free temp buffer
+
+### Section 3: Version 2+ parsing (~500 lines)
+
+When `version >= 2`:
+1. Read second payload (team data) with size + content
+2. Parse sub-version flags and format indicators
+3. Read game version ID → `DAT_0088ABB0`; validate < 0x1F8
+4. Read scheme presence flag → `DAT_0088AE0C`
+5. If scheme present: read `SCHM` magic + version byte (1/2/3)
+   - Version 1/2: call `FUN_004613D0` (scheme reader), maybe set defaults
+   - Version 3: validate extended options via `Scheme__ValidateExtendedOptions`
+6. Read map seed byte, random state
+7. Read observer player names (up to 0xD teams, stride 0x78)
+8. Team iteration (up to 6 teams, stride 0xD7B at `0x878120`):
+   - Team flag byte, team type, alliance
+   - 5 sub-field reads via `FUN_00461540`
+   - Worm alliance byte
+   - Per-worm names: 8 worms × 0x11 bytes (or auto-generated for old versions)
+   - Worm count (validate 1-8), color, flag, grave, soundbank bytes
+   - Team name (0x40), team config name (0x40)
+   - Weapon data: 0x400 + 0x154 + 0x400 + 0x300 bytes
+9. Validate team count matches expected
+10. XOR integrity: `DAT_0088AF50 = payload_dword ^ 0xEF5B5C49`
+
+### Section 4: Post-parse & map load (~200 lines)
+
+1. If mode 1 (play): `Scheme__CheckWeaponLimits` validation
+2. If mode 3 (getscheme): version compatibility fixups, `Scheme__SaveFile`
+3. If mode 4 (repair): artclass name writing to replay file
+4. Map loading: read `playback.thm`, call map loader (`FUN_00490890`)
+5. Artclass index → terrain descriptor lookup via table at `0x6ACD38`
+6. Close file
+
+### Section 5: Log output (~600 lines)
+
+Generates `/getlog` formatted output to `DAT_0088C370` (log file handle):
+1. Date/time header via `_gmtime64`
+2. Version string lookup (negative IDs → hardcoded strings, positive → table at
+   `0x6AB480` or `0x6AB7A4` for BoomRacing mode)
+3. Format line: `"Game: <version> + <mods>..."` and `"Replay: <format>..."`
+4. Current WA version line: `"3.8.1"`
+5. Artclass line (if applicable)
+6. Per-team listing with alignment padding:
+   - Team flag letter (uppercased via codepage)
+   - Team name with quotes and padding
+   - Player name assignment
+   - CPU teams: difficulty level float
+   - Human teams: host/first markers
+7. Observer teams (negative team type)
+8. Final newline + flush
+
+**Critical:** This output must match byte-for-byte for headless replay testing.
+
+## Helper functions
+
+Several internal helpers are called repeatedly. These need bridges or ports:
+
+| Address | Name | Purpose | Approach | Convention |
+|---------|------|---------|----------|------------|
+| `0x461340` | ReadBytes | Read N bytes from stream cursor into buffer | Port | Verify during impl |
+| `0x4614D0` | ReadBytesValidated | Read + validate bounds | Port | Verify during impl |
+| `0x4615B0` | ReadU32Validated | Read u32 from stream | Port | Verify during impl |
+| `0x461540` | ReadByteRange | Read byte with signed range validation | Port | Verify during impl |
+| `0x461620` | ReadTeamWormAlliance | Read worm alliance data | Port | Verify during impl |
+| `0x461690` | ReadTeamData_V1 | Read team data (version 1 format) | Port | Verify during impl |
+| `0x466460` | ProcessTeamColors | Post-process team color assignments | Bridge | Verify (check RET) |
+| `0x4670F0` | ProcessSchemeDefaults | Apply scheme default values | Bridge | Verify (check RET) |
+| `0x467280` | ProcessReplayFlags | Process replay feature flags | Bridge | Verify (check RET) |
+| `0x467BC0` | RegisterObserverTeam | Register observer team entry | Bridge | Verify (check RET) |
+| `0x468890` | ProcessAllianceData | Process alliance/team setup | Bridge | Verify (check RET) |
+| `0x465E10` | ValidateTeamSetup | Validate team configuration | Bridge | Verify (check RET) |
+| `0x593180` | LoadStringResource | Load MFC string resource by ID | Bridge | Verify (check RET) |
+| `0x5978A0` | FormatString | sprintf-like string formatter | Bridge | Verify (check RET) |
+| `0x5978F0` | FormatString2 | Another format variant | Bridge | Verify (check RET) |
+
+**Note:** All helper function calling conventions must be verified via `RET imm16`
+disassembly before implementation. Wrong conventions cause stack corruption.
+
+**Policy:** Small functions (especially usercall) should be ported to Rust rather
+than bridged. Bridging usercall functions requires naked asm trampolines which add
+complexity and risk. Only bridge functions that are large or have many dependencies.
+
+## Global buffers written
+
+| Address | Size | Purpose |
+|---------|------|---------|
+| `0x87D3F8` | param_1 base | Game state struct (team/scheme/weapon data at various offsets) |
+| `0x8779E4` | 0x5728 | Team header data |
+| `0x87D438` | 0xD9DC | Secondary team/game data |
+| `0x88AF50` | 4 | XOR'd game ID |
+| `0x88AF54` | 4 | Replay sub-format flag |
+| `0x88ABB0` | 4 | Game version ID |
+| `0x88AE0C` | 4 | Scheme present flag |
+| `0x88DC04` | 0x6E | Scheme defaults buffer |
+| `0x88C790` | 4 | Version/ArtClass counter |
+| `0x88D0B4` | 4 | Random seed |
+| `0x88ABAC` | 4 | Saved random seed |
+
+## Implementation plan
+
+### Phase 0: Passthrough hook + ParseReplayPosition
+
+**Goal:** Validate calling convention, port the trivial function.
+
+1. Add `va::REPLAY_LOADER` and `va::PARSE_REPLAY_POSITION` to `address.rs`
+2. Add all replay-related global addresses to `address.rs`
+3. Create `replacements/replay.rs` with passthrough hook for ReplayLoader
+4. Port `ParseReplayPosition` as full Rust replacement
+5. Register in `replacements/mod.rs`
+6. Test: headful + headless replay
+
+### Phase 1: Header parsing + early returns
+
+**Goal:** Replace the header validation and mode routing in Rust.
+
+1. Port Section 1 (header & file I/O) to Rust
+2. For modes 2 (getmap) and 4 (repair): delegate to original via trampoline
+3. For mode 3 (getscheme): delegate to original initially
+4. For mode 1 (play): continue to Rust Section 2/3
+5. Test: headful replay with mode 1
+
+### Phase 2: Payload parsing (version 2+)
+
+**Goal:** Replace the core team/scheme data parsing.
+
+Focus on version 2+ path (version 1 is legacy, unlikely to be encountered):
+1. Port stream cursor helpers (ReadBytes, ReadU32, etc.) as Rust utilities
+2. Port the team iteration loop (6 teams × 0xD7B stride)
+3. Port scheme data reading (SCHM magic validation + delegation to existing bridges)
+4. Port weapon data block copies
+5. Bridge remaining sub-functions (ProcessTeamColors, ProcessSchemeDefaults, etc.)
+6. Test: headless determinism — game must play identically
+
+### Phase 3: Log output
+
+**Goal:** Reproduce /getlog formatted output byte-for-byte.
+
+This is the highest-risk phase. The output includes:
+- Codepage-aware character conversion
+- MFC string resources (localized strings)
+- Precise column alignment with padding
+- Version string table lookups
+- Date formatting via `_gmtime64`
+
+Approach:
+1. Start with a passthrough to the original log section
+2. Port incrementally, comparing output byte-for-byte via headless tests
+3. Use WA's own string resource functions via FFI bridges
+4. Test: headless diff must show zero differences
+
+## Verification
+
+| Phase | Test | Pass criteria |
+|-------|------|---------------|
+| 0 | Headful + headless replay | All existing validations pass, headless log matches |
+| 1 | Headful replay | Game loads and plays replay correctly |
+| 2 | Headless replay | Output log byte-identical to expected |
+| 3 | Headless replay | Output log byte-identical to expected |
+
+## Risks
+
+1. **Calling convention**: Confirmed stdcall (`RET 0x8`). The plain `RET` at
+   0x465BC4 is the SEH exception cleanup path, not the normal return.
+
+2. **C++ exception handling**: The version 2+ path uses `__CxxThrowException_8`
+   with SEH (`FS:[0]` exception chain) for validation errors. The version 1 path
+   uses direct returns. The SEH handler performs cleanup (freeing malloc'd buffers,
+   closing file handles) before returning the error code. The Rust replacement must
+   replicate this cleanup on every error path. Use a cleanup guard pattern (e.g., a
+   struct with `Drop` impl, or explicit cleanup before each early return) to ensure
+   no resource leaks.
+
+3. **Log output fidelity**: The /getlog output must match byte-for-byte. Codepage
+   conversion, string resources, and column alignment must be exact. This is the
+   hardest part and may require falling back to WA's own formatting functions.
+
+4. **Version 1 format**: Rarely encountered (pre-3.5 replays). Could be left as
+   a bridge to original initially, ported later if needed.
+
+5. **Helper function dependencies**: ~15 helper functions called. Trivial stream
+   helpers should be ported; complex ones (string resources, scheme processing)
+   should be bridged via FFI. All conventions must be verified before use.
+
+6. **Stdcall trampoline delegation**: When delegating to the original function for
+   unimplemented modes, the hook is `extern "stdcall"` and the MinHook trampoline
+   preserves the original stdcall convention. The Rust hook should call the
+   trampoline as a regular function pointer (the trampoline handles its own stack
+   cleanup internally — MinHook trampolines are designed for this). This is the
+   same pattern used by existing stdcall hooks in `game_state_hooks.rs`.