Initial Commit

openspec/archive/2026-05-12-network-transport-standby/proposal.md

@@ -0,0 +1,90 @@
+# OpenSpec Change: network-transport-standby
+
+- **Change ID**: network-transport-standby
+- **Package**: `@suaveplan/network-transport-standby`
+- **Category**: universal
+- **Target path**: `packages/network/network-transport-standby`
+- **Status**: PROPOSED
+- **Date**: 2026-05-11
+- **Parent**: `network-transport-family` (2026-05-11) — Wave 3
+- **Migration source**: `../suaveplan/packages/universal/network-standby-transport` + `../suaveplan/enterprise/network-standby-transport.md`
+- **Supersedes**: the original name reservation in this folder (2026-05-11)
+
+---
+
+## Summary
+
+Migrate `@suaveplan/network-standby-transport` into genesis as `@suaveplan/network-transport-standby` (per the family-naming convention from the parent proposal). The package provides **pre-emptive WebRTC standby** — maintains a pool of warm `RTCPeerConnection` slots so consumer code experiences ~10 ms peer attach instead of the typical 1-3 s ICE/DTLS handshake. First package of Wave 3 because it cleanly builds on shipped `network-transport-webrtc` ✅ and has the smallest external surface.
+
+---
+
+## Why this is first in Wave 3
+
+- **Pure WebRTC extension.** Consumes `RTCPeerConnection` directly; no new external dep beyond what `network-transport-webrtc` ✅ already uses.
+- **Highest user-visible payoff.** Sub-100 ms peer attach is a dramatic UX win for real-time apps.
+- **Reference implementation.** Establishes the "extends an existing transport via pre-emption / pooling" pattern that Wave 4's `network-transport-hyperswarm` will mirror.
+
+---
+
+## Current-state audit
+
+Upstream source layout (`../suaveplan/packages/universal/network-standby-transport/src/`):
+
+- `core/` — connection-pool engine (min/max slots, eviction, warm-up scheduler)
+- `health/` — per-slot connection-quality scoring + auto-reconnect FSM
+- `transport/` — `Transport` adapter (`connect`/`disconnect`/`send`/`onMessage`/`getConnectedPeers`/`close`)
+- `types/` — `ConnectionState`, `ConnectionRequest`, pool options
+- `index.ts` — barrel
+
+Upstream coverage: 99.04% statement, no E2E.
+
+---
+
+## Parity Checklist
+
+| Capability | Upstream | Migrated | Notes |
+|---|---|---|---|
+| Pre-emptive connection pool | ✅ | ✅ | |
+| Min/max slot config + eviction | ✅ | ✅ | |
+| Warm-up scheduler | ✅ | ✅ | Backed by `@suaveplan/timing` scheduler + injectable `Clock`. |
+| Per-slot health scoring | ✅ | ✅ | EMA-smoothed RTT + jitter + loss composite. Re-uses `network-transport-webrtc`'s `PingManager` shape. |
+| Auto-reconnect with exponential backoff | ✅ | ⬆️ | Replaced ad-hoc loop with `@suaveplan/retry` policy + jitter. |
+| `Transport` contract impl | ✅ | ✅ | Registers with `network-plugin-transport-manager` ✅. |
+| `NetworkPlugin` wrapper | partial | ⬆️ | NEW — mirrors `WebRTCPlugin` shape so the manager treats standby uniformly. |
+| Event-driven observability | ✅ | ✅ | Replaced custom emitter with `@suaveplan/events` `NetworkBus`. Emits `transport:standby:warm`, `:promoted`, `:evicted`. |
+| Structured errors | 🚫 | ⬆️ | `defineCodes("NET_STANDBY", [...])`: `POOL_EXHAUSTED`, `SLOT_UNHEALTHY`, `PROMOTION_FAILED`, `INVALID_OPTIONS`. |
+| Zod boundary validation | partial | ⬆️ | Every public option struct. |
+| OTel instrumentation | partial | ⬆️ | Gauge `standby.warm_slots`, counters `standby.promotions_total{outcome}`, histogram `standby.warmup_duration_ms`. |
+| AbortSignal | partial | ⬆️ | Threaded through every async path. |
+| `export *` barrels | check | ⬆️ | Convert to explicit named exports per §6a. |
+| Test-runner imports | direct vitest | ⬆️ | Rewrite to `@suaveplan/testing/runner` per §7. |
+| 100% test coverage | 🚫 (99.04%) | ⬆️ | Bring to 100/100/100/100. |
+| fast-check property tests | 🚫 | ⬆️ | Pool invariants (min ≤ active ≤ max), eviction fairness, promotion atomicity. |
+
+---
+
+## Available workspace deps on genesis
+
+- `@suaveplan/network` ✅
+- `@suaveplan/network-transport-webrtc` ✅
+- `@suaveplan/network-plugin-transport-manager` ✅
+- `@suaveplan/retry` ✅, `@suaveplan/timing` ✅, `@suaveplan/events` ✅, `@suaveplan/error` ✅, `@suaveplan/types` ✅
+- `@suaveplan/testing` ✅
+- No new external deps.
+
+---
+
+## Acceptance gate
+
+1. `bunx turbo lint typecheck test --filter=@suaveplan/network-transport-standby` green.
+2. `bunx turbo test:coverage --filter=@suaveplan/network-transport-standby` 100/100/100/100.
+3. `bun run docs:check` green.
+4. Integration test with `network-plugin-transport-manager`: standby warms 4 slots, manager promotes one to active in < 100 ms.
+5. `STATUS.md` row flipped from `–` to `✅`.
+
+---
+
+## Out of scope
+
+- Pre-emption strategies tied to specific application heuristics — left as user-provided callbacks.
+- Server-side standby pools (Wave 4 hyperswarm/libp2p have their own pooling stories).

