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

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.