56 lines
2.6 KiB
Markdown
56 lines
2.6 KiB
Markdown
# Wave B-3: `@suaveplan/game-server` state slice
|
|
|
|
**Package**: `@suaveplan/game-server`
|
|
**Status**: PROPOSED
|
|
**Type**: feature-add (additive to existing 0.1.0 package)
|
|
|
|
## Why
|
|
|
|
Wave A landed the `@suaveplan/game-server` core foundation (DI container,
|
|
error registry, Zod-validated boundary types). Five parallel waves now
|
|
extend the package along orthogonal axes; B-3 owns the **state** axis:
|
|
the observable in-memory game state plus the diff/compress/sync pipeline
|
|
that lets clients and servers exchange compact mutations over any
|
|
transport.
|
|
|
|
The upstream reference (`packages/universal/game-server/src/state/` on
|
|
`/mnt/s/web/suaveplan`) ships four modules — `StateManager`,
|
|
`StateDiffer`, `DeltaCompressor`, `StateSync` — but couples them to
|
|
upstream-only types (`Logger`, `GameEventEmitter`, `NetworkAdapter`)
|
|
that do not yet exist on genesis. This slice ports the algorithms,
|
|
replaces the upstream couplings with `@suaveplan/types` (`Clock`,
|
|
`IdGenerator`) plus a slim `StateSyncTransport` interface, and adds
|
|
OTel-native instrumentation that the upstream lacked.
|
|
|
|
## What changes
|
|
|
|
- ADDED: `src/state/state-manager/` — `StateManager<TState>` with
|
|
`getState`/`get`/`update`/`updateMany`/`setState`/`reset`/`restore`/
|
|
`subscribe`/history APIs. Deep-frozen reads. Bounded history.
|
|
Injectable `Clock` + `IdGenerator`. Three OTel instruments
|
|
(`mutation_total`, `listener_error_total`, `mutation_duration_ms`).
|
|
- ADDED: `src/state/state-differ/` — `StateDiffer.diff(a,b)`/`patch(s,d)`/
|
|
`isEmpty`/`mergeDeltas`. Three-op grammar (`add | remove | replace`).
|
|
Symmetric round-trip on plain JSON shapes.
|
|
- ADDED: `src/state/delta-compressor/` — `DeltaCompressor.compress`/
|
|
`compressSelective`/`batchCompress`/`decompress`/`estimateSavings`.
|
|
UTF-8 JSON payload, Zod-validated on receipt, versioned wire format.
|
|
Three OTel instruments.
|
|
- ADDED: `src/state/state-sync/` — `StateSync<TState>.sync`/`syncFull`/
|
|
`requestFullSync` over an injectable `StateSyncTransport`. Automatic
|
|
full-snapshot fallback when delta exceeds `maxDeltaSize`. Three OTel
|
|
instruments.
|
|
- MODIFIED: `errors/game-server-error.ts` — six new codes:
|
|
`STATE_DIFF_FAILED`, `STATE_PATCH_FAILED`, `STATE_RESTORE_FAILED`,
|
|
`INVALID_SNAPSHOT`, `STATE_DECOMPRESS_FAILED`,
|
|
`STATE_SYNC_TRANSPORT_FAILED`.
|
|
- MODIFIED: `package.json` — four new subpath exports
|
|
(`./state/state-manager`, `./state/state-differ`,
|
|
`./state/delta-compressor`, `./state/state-sync`).
|
|
|
|
## Out of scope (other waves)
|
|
|
|
- `src/network/` — Wave B-other (transport implementations).
|
|
- `src/engine/`, `src/core/` — Wave A.
|
|
- Top-level `src/index.ts` consolidation — orchestrator wave.
|