# Tasks: enterprise-browser-network-discovery-gundb

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

---

## 1. Scaffold

- [x] Create directory tree per `proposal.md`.
- [x] `package.json` at version `0.1.0`; `sideEffects` accurately reflects Gun's import-time effects.
  - `dependencies`: `@suaveplan/network workspace:^`, `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `@suaveplan/crypto workspace:^`, `gun`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`, `tslib catalog:build`
  - `devDependencies`: `vitest catalog:testing`, `@vitest/coverage-istanbul catalog:testing`, `@suaveplan/testing workspace:^`, `react catalog:browser`, `@types/react catalog:browser`
- [x] `tsconfig.json`, `vitest.config.ts` (pool: forks).

---

## 2. Error codes

- [x] Define `GunDBErrorCode`: `GUN_RELAY_UNREACHABLE`, `GUN_MESSAGE_REJECTED`, `GUN_SIGNATURE_INVALID`.
- [x] `registerGunDBErrorCodes()` — call eagerly.

---

## 3. GunDB schema (`src/schema/gundb-schema/`)

- [x] `GunDBMessageSchema` (Zod): `{ type: GunDBMessageType, peerId: string, metadata: GunDBPeerMetadata, signature?: string, timestamp: number }`.
- [x] `GunDBPeerMetadataSchema` (Zod): peer addresses, protocols, capabilities.
- [x] Register in `@suaveplan/schema-registry`.
- [x] Write `gundb-schema.md`.

---

## 4. GunNodeManager (`src/gun-node-manager/`)

- [x] Implement `GunNodeManager`: create Gun instance with explicit peer list; expose `get`/`put`/`on` wrappers.
- [x] Strict-mode: if `peers` empty and `strict: true`, throw `GUN_RELAY_UNREACHABLE` before Gun is created.
- [x] Write `gun-node-manager.test.ts` against a local Gun relay instance, `gun-node-manager.md`.

---

## 5. GunDBInitializer (`src/gundb-initializer/`)

- [x] Implement relay bootstrap and room namespace setup.
- [x] Write `gundb-initializer.test.ts`, `gundb-initializer.md`.

---

## 6. GunDBDiscovery (`src/gundb-discovery/`)

- [x] Implement `GunDBDiscovery`:
  - On write: sign metadata with `@suaveplan/crypto` ed25519 when `config.sign: true`.
  - On read: verify signature; drop with `GUN_SIGNATURE_INVALID` if invalid.
  - Validate every incoming message with `GunDBMessageSchema`; drop + emit metric on failure.
  - Rate limit: track updates per peer per second; drop excess.
- [x] Wire OTel metrics.
- [x] Write `gundb-discovery.test.ts` (sign/verify, strict-mode, malformed drop, rate limit), `gundb-discovery.md`, `gundb-discovery.types.ts`.

---

## 7. Story (`src/gundb-discovery/gundb-discovery.stories.tsx`)

- [x] Write Storybook story with `react` in devDeps — demonstrates live peer discovery against a local Gun relay.

---

## 8. Integration test (`tests/integration.test.ts`)

- [x] Two `GunDBDiscovery` instances against a local Gun relay; assert discovery event fires.
- [x] Strict-mode: empty `peers` throws typed error.
- [x] Signed metadata: a discovery instance without a matching key drops the peer.

---

## 9. Docs + verify

- [x] Write `.md` per module; `README.md` with strict-mode + relay-list deployment guidance.
- [x] `bunx turbo lint typecheck test --filter=@suaveplan/network-discovery-gundb` — green.
- [x] `bunx turbo test:coverage` — 100%.
- [x] `sideEffects` accurately declared (check Gun's effects; may need `["./dist/index.js"]`).
- [x] Story builds cleanly.
- [x] `bun scripts/publish.ts --package @suaveplan/network-discovery-gundb`.
- [x] Archive to `openspec/archive/2026-04-24-enterprise-browser-network-discovery-gundb/`.