# OpenSpec Change: network-plugin-monitor

- **Change ID**: network-plugin-monitor
- **Package**: `@suaveplan/network-plugin-monitor` (new)
- **Status**: PROPOSED
- **Type**: new-package
- **Date**: 2026-04-29

## Why

Operating a production mesh network requires visibility into node health, connection quality, message flow, and hierarchy structure. Without monitoring, operators cannot detect degradation, diagnose partitions, or optimize topology. The genesis `opentelemetry` integration provides distributed tracing, but the network layer needs its own domain-specific metrics: peer latency distributions, tier stability, promotion/demotion rates, message routing efficiency, and transport health trends.

This plugin implements **production monitoring and distributed tracing** for the network layer, integrating with `@suaveplan/opentelemetry` for trace export while maintaining mesh-specific metrics.

## What changes

- **ADDED**: `MonitorPlugin` class implementing `NetworkPlugin`.
- **ADDED**: `NetworkMonitor` — collects and analyzes metrics across 4 categories:
  - **Node metrics**: CPU utilization, memory usage, message queue size, plugin count, error rate
  - **Connection metrics**: latency (min/avg/max/p95), packet loss, bandwidth, connection stability score
  - **Message metrics**: throughput (messages/sec), size distribution, processing time, routing efficiency
  - **Hierarchy metrics**: nodes per tier, parent-child ratios, promotion/demotion rates, sibling relationships
- **ADDED**: `MetricCollector` — supports 4 metric types: Counter, Gauge, Histogram, Summary. Configurable sampling rates. Push and pull collection modes.
- **ADDED**: `AlertEngine` — threshold-based alerting with configurable rules. Emits `monitor:alert` on `NetworkBus` when metrics exceed thresholds.
- **ADDED**: `NetworkTracer` — distributed tracing compatible with OpenTelemetry:
  - Trace ID propagation across mesh hops via message headers
  - Span creation for operations crossing multiple nodes
  - Context carriers for different transport types
  - Sampling strategies: probabilistic, rate-limited, error-based, priority-based
  - Clock skew detection and correction between peers
- **ADDED**: `HistoricalDataStore` — maintains metric history with configurable retention policies. Supports rollup and aggregation for long-term analysis.
- **ADDED**: `AdaptiveSampler` — reduces sampling rate under high metric volume to prevent monitoring overhead from degrading network performance.
- **ADDED**: `NETWORK_MON_CODES` — frozen error registry.

## Metric example

```typescript
// Node metric
monitor.recordNodeMetric(peerId, 'cpu', 0.45);

// Connection metric
monitor.recordConnectionMetric(sourceId, targetId, 'latency', 42);

// Message metric
monitor.recordMessageMetric('registry:update', 'processingTime', 3.2);

// Hierarchy metric
monitor.recordHierarchyMetric('tier0', 'nodeCount', 3);
```

## Out of scope

- Visual dashboards → external tools (Grafana, etc.) consume exported metrics.
- Log aggregation → `network-plugin-audit-mesh` handles signed log chains.
- Alert delivery (email, SMS) → external alerting system consumes `monitor:alert` bus events.

## Source mapping

This derives from `docs/old-network-planning/PHASE_8.md` §Monitoring and Tracing.

| Requirement | Source lines | Notes |
|---|---|---|
| Metric types (Counter, Gauge, Histogram, Summary) | `PHASE_8.md` §Metric Types | verbatim |
| Metric categories (node, connection, message, hierarchy) | `PHASE_8.md` §Metric Categories | verbatim |
| Distributed tracing | `PHASE_8.md` §NetworkTracer | reworded; OpenTelemetry compatible |
| Sampling strategies | `PHASE_8.md` §Sampling Strategies | verbatim: 4 strategies |
| Alerting | `PHASE_8.md` §Alerting | reworded; bus-based |
| Adaptive sampling | `PHASE_8.md` §High-Volume Monitoring | reworded |

### Requirements with no source line

| Requirement | Justification |
|---|---|
| Clock skew detection | Required for accurate cross-node span timing |
| Historical data store | Required for trend analysis and degradation detection |
| Push and pull modes | Required for integration with different monitoring backends |

## Verification approach

- `src/monitor/monitor.spec-conformance.test.ts` — pins metric collection, categorization, aggregation.
- `src/collector/collector.spec-conformance.test.ts` — pins 4 metric types, sampling, push/pull.
- `src/alert/alert.spec-conformance.test.ts` — pins threshold rules, bus emission, suppression.
- `src/tracer/tracer.spec-conformance.test.ts` — pins trace propagation, span creation, sampling.
- `src/history/history.spec-conformance.test.ts` — pins retention, rollup, aggregation.
- `src/sampler/sampler.spec-conformance.test.ts` — pins adaptive rate reduction under load.
- `src/error-codes.spec-conformance.test.ts` — frozen registry.
- `tests/dep-graph.test.ts` — pins no direct import of transport or webrtc packages.

## Migration impact

None — additive only. Monitoring is opt-in; metrics are collected only when the plugin is installed.