# Tasks: enterprise-network-bootstrap

**Change ID**: enterprise-network-bootstrap
**Package**: `@suaveplan/network-bootstrap`
**Target path**: `universal/network/network-bootstrap`
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/logger`, `@suaveplan/retry`, `@suaveplan/fsm`

---

## 1. Scaffold

- [x] Create `universal/network/network-bootstrap/` with `src/`, `tests/`, and all feature subdirectories.
- [x] Write `package.json` at version `0.1.0`: `"sideEffects": false`, exports map, deps per `proposal.md`.
- [x] Write `tsconfig.json`, `vitest.config.ts`, scripts.

---

## 2. Types and error codes

- [x] Define all public types in `src/types/common.ts`: `BootstrapConfig`, `SeedConfig`, `TopologyHint`, `BootstrapOptions`, `BootstrapState`, `BootstrapPeer`, `BootstrapResult`, `BootstrapEvent`, `BootstrapEventData`.
- [x] Write `src/types/common.md` (≥200 words, simple + advanced examples).
- [x] Define error codes in `src/error-codes.ts`.
- [x] Write Zod schemas in `src/types/schemas.ts` + `src/types/schemas.md`.

---

## 3. Peer discovery (`src/core/discovery/`)

- [x] Implement `discoverPeers(seeds: SeedConfig[], options, signal?)`:
  - Try each seed in priority order.
  - Use `@suaveplan/retry` to retry each seed up to `options.retry.maxAttempts`.
  - Return list of discovered peer addresses.
  - Throw `NetworkBootstrapError(BOOTSTRAP_SEED_UNREACHABLE)` if all seeds fail.
- [x] Write `discovery.test.ts` (≤500 lines): happy path, retry on failure, all fail throws.
- [x] Write `discovery.md` (≥200 words).

---

## 4. Peer negotiation (`src/core/negotiation/`)

- [x] Implement `negotiatePeer(address: string, port: number, config, signal?)`:
  - Connect to peer; exchange capability and topology messages.
  - Return `BootstrapPeer` with capabilities and measured latency.
  - Throw `NetworkBootstrapError(BOOTSTRAP_NEGOTIATION_FAILED)` on failure.
- [x] Write `negotiation.test.ts` + `negotiation.md`.

---

## 5. Bootstrapper (`src/core/bootstrapper/`)

- [x] Implement `createBootstrapper(config, options?)`:
  - Validates config with Zod.
  - Uses `@suaveplan/fsm` for state machine: `idle → discovering → connecting → negotiating → ready/failed`.
- [x] Implement `bootstrapper.bootstrap(signal?)`:
  - Transition FSM through phases.
  - Phase 1 (discovering): call `discoverPeers`.
  - Phase 2 (connecting): establish connections to discovered peers.
  - Phase 3 (negotiating): negotiate capabilities with each peer.
  - Resolve when `peers.length >= config.minPeers` (default 1).
  - Throw `NetworkBootstrapError(BOOTSTRAP_MIN_PEERS_NOT_MET)` if timeout elapses.
  - OTel: span `bootstrap.run`, child spans per phase, counter `bootstrap.peers_connected_total`.
- [x] Implement `bootstrapper.abort()` — transitions FSM to `aborted`, fires `AbortSignal`.
- [x] Implement `bootstrapper.on(event, handler)` — fires on FSM state transitions.
- [x] Write `bootstrapper.test.ts` (≤500 lines): full bootstrap, abort, timeout, min-peers not met.
- [x] Write `bootstrapper.md` (≥200 words).

---

## 6. Property-based tests (`tests/property.test.ts`)

- [x] State machine always reaches a terminal state (`ready`, `failed`, or `aborted`).
- [x] `peers.length >= minPeers` when result is `success: true`.
- [x] Seed priority ordering: higher-priority seeds are always tried before lower-priority ones.

---

## 7. Docs and verify

- [x] All per-file `.md` files per layout in `proposal.md`.
- [x] `universal/network/network-bootstrap/README.md`.
- [x] `bunx turbo lint typecheck test test:coverage --filter=@suaveplan/network-bootstrap` — all green, 100%.
- [x] `bun scripts/publish.ts --package @suaveplan/network-bootstrap`.
- [x] Update `CLAUDE.md`. Archive change folder.