Initial Commit

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

@@ -0,0 +1,81 @@
+# 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](https://github.com/dmotz/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).