Initial Commit

openspec/archive/2026-05-12-network-transport-hyperswarm/proposal.md

@@ -0,0 +1,89 @@
+# 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).

openspec/archive/2026-05-12-network-transport-hyperswarm/tasks.md

@@ -0,0 +1,61 @@
+# Tasks — network-transport-hyperswarm
+
+## Phase 1: Scaffold
+
+- [ ] 1.1 Create `packages/network/network-transport-hyperswarm/` with feature-module layout.
+- [ ] 1.2 `package.json` at `0.1.0`, `"sideEffects": false`, `"engines": { "node": ">=20" }`, NO `browser` field.
+- [ ] 1.3 Test config via `createTestConfig()`; `tests/dep-graph.test.ts`.
+- [ ] 1.4 Add `hyperswarm` to root catalog (`network-transport`).
+- [ ] 1.5 Open with server-tier marker comment in `src/transport/transport.ts`.
+
+## Phase 2: Types + errors
+
+- [ ] 2.1 Port `declarations.d.ts` + public types.
+- [ ] 2.2 `defineCodes("NET_HYPERSWARM", [...])`: `DHT_LOOKUP_FAILED`, `PEER_REJECTED`, `STREAM_FAILED`, `INVALID_TOPIC`, `INVALID_OPTIONS`.
+- [ ] 2.3 Zod schemas for `HyperswarmConfig`, topic input, wire frames.
+
+## Phase 3: Core
+
+- [ ] 3.1 Port `hyperswarm-context` node-local state.
+- [ ] 3.2 Port `hyperswarm-discovery` DHT topic management.
+- [ ] 3.3 Port `hyperswarm-connections` per-peer registry.
+- [ ] 3.4 Port `hyperswarm-messaging` over `@suaveplan/serialize`.
+- [ ] 3.5 Port `hyperswarm-dht-security` with tightened Zod + signed-announce enforcement.
+- [ ] 3.6 Port `hyperswarm-reputation` via `@suaveplan/feature-flags` Composite strategy.
+
+## Phase 4: Transport + plugin
+
+- [ ] 4.1 Author `HyperswarmTransport implements Transport`.
+- [ ] 4.2 Author `HyperswarmPlugin implements NetworkPlugin`.
+- [ ] 4.3 Conformance tests for both contracts.
+
+## Phase 5: Observability
+
+- [ ] 5.1 Counters `hyperswarm.connections_opened_total{outcome}`, `bytes_total{direction}`.
+- [ ] 5.2 Histograms `hyperswarm.dht_lookup_ms`, `hyperswarm.dial_ms`.
+- [ ] 5.3 Bus emissions `transport:hyperswarm:joined`/`:left`/`:connection`.
+
+## Phase 6: Tests + docs
+
+- [ ] 6.1 Unit tests via `@suaveplan/testing/runner`.
+- [ ] 6.2 fast-check property tests on topic/peer-ID validation, reputation monotonicity.
+- [ ] 6.3 Integration test with 3-peer in-process swarm (no mocks).
+- [ ] 6.4 100/100/100/100 coverage gate.
+- [ ] 6.5 Sibling `.md` per `.ts` impl file.
+- [ ] 6.6 Port `examples/` and ensure they lint+typecheck.
+- [ ] 6.7 Root `README.md`.
+
+## Phase 7: Verification
+
+- [ ] 7.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-transport-hyperswarm` green.
+- [ ] 7.2 `bunx turbo test:coverage --filter=@suaveplan/network-transport-hyperswarm` 100/100/100/100.
+- [ ] 7.3 `bun run docs:check` green.
+- [ ] 7.4 `MANIFEST.md` regen.
+- [ ] 7.5 `STATUS.md` row flipped.
+
+## Pre-archive checklist
+
+- [ ] Row 1 — Phase 7 green.
+- [ ] Row 2 — 3-peer integration test passes.
+- [ ] Row 3 — `openspec/specs/network-transport-hyperswarm/spec.md` written.
+- [ ] Row 4 — Folder archived.