suaveplan/openspec/archive/2026-05-05-network-plugin-simulation/tasks.md

# Tasks — network-plugin-simulation

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

## 1. Scaffold

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

## 2. Types

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

## 3. Network simulator

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

## 4. Virtual node

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

## 5. Scenario runner

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

## 6. Network condition injector

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

## 7. Chaos engine

- [x] 7.1 `src/chaos/chaos-engine.ts` — `ChaosEngine`.
- [x] 7.2 Probabilistic peer crashes.
- [x] 7.3 Targeted transport failures.
- [x] 7.4 Partition injection.
- [x] 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

- [x] 9.1 `src/plugin/simulation-plugin.ts` — `SimulationPlugin` implements `NetworkPlugin`.
- [x] 9.2 No-op in production (`process.env.NODE_ENV === 'production'`).
- [x] 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

- [x] 11.1 `src/simulator/simulator.spec-conformance.test.ts` — virtual network, determinism, time control.
- [x] 11.2 `src/scenario/scenario.spec-conformance.test.ts` — execution, success criteria, events.
- [x] 11.3 `src/virtual-node/virtual-node.spec-conformance.test.ts` — behavior fidelity, failure injection.
- [x] 11.4 `src/conditions/conditions.spec-conformance.test.ts` — latency, loss, bandwidth, jitter.
- [x] 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.
- [x] 11.10 `src/error-codes.spec-conformance.test.ts` — frozen registry.

## 12. Verify

- [x] 12.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-simulation` green.
- [x] 12.2 `bunx turbo test:coverage --filter=@suaveplan/network-plugin-simulation` 100/100/100/100.
- [x] 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.