docs: add E2E full gap coverage design document

Covers all 3 priority tiers from e2e_gaps.md: monitoring,
headers, shutdown/drain, clustering, leaf nodes, gateways,
MQTT, WebSocket, JetStream extensions, and advanced features.

docs/plans/2026-03-12-e2e-full-gap-coverage-design.md

@@ -0,0 +1,102 @@
+# E2E Test Full Gap Coverage Design
+
+**Date:** 2026-03-12
+**Scope:** All 3 priority tiers from `e2e_gaps.md` (~45-55 new tests)
+
+## Decisions
+
+- **Multi-server fixtures:** Real multi-process only where required (cluster, leaf, gateway). Single server with feature flags for MQTT and WebSocket.
+- **Gateway topology:** Minimal two-server (not full multi-cluster).
+- **Shutdown/drain:** Both client drain and server shutdown tests.
+- **MQTT client:** MQTTnet NuGet package.
+- **WebSocket client:** Built-in `System.Net.WebSockets.ClientWebSocket` speaking raw NATS protocol.
+
+## New Fixtures
+
+| Fixture | Servers | Config |
+|---------|---------|--------|
+| `ClusterFixture` | 3 `NatsServerProcess` instances | Route config pointing at each other |
+| `LeafNodeFixture` | 2 instances (hub + leaf) | Leaf config pointing at hub |
+| `GatewayFixture` | 2 standalone instances | Gateway config connecting them |
+| `MqttServerFixture` | 1 instance | MQTT port enabled |
+| `WebSocketServerFixture` | 1 instance | WebSocket port enabled |
+
+Existing `MonitorServerFixture` is already created but unused — use as-is.
+
+## New Test Files
+
+### 1. `MonitoringTests.cs` (existing `MonitorServerFixture`)
+
+- `/varz` — returns JSON with server_name, version, connections
+- `/connz` — reflects connected client count
+- `/healthz` — returns 200 OK
+
+### 2. `HeaderTests.cs` (existing `NatsServerFixture`)
+
+- Publish with headers, receive with headers intact
+- Multiple headers on a single message
+- Empty header value round-trip
+
+### 3. `ShutdownDrainTests.cs` (own server per test, no shared fixture)
+
+- Client drain completes in-flight messages then disconnects
+- Server kill mid-connection — client detects disconnection gracefully
+
+### 4. `ClusterTests.cs` (new `ClusterFixture`)
+
+- Message published on node A received by subscriber on node B
+- Subscriber on node C receives after joining mid-stream
+- Queue group across cluster nodes delivers once total
+
+### 5. `LeafNodeTests.cs` (new `LeafNodeFixture`)
+
+- Message published on hub received by leaf subscriber
+- Message published on leaf received by hub subscriber
+- Only subscribed subjects propagate to hub
+
+### 6. `GatewayTests.cs` (new `GatewayFixture`)
+
+- Message crosses gateway from server A to server B
+- No cross-delivery when no interest on remote side
+
+### 7. `MqttTests.cs` (new `MqttServerFixture`)
+
+- MQTT subscribe → NATS publish → MQTT receives
+- MQTT publish → NATS subscribe → NATS receives
+- MQTT QoS 0 and QoS 1 delivery
+
+### 8. `WebSocketTests.cs` (new `WebSocketServerFixture`)
+
+- Connect via WebSocket, subscribe, receive message
+- Pub/sub round-trip over WebSocket
+
+## Additions to Existing `JetStreamTests.cs`
+
+- Push consumer (server-initiated delivery)
+- AckAll policy
+- AckNone policy
+- Interest retention
+- WorkQueue retention
+- Ordered consumer
+- Stream mirroring
+- Stream sourcing
+
+## New File: `AdvancedTests.cs`
+
+- JWT authentication (inline server with JWT config)
+- Account imports/exports (cross-account service call)
+- Subject transforms
+- Config file loading (full config file, verify behavior)
+- System events (`$SYS.>` subscription, detect connect event)
+- Max connections enforcement
+- Service latency tracking
+
+## New NuGet Dependency
+
+- **MQTTnet** — added to `Directory.Packages.props` and `NATS.E2E.Tests.csproj`
+
+## Estimated Impact
+
+- ~45-55 new tests
+- 5 new fixtures + 7 new test files + 1 existing file extended
+- Total E2E: ~90-95 tests (from current 42)