Initial Commit

openspec/archive/2026-05-04-network-plugin-monitor/tasks.md

@@ -0,0 +1,84 @@
+# Tasks — network-plugin-monitor
+
+> Blocked on: `network-core`, `network-plugin-registry`.
+
+## 1. Scaffold
+
+- [x] 1.1 `packages/network/network-plugin-monitor/` with `package.json` (`@suaveplan/network-plugin-monitor@0.0.0`), `tsconfig.json`, `vitest.config.ts`, `README.md`.
+- [x] 1.2 Workspace deps: `@suaveplan/network`, `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/opentelemetry`, `@suaveplan/timing`, `zod`.
+- [x] 1.3 `sideEffects: false`.
+
+## 2. Types
+
+- [x] 2.1 `src/types/metric.types.ts` — `Metric`, `MetricType`, `MetricCategory`, `MetricValue`.
+- [x] 2.2 `src/types/alert.types.ts` — `AlertRule`, `AlertSeverity`, `AlertState`.
+- [x] 2.3 `src/types/trace.types.ts` — `NetworkTrace`, `NetworkSpan`, `TraceContext`.
+- [x] 2.4 `src/error-codes.ts` — `defineCodes("NET_MON", [...])`.
+
+## 3. Network monitor
+
+- [x] 3.1 `src/monitor/network-monitor.ts` — `NetworkMonitor`.
+- [x] 3.2 4 metric categories: node, connection, message, hierarchy.
+- [x] 3.3 `recordNodeMetric(peerId, name, value)`, `recordConnectionMetric(source, target, name, value)`, etc.
+- [x] 3.4 Statistical analysis: min, max, avg, p50, p95, p99.
+
+## 4. Metric collector
+
+- [x] 4.1 `src/collector/metric-collector.ts` — `MetricCollector`.
+- [x] 4.2 4 metric types: Counter, Gauge, Histogram, Summary.
+- [x] 4.3 Configurable sampling rates.
+- [x] 4.4 Push and pull collection modes.
+
+## 5. Alert engine
+
+- [x] 5.1 `src/alert/alert-engine.ts` — `AlertEngine`.
+- [x] 5.2 Threshold-based rules with configurable comparison (>, <, ==, !=).
+- [x] 5.3 Emits `monitor:alert` on bus with severity.
+- [x] 5.4 Alert suppression (cooldown between repeat alerts).
+
+## 6. Network tracer
+
+- [x] 6.1 `src/tracer/network-tracer.ts` — `NetworkTracer`.
+- [x] 6.2 OpenTelemetry compatible API.
+- [x] 6.3 Trace ID propagation via message headers.
+- [x] 6.4 Span creation for cross-node operations.
+- [x] 6.5 Sampling: probabilistic, rate-limited, error-based, priority-based.
+- [x] 6.6 Clock skew detection and correction.
+
+## 7. Historical data store
+
+- [x] 7.1 `src/history/historical-data-store.ts` — `HistoricalDataStore`.
+- [x] 7.2 Configurable retention policies (time-based, count-based).
+- [x] 7.3 Rollup and aggregation for long-term storage.
+
+## 8. Adaptive sampler
+
+- [x] 8.1 `src/sampler/adaptive-sampler.ts` — `AdaptiveSampler`.
+- [x] 8.2 Reduces sampling rate when metric volume exceeds threshold.
+- [x] 8.3 Restores full sampling when volume decreases.
+
+## 9. Plugin wrapper
+
+- [x] 9.1 `src/plugin/monitor-plugin.ts` — `MonitorPlugin` implements `NetworkPlugin`.
+- [x] 9.2 Subscribes to bus events and converts them to metrics.
+- [x] 9.3 Installs monitor, collector, alert engine, tracer on `install()`.
+
+## 10. Spec
+
+- [x] 10.1 Update `openspec/specs/network/spec.md` with `NET-44`.
+
+## 11. Conformance tests
+
+- [x] 11.1 `src/monitor/monitor.spec-conformance.test.ts` — collection, categories, aggregation.
+- [x] 11.2 `src/collector/collector.spec-conformance.test.ts` — 4 types, sampling, push/pull.
+- [x] 11.3 `src/alert/alert.spec-conformance.test.ts` — thresholds, bus emission, suppression.
+- [x] 11.4 `src/tracer/tracer.spec-conformance.test.ts` — propagation, spans, sampling.
+- [x] 11.5 `src/history/history.spec-conformance.test.ts` — retention, rollup, aggregation.
+- [x] 11.6 `src/sampler/sampler.spec-conformance.test.ts` — adaptive reduction, restoration.
+- [x] 11.7 `src/error-codes.spec-conformance.test.ts` — frozen registry.
+
+## 12. Verify
+
+- [x] 12.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-monitor` green.
+- [x] 12.2 `bunx turbo test:coverage --filter=@suaveplan/network-plugin-monitor` 100/100/100/100.
+- [x] 12.3 `bun scripts/openspec-conformance.ts @suaveplan/network-plugin-monitor` PASS.