# OpenSpec Change: network-plugin-transport-manager

- **Change ID**: network-plugin-transport-manager
- **Package**: `@suaveplan/network-plugin-transport-manager` (new)
- **Status**: PROPOSED
- **Type**: new-package
- **Date**: 2026-04-29

## Why

A resilient network cannot rely on a single transport. WebRTC may fail behind symmetric NAT. WebSockets may drop on mobile network transitions. HTTP fallback may be needed for corporate firewalls. The current architecture has `network-plugin-webrtc` and mentions `network-plugin-websocket` but provides no mechanism to use them simultaneously, fail over between them intelligently, or select transports based on message priority and peer capabilities. This plugin provides **multi-transport orchestration**: simultaneous active transports, round-robin load distribution, priority-based routing, capability negotiation, and automatic degradation/recovery.

## What changes

- **ADDED**: `TransportManagerPlugin` class implementing `NetworkPlugin`.
- **ADDED**: `TransportPool` — maintains all registered transports with health scores. Supports simultaneous active connections across multiple transports to the same peer.
- **ADDED**: `TransportSelector` — selects the best transport for a message based on: message priority, transport capability, peer capability, current latency, and health score.
- **ADDED**: `CapabilityNegotiator` — exchanges capability bitmaps during peer handshake: `webrtc`, `websocket`, `http`, `bluetooth`, `local-network`. Peers agree on common transports.
- **ADDED**: `PriorityRouter` — routes messages to transports based on 5 priority tiers:
  - `CRITICAL` — host election, failover, heartbeat (most reliable transport, redundant send)
  - `HIGH` — session transitions, state snapshots (fastest available)
  - `NORMAL` — game state, entity replication (default)
  - `LOW` — telemetry, metrics, non-urgent sync (batch, tolerate delay)
  - `BULK` — file chunks, large transfers (use highest-bandwidth transport, backpressure-aware)
- **ADDED**: `RoundRobinBalancer` — distributes BULK and NORMAL traffic across all healthy transports to prevent saturating any single path.
- **ADDED**: `TransportHealthMonitor` — tracks RTT, loss rate, bandwidth, and connection stability per transport. Auto-pauses degraded transports, auto-resumes on recovery.
- **ADDED**: `BatteryAwareScheduler` — when running on battery-powered devices, reduces transport keepalive frequency, defers non-critical transport probes, and prefers lower-power transports (WebSocket over WebRTC when quality is equivalent).
- **ADDED**: `BandwidthConservator` — monitors aggregate bandwidth usage across all transports. When conservation mode is active, coalesces small messages, increases batching intervals, and pauses redundant CRITICAL sends.
- **ADDED**: `RedundantSend` — CRITICAL messages are sent over 2+ transports simultaneously; first arrival wins, duplicates are detected and dropped.
- **ADDED**: `NETWORK_TM_CODES` — frozen error registry.

## Transport priority matrix

| Priority | WebRTC | WebSocket | HTTP | Behavior |
|---|---|---|---|---|
| CRITICAL | ✅ + redundant WS | ✅ + redundant WebRTC | ❌ | Send on 2+ transports |
| HIGH | ✅ preferred | ✅ fallback | ❌ | Fastest healthy |
| NORMAL | ✅ preferred | ✅ fallback | ❌ | Round-robin across healthy |
| LOW | ✅ | ✅ | ✅ | Batch, any available |
| BULK | ✅ preferred (bandwidth) | ✅ fallback | ✅ fallback | Backpressure-aware, round-robin |

## Capability bitmap

```typescript
type TransportCapability =
  | 'webrtc-datachannel'
  | 'websocket'
  | 'http-fetch'
  | 'http-sse'
  | 'bluetooth-le'
  | 'local-network-mdns'
  | 'relay-via-host';
```

Peers exchange capabilities during the `peer:connected` handshake. The transport manager only uses transports both peers support.

## Out of scope

- Transport-specific implementations → `network-plugin-webrtc`, `network-plugin-websocket`, etc.
- Physical-layer protocols (Bluetooth, mDNS) → future `network-plugin-bluetooth`, `network-plugin-mdns`.
- Bandwidth estimation per transport → `network-plugin-quality` (pre-existing enterprise plan).

## Source mapping

This is a **new design** — suaveplan has no equivalent multi-transport orchestration layer.

### Requirements with no source line

| Requirement | Justification |
|---|---|
| Multi-transport simultaneous operation | Required for resilience — single transport failure must not partition the mesh |
| Priority-based routing | Critical control messages must not be delayed behind bulk file transfers |
| Redundant send for CRITICAL | Host election messages must arrive even if one transport drops |
| Capability negotiation | Browser peers may not support WebRTC; Node.js peers may not support Bluetooth |
| Round-robin load balancing | Prevents saturating any single transport path |
| Transport health monitoring | Automatic pause/resume based on observed quality |

## Verification approach

- `src/pool/pool.spec-conformance.test.ts` — pins registration, health tracking, removal.
- `src/selector/selector.spec-conformance.test.ts` — pins priority routing, capability filtering.
- `src/negotiator/negotiator.spec-conformance.test.ts` — pins capability exchange, common subset.
- `src/priority/priority.spec-conformance.test.ts` — pins 5-tier routing, CRITICAL redundant send.
- `src/balancer/balancer.spec-conformance.test.ts` — pins round-robin, load distribution.
- `src/health/health.spec-conformance.test.ts` — pins degradation detection, auto-pause/resume.
- `tests/dep-graph.test.ts` — pins no direct import of transport implementations.

## Enhancement: Pre-Emptive Transport Switching

**Source**: `docs/old-network-planning/PHASE_2_5.md` §Pre-emptive switching, `ADAPT_3.md`

The transport manager currently switches transports after degradation threshold. Pre-emptive switching predicts failure and switches before complete disconnect:

- `QualityTrendAnalyzer` — tracks latency trend (EMA slope), packet loss trend, bandwidth degradation.
- `PreemptiveSelector` — initiates switch when trend indicates impending failure, even if current transport is still "healthy".
- Smooth handoff: establishes new transport before tearing down old, with overlap window.

## Enhancement: Session Persistence During Disconnection

**Source**: `docs/old-network-planning/PHASE_2_5.md` §Connection Recovery, `SERVER_FAILOVER.md`

- `SessionPersistenceBuffer` — buffers connection state during temporary drops.
- `ConnectionRecoveryManager` — exponential backoff reconnection with jitter.
- `SessionContinuityGuard` — maintains session context across reconnections. Replays buffered messages in sequence on recovery.
- Prioritized recovery: CRITICAL connections recover first.

## Migration impact

None — additive only.