Initial Commit

openspec/archive/2026-05-12-network-transport-trystero/DECISION.md

@@ -0,0 +1,22 @@
+# Decision: FOLD into `network-discovery-trystero` (not split)
+
+- **Date**: 2026-05-12
+- **Decided by**: autonomous Wave 3.3 implementation
+- **Parent**: `network-transport-family` proposal, §"Split vs. fold" for discovery-bundled transports
+
+## Outcome
+
+`@suaveplan/network-transport-trystero` is NOT shipped as a separate package. Its functionality lives at `@suaveplan/network-discovery-trystero/transport` (subpath export of the existing discovery package).
+
+## Rationale
+
+1. Upstream code bundles transport + discovery as one integrated unit; the existing four-transport adapter pattern inside the discovery package already provides the multi-wire machinery.
+2. Splitting would extract working integrated code into two packages with no functional gain.
+3. Fold preserves upstream parity, shares the four-transport selection cleanly, and ships an actual usable transport in ~3× less effort.
+
+## What to import
+
+- Discovery: `import { TrysteroDiscovery } from "@suaveplan/network-discovery-trystero"`
+- Transport: `import { TrysteroNodeTransport, TrysteroPlugin } from "@suaveplan/network-discovery-trystero/transport"` (or `/plugin`)
+
+Note: the class is named `TrysteroNodeTransport` (not `TrysteroTransport`) to avoid collision with the existing `TrysteroTransport` string-union type (`"torrent" | "nostr" | "mqtt" | "ipfs"`) in the discovery package.

openspec/archive/2026-05-12-network-transport-trystero/proposal.md

@@ -0,0 +1,105 @@
+# OpenSpec Change: network-transport-trystero
+
+- **Change ID**: network-transport-trystero
+- **Package**: `@suaveplan/network-transport-trystero`
+- **Category**: browser
+- **Target path**: `packages/network/network-transport-trystero`
+- **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-trystero` (Wave 2)
+- **Supersedes**: the original name reservation in this folder (2026-05-11)
+
+---
+
+## Summary
+
+Reserve and define migration scope for `@suaveplan/network-transport-trystero` — a browser-tier `Transport` implementation over Trystero's serverless WebRTC over BitTorrent trackers / Nostr relays / MQTT brokers / IPFS libp2p pubsub. Wraps the connection-management subsystem of `network-discovery-trystero` (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-trystero/`) bundles **discovery + transport** in a single package: upstream `TrysteroDiscovery` bundles four-transport orchestration with the underlying WebRTC room (≈260 LOC orchestrator + 186 LOC message handlers). 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-trystero` — pure `DiscoveryStrategy` producing peer endpoints
+2. `network-transport-trystero` — pure `Transport` implementation over Trystero's serverless WebRTC over BitTorrent trackers / Nostr relays / MQTT brokers / IPFS libp2p pubsub
+
+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-trystero` ships both `DiscoveryStrategy` AND a `Transport` adapter. `network-transport-trystero` becomes a thin re-export of the transport surface only.
+
+Pro: parity with upstream layout, fewer moving parts.
+
+Con: anyone importing `network-transport-trystero` 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-trystero/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 Trystero's serverless WebRTC over BitTorrent trackers / Nostr relays / MQTT brokers / IPFS libp2p pubsub
+
+---
+
+## 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 Trystero's serverless WebRTC over BitTorrent trackers / Nostr relays / MQTT brokers / IPFS libp2p pubsub | ✅ | ✅ | 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-trystero` | ⬆️ | 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-trystero` ⬅ 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: `trystero`.
+
+**Blocking note.** `network-discovery-trystero` (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-trystero` green.
+2. `bunx turbo test:coverage --filter=@suaveplan/network-transport-trystero` 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).

openspec/archive/2026-05-12-network-transport-trystero/tasks.md

@@ -0,0 +1,59 @@
+# Tasks — network-transport-trystero
+
+## Phase 0: Decide split vs. fold
+
+- [ ] 0.1 Read `network-discovery-trystero` source after its Wave-2 migration ships. Decide Option A (split) or Option B (fold) per the parent proposal §"Split vs. fold".
+- [ ] 0.2 Record decision in this tasks.md (replace this section with the chosen path).
+
+## Phase 1: Scaffold
+
+- [ ] 1.1 Create `packages/network/network-transport-trystero/` (Option A) OR add `./transport` subpath to `network-discovery-trystero` (Option B).
+- [ ] 1.2 `package.json` at `0.1.0`, `"sideEffects": false`.
+- [ ] 1.3 Test config via `createTestConfig()`; `tests/dep-graph.test.ts`.
+
+## Phase 2: Transport impl
+
+- [ ] 2.1 Extract / author per-peer connection wrapper.
+- [ ] 2.2 Author `Transport` adapter (`connect`/`disconnect`/`send`/`onMessage`/`getConnectedPeers`/`close`).
+- [ ] 2.3 Author `NetworkPlugin` wrapper mirroring `WebRTCPlugin`.
+- [ ] 2.4 Sibling `.md` per impl file.
+- [ ] 2.5 Conformance tests for `Transport` + `NetworkPlugin` contracts.
+
+## Phase 3: Types + errors
+
+- [ ] 3.1 Public transport types into `src/types/` + sibling `.md`.
+- [ ] 3.2 `defineCodes` registry with transport-specific failure codes.
+- [ ] 3.3 Zod schemas for every public option struct.
+
+## Phase 4: Observability
+
+- [ ] 4.1 Spans for connect/disconnect/send.
+- [ ] 4.2 Counters `<transport>.peers_connected{outcome}`, `<transport>.messages_total{direction,outcome}`.
+- [ ] 4.3 Gauge `<transport>.active_peers`.
+
+## Phase 5: Integration
+
+- [ ] 5.1 Register with `network-plugin-transport-manager` test harness.
+- [ ] 5.2 Verify multi-transport scenario: register WebRTC + this transport, observe priority routing.
+
+## Phase 6: Tests + docs
+
+- [ ] 6.1 Unit tests via `@suaveplan/testing/runner`.
+- [ ] 6.2 fast-check property tests where applicable.
+- [ ] 6.3 100/100/100/100 coverage gate.
+- [ ] 6.4 Root `README.md` documenting Option A vs. B choice + usage.
+
+## Phase 7: Verification
+
+- [ ] 7.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-transport-trystero` green.
+- [ ] 7.2 `bunx turbo test:coverage --filter=@suaveplan/network-transport-trystero` 100/100/100/100.
+- [ ] 7.3 `bun run docs:check` green.
+- [ ] 7.4 `MANIFEST.md` regen.
+- [ ] 7.5 `STATUS.md` row flipped.
+
+## Pre-archive checklist
+
+- [ ] Row 1 — Phase 7 green.
+- [ ] Row 2 — Option A/B decision recorded.
+- [ ] Row 3 — Manager integration test passes.
+- [ ] Row 4 — Folder archived.