suaveplan/openspec/archive/2026-05-12-enterprise-browser-network-discovery-webtorrent/tasks.md

Tasks: enterprise-browser-network-discovery-webtorrent

Change ID: enterprise-browser-network-discovery-webtorrent Package: @suaveplan/network-discovery-webtorrent Target path: browser/network/network-discovery-webtorrent Prerequisite packages on Verdaccio: @suaveplan/network, @suaveplan/events, @suaveplan/error, @suaveplan/types, @suaveplan/crypto

---

1. Scaffold

• Create directory tree per proposal.md.
• package.json v0.0.0, "sideEffects": false.
  • dependencies: @suaveplan/network workspace:^, @suaveplan/events workspace:^, @suaveplan/error workspace:^, @suaveplan/types workspace:^, @suaveplan/crypto workspace:^, p2pt, zod catalog:forms, @opentelemetry/api catalog:observability, tslib catalog:build
  • devDependencies: vitest catalog:testing, @vitest/coverage-istanbul catalog:testing, @playwright/test catalog:testing, @suaveplan/testing workspace:^
• tsconfig.json, vitest.config.ts (pool: forks).

---

2. Error codes + schema

• WEBTORRENT_TRACKER_UNREACHABLE, WEBTORRENT_ANNOUNCE_FAILED. Register eagerly.
• P2PTPeerSchema, EnvelopeSchema (Zod); register envelope in @suaveplan/schema-registry.

---

3. P2PTAdapter interface (src/lib/p2pt-adapter/)

• Define P2PTAdapter interface mirroring p2pt's public API surface.
• Implement RealP2PTAdapter wrapping new P2PT(...).
• This adapter is the seam for unit tests — inject it rather than stubbing globals.
• Write p2pt-adapter.test.ts, p2pt-adapter.md.

---

4. TrackerHealth (src/lib/tracker-health/)

• Track per-tracker warningCount, lastWarning, healthy flag.
• On trackerwarning event, increment warning count; mark unhealthy above threshold.
• Round-robin to next healthy tracker.
• Write tracker-health.test.ts, tracker-health.md.

---

5. WebTorrentDiscovery (src/lib/network-discovery-webtorrent/)

• No describe.skip — real tests.
• Strict-mode: reject four default public trackers.
• announceId must be ≥8 chars; optionally tenant-hashed.
• Optional encryption: AES-GCM wrap messages.
• Optional signed announcements: ed25519 via @suaveplan/crypto.
• Wire TrackerHealth failover.
• Wire OTel metrics.
• Write network-discovery-webtorrent.test.ts (config, tracker selection, peer dedup, error propagation via P2PTAdapter), network-discovery-webtorrent.md, network-discovery-webtorrent.types.ts.

---

6. Integration test (tests/integration.test.ts)

• Strict-mode rejects public trackers.
• announceId too short throws typed error.
• Tracker failover: simulate trackerwarning events and verify rotation.

---

7. Playwright E2E (e2e/webtorrent-discovery.spec.ts)

• Chromium browser context connects to a real WSS WebTorrent tracker.
• Second peer announces; first peer discovers it and emits peer event.

---

8. Docs + verify

• Write .md per module; README.md with tracker threat model, enterprise deployment, strict-mode guidance.
• bunx turbo lint typecheck test --filter=@suaveplan/network-discovery-webtorrent — green.
• bunx turbo test:coverage — 100%.
• No describe.skip, no vi.stubGlobal.
• Playwright E2E discovers a real peer.
• bun scripts/publish.ts --package @suaveplan/network-discovery-webtorrent.
• Archive to openspec/archive/2026-04-24-enterprise-browser-network-discovery-webtorrent/.