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

OpenSpec Change: network-discovery-gundb

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

---

Summary

Migrate @suaveplan/network-discovery-gundb as a browser-tier DiscoveryStrategy for @suaveplan/network. GunDB gossip-over-WebSocket discovery. Decentralised graph database that gossips peer metadata with eventual consistency. GunDBDiscovery + Gun node manager + initializer.

---

Current-state audit

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

• gundb-discovery.ts (244 L) — DiscoveryStrategy impl
• gun-node-manager.ts (211 L) — Gun node lifecycle
• gundb-initializer.ts (128 L) — relay/storage bootstrap
• types.ts (123 L)

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

---

Parity Checklist

Capability	Upstream	Migrated	Notes
DiscoveryStrategy impl	✅	✅
Gun-node lifecycle	✅	✅
Relay/storage bootstrap	✅	✅
Public Gun-relay defaults	⚠️ (insecure)	⬆️	Relay list REQUIRED; constructor throws INVALID_OPTIONS if missing.
Security-fragile audit	upstream flag	⬆️	Add Zod boundary on every wire payload + constant-time peer-ID compare.
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: gun — add to root catalog under network-discovery.

Blocking note. Wave 1 must land first. Security note. Upstream audit flags GunDB as security-fragile — migration tightens wire-payload validation and rejects unsigned peer announces.

---

Acceptance gate

1. bunx turbo lint typecheck test --filter=@suaveplan/network-discovery-gundb green.
2. bunx turbo test:coverage --filter=@suaveplan/network-discovery-gundb 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).