Initial Commit

openspec/archive/2026-05-24-game-server-enhanced-content/proposal.md

@@ -0,0 +1,79 @@
+# Wave C-3: `@suaveplan/game-server` enhanced content slice
+
+**Package**: `@suaveplan/game-server`
+**Status**: PROPOSED
+**Type**: feature-add (additive to existing 0.1.0 package)
+
+## Why
+
+Waves A and B landed the core foundation, engine, sessions, state,
+networking, matchmaking, and performance subsystems of
+`@suaveplan/game-server`. Wave C extends the package along the content
+axis with the four subsystems game operators consume directly:
+leaderboards, save persistence, replay capture, and tournament brackets.
+
+The upstream reference
+(`/mnt/s/web/suaveplan/packages/universal/game-server/src/enhanced/`)
+ships these as `EventEmitter`-backed managers coupled to upstream `Date.now`
+calls, hand-rolled id generators, and an upstream-specific `StorageAdapter`
+contract. This slice ports the algorithms, replaces the couplings with the
+genesis-canonical `Clock`, `IdGenerator`, `Rng`, and `StorageLike`
+abstractions from `@suaveplan/types`, and adds Zod-validated boundaries +
+OTel-native instrumentation that the upstream lacked.
+
+## What changes
+
+- ADDED: `src/enhanced/leaderboard/leaderboard-manager/` — multi-board
+  manager with `score` / `wins` / `elo` ranking modes, per-board
+  `maxEntries` rank-based eviction, injectable `Clock`, two OTel
+  counters, four typed errors (`LEADERBOARD_NOT_FOUND`,
+  `LEADERBOARD_ENTRY_INVALID`, `INVALID_LEADERBOARD_CONFIG`,
+  `INVALID_SCORE_SUBMISSION`).
+- ADDED: `src/enhanced/persistence/game-persistence/` — JSON-over-`StorageLike`
+  save manager with bounded snapshots and audit-trail history, injectable
+  `Clock` + `IdGenerator`, two OTel counters + duration histogram, four
+  typed errors (`PERSISTENCE_SAVE_FAILED`, `PERSISTENCE_LOAD_FAILED`,
+  `PERSISTENCE_NOT_FOUND`, `INVALID_SAVE_RECORD`).
+- ADDED: `src/enhanced/replay/replay-recorder/` — tick-driven input +
+  snapshot recorder with pause/resume, configurable auto-snapshot
+  interval, capped input buffer, injectable `Clock` + `IdGenerator`,
+  two OTel counters, four typed errors (`REPLAY_NOT_LOADED`,
+  `REPLAY_PARSE_FAILED`, `REPLAY_RECORDING_STATE_INVALID`,
+  `REPLAY_INVALID_SPEED`).
+- ADDED: `src/enhanced/replay/replay-player/` — tick-driven replay player
+  with step/seek/speed controls, snapshot-aware backward step, loop
+  mode, observer-style listeners, two OTel counters.
+- ADDED: `src/enhanced/tournament/tournament-manager/` — single-elim +
+  round-robin brackets with bye propagation, deterministic seeded
+  shuffling via injectable `Rng`, standings table with stable tie-break,
+  one OTel counter (tagged), eight typed errors
+  (`TOURNAMENT_INVALID_STATE`, `TOURNAMENT_FULL`,
+  `TOURNAMENT_DUPLICATE_PARTICIPANT`,
+  `TOURNAMENT_INSUFFICIENT_PARTICIPANTS`, `TOURNAMENT_MATCH_NOT_FOUND`,
+  `TOURNAMENT_INVALID_RESULT`, `INVALID_BRACKET_SIZE`,
+  `INVALID_BRACKET_TYPE`).
+- ADDED: 22 new `GAME_SERVER.*` error codes registered in `defineCodes`.
+- ADDED: five `package.json` subpath exports.
+
+## Out of scope
+
+- Double-elimination brackets — not requested by the dispatch spec and
+  excluded to keep the manager under the 300-line hard limit. Can be
+  added later as a sibling change without touching the public surface.
+- Wire serialisation (Replay export/compression, persistence CDC) —
+  caller-side concern; the `ReplayData` document is JSON-clean.
+- React companion hooks — separate package (`@suaveplan/react-game-server`).
+
+## Risks
+
+- None new. All five subsystems are leaf modules that consume only the
+  existing `errors/` + `types/` foundations plus the `@suaveplan/types`
+  cross-cutting contracts.
+
+## Verification
+
+- `bunx turbo lint typecheck test --filter=@suaveplan/game-server` green.
+- `bunx turbo test:coverage --filter=@suaveplan/game-server` at 100/100/100/100.
+- Zero `vitest`/`bun:test` direct imports under
+  `src/enhanced/`.
+- Zero `// biome-ignore`, `TODO`, `FIXME`, `XXX` under `src/enhanced/`.