# Bellona Network Impairment Test Plan

Status: `180.C.16.04` deterministic fixture coverage.

Implementation date: 2026-04-23.

This plan adds automated fixture coverage for gateway restart, host reconnect,
host sleep/wake, packet loss, high latency, and a TURN fallback placeholder. It
does not claim real packet shaping, physical MacBook sleep/wake, live gateway
process restart, or WebRTC TURN relay evidence yet.

## Sources Reviewed

Local implementation references:

- `apps/bellona/remote-host/src/gateway-connection.ts`
- `apps/bellona/remote-host/src/gateway-connection.test.ts`
- `testing/bellona/remote-control/fake-gateway-transport.ts`
- `testing/bellona/remote-control/fake-host-adapter.ts`
- `docs/domains/bellona/extras/remote-control/compatibility-matrix.md`
- `docs/domains/bellona/extras/remote-control/external-implementation-research-2026-04-21.md`
- `docs/domains/bellona/extras/remote-control/hardware-rig-inventory.md`
- `docs/domains/bellona/extras/remote-control/hetzner-reference-deployment.md`

Primary external references retained from the Phase 180 research notes:

- WebRTC ICE/STUN/TURN overview:
  <https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API/Protocols>
- coturn TURN server: <https://github.com/coturn/coturn>

## Automated Scenarios

`testing/bellona/remote-control/network-impairment.ts` exposes
`createRemoteControlNetworkImpairmentPlan()`,
`runRemoteControlNetworkImpairmentScenario()`, and
`runRemoteControlNetworkImpairmentSuite()`.

The deterministic suite covers:

| Scenario                    | Automated coverage                                                               | Live evidence still required                                              |
| --------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `gateway-restart`           | Disconnect connected fake host as `gateway.restart`, reconnect, then dispatch    | Real gateway process restart logs and reconnect timing                    |
| `host-reconnect`            | Simulate transient network drop, reconnect same device identity, then dispatch   | Two-MacBook Wi-Fi drop/rejoin or interface-toggle run                     |
| `host-sleep-wake`           | Simulate `host.sleep`, reconnect on wake, and verify post-wake command success   | Physical macOS sleep/wake, LaunchAgent recovery, and readiness evidence   |
| `packet-loss`               | Inject retrying progress and packet-loss metadata before command success         | OS/network-emulator packet-loss shaping on `NET-IMPAIR-01`                |
| `high-latency`              | Inject high-latency progress and command result metrics                          | OS/network-emulator high-latency shaping on `NET-IMPAIR-01`               |
| `turn-fallback-placeholder` | Record that TURN-only media relay is required before cross-network media signoff | WebRTC signaling, TURN credentials, TURN-only relay smoke, teardown proof |

## Release Gate Rules

The alpha gate must treat this suite as deterministic coverage only. It can
prove control-plane behavior under simulated impairment, but it cannot replace
hardware evidence for network shaping, sleep/wake, or TURN relay.

Before MVP alpha can claim network resilience, the release evidence must attach:

- gateway restart run with command and audit continuity after reconnect
- host reconnect run after a real network drop or interface toggle
- macOS sleep/wake run with LaunchAgent recovery and host readiness
- packet-loss and high-latency runs using an OS network emulator or equivalent
- TURN-only WebRTC relay smoke once live media signaling exists
- audit entries showing degraded/failed/recovered states rather than silent
  transport recovery

## Verification

The committed automated gate is:

```bash
pnpm exec vitest run --config vitest.config.ts tests/network-impairment.test.ts --reporter=verbose
pnpm nx run-many -p @bellona/remote-control-testing -t lint,typecheck,test,build --skip-nx-cache --verbose
```

The first command proves the individual impairment scenarios and the canonical
suite order. The second command keeps the reusable test harness buildable and
covered by Nx.
