Initial Commit

openspec/archive/2026-05-12-network-transport-peerjs/proposal.md

@@ -0,0 +1,105 @@
+# OpenSpec Change: network-transport-peerjs
+
+- **Change ID**: network-transport-peerjs
+- **Package**: `@suaveplan/network-transport-peerjs`
+- **Category**: browser
+- **Target path**: `packages/network/network-transport-peerjs`
+- **Status**: PROPOSED (architecture decision required at implementation time — see §"Split vs. fold")
+- **Date**: 2026-05-11
+- **Parent**: `network-transport-family` (2026-05-11) — Wave 3
+- **Sibling**: `network-discovery-peerjs` (Wave 2)
+- **Supersedes**: the original name reservation in this folder (2026-05-11)
+
+---
+
+## Summary
+
+Reserve and define migration scope for `@suaveplan/network-transport-peerjs` — a browser-tier `Transport` implementation over PeerJS-signaled WebRTC DataChannels. Wraps the connection-management subsystem of `network-discovery-peerjs` (Wave 2) into a standalone `Transport` that registers with `@suaveplan/network-plugin-transport-manager` ✅.
+
+---
+
+## Split vs. fold — architecture decision required
+
+Upstream (`../suaveplan/packages/browser/network-discovery-peerjs/`) bundles **discovery + transport** in a single package: the upstream `PeerJSDiscovery` class owns both `DiscoveryStrategy` and `PeerConnectionManager`/`PeerJSConnection` (≈390 LOC of transport work). Two implementation paths are valid; the migrating engineer chooses based on the audit:
+
+### Option A — Split (recommended for new code)
+
+Two genesis packages:
+
+1. `network-discovery-peerjs` — pure `DiscoveryStrategy` producing peer endpoints
+2. `network-transport-peerjs` — pure `Transport` implementation over PeerJS-signaled WebRTC DataChannels
+
+Pro: cleaner separation, transport-manager can pick this transport without inheriting the discovery package. Matches the family-naming convention.
+
+Con: more genesis packages, more boundaries to maintain, divergence from upstream layout.
+
+### Option B — Fold
+
+Single genesis package: `network-discovery-peerjs` ships both `DiscoveryStrategy` AND a `Transport` adapter. `network-transport-peerjs` becomes a thin re-export of the transport surface only.
+
+Pro: parity with upstream layout, fewer moving parts.
+
+Con: anyone importing `network-transport-peerjs` drags in the discovery dep.
+
+**Decision deferred** to the implementing proposal. This proposal reserves the name + path under both options.
+
+---
+
+## Current-state audit
+
+See parallel proposal `openspec/changes/network-discovery-peerjs/proposal.md` for the full upstream surface inventory (it covers both the discovery and transport subsystems).
+
+Transport-specific subsystem (extracted from the bundled upstream package):
+
+- Per-peer connection wrapper
+- Connection lifecycle (open / close / heartbeat / cleanup)
+- Wire-format encoding/decoding over PeerJS-signaled WebRTC DataChannels
+
+---
+
+## Parity Checklist
+
+| Capability | Upstream | Migrated | Notes |
+|---|---|---|---|
+| Per-peer connection wrapper | ✅ | ✅ | |
+| `Transport` contract impl | partial (embedded in discovery class) | ⬆️ | NEW `Transport` adapter or extracted from bundled code per Option A/B. |
+| `NetworkPlugin` wrapper | partial | ⬆️ | Mirrors `WebRTCPlugin` shape. |
+| Wire-format framing over PeerJS-signaled WebRTC DataChannels | ✅ | ✅ | Re-use `@suaveplan/serialize` length-prefix where applicable. |
+| Structured errors | 🚫 | ⬆️ | Strategy-specific code registry. |
+| Zod boundary validation | 🚫 | ⬆️ | Every public option struct. |
+| OTel instrumentation | 🚫 | ⬆️ | Spans + counters + histograms. |
+| AbortSignal | 🚫 | ⬆️ | Threaded everywhere. |
+| Insecure default rejection | inherited from `network-discovery-peerjs` | ⬆️ | Same — no public-relay/tracker/broker fallbacks. |
+| Test-runner imports | direct vitest | ⬆️ | `@suaveplan/testing/runner` per §7. |
+| 100% test coverage | 🚫 | ⬆️ | Bring to 100/100/100/100. |
+
+---
+
+## Available workspace deps on genesis
+
+- `@suaveplan/network` ✅
+- `@suaveplan/network-plugin-transport-manager` ✅
+- `@suaveplan/network-transport-webrtc` ✅ (composes `RTCPeerConnection` where applicable)
+- `network-discovery-peerjs` ⬅ Wave 2 (sibling — required if Option B, optional peer-dep if Option A)
+- `@suaveplan/types`, `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/timing`, `@suaveplan/retry` ✅
+- `@suaveplan/testing` ✅
+- External: `peerjs`.
+
+**Blocking note.** `network-discovery-peerjs` (Wave 2) must land first regardless of Option A/B — Option A pairs with it, Option B is implemented inside it.
+
+---
+
+## Acceptance gate
+
+1. `bunx turbo lint typecheck test --filter=@suaveplan/network-transport-peerjs` green.
+2. `bunx turbo test:coverage --filter=@suaveplan/network-transport-peerjs` 100/100/100/100.
+3. `bun run docs:check` green.
+4. Integration test with `network-plugin-transport-manager`: register this transport, send envelope through it, verify peer receives.
+5. `STATUS.md` row flipped from `–` to `✅`.
+
+---
+
+## Out of scope
+
+- Hosting / running any required relays, trackers, or brokers (deployment concern).
+- Cross-transport peer migration (covered by transport-manager + standby).