Initial Commit

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

@@ -0,0 +1,79 @@
+# Tasks: Wave B-3 game-server state
+
+## 0. Pre-flight
+
+- [x] `pwd && git worktree list && git status` — confirm isolated worktree, clean baseline.
+- [x] Read `CLAUDE.md`, `openspec/AGENTS.md`, existing `src/core`, `src/errors`, `src/types`, `src/engine/di-container`.
+- [x] Read upstream reference: `/mnt/s/web/suaveplan/packages/universal/game-server/src/state/{StateManager,StateDiffer,DeltaCompressor,StateSync}.ts`.
+
+## 1. Error registry
+
+- [x] Add six codes to `GAME_SERVER_CODES` (`STATE_DIFF_FAILED`,
+  `STATE_PATCH_FAILED`, `STATE_RESTORE_FAILED`, `INVALID_SNAPSHOT`,
+  `STATE_DECOMPRESS_FAILED`, `STATE_SYNC_TRANSPORT_FAILED`).
+- [x] Extend `game-server-error.test.ts` with assertions on the six new codes.
+- [x] Update `game-server-error.md` to enumerate the new codes.
+
+## 2. `state-differ`
+
+- [x] `state-differ.types.ts` — `DiffOperation`, `StateDelta`, Zod schemas.
+- [x] `state-differ.ts` — `diff`/`patch`/`isEmpty`/`mergeDeltas`,
+  injectable `Clock`, typed errors.
+- [x] `state-differ.test.ts` — 100% coverage incl. round-trip,
+  nested arrays, class-instance opaqueness, typed-error paths.
+- [x] `state-differ.md` — six sections, ≥ 200 words.
+- [x] `index.ts` barrel.
+
+## 3. `delta-compressor`
+
+- [x] `delta-compressor.types.ts` — `CompressedDelta`, `CompressionStats`,
+  Zod payload schema, `COMPRESSED_DELTA_VERSION`.
+- [x] `delta-compressor.ts` — `compress`/`compressSelective`/`decompress`/
+  `batchCompress`/`estimateSavings`, three OTel instruments.
+- [x] `delta-compressor.test.ts` — 100% coverage incl. version-mismatch,
+  malformed JSON, schema-invalid payload, selective-prefix matching,
+  divide-by-zero guard.
+- [x] `delta-compressor.md` — six sections, ≥ 200 words.
+- [x] `index.ts` barrel.
+
+## 4. `state-manager`
+
+- [x] `state-manager.types.ts` — `StateChangeEvent`, `StateChangeListener`,
+  `StateManagerStats`.
+- [x] `state-manager.ts` — full API with deep-frozen reads, bounded
+  history, injectable `Clock`/`IdGenerator`, three OTel instruments,
+  typed `restore` validator path.
+- [x] `state-manager.test.ts` — 100% coverage incl. listener isolation,
+  history trim, typed-error restore, default ID/clock fallback.
+- [x] `state-manager.md` — six sections, ≥ 200 words.
+- [x] `index.ts` barrel.
+
+## 5. `state-sync`
+
+- [x] `state-sync.types.ts` — `StateSyncMessage` discriminated union,
+  `StateSyncTransport`, `SyncStats`, `StateSyncConfig`.
+- [x] `state-sync.ts` — `sync`/`syncFull`/`requestFullSync`/`getStats`/
+  `resetStats`/`dispose`, automatic full-snapshot fallback, three OTel
+  instruments.
+- [x] `state-sync.test.ts` — 100% coverage with in-process
+  `StateSyncTransport`, includes transport-error wrapping, malformed
+  full-payload, request/full handshake.
+- [x] `state-sync.md` — six sections, ≥ 200 words.
+- [x] `index.ts` barrel.
+
+## 6. Package wiring
+
+- [x] Extend `package.json` exports with four new subpaths.
+- [x] Leave `src/index.ts` untouched (orchestrator wave consolidates).
+
+## 7. Verification gates
+
+- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/game-server` — green.
+- [ ] `bunx turbo test:coverage --filter=@suaveplan/game-server` — 100/100/100/100.
+- [ ] `grep -rnE "from ['\"](vitest|bun:test)['\"]" packages/gaming/games/game-server/src/` — empty.
+- [ ] `grep -rn "biome-ignore\|TODO\|FIXME\|XXX" packages/gaming/games/game-server/src/` — empty.
+
+## 8. Ship
+
+- [ ] Single commit on `worktree-agent-*` branch with the message specified
+  in the brief. No push, no `--no-verify`.