Initial Commit

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

@@ -0,0 +1,58 @@
+# 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.