v0.5.0 — multiplayer Phases 2 and 3: a server that runs a game and survives being restarted

Phases 0-1 shipped in v0.4.0 (seat/identity split, per-player turn state, the Session boundary).
This lands Phase 2 (server core, one game, no lobby) and Phase 3 (persistence and resumption) per
docs/architecture/multiplayer.md §12. Phases 4-6 (lobby/reconnection, the 22 opponent-directed
cards, StartOS packaging) are still ahead.

Phase 2: src/server/session.ts hosts a game in pure logic (no sockets) on top of game.ts's existing
Game/submit/currentActor/actionMenu; it verifies seat === currentActor(game) itself before calling
submit, since submit() trusts its caller and a server can't. src/server/http.ts and index.ts add
POST /api/game, GET /api/stream (SSE, per-seat), POST /api/intent, and static serving of dist/.
src/sim/frame-delta.ts is a purpose-built per-seat board delta for one live push at a time. Found
and fixed along the way: actionMenu(game, seat) only used seat for the hand field, so a server
computing every connected seat's Menu would have handed the acting player's legal moves to a
waiting seat. Verified with a live end-to-end smoke test (2-player game, two SSE streams, a
rejected intent from the wrong seat, an idempotent resend) plus test/server/session.test.ts and
test/redaction.test.ts. Not verified: an actual browser (none available in this environment).

