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.

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

@@ -0,0 +1,48 @@
+# Spec Delta — game-server / integrations capability
+
+## ADDED Requirements
+
+### Requirement: EnhancedGameServer top-of-stack bootstrap
+
+The `@suaveplan/game-server` package SHALL expose an `EnhancedGameServer`
+class under the `./integrations/enhanced-server` subpath export that
+bootstraps the canonical engine + plugin stack via a single
+`bootstrap(options)` entry point.
+
+#### Scenario: Bootstrap installs all eight plugins
+
+- **WHEN** `bootstrap()` is invoked with valid options
+- **THEN** a `GameLoop`, `PluginManager`, and `GameEngine` SHALL be
+  constructed and wired
+- **AND** all eight built-in plugins (`ABTestPlugin`, `AnalyticsPlugin`,
+  `FeatureFlagPlugin`, `LoggingPlugin`, `PersistencePlugin`, `RulesPlugin`,
+  `WorkflowPlugin`, and one further reserved slot satisfied by
+  `BasePlugin` derivatives) SHALL be installed in dependency order via
+  `PluginManager.installAll`
+- **AND** the `GameEngine` SHALL be returned ready to `start()`.
+
+#### Scenario: Double bootstrap rejected
+
+- **WHEN** `bootstrap()` is invoked twice on the same `EnhancedGameServer`
+- **THEN** the second call SHALL throw `GameServerError` with code
+  `GAME_SERVER.ALREADY_BOOTSTRAPPED`.
+
+#### Scenario: Plugin install failure rolls back
+
+- **WHEN** any plugin install fails during `bootstrap()`
+- **THEN** the failure SHALL be wrapped as `GameServerError` with code
+  `GAME_SERVER.BOOTSTRAP_FAILED`
+- **AND** the underlying `cause` SHALL be the original error.
+
+#### Scenario: Lifecycle deferral
+
+- **WHEN** the caller invokes `start()` / `tick()` / `stop()` / `dispose()`
+- **THEN** the `EnhancedGameServer` SHALL delegate to the underlying
+  `GameEngine` so existing engine lifecycle codes propagate unchanged.
+
+#### Scenario: Injected dependencies are honoured
+
+- **WHEN** `bootstrap(options)` is invoked
+- **THEN** every plugin SHALL receive the injected `Clock` and
+  `LoggerLike` so deterministic tests observe stable timestamps and
+  captured logs.

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

@@ -0,0 +1,18 @@
+# Tasks — game-server integrations (Wave C-5)
+
+## Implementation
+
+- [x] Author `src/integrations/enhanced-server/enhanced-server.ts`
+- [x] Author `src/integrations/enhanced-server/enhanced-server.types.ts`
+- [x] Author `src/integrations/enhanced-server/enhanced-server.md`
+- [x] Author `src/integrations/enhanced-server/index.ts`
+- [x] Append `BOOTSTRAP_FAILED` + `ALREADY_BOOTSTRAPPED` to `defineCodes`
+- [x] Add `./integrations/enhanced-server` subpath export
+
+## Verification
+
+- [x] `bunx turbo lint typecheck test --filter=@suaveplan/game-server` green
+- [x] `bunx turbo test:coverage --filter=@suaveplan/game-server` 100/100/100/100
+- [x] Zero `vitest`/`bun:test` direct imports in `src/`
+- [x] Zero biome-ignore/TODO/FIXME/XXX in `src/`
+- [x] Integration tests bootstrap real plugins (no mocks)