# OpenSpec Change: network-transport-hyperswarm

- **Change ID**: network-transport-hyperswarm
- **Package**: `@suaveplan/network-transport-hyperswarm`
- **Category**: server (Node-only)
- **Target path**: `packages/network/network-transport-hyperswarm`
- **Status**: PROPOSED
- **Date**: 2026-05-11
- **Parent**: `network-transport-family` (2026-05-11) — Wave 4
- **Migration source**: `../suaveplan/packages/server/network-hyperswarm` + `../suaveplan/enterprise/network-hyperswarm.md`
- **Supersedes**: the original name reservation in this folder (2026-05-11)

---

## Summary

Migrate `@suaveplan/network-hyperswarm` into genesis as `@suaveplan/network-transport-hyperswarm` — a server-tier `Transport` implementation over the [Hyperswarm](https://github.com/holepunchto/hyperswarm) DHT. Hyperswarm provides hole-punched peer-to-peer connections discovered via a Kademlia-style DHT keyed by 32-byte topics. First Wave-4 package because it's smaller in surface than libp2p and has a clearer single-purpose mission (DHT-discovered raw streams).

---

## Current-state audit

Upstream coverage: **8.98%** — major test gap. The migration writes the bulk of the test suite from scratch.

Upstream source layout (`../suaveplan/packages/server/network-hyperswarm/src/`):

- `hyperswarm-discovery.ts` — DHT topic discovery
- `hyperswarm-connections.ts` — per-peer connection registry
- `hyperswarm-messaging.ts` — wire-format encode/decode
- `hyperswarm-context.ts` — node-local state
- `hyperswarm-dht-security.ts` — DHT-level peer-ID validation
- `hyperswarm-events.ts` — typed event surface
- `hyperswarm-metrics.ts` — internal counters
- `hyperswarm-reputation.ts` — per-peer reputation tracking
- `declarations.d.ts` — Hyperswarm type augmentations
- `examples/` — usage samples

---

## Parity Checklist

| Capability | Upstream | Migrated | Notes |
|---|---|---|---|
| `Transport` contract impl | partial (Hyperswarm-shaped) | ⬆️ | Adapter wrapping `hyperswarm`'s `swarm.on('connection', ...)` into per-peer `Transport` callbacks. |
| `NetworkPlugin` wrapper | 🚫 | ⬆️ | Mirrors `WebRTCPlugin` shape. |
| DHT topic discovery | ✅ | ✅ | |
| Per-peer connection registry | ✅ | ✅ | |
| Wire-format encode/decode | ✅ | ✅ | Re-use `@suaveplan/serialize` length-prefix encoding. |
| Hole-punching | ✅ (Hyperswarm built-in) | ✅ | |
| DHT-security peer-ID validation | ✅ | ⬆️ | Tightened — Zod boundary on every wire frame; reject unsigned peer announces. |
| Per-peer reputation | ✅ | ✅ | Replaced with `@suaveplan/feature-flags` Composite strategy (re-use reputation pattern). |
| Internal metrics | ✅ (ad-hoc) | ⬆️ | Replaced with OTel: counters `hyperswarm.connections_opened_total{outcome}`, `hyperswarm.bytes_total{direction}`, histograms `hyperswarm.dht_lookup_ms`, `hyperswarm.dial_ms`. |
| Structured errors | 🚫 | ⬆️ | `defineCodes("NET_HYPERSWARM", [...])`: `DHT_LOOKUP_FAILED`, `PEER_REJECTED`, `STREAM_FAILED`, `INVALID_TOPIC`, `INVALID_OPTIONS`. |
| Zod boundary validation | 🚫 | ⬆️ | Every public option struct + wire frames. |
| AbortSignal | 🚫 | ⬆️ | Threaded through `join`/`leave`/`connect`. |
| `export *` barrels | check | ⬆️ | Convert to explicit named exports per §6a. |
| Test-runner imports | direct vitest | ⬆️ | Rewrite to `@suaveplan/testing/runner` per §7. |
| 100% test coverage | 🚫 (8.98%) | ⬆️ | Bring to 100/100/100/100 — major test-writing effort. |
| Integration tests | 🚫 | ⬆️ | Spin up a 3-peer in-process swarm via the real `hyperswarm` package (no mocks). |
| `examples/` | ✅ | ✅ | Keep — useful as runnable docs; lint-cleaned. |

---

## Available workspace deps on genesis

- `@suaveplan/network` ✅
- `@suaveplan/network-plugin-transport-manager` ✅
- `@suaveplan/serialize` ✅
- `@suaveplan/feature-flags` ✅ (reputation scoring)
- `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/retry`, `@suaveplan/timing` ✅
- `@suaveplan/testing` ✅
- External: `hyperswarm` (large transitive native deps) — add to root catalog under `network-transport`. Node-only — `package.json` declares `"engines": { "node": ">=20" }` and omits the `browser` field.

---

## Acceptance gate

1. `bunx turbo lint typecheck test --filter=@suaveplan/network-transport-hyperswarm` green.
2. `bunx turbo test:coverage --filter=@suaveplan/network-transport-hyperswarm` 100/100/100/100.
3. `bun run docs:check` green.
4. Integration test: 3 nodes join same DHT topic, all-to-all envelope exchange completes successfully.
5. `STATUS.md` row flipped.

---

## Out of scope

- Browser support (Hyperswarm is Node-only).
- DHT bootstrap-node hosting (deployment concern).