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:

network-discovery-webtorrent — pure DiscoveryStrategy producing peer endpoints
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

bunx turbo lint typecheck test --filter=@suaveplan/network-transport-webtorrent green.
bunx turbo test:coverage --filter=@suaveplan/network-transport-webtorrent 100/100/100/100.
bun run docs:check green.
Integration test with network-plugin-transport-manager: register this transport, send envelope through it, verify peer receives.
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).

5.1 KiB Raw Blame History Unescape Escape