Tasks — network-plugin-simulation

Blocked on: network-core, network-plugin-protocol.

1. Scaffold

1.1 packages/network/network-plugin-simulation/ with package.json (@suaveplan/network-plugin-simulation@0.0.0), tsconfig.json, vitest.config.ts, README.md.
1.2 Workspace deps: @suaveplan/network, @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/fsm, @suaveplan/timing, @opentelemetry/api, zod.
1.3 sideEffects: false.
1.4 Marked as devOnly: true in workspace config.

2. Types

2.1 src/types/simulation.types.ts — SimulationConfig, VirtualNodeConfig, NetworkTopologyConfig.
2.2 src/types/scenario.types.ts — SimulationScenario, ScenarioEvent, SuccessCriterion.
2.3 src/types/condition.types.ts — NetworkConditionConfig, LatencyModel, LossPattern.
2.4 src/error-codes.ts — defineCodes("NET_SIM", [...]).

3. Network simulator

3.1 src/simulator/network-simulator.ts — NetworkSimulator.
3.2 Deterministic with configurable seed.
3.3 Time acceleration/deceleration factor.
3.4 Virtual node factory with configurable capabilities.
3.5 Topology creation: star, mesh, tiered, custom.

4. Virtual node

4.1 src/virtual-node/virtual-node.ts — VirtualNode.
4.2 Uses real NetworkNode and plugin code.
4.3 Operates with injected TimerController for simulated time.
4.4 Supports failure injection (crash, disconnect, freeze).

5. Scenario runner

5.1 src/scenario/scenario-runner.ts — ScenarioRunner.
5.2 Declarative scenario execution: setup → event sequence → success criteria.
5.3 Checkpointing for long scenarios.
5.4 Metric collection during execution.

6. Network condition injector

6.1 src/conditions/network-condition-injector.ts — NetworkConditionInjector.
6.2 Latency models: constant, random, geographic.
6.3 Packet loss: random, burst, connection-based.
6.4 Bandwidth limits: fixed, variable, congestion-based.
6.5 Jitter: latency variation over time.
6.6 Connection disruptions: temporary, permanent.

7. Chaos engine

7.1 src/chaos/chaos-engine.ts — ChaosEngine.
7.2 Probabilistic peer crashes.
7.3 Targeted transport failures.
7.4 Partition injection.
7.5 Random message drops.

8. Predefined scenarios

8.1 src/scenarios/server-failure-scenario.ts — disconnect server, verify client takeover.
8.2 src/scenarios/network-partition-scenario.ts — split mesh, verify independent operation, heal, reconcile.
8.3 src/scenarios/client-surge-scenario.ts — rapid peer growth, verify promotion, stabilization.
8.4 src/scenarios/cascading-failure-scenario.ts — sequential host failures, verify circuit breaker, recovery.

9. Plugin wrapper

9.1 src/plugin/simulation-plugin.ts — SimulationPlugin implements NetworkPlugin.
9.2 No-op in production (process.env.NODE_ENV === 'production').
9.3 Exposes simulator and scenario runner on plugin API.

10. Spec

10.1 Update openspec/specs/network/spec.md with NET-43.

11. Conformance tests

11.1 src/simulator/simulator.spec-conformance.test.ts — virtual network, determinism, time control.
11.2 src/scenario/scenario.spec-conformance.test.ts — execution, success criteria, events.
11.3 src/virtual-node/virtual-node.spec-conformance.test.ts — behavior fidelity, failure injection.
11.4 src/conditions/conditions.spec-conformance.test.ts — latency, loss, bandwidth, jitter.
11.5 src/chaos/chaos.spec-conformance.test.ts — random failures, partitions, drops.
11.6 src/scenarios/server-failure.spec-conformance.test.ts — server disconnect, takeover.
11.7 src/scenarios/partition.spec-conformance.test.ts — split, heal, reconcile.
11.8 src/scenarios/client-surge.spec-conformance.test.ts — growth, promotion, stabilization.
11.9 src/scenarios/cascading-failure.spec-conformance.test.ts — failures, circuit breaker, recovery.
11.10 src/error-codes.spec-conformance.test.ts — frozen registry.

12. Verify

12.1 bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-simulation green.
12.2 bunx turbo test:coverage --filter=@suaveplan/network-plugin-simulation 100/100/100/100.
12.3 bun scripts/openspec-conformance.ts @suaveplan/network-plugin-simulation PASS.

Audit Note (2026-05-05)

Status: PARTIAL — core sections (1–7, 9–12, plus dep-graph) shipped at full quality (100/100/100/100 coverage, 100% docs, openspec-conformance PASS, 86 tests across 8 files).

Deferred to follow-up changes (one per scenario so each can wire into its specific dependency set without inflating the core simulator surface):

Section 8.1 (ServerFailureScenario) → follow-up network-plugin-simulation-server-failure. Depends on network-plugin-failover + network-plugin-server-bridge for realistic takeover testing.
Section 8.2 (NetworkPartitionScenario) → follow-up network-plugin-simulation-partition. Depends on network-plugin-partition + network-plugin-state for split / heal / reconcile assertions.
Section 8.3 (ClientSurgeScenario) → follow-up network-plugin-simulation-client-surge. Depends on network-plugin-topology for promotion/stabilization.
Section 8.4 (CascadingFailureScenario) → follow-up network-plugin-simulation-cascading-failure. Depends on network-plugin-circuit-breaker + network-plugin-failover.
Sections 11.6–11.9 conformance tests ship with the corresponding follow-up.

The shipped core (NetworkSimulator, VirtualNode, ScenarioRunner, NetworkConditionInjector, ChaosEngine, SimulationPlugin) covers NET-43 from the network spec and is fully self-contained.

5.8 KiB Raw Permalink Blame History Unescape Escape