OpenSpec Change: network-plugin-simulation

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

Why

Validating network resilience requires testing scenarios that are dangerous or impossible to reproduce in production: cascading host failures, network partitions, sudden client surges, and symmetric NAT blockages. A simulation framework enables deterministic, reproducible testing of the entire network stack under controlled conditions. This is essential for verifying the resilience claims of the tiered mesh architecture.

This plugin provides virtual network environments for testing: virtual nodes, predefined scenarios, network condition injection, and deterministic execution with seeded randomness.

What changes

ADDED: SimulationPlugin class implementing NetworkPlugin (dev-only, no-op in production).
ADDED: NetworkSimulator — creates and manages virtual networks. Supports:
- Deterministic simulation with configurable seed
- Time acceleration/deceleration (simulated time vs wall-clock time)
- Virtual node factories with configurable capabilities
- Network topology creation (star, mesh, tiered, custom)
ADDED: ScenarioRunner — executes predefined test scenarios with setup, event sequence, success criteria, and metric collection. Supports checkpointing for long scenarios.
ADDED: VirtualNode — simulated peer that uses the same NetworkNode and plugin code as real nodes but operates in simulated time with injected TimerController.
ADDED: NetworkConditionInjector — simulates realistic network conditions:
- Latency models: constant, random distribution, geographic-based
- Packet loss patterns: random, burst, connection-based
- Bandwidth limitations: fixed, variable, congestion-based
- Jitter: latency variation over time
- Connection disruptions: temporary and permanent
ADDED: ChaosEngine — injects random failures for chaos testing:
- Probabilistic peer crashes
- Targeted transport failures
- Partition injection
- Random message drops
ADDED: PredefinedScenarios:
- ServerFailureScenario — disconnect server, verify client-side takeover
- NetworkPartitionScenario — split mesh, verify independent operation, heal and reconcile
- ClientSurgeScenario — rapid peer growth, verify promotion and hierarchy adaptation
- CascadingFailureScenario — sequential host failures, verify circuit breaker and recovery
ADDED: NETWORK_SIM_CODES — frozen error registry.

Scenario definition format

interface SimulationScenario {
  name: string;
  seed: number;
  initialTopology: NetworkTopologyConfig;
  nodeCount: number;
  events: ScenarioEvent[];
  networkConditions: NetworkConditionConfig;
  successCriteria: SuccessCriterion[];
}

interface ScenarioEvent {
  timeMs: number;           // simulated time
  type: 'join' | 'leave' | 'fail' | 'partition' | 'heal' | 'condition-change';
  targetPeerIds?: string[];
  condition?: NetworkConditionConfig;
}

Out of scope

Production deployment → this is a dev/test-only package.
Performance benchmarking → network-plugin-monitor provides production metrics.
Visual simulation UI → network-plugin-devtools provides visualization.

Source mapping

This derives from docs/old-network-planning/PHASE_8.md §Simulation Framework and PHASE_10.md §End-to-End Tests.

Requirement	Source lines	Notes
Virtual node factories	`PHASE_8.md` §Virtual Node Implementation	reworded; uses real `NetworkNode` code
Scenario runner	`PHASE_8.md` §Scenario Runner	reworded; declarative format
Network condition simulation	`PHASE_8.md` §Network Condition Simulation	verbatim: latency, loss, bandwidth, jitter
Predefined scenarios	`PHASE_8.md` §Predefined Simulation Scenarios	verbatim: 4 scenarios
Deterministic simulation	`PHASE_8.md` §Simulation Framework	verbatim: seed support

Requirements with no source line

Requirement	Justification
`ChaosEngine`	Required for randomized failure injection beyond predefined scenarios
Time acceleration	Required to run long scenarios quickly in CI
Checkpointing	Required for debugging long-running scenario failures

Verification approach

src/simulator/simulator.spec-conformance.test.ts — pins virtual network creation, seed determinism, time control.
src/scenario/scenario.spec-conformance.test.ts — pins scenario execution, success criteria, event sequencing.
src/virtual-node/virtual-node.spec-conformance.test.ts — pins behavior fidelity, resource simulation.
src/conditions/conditions.spec-conformance.test.ts — pins latency, loss, bandwidth, jitter injection.
src/chaos/chaos.spec-conformance.test.ts — pins random failures, partition injection, message drops.
src/scenarios/server-failure.spec-conformance.test.ts — pins server disconnect, client takeover.
src/scenarios/partition.spec-conformance.test.ts — pins split, independent operation, heal, reconcile.
src/scenarios/client-surge.spec-conformance.test.ts — pins rapid growth, promotion, stabilization.
src/scenarios/cascading-failure.spec-conformance.test.ts — pins sequential failures, circuit breaker, recovery.
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.

5.5 KiB Raw Permalink Blame History