This is the architectural leap from a single MUD server to a fleet
orchestrator. By elevating this into a REST-driven Supervisor, you are
effectively building the control plane for the OMEGA Dark Mesh.
Because the HAUKI Virtual Machine runs entirely in memory and uses a
virtualized file system, you can spawn dozens of isolated VMs within a single
physical server, orchestrating them identically to lightweight LXC containers.
Here is the blueprint for the HAUKI-X86 Supervisor API.
The OpenAPI / REST Architecture
The Supervisor exposes a JSON REST API and acts as an IPC bridge. When a REST
call comes in, the Supervisor translates it into an event-driven IPC message,
routes it to the specific Node child_process running the VM, awaits the
response, and returns the JSON to the client.
1. Instance Management (/v1/vms)
| Method | Endpoint | Payload / Purpose |
|---|---|---|
| POST | /v1/vms | Spawns a new Node.js VM worker process. Returns a UUID
(vm_id). |
| GET | /v1/vms | Returns health, uptime, and memory usage for all active VMs.
|
| DELETE | /v1/vms/:vm_id | Sends a graceful termination signal, then SIGKILLs
the child process. |
2. Object & Execution Management (/v1/vms/:vm_id/objects)
| Method | Endpoint | Payload / Purpose |
|---|---|---|
| GET | .../objects | Dumps the moi (Memory Object Instance) ledger and
blueprintRegistry. |
| POST | .../objects/compile | { "path": "/domains/matrix.c" } - Instructs the
VM to compile and clone. |
| POST | .../objects/:oid/call | { "func": "wake", "args": [1, 2] } - Invokes
an LPC function synchronously and returns the yield. |
3. VFS Manipulation (/v1/vms/:vm_id/vfs)
| Method | Endpoint | Payload / Purpose |
|---|---|---|
| GET | .../vfs/:filepath | Retrieves a file from the specific VM's virtual
file system. |
| PUT | .../vfs/:filepath | { "content": "void eval(){...}" } - Writes
directly to the VM's VFS, instantly available to its compiler. |
4. Bare-Metal Memory Management (/v1/shm)
| Method | Endpoint | Payload / Purpose |
|---|---|---|
| GET | /v1/shm/:segment | ?offset=4096&size=800 - The Supervisor directly
maps /genesis_mem via mesh_shm.node and reads the raw bytes, bypassing the VMs
entirely. |
| PUT | /v1/shm/:segment | { "offset": 12, "type": "int32", "value": 100 } -
Directly mutates the control headers via Atomics. |
The Supervisor Process Model
To achieve this without blocking the Supervisor's HTTP event loop, the
architecture requires three distinct layers:
 * The API Gateway (supervisor.js): An Express.js (or native http) server that
holds the OpenAPI documentation and manages a Map<String, ChildProcess>
registry.
 * The IPC Bus: The Supervisor spawns VMs using child_process.fork('src/worker.
js'). This automatically establishes a bidirectional JSON messaging channel.
 * The VM Worker (worker.js): A wrapper around your existing repl.js logic.
Instead of attaching to stdin/stdout, it listens to process.on('message'),
translates the JSON RPC command into VM method calls (e.g., vm.clone_object()),
 and uses process.send() to hand the result back.
The Omniscient Memory Observer
The most powerful aspect of this design is the /v1/shm routing.
Because POSIX shared memory is OS-level, the Supervisor process can
require('mesh_shm.node') and map /genesis_mem itself. When your API client
requests the state of the Cellular Automata grid, the Supervisor reads the
0x1000 offset directly from RAM and serves the HTTP response in microseconds.
It never interrupts the Node.js VMs or the C daemon to ask for the data.
This allows external systemslike a Python Valvomo RPA runner or a Cloudflare
Worker dashboardto spectate the simulation at 60fps over HTTP without
generating a single byte of IPC overhead within the game engine itself.