Phase 3: src/server/persistence.ts writes game.json and turn-timings.json, atomic-rewrite-then-
rename. game.ts gained fromMultiplayerSave, fixing a narration-attribution bug found while testing
it (fromSave's replay loop drops the actor argument, invisible in solitaire, unreadable the moment
there's more than one seat — fromSave itself still has this gap, deliberately untouched). Verified
live: server killed and restarted mid-game, both seats reconnected exactly where they left off.

Two rules bugs found while building this: the New Train phase never implemented its car-placement
round (every car of every train was placed by the Superintendent alone, in every mode, all along —
now reads the round position off tray.consist.length); and victory conditions are now one shared,
configurable GameConfig set across solitaire/competitive/coop instead of a fixed length lookup and
a dead firstToTarget condition.

Also folds in the three fixes already released on the patch line as v0.4.9b/c/d: a switching
train's crew badge failing to draw once it left the Office square, an unload that always took the
westmost car regardless of which was picked, and a legal decision that could render with zero
buttons.

docs/testing/0.5.0-test-plan.md and three reported-bug save files (docs/station-master-seed*.json)
included for reproducibility. tools/jitsi-harness/ deliberately left untracked — unrelated
side-project work, not part of this release. 635 tests, 0 failures.

src/server/http.ts

@@ -0,0 +1,197 @@
+/**
+ * The HTTP/SSE wiring — Phase 2 of `docs/architecture/multiplayer.md` (§8-9, §12 steps 8 and 12).
+ *
+ * Plain `node:http`, no framework: the project has zero runtime dependencies
+ * (`package.json`), and `scripts/build-web.ts` already shells out to `tsc` directly rather than
+ * reaching for a bundler — this matches that everywhere-else choice rather than introducing the
+ * first framework dependency for one route table.
+ *
+ * All the game logic lives in `session.ts`; this file is deliberately thin — routing, the join-secret
+ * gate, SSE mechanics, and static file serving for the built client (`dist/`, D16: the server serves
+ * the client, which is what makes same-origin work with no CORS).
+ */
+
+import { createServer } from 'node:http';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { extname, join, normalize } from 'node:path';
+
+import type { Intent } from '../engine/intents.ts';
+import type { GameConfig, PlayerIndex } from '../engine/state.ts';
+import { appendTiming, writeGame } from './persistence.ts';
+import { createSession } from './session.ts';
+import type { GameSession, Push } from './session.ts';
+
+export type ServerOptions = {
+  port: number;
+  bindAddress: string;
+  /** D14 — a server-wide secret, passed out of band. Gates every `/api/*` route. */
+  joinSecret: string;
+  /** The built client (`npm run build:web`'s `dist/`), served at `/` (D16). */
+  distDir: string;
+  /** Where `game.json`/`turn-timings.json` live (Phase 3). */
+  dataDir: string;
+  /** `package.json`'s version — stamped onto every write, checked on every load (§12 step 15). */
+  engineVersion: string;
+  /** Already reconstructed by `index.ts`'s load-on-start, or `null` for a fresh server. */
+  initialSession: GameSession | null;
+};
+
+const MIME: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+};
+
+const HEARTBEAT_MS = 20_000;
+
+async function readJson(req: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) chunks.push(chunk as Buffer);
+  const text = Buffer.concat(chunks).toString('utf8');
+  return text.trim() === '' ? {} : JSON.parse(text);
+}
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  const text = JSON.stringify(body);
+  res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Content-Length': Buffer.byteLength(text) });
+  res.end(text);
+}
+
+async function serveStatic(distDir: string, urlPath: string, res: ServerResponse): Promise<void> {
+  const rel = urlPath === '/' ? '/index.html' : urlPath;
+  // `normalize` collapses `..`, and the join is then checked to still be inside `distDir` — a request
+  // for `/../../etc/passwd` must not escape the one directory this is allowed to read from.
+  const full = join(distDir, normalize(rel));
+  if (!full.startsWith(distDir)) {
+    sendJson(res, 400, { error: 'bad path' });
+    return;
+  }
+  try {
+    const info = await stat(full);
+    if (!info.isFile()) throw new Error('not a file');
+    res.writeHead(200, { 'Content-Type': MIME[extname(full)] ?? 'application/octet-stream', 'Content-Length': info.size });
+    createReadStream(full).pipe(res);
+  } catch {
+    res.writeHead(404, { 'Content-Type': 'text/plain' });
+    res.end('not found');
+  }
+}
+
+export function startServer(opts: ServerOptions): void {
+  let session: GameSession | null = opts.initialSession;
+  // One open SSE response per seat — a second connection from the same seat replaces the first
+  // rather than fanning out to both (Phase 2 has no concept of "the same seat from two tabs").
+  const connections = new Map<PlayerIndex, ServerResponse>();
+  const eventIds = new Map<PlayerIndex, number>();
+
+  function checkSecret(url: URL, res: ServerResponse): boolean {
+    if (url.searchParams.get('secret') === opts.joinSecret) return true;
+    sendJson(res, 403, { error: 'bad or missing secret' });
+    return false;
+  }
+
+  function writeSse(seat: PlayerIndex, push: Push): void {
+    const res = connections.get(seat);
+    if (!res) return; // that seat is not currently connected — Phase 4's reconnect story, not this one
+    const id = (eventIds.get(seat) ?? 0) + 1;
+    eventIds.set(seat, id);
+    res.write(`id: ${id}\ndata: ${JSON.stringify(push)}\n\n`);
+  }
+
+  function broadcast(pushes: Map<PlayerIndex, Push>): void {
+    for (const [seat, push] of pushes) writeSse(seat, push);
+  }
+
+  const server = createServer((req, res) => {
+    void (async () => {
+      const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+
+      if (url.pathname === '/api/game' && req.method === 'POST') {
+        if (!checkSecret(url, res)) return;
+        if (session) {
+          sendJson(res, 409, { error: 'a game already exists on this server' });
+          return;
+        }
+        const body = (await readJson(req)) as { config?: GameConfig; playerNames?: string[]; seed?: number };
+        if (!body.config || !Array.isArray(body.playerNames) || body.playerNames.length < 1) {
+          sendJson(res, 400, { error: 'expected { config, playerNames }' });
+          return;
+        }
+        session = createSession(body.seed ?? Math.floor(Math.random() * 1e9), body.config, body.playerNames);
+        // Persisted immediately, empty history and all — a crash one second after creation should
+        // still resume as "the game exists, day 1, nobody has moved" rather than vanish entirely.
+        await writeGame(opts.dataDir, session.exportSave(), opts.engineVersion);
+        sendJson(res, 200, { ok: true, playerCount: session.playerCount });
+        return;
+      }
+
+      if (url.pathname === '/api/stream' && req.method === 'GET') {
+        if (!checkSecret(url, res)) return;
+        if (!session) {
+          sendJson(res, 404, { error: 'no game yet' });
+          return;
+        }
+        const seat = Number(url.searchParams.get('seat')) as PlayerIndex;
+        if (!Number.isInteger(seat) || seat < 0 || seat >= session.playerCount) {
+          sendJson(res, 400, { error: 'bad or missing ?seat=' });
+          return;
+        }
+        res.writeHead(200, {
+          'Content-Type': 'text/event-stream',
+          'Cache-Control': 'no-cache',
+          Connection: 'keep-alive',
+        });
+        connections.set(seat, res);
+        writeSse(seat, session.connect(seat));
+        // Idle for minutes at a time is the expected shape of this game (multiplayer.md §9) — a
+        // silent SSE connection is exactly what a proxy in the path may reap. A comment line is not a
+        // real event (EventSource ignores lines starting with `:`), so it costs the client nothing.
+        const heartbeat = setInterval(() => res.write(': ping\n\n'), HEARTBEAT_MS);
+        req.on('close', () => {
+          clearInterval(heartbeat);
+          if (connections.get(seat) === res) connections.delete(seat);
+        });
+        return;
+      }
+
+      if (url.pathname === '/api/intent' && req.method === 'POST') {
+        if (!checkSecret(url, res)) return;
+        if (!session) {
+          sendJson(res, 404, { error: 'no game yet' });
+          return;
+        }
+        const seat = Number(url.searchParams.get('seat')) as PlayerIndex;
+        if (!Number.isInteger(seat) || seat < 0 || seat >= session.playerCount) {
+          sendJson(res, 400, { error: 'bad or missing ?seat=' });
+          return;
+        }
+        const body = (await readJson(req)) as { seq?: number; intent?: Intent };
+        if (typeof body.seq !== 'number' || !body.intent) {
+          sendJson(res, 400, { error: 'expected { seq, intent }' });
+          return;
+        }
+        const result = session.intent(seat, body.seq, body.intent);
+        if (result.accepted) {
+          // Persisted BEFORE the response goes out — "accepted" should mean "durably on disk" at
+          // this scale, not just "applied in memory" (§12 step 14).
+          await writeGame(opts.dataDir, session.exportSave(), opts.engineVersion);
+          if (result.timing) await appendTiming(opts.dataDir, result.timing);
+        }
+        sendJson(res, 200, result.accepted ? { ok: true } : { ok: false, code: result.code });
+        if (result.accepted) broadcast(result.pushes);
+        return;
+      }
+
+      await serveStatic(opts.distDir, url.pathname, res);
+    })().catch((err: unknown) => {
+      sendJson(res, 500, { error: err instanceof Error ? err.message : 'internal error' });
+    });
+  });
+
+  server.listen(opts.port, opts.bindAddress);
+}

