# 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.