# Capability Spec: network-webrtc

## Capability ID

`network-webrtc`

## Status

PROPOSED

## Description

WebRTC peer-to-peer transport for the tiered network mesh. Provides signaling, ICE management, data channels, peer mesh maintenance, and latency measurement.

## Interfaces

### `SignalingClient`

```typescript
interface SignalingClient {
  connect(): Promise<void>;
  disconnect(): Promise<void>;
  send(message: SignalingMessage): Promise<void>;
  onMessage(handler: (msg: SignalingMessage) => void): () => void;
}
```

### `WebRTCTransport`

```typescript
interface WebRTCTransport extends Transport {
  createPeerConnection(peerId: string): RTCPeerConnection;
  closePeerConnection(peerId: string): void;
  getPeerConnection(peerId: string): RTCPeerConnection | undefined;
}
```

### `WebRTCMesh`

```typescript
interface WebRTCMesh {
  connectToPeer(peerId: string): Promise<void>;
  disconnectFromPeer(peerId: string): void;
  getConnectedPeers(): string[];
}
```

### `PingManager`

```typescript
interface PingManager {
  start(): void;
  stop(): void;
  getLatency(peerId: string): number | undefined;
}
```

## Behaviors

### NET-WEB-01 — Signaling

The signaling client MUST connect to a WebSocket server, send `offer`/`answer`/`ice-candidate` messages, and receive corresponding messages from remote peers.

### NET-WEB-02 — ICE Restart

When `iceConnectionState` transitions to `failed`, the transport MUST automatically trigger ICE restart.

### NET-WEB-03 — Data Channel

The transport MUST open a reliable, ordered data channel per peer. Messages MUST be emitted as `Uint8Array` on the `NetworkBus`.

### NET-WEB-04 — Backpressure

The transport MUST pause sending when `bufferedAmount` exceeds a configurable threshold and resume when it drops below a lower threshold.

### NET-WEB-05 — Mesh Auto-Connect

The mesh MUST automatically connect to newly discovered peers and maintain a full mesh (all-to-all connections within the group).

### NET-WEB-06 — Mesh Removal

The mesh MUST remove peers on disconnect or heartbeat timeout and emit `peer:disconnected` on the `NetworkBus`.

### NET-WEB-07 — Ping/Latency

The ping manager MUST send correlated echo frames, measure RTT, apply EMA smoothing, and publish `peer:latency` on the `NetworkBus`.

### NET-WEB-08 — Configurable ICE Servers

The transport MUST accept configurable STUN/TURN servers.

## Error codes

- `NET_WEBRTC_SIGNALLING_FAILED` — WebSocket connection failed
- `NET_WEBRTC_ICE_FAILED` — ICE connection failed after restart
- `NET_WEBRTC_DATA_CHANNEL_CLOSED` — Data channel closed unexpectedly
- `NET_WEBRTC_BACKPRESSURE_EXCEEDED` — Buffered amount exceeded max

## Dependencies

- `@suaveplan/network`
- `@suaveplan/error`
- `@suaveplan/types`
- `@suaveplan/events`
- `@suaveplan/streams`
- `@suaveplan/timing`
- `@opentelemetry/api`
- `zod`

## Notes

- WebRTC is browser-only; Node.js peers use `network-websockets` or `network-standby-transport`.
- The mesh size is bounded by the registry capacity (default 32 peers).