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

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.

6.7 KiB Raw Blame History