# 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

```typescript
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.