# OpenSpec Change: enterprise-server-network-hyperswarm

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

---

## Summary

Deliver `@suaveplan/network-hyperswarm` on the genesis branch from scratch at enterprise quality. The package provides a Node.js server-side transport adapter built on [Hyperswarm](https://github.com/holepunchto/hyperswarm) — a DHT-based peer discovery and encrypted connection layer. It exposes a typed `HyperswarmAdapter` with `join(topic)` / `leave(topic)` / `connect(peerId)` / `disconnect(peerId)` / `send(peerId, data)` / `onData(handler)` and full connection lifecycle events. Connections use the Noise protocol for encryption. Genesis adds `@suaveplan/error`-aligned errors, OTel spans + gauges (peer count, message throughput), retry logic, structured logging, and 100% unit + integration coverage.

---

## Current-state audit (genesis)

Does not exist on genesis — fresh build.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/error` (`workspace:^`) | Typed `NETWORK_HYPERSWARM.*` error codes |
| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `EventBusLike` |
| `@suaveplan/events` (`workspace:^`) | Internal event bus for peer events |
| `@suaveplan/retry` (`workspace:^`) | Reconnect backoff |
| `@suaveplan/logger` (`workspace:^`) | Structured logs |
| `zod` (`catalog:forms`) | Options validation |
| `@opentelemetry/api` (`catalog:observability`) | Spans + gauges |
| `hyperswarm` (`catalog:network`) | DHT peer discovery |
| `tslib` (`catalog:build`) | Runtime helpers |

---

## Public API surface

```ts
class HyperswarmAdapter {
  constructor(options: HyperswarmOptions)
  join(topic: Buffer | string): Promise<void>
  leave(topic: Buffer | string): Promise<void>
  send(peerId: string, data: Uint8Array): Promise<void>
  broadcast(topic: Buffer | string, data: Uint8Array): Promise<void>
  onData(handler: (peerId: string, data: Uint8Array) => void): () => void
  onPeerConnect(handler: (peerId: string) => void): () => void
  onPeerDisconnect(handler: (peerId: string) => void): () => void
  peers(topic?: Buffer | string): string[]
  peerCount(): number
  destroy(): Promise<void>
}

function createHyperswarmAdapter(options: HyperswarmOptions): HyperswarmAdapter

interface HyperswarmOptions {
  keyPair?: { publicKey: Buffer; secretKey: Buffer }
  maxPeers?: number         // default: 64
  firewall?: (remotePublicKey: Buffer) => boolean
  logger?: LoggerLike
}

const HyperswarmOptionsSchema: z.ZodSchema<HyperswarmOptions>

type HyperswarmErrorCode =
  | 'NETWORK_HYPERSWARM_JOIN_FAILED'
  | 'NETWORK_HYPERSWARM_SEND_FAILED'
  | 'NETWORK_HYPERSWARM_PEER_NOT_FOUND'
  | 'NETWORK_HYPERSWARM_DESTROY_FAILED'

function registerHyperswarmErrorCodes(): void
```

---

## File layout

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

---

## Impact

Downstream: decentralised network packages, peer-to-peer features in the platform. Requires Node.js and native modules — not universal.

**Prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/retry`, `@suaveplan/logger`.