# OpenSpec Change: enterprise-server-network-trystero-server

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

---

## Summary

Deliver `@suaveplan/network-trystero-server` on the genesis branch from scratch at enterprise quality. Trystero enables serverless WebRTC mesh networking using public signalling infrastructure (BitTorrent DHT, Nostr, Firebase, MQTT, Supabase). This server-side package provides a Node.js host that can act as a persistent relay peer within a Trystero room — bridging browser peers, relaying data, and optionally recording room state. It wraps Trystero's `joinRoom` API into a typed `TrysteroServerAdapter` with room lifecycle, peer events, typed data channels, and full OTel observability.

---

## Current-state audit (genesis)

Does not exist on genesis — fresh build.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/error` (`workspace:^`) | Typed `NETWORK_TRYSTERO.*` error codes |
| `@suaveplan/types` (`workspace:^`) | `LoggerLike` |
| `@suaveplan/events` (`workspace:^`) | Internal event routing |
| `@suaveplan/logger` (`workspace:^`) | Structured logs |
| `zod` (`catalog:forms`) | Options validation |
| `@opentelemetry/api` (`catalog:observability`) | Gauges + counters |
| `trystero` (`catalog:network`) | WebRTC signalling library |
| `tslib` (`catalog:build`) | Runtime helpers |

---

## Public API surface

```ts
class TrysteroServerAdapter {
  constructor(options: TrysteroServerOptions)
  join(roomId: string): Promise<void>
  leave(roomId: string): Promise<void>
  send(roomId: string, channelName: string, data: unknown, peerId?: string): void
  onData(roomId: string, channelName: string, handler: (data: unknown, peerId: string) => void): () => void
  onPeerJoin(roomId: string, handler: (peerId: string) => void): () => void
  onPeerLeave(roomId: string, handler: (peerId: string) => void): () => void
  peers(roomId: string): string[]
  leaveAll(): Promise<void>
}

function createTrysteroServerAdapter(options: TrysteroServerOptions): TrysteroServerAdapter

interface TrysteroServerOptions {
  strategy: 'torrent' | 'nostr' | 'mqtt' | 'supabase'
  appId: string
  password?: string
  relayUrls?: string[]      // for nostr / mqtt strategies
  logger?: LoggerLike
}

const TrysteroServerOptionsSchema: z.ZodSchema<TrysteroServerOptions>

type TrysteroErrorCode =
  | 'NETWORK_TRYSTERO_JOIN_FAILED'
  | 'NETWORK_TRYSTERO_SEND_FAILED'
  | 'NETWORK_TRYSTERO_LEAVE_FAILED'
  | 'NETWORK_TRYSTERO_STRATEGY_UNSUPPORTED'

function registerTrysteroErrorCodes(): void
```

---

## File layout

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

---

## Impact

Downstream: browser-to-server WebRTC bridge, real-time multiplayer relay. Requires Node.js and network access for integration tests.

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