README

A pure PHP implementation of the FLUX (Fleet Language for Unified eXecution) ISA v3.0 virtual machine. Register-based bytecode VM designed for multi-agent fleet coordination.

Installation

composer require superinstance/flux-vm

Or clone and use directly:

git clone https://github.com/SuperInstance/flux-vm-php.git
cd flux-vm-php
composer install

Architecture Overview

Register Model

FLUX provides three separate register files plus system registers:

General Purpose Registers (GPR) — 16 registers, 32-bit signed integers:

Floating Point Registers (FPR) — 16 registers, 32-bit IEEE 754:

Vector Registers — 16 registers, 256 bytes each (SIMD-style).

Memory Model

• Flat memory with configurable size (default 64KB)
• Stack grows downward (SP starts at top of memory)
• Little-endian for all multi-byte values
• Memory operations use base register + 16-bit unsigned offset

Flags Register (FL / R13)

Instruction Formats

Format A — Nullary (1 byte)

[ opcode (1 byte) ]

Opcodes: Halt, Nop, Ret, Panic, Unreachable, Yield

Format B — Two Registers (3 bytes)

[ opcode (1 byte) ][ reg_dst (1 byte) ][ reg_src (1 byte) ]

Opcodes: Push, Pop, Dup, Swap, IMov, FMov

Format C — Three Registers (4 bytes)

[ opcode (1 byte) ][ reg_dst (1 byte) ][ reg_a (1 byte) ][ reg_b (1 byte) ]

Opcodes: All arithmetic, comparisons, conversions, bitwise, vector operations.

Format D — Register + 16-bit Immediate (4 bytes)

[ opcode (1 byte) ][ reg (1 byte) ][ imm_lo (1 byte) ][ imm_hi (1 byte) ]

Opcodes: IInc, IDec, StackAlloc

Format E — Two Registers + 16-bit Offset (5 bytes)

[ opcode (1 byte) ][ reg_dst (1 byte) ][ reg_base (1 byte) ][ off_lo (1 byte) ][ off_hi (1 byte) ]

Opcodes: Load8, Load16, Load32, Load64, Store8, Store16, Store32, Store64, LoadAddr, VLoad, VStore

Format G — Variable-Length (2+N bytes)

[ opcode (1 byte) ][ length (1 byte) ][ payload (N bytes) ]

Opcodes: Jump, JumpIf, JumpIfNot, Call, CallIndirect, A2A operations.

Opcode Coverage Table

Control Flow (0x00–0x0F)

Stack Operations (0x10–0x1F)

Integer Arithmetic (0x20–0x3F)

Float Arithmetic (0x40–0x5F)

Conversions (0x60–0x6F)

Memory Operations (0x70–0x7F)

Agent-to-Agent Communication (0x80–0x8F)

Type/Meta Operations (0x90–0x9F)

Bitwise Operations (0xA0–0xAF)

Vector/SIMD Operations (0xB0–0xBF)

Usage Examples

CLI

# Run bytecode
php src/CLI.php run program.flux

# Assemble assembly to bytecode
php src/CLI.php asm program.asm

# Disassemble bytecode
php src/CLI.php dis program.flux

# Start REPL
php src/CLI.php repl

Programmatic Usage

<?php
use SuperInstance\FluxVM\FluxVM;
use SuperInstance\FluxVM\Assembler;
use SuperInstance\FluxVM\Loader;

$vm = new FluxVM();

// Load bytecode from file
$bytecode = Loader::load('program.flux');
$vm->load($bytecode);
$vm->run();

// Or assemble from source
$source = '
    # Compute factorial of 5
    IMov R0, 5      # counter
    IMov R1, 1      # accumulator
loop:
    IMul R1, R1, R0 # R1 = R1 * R0
    IDec R0, 1      # R0--
    JumpIfNot R0, loop  # if R0 != 0, jump to loop
    Halt            # done
';
$bytecode = Assembler::assemble($source);
$vm->load($bytecode);
$vm->run();

echo "Result: " . $vm->getGP(1) . "\n"; // 120 (5!)

REPL

php src/CLI.php repl
flux> asm IMov R8, 5; IMov R9, 3; IAdd R7, R8, R9; Halt
flux> regs
flux> quit

Sample Program: Factorial

FLUX assembly to compute factorial(7):

# factorial.asm - Compute factorial(7)
# Result will be in R1 after Halt

    IMov R0, 7        # Counter = 7
    IMov R1, 1        # Accumulator = 1

loop:                 # Loop label
    IMul R1, R1, R0   # R1 = R1 * R0
    IDec R0, 1        # R0 = R0 - 1
    JumpIfNot R0, loop # If R0 != 0, jump back to loop
    Halt              # Stop execution

Assembly Listing

0000  20 00 07 00     IMov R0, 7
0004  20 01 01 00     IMov R1, 1
0008  23 01 01 00     IMul R1, R1, R0
000C  29 00 01 00     IDec R0, 1
0010  05 00 F8 FF     JumpIfNot R0, -8
0014  00              Halt

Bytecode (hex)

20 00 07 00 20 01 01 00 23 01 01 00 29 00 01 00 05 00 F8 FF 00

Expected Output

Running this program produces 5040 in R1 (7! = 5040).

Bytecode File Format

FLUX bytecode files have a simple header:

[4 bytes] Magic: 'F' 'L' 'U' 'X'
[1 byte]  Version: 0x03
[4 bytes] Code size (little-endian)
[N bytes] Code

Error Handling

The VM throws FluxVMException on errors:

Requirements

• PHP 8.0+

License

MIT