src/server/index.ts

@@ -0,0 +1,51 @@
+/**
+ * Process bootstrap — Phase 2 §12 step 8, extended for Phase 3 (§12 steps 14-15) load-on-start.
+ *
+ * Run with:  node src/server/index.ts
+ *
+ * Env-configured, no config file — matches how the rest of this project's dev-side tooling reads
+ * `process.env` directly (`scripts/build-web.ts`'s `BUILD_DIST_DIR`).
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { startServer } from './http.ts';
+import { loadGame } from './persistence.ts';
+import { resumeSession } from './session.ts';
+import type { GameSession } from './session.ts';
+
+const port = Number(process.env['PORT'] ?? 8081);
+const bindAddress = process.env['BIND_ADDRESS'] ?? '0.0.0.0';
+const joinSecret = process.env['JOIN_SECRET'];
+const distDir = resolve(process.env['DIST_DIR'] ?? 'dist');
+const dataDir = resolve(process.env['DATA_DIR'] ?? 'data');
+
+if (!joinSecret) {
+  console.error('JOIN_SECRET must be set — a server-wide secret, passed out of band (D14).');
+  process.exit(1);
+}
+
+// `package.json`'s version IS `engineVersion` (§12 step 15) — the same reading `scripts/build-web.ts`'s
+// `buildStamp()` already does, just from `src/server/` rather than the repo root script directory.
+const root = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const engineVersion = (JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { version: string }).version;
+
+let initialSession: GameSession | null = null;
+
+const loaded = await loadGame(dataDir, engineVersion);
+if (loaded.found && loaded.ok) {
+  initialSession = resumeSession(loaded.saved);
+  console.log(`Resumed a saved game from ${dataDir} (${loaded.saved.history.length} intents replayed).`);
+} else if (loaded.found && !loaded.ok) {
+  // Refused explicitly (§12 step 15) — never silently replayed under rules it wasn't recorded
+  // under. The file is left untouched: rolling the running version back would let it load again.
+  console.error(
+    `Refusing to load ${dataDir}/game.json: it was saved under engine version ` +
+      `${loaded.storedVersion}, this server is running ${engineVersion}. Starting with no active ` +
+      `game. The saved file has not been touched.`,
+  );
+}
+
+startServer({ port, bindAddress, joinSecret, distDir, dataDir, engineVersion, initialSession });
+console.log(`Station Master multiplayer server on ${bindAddress}:${port}, serving ${distDir}`);

src/server/persistence.ts

@@ -0,0 +1,69 @@
+/**
+ * Persistence — Phase 3 of `docs/architecture/multiplayer.md` (§12 steps 14-15;
+ * `lobby-and-sessions.md` §6 specifies the exact shape and reasoning).
+ *
+ * One game per process (Phase 2's scope, unchanged) — two files in `DATA_DIR`, no index and no
+ * `gameId`, both deferred to Phase 4's multi-game generalization same as the server core deferred
+ * them. Every write is a full-file atomic rewrite (write to `.tmp`, `rename` over the real path)
+ * rather than true on-disk appending: §6 says the storage mechanism is genuinely open as long as the
+ * LOGICAL history is never rewritten or reordered, which a full rewrite of an always-growing array
+ * satisfies — and at the measured scale (~350 intents, a few hundred bytes per game) there is nothing
+ * to optimize yet.
+ */
+
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { SavedGame, TurnTiming } from './session.ts';
+
+const GAME_FILE = 'game.json';
+const TIMINGS_FILE = 'turn-timings.json';
+
+type PersistedGame = SavedGame & { engineVersion: string };
+
+async function atomicWrite(path: string, text: string): Promise<void> {
+  const tmp = `${path}.tmp`;
+  await writeFile(tmp, text);
+  await rename(tmp, path);
+}
+
+export async function writeGame(dataDir: string, saved: SavedGame, engineVersion: string): Promise<void> {
+  await mkdir(dataDir, { recursive: true });
+  const payload: PersistedGame = { engineVersion, ...saved };
+  await atomicWrite(join(dataDir, GAME_FILE), JSON.stringify(payload, null, 1));
+}
+
+export type LoadResult =
+  | { found: false }
+  | { found: true; ok: true; saved: SavedGame }
+  /** §12 step 15 — refused explicitly, never silently replayed under the wrong rules. */
+  | { found: true; ok: false; storedVersion: string; currentVersion: string };
+
+export async function loadGame(dataDir: string, currentVersion: string): Promise<LoadResult> {
+  let text: string;
+  try {
+    text = await readFile(join(dataDir, GAME_FILE), 'utf8');
+  } catch {
+    return { found: false };
+  }
+  const payload = JSON.parse(text) as PersistedGame;
+  if (payload.engineVersion !== currentVersion) {
+    return { found: true, ok: false, storedVersion: payload.engineVersion, currentVersion };
+  }
+  const { engineVersion: _engineVersion, ...saved } = payload;
+  return { found: true, ok: true, saved };
+}
+
+/** Appended once per closed turn span (`GameSession.intent`'s `timing` result) — read-modify-write at
+ * this scale rather than real appending, same reasoning as `writeGame`. */
+export async function appendTiming(dataDir: string, timing: TurnTiming): Promise<void> {
+  await mkdir(dataDir, { recursive: true });
+  const path = join(dataDir, TIMINGS_FILE);
+  let existing: TurnTiming[];
+  try {
+    existing = JSON.parse(await readFile(path, 'utf8')) as TurnTiming[];
+  } catch {
+    existing = [];
+  }
+  existing.push(timing);
+  await atomicWrite(path, JSON.stringify(existing, null, 1));
+}