openspec/archive/2026-05-12-network-transport-standby/tasks.md

@@ -0,0 +1,67 @@
+# Tasks — network-transport-standby
+
+## Phase 1: Scaffold
+
+- [ ] 1.1 Create `packages/network/network-transport-standby/` with feature-module layout.
+- [ ] 1.2 `package.json` at `0.1.0`, `"sideEffects": false`, subpath exports per module.
+- [ ] 1.3 Test config via `createTestConfig()`; `tests/dep-graph.test.ts`.
+
+## Phase 2: Types + errors
+
+- [ ] 2.1 Port `types/` → `src/types/` + sibling `.md`.
+- [ ] 2.2 `defineCodes("NET_STANDBY", [...])`: `POOL_EXHAUSTED`, `SLOT_UNHEALTHY`, `PROMOTION_FAILED`, `INVALID_OPTIONS`.
+- [ ] 2.3 Zod schemas for `StandbyPoolConfig`, `ConnectionRequest`, `ConnectionState`.
+
+## Phase 3: Core pool
+
+- [ ] 3.1 Port pool engine (min/max slots, eviction policy).
+- [ ] 3.2 Port warm-up scheduler over `@suaveplan/timing` + injectable `Clock`.
+- [ ] 3.3 Replace ad-hoc reconnect loop with `@suaveplan/retry` exponential-backoff policy.
+
+## Phase 4: Health subsystem
+
+- [ ] 4.1 Port per-slot health scoring (EMA RTT + jitter + loss composite).
+- [ ] 4.2 Port auto-reconnect FSM.
+- [ ] 4.3 Wire to `network-transport-webrtc`'s ping primitives.
+
+## Phase 5: Transport + plugin
+
+- [ ] 5.1 Port `StandbyTransport implements Transport`.
+- [ ] 5.2 Author `StandbyPlugin implements NetworkPlugin` mirroring `WebRTCPlugin`.
+- [ ] 5.3 Conformance test for `Transport` + `NetworkPlugin` contracts.
+
+## Phase 6: Observability
+
+- [ ] 6.1 Gauge `standby.warm_slots`.
+- [ ] 6.2 Counters `standby.promotions_total{outcome}`, `standby.evictions_total{reason}`.
+- [ ] 6.3 Histogram `standby.warmup_duration_ms`.
+- [ ] 6.4 Bus emissions `transport:standby:warm`/`:promoted`/`:evicted`.
+
+## Phase 7: Tests + docs
+
+- [ ] 7.1 Unit tests per module via `@suaveplan/testing/runner`.
+- [ ] 7.2 fast-check property tests: pool invariants (min ≤ active ≤ max), eviction fairness, promotion atomicity.
+- [ ] 7.3 100/100/100/100 coverage gate.
+- [ ] 7.4 Sibling `.md` per `.ts` impl file.
+- [ ] 7.5 Root `README.md`.
+
+## Phase 8: Integration
+
+- [ ] 8.1 Cross-package test with `network-plugin-transport-manager`: standby warms 4 slots, manager promotes one to active in < 100 ms simulated.
+- [ ] 8.2 Failure-mode test: slot becomes unhealthy → evict → warm replacement.
+
+## Phase 9: Verification
+
+- [ ] 9.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-transport-standby` green.
+- [ ] 9.2 `bunx turbo test:coverage --filter=@suaveplan/network-transport-standby` 100/100/100/100.
+- [ ] 9.3 `bun run docs:check` green.
+- [ ] 9.4 `MANIFEST.md` regen.
+- [ ] 9.5 `STATUS.md` row flipped.
+
+## Pre-archive checklist
+
+- [ ] Row 1 — Phase 9 green.
+- [ ] Row 2 — Parity 🚫 list empty.
+- [ ] Row 3 — `openspec/specs/network-transport-standby/spec.md` written.
+- [ ] Row 4 — Manager integration test passes.
+- [ ] Row 5 — Folder archived.