# Migration: `@suaveplan/game-server` network slice (Wave B-4)

**Package**: `@suaveplan/game-server`
**Status**: PROPOSED
**Type**: extends-package

## Why

`@suaveplan/game-server` shipped its core slice (errors, types,
di-container) on Wave A. The network module is one of the four parallel
B-wave slices that bring the package up to the broader reference surface
from `claude/review-game-engine-arch-Kaykr`. Without a unified
`NetworkAdapter` + reconnection driver + WebSocket/WebRTC transports,
downstream session and matchmaking modules (Waves B-1…B-3, B-5) cannot
wire to a transport at all — they all consume the `Transport` contract
defined here.

The reference branch's network module (`network/NetworkAdapter.ts`,
`ReconnectionManager.ts`, `WebSocketTransport.ts`, `WebRTCTransport.ts`)
mixes runtime concerns (raw `WebSocket` / `RTCPeerConnection`) with
framework concerns (event emitter, logger). Genesis splits those: the
unified adapter contract lives here, and the actual platform-tier
clients live in `@suaveplan/network-transport-websockets` and
`@suaveplan/network-transport-webrtc`. The wrappers in this slice are
the thin glue layer that bridges those two worlds via a structural
boundary so tests can use in-process fakes instead of real sockets.

## What changes

- ADDED: `src/network/network-adapter/` — unified `NetworkAdapter` class
  with single-init guard, Zod boundary validation, multi-subscriber
  fan-out, isolated handler errors, OTel counters
  (`game_server.network.messages_sent_total`,
  `…messages_received_total`, `…errors_total`).
- ADDED: `src/network/reconnection-manager/` — exponential-backoff
  reconnection driver via `@suaveplan/retry`'s
  `createExponentialBackoff` + `applyJitter`, injectable
  `Clock` + `TimersLike`, OTel counter + histogram
  (`reconnect_attempts_total`, `reconnect_delay_ms`).
- ADDED: `src/network/websocket-transport/` — thin wrapper implementing
  `Transport` over a structural `UnderlyingWebSocket` boundary.
- ADDED: `src/network/webrtc-transport/` — thin wrapper implementing
  `Transport` over a structural `UnderlyingWebRTC` boundary, plus
  pass-through helpers (`addIceCandidate`, `applyAnswer`).
- ADDED: Six new `GAME_SERVER.*` error codes:
  `TRANSPORT_ALREADY_INITIALIZED`, `TRANSPORT_NOT_INITIALIZED`,
  `TRANSPORT_NOT_CONNECTED`, `INVALID_MESSAGE_FORMAT`,
  `RECONNECT_EXHAUSTED`, `RECONNECT_IN_PROGRESS`.
- ADDED: Subpath exports `./network/network-adapter`,
  `./network/reconnection-manager`, `./network/websocket-transport`,
  `./network/webrtc-transport`.
- ADDED: Workspace deps `@suaveplan/network-transport-websockets`,
  `@suaveplan/network-transport-webrtc`, `@suaveplan/retry`.

## Out of scope (deferred to later waves)

None. Network slice ships at full functional completeness for the
`NetworkAdapter` + Reconnection + WebSocket + WebRTC contract pair.
Real-world wiring of the underlying clients to the genesis transport
packages is a downstream concern in each application; the wrappers
themselves are complete.

### Affected dependents

- Downstream session and matchmaking slices (B-1, B-2, B-3, B-5)
  consume `Transport` and `NetworkAdapter` exclusively through their
  exported names; no additional change needed.

## Source mapping

| Genesis path | Upstream reference |
|---|---|
| `src/network/network-adapter/network-adapter.ts` | `packages/universal/game-server/src/network/NetworkAdapter.ts` (full rewrite into structural `Transport` contract, Zod boundary, OTel) |
| `src/network/reconnection-manager/reconnection-manager.ts` | `packages/universal/game-server/src/network/ReconnectionManager.ts` (rewritten to consume `@suaveplan/retry`; storage persistence dropped — handled by a future state slice) |
| `src/network/websocket-transport/websocket-transport.ts` | `packages/universal/game-server/src/network/WebSocketTransport.ts` (wraps `UnderlyingWebSocket` structural client instead of raw `WebSocket`) |
| `src/network/webrtc-transport/webrtc-transport.ts` | `packages/universal/game-server/src/network/WebRTCTransport.ts` (wraps `UnderlyingWebRTC` structural client instead of raw `RTCPeerConnection`) |