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

Tasks: Wave B-3 game-server state

0. Pre-flight

• pwd && git worktree list && git status — confirm isolated worktree, clean baseline.
• Read CLAUDE.md, openspec/AGENTS.md, existing src/core, src/errors, src/types, src/engine/di-container.
• Read upstream reference: /mnt/s/web/suaveplan/packages/universal/game-server/src/state/{StateManager,StateDiffer,DeltaCompressor,StateSync}.ts.

1. Error registry

• 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).
• Extend game-server-error.test.ts with assertions on the six new codes.
• Update game-server-error.md to enumerate the new codes.

2. state-differ

• state-differ.types.ts — DiffOperation, StateDelta, Zod schemas.
• state-differ.ts — diff/patch/isEmpty/mergeDeltas, injectable Clock, typed errors.
• state-differ.test.ts — 100% coverage incl. round-trip, nested arrays, class-instance opaqueness, typed-error paths.
• state-differ.md — six sections, ≥ 200 words.
• index.ts barrel.

3. delta-compressor

• delta-compressor.types.ts — CompressedDelta, CompressionStats, Zod payload schema, COMPRESSED_DELTA_VERSION.
• delta-compressor.ts — compress/compressSelective/decompress/ batchCompress/estimateSavings, three OTel instruments.
• delta-compressor.test.ts — 100% coverage incl. version-mismatch, malformed JSON, schema-invalid payload, selective-prefix matching, divide-by-zero guard.
• delta-compressor.md — six sections, ≥ 200 words.
• index.ts barrel.

4. state-manager

• state-manager.types.ts — StateChangeEvent, StateChangeListener, StateManagerStats.
• state-manager.ts — full API with deep-frozen reads, bounded history, injectable Clock/IdGenerator, three OTel instruments, typed restore validator path.
• state-manager.test.ts — 100% coverage incl. listener isolation, history trim, typed-error restore, default ID/clock fallback.
• state-manager.md — six sections, ≥ 200 words.
• index.ts barrel.

5. state-sync

• state-sync.types.ts — StateSyncMessage discriminated union, StateSyncTransport, SyncStats, StateSyncConfig.
• state-sync.ts — sync/syncFull/requestFullSync/getStats/ resetStats/dispose, automatic full-snapshot fallback, three OTel instruments.
• state-sync.test.ts — 100% coverage with in-process StateSyncTransport, includes transport-error wrapping, malformed full-payload, request/full handshake.
• state-sync.md — six sections, ≥ 200 words.
• index.ts barrel.

6. Package wiring

• Extend package.json exports with four new subpaths.
• 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.