# 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.