suaveplan/openspec/archive/2026-05-11-network-transport-websockets-adapter/tasks.md

Tasks — network-transport-websockets-adapter

Phase 1: Transport implementation

• 1.1 Author src/transport/transport.ts — WebSocketTransport implements Transport with per-peer WebSocketClient registry.
• 1.2 Wire connect/disconnect/send/onMessage/getConnectedPeers/close.
• 1.3 Author sibling src/transport/transport.md.
• 1.4 Author src/transport/transport.spec-conformance.test.ts running the Transport contract suite from @suaveplan/network.

Phase 2: Plugin wrapper

• 2.1 Author src/plugin/plugin.ts — WebSocketPlugin implements NetworkPlugin mirroring WebRTCPlugin.
• 2.2 Author sibling src/plugin/plugin.md.
• 2.3 Author src/plugin/plugin.spec-conformance.test.ts for lifecycle idempotency.

Phase 3: Type + error extensions

• 3.1 Add WebSocketTransportConfig to src/types/types.ts.
• 3.2 Extend defineCodes("NET_WS", [...]) with PEER_ALREADY_CONNECTED, PEER_UNKNOWN, TRANSPORT_CLOSED, MAX_PEERS_EXCEEDED.

Phase 4: Observability

• 4.1 Spans: ws_transport.connect, ws_transport.disconnect, ws_transport.send.
• 4.2 Counters: ws_transport.peers_connected{outcome}, ws_transport.messages_total{direction,outcome}.
• 4.3 Gauges: ws_transport.active_peers.

Phase 5: Bus events (optional, when plugin holds a bus reference)

• 5.1 Emit transport:connected / transport:disconnected on NetworkBus.
• 5.2 Emit peer:latency with EMA-smoothed RTT (re-use the heartbeat path).

Phase 6: Tests

• 6.1 Per-peer registry property test (fast-check).
• 6.2 Multi-peer fan-out test.
• 6.3 Lifecycle idempotency test (install → install, stop → stop).
• 6.4 100/100/100/100 coverage gate.

Phase 7: Integration

• 7.1 Cross-package integration test with network-plugin-transport-manager ✅: register WS as fallback, simulate WebRTC failure, verify WS takes over.
• 7.2 Update openspec/specs/network/spec.md if NET-04 conformance language tightens.

Phase 8: Verification

• 8.1 bunx turbo lint typecheck test --filter=@suaveplan/network-transport-websockets green.
• 8.2 bunx turbo test:coverage --filter=@suaveplan/network-transport-websockets 100/100/100/100.
• 8.3 bun run docs:check --filter=@suaveplan/network-transport-websockets green.
• 8.4 MANIFEST.md shows new dep on @suaveplan/network (for the Transport + NetworkPlugin types).

Pre-archive checklist

• Row 1 — Phase 8 green.
• Row 2 — Transport conformance test passes against the canonical suite.
• Row 3 — Integration test with network-plugin-transport-manager passes.
• Row 4 — STATUS.md row updated to drop the "(pending Plugin adapter)" suffix.
• Row 5 — Folder archived.