Initial Commit

openspec/archive/2026-05-11-network-bootstrap/proposal.md

@@ -0,0 +1,94 @@
+# OpenSpec Change: network-bootstrap
+
+- **Change ID**: network-bootstrap
+- **Package**: `@suaveplan/network-bootstrap`
+- **Category**: universal
+- **Target path**: `packages/network/network-bootstrap`
+- **Status**: PROPOSED
+- **Date**: 2026-05-11
+- **Parent**: `network-transport-family` (2026-05-11) — Wave 1
+- **Migration source**: `../suaveplan/packages/universal/network-bootstrap` + `../suaveplan/enterprise/network-bootstrap.md`
+
+---
+
+## Summary
+
+Migrate `@suaveplan/network-bootstrap` into genesis as a universal-tier plugin providing initial-peer discovery and bootstrap orchestration for the `@suaveplan/network` mesh. Upstream ships at 99.15% coverage with a working `BootstrapPlugin`, discovery-chain, peer cache, and bootstrap middleware. This migration ports the full surface, hardens it against genesis primitives (`@suaveplan/retry`, `@suaveplan/events`, `@suaveplan/types`, OTel), and converts upstream `export *` barrels to explicit named exports per AGENTS.md §6a.
+
+`network-bootstrap` is Wave 1 of the network migration sequence because every concrete transport in Waves 3–4 (`hyperswarm`, `libp2p`, `gundb`, …) consumes a bootstrap chain to find initial peers. Landing it first unblocks every downstream transport.
+
+---
+
+## Why this is needed
+
+`@suaveplan/network` ✅ defines `NetworkPlugin` lifecycle and `NetworkBus` but does NOT define how a freshly-started node finds its first peers. Today every transport would have to roll its own initial-peer logic — duplicated code and inconsistent retry/cache semantics. `network-bootstrap` is the canonical place: pluggable discovery chain, exponential-backoff retries, persistent peer cache, deterministic peer selection.
+
+---
+
+## Current-state audit
+
+Upstream surface (`../suaveplan/packages/universal/network-bootstrap/src/`):
+
+- `core/discovery-chain/` — ordered chain of `DiscoveryStrategy` implementations, first-match-wins with fallthrough
+- `core/peer-cache/` — persistent cache of known-good peer endpoints (TTL + eviction)
+- `plugin/bootstrap-plugin/` — `NetworkPlugin` wrapper that wires the discovery chain into node startup
+- `plugin/bootstrap-middleware/` — middleware hook for runtime augmentation of the chain
+- `types/bootstrap.types.ts` — `DiscoveryStrategy`, `BootstrapResult`, `PeerCacheEntry`, options
+
+Upstream coverage: 99.15% statement, no E2E. Upstream depends on its own ad-hoc retry/event utilities that genesis already replaces.
+
+---
+
+## Parity Checklist
+
+| Capability | Upstream | Migrated | Notes |
+|---|---|---|---|
+| `DiscoveryStrategy` interface | ✅ | ✅ | Re-exported from `@suaveplan/types` if shared, else local. |
+| `DiscoveryChain` ordered execution | ✅ | ✅ | First-success-wins, configurable fallthrough on error vs. empty result. |
+| `PeerCache` with TTL + eviction | ✅ | ✅ | Backed by `@suaveplan/storage` `AbstractStorage` (universal); upstream's bespoke cache replaced. |
+| `BootstrapPlugin` (NetworkPlugin lifecycle) | ✅ | ✅ | `install`/`start`/`stop`/`dispose` per `@suaveplan/network`'s contract. |
+| Bootstrap middleware hook | ✅ | ✅ | Runtime augmentation of chain order/contents. |
+| Retry with backoff | ✅ (ad-hoc) | ⬆️ | Replaced with `@suaveplan/retry` `RetryPolicy` + jitter. |
+| Bus events on join/fail | ✅ (ad-hoc) | ⬆️ | Replaced with `@suaveplan/events` `NetworkBus` topics (`bootstrap:started`, `:peer-found`, `:exhausted`). |
+| Structured errors | 🚫 (plain Error) | ⬆️ | `defineCodes("NET_BOOTSTRAP", [...])` per AGENTS.md. Codes: `CHAIN_EXHAUSTED`, `CACHE_CORRUPTED`, `STRATEGY_TIMEOUT`, `INVALID_OPTIONS`. |
+| Zod boundary validation | 🚫 | ⬆️ | Every public option struct gets a Zod schema. |
+| OTel instrumentation | 🚫 | ⬆️ | Spans (`bootstrap.chain.execute`), counters (`bootstrap.peers_found_total{strategy}`, `bootstrap.failures_total{strategy,code}`), histograms (`bootstrap.chain_duration_ms`). |
+| AbortSignal support | 🚫 | ⬆️ | Threaded through every async path. |
+| `export *` barrels | ✅ (some) | ⬆️ | Converted to explicit named exports per AGENTS.md §6a. |
+| Test-runner imports | direct vitest | ⬆️ | Rewritten to `@suaveplan/testing/runner` per AGENTS.md §7. |
+| 100% test coverage | 🚫 (99.15%) | ⬆️ | Bring to 100/100/100/100 per CLAUDE.md gate. |
+| Property tests | 🚫 | ⬆️ | fast-check property suite on chain ordering + cache eviction. |
+| Storybook stories | 🚫 (no UI) | 🚫 | Not applicable — universal-tier, no UI surface. |
+
+No upstream capability is dropped without uplift.
+
+---
+
+## Available workspace deps on genesis
+
+- `@suaveplan/network` ✅ — `NetworkPlugin`, `NetworkBus`, `MessageEnvelope`
+- `@suaveplan/types` ✅ — shared interfaces (`Clock`, `Rng`, etc.)
+- `@suaveplan/error` ✅ — `defineCodes`, `SuaveplanError`
+- `@suaveplan/events` ✅ — typed event bus
+- `@suaveplan/retry` ✅ — backoff strategies + circuit breaker
+- `@suaveplan/storage` ✅ — `AbstractStorage` for the peer cache backing
+- `@suaveplan/testing` ✅ — runner-agnostic test utilities + runner wrapper
+
+All deps present; no blocking gaps.
+
+---
+
+## Acceptance gate
+
+1. `bunx turbo lint typecheck test --filter=@suaveplan/network-bootstrap` green.
+2. `bunx turbo test:coverage --filter=@suaveplan/network-bootstrap` at 100/100/100/100.
+3. `bun run docs:check --filter=@suaveplan/network-bootstrap` green (every `.ts` has a sibling `.md`).
+4. `MANIFEST.md` regen confirms dep graph has no cycles.
+5. `STATUS.md` row flipped from `–` to `✅`.
+
+---
+
+## Out of scope
+
+- Concrete discovery strategies for individual transports — those ship with their owning `network-discovery-*` packages (Wave 2).
+- Server-tier daemons — separate `network-*-server` packages (Wave 5).