src/server/session.ts

@@ -0,0 +1,200 @@
+/**
+ * The game session host — Phases 2 and 3 of `docs/architecture/multiplayer.md` (§8, §12 steps 9,
+ * 14-16).
+ *
+ * Pure logic, no sockets, no filesystem — `src/server/http.ts` is the thin wiring that calls into
+ * this, and `src/server/persistence.ts` is what actually reads/writes disk. One `GameSession` per
+ * in-memory game (Phase 2 is one game per process; Phase 4 generalizes to many).
+ *
+ * REUSES `src/web/game.ts`'s `Game`/`submit`/`drain`/`currentActor`/`actionMenu` wholesale — all pure
+ * logic already, with no DOM dependency, exactly as `LocalSession` uses them client-side. Building a
+ * second copy of "apply an intent, narrate it, compute the Menu" here would drift from what solitaire
+ * already does and is tested against.
+ *
+ * ONE THING `game.ts`'s `submit` DOES NOT DO: verify who is calling it. `submit(game, intent)` reads
+ * `currentActor(game)` itself and applies the intent AS that player, regardless of who asked — safe
+ * for `LocalSession` (there is only ever one possible caller: the one browser). A server has more than
+ * one seat submitting, so THIS file is where "is `seat` actually allowed to act right now?" has to be
+ * checked, before `submit` is ever called — see `intent()` below.
+ */
+
+import { check } from '../engine/apply.ts';
+import type { Intent } from '../engine/intents.ts';
+import type { GameConfig, PlayerIndex } from '../engine/state.ts';
+import { actionMenu, currentActor, fromMultiplayerSave, newMultiplayerGame, submit } from '../web/game.ts';
+import type { Game, Menu } from '../web/game.ts';
+import { deltaFrame } from '../sim/frame-delta.ts';
+import type { FrameDelta } from '../sim/frame-delta.ts';
+import { snapshot } from '../sim/view.ts';
+import type { Frame } from '../sim/view.ts';
+
+export type Push = {
+  frame: FrameDelta;
+  /** Non-null only for the seat that may currently act — never guess otherwise (`game.ts`'s `actionMenu` guards this too, but the host must still only compute/send it for the actor). */
+  menu: Menu | null;
+  /** Narration since the LAST push to this specific seat, not the whole game's log. */
+  lines: { text: string; tone: string }[];
+};
+
+/**
+ * `lobby-and-sessions.md` §5 — "wall-clock at the start of a turn, wall-clock at the intent that
+ * ends it, per player per phase." Computed entirely here, never touching the engine (which has no
+ * clock and must stay deterministic) and never stored inside `history` (a replay must reproduce a
+ * game from decisions alone).
+ */
+export type TurnTiming = {
+  player: PlayerIndex;
+  phase: string;
+  day: number;
+  stage: number;
+  startedAt: number;
+  endedAt: number;
+};
+
+/** Everything `persistence.ts` needs to write `game.json` and rebuild a session from it later. */
+export type SavedGame = {
+  seed: number;
+  config: GameConfig;
+  playerNames: string[];
+  history: Intent[];
+  status: 'active' | 'finished';
+  createdAt: number;
+};
+
+export type IntentResult =
+  | { accepted: true; pushes: Map<PlayerIndex, Push>; timing: TurnTiming | null }
+  | { accepted: false; code: string };
+
+export type GameSession = {
+  readonly playerCount: number;
+  /** A new SSE connection (or a reconnect) for `seat` — always a full Frame, never a delta. */
+  connect(seat: PlayerIndex): Push;
+  intent(seat: PlayerIndex, seq: number, i: Intent): IntentResult;
+  /** Everything needed to persist this game and, later, rebuild it via `resumeSession`. */
+  exportSave(): SavedGame;
+};
+
+type OpenSpan = { player: PlayerIndex; phase: string; day: number; stage: number; startedAt: number };
+
+function buildSession(game: Game, playerNames: string[], createdAt: number): GameSession {
+  const lastSeq = new Map<PlayerIndex, number>();
+  const lastFrame = new Map<PlayerIndex, Frame>();
+  const sentLines = new Map<PlayerIndex, number>();
+
+  const openSpanFor = (now: number): OpenSpan | null => {
+    const actor = currentActor(game);
+    if (actor === null) return null;
+    return { player: actor, phase: game.state.clock.phase, day: game.state.clock.day, stage: game.state.clock.stage, startedAt: now };
+  };
+  let open: OpenSpan | null = openSpanFor(Date.now());
+
+  function frameFor(seat: PlayerIndex): Frame {
+    return snapshot(game.state, game.log, null, null, null, false, seat);
+  }
+
+  function linesSince(seat: PlayerIndex): { text: string; tone: string }[] {
+    const already = sentLines.get(seat) ?? 0;
+    sentLines.set(seat, game.log.length);
+    return game.log.slice(already);
+  }
+
+  function menuFor(seat: PlayerIndex): Menu | null {
+    return seat === currentActor(game) ? actionMenu(game, seat) : null;
+  }
+
+  function pushFor(seat: PlayerIndex): Push {
+    const frame = frameFor(seat);
+    const delta = deltaFrame(lastFrame.get(seat) ?? null, frame);
+    lastFrame.set(seat, frame);
+    return { frame: delta, menu: menuFor(seat), lines: linesSince(seat) };
+  }
+
+  function pushesForAll(): Map<PlayerIndex, Push> {
+    const out = new Map<PlayerIndex, Push>();
+    for (let seat = 0; seat < playerNames.length; seat++) out.set(seat as PlayerIndex, pushFor(seat as PlayerIndex));
+    return out;
+  }
+
+  /**
+   * Closes the open span if the acting player, phase, Day or Stage moved since it opened, and opens
+   * the next one (or none, in the automatic Mainline Phase). Returns the just-closed span, if any,
+   * for the caller to persist — a "turn" here is exactly the contiguous stretch where none of those
+   * four things changed, which can span several intents (draw, then play, then end) as one span.
+   */
+  function settleTiming(): TurnTiming | null {
+    const now = Date.now();
+    const next = openSpanFor(now);
+    const same =
+      open !== null &&
+      next !== null &&
+      open.player === next.player &&
+      open.phase === next.phase &&
+      open.day === next.day &&
+      open.stage === next.stage;
+    if (same) return null;
+    const closed: TurnTiming | null = open === null ? null : { ...open, endedAt: now };
+    open = next;
+    return closed;
+  }
+
+  return {
+    playerCount: playerNames.length,
+
+    connect(seat) {
+      // A (re)connect always starts from a clean slate — no cache to trust across a lost connection
+      // (or a server restart, Phase 3) — so the honest thing is a full Frame, not a delta.
+      lastFrame.delete(seat);
+      return pushFor(seat);
+    },
+
+    intent(seat, seq, i) {
+      // Idempotent resend (protocol.md §5): a repeat of an ALREADY-APPLIED seq is a no-op success,
+      // with no pushes to re-broadcast. A repeat after a REJECTION is not remembered here — it was
+      // never applied, so it is worth trying again (see the `lastSeq.set` below: only on success).
+      if (lastSeq.get(seat) === seq) return { accepted: true, pushes: new Map(), timing: null };
+
+      if (seat !== currentActor(game)) return { accepted: false, code: 'NOT_YOUR_TURN' };
+
+      // Checked directly, rather than via `submit`'s boolean, for two reasons: `submit` writes a
+      // "that is not allowed" line into the SHARED `game.log` on rejection, which would otherwise
+      // broadcast one seat's illegal attempt to the whole table on their next push (rejection
+      // feedback is private, to the submitter only); and calling `check` first means an intent
+      // already known to be illegal never touches the engine at all.
+      const code = check(game.state, seat, i);
+      if (code) return { accepted: false, code };
+
+      const applied = submit(game, i);
+      /* c8 ignore next -- `check` above already proved this intent is legal; `submit` cannot then refuse it. */
+      if (!applied) return { accepted: false, code: 'REJECTED' };
+
+      lastSeq.set(seat, seq);
+      const timing = settleTiming();
+      return { accepted: true, pushes: pushesForAll(), timing };
+    },
+
+    exportSave() {
+      return {
+        seed: game.seed,
+        config: game.state.config,
+        playerNames: [...playerNames],
+        history: [...game.history],
+        status: game.state.status === 'finished' ? 'finished' : 'active',
+        createdAt,
+      };
+    },
+  };
+}
+
+export function createSession(seed: number, config: GameConfig, playerNames: string[]): GameSession {
+  return buildSession(newMultiplayerGame(seed, config, playerNames), playerNames, Date.now());
+}
+
+/**
+ * Phase 3 — rebuild a session from a persisted `SavedGame` (`persistence.ts`). The engine-version
+ * check happens before this is ever called; by the time `saved.history` reaches here it is already
+ * known to have been recorded under the currently-running rules.
+ */
+export function resumeSession(saved: SavedGame): GameSession {
+  const game = fromMultiplayerSave(saved.seed, saved.config, saved.playerNames, saved.history);
+  return buildSession(game, saved.playerNames, saved.createdAt);
+}