whalescale/AGENTS.md

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.