Initial Commit

openspec/archive/2026-05-12-enterprise-network-testing/tasks.md

@@ -0,0 +1,106 @@
+# Tasks: enterprise-network-testing
+
+**Change ID**: enterprise-network-testing
+**Package**: `@suaveplan/network-testing`
+**Target path**: `universal/network/network-testing`
+**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/testing`
+
+---
+
+## 1. Scaffold
+
+- [x] Create `universal/network/network-testing/` with `src/`, `tests/`, and all feature subdirectories.
+- [x] Write `package.json` at version `0.1.0`: `"sideEffects": false`, exports map, deps per `proposal.md`.
+- [x] Write `tsconfig.json`, `vitest.config.ts`, scripts.
+
+---
+
+## 2. Types and error codes
+
+- [x] Define all public types in `src/types/common.ts`: `MemoryTransport`, `MemoryTransportPair`, `MemoryTransportOptions`, `FakeWebSocketAdapter`, `FakeWebSocketHandle`, `FakeWebSocketOptions`, `NetworkConditions`, `LatencyDistribution`, `ConditionSimulator`, `SimulationStats`, `TestPeer`, `TestPeerOptions`, `NetworkEventCapture`.
+- [x] Write `src/types/common.md` (≥200 words, simple + advanced examples).
+- [x] Define error codes in `src/error-codes.ts`.
+- [x] Write Zod schemas in `src/types/schemas.ts` + `src/types/schemas.md`.
+
+---
+
+## 3. Memory transport (`src/transports/memory-transport/`)
+
+- [x] Implement `createMemoryTransport(options?)` — returns `MemoryTransportPair`:
+  - Two ends share a queue; `client.send(m)` pushes to `server.messages`, calls `server`'s `onmessage`.
+  - `connect()` sets both ends to `connected`.
+  - `disconnect()` sets both ends to `disconnected`, fires `ondisconnect`.
+  - Injectable `Clock` for `latencyMs` simulation (use `setTimeout` equivalent on clock).
+- [x] Write `memory-transport.test.ts` (≤500 lines): send client→server, server→client, disconnect, latency.
+- [x] Write `memory-transport.md` (≥200 words).
+
+---
+
+## 4. Fake WebSocket adapter (`src/transports/fake-websocket/`)
+
+- [x] Implement `createFakeWebSocketAdapter(options?)`:
+  - `connect(url, protocols?)` — creates a `FakeWebSocketHandle`, stores in `connections`.
+  - `simulateMessage(data)` — calls `onmessage` on all handles.
+  - `simulateError(error)` — calls `onerror` on all handles.
+  - `simulateClose(code?, reason?)` — calls `onclose` on all handles.
+  - `FakeWebSocketHandle.send(data)` — pushes to `sentMessages`.
+  - `autoConnect: true` (default) calls `onopen` immediately after `connect`.
+- [x] Write `fake-websocket.test.ts` (≤500 lines): connect, send tracked, simulateMessage received, close, error.
+- [x] Write `fake-websocket.md` (≥200 words).
+
+---
+
+## 5. Condition simulator (`src/simulators/condition-simulator/`)
+
+- [x] Implement `createConditionSimulator(conditions)`:
+  - `wrap(transport)` — returns a proxy that intercepts `send()`:
+    - Roll packet drop: if `rng.next() < conditions.packetLossRate`, drop (return without sending).
+    - Compute latency: sample from `conditions.latencyMs` distribution using injectable `Rng`.
+    - Add jitter: ± `conditions.jitterMs` random offset.
+    - After delay, call real `transport.send()`.
+  - `setConditions(partial)` — update conditions on the fly.
+  - `reset()` — restore original conditions, clear stats.
+  - Track `sentMessages`, `droppedMessages`, `totalLatencyMs`.
+- [x] Write `condition-simulator.test.ts` (≤500 lines): packet drop rate, latency added, stats tracked.
+- [x] Write `condition-simulator.md` (≥200 words).
+
+---
+
+## 6. Test peer factory (`src/factories/test-peer/`)
+
+- [x] Implement `createTestPeer(options?)`:
+  - Auto-generates `id` (`test-peer-${n}`) and `address` (`127.0.0.1:${port}`).
+  - Fluent builder: `withCapabilities`, `withRegion`, `withHealth`.
+  - `asRegistryEntry()` — returns `RegistryEntry` compatible shape.
+  - `asBootstrapSeed()` — returns `SeedConfig` compatible shape.
+- [x] Write `test-peer.test.ts` + `test-peer.md`.
+
+---
+
+## 7. Network event capture (`src/assertions/event-capture/`)
+
+- [x] Implement `createNetworkEventCapture(eventBus)`:
+  - Subscribes to all events on the bus; pushes to `events` array.
+  - `waitFor(event, timeout?)` — returns a `Promise` that resolves when the event fires; rejects after timeout.
+  - `assertEventEmitted(event, predicate?)` — throws `NetworkTestingError(NET_TEST_EVENT_NOT_EMITTED)` if not found.
+  - `assertEventCount(event, count)` — throws if actual count !== expected.
+  - `clear()` — empties `events`.
+- [x] Write `event-capture.test.ts` + `event-capture.md`.
+
+---
+
+## 8. Integration test (`tests/integration.test.ts`)
+
+- [x] Create a `MemoryTransportPair`, send messages, verify receipt.
+- [x] Wrap a transport with `ConditionSimulator` (50% packet loss), send 100 messages, verify ~50 dropped.
+- [x] Use `FakeWebSocketAdapter` with a hypothetical client, simulate messages, verify received.
+
+---
+
+## 9. Docs and verify
+
+- [x] All per-file `.md` files per layout in `proposal.md`.
+- [x] `universal/network/network-testing/README.md`.
+- [x] `bunx turbo lint typecheck test test:coverage --filter=@suaveplan/network-testing` — all green, 100%.
+- [x] `bun scripts/publish.ts --package @suaveplan/network-testing`.
+- [x] Update `CLAUDE.md`. Archive change folder.