suaveplan/openspec/archive/2026-05-24-game-server-state/proposal.md

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.