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

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")