# OpenSpec Change: network-transport-webtorrent

- **Change ID**: network-transport-webtorrent
- **Package**: `@suaveplan/network-transport-webtorrent`
- **Category**: browser
- **Target path**: `packages/network/network-transport-webtorrent`
- **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-webtorrent` (Wave 2)
- **Supersedes**: the original name reservation in this folder (2026-05-11)

---

## Summary

Reserve and define migration scope for `@suaveplan/network-transport-webtorrent` — a browser-tier `Transport` implementation over WebRTC DataChannels signaled by WebTorrent trackers via p2pt. Wraps the connection-management subsystem of `network-discovery-webtorrent` (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-webtorrent/`) bundles **discovery + transport** in a single package: upstream `WebTorrentDiscovery` (210 LOC) handles both tracker rendezvous AND P2PT data-channel lifecycle in one class. 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-webtorrent` — pure `DiscoveryStrategy` producing peer endpoints
2. `network-transport-webtorrent` — pure `Transport` implementation over WebRTC DataChannels signaled by WebTorrent trackers via p2pt

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-webtorrent` ships both `DiscoveryStrategy` AND a `Transport` adapter. `network-transport-webtorrent` becomes a thin re-export of the transport surface only.

Pro: parity with upstream layout, fewer moving parts.

Con: anyone importing `network-transport-webtorrent` 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-webtorrent/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 WebRTC DataChannels signaled by WebTorrent trackers via p2pt

---

## 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 WebRTC DataChannels signaled by WebTorrent trackers via p2pt | ✅ | ✅ | 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-webtorrent` | ⬆️ | 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-webtorrent` ⬅ 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: `p2pt`.

**Blocking note.** `network-discovery-webtorrent` (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-webtorrent` green.
2. `bunx turbo test:coverage --filter=@suaveplan/network-transport-webtorrent` 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).