# 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

```ts
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

```text
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`.