Jesse.Markowitz/station-master
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity

v0.4.1 - bug fixes. initial d12 rolls determine what player in which seat.

Browse Source
This commit is contained in:
Jesse
2026-08-13 15:28:53 -04:00
parent 49f8504b05
commit a7221dcf20
22 changed files with 736 additions and 237 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/components.md
+11 -10
View File
@@ -35,7 +35,7 @@ decision (you are the Superintendent, ruling on your own trains).
| Turn arbitration between players | Card catalogue |
| Presence, reconnection of others | Track graph and Move legality |
| Fedora rotation between players | Board and action UI |
| Competitive/Co-op victory modes | Event log and persistence |
| Competitive/Co-op victory modes | Intent history and persistence |
| Collision floor (Competitive only) | Server and protocol |
**Consequence: the engine is the dominant cost and it is front-loaded.** Components 4–6 barely differ
@@ -141,11 +141,12 @@ is what makes the whole system testable without a server.
- **Size driver:** at MVP one game and one player, so the pump loop is nearly all of it. Grows with
concurrent games and per-player routing.
**9. Event log and persistence**
**9. Intent history and persistence**
- **Where:** Server · **When:** append per event; full read on startup
- **Does:** append-only log to disk; state is `fold(events)`. Powers restart recovery at MVP, and
later reconnection and the replay viewer.
- **Does:** append-only `{ engineVersion, seed, config, history: Intent[] }` to disk. Restart recovery
is `fromSave` over the stored intents; the replay viewer reads the same file
([`protocol.md`](protocol.md) §3 — events narrate, intents reconstruct).
- **MVP: S** · **Final: M** · ~100 → ~350 LOC
- **Size driver:** an append and a read-back. Grows with snapshotting, retention and indexing.
@@ -180,7 +181,7 @@ is what makes the whole system testable without a server.
- **Where:** Server · **When:** once, at process start
- **Does:** reads environment configuration (bind address, port, data directory), opens or creates the
event log, constructs the session host and transport, wires them together, handles shutdown.
intent history, constructs the session host and transport, wires them together, handles shutdown.
- **MVP: XS** · **Final: S** · ~80 → ~200 LOC
- **Size driver:** trivial in itself, but it is where
[`deployment.md`](deployment.md)'s five portability rules are actually enforced — single process
@@ -223,9 +224,9 @@ is what makes the whole system testable without a server.
**16. Replay viewer**
- **Where:** Browser · **When:** after a game ends — **pulled forward, built**
- **Does:** read-only projection over the event log, with playback controls. A Node script
precomputes one frame per visible event and writes a self-contained HTML file, so the browser
never runs the engine and there is no bundling or build step.
- **Does:** read-only playback of a stored game, with controls. A Node script replays the saved
intents, precomputes one `Frame` per visible event with its narration, and writes a self-contained
HTML file — so the browser never runs the engine and there is no bundling or build step.
- **MVP: —** · **Final: S** · 0 → ~250 LOC · *built: 560 LOC (replay) + 330 (narration)*
- **Size driver:** the narration layer, not the rendering. Turning 30 event types into readable
sentences and deriving the "what is currently blocked" panel is most of it.
@@ -304,7 +305,7 @@ under.
[4]apply [5]advance [6]legalActions
└───────┼───────┘
▼
[8] session host ──► [9] event log
[8] session host ──► [9] intent history
│
▼
[10] view projection
@@ -393,7 +394,7 @@ Crew Tray onto a card holding two standing cars, which couples them automaticall
| 4 | Apply | Validates the Move via component 3; rejects with `WOULD_REVERSE` / `NOT_OPERATIONAL_RAIL` / `TRACK_OCCUPIED` if illegal. |
| 3 | Track graph | Confirms the path exists without a direction change. |
| 4 | Apply | Moves the tray, couples the standing cars **in track order**, checks the four-slot limit, decrements Moves. Emits `TrayMoved` and `CarsCoupled`. |
| 9 | Event log | Appends both events to disk. |
| 9 | Intent history | Appends the accepted `switch.move` intent to the game's history on disk. |
| 8 | Session host | Calls `advance` — no automatic work is due mid-Local-Ops, so it returns `needsInput`. |
| 10 | View projection | Rebuilds the view. Nothing is redacted here; the board is public. |
| 6 | Legal-action enumeration | Recomputes affordances from the new state — fewer Moves remain, and a fuller consist may now be at its four-slot limit. |
docs/architecture/deployment.md
+1 -1
View File
@@ -16,7 +16,7 @@ The requirements are modest, which is what makes both paths viable:
| --- | --- |
| One long-running process | Active games are held in memory ([`overview.md`](overview.md)) |
| Plain HTTP on one port | Lobby and intents over POST, game stream over SSE — no WebSocket upgrade, which is what keeps this a *plain* HTTP need ([`multiplayer.md`](multiplayer.md) D5) |
| A writable data directory | The append-only event log ([`lobby-and-sessions.md`](lobby-and-sessions.md)) |
| A writable data directory | The append-only `{ seed, config, history }` per game ([`lobby-and-sessions.md`](lobby-and-sessions.md)) |
| Static asset serving | The browser client |
| No outbound network access | The game talks to nobody |
| No scheduled work | Nothing in the rules is real-time ([`overview.md`](overview.md)) |
docs/architecture/lobby-and-sessions.md
+152 -61
View File
@@ -10,20 +10,31 @@ Written against [`../rules/rules-v0.2.md`](../rules/rules-v0.2.md).
## 1. Identity
No accounts to begin with. A player is a **display name** plus a **session token** the server issues
on join and the client stores locally.
No accounts. Access to the server is a **join secret** (§2); identity within a game is a **display
name** plus a **session token** the server issues on join and the client stores locally.
```
Session
token : opaque, unguessable
gameId
playerIndex
player : PlayerIndex
displayName
```
The token is what makes reconnection work: it proves "I am the player who was sitting at seat 2,"
which is the only identity claim the game needs. Keep it out of URLs so it is not shoulder-surfed or
pasted into a chat.
**It names the PLAYER, not the seat.** Those became different things in v0.4.0, and the difference is
exactly the case this field has to survive: under Employee Rotation (§4) a player changes chairs while
their Revenue and their identity stay with them. A token naming a seat would sit a returning player
down in someone else's Office. The seat is derived with `seatOf(state, player)` whenever it is needed,
which is one lookup and always current.
The token is what makes reconnection work: it proves "I am the player who was in this game," which is
the only identity claim the game needs. Keep it out of URLs so it is not shoulder-surfed or pasted
into a chat.
**Tokens are per-origin.** The server may be reached by more than one address — `stationmaster.<domain>`
and `<ip>:<port>` are both expected — and browser storage is scoped to the origin. A player who joined
at one address must come back to that address, or they are a stranger with no token. Say so in the
UI at join time rather than letting someone discover it when they cannot get back in.
Real accounts can be layered on later without touching the rules engine, which is exactly why
[`overview.md`](overview.md) keeps that boundary sharp.
@@ -33,22 +44,45 @@ Real accounts can be layered on later without touching the rules engine, which i
## 2. Creating and joining
```
Lobby.Create { config } → { gameId, gameCode, token }
Lobby.Join { gameCode, displayName } → { token, playerIndex }
Lobby.Create { secret, config } → { gameId, gameCode, token }
Lobby.Join { secret, gameCode, displayName } → { token, player }
```
A **game code** — short, human-speakable, e.g. `RAIL-4471` — is the whole discovery mechanism. No
matchmaking, no browsing, no public game list. Players are already talking to each other; the code
just needs to survive being read aloud.
**These four messages are the one family with no types behind them**, because the engine has no
concept of a lobby — `intents.ts` starts at `localOps.choose`. Everywhere else, the code is the
protocol ([`protocol.md`](protocol.md)); here the prose is, until the server exists.
The creating player is the **host**: they set the config (§3) and start the game. Host-only rights
end at `Lobby.Start` — the rules give no player special standing during play, and the Superintendent
role rotates independently (§5).
**The join secret gates the door.** Server-wide, set by environment variable, passed out of band by
whoever runs the server (`multiplayer.md` D14). Anyone holding it may create a game and may join any
created game that has not started. It is not per-game and it is not an account — it is the cheapest
thing that stops a clearnet-reachable box from being someone else's game server. Typed once and kept
per-origin, alongside the token.
**Player counts.** Solitaire is 1. Competitive and Co-op need at least 2. The upper bound is a
practical judgment rather than a rules limit: the Division grows by one Office and one Mainline card
per player (§4.3), and every added player lengthens the Superintendent's rotation and the
phase-major waiting. **6 is a sensible cap** for the prototype.
A **game code** — short, human-speakable, e.g. `RAIL-4471` — is the discovery mechanism *inside* the
door. No matchmaking, no browsing, no public game list. Players are already talking to each other; the
code just needs to survive being read aloud.
**One game at a time per person is expected usage and is deliberately not enforced** (`multiplayer.md`
§10). Enforcing it needs cross-game state whose only job is deciding when to release someone, and
getting that wrong locks a player out of their own server.
The creating player is the **host**: they set the config (§3) and start the game. **If the host leaves
before `Lobby.Start`, host rights pass to the earliest-joined remaining player.** No lobby should ever
be stuck waiting on somebody who closed a tab, and the alternative — everyone leaves and someone makes
a new game — throws away the seating they had already agreed. Host rights end at `Lobby.Start`
regardless: the rules give no player special standing during play, and the Superintendent rotates
independently (§4).
**Player counts.** Solitaire is 1. Competitive and Co-op are **2 to 4**. Nothing in the engine enforces
a limit, so the lobby is where it is enforced — and the number is set to what is actually exercised
(`test/multiplayer.test.ts` plays 2, 3 and 4 to a finish) rather than to a guess. The cost of more is
real: the Division grows by one Office and one Mainline card per player (§4.3), and every added player
lengthens both the Superintendent's rotation and the phase-major waiting. Raise the cap when somebody
has played a bigger game and reported back, not before.
This is a lobby judgment, **not a rules limit** — §7 of the rules describes what happens at five or
more players (the New Train round ends mid-pass when the consist fills) and the engine implements it.
The cap is about what has been played, not about what the game can do.
---
@@ -67,6 +101,10 @@ These must lock at `Lobby.Start`. Changing `length` mid-game would move the fini
`mode` would switch which failure floors apply (§3.4, §3.5). Neither has a coherent meaning
mid-game, so the server should refuse rather than try.
`mode` and the seat count are checked together at start: solitaire is exactly 1, competitive and
co-op are 2 to 4 (§2). The engine will happily build a 7-player Division, so this is the only place
the limit exists.
---
## 4. Seating
@@ -82,80 +120,132 @@ So seating must be settled before the opening D12 rolls, and the lobby should sh
visually — a player should see whose Office lies east and west of theirs before the game begins.
**The opening rolls** (§4.4, §4.5) happen server-side at `Lobby.Start`, from the game seed: highest
D12 takes the Eastern Division Point, and a second roll picks the opening Superintendent. Emit both
as events so clients can show the rolls rather than just the outcome — it is the game's first moment
of drama and there is no reason to hide it.
D12 takes the Eastern Division Point, and a second roll picks the opening Superintendent.
**Both are implemented.** The Division roll was drawn and discarded until v0.4.1 — `void
divisionRolls`, with seating fixed by array order — so §4.4 decided nothing and the seat/player split
was untested at runtime. It orders the chain now: `seating[seat] = player`, ascending by roll from
seat 0 (west, beside the Western Division Point) to the last seat (east, "highest is the Eastern
Division Point").
The rule names only those two ends, because at a table the players are already sitting in a chain and
the roll only says which way round it is. There is no physical table here, so the roll orders
everybody — it uses a number every player is already told to roll, and it makes the roll matter to
more than the winner. Ties break toward the lower player index sitting further east, the same
first-max-wins convention the Superintendent roll uses.
Both rolls are kept on the state as `openingRolls`, indexed by player, **so the lobby can show the
rolls rather than only their outcome** — it is the game's first moment of drama and there is no reason
to hide it. Show the chain forming.
**Solitaire is unchanged and must stay so:** one player is one seat, seating is trivially `[0]`, and
every published replay depends on that.
**Employee Rotation** (Appendix B), if enabled, moves every player one seat left at the end of each
Day, carrying their Revenue and the Fedora with them. Note what this means for the model: a player's
*seat* changes while their *score* follows them, so `Player.index` and Office ownership must be
separable. This is the one optional rule with real structural consequences — worth wiring in from the
start rather than retrofitting.
Day, carrying their Revenue and the Fedora with them. **The model supports this as of v0.4.0**:
offices and districts are keyed by seat, hands and Revenue and the Fedora by player, and `seating[]`
maps between them, so rotating is a one-line operation and every `areaOf(state, player)` caller
follows without changing. The *rule* is still unimplemented — nothing rotates `seating` yet — but the
structure it needs is in place and tested, which was the point of doing it early.
---
## 5. Disconnection and reconnection
Turn-based with one actor at a time makes this far easier than it would be in a real-time game.
Being turn-based makes this far easier than it would be in a real-time game. (It is no longer "one
actor at a time" — v0.4.0 gave every player their own `TurnState` precisely so that players can act in
parallel where the rules allow it, `multiplayer.md` D19. Nothing about disconnection changes: the game
still waits on whoever it is waiting on.)
**On disconnect:** keep the seat. Do not remove the player, do not auto-play. The game simply waits
if it was their turn. Broadcast a `PlayerDisconnected` event so everyone else can see why nothing is
happening — silence with no explanation is the worst version of this.
if it was their turn. Broadcast a disconnect notice so everyone else can see why nothing is happening
— silence with no explanation is the worst version of this. There is no such event type today; it is
server-layer news about a *connection*, not about the game, so it belongs with the transport rather
than in `GameEvent`, which must stay replayable from a seed.
**On reconnect:** the client presents its token, and the server replies with a full current view plus
the event tail it missed. Because state is `fold(events)` ([`protocol.md`](protocol.md)), catching up
is a replay, not a special case.
**On reconnect:** the client presents its token and the server replies with a **full current view**.
Not an event tail — a returning client needs the position, not the history of how it got there, and
the server can always produce the position because it holds the game
([`protocol.md`](protocol.md) §3). This is why catching up is not a special case.
**On a player who does not come back:** the honest options at this scale are to wait, or to let the
host end the game. An optional **turn timer** is worth having — a lobby setting, off by default,
never part of the rules — that on expiry takes the safest legal action:
host end the game.
| Phase | Timeout action |
| --- | --- |
| Local Operations | `Switch.End` / `Draw.End` — forfeit the remaining action |
| New Train | `NewTrain.PassCar` if legal, else place any legal car |
| Mainline clearance | **Deny** clearance — the safe answer; a held train costs a Stage, a wrecked one costs 5 Revenue and counts toward the collision floor |
| Load/Unload | `LoadUnload.End` |
**Nothing moves on an absent player's behalf.** No forcing timer, no bot stepping in. Jesse's call,
and the reasoning is the same one that keeps bots out of running games generally: the Superintendent's
clearance decision materially affects *other* players' scores, so anything that answers it
automatically changes the game rather than preserving it. Bots fill empty seats **at game start
only** (`multiplayer.md` D8). Two ways out of a permanently-halted game are recorded in `TODO.md` and
deliberately not designed here — a bot playing minimally-damaging defensive moves for someone who
stepped away, and a player *consenting* to resign their railroad to a bot. Both need care; neither is
a timer.
Denying clearance on timeout is the right default and worth stating explicitly: the asymmetry between
the two outcomes is large, and in Competitive mode a timed-out clearance that causes a wreck could
end the game for everybody (§3.4).
### The turn clock — a stopwatch, not a shot clock
**Do not substitute an AI player.** The Superintendent's clearance decisions materially affect other
players' scores; a bot making them on an absent player's behalf changes the game rather than
preserving it.
**Record how long each player takes on each turn.** Not to enforce anything: to find out where the
game actually goes. "A 4-player game takes an evening" is currently a guess, and the useful version of
that answer is per-phase — whether the wait is Local Operations, or making up a train, or one player
thinking about a clearance while three others watch. That is what tells you which part is worth
speeding up, and it is the one measurement no amount of bot simulation can produce, because the bot
does not think.
Where it lives matters:
- **Outside the rules engine.** The engine has no clock and must not acquire one — it is pure and
deterministic given a seed, which is what makes every replay and every test work.
- **Outside the canonical record.** Timings are stored beside `{ engineVersion, seed, config, history }`,
never inside it. A replay must reproduce a game from decisions alone; if it depended on wall-clock
data it would no longer be reproducible from a seed.
- **In the session host**, which already sees each intent arrive and already knows whose turn it is.
Wall-clock at the start of a turn, wall-clock at the intent that ends it, per player per phase.
Show the current turn's elapsed time in the UI if it is unobtrusive — a table can self-regulate on
information alone, which is the polite version of a shot clock and costs nothing.
---
## 6. Persistence
Persist the **event log**, not a state snapshot. It is smaller, it is the thing that already exists,
and it makes a mid-game server restart a replay rather than a recovery.
Persist the **intents**, not a state snapshot and not the event log. This section said "event log"
until v0.4.0, on the strength of a `state = fold(events)` claim that was never true
([`protocol.md`](protocol.md) §3) — folding the log rebuilds card plays and switching, and not one
train movement. The intents genuinely do reconstruct a game, they are smaller still, and `fromSave`
already replays them, so a mid-game server restart is a replay rather than a recovery.
```
games : gameId → { config, seed, status, createdAt, gameCode }
events : gameId → ordered event list
sessions : token → { gameId, playerIndex, displayName }
games : gameId → { engineVersion, config, seed, status, createdAt, gameCode }
history : gameId → ordered Intent list
sessions : token → { gameId, player, displayName }
```
`engineVersion` is stored beside the seed because a replay is only faithful under the rules it was
recorded with. A version mismatch on load must be refused explicitly rather than replayed and quietly
diverged (`multiplayer.md` Phase 3).
Requirements are modest enough that the storage choice is genuinely open — SQLite on a single node
covers this comfortably, and so would flat files with an append-only log per game. The constraint
worth honouring is that the **event log is append-only**: rewriting history breaks the one property
that makes replay trustworthy.
covers this comfortably, and so would flat files with an append-only list per game. The constraint
worth honouring is that the **history is append-only**: rewriting it breaks the one property that
makes replay trustworthy. (Undo is not an exception — it replays the history *without* the last
intent, and a server does not offer it at all.)
**Snapshotting** is an optimisation, not a requirement. If a Campaign game's log grows long enough
that replay feels slow, periodically store a state snapshot with its `eventSeq` and replay forward
from there. Do not build this until it is needed.
**Snapshotting** is an optimisation, not a requirement. If a Campaign game's history grows long
enough that replay feels slow, periodically store a state snapshot with its intent count and replay
forward from there. Do not build this until it is needed. Measured today: a finished solitaire game
is ~350 intents and a few hundred bytes.
**Retention.** Finished games **keep their event log, seed and config**, because post-game replay is
a wanted capability (see [`overview.md`](overview.md#post-game-replay--a-desired-future-capability))
and the log is the only thing it needs. Do not delete finished games by default.
**Retention.** Finished games **keep their history, seed and config**, because post-game replay is a
wanted capability (see [`overview.md`](overview.md#post-game-replay--a-desired-future-capability))
and those three are the only things it needs — the replay viewer on the site already reads exactly
that file. Do not delete finished games by default.
Retention is an operator setting rather than an application decision — a self-hosted instance among
friends may as well keep everything, since a finished game's log is small. If a cap is wanted, expire
by age or by total count and say so plainly in the UI, because a replay that silently stops existing
is worse than one that was never offered.
**Turn timings** (§5) are stored per game beside the history, never inside it, and are retained on the
same terms — they are only interesting in aggregate, and only across enough games to see a pattern.
Session tokens are the exception: those can expire on a short window once their game has finished.
---
@@ -167,7 +257,8 @@ At small self-hosted scale these are not needed, and building them early costs m
- **Matchmaking or a public game browser.** The game code covers discovery.
- **Ranking, ladders, persistent profiles.** §3's timed modes produce comparable scores, so a
high-score table would be a natural first addition — but it is a feature, not infrastructure.
- **Spectators.** Straightforward to add later, since a spectator is just a view with no `private`
section and no ability to send intents — the same shape post-game replay needs.
- **Spectators.** Straightforward to add later: a spectator is a `Frame` with no hand and no ability
to send intents. `snapshot` already takes a viewing seat, so the only new thing is a viewer that
belongs to no seat — the same shape post-game replay already uses.
- **Horizontal scaling and cross-process coordination.** One process holds every active game
in memory.
docs/architecture/multiplayer.md
+39 -15
View File
@@ -31,10 +31,17 @@ 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.
deterministic engine, two entry points (`applyIntent` / `pump`), events that render standalone,
per-player redacted views.
Three things moved:
Four things moved:
**`state = fold(events)` is not true, and the intents are canonical instead.** `applyIntent` does go
through the reducer, but the phase driver does not — it mutates and then emits a descriptive event —
so fourteen of the forty-six event types are never reduced, including the clock and the whole Mainline
phase. This costs nothing, because the plan never needed it: persistence is `{ seed, history }` (§10)
and the wire carries `Frame`s rather than events (D2/D3). Reconnection is a fresh `Frame`, not an
event tail.
**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).
@@ -270,14 +277,24 @@ Two consequences:
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:
**Seating is decided by §4.4's D12** as of v0.4.1, so `seating` is a real permutation rather than the
identity mapping. Everything "round the table" — acting order, the deal, the Fedora — is seat
arithmetic via `playerLeftOf`, and the three places that were doing it with player indices were found
and fixed by turning the roll on. That is the point: the seat/player split is now exercised by every
multi-player game instead of only by tests that rotate `seating` by hand.
**Identity: a session token scoped to one game**, exactly as `lobby-and-sessions.md` describes.
Joining issues it; presenting it *is* the rejoin, because it already names the game and the person:
```
Session token, gameId, seat, displayName
Session token, gameId, player, displayName
```
It names the **player**, not the seat — the two stopped being the same thing in v0.4.0, and Employee
Rotation is precisely the case where a token naming a chair would seat someone in the wrong Office.
The seat is `seatOf(state, player)`, one lookup and always current. (This said `seat` until the
`lobby-and-sessions.md` review.)
The join secret is separate and server-wide — typed once and kept per-origin for convenience. It
gates entry; the token identifies a seat.
@@ -378,31 +395,38 @@ source check that `main.ts` never regains a `GameState` read or a value import f
14. Append-only `{engineVersion, seed, config, history}` per game; index.
15. Load on start; rebuild via `fromSave`; refuse a version mismatch explicitly.
16. **Turn timings**, stored beside the history and never inside it — wall-clock per player per
phase, so "how long does a 4-player game take, and which phase is the wait?" becomes a measured
answer instead of a guess (`lobby-and-sessions.md` §5).
**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.
17. Join secret; per-game session token naming the **player** (not the seat); display name.
18. Create/join by game code; bot seats; seating UI showing the west-to-east chain; config locked at
start; **2–4 players enforced here**, since the engine enforces nothing.
19. Disconnect keeps the seat and announces it; reconnect replies with a full `Frame`.
20. Host rights pass to the earliest-joined remaining player if the host leaves before start.
**No forcing turn timer** — cut in the `lobby-and-sessions.md` review, and in `TODO.md` as something
to explore only if halted games turn out to be a real problem. Nothing moves on an absent player's
behalf.
**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.
21. The 10 Action and 12 Space-use cards; flip `opponentCardsInDeck` in `setup.ts`.
22. 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.
23. `.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.
docs/architecture/overview.md
+18 -8
View File
@@ -67,12 +67,18 @@ Three flows, and keeping them distinct is what keeps the implementation tractabl
```
- **Intents** are what a player wants to do. They are proposals; they can be rejected.
- **Events** are what happened. They are facts, ordered, and form the game's history.
- **Events** are what happened. They are facts, ordered, and standalone — they narrate the game.
They do **not** reconstruct it: see `protocol.md` §3, and the note below.
- **Views** are per-player projections of state, with other players' hands redacted.
An event log that fully determines state is worth building even at this scale. It gives
reconnection (replay to catch up), persistence (store the log, not a snapshot), and debugging (replay
a reported bug exactly) for one design decision.
A recorded, ordered history is worth keeping even at this scale. It gives persistence (store the
history, not a snapshot) and debugging (replay a reported bug exactly) for one design decision.
**That history is the INTENTS, not the events.** This paragraph originally said an event log "fully
determines state", and it does not — the phase driver mutates state and then emits a descriptive
event, so fourteen of the forty-six event types are never reduced, including every train movement.
A game is `{ seed, history: Intent[] }` and `fromSave` replays it exactly. Reconnection is therefore a
fresh view rather than a catch-up replay, which is simpler anyway.
### Post-game replay — a desired future capability
@@ -84,9 +90,13 @@ traffic, the wrecks, who was Superintendent when. For a game whose drama is larg
you are playing your own Office, this is worth more than it would be in most games. You spend the
game watching your own station; the replay is where you find out what the railroad was doing.
State is already `fold(events)` over an ordered, append-only log, and all randomness derives from a
stored seed. Replay is therefore a **read-only projection over the existing log** — no new rules-engine
surface, no second code path, nothing the server has to do differently during play.
A game is already reconstructible from `{ seed, history: Intent[] }`, and all randomness derives from
that stored seed. Replay is therefore a **read-only re-run of the stored intents** — no new
rules-engine surface, no second code path, nothing the server has to do differently during play.
(This paragraph said "state is `fold(events)`" until v0.4.0. It is not: the phase driver mutates state
and then emits a descriptive event, so folding the log rebuilds card plays and switching but not one
train movement or clock tick. The intents are what is canonical.)
Three constraints keep it cheap, and all three are free if honoured from the start:
@@ -144,7 +154,7 @@ is a lobby setting layered on top of the rules, never part of them.
Worth stating, because small self-hosted scale makes several standard concerns disappear:
- **No horizontal scaling.** A handful of concurrent games fits in one process. Game state lives in
memory; the event log is persisted for durability, not for coordination.
memory; the intent history is persisted for durability, not for coordination.
- **No matchmaking service.** Players share a game code (see `lobby-and-sessions.md`).
- **No accounts system, initially.** A display name plus a session token is enough to join and
reconnect. Real accounts can be layered on later without touching the game engine.
docs/architecture/protocol.md
+14 -5
View File
@@ -11,7 +11,7 @@ that live nowhere else.
| Family | Direction | Authority |
| --- | --- | --- |
| **Intent** — a proposal, may be rejected | client → server | [`src/engine/intents.ts`](../../src/engine/intents.ts) — `Intent`, 28 variants |
| **Event** — a fact, ordered, the game's history | server → clients | [`src/engine/events.ts`](../../src/engine/events.ts) — `GameEvent`, 46 variants |
| **Event** — a fact, ordered; narration, not the record (§3) | server → clients | [`src/engine/events.ts`](../../src/engine/events.ts) — `GameEvent`, 46 variants |
| **View** — a redacted projection | server → one client | [`src/sim/view.ts`](../../src/sim/view.ts) — `Frame` and `snapshot(state, …, seat)` |
| **Rejection** — why an intent was refused | server → one client | `RejectionCode` in `intents.ts` |
@@ -79,8 +79,16 @@ which makes them worth logging server-side: a spike means client and server rule
## 3. Events
Events are the authoritative history: `state = fold(events)`, which buys reconnection, persistence and
post-game replay for one design decision.
**Events narrate; they do not reconstruct.** This section claimed `state = fold(events)` until
v0.4.0, and it was never true: `applyIntent` goes through `reduce`, but the phase driver mutates state
and *then* emits a descriptive event, so fourteen of the forty-six event types are never reduced — the
clock, and the whole Mainline phase, which is to say every train movement in the game.
**The canonical record is `{ seed, history: Intent[] }`**, replayed by `fromSave`. That is what save,
share, undo, restart recovery and post-game replay all run on, and it is what persistence stores
(`multiplayer.md` §10). Events drive the display and the notifications. Do not build anything on
folding them without first making the phase driver reduce, which is a rewrite of the most rule-dense
code in the project and buys nothing the current plan uses.
**Events must render standalone** — the rule is stated at the top of `events.ts` and it is the one that
gets broken by accident. Carry the `from`/`to`, not an id the renderer resolves against live state,
@@ -92,8 +100,9 @@ Two consequences worth knowing before adding an event:
Fault depends on *where* the wreck happened — Superintendent for a Mainline card, the local player
between their Limits (§10) — and getting it wrong misattributes a −5 and, in Competitive, feeds a
floor that ends the game.
- **Events are not what goes over the wire.** The server folds them and pushes the resulting `Frame`
(`multiplayer.md` D2/D3). They are the store and the replay format, not the protocol.
- **Events are not what goes over the wire.** The server applies the intent and pushes the resulting
`Frame` (`multiplayer.md` D2/D3). Events are narration and cues, not the protocol — and a reconnect
gets a fresh `Frame` rather than the tail it missed.
---
docs/design.md
+38 -58
View File
@@ -49,73 +49,53 @@ must do.
## Current status
Rules formalized, card faces specified, architecture documented, and the rules engine built and
simulated. Eleven of thirteen gaps are closed; **Gap 12 (balance variance) and Gap 13 (deck scaling)
remain open**, both with data behind them.
**v0.4.1.** Rules formalized, card faces specified, architecture documented, and the game playable
solitaire in a browser. See [`../CHANGELOG.md`](../CHANGELOG.md) for what each version changed and
[`../TODO.md`](../TODO.md) for what is open; this section is the shape of the project, not a
running tally, because a hand-maintained tally is what drifted last time.
Gaps 8–13 were all found by working the design forward — building it or simulating it — rather than
by reading the PDFs. None arises in tabletop play, where a person simply does the sensible thing.
**What is built.** The rules engine, the developer bot, the balance harness, the replay viewer and
the playable page — components 1–7, 17 and 18 of
[`architecture/components.md`](architecture/components.md). A game can be saved, shared, replayed and
stepped back through. **493 tests.**
**What is not.** The server. Phases 0 and 1 of
[`architecture/multiplayer.md`](architecture/multiplayer.md) landed in v0.4.0 — seat and player are
separate, turn state is per player, and the page talks to a `Session` rather than to the engine, so a
`RemoteSession` drops in without the page changing. Phase 2 onward is **deliberately held** until the
two provisional rules introduced in v0.3.0 have been played at a table: changing a rule after the wire
format is live costs far more than changing it before. Also unbuilt: the 22 opponent-directed cards
and real audio.
**Balance is not where it should be, and no conclusion should be read from the revenue numbers yet.**
The rebalance pass is deliberately deferred until the rules stop moving — card counts, industry counts
and the track mix all need moving together. `TODO.md` carries the standing distortions and the
measurements behind them.
**Three rules are genuinely open**, and they are the reason the README does not claim the rules are
finished: where the Local's coach stands while its engine works (a §A.4 question, not a train-card
question); Poling, the one card in the deck with no defined behaviour; and whether a Heavy Grade's
orientation is rolled or chosen at setup. Thirteen gaps in the prototype rules were found and closed;
these three came after.
**The event log narrates; the intents reconstruct.** Settled in v0.4.0 after the documentation had
claimed `state = fold(events)` for months. It is not true — the phase driver mutates state and then
describes it — so the canonical record is `{ seed, history: Intent[] }` and persistence will be built
on that. [`architecture/protocol.md`](architecture/protocol.md) §3 has the reasoning;
`test/events.test.ts` pins it.
**The economy, in one line:** Local Operations actions are the main currency — one per Stage, twelve
per Day — but **inbound work bypasses them**, which is where the game's variance comes from. See
`card-reference.md` §7.
**Wanted, not yet designed:** post-game replay — watching a finished game back at speed. The
architecture already produces what it needs (an ordered append-only event log plus a stored seed), so
the note in `architecture/overview.md` exists to keep the capability from being designed out. It is
explicitly not scheduled.
**Provisional numbers** — the victory targets are now confirmed at the mean by simulation. Still
untested by play: Crew Tray count, Laborer counts, and whether the variance in Gap 12 is a flaw.
**Next steps.** The specification is complete enough to build against or to play on paper.
The build path is laid out in [`architecture/components.md`](architecture/components.md) — 20
components, a dependency graph, and a twelve-step order. Its **MVP is solitaire: one Office, a fixed
number of Days, a server talking to a single browser, display functional rather than pretty.** The
milestones worth knowing:
- **Step 4** — a full solitaire game runs to completion headless, proving the rules before a pixel is
drawn.
- **Step 6** — the balance harness validates or retunes the provisional numbers, while changing them
is still free.
- **Step 10** — MVP complete; a human plays end to end.
**Stack: TypeScript**, chosen so the engine runs in both the server and the browser — one
implementation of the movement rules, and instant affordances without a round-trip. Node 22 runs
TypeScript natively, so there is no build step during development.
TypeScript natively, so there is no build step during development, which also means **erasable syntax
only**: no `enum`, no parameter properties, no namespaces.
> **The recovered design files are now transcribed and the nine open questions answered** — see
> [`rules/implications.md`](rules/implications.md) §1b for exactly what is implemented. The deck is
> 115 cards (93 in solitaire), Mainline cards have terrain and crossing times, and the balance
> numbers below predate all of it.
**Steps 1–6 are done** — the rules engine (components 1–7), heuristic bots (17) and the balance
harness (18), with 134 tests passing.
**The step 4 milestone is met: a full solitaire game runs to completion, headless.** Games are
reproducible from a seed, terminate from every seed tried, conserve all 62 rolling stock pieces, and
develop properly.
**End-of-game statistics** (`src/sim/stats.ts`) report revenue by source, traffic, development,
action mix and strategy buckets — plus an **anomaly detector** that treats "this event never fired"
as a finding. It caught two bugs on its first run.
**The step 6 milestone is met, with a caveat.** The harness found **five engine bugs that no test had
caught**, and once they were fixed the numbers came good: **~35% win rate and 5.0 Revenue/player/Day,
matching the Gap 10e prediction of 5-6.**
The caveat is large: those numbers were themselves measured against a **scoring bug**, since fixed.
Honest figures are ~0.9 Revenue/Day and a **0% win rate** — the targets are currently unreachable.
The bot is still the prime suspect (it uses ~10 Laborer actions per game out of ~900 available), so
this is **Gap 12** and remains open. One genuine signal did emerge: **mixed freight/passenger
strategies outscore pure ones**, with pure freight much the worst.
**Gap 11 is decided** — track orientation is chosen on placement, settled by measurement.
**Gap 13** answers the deck-size question: do not double it; scale only the buildable cards with
player count.
Next: step 7 begins the server (components 8, 9, 20).
Running alongside, and independent of all of it: **print-and-play components.** `card-reference.md`
specifies every card face, so layout and art are the only remaining work before a table playtest —
which answers the one question simulation cannot, whether it is fun.
Run the harness with `node src/sim/harness.ts [games] [length]`.