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

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

• Create directory tree per proposal.md.
• 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
• tsconfig.json, vitest.config.ts (pool: forks).

---

2. Error codes

• Define GunDBErrorCode: GUN_RELAY_UNREACHABLE, GUN_MESSAGE_REJECTED, GUN_SIGNATURE_INVALID.
• registerGunDBErrorCodes() — call eagerly.

---

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

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

---

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

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

---

5. GunDBInitializer (src/gundb-initializer/)

• Implement relay bootstrap and room namespace setup.
• Write gundb-initializer.test.ts, gundb-initializer.md.

---

6. GunDBDiscovery (src/gundb-discovery/)

• 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.
• Wire OTel metrics.
• 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)

• Write Storybook story with react in devDeps — demonstrates live peer discovery against a local Gun relay.

---

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

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

---

9. Docs + verify

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