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

Tasks: enterprise-browser-network-discovery-hybrid

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

---

1. Scaffold

• Create directory tree per proposal.md.
• package.json at version 0.1.0, "sideEffects": false.
  • dependencies: @suaveplan/network workspace:^, @suaveplan/error workspace:^, @suaveplan/types workspace:^, zod catalog:forms, @opentelemetry/api catalog:observability, tslib catalog:build
  • peerDependencies + peerDependenciesMeta.optional: true: @suaveplan/network-discovery-peerjs, @suaveplan/network-discovery-trystero, @suaveplan/network-discovery-webtorrent, @suaveplan/network-discovery-crdt, @suaveplan/network-discovery-gundb
  • devDependencies: above five sibling packages as workspace:^, vitest catalog:testing, @vitest/coverage-istanbul catalog:testing, @suaveplan/testing workspace:^, react catalog:browser, @types/react catalog:browser
• tsconfig.json, vitest.config.ts (pool: forks).

---

2. Error codes

• STRATEGY_LOAD_FAILED, STRATEGY_UNAVAILABLE, HYBRID_NO_HEALTHY_STRATEGY.
• registerHybridErrorCodes() — call eagerly.

---

3. In-tree MemoryDiscoveryStrategy (src/internal/memory-discovery-strategy.ts)

• Implement a minimal DiscoveryStrategy for unit tests — typed correctly against the real interface, no duck typing.

---

4. PeerTracker (src/peer-tracker/)

• Implement deduplication of peer sets across strategies; track PeerSource per peer.
• Write peer-tracker.test.ts, peer-tracker.md.

---

5. StrategyLoader (src/strategy-loader/)

• Implement dynamic peer-dep loading: check if the package is present in the module graph; return STRATEGY_LOAD_FAILED typed error if missing — never returns null silently.
• Write strategy-loader.test.ts, strategy-loader.md.

---

6. StrategyManager (src/strategy-manager/)

• Implement health tracking, priority tie-breaking (alphabetical on equal score), back-pressure per strategy.
• Wire OTel counters for strategy health transitions.
• Write strategy-manager.test.ts, strategy-manager.md.

---

7. Lifecycle (src/lifecycle/)

• Implement start/stop sequencing across all strategies with timeout per strategy.
• Wire OTel histogram discovery.hybrid.failover_ms.
• Write lifecycle.test.ts, lifecycle.md.

---

8. HybridDiscoveryManager (src/hybrid-discovery-manager/)

• Implement orchestrator composing all sub-modules.
• static presets.browserP2P() returning a HybridDiscoveryConfig wiring PeerJS + Trystero.
• Write hybrid-discovery-manager.test.ts, hybrid-discovery-manager.md, hybrid-discovery-manager.types.ts.

---

9. Presets (src/presets/)

• Implement presets object with browserP2P().
• Write presets.md.

---

10. Tests (all ≤500 lines each)

• tests/config.test.ts — config schema validation.
• tests/config-advanced.test.ts — priority ordering, back-pressure, tie-breaking.
• tests/runtime.test.ts — start/stop, failover, peer dedup.
• tests/runtime-failover.test.ts — strategy degraded → failover → recovery.
• All tests use real MemoryDiscoveryStrategy or real sibling packages — no __mocks__/.

---

11. Zod schema + docs

• HybridDiscoveryConfigSchema; register in @suaveplan/schema-registry.
• Story (src/hybrid-discovery-manager/hybrid-discovery.stories.tsx) with React devDep declared.
• Write .md per module; README.md with sibling install matrix.

---

12. Verify and publish

• bunx turbo lint typecheck test --filter=@suaveplan/network-discovery-hybrid — green.
• bunx turbo test:coverage — 100%.
• No __mocks__/ directory, no vi.mock, no any.
• Missing-peer-dep scenario returns typed error (not silent null).
• bun scripts/publish.ts --package @suaveplan/network-discovery-hybrid.
• Archive to openspec/archive/2026-04-24-enterprise-browser-network-discovery-hybrid/.