first commit

docs/networking/network/network-plugin-simulation/src/plugin/simulation-plugin.md

@@ -0,0 +1,62 @@
+# `SimulationPlugin`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Single `NetworkPlugin` that bundles the simulation toolkit (`NetworkSimulator`, `NetworkConditionInjector`, `ChaosEngine`) and ties their lifecycle to a host `NetworkNode`. Every subsystem is exposed as a public field so consumers extend behaviour by reaching past the plugin facade. No-op in production builds so accidentally bundling the plugin into a release does not run chaos against real peers.
+
+## Features
+
+- `disabled` defaults to `process.env.NODE_ENV === "production"`; explicit `disabled: false` overrides for staging environments.
+- `install` / `start` short-circuit when disabled — the plugin remains constructed but inert.
+- `dispose` resets the chaos event log so a re-install starts clean.
+
+## Usage: Basic Example
+
+```ts
+import { NetworkBus, NetworkNode } from "@suaveplan/network";
+import { SimulationPlugin } from "@suaveplan/network-plugin-simulation";
+
+const node = new NetworkNode({ id: "n", networkBus: new NetworkBus() });
+const plugin = new SimulationPlugin({ simulation: { seed: 1 } });
+node.use(plugin);
+await node.start();
+plugin.simulator.advanceBy(10);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { SimulationPlugin } from "@suaveplan/network-plugin-simulation";
+
+const plugin = new SimulationPlugin({
+    simulation: { seed: 42, timeFactor: 1_000 },
+    conditions: {
+        latency: { kind: "constant", latencyMs: 50 },
+        loss: { kind: "random", probability: 0.01 },
+    },
+    chaos: { crashProbability: 0.001 },
+    disabled: false,
+});
+plugin.isActive(); // true
+plugin.simulator.now();
+```
+
+## API Reference
+
+- `class SimulationPlugin implements NetworkPlugin`
+  - Public fields: `simulator`, `conditions`, `chaos`.
+  - `constructor(config: SimulationPluginConfig)`.
+  - `isActive(): boolean`.
+  - `install(node): void` / `start(): void` / `stop(): void` / `dispose(): void`.
+  - `host(): NetworkNode | null` / `isStarted(): boolean`.
+- `interface SimulationPluginConfig` — `{ simulation, conditions?, chaos?, disabled? }`.
+
+## Implementation Notes
+
+- The plugin holds _references_ to subsystems rather than re-exporting their methods so refactors inside any subsystem do not reshape the plugin facade.
+- The default-disabled-in-production guard reads `process.env.NODE_ENV` defensively (`process` may be undefined in the browser); browser callers wanting simulation explicitly pass `disabled: false`.
+- `install` is the only method that gates on `disabled`; the simulator / conditions / chaos fields remain non-null and usable so test code can still exercise them via `plugin.simulator.advanceBy(...)` even while the plugin is "disabled".
+- The four predefined integration scenarios (`server-failure`, `network-partition`, `client-surge`, `cascading-failure`) ship as follow-up changes — they require coordination with `failover`, `topology`, `circuit-breaker`, etc., which lives outside this package's contract.