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

Tasks: enterprise-server-network-libp2p-server

Change ID: enterprise-server-network-libp2p-server Package: @suaveplan/network-libp2p-server Target path: server/network/network-libp2p-server 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: all workspace and catalog deps listed in proposal.
• DevDeps: vitest catalog:testing, @vitest/coverage-istanbul catalog:testing, @suaveplan/testing workspace:^.
• tsconfig.json extending library-node.json; vitest.config.ts with pool: 'forks', setupFiles: ['@suaveplan/testing/polyfills'].
• Scripts: lint, typecheck, test, test:coverage, build, docs:check.

2. Types and errors

• Define Libp2pServerOptions, Libp2pServerOptionsSchema in src/types/libp2p-server.types.ts.
• Write libp2p-server.types.md (≥200 words).
• src/error-codes.ts: four codes with metadata; registerLibp2pErrorCodes(); eager call.

3. Adapter implementation

• Implement Libp2pServerAdapter in src/adapter/libp2p-server-adapter/libp2p-server-adapter.ts:
  • Constructor builds createLibp2p({...}) config from options — TCP + WS transports, Noise, Yamux, KadDHT (when dhtEnabled), GossipSub (when gossipEnabled).
  • start(): await node.start(); throw NETWORK_LIBP2P_START_FAILED on error; OTel span.
  • stop(): await node.stop(); unsubscribe all handlers; OTel span.
  • peerId() / multiaddrs() / peers(): delegate to libp2p node.
  • dialPeer(multiaddr): retry up to maxRetries with @suaveplan/retry; throw NETWORK_LIBP2P_DIAL_FAILED on exhaustion; OTel span.
  • subscribe(topic, handler): GossipSub topic subscription; return unsubscribe fn.
  • publish(topic, data): GossipSub publish; throw NETWORK_LIBP2P_PUBLISH_FAILED on error.
  • OTel gauge network_libp2p.peer_count; counter network_libp2p.messages_total.
• Write libp2p-server-adapter.types.ts with internal types.
• Write libp2p-server-adapter.test.ts (≤500 lines): two in-process nodes; start/stop lifecycle; dial + subscribe + publish round-trip; peer count updates; { timeout: 30000 }.
• Write libp2p-server-adapter.md (≥200 words, simple + advanced, API reference).

4. Integration tests

• tests/integration.test.ts: three-node mesh — each node subscribes same topic, one publishes, others receive; graceful stop propagates disconnect event; { timeout: 30000 }.

5. OTel + docs

• All OTel instrumentation per proposal.
• Root README.md: quick-start two-node example, subscribe/publish example, bootstrap peers setup, API table.

6. Verify and publish

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