# 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).