Initial Commit

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

@@ -0,0 +1,92 @@
+# Tasks: enterprise-network-observability
+
+**Change ID**: enterprise-network-observability
+**Package**: `@suaveplan/network-observability`
+**Target path**: `universal/network/network-observability`
+**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/logger`, `@suaveplan/timing`
+
+---
+
+## 1. Scaffold
+
+- [x] Create `universal/network/network-observability/` with `src/`, `tests/`, 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.
+
+---
+
+## 2. Types and error codes
+
+- [x] Define all public types in `src/types/common.ts`: `NetworkSnapshot`, `RttMetrics`, `BandwidthMetrics`, `PacketLossMetrics`, `NetworkHealthScore`, `HealthFactor`, `NetworkMonitorOptions`, `NetworkThresholds`, `NetworkEvent`, `NetworkSpanAttributes`.
+- [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. RTT metrics (`src/metrics/rtt.ts`)
+
+- [x] Implement `measureRtt(url: string, samples?: number, signal?: AbortSignal): Promise<RttMetrics>`:
+  - Fire `samples` (default 5) HTTP HEAD or WebSocket ping probes in sequence.
+  - Compute min/max/avg/p50/p95/p99 over results.
+- [x] Write `rtt.test.ts` + `rtt.md`.
+
+---
+
+## 4. Bandwidth metrics (`src/metrics/bandwidth.ts`)
+
+- [x] Implement `measureBandwidth(url: string, signal?: AbortSignal): Promise<BandwidthMetrics>`:
+  - Download a known-size payload; compute bytes / elapsed time.
+- [x] Write `bandwidth.test.ts` + `bandwidth.md`.
+
+---
+
+## 5. Health scoring (`src/core/health/`)
+
+- [x] Implement `computeHealthScore(snapshot: Partial<NetworkSnapshot>, thresholds?: NetworkThresholds): NetworkHealthScore`:
+  - RTT factor (40%): 100 if < 50ms, linear decay to 0 at 500ms.
+  - Packet loss factor (35%): 100 if 0%, linear decay to 0 at 10%.
+  - Bandwidth factor (25%): 100 if > 10Mbps, linear decay to 0 at 0.
+  - Weighted sum = score; grade from score: 80+ excellent, 60+ good, 40+ fair, 20+ poor, <20 critical.
+- [x] Write `health.test.ts` (≤500 lines): known inputs produce expected scores and grades.
+- [x] Write `health.md` (≥200 words).
+
+---
+
+## 6. Trace context propagation (`src/tracing/`)
+
+- [x] Implement `injectTraceContext(headers)` — calls `context.with(...)` + OTel `TextMapPropagator.inject`.
+- [x] Implement `extractTraceContext(headers)` — calls OTel `TextMapPropagator.extract`.
+- [x] Implement `withNetworkSpan(name, fn, attributes?)` — wraps `fn` in a span with network attributes.
+- [x] Write `propagation.test.ts` + `propagation.md`.
+
+---
+
+## 7. Network monitor (`src/core/monitor/`)
+
+- [x] Implement `createNetworkMonitor(options?)`:
+  - On `start()`, begin measurement loop using `@suaveplan/timing` interval timer.
+  - Each iteration: call RTT probe, compute health score, push to history ring buffer.
+  - Emit `snapshot` event on each measurement.
+  - Check against thresholds; emit `threshold-breach` on violation, `recovery` on recovery.
+  - OTel: gauge `net.rtt_ms`, gauge `net.health_score`, gauge `net.packet_loss`.
+- [x] Implement `monitor.snapshot()`, `monitor.history(limit?)`, `monitor.on(event, handler)`.
+- [x] Write `monitor.test.ts` (≤500 lines): start/stop, snapshot, threshold breach + recovery event.
+- [x] Write `monitor.md` (≥200 words).
+
+---
+
+## 8. Property-based tests (`tests/property.test.ts`)
+
+- [x] Health score monotonicity: increasing RTT (all else equal) never increases the score.
+- [x] Grade ordering: `score >= 80 ⇒ excellent`, grade boundaries consistent.
+
+---
+
+## 9. Docs and verify
+
+- [x] All per-file `.md` files per layout in `proposal.md`.
+- [x] `universal/network/network-observability/README.md`.
+- [x] `bunx turbo lint typecheck test test:coverage --filter=@suaveplan/network-observability` — all green, 100% coverage.
+- [x] `bun scripts/publish.ts --package @suaveplan/network-observability`.
+- [x] Update `CLAUDE.md`. Archive change folder.