Document first-report ordering limitation (Refs #144)

docs/guides/beta-test-plans.md

@@ -214,9 +214,18 @@ key starts a new game before the previous keyed game's `game_end` arrives,
 Matches labels the previous game **End report missing**. A later `game_end`
 completes its own match without changing the newer game. Missing sequence counts
 are diagnostic: they do not invent absent rounds, rosters, or an ending.
-Duplicate and older reports do not advance beta requirements or replace the
+Duplicate sequences, lower-sequence reports, and reports for known older keys do
-current scoreboard. A successful response acknowledges the submitted report;
+not advance beta requirements or replace the current scoreboard. A successful
-it does not mean that report became the current game state.
+response acknowledges the submitted report; it does not mean that report became
+the current game state.
+
+Preserve delivery order across games as well: keep queued retries ahead of
+newer games' reports. An unseen key is always treated as the next game, even if
+its first report was delayed from an older game. `seq` cannot resolve this because
+it orders reports only within a game. A persistent per-server game counter or
+equivalent ordering metadata would require a protocol extension. See the
+[first-report ordering limitation](leaderboard.md#persistence-and-match-boundaries)
+for its effect on match history and the live scoreboard.
 
 Electric Cherry saves the latest accepted report, including player stats, and
 streams it to connected clients. A new start clears the previous round display;

docs/guides/leaderboard.md

@@ -159,9 +159,21 @@ A `game_start` opens a match; `game_end` completes it. Reporters can send an opt
 A key identifies one game on one server, including when the start report was
 missed. An unseen key opens a new game and labels the previous active keyed game
 **End report missing**. This records missing evidence; it does not establish
-whether the game finished or was interrupted. A late `game_end` can still complete its own match; old keys never
+whether the game finished or was interrupted. A late `game_end` for a previously
+seen key can still complete its own match; reports for known older keys do not
 replace the newer game's live state.
 
+Keys are opaque, and `seq` orders reports only within one game. Electric Cherry
+therefore orders games by their first processed report. If game `new` is already
+reporting when the first report for game `old` arrives, the unseen `old` key
+supersedes `new` and marks it **End report missing**. Later `new` heartbeats update
+its history but cannot restore it as the live game. If `old` arrived as a
+heartbeat, it can remain active even after `new` ends. Reporters should preserve
+delivery order across games, keeping queued retries ahead of newer games' reports.
+Reliably ordering unseen keys would require additional reporter metadata, such
+as a persistent, increasing per-server game counter; the current protocol has no
+such field.
+
 With both fields present, each sequence is counted once, including across app
 restarts. Lower sequences fill missing-report gaps without rolling back newer
 rounds, counters, or rosters. A delayed `game_start` may fill the recorded starting