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

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

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

---

2. Types and error codes

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

---

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

• 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.
• Write discovery.test.ts (≤500 lines): happy path, retry on failure, all fail throws.
• Write discovery.md (≥200 words).

---

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

• 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.
• Write negotiation.test.ts + negotiation.md.

---

5. Bootstrapper (src/core/bootstrapper/)

• Implement createBootstrapper(config, options?):
  • Validates config with Zod.
  • Uses @suaveplan/fsm for state machine: idle → discovering → connecting → negotiating → ready/failed.
• 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.
• Implement bootstrapper.abort() — transitions FSM to aborted, fires AbortSignal.
• Implement bootstrapper.on(event, handler) — fires on FSM state transitions.
• Write bootstrapper.test.ts (≤500 lines): full bootstrap, abort, timeout, min-peers not met.
• Write bootstrapper.md (≥200 words).

---

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

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

---

7. Docs and verify

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