openspec/archive/2026-05-11-network-bootstrap/tasks.md

@@ -0,0 +1,57 @@
+# Tasks — network-bootstrap
+
+## Phase 1: Scaffold
+
+- [ ] 1.1 Create `packages/network/network-bootstrap/` with standard package layout (per CLAUDE.md feature-module structure).
+- [ ] 1.2 Author `package.json` at `0.1.0`, `"sideEffects": false`, subpath exports per feature module.
+- [ ] 1.3 Wire `tsconfig.json` / `tsconfig.lib.json` / `vite.config.ts` / `vitest.config.ts` via `createTestConfig()`.
+- [ ] 1.4 Add `tests/dep-graph.test.ts` asserting no cycles.
+
+## Phase 2: Port types + errors
+
+- [ ] 2.1 Port `bootstrap.types.ts` → `src/types/types.ts` + sibling `.md` doc.
+- [ ] 2.2 `defineCodes("NET_BOOTSTRAP", [...])` registry: `CHAIN_EXHAUSTED`, `CACHE_CORRUPTED`, `STRATEGY_TIMEOUT`, `INVALID_OPTIONS`.
+- [ ] 2.3 Zod schemas for every public option struct.
+
+## Phase 3: Core
+
+- [ ] 3.1 Port `DiscoveryChain` with ordered execution + first-success fallthrough.
+- [ ] 3.2 Port `PeerCache` backed by `AbstractStorage` from `@suaveplan/storage`.
+- [ ] 3.3 Wire `@suaveplan/retry` for backoff between strategy attempts.
+- [ ] 3.4 Emit `bootstrap:started`/`:peer-found`/`:exhausted` on `NetworkBus`.
+- [ ] 3.5 Thread `AbortSignal` through every async path.
+
+## Phase 4: Plugin + middleware
+
+- [ ] 4.1 Port `BootstrapPlugin` (`NetworkPlugin` impl).
+- [ ] 4.2 Port `BootstrapMiddleware` (runtime chain augmentation).
+- [ ] 4.3 Conformance test for `NetworkPlugin` lifecycle (install/start/stop/dispose idempotency).
+
+## Phase 5: Observability
+
+- [ ] 5.1 OTel spans (`bootstrap.chain.execute`).
+- [ ] 5.2 Counters (`bootstrap.peers_found_total{strategy}`, `bootstrap.failures_total{strategy,code}`).
+- [ ] 5.3 Histograms (`bootstrap.chain_duration_ms`).
+
+## Phase 6: Tests + docs
+
+- [ ] 6.1 Unit tests per feature module via `@suaveplan/testing/runner`.
+- [ ] 6.2 fast-check property tests: chain ordering, cache eviction, retry idempotency.
+- [ ] 6.3 100/100/100/100 coverage gate.
+- [ ] 6.4 Sibling `.md` doc per `.ts` impl file (`docs:check` green).
+- [ ] 6.5 Root `README.md` with basic + advanced examples.
+
+## Phase 7: Verification
+
+- [ ] 7.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-bootstrap` green.
+- [ ] 7.2 `bunx turbo test:coverage --filter=@suaveplan/network-bootstrap` 100/100/100/100.
+- [ ] 7.3 `bun run docs:check --filter=@suaveplan/network-bootstrap` green.
+- [ ] 7.4 `bun scripts/folder-reorg/generate-manifest.ts` updates `MANIFEST.md`.
+- [ ] 7.5 `STATUS.md` row flipped from `–` to `✅`.
+
+## Pre-archive checklist
+
+- [ ] Row 1 — Verified by: Phase 7 gates all green.
+- [ ] Row 2 — Verified by: Parity checklist in `proposal.md` has zero unresolved 🚫.
+- [ ] Row 3 — Verified by: `openspec/specs/network-bootstrap/spec.md` written with `## ADDED Requirements`.
+- [ ] Row 4 — Verified by: Folder moved to `openspec/archive/<yyyy-mm-dd>-network-bootstrap/`.