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

Wave B-5b: @suaveplan/game-server performance 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. Five parallel waves now extend the package along orthogonal axes; B-5 owns the matchmaking + performance axis. This change covers the performance half; a sibling change (game-server-matchmaking) covers queue / matcher / spectator / engine.

The upstream reference (/mnt/s/web/suaveplan/packages/universal/game-server/src/performance/) ships three modules — ObjectPool, SessionPool, NetworkTierAdapter — but couples them to upstream-only types (Logger, GameEventEmitter, SessionNodeImpl) and lacks typed-error / Zod-validated boundaries. This slice ports the algorithms, replaces the upstream couplings with @suaveplan/types (Clock) plus typed observer callbacks, and adds OTel-native instrumentation across all three modules.

What changes

• ADDED: src/performance/object-pool/ — generic typed object pool with factory + reset + optional dispose; configurable initialSize/maxSize/preAllocate; acquire / release / withObject / clear / dispose / getStats; two OTel counters; typed-error boundary (POOL_EXHAUSTED, POOL_DISPOSED, RELEASE_FOREIGN_OBJECT, INVALID_POOL_CONFIG).
• ADDED: src/performance/session-pool/ — session-specific wrapper over ObjectPool that pools plain-data PooledSession records (id, type, metadata, children[]); injectable Clock; acquireSession/releaseSession/withSession/getStats.
• ADDED: src/performance/network-tier-adapter/ — bridge between the game-server's matchmaking layer and the @suaveplan/network tier model; registerNodeCapabilities / getOptimalTier / getLoadBalancingRecommendations / validateTierCapacity / getStats; one OTel counter; typed-error boundary (INVALID_TIER_CONFIG, UNKNOWN_TIER); optional onCapabilityUpdated listener.

Impact

• Affected specs: openspec/specs/game-server/spec.md (game-server capability).
• New error codes: POOL_EXHAUSTED, POOL_DISPOSED, RELEASE_FOREIGN_OBJECT, INVALID_POOL_CONFIG, INVALID_TIER_CONFIG, UNKNOWN_TIER.
• New subpath exports: ./performance/{object-pool, session-pool, network-tier-adapter}.
• No core/ / state/ / engine/ / network/ modifications.