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

Tasks — network-plugin-monitor

Blocked on: network-core, network-plugin-registry.

1. Scaffold

• 1.1 packages/network/network-plugin-monitor/ with package.json (@suaveplan/network-plugin-monitor@0.0.0), tsconfig.json, vitest.config.ts, README.md.
• 1.2 Workspace deps: @suaveplan/network, @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/opentelemetry, @suaveplan/timing, zod.
• 1.3 sideEffects: false.

2. Types

• 2.1 src/types/metric.types.ts — Metric, MetricType, MetricCategory, MetricValue.
• 2.2 src/types/alert.types.ts — AlertRule, AlertSeverity, AlertState.
• 2.3 src/types/trace.types.ts — NetworkTrace, NetworkSpan, TraceContext.
• 2.4 src/error-codes.ts — defineCodes("NET_MON", [...]).

3. Network monitor

• 3.1 src/monitor/network-monitor.ts — NetworkMonitor.
• 3.2 4 metric categories: node, connection, message, hierarchy.
• 3.3 recordNodeMetric(peerId, name, value), recordConnectionMetric(source, target, name, value), etc.
• 3.4 Statistical analysis: min, max, avg, p50, p95, p99.

4. Metric collector

• 4.1 src/collector/metric-collector.ts — MetricCollector.
• 4.2 4 metric types: Counter, Gauge, Histogram, Summary.
• 4.3 Configurable sampling rates.
• 4.4 Push and pull collection modes.

5. Alert engine

• 5.1 src/alert/alert-engine.ts — AlertEngine.
• 5.2 Threshold-based rules with configurable comparison (>, <, ==, !=).
• 5.3 Emits monitor:alert on bus with severity.
• 5.4 Alert suppression (cooldown between repeat alerts).

6. Network tracer

• 6.1 src/tracer/network-tracer.ts — NetworkTracer.
• 6.2 OpenTelemetry compatible API.
• 6.3 Trace ID propagation via message headers.
• 6.4 Span creation for cross-node operations.
• 6.5 Sampling: probabilistic, rate-limited, error-based, priority-based.
• 6.6 Clock skew detection and correction.

7. Historical data store

• 7.1 src/history/historical-data-store.ts — HistoricalDataStore.
• 7.2 Configurable retention policies (time-based, count-based).
• 7.3 Rollup and aggregation for long-term storage.

8. Adaptive sampler

• 8.1 src/sampler/adaptive-sampler.ts — AdaptiveSampler.
• 8.2 Reduces sampling rate when metric volume exceeds threshold.
• 8.3 Restores full sampling when volume decreases.

9. Plugin wrapper

• 9.1 src/plugin/monitor-plugin.ts — MonitorPlugin implements NetworkPlugin.
• 9.2 Subscribes to bus events and converts them to metrics.
• 9.3 Installs monitor, collector, alert engine, tracer on install().

10. Spec

• 10.1 Update openspec/specs/network/spec.md with NET-44.

11. Conformance tests

• 11.1 src/monitor/monitor.spec-conformance.test.ts — collection, categories, aggregation.
• 11.2 src/collector/collector.spec-conformance.test.ts — 4 types, sampling, push/pull.
• 11.3 src/alert/alert.spec-conformance.test.ts — thresholds, bus emission, suppression.
• 11.4 src/tracer/tracer.spec-conformance.test.ts — propagation, spans, sampling.
• 11.5 src/history/history.spec-conformance.test.ts — retention, rollup, aggregation.
• 11.6 src/sampler/sampler.spec-conformance.test.ts — adaptive reduction, restoration.
• 11.7 src/error-codes.spec-conformance.test.ts — frozen registry.

12. Verify

• 12.1 bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-monitor green.
• 12.2 bunx turbo test:coverage --filter=@suaveplan/network-plugin-monitor 100/100/100/100.
• 12.3 bun scripts/openspec-conformance.ts @suaveplan/network-plugin-monitor PASS.