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

OpenSpec Change: network-discovery-trystero

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

---

Summary

Migrate @suaveplan/network-discovery-trystero as a browser-tier DiscoveryStrategy for @suaveplan/network. Serverless WebRTC peer discovery via Trystero, with four interchangeable transports: BitTorrent trackers, Nostr relays, MQTT brokers, IPFS libp2p pubsub.

---

Current-state audit

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

• trystero-discovery.ts (259 L) — orchestrator
• message-handlers.ts (186 L)
• room-config.ts (178 L) — per-strategy room config
• types-messages.ts (176 L), types-config.ts (158 L)
• intervals.ts (132 L)
• fallback.ts — auto-fallback between transports
• event-emitter.ts — typed events

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

---

Parity Checklist

Capability	Upstream	Migrated	Notes
DiscoveryStrategy impl	✅	✅
4 transports (torrent / nostr / mqtt / ipfs)	✅	✅	Each transport selectable at construction.
Inter-transport fallback	✅	✅	Reuses @suaveplan/retry for backoff.
Public relay defaults	⚠️ (insecure)	⬆️	Relay list REQUIRED in options; constructor throws INVALID_OPTIONS if missing.
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: trystero — 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-trystero green.
2. bunx turbo test:coverage --filter=@suaveplan/network-discovery-trystero 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).