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

Tasks — network-transport-libp2p

Phase 1: Scaffold

• 1.1 Create packages/network/network-transport-libp2p/ with feature-module layout.
• 1.2 package.json at 0.1.0, "sideEffects": false, universal-tier (no browser restriction, no React deps).
• 1.3 Test config via createTestConfig(); tests/dep-graph.test.ts.
• 1.4 Add 14 libp2p subpackages to root catalog under network-transport group.

Phase 2: Demo extraction (PRE-WORK)

• 2.1 Open Wave-7 proposal react-network-libp2p-demo reserving the destination package.
• 2.2 Do NOT port libp2p-demo.tsx or libp2p-demo.stories.tsx into this package.
• 2.3 Verify package has zero react / react-dom references.

Phase 3: Types + errors

• 3.1 Port libp2p.types.ts → src/types/types.ts + sibling .md.
• 3.2 defineCodes("NET_LIBP2P", [...]): BOOTSTRAP_FAILED, DIAL_FAILED, STREAM_FAILED, PROTOCOL_NOT_SUPPORTED, IDENTIFY_REJECTED, INVALID_OPTIONS.
• 3.3 Zod schemas for Libp2pConfig + sub-transport configs.
• 3.4 Reject construction without explicit bootstrap list (throws INVALID_OPTIONS).

Phase 4: Core libp2p stack

• 4.1 Port libp2p-connection.ts — node create + dial lifecycle.
• 4.2 Port libp2p-messaging.ts — stream-based request/response.
• 4.3 Port peer-message.ts — wire format over @suaveplan/serialize.
• 4.4 Port send-to-peer.ts — addressed-send helpers.
• 4.5 Port stream-handler.ts — protocol handler registration.

Phase 5: Transport + plugin

• 5.1 Author Libp2pTransport implements Transport.
• 5.2 Author Libp2pPlugin implements NetworkPlugin.
• 5.3 Conformance tests for both contracts.

Phase 6: Test refactor

• 6.1 DELETE upstream duplicate network-libp2p.spec.ts (.spec.ts is Playwright-only per CLAUDE.md).
• 6.2 Split upstream 505-line network-libp2p.test.ts into ≤500-line files by responsibility.
• 6.3 Author unit tests for libp2p-connection, libp2p-messaging, send-to-peer, stream-handler, peer-message.

Phase 7: Observability

• 7.1 Counters libp2p.connections_opened_total{outcome}, streams_opened_total, bytes_total{direction}.
• 7.2 Histograms libp2p.dial_ms, libp2p.stream_ttfb_ms.
• 7.3 Bus emissions transport:libp2p:dial/:identify/:stream.

Phase 8: Tests + docs

• 8.1 fast-check property tests on multiaddr parsing + peer-ID round-trip.
• 8.2 Integration test: 2-peer webrtc dial + 2-peer websockets dial, both round-trip envelope.
• 8.3 100/100/100/100 coverage gate.
• 8.4 Sibling .md per .ts impl file.
• 8.5 No file > 300 LOC source or > 500 LOC test.
• 8.6 Root README.md with sub-transport selection examples.

Phase 9: Verification

• 9.1 bunx turbo lint typecheck test --filter=@suaveplan/network-transport-libp2p green.
• 9.2 bunx turbo test:coverage --filter=@suaveplan/network-transport-libp2p 100/100/100/100.
• 9.3 bun run docs:check green.
• 9.4 Zero React imports in src/.
• 9.5 MANIFEST.md regen.
• 9.6 STATUS.md row flipped.

Pre-archive checklist

• Row 1 — Phase 9 green.
• Row 2 — Demo extraction confirmed (no React in this package).
• Row 3 — Integration test against real libp2p stack passes.
• Row 4 — openspec/specs/network-transport-libp2p/spec.md written.
• Row 5 — Folder archived.