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

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

• Create universal/network/network-quality/ with src/, tests/, src/__benchmarks__/, 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 (including bench).

---

2. Types and error codes

• Define all public types in src/types/common.ts: QualityMeasurement, QualityReport, QualityWindowStats, QualityTrend, QualityGrade, ThresholdViolation, QualityMonitorOptions, QualityThresholds, QualityProbe, QualityEvent.
• 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. Window statistics (src/stats/)

• 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).
• Implement exponentialSmooth(values: number[], alpha: number): number[]: EWMA.
• Write window-stats.test.ts + window-stats.md.

---

4. Scorer (src/scoring/)

• 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).
• Implement gradeScore(score: number): QualityGrade.
• Implement detectTrend(recent: number[], older: number[]): QualityTrend:
  • Compare averages; improving if delta > +5, degrading if delta < -5, else stable.
• Write scorer.test.ts (≤500 lines): boundary cases, all four factors.
• Write scorer.md (≥200 words).

---

5. Probe factories (src/probes/)

• Implement createRttProbe(url, options?): HTTP HEAD probe with clock-measured RTT.
• Implement createBandwidthProbe(url, options?): fetch known-size payload, compute bytes/elapsed.
• Write rtt-probe.test.ts + rtt-probe.md.
• Write bandwidth-probe.test.ts + bandwidth-probe.md.

---

6. Quality monitor (src/core/monitor/)

• 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.
• Implement selectBestPeer(peers, monitor) — returns peer with lowest score gauge if custom probe; otherwise highest score field.
• Write monitor.test.ts (≤500 lines): start/stop, degradation event fired, recovery event, threshold violation.
• Write monitor.md (≥200 words).

---

7. Benchmarks (src/__benchmarks__/quality.bench.ts)

• computeWindowStats_20, computeWindowStats_100: 20 and 100 measurement samples.
• scorer_hot: 10k computeQualityScore calls.

---

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

• Score monotonicity: increasing RTT (all else equal) never increases the score.
• Grade boundary consistency: score ≥ 80 → grade is excellent.
• Trend stability: stable measurements produce stable trend.

---

9. Docs and verify

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