Initial Commit

openspec/archive/2026-05-12-enterprise-network-bootstrap/tasks.md

@@ -0,0 +1,83 @@
+# 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.