# Agents Guide: Whalescale

## Architecture: Integrated Plane

Whalescale is a unified agent — the control plane and data plane share the same process, the same encryption sessions, and the same UDP sockets. **There is no separate WireGuard process.** All logic — discovery, NAT traversal, encryption, multipath scheduling, and TUN management — lives in one program.

```
┌──────────────────────────────────────────────┐
│              TUN Device (IP packets)          │
├──────────────────────────────────────────────┤
│         Reordering Buffer                     │
├──────────────────────────────────────────────┤
│          Path Scheduler                       │
├───────────┬───────────┬──────────────────────┤
│   Path 1  │   Path 2  │      Path N          │
│  5G/UDP   │  WiFi/UDP │    IPv6/UDP          │
├───────────┴───────────┴──────────────────────┤
│       Noise_IK Session Manager                │
├──────────────────────────────────────────────┤
│       Whalescale Agent (single process)       │
└──────────────────────────────────────────────┘
```

**Never split logic across processes or re-introduce a WireGuard dependency.** The unified architecture exists specifically to avoid the coordination conflicts that arise when the control plane and data plane are separate.

## Core Technical Constraints

* **Identity:** Uses Ed25519 keys. The Whalescale Node ID **is** the Ed25519 public key. No separate WireGuard key.
* **Handshake:** Noise_IK, implemented in userspace via an established Rust Noise library (not the WireGuard kernel module).
* **Discovery:** No DHT. Discovery relies on **Manual Bootstrap** → **Anchors** → **Gossip** → **LKG Cache**.
* **Connectivity:** Best-effort UDP hole punching. Symmetric ↔ Symmetric pairs communicate via anchor relay (encrypted forwarding, not TURN).
* **Multipath:** A single peer session can use multiple network interfaces simultaneously (e.g., 5G + WiFi) with a reordering buffer.
* **IPv6:** Preferred transport when available. Eliminates NAT entirely. Always attempt IPv6 paths first.
* **Anchors:** First-class concept. At least one anchor (cone NAT or public IP, stable address) is required for the network to support mobile/symmetric-NAT nodes. Recommend at least two anchors on different ISPs.
* **No port prediction/sweeping:** Categorically ineffective against CGNAT. Do not re-implement.

## What Whalescale Is NOT

* **Not a WireGuard wrapper.** Whalescale owns its data plane.
* **Not a DHT.** No Kademlia, no distributed hash tables.
* **Not a TURN/STUN service.** Anchor relay is packet forwarding through existing encrypted tunnels, not dedicated relay infrastructure.
* **Not designed for internet-scale.** The target is trusted, known-peer networks (tens to low hundreds of nodes).

## Module Structure (Target)

Rust workspace with the following crates:

* `crates/whalescale-agent/` — Main entry point, event loop, configuration (binary crate)
* `crates/whalescale-session/` — Noise_IK handshake, session state, key rotation
* `crates/whalescale-transport/` — UDP socket management, packet framing, send/receive
* `crates/whalescale-path/` — Path discovery, scheduling, health monitoring, reordering buffer
* `crates/whalescale-multipath/` — Multipath scheduler (weighted round-robin), bandwidth estimation, feedback loop, reordering buffer logic, test bench framework
* `crates/whalescale-gossip/` — Gossip protocol, LKG cache, anti-entropy, conflict resolution
* `crates/whalescale-nat/` — NAT type detection, hole punching, UPnP/NAT-PMP/PCP
* `crates/whalescale-anchor/` — Anchor management, relay forwarding, mutual keepalive
* `crates/whalescale-tun/` — TUN device read/write, IP packet routing
* `crates/whalescale-bootstrap/` — Pre-session discovery protocol, manual bootstrap
* `crates/whalescale-crypto/` — Ed25519 key management, Noise library integration (thin wrapper)
* `crates/whalescale-types/` — Shared types, constants, and protocol definitions

## Development Context

* **Language:** Rust.
* **Module:** `eganshub.net/whalescale`.
* **Critical Files:**
  * `DESIGN.md`: The primary source of truth for architectural decisions.
  * `MULTIPATH.md`: Full specification for the multipath transport subsystem.
  * `ANTI_PATTERN.md`: Crucial for avoiding regressive design (e.g., trying to add a DHT, re-introducing WireGuard, or implementing port prediction).

## Implementation Phases

| Phase | Scope |
|-------|-------|
| 1 | Noise_IK session, single path, single peer, TUN integration |
| 2 | Multipath transport — weighted round-robin scheduler, reordering buffer, path management, feedback loop, bandwidth estimation |
| 3 | Multi-peer session management, LKG cache, gossip |
| 4 | NAT traversal (hole punching, UPnP/PCP, anchor signaling) |
| 5 | LAN discovery, IPv6 preference, anchor relay |
| 6 | Adaptive path scheduling, test bench framework, scheduler comparison |

**Phase 2 is the novel work.** The multipath transport has significant open questions (inner TCP interaction, reordering depth tuning, scheduler optimality) that require empirical validation. See `MULTIPATH.md` §11 for the test bench specification.