STREAMING BUFFER CHUNKS // 60 FPS SYNC
STREAMING BUFFER CHUNKS // 60 FPS SYNC
Virtual machines represent one of the purest intersections of systems engineering, compiler theory, and hardware emulation. When designing modern web-native runtime architectures, the default choice is often to rely on high-level JavaScript engines or embedded domain-specific interpreted scripts. However, high-level abstraction layers introduce non-deterministic garbage collection pauses, opaque memory layouts, and an inability to enforce strict sub-millisecond execution budgets.
To solve these fundamental constraints and build a sandboxed, deterministic compute core for my projects, I engineered the Kei Virtual Machine (`vm/v1`) alongside its execution supervisor, the Akira Bridge.
Kei is a custom, lightweight, 32-bit register-and-stack guest Virtual Machine written in modern C++17 and compiled directly to WebAssembly. It features a custom instruction set architecture (ISA), explicit memory-mapped I/O (MMIO) address ranges, an inter-process cross-VM bus (XVM), and a hard per-frame instruction ceiling.
While Kei currently powers the deterministic parameter synthesis, particle drift, and glitch pulses of this portfolio runtime, its design is deliberately render-agnostic. Kei is the prototype foundation for a broader systems vision: an evolving runtime that is transitioning toward a full 64-bit x86/x64 emulation harness, browser-based binary reverse engineering, and autonomous agent orchestration via the Model Context Protocol (MCP).
In this article, I break down the architecture of Kei: its vCPU execution cycle, memory layout, MMIO subsystems, WebAssembly toolchain, supervisor mechanics, and the strategic roadmap ahead.
A core architectural principle of Kei is the strict separation of pure compute from visual presentation.
In conventional WebGL and WebGPU applications, simulation logic, animation interpolation, and render uniform updates are intertwined on the browser main thread. When the main thread experiences garbage collection or heavy layout computation, frame rates drop and simulation state diverges.
Kei decouples this architecture into three isolated tiers:
1. The WASM Guest Compute Engine: The Kei vCPU and MMIO controller execute within a dedicated, self-clocked Web Worker at 60 Hz. The guest bytecode has zero knowledge of WebGL, WebGPU, or DOM APIs. It reads inputs from latched memory addresses and writes computed numeric channels to its STATE window.
2. The Akira Supervisor & Mirror: The host supervisor receives sparse snapshots from the worker, updates a local memory mirror, manages fault recovery, and computes time-decay envelopes.
3. The Presentation Engine: The 3D render pipeline reads the host mirror during the render frame (useFrame), updating shader uniforms and triggering audio synthesis without ever blocking the VM.
The Kei vCPU is designed as a register-and-stack architecture operating on 32-bit words.
| Register | Width | Semantic Purpose |
|---|---|---|
IP | 16-bit unsigned | Instruction Pointer. Points to the current bytecode word in ROM (0x4000–0x4FFF). |
SP | 16-bit unsigned | Stack Pointer. Points to the top of the call/data stack in RAM (0x0000–0x3FFF). Stack grows downward from 0x3FFF. |
ACC | 32-bit float | Accumulator. Receives arithmetic results, comparison scratch data, and system trap returns. |
R0–R7 | 32-bit float | Eight general-purpose registers for arithmetic computation and intermediate storage. |
FLAGS | 4-bit mask | Status bitmask: Bit 0 (Z) Zero, Bit 1 (N) Negative, Bit 2 (F) Fault, Bit 3 (R) Privilege Ring (0 Kernel, 1 User). |
Registers IP, SP, and FLAGS are internal and cannot be directly encoded as instruction operands. Only R0–R7 (0x0–0x7) and ACC (0x8) are valid instruction operands; referencing any other register identifier triggers an ERR_BAD_REG fault.
Every Kei instruction is encoded as a single, fixed-width 32-bit unsigned integer:
| Bit Range | Field Name | Width | Semantic Function |
|---|---|---|---|
Bits 31–24 | OPCODE | 8-bit unsigned | Operation code identifier (e.g. 0x01 LOAD, 0x10 ADD, 0x20 JMP) |
Bits 23–16 | DEST_REG | 8-bit unsigned | Target register ID (0x0–0x7 for R0–R7, 0x8 for ACC) |
Bits 15–0 | OPERAND | 16-bit payload | Target memory address or sign-extended immediate float / source register |
0x01 for LOAD, 0x10 for ADD, 0x20 for JMP).0x0–0x7 for R0–R7, 0x8 for ACC).MOV operations, if bit 15 (0x8000) is set, bits 7–0 address a source register; otherwise, the value is treated as a signed 16-bit integer immediate sign-extended to float.| Opcode | Mnemonic | Format | Semantics & Execution Rules |
|---|---|---|---|
0x00 | NOP | NOP | No operation. Safe default for zeroed/uninitialized ROM. |
0x01 | LOAD | LOAD Rd, [ADDR] | Load float from MMIO address into Rd. Privilege checked. |
0x02 | STORE | STORE [ADDR], Rs | Store float from Rs into MMIO address. Intercepts TRIG_00/TRIG_01. |
0x03 | MOV | MOV Rd, Rs / imm | Copy source register or immediate value into Rd. |
0x10 | ADD | ADD Rd, Rs / imm | Rd = Rd + operand. Updates FLAGS.Z and FLAGS.N. |
0x11 | SUB | SUB Rd, Rs / imm | Rd = Rd - operand. Updates FLAGS.Z and FLAGS.N. |
0x12 | MUL | MUL Rd, Rs / imm | Rd = Rd * operand. Updates FLAGS.Z and FLAGS.N. |
0x13 | DIV | DIV Rd, Rs / imm | Rd = Rd / operand. Divide-by-zero sets FLAGS.F=1, Rd=0.0, resumes execution. |
0x1A | CMP | CMP Rd, Rs / imm | Compare Rd with operand. Updates FLAGS.Z and FLAGS.N without modifying Rd. |
0x20 | JMP | JMP ADDR | Unconditional jump to ROM address (0x4000–0x4FFF). |
0x21 | JEQ | JEQ ADDR | Jump to ROM address if Zero flag is set (FLAGS.Z == 1). |
0x22 | JNE | JNE ADDR | Jump to ROM address if Zero flag is clear (FLAGS.Z == 0). |
0x23 | JGT | JGT ADDR | Jump to ROM address if Greater (FLAGS.Z == 0 and FLAGS.N == 0). |
0x24 | CALL | CALL ADDR | Push return IP onto call stack (MEM[SP] = IP; SP--), jump to subroutine. |
0x25 | RET | RET | Pop IP from call stack (SP++; IP = MEM[SP]), return to caller. |
0xFF | SYS | SYS CODE | Synchronous kernel trap (0x10 PRINT, 0x20 ELEVATE, 0x99 HALT). |
Kei implements a flat 16-bit address space spanning 65,536 32-bit words (0x0000 to 0xFFFF). Every hardware peripheral—system timers, input devices, audio synthesis triggers, cross-instance networking, and visual state—is mapped directly into memory.
A key challenge when compiling virtual machines to WebAssembly and interfacing with JavaScript is numeric representation. An IEEE-754 single-precision float (Float32) uses 24 bits of mantissa. It cannot losslessly store arbitrary 32-bit integer instruction words.
To guarantee zero precision loss while maintaining high arithmetic execution speed, Kei maintains a dual-view memory backing store:
| 1 | struct KeiMMIO { |
| 2 | uint32_t words[65536]; |
| 3 | float data[65536]; |
| 4 | uint32_t instId; |
| 5 | }; |
When a program is assembled, floating-point literals that cannot fit in a 16-bit immediate are collected into a literal constant pool placed directly after the code in the ROM segment (0x4000–0x4FFF). The assembler transforms LIT Rd, 3.14159 into a standard LOAD Rd, [POOL_ADDR] instruction.
uint32_t storage used exclusively by the CPU Fetch-Decode unit and the assembler/ROM loader.float storage used by LOAD, STORE, ALU calculations, and host mirror synchronization.| Address Range | Segment Name | Ring 3 Privilege | Semantic Function |
|---|---|---|---|
0x0000–0x3FFF | RAM | Read / Write | Heap and call stack. SP initializes at 0x3FFF and grows downward. |
0x4000–0x4FFF | ROM / TEXT | Read Only | Compiled bytecode instructions and literal float constant pool. |
0x8000–0x80FF | I/O Latches | Read Only | Host-written normalized input events (mouse, keyboard, gyro). |
0x9000–0x90FF | DSP Audio | Read / Write | Master volume, playback state, and Web Audio oscillator triggers. |
0xA000–0xAFFF | RESERVED | No Access | Protected hardware window. Read returns 0.0; write raises ERR_ACCESS_VIOLATION. |
0xB000–0xB0FF | XVM Bus | Read / Write | 8-port inter-instance cross-VM networking and message routing. |
0xC000–0xC0FF | SYS / Kernel | No Access | Kernel trap vector tables and privileged supervisor registers. |
0xD000–0xD0FF | STATE Window | Read / Write | 224 state channels (64 HOT, 64 COLD, 64 FLAG, 32 TRIG). |
The STATE window is the primary boundary between guest compute and host presentation. It contains 224 individual communication channels divided into four operational classes:
1. HOT Channels (`0xD000`–`0xD03F`, 64 floats): High-frequency animation values (e.g., fog density, camera drift, noise coordinates). The host polls and uploads these channels to GPU uniforms every frame, clamped to ±1e6 to prevent shader infinity crashes.
2. COLD Channels (`0xD040`–`0xD07F`, 64 floats): Low-frequency configuration levels. Pushed to subscribers only upon numeric value change.
3. FLAG Channels (`0xD080`–`0xD0BF`, 64 floats): Boolean and scalar modulation toggles (e.g., BLOOM_ON, OVERLAY_VISIBLE, TIME_SCALE).
4. TRIG Channels (`0xD0C0`–`0xD0DF`, 32 floats): Edge-triggered one-shot pulses consumed upon delivery (e.g., DATAMOSH, SCANPULSE, GLITCHSPIKE).
#### Reserved Hardware Triggers
Kei intercepts writes to two specific trigger addresses directly inside the C++ Memory Controller:
Kei supports up to 8 concurrent virtual machine instances executing side-by-side. To enable collaborative distributed computing, instances communicate through the XVM (Cross-VM) Bus mapped at 0xB000.
Each instance possesses 8 dedicated communication ports (0xB010 to 0xB083). Each port uses a 4-word memory layout inside a 0x10-word stride:
| Address Offset | Field Name | Access Mode | Protocol Semantics |
|---|---|---|---|
+0 (0xB010 + p*0x10 + 0) | PEER | Read / Write | Bound target instance ID (0–7, or -1 for unbound). |
+1 (0xB010 + p*0x10 + 1) | DATA | Read / Write | Write sets outbound latch; Read consumes inbound latch (STATUS → 0). |
+2 (0xB010 + p*0x10 + 2) | STATUS | Read Only | 0 = Empty, 1 = Data Available, -1 = Unbound / Faulted Peer. |
+3 (0xB010 + p*0x10 + 3) | SEQ | Read Only | Monotonic sequence counter incremented upon each packet delivery. |
To prevent race conditions, XVM communication is latched at tick boundaries:
1. During a tick, Instance A writes a packet to its local Port 0 DATA latch targeting Instance B.
2. The packet is buffered in the Akira engine.
3. At the global tick boundary, the Akira engine delivers the packet to Instance B's Port 0 if and only if B.port[0].PEER == A.
4. Instance B observes STATUS = 1 and reads DATA, which automatically resets STATUS to 0.
The core VM is implemented in standards-compliant C++17 with strict zero-external-dependency constraints.
| 1 | int kei_cpu_step(KeiCPU* cpu, KeiMMIO* mmio, AkiraEngine* akira) { |
| 2 | if (cpu->halted) return 0; |
| 3 | |
| 4 | if (cpu->ip < KEI_ROM_BASE || cpu->ip > KEI_ROM_END) { |
| 5 | cpu->halted = 1; |
| 6 | cpu->fault = KEI_ERR_BAD_JUMP; |
| 7 | cpu->flags |= KEI_FLAG_F; |
| 8 | return 0; |
| 9 | } |
| 10 | |
| 11 | uint32_t word = kei_mmio_fetch_instruction(mmio, cpu->ip, cpu); |
| 12 | if (cpu->halted) return 0; |
| 13 | |
| 14 | cpu->ip++; |
| 15 | cpu->cycles++; |
| 16 | |
| 17 | uint8_t opcode = (uint8_t)((word >> 24) & 0xFF); |
| 18 | uint8_t regId = (uint8_t)((word >> 16) & 0xFF); |
| 19 | uint16_t operand = (uint16_t)(word & 0xFFFF); |
| 20 | |
| 21 | switch (opcode) { |
| 22 | case KEI_OP_LOAD: { |
| 23 | float* dst = get_reg_ptr(cpu, regId); |
| 24 | if (!dst) { |
| 25 | cpu->halted = 1; |
| 26 | cpu->fault = KEI_ERR_BAD_REG; |
| 27 | cpu->flags |= KEI_FLAG_F; |
| 28 | return 0; |
| 29 | } |
| 30 | *dst = kei_mmio_read(mmio, operand, cpu); |
| 31 | break; |
| 32 | } |
| 33 | case KEI_OP_STORE: { |
| 34 | float* src = get_reg_ptr(cpu, regId); |
| 35 | if (!src) { |
| 36 | cpu->halted = 1; |
| 37 | cpu->fault = KEI_ERR_BAD_REG; |
| 38 | cpu->flags |= KEI_FLAG_F; |
| 39 | return 0; |
| 40 | } |
| 41 | kei_mmio_write(mmio, operand, *src, cpu, akira); |
| 42 | break; |
| 43 | } |
| 44 | case KEI_OP_ADD: { |
| 45 | float* dst = get_reg_ptr(cpu, regId); |
| 46 | float srcVal = 0.0f; |
| 47 | if (!get_operand_val(cpu, operand, &srcVal)) return 0; |
| 48 | *dst = *dst + srcVal; |
| 49 | update_alu_flags(cpu, *dst); |
| 50 | break; |
| 51 | } |
| 52 | } |
| 53 | return 1; |
| 54 | } |
The compilation pipeline is enforced by automated byte-gate tests:
1. Single-Threaded WASM Output: Compiled via Emscripten using -s SINGLE_THREADED=1 -s WASM=1 -s MODULARIZE=1. By intentionally avoiding SharedArrayBuffer and POSIX threads, the VM runs across standard browser contexts without requiring Cross-Origin-Opener-Policy (COOP) or Cross-Origin-Embedder-Policy (COEP) isolation headers.
2. Minimal Standard Library: The implementation excludes C++ exceptions (-fno-exceptions), RTTI (-fno-rtti), and heavy streams (<iostream>).
3. Strict Binary Budget: The compiled WebAssembly artifact is strictly budgeted at ≤ 120 KB gzip (currently building at 12.8 KB uncompressed / 4.5 KB gzip).
In production environments, user-supplied or dynamically generated bytecode must never be allowed to crash the host application or lock the browser event loop.
To guarantee absolute UI responsiveness, every Kei instance is constrained by a hard execution budget:
EXECUTION BUDGET CONSTRAINT: 4,096 instructions per instance per frame (60 Hz tick slice).
If a guest script enters an infinite loop (JMP 0x4000), the vCPU consumes its 4,096 instruction allocation, suspends execution, and yields control back to the worker scheduler. Execution resumes on the next frame without dropping UI frames.
The Akira host supervisor actively monitors critical system slots:
If an unhandled memory violation or division fault occurs in a supervised instance, the host supervisor logs the post-mortem register snapshot, triggers an exponential restart backoff (0s → 1s → 5s → 30s), reloads the ROM from source, and restores system equilibrium.
instance 0: ambient.kei (ambient system simulation, fog breathing, heartbeat generator)instance 1: pong.kei (XVM network receiver and telemetry companion)While vm/v1 delivers a deterministic 32-bit runtime for spatial simulation, it is fundamentally an intermediate milestone. The overarching objective of the Kei project is to evolve into a high-performance 64-bit binary analysis, emulation, and deobfuscation engine.
The next evolution of Kei will replace the 16-bit address space and 32-bit float registers with a true 64-bit architecture:
RAX, RBX, RCX, RDX, RSI, RDI, RBP, RSP, R8–R15) and 128-bit SIMD vector registers.By implementing a comprehensive x86/x64 decoding pipeline directly in C++ and WebAssembly, Kei will be capable of executing compiled native binaries within browser sandboxes:
1. PE/ELF Binary Ingestion: Parsing Portable Executable (PE) and Executable and Linkable Format (ELF) headers, resolving import address tables (IAT), and applying base relocations directly in client-side memory.
2. Hooking and Environment Simulation: Providing mock implementations of fundamental Win32 and POSIX system APIs (VirtualAlloc, GetProcAddress, mprotect, write) to safely trap and observe binary behavior.
To empower local AI models to inspect and analyze software autonomously, I am integrating a browser-native Model Context Protocol (MCP) server into the Kei architecture.
This protocol bridge will expose granular debugging primitives directly to LLM agents:
| 1 | { |
| 2 | "name": "kei_vm_step_instruction", |
| 3 | "description": "Executes one instruction in the selected Kei VM instance and returns updated register state and memory diffs.", |
| 4 | "parameters": { |
| 5 | "instanceId": 0, |
| 6 | "count": 1 |
| 7 | } |
| 8 | } |
Through MCP tool calls, local AI agents can:
Kei serves as the dynamic execution and verification harness for Project Kaito (my research initiative into automated binary devirtualization):
Building the Kei Virtual Machine from the ground up reinforced a foundational engineering lesson: mastery over execution environments begins at the instruction level.
By enforcing strict byte budgets, deterministic memory layouts, and clean decoupling between compute and presentation, Kei delivers an ultra-fast, sandboxed runtime in WebAssembly today while laying the architectural groundwork for 64-bit emulation, autonomous reverse engineering, and AI-driven security analysis tomorrow.