Initial Commit

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

@@ -0,0 +1,55 @@
+# 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.