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

Tasks: enterprise-server-network-hyperswarm

Change ID: enterprise-server-network-hyperswarm Package: @suaveplan/network-hyperswarm Target path: server/network/network-hyperswarm Prerequisites on Verdaccio: @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/retry, @suaveplan/logger

---

1. Scaffold

• Create directory tree per proposal.md.
• package.json at 0.1.0, "sideEffects": false, exports "." + adapter subpath.
• Deps: @suaveplan/error workspace:^, @suaveplan/types workspace:^, @suaveplan/events workspace:^, @suaveplan/retry workspace:^, @suaveplan/logger workspace:^, zod catalog:forms, @opentelemetry/api catalog:observability, hyperswarm catalog:network, tslib catalog:build.
• DevDeps: vitest catalog:testing, @vitest/coverage-istanbul catalog:testing, @suaveplan/testing workspace:^.
• tsconfig.json extending library-node.json; vitest.config.ts with createTestConfig() and pool: 'forks'.
• Scripts: lint, typecheck, test, test:coverage, build, docs:check.

2. Types and errors

• Define HyperswarmOptions, HyperswarmOptionsSchema, peer event handler types in src/types/hyperswarm.types.ts.
• Write hyperswarm.types.md (≥200 words).
• src/error-codes.ts: all four error codes with metadata; registerHyperswarmErrorCodes(); eager call.

3. Adapter implementation

• Implement HyperswarmAdapter in src/adapter/hyperswarm-adapter/hyperswarm-adapter.ts:
  • Constructor creates new Hyperswarm({ keyPair, maxPeers, firewall }); validates options via HyperswarmOptionsSchema; registers event listeners.
  • join(topic): swarm.join(toBuffer(topic)) + await swarm.flush(); throws NETWORK_HYPERSWARM_JOIN_FAILED on error.
  • leave(topic): swarm.leave(toBuffer(topic)).
  • send(peerId, data): find connection in internal map; write data; throws NETWORK_HYPERSWARM_PEER_NOT_FOUND if not connected.
  • broadcast(topic, data): iterate all peers in topic; send to each.
  • onData / onPeerConnect / onPeerDisconnect: register listeners via internal EventEmitter; return unsubscribe fn.
  • peers(topic?): return peer IDs for topic or all.
  • peerCount(): total connected peers.
  • destroy(): await swarm.destroy().
  • OTel gauge network_hyperswarm.peer_count; counter network_hyperswarm.messages_total; span per join / send.
• Export createHyperswarmAdapter(options).
• Write hyperswarm-adapter.types.ts with internal connection-map types.
• Write hyperswarm-adapter.test.ts (≤500 lines): unit tests with real Hyperswarm instances on loopback (two adapters connecting to each other) — no mocks; send/receive round-trip, peer lifecycle events, destroy cleanup. Skip tests if SKIP_NETWORK_TESTS=1.
• Write hyperswarm-adapter.md (≥200 words, simple + advanced, API reference).

4. Integration tests

• tests/integration.test.ts: multi-peer mesh test — three adapters join same topic, each sends to others, verify all receive; one adapter destroys, others emit disconnect; { timeout: 30000 }.

5. OTel + docs

• Gauge network_hyperswarm.peer_count updated on connect/disconnect.
• Counter network_hyperswarm.messages_total with direction (sent/received).
• Span network_hyperswarm.join and network_hyperswarm.send.
• Root README.md: quick-start, key-pair generation example, multi-peer mesh example, API table.

6. Verify and publish

• bunx turbo lint --filter=@suaveplan/network-hyperswarm — zero errors.
• bunx turbo typecheck --filter=@suaveplan/network-hyperswarm — zero errors.
• bunx turbo test --filter=@suaveplan/network-hyperswarm — all pass.
• bunx turbo test:coverage --filter=@suaveplan/network-hyperswarm — 100%.
• bun scripts/publish.ts --package @suaveplan/network-hyperswarm.
• Update CLAUDE.md; archive to openspec/archive/2026-04-24-enterprise-server-network-hyperswarm/.