# game-server — Wave C-1 plugin layer

## ADDED Requirements

### Requirement: BasePlugin SHALL implement the EnginePlugin contract

`BasePlugin` is an abstract base class that implements the four lifecycle
hooks of `EnginePlugin` and forwards each to a `protected` template-method
hook subclasses override. Subclasses declare `name`, `version`, and an
optional `dependencies` array.

#### Scenario: invokes onInstallHook on install

- WHEN `BasePlugin.onInstall(ctx)` is awaited
- THEN the subclass's `onInstallHook(ctx)` runs first
- AND the plugin state transitions to `"installed"`
- AND `snapshot().installedAt` is set to `clock()`

**Verified by:** `it("invokes onInstallHook and transitions to 'installed'")`

#### Scenario: rejects any hook after destroy

- WHEN a plugin has reached `"destroyed"` (after `onUninstall`)
- AND `onInstall`/`onEnable`/`onDisable`/`onUninstall` is called again
- THEN the call rejects with `GAME_SERVER.PLUGIN_BASE_DESTROYED`

**Verified by:** `it("rejects any hook after destroy")`

#### Scenario: adopts context logger on install

- WHEN a `BasePlugin` is constructed without an explicit `logger`
- AND `onInstall(ctx)` runs
- THEN subsequent `this.logger` calls forward to `ctx.logger`

**Verified by:** `it("adopts the context logger on install when no override given")`

### Requirement: ABTestPlugin SHALL bucket players via injectable Rng

`ABTestPlugin` registers weighted experiments and assigns players to
variants by accumulating variant weights and comparing against
`rng.nextFloat() * totalWeight`. Assignment is idempotent per player.

#### Scenario: deterministic assignment with seeded Rng

- GIVEN a seeded `Rng`
- WHEN `assignPlayer(experimentId, playerId)` is called twice for the same
  `playerId`
- THEN both calls return the same `variantId`

**Verified by:** `it("assigns players to a variant deterministically and idempotently")`

#### Scenario: weighted distribution honoured

- GIVEN an experiment with two equal-weight variants
- WHEN `rng.nextFloat()` returns `0.0, 0.4, 0.6, 0.9` in sequence
- THEN the first two assignments land in variant `a` and the next two in `b`

**Verified by:** `it("assigns according to weighting")`

#### Scenario: missing experiment surfaces stable error code

- WHEN `assignPlayer` or `getSummary` is called for an unknown id
- THEN `GameServerError` with code
  `GAME_SERVER.AB_TEST_EXPERIMENT_NOT_FOUND` is thrown

**Verified by:** `it("requireExperiment throws on missing")`

### Requirement: AnalyticsPlugin SHALL subscribe via GameEventEmitter

`AnalyticsPlugin` subscribes to `session:created`, `session:destroyed`,
`game:started`, `game:ended`, `player:joined`, `player:left`, and
`move:processed` on install and routes structured `AnalyticsEvent` payloads
to an injectable sink.

#### Scenario: dispatches to sink on subscribed events

- WHEN `game:started` and `player:joined` are emitted
- THEN the sink receives `session:started` and `player:joined` analytics
  events with `timestamp = clock()`

**Verified by:** `it("subscribes to game events on install and dispatches to sink")`

#### Scenario: marks abandoned sessions

- WHEN a session is active for longer than `abandonAfterMs`
- THEN `getMetrics().sessionsAbandoned` is incremented

**Verified by:** `it("marks abandoned sessions")`

#### Scenario: unsubscribes on uninstall

- WHEN the plugin is uninstalled
- THEN subsequent emitter events are not delivered to the sink

**Verified by:** `it("unsubscribes on uninstall — emitter events stop reaching the plugin")`

### Requirement: FeatureFlagPlugin SHALL adapt FlagManager with per-player context

`FeatureFlagPlugin` wraps a `@suaveplan/feature-flags` `FlagManager` and
merges the per-call `playerId` into the evaluation context.

#### Scenario: per-player evaluation context

- WHEN `isEnabled("flag", "p1")` is called
- THEN the underlying `FlagManager.isEnabled` is invoked with a context
  whose `userId === "p1"`

