Initial Commit

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

@@ -0,0 +1,81 @@
+# 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
+
+- [x] Create directory tree per `proposal.md`.
+- [x] `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:^`
+- [x] `tsconfig.json`, `vitest.config.ts` (pool: forks).
+
+---
+
+## 2. Error codes + schema
+
+- [x] `WEBTORRENT_TRACKER_UNREACHABLE`, `WEBTORRENT_ANNOUNCE_FAILED`. Register eagerly.
+- [x] `P2PTPeerSchema`, `EnvelopeSchema` (Zod); register envelope in `@suaveplan/schema-registry`.
+
+---
+
+## 3. `P2PTAdapter` interface (`src/lib/p2pt-adapter/`)
+
+- [x] Define `P2PTAdapter` interface mirroring `p2pt`'s public API surface.
+- [x] Implement `RealP2PTAdapter` wrapping `new P2PT(...)`.
+- [x] This adapter is the seam for unit tests — inject it rather than stubbing globals.
+- [x] Write `p2pt-adapter.test.ts`, `p2pt-adapter.md`.
+
+---
+
+## 4. `TrackerHealth` (`src/lib/tracker-health/`)
+
+- [x] Track per-tracker `warningCount`, `lastWarning`, `healthy` flag.
+- [x] On `trackerwarning` event, increment warning count; mark unhealthy above threshold.
+- [x] Round-robin to next healthy tracker.
+- [x] Write `tracker-health.test.ts`, `tracker-health.md`.
+
+---
+
+## 5. `WebTorrentDiscovery` (`src/lib/network-discovery-webtorrent/`)
+
+- [x] No `describe.skip` — real tests.
+- [x] Strict-mode: reject four default public trackers.
+- [x] `announceId` must be ≥8 chars; optionally tenant-hashed.
+- [x] Optional encryption: AES-GCM wrap messages.
+- [x] Optional signed announcements: ed25519 via `@suaveplan/crypto`.
+- [x] Wire `TrackerHealth` failover.
+- [x] Wire OTel metrics.
+- [x] 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`)
+
+- [x] Strict-mode rejects public trackers.
+- [x] `announceId` too short throws typed error.
+- [x] Tracker failover: simulate `trackerwarning` events and verify rotation.
+
+---
+
+## 7. Playwright E2E (`e2e/webtorrent-discovery.spec.ts`)
+
+- [x] Chromium browser context connects to a real WSS WebTorrent tracker.
+- [x] Second peer announces; first peer discovers it and emits `peer` event.
+
+---
+
+## 8. Docs + verify
+
+- [x] Write `.md` per module; `README.md` with tracker threat model, enterprise deployment, strict-mode guidance.
+- [x] `bunx turbo lint typecheck test --filter=@suaveplan/network-discovery-webtorrent` — green.
+- [x] `bunx turbo test:coverage` — 100%.
+- [x] No `describe.skip`, no `vi.stubGlobal`.
+- [x] Playwright E2E discovers a real peer.
+- [x] `bun scripts/publish.ts --package @suaveplan/network-discovery-webtorrent`.
+- [x] Archive to `openspec/archive/2026-04-24-enterprise-browser-network-discovery-webtorrent/`.