Initial Commit

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

@@ -0,0 +1,102 @@
+# Tasks: enterprise-network-quality
+
+**Change ID**: enterprise-network-quality
+**Package**: `@suaveplan/network-quality`
+**Target path**: `universal/network/network-quality`
+**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/logger`, `@suaveplan/timing`
+
+---
+
+## 1. Scaffold
+
+- [x] Create `universal/network/network-quality/` with `src/`, `tests/`, `src/__benchmarks__/`, 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 (including `bench`).
+
+---
+
+## 2. Types and error codes
+
+- [x] Define all public types in `src/types/common.ts`: `QualityMeasurement`, `QualityReport`, `QualityWindowStats`, `QualityTrend`, `QualityGrade`, `ThresholdViolation`, `QualityMonitorOptions`, `QualityThresholds`, `QualityProbe`, `QualityEvent`.
+- [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. Window statistics (`src/stats/`)
+
+- [x] Implement `computeWindowStats(measurements: QualityMeasurement[], windowMs: number): QualityWindowStats`:
+  - Filter measurements within the last `windowMs`.
+  - Compute avg RTT, avg jitter, avg packet loss, p95 RTT.
+  - Uses insertion-sort for p95 on small sample sets (≤100).
+- [x] Implement `exponentialSmooth(values: number[], alpha: number): number[]`: EWMA.
+- [x] Write `window-stats.test.ts` + `window-stats.md`.
+
+---
+
+## 4. Scorer (`src/scoring/`)
+
+- [x] Implement `computeQualityScore(measurement: QualityMeasurement, thresholds?: QualityThresholds): number`:
+  - RTT factor (40%): 100 when rtt ≤ 50ms; 0 when rtt ≥ thresholds.maxRttMs (default 500ms); linear between.
+  - Jitter factor (20%): 100 when jitter ≤ 10ms; 0 when jitter ≥ 100ms.
+  - Packet loss factor (30%): 100 when 0%; 0 when ≥ thresholds.maxPacketLoss (default 0.1).
+  - Throughput factor (10%): 0 if below threshold; 100 if above.
+  - Return weighted sum (0–100).
+- [x] Implement `gradeScore(score: number): QualityGrade`.
+- [x] Implement `detectTrend(recent: number[], older: number[]): QualityTrend`:
+  - Compare averages; `improving` if delta > +5, `degrading` if delta < -5, else `stable`.
+- [x] Write `scorer.test.ts` (≤500 lines): boundary cases, all four factors.
+- [x] Write `scorer.md` (≥200 words).
+
+---
+
+## 5. Probe factories (`src/probes/`)
+
+- [x] Implement `createRttProbe(url, options?)`: HTTP HEAD probe with clock-measured RTT.
+- [x] Implement `createBandwidthProbe(url, options?)`: fetch known-size payload, compute bytes/elapsed.
+- [x] Write `rtt-probe.test.ts` + `rtt-probe.md`.
+- [x] Write `bandwidth-probe.test.ts` + `bandwidth-probe.md`.
+
+---
+
+## 6. Quality monitor (`src/core/monitor/`)
+
+- [x] Implement `createQualityMonitor(options?)`:
+  - Validates options with Zod.
+  - `start(signal?)` — runs measurement loop via `@suaveplan/timing` interval.
+  - Each tick: call `options.probe ?? createRttProbe(options.rttUrl)`.
+  - Store in sliding window `measurements[]` (capped at `windowSize`, default 20).
+  - Apply exponential smoothing before scoring.
+  - Detect trend comparing newest half vs oldest half of window.
+  - Compute threshold violations.
+  - Emit `measurement` event. On grade transition, emit `degradation` or `recovery`.
+  - OTel: gauge `net.quality.rtt_ms`, gauge `net.quality.score`, gauge `net.quality.packet_loss`.
+- [x] Implement `selectBestPeer(peers, monitor)` — returns peer with lowest `score` gauge if custom probe; otherwise highest `score` field.
+- [x] Write `monitor.test.ts` (≤500 lines): start/stop, degradation event fired, recovery event, threshold violation.
+- [x] Write `monitor.md` (≥200 words).
+
+---
+
+## 7. Benchmarks (`src/__benchmarks__/quality.bench.ts`)
+
+- [x] `computeWindowStats_20`, `computeWindowStats_100`: 20 and 100 measurement samples.
+- [x] `scorer_hot`: 10k `computeQualityScore` calls.
+
+---
+
+## 8. Property-based tests (`tests/property.test.ts`)
+
+- [x] Score monotonicity: increasing RTT (all else equal) never increases the score.
+- [x] Grade boundary consistency: score ≥ 80 → grade is `excellent`.
+- [x] Trend stability: stable measurements produce `stable` trend.
+
+---
+
+## 9. Docs and verify
+
+- [x] All per-file `.md` files per layout in `proposal.md`.
+- [x] `universal/network/network-quality/README.md`.
+- [x] `bunx turbo lint typecheck test test:coverage --filter=@suaveplan/network-quality` — all green, 100%.
+- [x] `bun scripts/publish.ts --package @suaveplan/network-quality`.
+- [x] Update `CLAUDE.md`. Archive change folder.