OpenSpec Change: network-plugin-devtools

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

Why

Debugging a distributed mesh network is notoriously difficult. Peers join and leave, messages are dropped, topology reorganizes, and state diverges. Without specialized developer tools, engineers must rely on console logs and guesswork. The old planning documents envisioned a comprehensive developer experience layer: real-time network visualization, interactive state inspection, simulation configuration, and performance profiling.

This plugin provides developer tools for the network layer: visualization, state inspection, simulation configuration, and performance analysis. It is dev-only and does not run in production.

What changes

ADDED: DevToolsPlugin class implementing NetworkPlugin (dev-only, no-op in production).
ADDED: NetworkVisualizer — real-time visualization of the mesh:
- Hierarchy view: tier structure, host/sub-host/leaf nodes, parent-child edges
- Message flow view: animated message paths, throughput per link, dropped messages
- Performance heat map: latency color-coding, bandwidth saturation, error rates
- Filtering by tier, latency group, session, transport type
- Export to PNG/SVG for documentation
ADDED: StateInspector — interactive state browser:
- Tree view of all synchronized state paths
- Historical state viewing with timeline scrubber
- Diff visualization between two state versions
- Search and filter by path, peer, or session
ADDED: SimulationConfigTool — scenario builder UI:
- Drag-and-drop network topology editor
- Network condition editor (latency, loss, bandwidth curves)
- Event timeline editor
- Simulation recording and playback
- Scenario sharing (export/import JSON)
ADDED: PerformanceProfiler — performance analysis:
- Message latency distribution (p50, p95, p99)
- Transport throughput per path
- Plugin overhead measurement
- Memory usage tracking
- Regression detection: compares current run against baseline
- Optimization suggestions based on bottlenecks
ADDED: NETWORK_DEV_CODES — frozen error registry.

DevTools API

// Start visualization
visualizer.start({ mode: 'hierarchy', refreshRate: 30 });

// Focus on a specific peer
visualizer.focus(peerId);

// Inspect state at a path
inspector.inspect('game/positions/player1');

// Run a predefined scenario
simulator.runScenario('client-surge', { nodeCount: 100 });

// Compare performance against baseline
profiler.compare(baselineRunId);

Out of scope

Production monitoring → network-plugin-monitor.
Production alerting → network-plugin-monitor.
Simulation engine → network-plugin-simulation.
Framework-specific UI components → future React/Vue/Angular wrappers.

Source mapping

This derives from docs/old-network-planning/ADAPT_5.md §Developer Tooling and PHASE_8.md §Visualization.

Requirement	Source lines	Notes
Network visualizer	`ADAPT_5.md` §Network Visualizer Tool	reworded; modes: hierarchy, messages, performance
State inspector	`ADAPT_5.md` §State Inspector Tool	reworded; diff visualization
Simulation config	`ADAPT_5.md` §Simulation Configuration Tool	reworded; scenario builder
Performance profiling	`ADAPT_5.md` §Performance Profiling Tools	reworded; regression detection

Requirements with no source line

Requirement	Justification
Export to PNG/SVG	Required for documentation and bug reports
Regression detection	Required to catch performance degradation in CI
Scenario sharing	Required for team collaboration on test cases

Verification approach

src/visualizer/visualizer.spec-conformance.test.ts — pins hierarchy rendering, message flow, heat map.
src/inspector/inspector.spec-conformance.test.ts — pins state tree, history, diff.
src/simulator/simulator.spec-conformance.test.ts — pins scenario builder, playback, export/import.
src/profiler/profiler.spec-conformance.test.ts — pins latency distribution, overhead, regression.
src/error-codes.spec-conformance.test.ts — frozen registry.

Migration impact

None — additive only. This package is dev-only and not imported in production builds.

4.3 KiB Raw Permalink Blame History