Initial Commit

openspec/changes/archive/2026-05-04-network-plugin-webrtc/proposal.md

@@ -0,0 +1,63 @@
+# 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.

openspec/changes/archive/2026-05-04-network-plugin-webrtc/tasks.md

@@ -0,0 +1,72 @@
+# Tasks — network-plugin-webrtc
+
+> Blocked on: `network-core`.
+
+## 1. Scaffold
+
+- [x] 1.1 `packages/network/network-plugin-webrtc/` with `package.json` (`@suaveplan/network-plugin-webrtc@0.0.0`), `tsconfig.json`, `vitest.config.ts`, `README.md`.
+- [x] 1.2 Workspace deps: `@suaveplan/network`, `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/streams`, `@suaveplan/timing`, `@opentelemetry/api`, `zod`.
+- [x] 1.3 `sideEffects: false`.
+
+## 2. Types
+
+- [x] 2.1 `src/types/signaling.types.ts` — `SignalingClient`, `SignalingMessage`, `SignalType`.
+- [x] 2.2 `src/types/webrtc.types.ts` — `WebRTCConfig`, `PeerConnectionState`, `DataChannelConfig`.
+- [x] 2.3 `src/types/ping.types.ts` — `PingFrame`, `PongFrame`, `LatencyRecord`.
+- [x] 2.4 `src/error-codes.ts` — `defineCodes("NET_WEBRTC", [...])`.
+
+## 3. Signaling
+
+- [x] 3.1 `src/signaling/signaling-client.ts` — `SignalingClient` interface.
+- [x] 3.2 `src/signaling/websocket-signaling-client.ts` — WebSocket implementation with reconnect.
+
+## 4. ICE management
+
+- [x] 4.1 `src/ice/ice-manager.ts` — monitors `iceConnectionState`, triggers restart on `failed`.
+- [x] 4.2 Configurable `iceServers` (STUN + TURN).
+
+## 5. Data channel
+
+- [x] 5.1 `src/data-channel/data-channel-manager.ts` — open/close channels, `bufferedAmount` backpressure.
+- [x] 5.2 Emits `Uint8Array` messages on the bus.
+
+## 6. Transport implementation
+
+- [x] 6.1 `src/transport/webrtc-transport.ts` — implements `Transport`: `connect`, `disconnect`, `send`, `onMessage`, `getConnectedPeers`.
+- [x] 6.2 Manages one `RTCPeerConnection` per peer.
+
+## 7. Mesh
+
+- [x] 7.1 `src/mesh/webrtc-mesh.ts` — auto-connects to discovered peers, maintains full-mesh.
+- [x] 7.2 Removes peers on disconnect or heartbeat timeout.
+
+## 8. Ping / latency
+
+- [x] 8.1 `src/ping/ping-manager.ts` — correlated echo frames, RTT measurement.
+- [x] 8.2 EMA smoothing with configurable window.
+- [x] 8.3 Publishes `peer:latency` on `NetworkBus`.
+
+## 9. Plugin wrapper
+
+- [x] 9.1 `src/plugin/webrtc-plugin.ts` — `WebRTCPlugin` implements `NetworkPlugin`.
+- [x] 9.2 Registers itself as a transport with the node on `install()`.
+
+## 10. Spec
+
+- [x] 10.1 Update `openspec/specs/network/spec.md` with `NET-06`, `NET-07`.
+
+## 11. Conformance tests
+
+- [x] 11.1 `src/transport/transport.spec-conformance.test.ts` — `Transport` compliance.
+- [x] 11.2 `src/mesh/mesh.spec-conformance.test.ts` — auto-connect, full-mesh, removal.
+- [x] 11.3 `src/ping/ping.spec-conformance.test.ts` — echo, RTT, EMA.
+- [x] 11.4 `src/ice/ice.spec-conformance.test.ts` — restart on failure.
+- [x] 11.5 `src/signaling/signaling.spec-conformance.test.ts` — interface, WebSocket impl.
+- [x] 11.6 `src/backpressure/backpressure.spec-conformance.test.ts` — bufferedAmount pause.
+- [x] 11.7 `src/error-codes.spec-conformance.test.ts` — frozen registry.
+
+## 12. Verify
+
+- [x] 12.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-webrtc` green.
+- [x] 12.2 `bunx turbo test:coverage --filter=@suaveplan/network-plugin-webrtc` 100/100/100/100.
+- [x] 12.3 `bun scripts/openspec-conformance.ts @suaveplan/network-plugin-webrtc` PASS.