# OpenSpec Change: network-plugin-webrtc

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

## Why

The core `network` package defines the `Transport` interface but ships no implementation. For browser-to-browser mesh networking — the primary use-case for the tiered host-nomination system — WebRTC is the only practical peer-to-peer transport. This plugin implements the `Transport` contract using `RTCPeerConnection` and `RTCDataChannel`, adds automatic mesh formation, ICE restart, RTT measurement (ping), and signaling pluggability so it can work with any signaling backend (WebSocket, HTTP POST, or a future DHT plugin).

## What changes

- **ADDED**: `WebRTCPlugin` class implementing `NetworkPlugin` and `Transport`.
- **ADDED**: `WebRTCTransport` — manages `RTCPeerConnection` lifecycle per peer: create, offer/answer, ICE handling, data channel open/close.
- **ADDED**: `WebRTCMesh` — automatic mesh formation: on peer discovery, initiates connection; on peer disconnect, removes from mesh. Maintains full-mesh within a group.
- **ADDED**: `DataChannelManager` — opens labeled data channels, handles `bufferedAmount` backpressure, emits `message` events as `Uint8Array`.
- **ADDED**: `PingManager` — sends correlated echo frames over any active transport (not just WebRTC), measures RTT with EMA smoothing, calculates jitter and packet loss, maintains a composite reliability score, publishes `peer:latency` on the bus. Can be used by `network-plugin-transport-manager` to health-monitor any transport type.
- **ADDED**: `SignalingClient` interface — pluggable signaling: `connect()`, `send(signal)`, `onSignal(handler)`, `disconnect()`. Ships with a `WebSocketSignalingClient` implementation.
- **ADDED**: `IceManager` — monitors `iceConnectionState`, triggers ICE restart on failure, surfaces `transport:ice-restart` events.
- **ADDED**: `NETWORK_WEBRTC_CODES` — frozen error registry.

## Out of scope

- TURN server deployment or TURN credential rotation → ops concern, documented but not implemented.
- DHT-based peer discovery without signaling → future `network-plugin-discovery-dht`.
- Simulcast / SFU mode → future `network-plugin-sfu`.
- Screen sharing or media tracks → this is a data-channel transport only.

## Source mapping

This change derives from `../suaveplan/enterprise/network-webrtc.md`, `../suaveplan/enterprise/drive-webrtc.md`, and `../suaveplan/packages/browser/network-webrtc/`.

| Requirement | Source lines | Notes |
|---|---|---|
| WebRTC peer connection lifecycle | `drive-webrtc.md` §2, `network-webrtc/README.md` | reworded; merged with Transport interface |
| Data channel byte transport | `drive-webrtc.md` §2 `DataChannelManager` | verbatim contract |
| ICE restart on failure | `drive-webrtc.md` §3.6 | verbatim |
| Ping / RTT measurement | `network/src/transport/legacy/base-transport.md` (stub) | new requirement — source only had a TODO |
| Signaling pluggability | `drive-webrtc.md` §4.8 | verbatim |

### Requirements with no source line

| Requirement | Justification |
|---|---|
| `PingManager` with EMA | Source had `"Ping not implemented"` stub; genesis implements it properly using `timing` EMA |
| Full-mesh within group | Required for the tiered host-nomination voting use-case |
| `bufferedAmount` backpressure | Prevents datachannel buffer overflow in high-throughput scenarios |

## Verification approach

- `src/transport/transport.spec-conformance.test.ts` — pins `Transport` interface compliance (connect, disconnect, send, onMessage, getConnectedPeers).
- `src/mesh/mesh.spec-conformance.test.ts` — pins automatic connection on peer discovery and removal on disconnect.
- `src/ping/ping.spec-conformance.test.ts` — pins correlated echo, RTT calculation, EMA smoothing.
- `src/ice/ice.spec-conformance.test.ts` — pins ICE restart on `failed` state.
- `src/signaling/signaling.spec-conformance.test.ts` — pins `SignalingClient` interface and WebSocket implementation.
- `src/backpressure/backpressure.spec-conformance.test.ts` — pins `bufferedAmount` pause/resume.
- `tests/dep-graph.test.ts` — pins no browser-only APIs leak into non-browser builds.

## Migration impact

None — additive only.