Architecture: net.connect() and connection callbacks ...

Well, I'd be up for more documentation in network.h - although the descriptions there do actually cover what happens quite well. Maybe a comment showing the flow of function calls would help to clear things up.

For gethostbyname it's worth looking at what's been done already. That problem has already been solved for the existing ESP8266 stuff.

JSNetwork stores the string in gethostbyname, then returns 0xFFFFFFFF (an invalid IP) to signal that the 'connect' call should sort everything out.

So now your code looks like:

hostIp = "";
state = IDLE;
function gethostbyname(name) {
  hostName = name;
  esp8266_gethostaddress(name);
  return 0xFFFFFFFF;
}
function esp8266_gotHostAddress(ip) {
   hostIp =  ip;
   if (state==BUSY_HOSTNAME_AND_CONNECT)
    realconnect();
  else
   state = IDLE;
}
function realconnect() {
  state = BUSY_CONNECTING;
  esp8266_connect();
}
function esp8266_connected() {
  state = IDLE;
}
function connect(ip, ...) {
  if (ip!=0xFFFFFFFF) hostIp==ip;
 if (state==BUSY_HOSTNAME)
   state = BUSY_HOSTNAME_AND_CONNECT;
 else
  realconnect();
  return -1;
}

But please, if you have questions about this, can you look at the existing implementations of linux, jsnetwork, and wiznet to try and get some ideas first? At this rate I'm basically telling you step by step how to implement every function.