Add match replay and JSONL export

docs/research/README.md

@@ -37,6 +37,7 @@ the workflow document for deciding where new documentation belongs.
 ## Engine / Performance
 
 - [Classic game port architecture](classic-port-notes.md) — Describes the standalone Cython classic engine as the stable rules layer for all consumers. (2026-05-08)
+- [Lost Cities match record v1](lost-cities-match-record-v1.md) — Defines the versioned JSONL format for complete hidden-state replay and post-game analysis. (2026-07-12)
 - [Fast engine optimization architecture](fast-engine-next-optimizations.md) — Prioritizes C-level APIs, contiguous allocation, and zero-copy extraction for high-throughput RL. (2026-05-08)
 - [Optimization sequencing](optimization_sequencing.md) — Orders runtime, traversal, model-scale, and inference optimizations to avoid invalidating experiments. (2026-05-07)
 

docs/research/lost-cities-match-record-v1.md

@@ -0,0 +1,42 @@
+# Lost Cities Match Record v1
+
+Last verified: 2026-07-12
+
+`coolrl.lost-cities.match.v1` is the canonical portable record for one complete
+or in-progress classic Lost Cities match. Files use UTF-8 JSON Lines (`.jsonl`)
+so metadata can be inspected without loading the full replay and steps can be
+streamed in order.
+
+## Row 1: metadata
+
+The first row has `type: "metadata"` and `format:
+"coolrl.lost-cities.match.v1"`. It records creation time, classic rules,
+initial seed, human seat, opponent identity, and completion status. Producers
+may add fields; v1 readers must ignore unknown metadata fields.
+
+## Rows 2+: steps
+
+Every remaining row has `type: "step"` and a contiguous zero-based `index`.
+Step 0 is the initial position and has null `actor`, `phase_before`, and
+`action_id`. Later steps contain:
+
+- `actor`: player that took the action (`0` or `1`).
+- `phase_before`: `card` or `draw`.
+- `action_id`: the classic engine unified action ID.
+- `state`: complete `GameState.to_snapshot()` output after the action.
+- `public_hands`: cards known to be in each player's hand because they were
+  drawn from a discard pile. Entries use `{color, value, count}`; wagers have
+  value 0 and numbered cards use their printed value.
+
+Full state snapshots intentionally include hidden hands and deck order. A match
+record is therefore suitable for post-game analysis and deterministic replay,
+but must not be exposed to a player during a live match.
+
+## Compatibility
+
+Readers must reject an unknown `format` value rather than guessing. New
+optional fields may be added within v1. Any incompatible change to action IDs,
+state encoding, or required row semantics requires `v2`.
+
+The reference reader, writer, and validator are in
+`src/coolrl_lost_cities/games/classic/match_record.py`.