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

OpenSpec Change: network-discovery-crdt

• Change ID: network-discovery-crdt
• Package: @suaveplan/network-discovery-crdt
• Category: browser
• Target path: packages/network/network-discovery-crdt
• Status: PROPOSED
• Date: 2026-05-11
• Parent: network-transport-family (2026-05-11) — Wave 2
• Migration source: ../suaveplan/packages/browser/network-discovery-crdt + ../suaveplan/enterprise/network-discovery-crdt.md

---

Summary

Migrate @suaveplan/network-discovery-crdt as a browser-tier DiscoveryStrategy for @suaveplan/network. CRDT awareness layers (Yjs + Automerge) for eventually-consistent peer-metadata exchange. Two interchangeable provider backends behind a single CRDTDiscovery class.

---

Current-state audit

Upstream source layout (../suaveplan/packages/browser/network-discovery-crdt/src/):

• crdt-discovery.ts (183 L) — orchestrator
• crdt-state-manager.ts (221 L)
• crdt-peer-manager.ts (155 L)
• crdt-initializer.ts (158 L) — bootstrap
• crdt-intervals.ts (105 L) — periodic reconciliation
• automerge-discovery.ts (216 L) — Automerge provider path
• Yjs provider modules (yjs-discovery, yjs-awareness, yjs-sync)

See ../suaveplan/enterprise/network-discovery-crdt.md for full upstream surface inventory.

---

Parity Checklist

Capability	Upstream	Migrated	Notes
DiscoveryStrategy impl	✅	✅
Yjs provider	✅	✅	y-webrtc signaling + awareness.
Automerge provider	✅	✅	@automerge/automerge-repo + broadcast-channel + websocket + IndexedDB adapters.
Provider abstraction	✅	⬆️	Tightened — Yjs/Automerge selection at construction time, no runtime swap.
Structured errors	🚫	⬆️	defineCodes registry with strategy-specific codes.
Zod boundary validation	🚫	⬆️	Every public option struct.
OTel instrumentation	🚫	⬆️	Spans + counters + histograms keyed by strategy.
AbortSignal	🚫	⬆️	Threaded through start/stop/connect.
export * barrels	check	⬆️	Convert to explicit named exports per §6a.
Test-runner imports	direct vitest	⬆️	Rewrite to @suaveplan/testing/runner per §7.
100% test coverage	🚫	⬆️	Bring to 100/100/100/100.
Property tests	🚫	⬆️	fast-check property suite where applicable.

---

Available workspace deps on genesis

• @suaveplan/network ✅
• @suaveplan/network-bootstrap ⬅ Wave 1
• @suaveplan/service-discovery ⬅ Wave 1
• @suaveplan/types, @suaveplan/error, @suaveplan/events, @suaveplan/timing ✅
• @suaveplan/testing ✅
• External: yjs, y-webrtc, @automerge/automerge-repo + adapters — add to root catalog under network-discovery.

Blocking note. Wave 1 (network-bootstrap, service-discovery) must land first.

---

Acceptance gate

1. bunx turbo lint typecheck test --filter=@suaveplan/network-discovery-crdt green.
2. bunx turbo test:coverage --filter=@suaveplan/network-discovery-crdt 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 this strategy as a working entry.

---

Out of scope

• Hosting / running any required relays or trackers (deployment concern).
• React Storybook stories — discovery is a universal/headless tier; UI lives in a dedicated devtools package (future).