**Verified by:** `it("evaluates a boolean flag via isEnabled")` and
`it("builds context with defaultContext merged")`

#### Scenario: rolling evaluation log

- WHEN evaluations exceed `maxLogEntries`
- THEN the oldest entries are dropped FIFO

**Verified by:** `it("records evaluations and trims to maxLogEntries")`

### Requirement: LoggingPlugin SHALL forward emitter events to a LoggerLike sink

`LoggingPlugin` subscribes to player, game, and session events (each
individually toggleable) and forwards them to a `LoggerLike` sink, also
retaining a bounded FIFO ring buffer.

#### Scenario: level mapping per event class

- WHEN `player:joined`, `move:rejected`, `move:processed`, and
  `game:started` are emitted
- THEN the buffer carries one `info`, one `warn`, one `debug`, and one
  `info` entry respectively

**Verified by:** `it("forwards game events including move levels")`

#### Scenario: ring buffer trims to maxEntries

- WHEN more than `maxEntries` events are emitted
- THEN the oldest entries are dropped

**Verified by:** `it("trims buffer to maxEntries")`

### Requirement: PersistencePlugin SHALL persist via StorageLike with Zod-validated load

`PersistencePlugin` writes per-session save records as UTF-8 JSON via
`StorageLike.set` and verifies records on `load` against a Zod schema.

#### Scenario: round-trip save → load

- WHEN a session is tracked via `game:started` + `game:state:changed`
- AND `save` is awaited then `load` is awaited
- THEN the loaded record reflects the accumulated state

**Verified by:** `it("manual save / load / delete round-trip")`

#### Scenario: corrupt record surfaces stable error code

- WHEN the stored bytes do not decode to valid JSON
- THEN `load` throws `GAME_SERVER.PERSISTENCE_LOAD_FAILED`

**Verified by:** `it("load throws on invalid JSON")` and
`it("load throws on schema mismatch")`

#### Scenario: auto-save errors do not propagate to the emitter

- GIVEN `saveOnGameEnd: true`
- WHEN the storage `set` call rejects
- THEN the error is logged and swallowed; the emitter continues to deliver
  subsequent events

**Verified by:** `it("auto-save swallows storage errors to keep emitter alive")`

### Requirement: RulesPlugin SHALL evaluate three named rule sets

`RulesPlugin` exposes `evaluateMove`, `evaluateGameStart`, and
`evaluateGameEnd`, each backed by an independent `Rule[]` slot. Empty
slots short-circuit and record a passing history entry.

#### Scenario: ad-hoc evaluate rejects non-object context

- WHEN `evaluate(rules, null)` is awaited
- THEN it rejects with `GAME_SERVER.INVALID_RULE_CONTEXT`

**Verified by:** `it("evaluate rejects non-object context")`

#### Scenario: history is bounded by historyCap

- WHEN more than `historyCap` evaluations are recorded
- THEN the history retains only the most recent `historyCap` entries

**Verified by:** `it("history is bounded by historyCap")`

### Requirement: WorkflowPlugin SHALL orchestrate registered engines

`WorkflowPlugin` keys `WorkflowEngine` instances by `id` and exposes
`execute` (run-and-record), `cancel` (defer to engine), and a rolling
history with `getHistory`/`clearHistory`.

#### Scenario: duplicate registration rejected

- WHEN `registerWorkflow` is called twice with the same id
- THEN the second call throws `GAME_SERVER.DUPLICATE_WORKFLOW`

**Verified by:** `it("rejects duplicate registration")`

#### Scenario: execute records failed status on rejected promise

- GIVEN an engine whose `run` rejects
- WHEN `execute(id, data)` is awaited
- THEN the history entry status is `"failed"` and `error` carries the
  message

**Verified by:** `it("execute records error on rejected promise")`

#### Scenario: cancel returns false when no execution is active

- WHEN `cancel(id)` is called with no in-flight execution
- THEN the call returns `false`

**Verified by:** `it("cancel returns true for active and false for absent")`