suaveplan/openspec/archive/2026-05-11-network-discovery-webtorrent/proposal.md

OpenSpec Change: network-discovery-webtorrent

• Change ID: network-discovery-webtorrent
• Package: @suaveplan/network-discovery-webtorrent
• Category: browser
• Target path: packages/network/network-discovery-webtorrent
• Status: PROPOSED
• Date: 2026-05-11
• Parent: network-transport-family (2026-05-11) — Wave 2
• Migration source: ../suaveplan/packages/browser/network-discovery-webtorrent + ../suaveplan/enterprise/network-discovery-webtorrent.md

---

Summary

Migrate @suaveplan/network-discovery-webtorrent as a browser-tier DiscoveryStrategy for @suaveplan/network. WebTorrent-tracker-based WebRTC peer discovery via p2pt. Smallest discovery package but the upstream test file is describe.skip-only, so this migration adds the entire test suite from zero.

---

Current-state audit

Upstream source layout (../suaveplan/packages/browser/network-discovery-webtorrent/src/):

• lib/network-discovery-webtorrent.ts (210 L) — full implementation: tracker list, P2PT wrap, peer add/remove, error propagation

See ../suaveplan/enterprise/network-discovery-webtorrent.md for full upstream surface inventory.

---

Parity Checklist

Capability	Upstream	Migrated	Notes
DiscoveryStrategy impl	✅	✅
WebTorrentDiscovery core	✅	✅	Extends genesis @suaveplan/events EventEmitter.
Default tracker list	⚠️ (public)	⬆️	Tracker list REQUIRED in options; no public-tracker fallback.
Tests	🚫 (describe.skip shell)	⬆️	Full unit + integration suite written from scratch — upstream coverage is effectively 0%.
Structured errors	🚫	⬆️	defineCodes registry with strategy-specific codes.
Zod boundary validation	🚫	⬆️	Every public option struct.
OTel instrumentation	🚫	⬆️	Spans + counters + histograms keyed by strategy.
AbortSignal	🚫	⬆️	Threaded through start/stop/connect.
export * barrels	check	⬆️	Convert to explicit named exports per §6a.
Test-runner imports	direct vitest	⬆️	Rewrite to @suaveplan/testing/runner per §7.
100% test coverage	🚫	⬆️	Bring to 100/100/100/100.
Property tests	🚫	⬆️	fast-check property suite where applicable.

---

Available workspace deps on genesis

• @suaveplan/network ✅
• @suaveplan/network-bootstrap ⬅ Wave 1
• @suaveplan/service-discovery ⬅ Wave 1
• @suaveplan/types, @suaveplan/error, @suaveplan/events, @suaveplan/timing ✅
• @suaveplan/testing ✅
• External: p2pt — add to root catalog under network-discovery.

Blocking note. Wave 1 must land first.

---

Acceptance gate

1. bunx turbo lint typecheck test --filter=@suaveplan/network-discovery-webtorrent green.
2. bunx turbo test:coverage --filter=@suaveplan/network-discovery-webtorrent 100/100/100/100.
3. bun run docs:check green (sibling .md per .ts).
4. STATUS.md row flipped from – to ✅.
5. network-bootstrap chain integration test demonstrates this strategy as a working entry.

---

Out of scope

• Hosting / running any required relays or trackers (deployment concern).
• React Storybook stories — discovery is a universal/headless tier; UI lives in a dedicated devtools package (future).