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

Tasks — network-transport-peerjs

Phase 0: Decide split vs. fold

• 0.1 Read network-discovery-peerjs 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-peerjs/ (Option A) OR add ./transport subpath to network-discovery-peerjs (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-peerjs green.
• 7.2 bunx turbo test:coverage --filter=@suaveplan/network-transport-peerjs 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.