Initial Commit

openspec/archive/2026-05-12-network-quality-consolidation/proposal.md

@@ -0,0 +1,78 @@
+# OpenSpec Change: network-quality-consolidation
+
+- **Change ID**: network-quality-consolidation
+- **Affects**:
+  - `@suaveplan/network-plugin-monitor` ✅ (extended) OR new `@suaveplan/network-plugin-quality`
+  - `@suaveplan/network-quality` (upstream — folded or migrated)
+- **Category**: universal
+- **Status**: ARCHIVED 2026-05-12 — Option A executed
+- **Date**: 2026-05-11
+- **Parent**: `network-transport-family` (2026-05-11) — Wave 6
+- **Migration source**: `../suaveplan/packages/universal/network-quality` + `../suaveplan/enterprise/network-quality.md`
+
+---
+
+## Summary
+
+Mirror change of `network-observability-consolidation` but for `@suaveplan/network-quality` — upstream's network-quality-monitoring layer. The shipped `@suaveplan/network-plugin-monitor` ✅ already scores per-peer quality; upstream `network-quality` likely overlaps. Resolve via fold or split.
+
+---
+
+## Decision required
+
+Same fold-vs-split decision as `network-observability-consolidation`. See that proposal for the framing.
+
+**Recommendation:** Fold into `network-plugin-monitor` (Option A) unless audit reveals quality-specific abstractions (e.g. MOS scoring, QoE estimation, packet-pacing analyzers) that warrant a dedicated plugin.
+
+---
+
+## Current-state audit (perform at execution time)
+
+Upstream coverage: 98.88%. Investigate:
+
+```bash
+ls ../suaveplan/packages/universal/network-quality/src/
+diff <(grep -rh "^export" ../suaveplan/packages/universal/network-quality/src/) \
+     <(grep -rh "^export" packages/network/network-plugin-monitor/src/)
+```
+
+---
+
+## Parity Checklist (FINAL — audit complete 2026-05-12)
+
+Decision: **Option A — fold into `@suaveplan/network-plugin-monitor`**.
+
+Audit confirmed **zero overlap** with the shipped `network-plugin-monitor` exports — none of `BandwidthMonitor`, `DegradationManager`, or `createQualityMiddleware` have analogues in monitor's existing collector/alert/sampler/tracer surface:
+
+| Capability | Upstream | Existing (`monitor`) | Verdict |
+|---|---|---|---|
+| Per-peer RTT raw metric | 🚫 | ✅ (`MetricCollector`) | already covered |
+| Loss / jitter raw metrics | 🚫 | ✅ (`NetworkMonitor`) | already covered |
+| Alert thresholds on raw metrics | 🚫 | ✅ (`AlertEngine`) | already covered |
+| **EMA-smoothed bandwidth/RTT/loss recorder** | ✅ `BandwidthMonitor` (122 LOC) | 🚫 | ⬆️ **folded as `quality/bandwidth-monitor`** |
+| **4-rung quality-class classifier with hysteresis + one-step transitions** | ✅ `DegradationManager` (207 LOC) | 🚫 | ⬆️ **folded as `quality/degradation-manager`** |
+| **Per-source outgoing-message throttling middleware** | ✅ `createQualityMiddleware` (95 LOC) | 🚫 | ⬆️ **folded as `quality/quality-middleware`** |
+| MOS / QoE scoring | 🚫 not in upstream src | 🚫 | n/a — not present |
+| Packet-pacing analyzers | 🚫 not in upstream src | 🚫 | n/a — not present |
+| `QualityPlugin` `NetworkPlugin`-wrapper driving periodic `evaluate()` via `setInterval` | ✅ (120 LOC) | n/a | ❌ **NOT folded** — monitor already exposes `MonitorPlugin`; consumers wanting auto-evaluation wire `BandwidthMonitor` + `DegradationManager` behind their own scheduler |
+
+**Why fold and not split:** upstream is 707 LOC, only ~430 LOC of which is portable after dropping `QualityPlugin`. After filtering, the three remaining modules consume each other in a tight loop (`BandwidthMonitor` → `DegradationManager` → `createQualityMiddleware`) and share a single `QualityLevel`/`BandwidthSample` types layer — same fold pattern as Wave 6.1's prometheus/grafana.
+
+**API rewrites at fold:** upstream `BandwidthMonitor`/`DegradationManager` both extended `@suaveplan/events`'s `EventEmitter<TMap>`, but genesis's events package is now bus-based. Replaced with callback-handler subscriptions returning unsubscribe functions — same observable surface, zero monolithic-EE coupling. `hysteresisMs: 0` newly commits same-call so the policy is usable synchronously. `QualityLevel` rewritten as a `const` object + value-union to drop TypeScript enum reverse-mapping. Every public shape gained Zod validation (`BandwidthSampleSchema`, `QualityThresholdsSchema`, `LevelThresholdSchema`).
+
+---
+
+## Acceptance gate
+
+Identical to `network-observability-consolidation`:
+
+1. Audit + decision.
+2. Implementation under chosen option.
+3. `STATUS.md` row removed; supersession table updated.
+4. `bunx turbo lint typecheck test` + `test:coverage` 100% on affected packages.
+
+---
+
+## Out of scope
+
+- Audio/video MOS scoring (separate `@suaveplan/audio-quality` if needed).