Initial Commit

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

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