From 76325b99adefcfe953ead943497fdff074852bdb Mon Sep 17 00:00:00 2001 From: Josh Wright Date: Mon, 12 Oct 2026 10:28:44 -0400 Subject: [PATCH] Document first-report ordering limitation (Refs #144) --- docs/guides/beta-test-plans.md | 15 ++++++++++++--- docs/guides/leaderboard.md | 14 +++++++++++++- 2 files changed, 25 insertions(+), 4 deletions(-) diff --git a/docs/guides/beta-test-plans.md b/docs/guides/beta-test-plans.md index 5f264d8..0099637 100644 --- a/docs/guides/beta-test-plans.md +++ b/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 -current scoreboard. A successful response acknowledges the submitted report; -it does not mean that report became the current game state. +Duplicate sequences, lower-sequence reports, and reports for known older keys do +not advance beta requirements or replace the current scoreboard. A successful +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; diff --git a/docs/guides/leaderboard.md b/docs/guides/leaderboard.md index 3ac1cab..a42fafa 100644 --- a/docs/guides/leaderboard.md +++ b/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