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

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.