Initial Commit

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

@@ -0,0 +1,93 @@
+# OpenSpec Change: network-discovery-peerjs
+
+- **Change ID**: network-discovery-peerjs
+- **Package**: `@suaveplan/network-discovery-peerjs`
+- **Category**: browser
+- **Target path**: `packages/network/network-discovery-peerjs`
+- **Status**: PROPOSED
+- **Date**: 2026-05-11
+- **Parent**: `network-transport-family` (2026-05-11) — Wave 2
+- **Migration source**: `../suaveplan/packages/browser/network-discovery-peerjs` + `../suaveplan/enterprise/network-discovery-peerjs.md`
+
+---
+
+## Summary
+
+Migrate `@suaveplan/network-discovery-peerjs` as the simplest possible browser-tier `DiscoveryStrategy` — a PeerJS signaling-server client wrapper that produces initial WebRTC peers for `@suaveplan/network`. First package of Wave 2 because PeerJS has the smallest API surface and the fewest external moving parts, so it doubles as the canonical template for the other 5 discovery migrations.
+
+---
+
+## Why this is first in Wave 2
+
+- **Smallest surface.** Six upstream source files totalling ≈1.2k LOC.
+- **Cleanest dependency.** Single external (`peerjs`), no signaling relay we have to host.
+- **Strategy contract.** Implements `DiscoveryStrategy` — the same interface `network-bootstrap` chains and `network-discovery-hybrid` aggregates. Locking it in first proves the contract before the heavier packages port.
+
+---
+
+## Current-state audit
+
+Upstream (`../suaveplan/packages/browser/network-discovery-peerjs/src/`):
+
+- `peerjs-discovery.ts` (244 L) — `DiscoveryStrategy` implementation
+- `peer-connection-manager.ts` (257 L) — connection registry
+- `room-manager.ts` (242 L) — logical room semantics
+- `peerjs-connection.ts` (132 L) — `RTCDataConnection` wrapper
+- `peerjs-message-handlers.ts` (129 L) — wire-format routing
+- `peerjs-event-emitter.ts` — typed events
+- `peerjs-intervals.ts` — ping / cleanup loops
+- `types.ts` (175 L)
+
+Upstream coverage: single test file (`peerjs-discovery.browser.test.ts`), `.stories.tsx` exists. No declared React peer dep despite the TSX story.
+
+---
+
+## Parity Checklist
+
+| Capability | Upstream | Migrated | Notes |
+|---|---|---|---|
+| `PeerJSDiscovery implements DiscoveryStrategy` | ✅ | ✅ | |
+| `PeerConnectionManager` per-peer registry | ✅ | ✅ | |
+| `RoomManager` logical rooms over PeerJS IDs | ✅ | ✅ | |
+| `PeerJSConnection` `RTCDataConnection` wrapper | ✅ | ✅ | |
+| Typed event emission | ✅ | ✅ | Replaced with `@suaveplan/events` `EventBus` per AGENTS.md. |
+| Ping / cleanup intervals | ✅ | ✅ | Replaced with `@suaveplan/timing` scheduler + injectable `Clock`. |
+| Structured errors | 🚫 | ⬆️ | `defineCodes("NET_DISC_PEERJS", [...])`: `SIGNALING_FAILED`, `PEER_CONNECT_FAILED`, `ROOM_FULL`, `INVALID_OPTIONS`, `DISPOSED`. |
+| Zod boundary validation | 🚫 | ⬆️ | Every public option struct. |
+| OTel instrumentation | 🚫 | ⬆️ | Span `disc_peerjs.start`, counters `peers_discovered_total{outcome}`, histogram `signaling_duration_ms`. |
+| AbortSignal | 🚫 | ⬆️ | Threaded through `start`/`stop`/`connect`. |
+| `export *` barrels | check | ⬆️ | Convert to explicit named exports (§6a). |
+| Test-runner imports | direct vitest | ⬆️ | Rewrite to `@suaveplan/testing/runner` (§7). |
+| 100% test coverage | 🚫 (single test file) | ⬆️ | Add unit + integration suites, 100/100/100/100. |
+| React Storybook story | ✅ (no declared dep) | ⬆️ | Move stories under `react-` aware path or drop — universal-tier discovery has no UI surface. Spec out unless we add `@suaveplan/react-network-devtools` (out of scope here). |
+| Public PeerJS server default | ⚠️ (insecure default) | ⬆️ | `host` REQUIRED in options; no public server fallback. Constructor throws `INVALID_OPTIONS` if missing. |
+
+---
+
+## Available workspace deps on genesis
+
+- `@suaveplan/network` ✅ — `DiscoveryStrategy` contract
+- `@suaveplan/network-bootstrap` ⬅ Wave 1 (chains this strategy)
+- `@suaveplan/service-discovery` ⬅ Wave 1 (registers PeerJS-discovered services)
+- `@suaveplan/types`, `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/timing` ✅
+- `@suaveplan/testing` ✅
+- External: `peerjs` — add to root catalog under `network-discovery`.
+
+**Blocking note.** Implementation can proceed once `network-bootstrap` + `service-discovery` (Wave 1) land. Until then this proposal is approved but not started.
+
+---
+
+## Acceptance gate
+
+1. `bunx turbo lint typecheck test --filter=@suaveplan/network-discovery-peerjs` green.
+2. `bunx turbo test:coverage --filter=@suaveplan/network-discovery-peerjs` 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 PeerJS as a working strategy entry.
+
+---
+
+## Out of scope
+
+- Server-side PeerJS broker hosting (deployment concern; users supply their own server URL).
+- Cross-room peer migration (covered by the WebRTC transport's mesh layer).

openspec/archive/2026-05-11-network-discovery-peerjs/tasks.md

@@ -0,0 +1,61 @@
+# Tasks — network-discovery-peerjs
+
+## Phase 1: Scaffold
+
+- [ ] 1.1 Create `packages/network/network-discovery-peerjs/` with feature-module layout.
+- [ ] 1.2 `package.json` at `0.1.0`, `"sideEffects": false`, subpath exports.
+- [ ] 1.3 Test config via `createTestConfig()`; `tests/dep-graph.test.ts`.
+- [ ] 1.4 Add `peerjs` to root `package.json` catalog (`network-discovery` group).
+
+## Phase 2: Types + errors
+
+- [ ] 2.1 Port `types.ts` → `src/types/types.ts` + sibling `.md`.
+- [ ] 2.2 `defineCodes("NET_DISC_PEERJS", [...])`: `SIGNALING_FAILED`, `PEER_CONNECT_FAILED`, `ROOM_FULL`, `INVALID_OPTIONS`, `DISPOSED`.
+- [ ] 2.3 Zod schemas for `PeerJSDiscoveryConfig`, `PeerJSMessage`, `PeerJSPeerMetadata`.
+
+## Phase 3: Core strategy
+
+- [ ] 3.1 Port `PeerJSDiscovery` orchestrator (`DiscoveryStrategy` impl).
+- [ ] 3.2 Port `PeerConnectionManager` per-peer registry.
+- [ ] 3.3 Port `RoomManager` logical rooms.
+- [ ] 3.4 Port `PeerJSConnection` `RTCDataConnection` wrapper.
+- [ ] 3.5 Port `PeerJSMessageHandlers` wire-format routing.
+- [ ] 3.6 Replace event emitter with `@suaveplan/events` `EventBus`.
+- [ ] 3.7 Replace interval loops with `@suaveplan/timing` scheduler + injectable `Clock`.
+- [ ] 3.8 Reject construction without explicit `host` option (no public-server fallback).
+- [ ] 3.9 Thread `AbortSignal` through `start`/`stop`/`connect`.
+
+## Phase 4: Observability
+
+- [ ] 4.1 Span `disc_peerjs.start`.
+- [ ] 4.2 Counter `peers_discovered_total{outcome}`.
+- [ ] 4.3 Histogram `signaling_duration_ms`.
+
+## Phase 5: Integration
+
+- [ ] 5.1 Integration test with `@suaveplan/network-bootstrap`: register PeerJS strategy, run a node against a local PeerJS broker, observe `peer:found`.
+- [ ] 5.2 Optional: register discovered peers into `@suaveplan/service-discovery`.
+
+## Phase 6: Tests + docs
+
+- [ ] 6.1 Unit tests per feature module via `@suaveplan/testing/runner`.
+- [ ] 6.2 fast-check property tests on peer dedup + room admission.
+- [ ] 6.3 100/100/100/100 coverage gate.
+- [ ] 6.4 Sibling `.md` per `.ts` impl file.
+- [ ] 6.5 Root `README.md` with basic + advanced examples.
+
+## Phase 7: Verification
+
+- [ ] 7.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-discovery-peerjs` green.
+- [ ] 7.2 `bunx turbo test:coverage --filter=@suaveplan/network-discovery-peerjs` 100/100/100/100.
+- [ ] 7.3 `bun run docs:check --filter=@suaveplan/network-discovery-peerjs` green.
+- [ ] 7.4 `MANIFEST.md` regen.
+- [ ] 7.5 `STATUS.md` row flipped from `–` to `✅`.
+
+## Pre-archive checklist
+
+- [ ] Row 1 — Phase 7 green.
+- [ ] Row 2 — Parity 🚫 list empty (or React-story exception justified).
+- [ ] Row 3 — `openspec/specs/network-discovery-peerjs/spec.md` written.
+- [ ] Row 4 — Integration test against a local PeerJS broker passes.
+- [ ] Row 5 — Folder archived.