# 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.