# Wave B-5a: `@suaveplan/game-server` matchmaking slice

**Package**: `@suaveplan/game-server`
**Status**: PROPOSED
**Type**: feature-add (additive to existing 0.1.0 package)

## Why

Wave A landed the `@suaveplan/game-server` core foundation (DI
container, error registry, Zod-validated boundary types). Five parallel
waves now extend the package along orthogonal axes; B-5 owns the
**matchmaking + performance** axis. This change covers the matchmaking
half; a sibling change (`game-server-performance`) covers pooling and
network-tier adapter.

The upstream reference
(`/mnt/s/web/suaveplan/packages/universal/game-server/src/matchmaking/`)
ships five modules — `MatchmakingEngine`, `QueueManager`,
`SpectatorManager`, `skill-matcher`, `winner-stays-on` — but couples
them to upstream-only types (`Logger`, `GameEventEmitter`,
`AbstractStorage`) and emits events that do not appear in the genesis
`GameEvents` map. This slice ports the algorithms, replaces the
upstream couplings with `@suaveplan/types` (`Clock`, `IdGenerator`,
`Rng`) plus typed observer callbacks, and adds OTel-native
instrumentation that the upstream lacked.

## What changes

- ADDED: `src/matchmaking/queue-manager/` — priority-queue manager with
  premium / wait-time / explicit-offset priority math, configurable
  `maxQueueSize`, four OTel instruments, Zod-validated boundary, typed
  `MATCHMAKING_QUEUE_FULL` / `INVALID_QUEUE_REQUEST` errors.
- ADDED: `src/matchmaking/skill-matcher/` — Elo-style matcher with
  pluggable scoring fn, base + wait-time range, injectable `Clock` and
  `Rng`, two OTel instruments.
- ADDED: `src/matchmaking/spectator-manager/` — per-session spectator
  roster with cap enforcement, three OTel counters, Zod-validated
  permissions, `onSpectatorJoined` / `onSpectatorLeft` callbacks.
- ADDED: `src/matchmaking/winner-stays-on/` — winner-stays-on strategy
  with champion / streak / challenger-queue tracking, two OTel
  counters, configurable streak cap.
- ADDED: `src/matchmaking/matchmaking-engine/` — top-level façade
  composing the above; `createMatch(players, criteria, algorithm)` +
  `createMatchFromQueue(queueKey, criteria, algorithm)` (drain + match
  + restore on shortfall); `quick` and `skill-based` algorithms;
  injectable `IdGenerator`; three OTel instruments.

## Impact

- Affected specs: `openspec/specs/game-server/spec.md` (game-server
  capability).
- New error codes: `MATCHMAKING_QUEUE_FULL`, `INVALID_QUEUE_REQUEST`,
  `INVALID_MATCH_CRITERIA`, `NO_MATCH_FOUND`, `INVALID_SKILL_SCORE`,
  `SPECTATOR_LIMIT_REACHED`, `INVALID_SPECTATOR_REQUEST`,
  `UNKNOWN_MATCHING_ALGORITHM`.
- New subpath exports: `./matchmaking/{queue-manager, skill-matcher,
  spectator-manager, winner-stays-on, matchmaking-engine}`.
- No `core/` / `state/` / `engine/` / `network/` modifications.