suaveplan/openspec/changes/enterprise-game-server-core/proposal.md

Enterprise migration: @suaveplan/game-server (core slice)

Package: @suaveplan/game-server Status: PROPOSED Type: new-package

Why

@suaveplan/game-server on the reference branch claude/review-game-engine-arch-Kaykr (main repo packages/universal/game-server/) is a 192-file framework with session lifecycle, plugin chain, networking, state-sync, matchmaking, and an "enhanced" variant (anti-cheat / lag-compensation / interest management / replay / tournament / persistence / leaderboard / state-sync / timing). The branch's last commit (2fb25cdb35) made the engine generic by removing all game-specific adapters (bingo / tic-tac-toe / gem-crush).

Genesis needs that engine, but porting all 192 files in one slice would either skip the genesis quality gates (100% test coverage, sibling .md per .ts, kebab-case + 5-file layout, typed errors, Zod boundaries, OTel) or land partially-built code. Six required workspace dependencies (controller, keys, network-webrtc, network-websockets, storage-browser, workflow) do not yet exist on genesis, blocking the network/, plugins/, and parts of state/.

This change ships the dependency-light foundation that every later slice depends on, behind the @suaveplan/game-server name at 0.1.0, and documents the remaining scope as explicitly deferred follow-on changes. The package is fully usable today by downstream code that wants typed errors, Zod-validated boundary types, or the DI container.

What changes

• ADDED: @suaveplan/game-server package at packages/gaming/games/game-server/ (universal tier, sideEffects: false, version 0.1.0).
• ADDED: GameServerError + GAME_SERVER_CODES registry via defineCodes — four initial codes: SERVICE_NOT_REGISTERED, INVALID_GAME_CONFIG, INVALID_SESSION_METADATA, INVALID_PLAYER_INFO.
• ADDED: GameConfig, SessionMetadata, PlayerInfo, MoveValidationResult, GameResult, SessionType, DeepReadonly with Zod schemas (GameConfigSchema, SessionMetadataSchema, PlayerInfoSchema, MoveValidationResultSchema, GameResultSchema, SessionTypeSchema) and validators (parseGameConfig, parseSessionMetadata, parsePlayerInfo, tryParseMoveValidationResult, tryParseGameResult).
• ADDED: DIContainer with singleton/transient lifecycles, typed error on miss, and re-register-invalidates-cache semantics (genesis improvement over upstream).
• ADDED: Subpath exports ./errors, ./types, ./engine/di-container for tree-shaking.

Out of scope (deferred)

Surface area	Why deferred	Follow-up change
core/{AbstractGameLogic, interfaces/*, events/*}	Each contract file needs its own 5-file layout + tests + docs; bundling all of them in one slice would force this PR over 30 files.	enterprise-game-server-core-contracts
engine/{GameEngine 487, GameLoop 355, PlayerManager 345, PluginManager 340, SessionLifecycle 295, SessionNode 173, SessionStore 128, SessionTree 429}	Six of eight files exceed the 300-line genesis hard limit and require splitting. Each needs Zod boundary schemas, OTel instruments, typed GAME_SERVER.* codes, 100% coverage, ≥200-word sibling .md.	enterprise-game-server-engine
state/{DeltaCompressor 221, StateDiffer 280, StateManager 316, StateSync 375}	StateManager and StateSync exceed the 300-line limit; StateSync also reaches into networking which is blocked.	enterprise-game-server-state
matchmaking/{MatchmakingEngine 152, QueueManager 169, SpectatorManager 122, skill-matcher 40, winner-stays-on 56}	Dependency-clean but still requires the engine/state slices to be useful end-to-end.	enterprise-game-server-matchmaking
performance/{NetworkTierAdapter, ObjectPool, SessionPool} → telemetry/	Folds into engine slice (SessionPool consumes Session from engine).	enterprise-game-server-engine
network/{NetworkAdapter, ReconnectionManager, WebRTCTransport, WebSocketTransport}	BLOCKED on missing genesis deps @suaveplan/network-webrtc and @suaveplan/network-websockets.	After transport packages land.
plugins/{ABTest, Analytics, BasePlugin, FeatureFlag, Logging, Persistence, Rules, Workflow}	BLOCKED on missing genesis deps @suaveplan/workflow and @suaveplan/keys.	After workflow/keys packages land.
enhanced/ (73 files: anti-cheat, components, interest-management, lag-compensation, leaderboard, persistence, replay, service-discovery, state-sync, timing, tournament)	Priority 2 per migration brief; the enhanced variant sits above a stable engine. Several enhanced features have transitive deps on the blocked packages.	enterprise-game-server-enhanced
integrations/components/game-lobby/*	Priority 3 — React-coupled UI that belongs in a react-game-lobby package, not a universal-tier engine.	enterprise-react-game-lobby
integrations/enhanced-server/*	Bundles every enhanced feature; depends on enterprise-game-server-enhanced.	enterprise-game-server-enhanced
stories/*, e2e/*, benchmarks/*	Storybook/Playwright/bench tooling lands with the surfaces they exercise.	per-slice.

Source mapping

This change derives from ../suaveplan/enterprise/game-server.md (not present in the worktree's parent repo — the reference is the branch claude/review-game-engine-arch-Kaykr itself, since the package was under active redesign).

Requirement	Source lines	Notes
Typed error registry GAME_SERVER.*	src/engine/DIContainer.ts:30 (only throw site in the migrated slice; upstream used plain Error)	reworded — typed error replaces plain throw.
GameConfig/SessionMetadata/PlayerInfo/MoveValidationResult/GameResult types	src/core/types/index.ts:1-47	extended — added Zod schemas + validators (no source line).
DIContainer singleton/transient resolver	src/engine/DIContainer.ts:1-61	extended — re-register-invalidates-cache is new in genesis.

Requirements with no source line

Requirement	Justification
Zod schemas for every boundary type	Genesis rule: every public boundary is Zod-validated.
Typed GameServerError instead of plain Error	Genesis rule: every package throws via its own defineCodes registry.
readonly modifiers on every interface field	Genesis lint profile rejects Record<string, any> and prefers immutable shapes.
Re-register-invalidates-cache on DIContainer	Bug-class fix: upstream silently kept stale singletons after re-register.

Verification approach

• src/errors/game-server-error.test.ts — registry shape, error construction, code discrimination.
• src/types/common.test.ts — every schema accept-path, reject-path, and validator throw-path with the matching code.
• src/engine/di-container/di-container.test.ts — singleton, transient, symbol identifiers, fluent chaining, miss-throws-typed-error, has/unregister/clear/getRegisteredServices, re-register cache invalidation.

Migration impact

None — additive only. No consumer on genesis currently imports @suaveplan/game-server.