OpenSpec Change: enterprise-server-network-gundb-server

Change ID: enterprise-server-network-gundb-server
Package: @suaveplan/network-gundb-server
Category: server/network
Target path: server/network/network-gundb-server
Status: SUPERSEDED-BY-GENESIS-WAVE
Date: 2026-04-24
Reference spec: /mnt/s/web/suaveplan/enterprise/network-gundb-server.md

Summary

Deliver @suaveplan/network-gundb-server on the genesis branch from scratch at enterprise quality. The package runs a Gun.js relay server over WebSockets, enabling decentralised real-time data sync for browser and server peers. It wraps Gun's GUN({web: server}) pattern into a typed GunServerAdapter with start / stop, get / put / on / off for direct data operations on the server side, and connection-count observability. Genesis adds Zod-validated options, @suaveplan/error codes, OTel gauges, structured logging, and full integration tests.

Current-state audit (genesis)

Does not exist on genesis — fresh build.

Available workspace deps on genesis

Package	Role
`@suaveplan/error` (`workspace:^`)	Typed `NETWORK_GUNDB.*` error codes
`@suaveplan/types` (`workspace:^`)	`LoggerLike`
`@suaveplan/logger` (`workspace:^`)	Structured logs
`zod` (`catalog:forms`)	Options validation
`@opentelemetry/api` (`catalog:observability`)	Gauges + counters
`gun` (`catalog:network`)	Gun.js database/relay
`tslib` (`catalog:build`)	Runtime helpers

Public API surface

class GunServerAdapter {
  constructor(options: GunServerOptions)
  start(): Promise<void>
  stop(): Promise<void>
  get<T = unknown>(path: string): Promise<T | undefined>
  put(path: string, data: unknown): Promise<void>
  on<T = unknown>(path: string, handler: (data: T, key: string) => void): () => void
  peerCount(): number
  isRunning(): boolean
  address(): { host: string; port: number } | undefined
}

function createGunServerAdapter(options: GunServerOptions): GunServerAdapter

interface GunServerOptions {
  port?: number              // default: 8765
  host?: string              // default: '0.0.0.0'
  peers?: string[]           // bootstrap relay URLs
  radisk?: boolean           // persist to disk, default: false
  logger?: LoggerLike
}

const GunServerOptionsSchema: z.ZodSchema<GunServerOptions>

type GunServerErrorCode =
  | 'NETWORK_GUNDB_START_FAILED'
  | 'NETWORK_GUNDB_STOP_FAILED'
  | 'NETWORK_GUNDB_PUT_FAILED'
  | 'NETWORK_GUNDB_GET_TIMEOUT'

function registerGunServerErrorCodes(): void

File layout

server/network/network-gundb-server/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    error-codes.ts
    constants/index.ts
    types/
      gundb-server.types.ts
      gundb-server.types.md
    adapter/
      gun-server-adapter/
        gun-server-adapter.ts
        gun-server-adapter.md
        gun-server-adapter.types.ts
        gun-server-adapter.test.ts
        index.ts
  tests/
    integration.test.ts

Impact

Downstream: real-time sync features, collaborative editing, offline-first client sync. Server-only.

Prerequisites on Verdaccio: @suaveplan/error, @suaveplan/types, @suaveplan/logger.

3.2 KiB Raw Blame History