station-master/docs/architecture/multiplayer.md

Multiplayer — design and build plan

How Station Master becomes a multiplayer game with an authoritative server, as a layer added on top of what exists. Solitaire keeps working exactly as it does today: opened from a static host, played entirely in the browser, no server involved at any point.

This is a plan, not an implementation. Written against the engine as built (v0.3.1). It reconciles overview.md, protocol.md, lobby-and-sessions.md and deployment.md — all written before the engine existed — with what was actually built, and with the decisions reviewed and settled in §11.

---

1. The constraint that shapes everything

Solitaire still plays the same. No server needed.

That decides the architecture:

• The engine stays pure and browser-runnable. No server-only dependency enters src/engine/.
• The client runs in two modes without forking: authoritative-local (solitaire, today's behaviour) and view-only-remote (multiplayer).
• The static deploy keeps working. A server is an additional way to run the game.

The existing architecture anticipated nearly all of this and the engine was built to it. Most of what follows is assembly.

---

2. What holds, and what moved

overview.md's core claims survived contact with the implementation: server authority, a pure deterministic engine, two entry points (applyIntent / pump), state = fold(events), events that render standalone, per-player redacted views.

Three things moved:

The save format is already the wire format. A game is { seed, history: Intent[] } and fromSave reconstructs it exactly. That is what makes persistence nearly free (§7).

protocol.md's message vocabulary was out of date; fixed in Phase 0. It had been written from the rules before the engine existed, and the real Intent union diverged — different names (switch.move, not Switch.Move), different shapes (dropCars grew fromNose; card.play grew variant and node), and intents that did not exist then (switch.sortConsist, newTrain.secondSection, maneuver.*, redFlag.*), plus 40-odd rejection codes against a listed 20. The real types are the protocol, so protocol.md now points at intents.ts and events.ts and keeps only what the types cannot say.

The client already renders from a projection. snapshot() produces a Frame, actionMenu() a Menu, and the renderers consume only those. This is why the multiplayer client is cheap.

---

3. Measurements this plan rests on

Taken from 8 four-player bot games and 12 solitaire games, so the sizing is not guesswork.

	value
Intents per game (4 players)	~355, over ~16 Stages
Intents per player per game	~89
Intents per Stage	22 — about 5.5 yours, 16.7 watched
Phase split	Local Ops 78%, Load/Unload 19%, New Train 3%
A turn: switch / draw / freight agent	5.8 / 4.3 / 2.0 intents
Frame	9.3 KB mean; 2.9 KB with the board delta'd
Menu	2.2 KB mean, 9.8 KB max
Events per intent	3.3, ~160 B
Push rate	~0.4 per second across a whole game

Two consequences worth stating plainly:

Latency is not the problem. Watching does not block — pushes arrive asynchronously. The only latency a player feels is on their own ~89 actions: 1.7 seconds across an entire game on a LAN. Nothing here is a performance decision.

Idle time is the problem. With four players you watch ~17 of 22 intents per Stage. That is a turn-order property of the rules, not of the implementation — see §11 D19 for what is being kept open about it.

Open, and not a plan decision: a 4-player competitive game ends after ~16 Stages of a possible 60, well before the 5-day limit. Most likely the collision or revenue floor (§3.4) firing early. Worth understanding before building a lobby around game length — it may be a balance bug rather than intent.

---

4. The structural idea: a Session boundary

Today main.ts calls submit(game, intent), which applies in-process and re-renders. Introduce one interface between the UI and the game:

Session
  view()            -> Frame          what to draw
  menu()            -> Menu           what may be done
  submit(intent)    -> Promise<ok>    propose an action
  subscribe(cb)     -> unsubscribe    "something changed, re-render"
  capabilities      -> { undo, saveLocal, newGame }

• LocalSession wraps today's Game: applies through the engine, pumps advance, keeps history, supports undo and localStorage. This is solitaire, unchanged.
• RemoteSession holds no authoritative state. Posts intents, receives Frame and Menu, re-renders on push. Undo and local save are absent from capabilities, so the UI hides those controls rather than failing when pressed.

The client cannot keep authoritative state in remote mode even if it wanted to: it has neither the deck order nor the other players' hands.

---

5. What the client must stop doing

main.ts reaches into game.state in 11 places. Five new Frame fields remove all of them:

Reads today	Fix
clock.day, clock.stage, clock.phase	already on Frame
turn.option	add — and under §6 it becomes your turn, not the turn
status, outcome	add
players (names and revenues of every seat)	add — the scoreboard is public
decks.hands.get(actor).length	add as handCount, plus per-seat counts

Everything else it draws already comes from Frame/Menu.

Solitaire-only, gated by capabilities: undo (other players have seen the result), localStorage save/restore, new-game-by-seed-in-URL.

---

6. Per-player turn state

s.turn is a single TurnState — one option, one movesRemaining, one freightWorked — read in 50 places, with a phase driver that walks players one at a time calling freshTurn() as it goes.

Phase 0 makes it per-player: turns: Map<PlayerIndex, TurnState>, with a turn created for every player at phase entry. This is deliberately behaviour-neutral — the cursor still advances one player at a time, so play is identical and every existing test still describes the same game.

It is done now because the engine is least encumbered now, and because the alternative later means the same work plus reworking a client built around "wait your turn". There is no data migration either way: we persist intents, not state.

What it buys later. There is exactly one NOT_YOUR_TURN gate in the engine (apply.ts:463, delegating to isActor). Once turn state is per-player, allowing genuinely local work to happen off-cursor is a change to that one function:

isActor(s, player, intent)
  local intent   -> that player's own turn isn't done
  shared intent  -> player is at the shared cursor

An intent is local iff it touches only the acting player's Office Area and does not advance the shared RNG (three sites: the reshuffle, the D12 that schedules a train, and setup).

Local	Shared
switch.move, dropCars, sortConsist	draw.fromHomeOffice, draw.fromDepartment
card.play — track, facility, office, modifier, enhancement	card.discard (buries a shared pile)
localOps.choose, switch.end, draw.end	card.play — train cards, which roll the D12
	freightAgent.*, and the yards generally

That flip is not part of this plan. See D19.

---

7. Redaction — the trust boundary

protocol.md §4's table governs, and Frame was designed for it: Frame.hand is the viewer's own, Frame.deck is a count, and the seed is not on it.

The redaction surface is four fields, not sixty event types. An earlier draft of this document claimed the latter and it was wrong — it biased the design. The genuinely secret things are:

Secret	Why
seed, rngState	leak every future shuffle and roll
decks.homeOffice — contents and order	§12.1; the count is public, the pile's height is visible
decks.hands — other players'	owner only; counts public
cards (the id→kind map)	the dictionary that turns any leaked id into a known card

Everything else is public by the rules: the board, the Division, trays and consists, the timetable, the yards, the salvage pile, the face-up Departments, revenues, held Red Flags, the clock and whose turn it is. trainScheduled is public — trainNumber, roll and slot all belong on screen; only its rngState field must be stripped.

So redaction reduces to: call snapshot(s, seat) and never send GameState. Because Frame resolves card names and descriptions server-side, the client never needs the cards dictionary at all.

This must be enforced, not assumed. Phase 2's redaction test is the single most important test in the plan: serialize a seat's payload and assert it contains no other seat's card ids, no deck array, and no rng state.

---

8. Server shape

One process, one port, same origin. Three layers:

  transport      HTTP: lobby, intents, static assets.  SSE: the per-seat stream.
       |
  game session   one per active game: owns state, serializes intents, pumps advance,
       |         computes per-seat Frame+Menu, appends to the log
       |
  rules engine   unchanged, imported as-is from src/engine/

The session host is thin, because the engine does the hard part:

on intent(seat, intent, seq):
    if seq already applied: ignore                       // idempotent resend
    result = applyIntent(state, seat, intent)
    if not result.ok: reply Rejected(result.code)
    append intent to the log
    pump(state)                                          // drain the automatic phases
    for each connected seat:
        push { frameΔ: delta(snapshot(state, seat)), menu: seat may act ? menuFor(seat) : null, lines }

pump after every intent is what today's drain() does, and it is why the Mainline Phase needs no special handling: pump stops, and the next push simply carries a Menu containing mainline.clearance for whoever must rule.

Bots run server-side using the existing developerBot, for seats chosen at lobby time only.

---

9. Transport, and multiple addresses

SSE for push, HTTP POST for intents.

POST /api/lobby/create, /api/lobby/join      lobby
POST /api/intent          { gameId, seq, intent }
GET  /api/stream          EventSource — per-seat frames, with Last-Event-ID resume
GET  /                    the client

Chosen over WebSocket because this game is idle most of the time — turn-based with human think-time means a connection sits silent for minutes, exactly when proxies reap sockets. SSE's reconnection and Last-Event-ID resume are handled by the browser, and it needs no Upgrade support from anything in the path. WebSocket is supported on StartOS (recipe-multi-interface.md; cln-startos ships one) and remains a contained swap behind the Session interface if bidirectionality is ever wanted. Two channels means intents carry a seq, which the design already required for idempotent resend.

Players will reach one server at different addresses — a LAN IP:port and a clearnet subdomain, in the same game. That works because the server serves the client from the same origin, so each browser is same-origin with itself and no CORS is involved at any point. One rule makes it hold:

The client derives every endpoint from location. Never from configuration, never baked in.

Two consequences:

• localStorage is per-origin, so a session token exists only at the address it was created at. A player rejoins at the address they joined from. This is a stated constraint, not a bug to fix.
• The two paths have different reliability characteristics — only the clearnet player traverses TLS termination and ingress. SSE's automatic recovery is what makes that difference not matter.

---

10. Identity, access and persistence

Access: a server-wide join secret, set by environment variable and passed out of band by whoever runs the server. Anyone holding it may create a game, and may join any created game that has not started. No accounts, no user database. (Revisit — see TODO.md.)

Identity: a session token scoped to one game, exactly as lobby-and-sessions.md already describes. Joining issues it; presenting it is the rejoin, because it already names the game and the seat:

Session   token, gameId, seat, displayName

The join secret is separate and server-wide — typed once and kept per-origin for convenience. It gates entry; the token identifies a seat.

One game at a time per person is the expected usage, and is deliberately not enforced. Enforcing it would mean a server-scoped token carrying an activeGame, and then answering what clears it — a finished game, a player who leaves, a game that never ends — which is real state to get wrong for no benefit. Nothing in the design needs a person to be in only one game, so nothing checks. A browser that ends up holding two tokens simply has two games.

Persistence: { engineVersion, seed, config, history: Intent[] }, append-only per game, plus a small index. Rebuilding is fromSave, already implemented and exercised by every published replay. No state snapshot — see D6.

Games do not survive a rules change, by design. A saved intent legal under old rules is rejected under new ones; that happened four times in one release. So every game is stamped with its engine version, and on load a mismatch is refused with an explicit message rather than silently truncated. The upgrade path is: stop new games on the old version, let running ones drain.

Retention: finished games keep everything, because replay reveals everything (D20) and the log is all it needs.

---

11. Decisions — reviewed and settled

#	Decision	Rationale
D1	SSE + HTTP POST	The game is idle for minutes at a time and players arrive by different paths; browser-native reconnect and resume, no Upgrade dependency. Swap is contained behind Session.
D2/D3	Push Frame + Menu, delta'd. No raw event stream.	Latency is not the deciding factor (1.7 s per game on a LAN), so decide on correctness: one reducer, one redaction chokepoint, no card dictionary on the client. 2.9 KB per push with the board omitted when unchanged — reusing replay.ts's packing, already tested for losslessness.
D4	One client bundle, mode switch	The engine ships either way; in remote mode it is simply not used for authority.
D5	Persist intents, not events	Smaller, already the save format, already proven by fromSave.
D6	No state snapshot	A second format to keep correct, and D7 removes the need.
D7	Stamp the engine version; refuse to resume a mismatch	Rules changes invalidate stored intents. Drain before upgrading.
D8	Bots fill empty seats at lobby time only	Makes short-handed games and one-person testing possible. Never automatic on disconnect — see the two TODO.md items.
D9	Separate seat from identity, now	Employee Rotation needs a player's score to follow them while their seat changes. The single hardest thing here to retrofit, and the codebase is smallest today.
D10	No hotseat in v1	Nearly free once seats exist, but a different UX. Additive later.
D11	Server accepts 1-seat games, but solitaire stays the static build	Falls out of seats generalising, and is genuinely useful for testing and validation. Not a featured path — playing alone gains nothing from a round trip.
D12	No spectators in v1	A view with no private section and no intent rights. Additive later.
D13	No accounts	Display name plus a per-game session token, as lobby-and-sessions.md describes. One game at a time per person is the expected usage but is not enforced — doing so would add cross-game state to get wrong for no benefit.
D14	Server-wide join secret, passed out of band	The server may be clearnet-reachable. Cheapest thing that stops it being someone else's game server. Revisit.
D15	Build to deployment.md's five portability rules; package as an .s9pk	This is a StartOS packaging workspace and the toolchain is on disk.
D16	The server serves the client	Required for same-origin, which is what makes multiple access addresses work without CORS.
D17	Undo is solitaire-only	Other players have seen the result.
D18	Player cap 6	Per lobby-and-sessions.md §2.
D19	Per-player turn state now; parallel turns deferred	The model change is behaviour-neutral and cheap today. Whether local work should run off-cursor depends on how often humans choose to switch — 13% for the bot, and the benefit ranges from ~8 minutes to ~27 off an hour-long game between 13% and 50%. Measure with real players, then flip one function.
D20	Replay reveals everything once the game ends	Most useful for learning and for arguing about it afterwards; costs nothing extra to retain.

Still open, and deliberately so: whether local turns should run in parallel (D19, needs human switching data); whether the join secret is enough (D14); and the ~16-Stage game length in §3, which is a balance question rather than an architecture one.

---

12. Build plan

Sizes use components.md's scale. Each phase ends somewhere demonstrable.

Phase 0 — Engine and client preparation · M — done, v0.4.0

Safe to do now, and all of it improves the code whether or not multiplayer ships. Larger than a typical "phase 0" because two structural changes are cheapest here.

1. Separate seat from identity (D9). Player carries id, name and revenue; the seat carries the Office. Touches setup, areaOf, scoring, seating, the Division build and most tests.
2. Per-player turn state (D19). turns: Map<PlayerIndex, TurnState>, one per player at phase entry, turnOf(s, player) at 50 sites. Behaviour-neutral — the cursor still walks one player at a time, and every existing test must still pass unchanged.
3. Add option, status, outcome, players[], handCount to Frame.
4. Remove all 11 game.state reads from main.ts; add a test that it never regains one.
5. Rewrite protocol.md to reference intents.ts and events.ts rather than restate them.

Done when: solitaire plays identically, the client renders from Frame + Menu alone, and the engine has per-player turn state that nothing yet exploits. All five shipped in v0.4.0. Item 1 found a real bug on the way — awardDeparture was indexing s.players with a seat.

Phase 1 — The Session boundary · S — done, v0.4.0

6. Define Session; implement LocalSession around today's Game.
7. Move main.ts onto it, with capabilities gating undo, save and new-game.

Done when: solitaire plays identically through the new interface. Maximum "nothing appears to have happened"; the regression suite is the proof. Shipped in v0.4.0. The proof is test/session.test.ts, which plays seed 77 to a finish through both routes and asserts the boards and histories match, plus a source check that main.ts never regains a GameState read or a value import from game.ts.

Phase 2 — Server core, one game, no lobby · M

8. Process bootstrap: env-configured bind address, port, data directory, join secret; static serving.
9. Game session host — the loop in §8.
10. Per-seat Frame + Menu, with the board delta reusing replay.ts's packing.
11. The redaction test (§7). Fail loudly.
12. SSE stream and POST /api/intent, with seq and Last-Event-ID.
13. RemoteSession in the client.

Done when: two browsers — one on a LAN IP, one on a hostname — play a 2-player game to a finish.

Phase 3 — Persistence and resumption · S

14. Append-only {engineVersion, seed, config, history} per game; index.
15. Load on start; rebuild via fromSave; refuse a version mismatch explicitly.

Done when: the server restarts mid-game and both clients carry on.

Phase 4 — Lobby, sessions, reconnection · M

16. Join secret; per-game session token; display name.
17. Create/join by game code; bot seats; seating UI showing the west-to-east chain; config locked at start.
18. Disconnect keeps the seat and announces it; reconnect resumes from Last-Event-ID.
19. Optional turn timer, off by default, denying clearance on expiry.

Done when: four people join from four browsers at two different addresses, one closes the tab and rejoins where they left off.

Phase 5 — Multiplayer content · M

20. The 10 Action and 12 Space-use cards; flip opponentCardsInDeck in setup.ts.
21. Facing Point Locks, Water Column and Overpass stop being dormant — already wired.

Done when: an opponent-directed card resolves against another player and the Enhancement that answers it fires.

Phase 6 — Package for StartOS · S

22. .s9pk per the workspace guide: interface, health check, backup of the data directory.

Done when: it installs on a StartOS box and players on two different addresses play a game.

Shape of it: Phases 0–1 are low-risk refactoring that stands on its own merits. Phases 2–4 are the real system. Phase 5 is content and independent of the rest. Phase 6 is packaging.

---

13. Risks

R1 — The switching UI is still the sleeper. components.md called it that and it remains the hardest interface in the game. Multiplayer does not make it harder, but four people now watch one person use it.

R2 — Redaction must be exactly right. Everything else degrades gracefully; a redaction bug hands someone else's hand to a player and cannot be walked back. Hence the explicit test, not a review.

R3 — Menu peaks at 9.8 KB against a 2.2 KB mean. If that bites, send placements only for a selected card. Measure before optimising.

R4 — Idle time, not latency, is what makes 4-player games drag. You watch ~17 of 22 intents per Stage. D19 keeps the door open; the instrumentation to decide it is a few lines and belongs in the first real multiplayer games.

R5 — The two provisional rules are still unplaytested. The opening deal and departure Revenue are both flagged for review in TODO.md. Phases 0–1 are safe regardless; Phase 2 onward should wait until those settle, or the server gets built against rules that are still moving.