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

Tasks: enterprise-server-network-gundb-server

Change ID: enterprise-server-network-gundb-server Package: @suaveplan/network-gundb-server Target path: server/network/network-gundb-server Prerequisites on Verdaccio: @suaveplan/error, @suaveplan/types, @suaveplan/logger

---

1. Scaffold

• Create directory tree per proposal.md.
• package.json at 0.1.0, "sideEffects": false, exports "." + adapter subpath.
• Deps: @suaveplan/error workspace:^, @suaveplan/types workspace:^, @suaveplan/logger workspace:^, zod catalog:forms, @opentelemetry/api catalog:observability, gun catalog:network, tslib catalog:build.
• DevDeps: vitest catalog:testing, @vitest/coverage-istanbul catalog:testing, @suaveplan/testing workspace:^.
• tsconfig.json extending library-node.json; vitest.config.ts with pool: 'forks'.
• Scripts: lint, typecheck, test, test:coverage, build, docs:check.

2. Types and errors

• Define GunServerOptions, GunServerOptionsSchema in src/types/gundb-server.types.ts.
• Write gundb-server.types.md (≥200 words).
• src/error-codes.ts: four codes; registerGunServerErrorCodes(); eager call.

3. Adapter implementation

• Implement GunServerAdapter in src/adapter/gun-server-adapter/gun-server-adapter.ts:
  • start(): create Bun HTTP server on port; pass it to Gun({ web: server, peers, file: radisk }). Wait for server to be listening; throw NETWORK_GUNDB_START_FAILED on error. OTel span.
  • stop(): stop Bun server; Gun instance cleanup. OTel span.
  • get(path): gun.get(path).once(...) wrapped in a Promise with a 5-second timeout; throw NETWORK_GUNDB_GET_TIMEOUT on timeout.
  • put(path, data): gun.get(path).put(data, ack => ...) wrapped in a Promise; throw NETWORK_GUNDB_PUT_FAILED on ack error.
  • on(path, handler): gun.get(path).on(handler); return unsubscribe fn.
  • peerCount() / isRunning() / address(): internal state getters.
  • OTel gauge network_gundb.peer_count; counter network_gundb.ops_total.
• Write gun-server-adapter.types.ts.
• Write gun-server-adapter.test.ts (≤500 lines): start/stop lifecycle; put + get round-trip; on subscription receives updates; timeout on missing key; { timeout: 30000 }.
• Write gun-server-adapter.md (≥200 words, simple + advanced, API reference).

4. Integration tests

• tests/integration.test.ts: start server on random port; second Gun instance connects as peer; put from server, verify peer receives via on; stop server, peer disconnects gracefully; { timeout: 30000 }.

5. OTel + docs

• All OTel instrumentation per proposal.
• Root README.md: quick-start server + browser client example, API table.

6. Verify and publish

• bunx turbo lint --filter=@suaveplan/network-gundb-server — zero errors.
• bunx turbo typecheck --filter=@suaveplan/network-gundb-server — zero errors.
• bunx turbo test --filter=@suaveplan/network-gundb-server — all pass.
• bunx turbo test:coverage --filter=@suaveplan/network-gundb-server — 100%.
• bun scripts/publish.ts --package @suaveplan/network-gundb-server.
• Update CLAUDE.md; archive to openspec/archive/2026-04-24-enterprise-server-network-gundb-server/.