Rework leave-game around an explicit player roster in ctx

[devill]

Draft, and deliberately so — this changes public API, so I'd like to agree the shape
before polishing it. It also reworks part of #1258, which only just landed, so I'd
very much like @Rupesh-ark's read on it.

The filtering mechanism doesn't sit well with the existing design

ctx has never held a list of players. It holds numPlayers, and playOrder is
rebuilt from numPlayers at the start of every phase:

// InitTurnOrderState
let playOrder = Array.from({ length: numPlayers }).map((_, i) => i + '');

So a player taken out of playOrder is back at the next phase change. #1258 handles
that with a ctx._removedPlayers tombstone that every consumer subtracts again:

flowchart LR
  N["ctx.numPlayers<br/>frozen at create"] -->|rebuilt every phase| P["ctx.playOrder"]
  R["ctx._removedPlayers"] -.->|subtract| P
  R -.->|subtract| A["SetActivePlayers<br/>4 branches"]
  R -.->|subtract| I["IsPlayerActive"]
  R -.->|deep scrub| H["_prevActivePlayers<br/>_nextActivePlayers"]

Loading

A tombstone is a negative list, so it is only correct while every reader remembers to
subtract it. Nothing in the type system says a new reader of playOrder must.

It also blocks things we might want next

Each of these needs to change who is playing:

• handing a seat over to another player mid-match
• adding a seat during a match, in a game that supports it
• creating a match before you know how many people will join

With a tombstone there is nothing to change — only a list of who has been struck out.

The alternative

The first commit reverts the turn-order half of #1258. The rest replaces it with one
new field, ctx.players — the players in this match, in seat order:

layer	field	changed
who is admitted to the lobby	metadata.players	no
who is in the match	ctx.players	new
who plays this phase	ctx.playOrder	no

playOrder is seeded from the roster instead of from a count, and constrained to it:

// InitTurnOrderState
const players = GetPlayers(ctx);
let playOrder = [...players];
if (order.playOrder !== undefined) {
  playOrder = order.playOrder(context);
}
// invariant: ctx.playOrder is always a subset of ctx.players
playOrder = playOrder
  .map((playerID) => playerID + '')
  .filter((playerID) => players.includes(playerID));

flowchart LR
  N["ctx.numPlayers<br/>seats created"] -->|at setup| PL["ctx.players<br/>who is in the match"]
  PL -->|seeds, every phase| PO["ctx.playOrder<br/>who plays this phase"]
  L["leaveGame"] -->|removes from| PL

Loading

Removing a player is then a removal rather than a filter, and RemovePlayer drops from
65 lines to 30 — the deep scrub of _prevActivePlayers / _nextActivePlayers goes away,
because both are made inert where they are read instead.

GetPlayers() falls back to deriving the roster from numPlayers, so matches persisted
by 0.50.x keep working.

Commits

commit	diff
revert(core) drop the turn-order half of the leave-game feature	+56 −511
refactor(core) give ctx an explicit player list	+78 −11
feat(core) remove a leaving player from the match	+506 −23

The middle commit is pure structure: I diffed its behaviour against main across six
scenarios and the resulting states are identical.

Two things I left alone on purpose

• endTurn({ next }) and the array form of setActivePlayers still set whatever player
  ID you name, including one who has left. Without a tombstone the framework can't tell
  "has left" from "was never in the roster", and boardgame.io tolerates the latter today.
  Documented rather than changed.
• flow.ts EndTurn returns the wrong state in the arg.remove branch, so removing
  the last player silently does nothing. Pre-existing since Add pass event #492 (2018), out of scope here.

Where this goes next

This PR stands on its own — it adds no features and leaveGame ends up behaving exactly
as it does today. What the roster makes possible afterwards is written up separately, so
none of it has to be bought into here: #1327 (seating), #1328 (lobby lifecycle),
#1329 (tidy-up).

pnpm test and pnpm run lint are green — 43 suites, 911 tests, 100% statements and
branches.

[Rupesh-ark]

Yeah, I read though all this.

This is right, we should have an overall list, but we should keep track of the original list of players to compare against with cause the information is lost as who left.

The overall Shape's right, ship the revert.

One blocker: turn-order.ts:396 filters the custom play order against the roster, so a game whose turn.order.playOrder returns non-seat IDs loses all of them. playOrder: () => ['alice','bob'] with numPlayers: 2 gives ["alice","bob"] on base and [] here, empty rotation, unplayable, silent, and it hits games that never call leaveGame.

The filter's reasoning is right, it just can't tell a departure from an ID that was never here. Suggestion: keep _removedPlayers as private bookkeeping next to ctx.players, and filter on !IsPlayerRemoved(ctx, playerID) — the predicate that was there before. The roster stays authoritative; the departed list is only consulted where something wants a finer answer than "who's in the match", so forgetting it costs today's behaviour rather than correctness. It'd settle #1327's waiting list too.

One decision: types.ts:90 says players is required, GetPlayers() says it might not be, we should decide on one.