# Edge Case Catalog

> Every edge case discovered through real E2E testing, documented with its solution.

## Master Edge Case Table

| # | Edge Case | Solution | Discovered | Journey |
|---|-----------|----------|-----------|---------|
| 1 | Cursor IDE squats ports (17+ ports on Windows) | Connect-based detection + specific binding (`127.0.0.1`) + IPv6 bridge | 2026-03-08, verified | J1, J3 |
| 2 | Windows `localhost` resolves to `[::1]` first | IPv6 TCP bridge forwards `[::1]:PORT` to `127.0.0.1:PORT` | 2026-03-08, verified | J1, J3 |
| 3 | `httptools` (C extension) silently fails on Windows | Auto-detect Windows, use `h11` (pure Python HTTP parser) | 2026-03-08, verified | J1 |
| 4 | Tunnel fails, heartbeat returns 500 | Upsert device record on heartbeat (not just update) | 2026-03-08 | J6 |
| 5 | Device registered without tunnel | Registration no longer requires tunnel_url field | 2026-03-08 | J1, J6 |
| 6 | Port 11400 pre-occupied | Adaptive scan: 11400 → 11401 → 11402 → ... (+100 range) | 2026-03-08, verified | J1, J3 |
| 7 | No inference engine found | Auto-install Ollama + pull model for detected VRAM | Designed | J2 |
| 8 | VRAM too small for chosen model | Suggest smaller model from VRAM tier map (7 tiers) | Designed | J2 |
| 9 | Multiple GPUs, VRAM calc wrong | Use `max(GPU VRAM)` not `sum` (multi-GPU VRAM fix) | PR #415 | J1 |
| 10 | Apple Silicon unified memory | 4GB offset applied (OS reserves from unified pool) | Designed | J2 |
| 11 | Corporate firewall blocks tunnel | WSS relay looks like HTTPS, passes through | ADR-009 design | J4, J8 |
| 12 | Relay server down | Fallback to Tailscale/Cloudflare if installed | ADR-009 design | J6, J8 |
| 13 | Relay token expired | Auto-refresh via control stream at 23h | ADR-009 design | J8 |
| 14 | Slow 70B model blocks fast 3B model | yamux stream multiplexing (per-stream flow control) | ADR-009 design | J8 |
| 15 | Network change (WiFi switch) | Re-connect relay on IP change | ADR-009 design | J4, J8 |
| 16 | Ollama crashes mid-session | Proxy returns clear error, doesn't crash itself | PR #415 | J6 |
| 17 | Pydantic v2 + `from __future__ import annotations` | Import `datetime` at runtime, not in `TYPE_CHECKING` block | PRs #433-434 | All |
| 18 | Marketplace node <30% uptime | Auto-removal: set `marketplaceEnabled=false` | PR #430 | J7 |
| 19 | WebSocket blocked by rare proxy | Fallback to Tailscale/Cloudflare providers | ADR-009 design | J8 |
| 20 | Same device reconnects | Drain old yamux session, register new | ADR-009 design | J8 |

## Edge Cases by Category

### Network & Connectivity
1, 2, 4, 5, 6, 11, 12, 15, 19

### Platform-Specific (Windows)
1, 2, 3, 6

### Platform-Specific (macOS)
8, 10

### Hardware & VRAM
7, 8, 9, 10

### Relay-Specific
11, 12, 13, 14, 15, 19, 20

### Resilience & Recovery
4, 5, 12, 13, 15, 16, 18, 20

### Runtime Compatibility
3, 17

## Adding New Edge Cases

When you discover a new edge case:

1. Add a row to the master table above
2. Note which journey(s) it affects
3. Document the solution
4. Add a test in `tests/` that covers it
5. If it's platform-specific, note which platform
6. Update the relevant journey file in `docs/grounding/journeys/`
