To achieve thousands of concurrent network connections and file operations
without ever blocking the host thread (whether that is the V8 event loop or
the HAUKI-X86 bare-metal kernel), we must architect the VM to act as a massive
state machine.
We will abandon traditional blocking I/O and avoid callback hell. Instead, we
implement Engine-Level Coroutines.
Here is the architectural specification for Phase 3: The I/O and Concurrency
Model.
1. The Execution Context (CTX)
An object's execution state is no longer hardcoded to the VM's global
registers. The Master Context maintains an array of Execution Contexts (Green
Threads).
When an object's function is invoked (e.g., a network packet arrives for a
player), the engine allocates a CTX record.
| Offset | Type (32-bit) | Field | Description |
|---|---|---|---|
| 0x00 | uint32 | oid | The Object ID currently executing. |
| 0x04 | uint32 | ip | The Instruction Pointer. |
| 0x08 | uint32 | sp | The current Shadow Stack Pointer. |
| 0x0C | uint32 | gas_limit | Remaining execution ticks before a forced yield.
|
The VM has a Run Queue (contexts ready to execute) and a Wait Table (contexts
waiting on I/O).
2. The Asynchronous Syscall Contract (Await)
The VM knows nothing about asynchronous logic. To the bytecode, a network read
looks perfectly synchronous. The magic happens in the handshake between the
JIT/Interpreter loop and the Host OS via the Interrupt Vector Table (IVT).
The Execution Flow:
 * The Request: The bytecode executes SYSCALL SYS_NET_READ. It passes a Stream
Handle (e.g., Handle 45) in R1.
 * The Host Intercept: The Host OS checks the socket. If no data is available,
it cannot return a string.
 * The Yield Signal: The Host IVT routine returns a special reserved trap
signal to the VM: STATE_YIELD_IO. It also sets a VM control register with the
pending Handle (45).
 * The VM Suspend: The execution loop immediately halts. It flushes the
physical CPU registers (R0-R7) into the current Shadow Stack frame, saves the
IP, and returns control to the Host Scheduler.
 * The Wait Table: The Host moves this CTX from the Run Queue to the Wait
Table, mapping it to Handle 45.
3. The Host Event Loop & Resume Protocol
Because the VM yields instantly, the Host OS thread is never blocked.
On HAUKI-X86 Bare Metal: The Host enters an epoll or hardware interrupt wait
loop.
On Chrome/V8: The Host simply yields back to the browser's native JavaScript
Event Loop.
The Wake-Up Sequence:
 * A TCP packet arrives for Handle 45.
 * The Host OS allocates a new String Handle in the Global Handle Ledger
containing the packet payload.
 * The Host looks up Handle 45 in the Wait Table and retrieves the sleeping
CTX.
 * The Host injects the new String Handle directly into the CTX's Accumulator
Register (R0).
 * The Host moves the CTX back to the Run Queue.
The next time the Scheduler ticks that CTX, the VM restores the Shadow Stack
and resumes at the exact instruction after the SYSCALL. The LPC code
seamlessly receives the string in R0 as if the read operation took 1
nanosecond.
4. The Preemptive Gas Scheduler (Anti-Starvation)
To ensure a single LPC object cannot monopolize the CPU (e.g., executing a
massive pathfinding loop while 500 other objects wait for network I/O), we
integrate the Gas limit directly into the Scheduler.
 * Every CTX is popped from the Run Queue with a fixed gas_limit (e.g., 10,000
instructions).
 * The VM executes blocks of bytecode, decrementing the gas.
 * If gas hits 0, the VM traps with STATE_YIELD_GAS.
 * The Host flushes the registers to the Shadow Stack, pushes the CTX to the
back of the Run Queue, and immediately starts executing the next object in the
queue.
This creates a perfectly fair, deterministic, cooperative multi-tasking
environment that runs completely in userspace on bare metal, and avoids
RangeError: Maximum call stack size exceeded or "Page Unresponsive" warnings
in browser environments.