Initial Commit

openspec/archive/2026-05-05-network-plugin-simulation/proposal.md

@@ -0,0 +1,105 @@
+# 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.