AGUWA आगुवा

Kuramoto Adaptive Phase Coupling

Oscillator-based mesh synchronization that couples MANI clocks, dynamically adjusts connection capacity, and offloads compute to Worker threads.

v3.3.0 • Layer 16.5

The Guide Who Keeps Pace

An aguwa is a leader or guide — one who walks at the front and sets the rhythm for the group. In yakmesh, AGUWA is the protocol that makes every node walk in step: it models each peer as a Kuramoto oscillator, coupling their MANI clocks through phase differences weighted by exponential decay. When a peer drifts, the coupling pulls it back. When the network is overloaded, AGUWA shrinks the admission window. When conditions improve, it widens again. The mesh breathes together.

AGUWA & MANI

MANI provides the raw time synchronization — GPS, NTP, and peer-to-peer clock exchange. AGUWA sits above MANI at Layer 16.5, using those clock readings as inputs to the Kuramoto coupling model. Think of MANI as the individual clocks; AGUWA is the conductor that keeps them in sync.

Kuramoto Oscillator Model

Each peer is modeled as an oscillator with its own natural frequency. The coupling formula synchronizes phases using exponential-decay weighted differences:

dθ_i/dt = ω_i + (K/N) ∑ sin(θ_j − θ_i) × e^−λΔt

ω_i = natural frequency • K = coupling constant • λ = decay rate • Δt = time since last heartbeat

Natural Frequency Derivation

The natural frequency ω_i is derived from the peer’s available time sources, in priority order:

Hardware / Atomic — Local high-precision receivers (e.g., Atomic clock, GPS, Stratum-1) (highest confidence)
NTP — Network Time Protocol sources
Peer consensus — Median of connected peer clocks
Local monotonic — Fallback to system monotonic clock

Coupling Constants

Tier	K value	Context
Bootstrap	0.25	Trusted bootstrap nodes — strongest coupling
Peer	0.10	Regular mesh peers
GPS	0.04	GPS-calibrated peers (already accurate)
NTP	0.01	NTP-only peers (weakest coupling)

AGUWA Score

Each peer receives a composite score reflecting its synchronization quality:

score = 0.4×uptime + 0.2×peerCount + 0.2×maniSync + 0.2×gossipLag

Factor	Weight	Description
uptime	0.4	Normalized uptime (time since startup / 24h, capped at 1.0)
peerCount	0.2	Connected peers / max capacity
maniSync	0.2	MANI clock synchronization quality (0–1)
gossipLag	0.2	Inverse gossip latency (lower lag = higher score)

PeerPhaseBuffer

Phase data for all peers is stored in a SharedArrayBuffer with 32-byte slots. This enables lock-free concurrent access from the main thread and Worker threads:

Offset	Size	Field
0	8 bytes	Phase angle (Float64)
8	8 bytes	Natural frequency (Float64)
16	8 bytes	Last heartbeat timestamp (Float64)
24	8 bytes	Flags: admission state, stale marker, GPS calibrated

Dynamic Capacity

AGUWA adjusts the maximum number of peer connections in real-time:

effectiveMax = maxPeers × networkMul × timeMul

networkMul

0 peers	1.5×
50% capacity	1.0×
80%+ capacity	0.8×

timeMul

Good sync	1.2×
Moderate sync	1.0×
Poor sync	0.7×

Worker Thread Offloading

When the peer count exceeds a threshold, AGUWA offloads coupling calculations to a dedicated Worker thread to keep the main event loop responsive:

// Main thread delegates to Worker when peers > threshold
if (peerCount > WORKER_THRESHOLD) {
    worker.postMessage({
        type: 'couple',
        buffer: peerPhaseBuffer,   // SharedArrayBuffer
        peerCount,
        couplingConstants
    });
}

Hardware Calibration & Order Parameter

Hardware Calibration

Peers with high-precision time sources (atomic/GPS receivers) receive the hardware-calibrated flag in PeerPhaseBuffer. Their natural frequencies are treated as ground truth, and their coupling constants are reduced (0.04) because they’re already accurate.

Order Parameter

The Kuramoto order parameter r measures global coherence: r = 1.0 means perfect synchronization, r = 0.0 means random phases. AGUWA reports this value in the /api/aguwa endpoint.

API Endpoints

Endpoint	Description
`GET /api/aguwa`	Phase coupling status: order parameter, peer phases, capacity, Worker state
`GET /api/aguwa/phases`	Raw PeerPhaseBuffer dump (all peer slots)
`GET /api/aguwa/capacity`	Dynamic capacity calculation breakdown

Version History

Version	Changes
v3.3.0	Initial implementation: Kuramoto coupling model, PeerPhaseBuffer (SharedArrayBuffer), dynamic capacity (networkMul × timeMul), AGUWA score (0.4/0.2/0.2/0.2 weights), Worker thread offloading, GPS calibration, order parameter calculation.

Continue the Journey

← Previous

MANI

Time synchronization

KARMA

Reputation system