Document first-report ordering limitation (Refs #144)

2026-10-12 10:28:44 -04:00
parent 785cc4616b
commit 76325b99ad
2 changed files with 25 additions and 4 deletions
@@ -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