Initial Commit

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

@@ -0,0 +1,52 @@
+# Proposal — game-server integrations (Wave C-5)
+
+## Why
+
+Waves B and C-1 shipped the `GameEngine`, `PluginManager`, and eight
+concrete plugins. Consumers still have to wire them together by hand:
+construct the loop, the plugin manager, install every plugin, register
+them, and tear everything down on shutdown. Wave C-5 closes that gap with
+a single-entry-point `EnhancedGameServer` integration that bootstraps the
+canonical stack via one `bootstrap(options)` call.
+
+The integration is universal-tier (zero browser / React deps). React
+component shells from upstream (`game-lobby/`) are explicitly **deferred**
+to a future `react-game-server` package — they cannot live inside a
+universal-tier package.
+
+## What changes
+
+### ADDED `EnhancedGameServer`
+
+Top-of-stack orchestrator that:
+
+- Accepts injectable `Clock`, `IdGenerator`, `LoggerLike`, `TimersLike`,
+  `EventBusLike`, plus per-plugin external collaborators (FlagManager,
+  RuleEngine, StorageLike, AnalyticsSink, Rng, GameEventEmitter).
+- Constructs a `GameLoop`, `PluginManager`, and `GameEngine` in canonical
+  wiring order.
+- Pre-registers all eight plugins (`BasePlugin`-derived) in declared
+  install order, honouring the `topoSort` guarantee of `PluginManager`.
+- Surfaces `bootstrap(options)` as the single user-facing entry point.
+- Exposes `start()`, `tick()`, `stop()`, `dispose()` deferring to the
+  underlying `GameEngine`.
+- Throws `BOOTSTRAP_FAILED` if any plugin install fails, and
+  `ALREADY_BOOTSTRAPPED` on double-bootstrap.
+
+### ADDED error codes
+
+- `GAME_SERVER.BOOTSTRAP_FAILED`
+- `GAME_SERVER.ALREADY_BOOTSTRAPPED`
+
+### DEFERRED — `components/game-lobby/`
+
+The upstream React lobby component cannot ship in a universal-tier
+package. It will land in a follow-up `react-game-server` package and is
+out of scope for Wave C-5.
+
+## Impact
+
+- Affected packages: `@suaveplan/game-server`.
+- Affected specs: `game-server` (ADDED integrations capability).
+- Public surface: `./integrations/enhanced-server` subpath export only.
+- No breaking change — purely additive.