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

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

• Create universal/network/network-observability/ with src/, tests/, 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.

---

2. Types and error codes

• Define all public types in src/types/common.ts: NetworkSnapshot, RttMetrics, BandwidthMetrics, PacketLossMetrics, NetworkHealthScore, HealthFactor, NetworkMonitorOptions, NetworkThresholds, NetworkEvent, NetworkSpanAttributes.
• 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. RTT metrics (src/metrics/rtt.ts)

• 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.
• Write rtt.test.ts + rtt.md.

---

4. Bandwidth metrics (src/metrics/bandwidth.ts)

• Implement measureBandwidth(url: string, signal?: AbortSignal): Promise<BandwidthMetrics>:
  • Download a known-size payload; compute bytes / elapsed time.
• Write bandwidth.test.ts + bandwidth.md.

---

5. Health scoring (src/core/health/)

• 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.
• Write health.test.ts (≤500 lines): known inputs produce expected scores and grades.
• Write health.md (≥200 words).

---

6. Trace context propagation (src/tracing/)

• Implement injectTraceContext(headers) — calls context.with(...) + OTel TextMapPropagator.inject.
• Implement extractTraceContext(headers) — calls OTel TextMapPropagator.extract.
• Implement withNetworkSpan(name, fn, attributes?) — wraps fn in a span with network attributes.
• Write propagation.test.ts + propagation.md.

---

7. Network monitor (src/core/monitor/)

• 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.
• Implement monitor.snapshot(), monitor.history(limit?), monitor.on(event, handler).
• Write monitor.test.ts (≤500 lines): start/stop, snapshot, threshold breach + recovery event.
• Write monitor.md (≥200 words).

---

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

• Health score monotonicity: increasing RTT (all else equal) never increases the score.
• Grade ordering: score >= 80 ⇒ excellent, grade boundaries consistent.

---

9. Docs and verify

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