Swiss-pairing tournament organizer — design discussion (following up on #4612 / #4615)

[rykerwilliams]

Swiss-pairing tournament organizer — design discussion (following up on #4612 / #4615)

Picking this up per @matthewevans's note on #4615 — posting the design discussion here before any new implementation work, rather than jumping straight to a PR.

Starting point

#4612's proposal is the right architecture and I'm not proposing an alternative to it: a TournamentManager living in crates/lobby-broker as a sibling to LobbyManager, sharing its functional-core/imperative-shell pattern, dispatch (Broker::handle), and existing lobby_subscribers broadcast channel so it runs byte-identically on the native server and the Cloudflare Worker. Matches are self-reported by players who start their own table via the existing CreateGameWithSettings/JoinGameWithPassword flow — the broker organizes, it doesn't supervise GameSessions. This is the same shape #4615 implemented; the review on that PR found real bugs in the implementation, not a problem with this direction.

Grounding the rules in the actual Magic Tournament Rules (MTR), not invented convention

Rather than inventing tiebreaker/bye/round-count conventions from memory, I pulled the current official MTR (effective 2026-02-27, PDF, HTML) and verified the exact text. This should be the default ruleset the feature ships with — a tournament tool that gets tiebreakers subtly wrong is worse than not having one.

• Match points (MTR §2.1): 3 for a win, 1 for a draw, 0 for a loss.
• Tiebreaker order (MTR §3.1): match points → opponents' match-win % → game-win % → opponents' game-win %.
• Tiebreaker floors (MTR Appendix C): match-win % = accumulated match points ÷ total possible (3 × rounds played), floored at 0.33 if lower. Game-win % = game points earned ÷ total possible (3 × games played), same 0.33 floor. Opponents' match-win %/game-win % = the average of that stat across the opponents actually faced.
• Byes (MTR Appendix C): a bye scores as a 2–0 match win — 3 match points, 6 game points — and the bye round is excluded (not zero-filled) when averaging that player's own opponents'-percentage stats, since there was no real opponent that round. This resolves the "does a bye count as a match win" open question directly: yes, per MTR, unconditionally — no ExcludeFromStandings variant needed.
• Recommended Swiss round count (MTR Appendix E): an exact player-count → round-count table (9–16 players → 5 rounds, 17–32 → 5, 33–64 → 6, 65–128 → 7, etc. — note this is written for Premier-level events specifically, but it's the best available default for a casual tool too, with organizer override). 4–8 players skip Swiss entirely and run single-elimination per the same table.
• Match result reporting (MTR §2.4): players themselves are responsible for reporting — this matches Add a Swiss-pairing tournament organizer to the lobby broker #4612/feat(lobby): Swiss tournament organizer for lobby broker (#4612) #4615's self-report model and doesn't need to change, only the authority validation around it (see fix chore: update coverage stats and badges #2 below).
• Not MTR-specified: the actual Swiss pairing algorithm (score-group pairing, avoiding rematches, floating an odd player down) has no codified MTR text — §10.4 only says tournaments "follow the Swiss pairing algorithm" without detailing mechanics. That's genuinely implementation-defined (tournament software convention, e.g. WER/EventLink), not something to cite a rule number for.

TOs need override knobs, not hardcoded MTR constants

The MTR is the right default, but it's explicitly not universal practice — casual and format-specific communities commonly run variants. The concrete example that came up: some Old School/93-94-adjacent groups score draws as 0 match points instead of MTR's 1, specifically to discourage intentional draws. This repo is also already moving toward a general custom-format engine (per an internal backlog note reframing formats as presets rather than a fixed list), so tournament scoring policy should follow the same shape: MTR values as the shipped default, exposed as an explicit, TO-configurable ScoringPolicy at tournament-creation time — not a constant baked into TournamentManager. Concretely: ScoringPolicy { win_points: u8, draw_points: u8, loss_points: u8 } (default {3, 1, 0}), threaded through match-point accumulation and the tiebreaker calculations the same way. The tiebreaker order and floor value are less likely to need per-TO overrides than the point values are, but the scoring policy should be a first-class config field either way rather than assumed fixed.

What #4615's review already surfaced (baking these in as day-one design decisions, not follow-up fixes)

1. Tournament/organizer authority must not live on the socket. feat(lobby): Swiss tournament organizer for lobby broker (#4612) #4615 stored organizer authority in ConnState, so closing the tab (which the UI did immediately after creating a tournament) triggered on_disconnect and unregistered the tournament; joined players lost joined_tournaments too, orphaning later report/drop calls. Proposal: mint an explicit organizer token and per-player tokens at creation/join time (mirroring how draft-pod sessions already do reconnect via token, not socket identity), so authority survives a socket bounce. The tournament page keeps its socket open for the page lifetime as an optimization (live updates), not as the source of authority.
2. Winner must be validated against the reported game-win score, not accepted independently — reject ReportMatchResult when winner_player_key doesn't match the player with the higher game-win count.
3. Expiry must track activity, not creation time. Add last_activity_at, bumped on every tournament mutation (join, pairing, report, round advance); the native reaper and any Cloudflare Worker cleanup key off that, not created_at. Restrict staleness reaping to abandoned registration state — an active in-progress round should never be reaped by a fixed timeout.
4. Cloudflare Worker emptiness predicate must include tournaments. is_empty() in broker-wasm currently only checks lobby games; it needs to also check tournaments.is_empty() so a Durable Object holding only tournament state keeps rescheduling its cleanup alarm.
5. Swiss backtracking must treat "one player left" as a valid partial pairing (the float), not a dead end that falls back to greedy rematch-prone pairing. Fix the base case in the backtracking recursion rather than patching around it with a fallback.
6. Frontend must close the tournament socket on unmount, including the cancelled-connect path — not just unsubscribe.
7. New UI chrome goes through t() from day one, per client/src/i18n/README.md — no English-only strings landing then getting retrofitted.

Proposed rollout — split into small, independently reviewable PRs

Per the ask on #4615 to split this up rather than one large cross-stack PR:

1. PR 1 — pure core, no wiring. crates/lobby-broker/src/tournament.rs: TournamentManager, Swiss pairing (score-group + backtracking with the fixed base case, float-down, bye assignment preferring players who haven't had one), standings using the MTR-cited tiebreak order/floors above, ScoringPolicy as a first-class config. Exhaustively unit tested with a deterministic FakeEnv, same style as lobby.rs/broker.rs — including test vectors pinned against the MTR's own worked examples where practical. No protocol changes, no shell wiring — reviewable purely as an algorithm + state machine.
2. PR 2 — protocol + native server. protocol.rs new message variants and view types (TournamentView, TournamentSummary, TournamentStanding, PairingView), protocol version bump, broker.rs gains the tournaments: TournamentManager field and the ConnState organizer/joined-tournament fields (as tokens per the auth fix above, not bare socket-bound state), native server dispatch arms in phase-server/src/main.rs, reaper keyed off last_activity_at.
3. PR 3 — Cloudflare Worker shell. lobby-worker/broker-wasm mutates_lobby match extension, lobby-do.ts ConnAttachment extension, the corrected is_empty() predicate.
4. PR 4 — frontend. adapter/types.ts mirrors, tournamentClient.ts, TournamentLandingPage.tsx/TournamentPage.tsx + presentational components, i18n keys, routes/nav entry, explicit socket-close-on-unmount.

Each PR is reviewable independently and PR 1 in particular has no cross-stack surface at all — it's just an algorithm with tests.

Remaining open questions for maintainer alignment before PR 1

Most of the open questions from the first draft of this post are now resolved directly by the MTR citations above (bye handling, tiebreaker order/floors). What's left:

• Scoring-policy default and override UI: agree MTR's {3,1,0} should be the shipped default with a TO override, per the section above — is a simple three-number config sufficient for v1, or does this want to hook into the custom-format system if/when that lands?
• Round advancement: host/organizer-gated only for v1, or does an auto-advance timer matter enough to build now? (MTR's time-limit content, Appendix B, covers round clocks generally but doesn't mandate a specific online-tool advancement model.)
• Confirming v1 stays lobby-only (no auto-launched GameSession per pairing) as Add a Swiss-pairing tournament organizer to the lobby broker #4612 proposes, with full-mode integration explicitly out of scope as a separate fast-follow.

Happy to start on PR 1 once there's rough agreement here — it's the smallest, lowest-risk piece and doesn't block on the open questions above.

[rykerwilliams]

Wrote up a verification pass against the current repo state for this — full research/design docs (with file:line citations confirming the LobbyManager/Broker pattern, the current protocol version, the Cloudflare Worker is_empty() gap, and #4615's actual review findings against the real diff) are in rykerwilliams#4, a discussion artifact, not meant to merge as-is. One correction worth noting: the lobby_subscribers broadcast channel actually lives in the native shell (phase-server/src/main.rs), not inside lobby-broker itself — the broker core only emits abstract Outbound variants — but the reuse claim otherwise holds.