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

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

Out of scope

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

4.6 KiB Raw Blame History