# 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/`.